From 013bf691fdd437490478c3de1ca888aeb47551cf Mon Sep 17 00:00:00 2001 From: AkitaOnRails Date: Thu, 1 Oct 2026 02:47:14 -0300 Subject: [PATCH] docs: fix audited drift in frontend-api, windows, and Codex managed runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - frontend-api.md (#986): the list, search, and recent routes return bare JSON arrays, not `{ "workspaces": … }`-style wrappers (the route tests assert `as_array()`); a page read returns `body_markdown`, not `body`; a search hit carries workspace/project/kind and no `id`. - windows.md (#758): native `ai-memory upgrade` is done (#801/#802), not in-progress. - managed-workstreams.md + support matrix (#987): document the Codex shared daemon handing hooks a stale AI_MEMORY_RUN_ID and the `--no-daemon` workaround until the server-side fix lands. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01MDbhmszrjG9s5MrPrTuNtm --- docs/frontend-api.md | 108 +++++++++++++++++------------------- docs/managed-workstreams.md | 21 +++++++ docs/support-matrix.md | 2 +- docs/windows.md | 10 ++-- 4 files changed, 78 insertions(+), 63 deletions(-) diff --git a/docs/frontend-api.md b/docs/frontend-api.md index 8e97d27a..d803d403 100644 --- a/docs/frontend-api.md +++ b/docs/frontend-api.md @@ -98,19 +98,17 @@ All endpoints are `GET` unless noted. Paths under `/api/v1/`. GET /api/v1/workspaces ``` -**Response:** `{ "workspaces": [WorkspaceSummary, …] }` +**Response:** a bare JSON array, `[WorkspaceSummary, …]` ```json -{ - "workspaces": [ - { - "workspace_name": "default", - "project_count": 3, - "page_count": 412, - "last_updated": "2026-05-28T14:02:11.123Z" - } - ] -} +[ + { + "workspace_name": "default", + "project_count": 3, + "page_count": 412, + "last_updated": "2026-05-28T14:02:11.123Z" + } +] ``` `last_updated` is `null` for an empty workspace. @@ -122,19 +120,17 @@ GET /api/v1/projects # all projects across all workspaces GET /api/v1/projects?workspace=NAME # projects in one workspace ``` -**Response:** `{ "projects": [ProjectSummary, …] }` +**Response:** a bare JSON array, `[ProjectSummary, …]` ```json -{ - "projects": [ - { - "workspace_name": "default", - "project_name": "ai-memory", - "page_count": 138, - "last_updated": "2026-05-28T14:02:11.123Z" - } - ] -} +[ + { + "workspace_name": "default", + "project_name": "ai-memory", + "page_count": 138, + "last_updated": "2026-05-28T14:02:11.123Z" + } +] ``` ### 4.3 Pages (list) @@ -143,20 +139,18 @@ GET /api/v1/projects?workspace=NAME # projects in one workspace GET /api/v1/workspaces/{workspace}/projects/{project}/pages ``` -**Response:** `{ "pages": [PageSummary, …] }` +**Response:** a bare JSON array, `[PageSummary, …]` ```json -{ - "pages": [ - { - "path": "decisions/0007-db.md", - "title": "Standardised on Postgres", - "kind": "decision", - "tier": "semantic", - "updated_at": "2026-05-27T09:12:00.000Z" - } - ] -} +[ + { + "path": "decisions/0007-db.md", + "title": "Standardised on Postgres", + "kind": "decision", + "tier": "semantic", + "updated_at": "2026-05-27T09:12:00.000Z" + } +] ``` `404` if the workspace or project doesn't exist. @@ -185,7 +179,7 @@ links + back-links. "updated_at": "2026-05-28T11:04:33.123Z", "supersedes": null, "frontmatter": { "tags": ["adr"], "pinned": true }, - "body": "# Standardised on Postgres\n\n…", + "body_markdown": "# Standardised on Postgres\n\n…", "links": [ { "path": "concepts/db-rules.md", "title": "DB rules", "kind": "rule" } ], "backlinks": [ { "path": "sessions/2026-05-27.md", "title": "Session 2026-05-27", "kind": "session" } ] } @@ -218,20 +212,20 @@ Content-Type: application/json } ``` -**Response:** `{ "hits": [PageHit, …] }` +**Response:** a bare JSON array, `[SearchHit, …]` ```json -{ - "hits": [ - { - "id": "01928d27-…", - "path": "concepts/karpathy-wiki.md", - "title": "Karpathy LLM Wiki pattern", - "snippet": "Andrej Karpathy's LLM wiki design …", - "rank": -8.4 - } - ] -} +[ + { + "workspace": "default", + "project": "ai-memory", + "path": "concepts/karpathy-wiki.md", + "title": "Karpathy LLM Wiki pattern", + "kind": "concept", + "snippet": "Andrej Karpathy's LLM wiki design …", + "rank": -8.4 + } +] ``` Rules: @@ -261,19 +255,17 @@ Every reader surface uses the same `kind` contract. An explicit frontmatter `rule`, `slot`, `session`, `decision`, `gotcha`, `concept`, `procedure`, and `note`, respectively. Other paths fall back to `fact`. -**Response:** `{ "pages": [BriefingPage, …] }` +**Response:** a bare JSON array, `[BriefingPage, …]` ```json -{ - "pages": [ - { - "path": "sessions/2026-05-28.md", - "title": "Session 2026-05-28", - "kind": "session", - "updated_at": "2026-05-28T14:02:11.123Z" - } - ] -} +[ + { + "path": "sessions/2026-05-28.md", + "title": "Session 2026-05-28", + "kind": "session", + "updated_at": "2026-05-28T14:02:11.123Z" + } +] ``` ### 4.7 Briefing (structured snapshot) diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md index 5307f171..b1115cd0 100644 --- a/docs/managed-workstreams.md +++ b/docs/managed-workstreams.md @@ -500,6 +500,27 @@ protocol](managed-harness-contributions.md), including read-only extraction, pre-turn context delivery, migration invariants, deterministic tests, and an opt-in real-harness acceptance pass. +### Known issue: Codex's shared daemon and stale run ids (#987) + +Recent Codex releases run sessions through a shared background app-server +daemon (`codex agents` lists it). The daemon keeps the environment it started +with, and the lifecycle hooks it launches inherit that environment — including +the `AI_MEMORY_RUN_ID` of whichever managed run auto-started it. A later +`ai-memory run codex` then reports that finished run, gets no continuity +context, and the server logs `managed SessionStart has no active run`. + +Until the server-side fix lands, launch managed Codex sessions without the +daemon. Native arguments after the harness are forwarded to Codex: + +```bash +ai-memory run codex --no-daemon +``` + +`--no-daemon` makes that one session run without the shared background server +even if one is already running; it is available on Codex's interactive and +`resume` commands (checked on Codex 0.156). Sessions started without it keep +the daemon behavior described above. + ## Installation and recovery Managed runs need current ai-memory lifecycle hooks so SessionStart can receive diff --git a/docs/support-matrix.md b/docs/support-matrix.md index 5ad8e5a0..5d63037a 100644 --- a/docs/support-matrix.md +++ b/docs/support-matrix.md @@ -11,7 +11,7 @@ | Windows via WSL2 | Supported | Use the Linux install path inside WSL2 when the agent runs there. | | Native Windows | Experimental | Tagged releases publish `ai-memory-windows-x86_64.zip` with `ai-memory.exe`; Docker Desktop wrapper and source builds are also available. Native `ai-memory upgrade` is supported for writable x86_64 zip installs (checksum-verified zip + rename-aside self-replace + sibling `hooks/` refresh). Local supported profiles default to host-native hook commands; Claude Code may use its Windows exec form, while other agents use native single command strings matching their hook schema. PowerShell/Git Bash scripts are compatibility fallbacks. See [`docs/windows.md`](windows.md). | | Claude Code | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `install-mcp --session-aware` optionally enables per-session auto-scope isolation through a local stdio bridge. Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default). | -| Codex | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `SessionEnd` is wired since Codex CLI 0.145.0 (openai/codex#33895), so finished sessions get an automatic end-of-session summary/handoff; on older Codex the event is inert and `ai-memory finalize-session --agent codex` is the fallback. Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default) — Codex's `Stop` payload carries `last_assistant_message`, same as Claude Code. | +| Codex | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `SessionEnd` is wired since Codex CLI 0.145.0 (openai/codex#33895), so finished sessions get an automatic end-of-session summary/handoff; on older Codex the event is inert and `ai-memory finalize-session --agent codex` is the fallback. Managed runs (`ai-memory run codex`) can lose continuity through Codex's shared daemon inheriting a stale run id; launch with `--no-daemon` until #987 is fixed (see [`docs/managed-workstreams.md`](managed-workstreams.md)). Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default) — Codex's `Stop` payload carries `last_assistant_message`, same as Claude Code. | | Command Code | Supported | MCP config (`~/.commandcode/mcp.json`) + its four stable lifecycle-hook events (`~/.commandcode/settings.json`); native commands enforce capture exclusions and `SessionStart` injects handoffs. `Stop` is only a turn boundary, so use `ai-memory finalize-session --agent command-code` after the final turn; an interactive session launched with `ai-memory run command-code` is finalized automatically when it exits if the run can tie the session to itself (see [`docs/managed-workstreams.md`](managed-workstreams.md)). `ai-memory run command-code` adds exact v3 native-session resume and visible-event import; experimental unsandboxed Mods remain excluded. | | Devin CLI | Supported | MCP config + lifecycle hooks. Hooks use Devin's `PostCompaction` event, inject handoffs via `hookSpecificOutput.additionalContext`, and omit subagent events because Devin does not expose them. | | OpenCode | Supported | Remote MCP config + generated TypeScript plugin; generated plugin enforces capture exclusions. | diff --git a/docs/windows.md b/docs/windows.md index 276cd30b..3bb993f8 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -643,10 +643,12 @@ from what the repository actually ships today. decision is made; it is a blocker for a frictionless Supported experience on Application-Control-enforced fleets. -- **Native `ai-memory upgrade` path — in-progress.** A first-class in-place - upgrade for native Windows installs (release-binary and wrapper flows) is - tracked in #801/#802. Until it lands, upgrading is the manual - download/extract/re-`install-hooks` sequence in Scenarios B and C. +- **Native `ai-memory upgrade` path — done.** `ai-memory upgrade` upgrades a + writable native install in place (#801, #802): it verifies the + `ai-memory-windows-x86_64.zip` checksum, replaces `ai-memory.exe` by + rename-aside, refreshes a sibling `hooks/` tree, and re-stages installed + hooks — see Scenario B. A non-writable prefix (for example under Program + Files) still upgrades through the manual download/extract sequence. Promotion to Supported is the maintainer's decision once the in-progress items are closed and the deferred code-signing policy is resolved (or explicitly