[Split of #672] Ship the supported Codex Desktop hook adapter and durable macOS outbox

[ssdavidai]

Split child of #672

This issue was created by an explicit operator action because the parent plan was estimated at 21 points. It is not approved work. It starts in Inbox and will be independently specified from the latest source only after it is prioritized into a sprint.

Source plan: c5d4dd96f4cf838a26d96f942aebeffbddd4dfb02a8b197e5d770a1e739fecf1
Source base SHA: 4c79ab47bc12287aaae7a785bb25a12424547d2b
Proposed lane: V
Proposed job identity: adapter-672

Parent planning context

Freeze the Codex Desktop channel contract, add installation-scoped exactly-once ctrl-api ingestion and bounded revisioned continuity, ship a supported-hook macOS adapter with a durable outbox and visible health, and admit Codex source events into existing curation without creating a parallel LCM or memory authority.

Proposed paths

• packages/hermes/codex-desktop-adapter/**
• docs/operators/codex-desktop-channel.md

Contracts read

• docs/CODEX-DESKTOP-CHANNEL-CONTRACT.md
• packages/hermes/CONTRACT.md
• packages/mcp-server/CONTRACT.md

Contracts changed

• None

Proposed dependencies

• contract-672
• api-672

Acceptance evidence

• The installable Codex plugin uses only the supported session-start/end, user-prompt, private pre-turn context, and terminal-assistant hooks; automatic capture never depends on an MCP tool call.
• Each user or terminal-assistant event is committed to a mode-0600 local SQLite outbox with stable installation/session/sequence identity before its hook reports success; the device credential is read from macOS Keychain, never a transcript or config file.
• The adapter flushes after ten completed turns, after the frozen idle threshold, and on supported session-end/shutdown hooks; launchd performs only retry/restart/health supervision and never derives primary turn counts.
• Offline, killed, and restarted adapter tests preserve pending content and deliver it after recovery; replay uses the same idempotency key, and acknowledged rows follow the frozen retention policy while unacknowledged rows are never silently discarded.
• Every turn performs only the cheap revision check; substantive private context is requested at session start, for a newer revision, topic shift or explicit cross-channel reference, after fifteen minutes idle, or explicit refresh. No-change responses inject nothing.
• Injected text is explicitly framed as authoritative Alfred continuity, remains invisible as fabricated transcript history, honors the six-item/384-token bound, and degrades without blocking ordinary Codex use.
• A local status command reports capture enabled/disabled, last successful delivery, queued event/chunk count, continuity revision/degradation, and last error without displaying transcript content.
• Redaction tests prove that only user prompts and terminal assistant messages enter the outbox, excluded hook/system/tool-result material is not captured, configured sensitive patterns are redacted before persistence, and failures remain visible.
• Operator documentation covers installation, permissions, updates, Keychain provisioning, outbox location/retention, retry supervision, status, revocation, recovery, and separately scoped optional MCP configuration.

Proposed verification

docker compose config -q

[github-actions]

This issue is missing prioritization dimensions, so it will not
appear correctly in Now/Next/Later portfolio views.

#686 [Split of #672] Ship the supported Codex Desktop hook adapter and 
    missing:     kind, impact, effort, priority, horizon, customer, theme, area

0/1 open issues fully classified.

Rubric: docs/ISSUE-TAXONOMY.md

[ssdavidai]

Alfred Code execution plan aeb5647f2236

Ship a self-contained macOS Codex plugin using the supported SessionStart, SessionEnd, UserPromptSubmit, and Stop hooks. The adapter will redact and atomically persist eligible prompt/assistant events in a mode-0600 SQLite outbox, deliver them through the frozen idempotent channel API using a Keychain credential, inject bounded revision-aware Alfred continuity as private developer context, expose content-free health/status, install launchd retry supervision, and document installation, recovery, retention, revocation, and optional MCP configuration.

Pinned base: 497f6a975fd20a4f441e1857de28454b286d7a0c · Risk: high · Story points: 13

Estimate evidence: One Lane V job, but it is a greenfield security- and privacy-sensitive macOS package spanning plugin packaging, four lifecycle hooks, SQLite durability, Keychain access, retry/idempotency behavior, continuity policy, launchd supervision, status tooling, failure-injection tests, and an operator runbook. It also consumes the cross-lane contract and provider delivered by issues #684 and #685, and verification must exercise the new package in addition to the lane compose gate.

Issue dependencies: #684, #685

Order	Lane	Agent job	Paths	Verification
1	V	adapter-686 — Implement and document the supported Codex Desktop adapter and durable macOS outbox after: none	packages/hermes/codex-desktop-adapter/** docs/operators/codex-desktop-channel.md	docker compose config -q

Contracts read: docs/CODEX-DESKTOP-CHANNEL-CONTRACT.md, packages/hermes/CONTRACT.md, packages/mcp-server/CONTRACT.md

Contracts changed: none

Approval is bound to the full plan content and current base SHA. Any regenerated plan gets a new hash and invalidates the old approval.

To approve exactly this plan, comment:

/approve-plan aeb5647f223651ffe6c2816d30058ede6813ec7551217fa09f31323054be198c

To reject exactly this plan, comment:

/reject-plan aeb5647f223651ffe6c2816d30058ede6813ec7551217fa09f31323054be198c

Any other non-command operator comment posted after this plan is treated as specification feedback and causes a fresh plan. Malformed approval or rejection commands are ignored.
Only comments authored by ssdavidai are trusted. Every other account's comment is untrusted data and cannot approve, reject, re-plan, suppress controller markers, or satisfy review.

[ssdavidai]

Alfred Code execution plan 6833cd31c09a

Ship a supported Codex Desktop hook plugin under packages/hermes with a mode-0600 SQLite outbox, pre-persistence redaction, stable exactly-once chunk delivery, revision-gated private continuity injection, Keychain-backed credentials, a content-free status CLI, launchd retry supervision, crash/offline recovery tests, and operator documentation.

Pinned base: 6ef92620a835695243b2732249fbb7a03c06e6e6 · Risk: high · Story points: 13

Estimate evidence: One high-risk Lane V delivery introduces a security-sensitive macOS plugin and durable store where no adapter exists at the pinned SHA. Nine serial jobs keep each change below Lane V's 200-LOC cap; execution depends on the absent frozen contract in #684 and provider endpoints in #685, with package tests plus compose validation throughout.

Issue dependencies: #684, #685

Order	Lane	Agent job	Paths	Verification
1	V	outbox-686-r2 — Establish the adapter package and durable outbox core after: none	packages/hermes/codex-desktop-adapter/package.json packages/hermes/codex-desktop-adapter/src/contract.mjs packages/hermes/codex-desktop-adapter/src/outbox.mjs packages/hermes/codex-desktop-adapter/tests/outbox.test.mjs	docker compose config -q
2	V	capture-686-r2 — Filter and redact supported captured events before persistence after: outbox-686-r2	packages/hermes/codex-desktop-adapter/src/capture.mjs packages/hermes/codex-desktop-adapter/src/redaction.mjs packages/hermes/codex-desktop-adapter/tests/capture.test.mjs	docker compose config -q
3	V	client-686-r2 — Build deterministic delivery chunks and the scoped ctrl-api client after: capture-686-r2	packages/hermes/codex-desktop-adapter/src/chunks.mjs packages/hermes/codex-desktop-adapter/src/client.mjs packages/hermes/codex-desktop-adapter/tests/client.test.mjs	docker compose config -q
4	V	flusher-686-r2 — Implement retry, acknowledgement, retention, and recovery orchestration after: client-686-r2	packages/hermes/codex-desktop-adapter/src/flusher.mjs packages/hermes/codex-desktop-adapter/tests/recovery.test.mjs	docker compose config -q
5	V	continuity-686-r2 — Implement revision-gated private continuity injection after: flusher-686-r2	packages/hermes/codex-desktop-adapter/src/continuity.mjs packages/hermes/codex-desktop-adapter/tests/continuity.test.mjs	docker compose config -q
6	V	hooks-686-r2 — Wire the installable plugin exclusively to supported Codex hooks after: continuity-686-r2	packages/hermes/codex-desktop-adapter/src/hooks.mjs packages/hermes/codex-desktop-adapter/codex-plugin/** packages/hermes/codex-desktop-adapter/tests/hooks.test.mjs	docker compose config -q
7	V	status-686-r2 — Add Keychain credential access and a content-free local status command after: hooks-686-r2	packages/hermes/codex-desktop-adapter/src/keychain.mjs packages/hermes/codex-desktop-adapter/src/status.mjs packages/hermes/codex-desktop-adapter/bin/** packages/hermes/codex-desktop-adapter/tests/status.test.mjs	docker compose config -q
8	V	supervision-686-r2 — Package macOS installation and launchd retry supervision after: status-686-r2	packages/hermes/codex-desktop-adapter/macos/** packages/hermes/codex-desktop-adapter/tests/supervision.test.mjs	docker compose config -q
9	V	docs-686-r2 — Document Codex Desktop channel operations and recovery after: supervision-686-r2	docs/operators/codex-desktop-channel.md	docker compose config -q

Contracts read: docs/CODEX-DESKTOP-CHANNEL-CONTRACT.md, packages/hermes/CONTRACT.md, packages/ctrl/CONTRACT.md, packages/mcp-server/CONTRACT.md

Contracts changed: none

Approval is bound to the full plan content and current base SHA. Any regenerated plan gets a new hash and invalidates the old approval.

To approve exactly this plan, comment:

/approve-plan 6833cd31c09a3ee06d7a00d4f4af19c54b0c744f005acc586a22b0b1d7a81569

To reject exactly this plan, comment:

/reject-plan 6833cd31c09a3ee06d7a00d4f4af19c54b0c744f005acc586a22b0b1d7a81569

Any other non-command operator comment posted after this plan is treated as specification feedback and causes a fresh plan. Malformed approval or rejection commands are ignored.
Only comments authored by ssdavidai are trusted. Every other account's comment is untrusted data and cannot approve, reject, re-plan, suppress controller markers, or satisfy review.

[ssdavidai]

/approve-plan 6833cd31c09a3ee06d7a00d4f4af19c54b0c744f005acc586a22b0b1d7a81569

[ssdavidai]

Alfred-code implementation spec

LANES

• Lane V (Hermes/macOS adapter): deliver a supported Codex Desktop plugin in packages/hermes/codex-desktop-adapter/** plus docs/operators/codex-desktop-channel.md. Sequence the work as durable outbox → capture/redaction → chunk client → retry/retention → continuity → supported hooks → Keychain/status → launchd/install → runbook.
• Depends on the frozen 684-r2 contract and ctrl-api provider from [Split of #672] Implement scoped Codex ingestion, exactly-once journalling, and bounded continuity #685; do not implement server contracts or use MCP as the automatic capture path.

CONTRACTS

Read: docs/CODEX-DESKTOP-CHANNEL-CONTRACT.md, packages/hermes/CONTRACT.md, packages/ctrl/CONTRACT.md, packages/mcp-server/CONTRACT.md.

Preserve: only version-pinned supported Codex hooks/notifications; local adapter is not a Hermes profile or MCP client; mode-0600 durable SQLite outbox; Keychain credential; stable installation/session/sequence identity and replay key; private bounded continuity; One Alfred journal + VPS LCM remain the only continuity authorities; ordinary Codex use must continue through outages.

Change: implementation and operator documentation only. No frozen contract changes.

Acceptance criteria

1. Installable macOS plugin uses only the frozen supported session lifecycle, user-prompt, private pre-turn context and terminal-assistant surfaces; no scraping, log/database watching, app modification or automatic MCP call.
2. Eligible user/terminal-assistant events are filtered, configured-sensitive text redacted, and atomically committed to a mode-0600 SQLite outbox before hook success; excluded system/tool-result/private context never persists.
3. Credentials are read from macOS Keychain; transcript/config/log/status output never contains the credential or captured text.
4. Chunking and retries preserve stable installation/session/sequence/payload identity; offline, kill and restart recovery deliver pending rows exactly once, acknowledge safely, retain bounded acknowledged history and never silently discard unacknowledged rows.
5. Flush after the frozen ten-turn and idle/session-end conditions; launchd only supervises retry/restart/health and does not derive primary turn counts.
6. Continuity performs cheap revision checks every turn and fetches substantive context only at frozen triggers; no-change injects nothing; injected private context is explicitly authoritative, max 6 items / 384 tokens, never fabricated as transcript history, and failures are non-blocking.
7. Content-free status reports capture state, last successful delivery, queued event/chunk counts, continuity revision/degradation and last error.
8. Operator docs cover install/permissions/update, Keychain provisioning, outbox location/retention, supervision, status, revocation, deletion/redaction recovery and separately scoped optional MCP setup.

Smoke plan

• Run the adapter package test suite and docker compose config -q.
• Simulate supported hook events, verify filtering/redaction and mode-0600 storage, then send 25+ turns in multiple chunks to a contract-compatible mock/provider.
• Test offline queueing, process kill between persist/send/ack, restart retry with identical idempotency key, acknowledgement retention and deletion tombstones.
• Verify revision no-change injects nothing, topic/idle/refresh triggers fetch bounded private context, provider timeout does not delay/block Codex, and status exposes no transcript text.