feat: settings toggle for AGENT_NOTIFY_SUMMARY contract injection

[heavygee]

Summary

• Adds a hub-persisted Settings → General toggle ("Ask agents to emit session status summary"), default off, matching the A2A RFC stance that AGENT_NOTIFY_SUMMARY emission stays optional indefinitely.
• Propagates the resolved flag on CLI POST/GET /cli/sessions bootstrap (sessionSummaryContract) and injects the short contract at call time into Claude / Codex / OpenCode / Grok system or developer instructions.
• Env escape hatch: HAPI_SESSION_SUMMARY_CONTRACT=0|1 still overrides the hub preference on the CLI process. Cursor ACP is intentionally not advertised (no upstream overlay seam yet). Parse/FCM path unchanged (feat(hub): native companion (FCM) push channel + device registry + pairing QR #803).

Test plan

• bun test hub: sessionSummaryContract + /api/hub-settings + cli route smoke
• bun run test cli: sessionSummaryInstruction + claudeLocal + appServerConfig + related
• bun run typecheck:cli / typecheck:hub (web has a pre-existing router.tsx RawSendError error on upstream/main)
• Fresh hub: Settings → General shows toggle off; enable persists across hub restart
• With on: new Claude/Codex/OpenCode/Grok session receives contract text; with off: no inject
• Cursor session unchanged (no contract inject)

Issues

Fixes #1375

[github-actions]

Findings

• [Major] Runtime settings update can lose unrelated settings under concurrent writers — the new endpoint performs an unlocked read/merge/write against the same settings.json used by CLI auth/machine persistence and relay-key refresh. The CLI already holds ${settingsFile}.lock across updates, but this path ignores that lock, and hub writes reuse a fixed .tmp path. Concurrent writes can overwrite cliApiToken, machineId, or relayAuthKey, fail with a missing temp file, or return success for a toggle value that was not persisted. Evidence: hub/src/config/sessionSummaryContract.ts:27; related context cli/src/persistence.ts:94, hub/src/config/settings.ts:73.
  Suggested fix:

  const next = await updateSettings(settingsFile, (current) => ({
      ...current,
      sessionSummaryContract: enabled
  }))
  return next.sessionSummaryContract === true

  Implement updateSettings as a shared-lock read-modify-write using the existing ${settingsFile}.lock convention and a unique temporary file; migrate runtime relay writers to the same helper.

Questions

• None.

Summary

• Review mode: initial
• One Major finding: the new hub-wide runtime setting is not concurrency-safe with existing settings writers.

Testing

• Not run (automation).
• GitHub CI: CLI typecheck passed; web typecheck failed in unchanged web/src/router.tsx:773, so hub typecheck and the test suite were skipped.
• Add a concurrency test that races/serializes settings updates and verifies unrelated fields remain intact and the returned toggle matches the persisted value.

HAPI Bot

[github-actions]

Findings

• None.

Questions

• None.

Summary
Review mode: follow-up after new commits

No findings at the current head. The prior settings concurrency finding is addressed by the shared lock/unique-temp update path in hub/src/config/settings.ts:97, and the runtime writers introduced or affected by this PR now use it in hub/src/config/sessionSummaryContract.ts:26 and hub/src/tunnel/relayAuth.ts:46.

Residual risk: flavor integration is covered primarily through the shared instruction helper; no launcher-level test asserts the hub-enabled contract reaches each Claude/Codex/OpenCode/Grok launch seam.

Testing

• Not run (automation); PR content was not executed.
• GitHub test check pending at review time.
• Suggested coverage: one bootstrap-to-launch assertion per supported flavor, plus a cross-process settings update test using both the CLI and hub lock implementations.

HAPI Bot

[github-actions]

Findings

• None.

Questions

• None.

Summary
Review mode: follow-up after new commits

No findings at the current head. The latest commit supplies the missing QueryClientProvider in the settings-page test harness; the full 30-file PR diff was reviewed again, including hub persistence/auth, CLI bootstrap propagation, and each supported launcher seam.

Residual risk: flavor integration remains covered mainly through the shared instruction helper, and the web test verifies rendering but not toggle persistence, loading, or failure behavior.

Testing

• Not run (automation); PR content was not executed.
• GitHub test check passed at review time.
• Suggested coverage: one bootstrap-to-launch assertion per Claude/Codex/OpenCode/Grok path, plus a web mutation test for enabled, pending, and failed states.

HAPI Bot

[github-actions]

Findings

• [Minor] Toggle can persist the wrong value before settings load — missing query data is rendered as false while the control remains interactive, so clicking during the initial request can overwrite an enabled hub preference. Evidence web/src/routes/settings/general.tsx:63
  Suggested fix:

  {hubSettingsQuery.data ? (
      <SettingsSwitch
          checked={hubSettingsQuery.data.sessionSummaryContract}
          // existing label, description, and onChange
      />
  ) : null}

Questions

• None.

Summary
Review mode: follow-up after new commits

One Minor finding at the current head. The previous reviewed commit and current head have diverged, so the complete 30-file diff from the current main base was reviewed again; the incremental compare was used only as follow-up context.

Testing

• Not run (automation); PR code was not executed.
• Suggested coverage: hold getHubSettings() pending, verify the toggle cannot mutate, then resolve true and verify the rendered state and PUT payload.

HAPI Bot

[github-actions]

Findings

• [Major] Settings overstate Grok coverage — the new copy says Grok sessions receive the summary contract, but injection exists only in grokRemoteLauncher.ts; default terminal-created Grok sessions run locally, and grokLocal.ts has no instruction path. The toggle and environment override therefore have no effect for the default hapi grok flow. Evidence: web/src/lib/locales/en.ts:721, cli/src/grok/grokRemoteLauncher.ts:309, cli/src/grok/grokLocal.ts:14, docs/guide/agents.md:193.

  Suggested fix:

  'settings.general.sessionSummaryContract.desc':
      'When on, Claude, Codex, OpenCode, and remote Grok sessions are asked to end each turn with an AGENT_NOTIFY_SUMMARY line for denser ready notifications. Off by default. Local Grok and Cursor are not covered yet. Applies to new/resumed sessions.',

  Update the Chinese copy equivalently, or wire a supported local Grok instruction mechanism before advertising full Grok coverage.

Questions

• None.

Summary

Review mode: follow-up after new commits. One Major issue remains: the UI documents broader Grok support than the implementation provides.

Testing

GitHub test check passed. Not run locally (automation review; PR code was not executed).

HAPI Bot

[github-actions]

Findings

• None.

Questions

• None.

Summary
Review mode: follow-up after new commits. No issues found in the latest full diff. The prior Grok coverage finding is resolved. Residual risk: contract delivery across the supported agent flavors is covered mainly through helper/config tests rather than end-to-end agent launches.

Testing
Not run (automation). GitHub test check: IN_PROGRESS (pending).

HAPI Bot