A

V1 Implementation Log

This log tracks implementation checkpoints for the V1 harness/process refactor.

2026-05-10 Initial Plan Checkpoint#

  • Built: branch v1; committed and pushed architecture/research docs; created implementation plan.
  • Files changed:
    • docs/plans/2026-05-10-harness-process-architecture.md
    • docs/research/2026-05-08-auto-generating-wikis-deep-research.md
    • docs/research/2026-05-09-claude-harness-capabilities.md
    • docs/research/2026-05-09-codex-harness-capabilities.md
    • docs/plans/2026-05-10-v1-harness-refactor-implementation.md
    • docs/plans/2026-05-10-v1-implementation-log.md
    • docs/plans/2026-05-10-v1-decision-log.md
  • Tests run: not yet for implementation; first checkpoint is docs/planning only.
  • Result: plan ready for implementation.
  • Next: start Phase 1 prompt system reset.

2026-05-09 19:42 PDT#

  • Built: Phase 1.1 minimal prompt layout.
  • Files changed:
    • prompts/operations/build.md
    • prompts/operations/absorb.md
    • prompts/operations/garden.md
    • prompts/agents/.gitkeep
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Tests run: npm test -- test/auth.test.ts test/bootstrap.test.ts test/capture.test.ts
  • Result: 3 test files passed, 58 tests passed.
  • Next: Phase 1.2 path-based prompt loader and joinPrompts.

2026-05-09 19:44 PDT#

  • Built: Phase 1.2 path-based prompt loading and joinPrompts.
  • Files changed:
    • src/agent/prompts.ts
    • test/bootstrap.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Tests run: npm test -- test/bootstrap.test.ts
  • Result: 1 test file passed, 28 tests passed.
  • Next: Phase 2.1 provider-neutral harness types/events/tools.

2026-05-09 19:45 PDT#

  • Built: Phase 2.1 provider-neutral harness types, events, and base tool registry.
  • Files changed:
    • src/harness/types.ts
    • src/harness/events.ts
    • src/harness/tools.ts
    • src/harness/index.ts
    • test/harness-types.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Tests run:
    • npm test -- test/harness-types.test.ts
    • npm run lint
  • Result: 1 test file passed, 5 tests passed; TypeScript lint passed.
  • Next: Phase 2.2 harness provider registry.

2026-05-09 19:47 PDT#

  • Built: Phase 2.2 harness provider registry with explicit provider metadata and placeholder adapters.
  • Files changed:
    • src/harness/providers/index.ts
    • src/harness/providers/metadata.ts
    • src/harness/providers/not-implemented.ts
    • src/harness/providers/claude.ts
    • src/harness/providers/codex.ts
    • src/harness/providers/cursor.ts
    • src/harness/index.ts
    • test/harness-provider-registry.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
    • docs/plans/2026-05-10-v1-decision-log.md
  • Tests run:
    • npm test -- test/harness-types.test.ts test/harness-provider-registry.test.ts
    • npm run lint
  • Result: 2 test files passed, 9 tests passed; TypeScript lint passed.
  • Next: Phase 3.1 process run records and ids.

2026-05-09 19:49 PDT#

  • Built: Phase 3.1 process run ids, run records, atomic writes, listing, finishing, and stale detection.
  • Files changed:
    • src/process/types.ts
    • src/process/ids.ts
    • src/process/records.ts
    • src/process/index.ts
    • test/process-records.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Tests run:
    • npm test -- test/process-records.test.ts
    • npm run lint
  • Result: 1 test file passed, 5 tests passed; TypeScript lint passed.
  • Next: Phase 3.2 wiki page snapshot and delta accounting.

2026-05-09 19:51 PDT#

  • Built: Phase 3.2 wiki page snapshots and delta accounting.
  • Files changed:
    • src/process/snapshots.ts
    • src/process/index.ts
    • test/process-snapshots.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Tests run:
    • npm test -- test/process-snapshots.test.ts
    • npm run lint
  • Result: 1 test file passed, 5 tests passed; TypeScript lint passed.
  • Next: Phase 3.3 foreground process manager start path.

2026-05-09 19:53 PDT#

  • Built: Phase 3.3 foreground process manager start path with run records, event logs, page deltas, reindex, and failure handling.
  • Files changed:
    • src/process/logs.ts
    • src/process/manager.ts
    • src/process/index.ts
    • src/harness/types.ts
    • test/process-manager.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Tests run:
    • npm test -- test/process-manager.test.ts
    • npm run lint
  • Result: 1 test file passed, 2 tests passed; TypeScript lint passed.
  • Next: Phase 3.4 background job execution.

2026-05-09 19:58 PDT#

  • Built: Phase 3.4 background job execution.
  • Files changed:
    • src/process/background.ts
    • src/process/spec.ts
    • src/process/types.ts
    • src/process/records.ts
    • src/process/index.ts
    • src/cli.ts
    • test/process-background.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
    • docs/plans/2026-05-10-v1-decision-log.md
  • Tests run:
    • npm test -- test/process-records.test.ts test/process-manager.test.ts test/process-background.test.ts
    • npm run lint
  • Result: 3 test files passed, 10 tests passed; TypeScript lint passed.
  • Next: Phase 4.1 Claude harness adapter port.

2026-05-09 20:03 PDT#

  • Built: Phase 4.1 Claude harness adapter port.
  • Files changed:
    • src/harness/providers/claude.ts
    • test/claude-harness-provider.test.ts
    • test/harness-provider-registry.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
    • docs/plans/2026-05-10-v1-decision-log.md
  • Tests run:
    • npm test -- test/claude-harness-provider.test.ts test/harness-provider-registry.test.ts
    • npm run lint
  • Result: 2 test files passed, 6 tests passed; TypeScript lint passed.
  • Next: Phase 4.2 Codex harness adapter port.

2026-05-09 20:06 PDT#

  • Built: Phase 4.2 Codex harness adapter port.
  • Files changed:
    • src/harness/providers/codex.ts
    • test/codex-harness-provider.test.ts
    • test/harness-provider-registry.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
    • docs/plans/2026-05-10-v1-decision-log.md
  • Tests run:
    • npm test -- test/codex-harness-provider.test.ts test/harness-provider-registry.test.ts
    • npm run lint
  • Result: 2 test files passed, 9 tests passed; TypeScript lint passed.
  • Next: Phase 4.3 Cursor harness adapter or Phase 5 operation spec builders, depending on whether we keep Cursor in V1.

2026-05-09 20:09 PDT#

  • Built: Phase 4.3 Cursor decision and Phase 5.1 Build operation.
  • Files changed:
    • src/operations/types.ts
    • src/operations/build.ts
    • src/commands/init.ts
    • test/build-operation.test.ts
    • test/init-helper.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
    • docs/plans/2026-05-10-v1-decision-log.md
  • Tests run:
    • npm test -- test/build-operation.test.ts test/init-helper.test.ts
    • npm run lint
  • Result: 2 test files passed, 19 tests passed; TypeScript lint passed.
  • Next: Phase 5.2 internal Absorb operation for capture/ingest.

2026-05-09 20:11 PDT#

  • Built: Phase 5.2 internal Absorb operation.
  • Files changed:
    • src/operations/absorb.ts
    • test/absorb-operation.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Tests run:
    • npm test -- test/absorb-operation.test.ts
    • npm run lint
  • Result: 1 test file passed, 4 tests passed; TypeScript lint passed.
  • Next: Phase 5.3 Garden operation.

2026-05-09 20:12 PDT#

  • Built: Phase 5.3 Garden operation.
  • Files changed:
    • src/operations/garden.ts
    • test/garden-operation.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Tests run:
    • npm test -- test/garden-operation.test.ts
    • npm run lint
  • Result: 1 test file passed, 4 tests passed; TypeScript lint passed.
  • Next: Phase 6.1 CLI command surface and shared --using parsing.

2026-05-09 20:15 PDT#

  • Built: Phase 6.1 CLI command surface and shared --using parsing.
  • Files changed:
    • src/commands/operations.ts
    • src/cli/register-wiki-lifecycle-commands.ts
    • test/operation-commands.test.ts
    • test/cli.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Tests run:
    • npm test -- test/operation-commands.test.ts test/cli.test.ts
    • npm run lint
  • Result: 2 test files passed, 25 tests passed; TypeScript lint passed.
  • Next: Phase 6.2 Jobs commands over .almanac/runs/.

2026-05-09 20:18 PDT#

  • Built: Phase 6.2 Jobs commands over .almanac/runs/.
  • Files changed:
    • src/commands/jobs.ts
    • src/cli/register-wiki-lifecycle-commands.ts
    • test/jobs-command.test.ts
    • test/cli.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Tests run:
    • npm test -- test/jobs-command.test.ts test/cli.test.ts
    • npm run lint
  • Result: 2 test files passed, 24 tests passed; TypeScript lint passed.
  • Next: run broader V1 verification, then request review.

2026-05-09 20:30 PDT#

  • Built: Review fixes after V1 review agent.
  • Files changed:
    • src/cli/help.ts
    • src/cli/register-wiki-lifecycle-commands.ts
    • src/commands/operations.ts
    • src/harness/providers/codex.ts
    • src/harness/providers/metadata.ts
    • src/operations/build.ts
    • src/process/background.ts
    • test/build-operation.test.ts
    • test/capture-status.test.ts
    • test/cli.test.ts
    • test/codex-harness-provider.test.ts
    • test/deprecations.test.ts
    • test/harness-provider-registry.test.ts
    • test/operation-commands.test.ts
    • test/process-background.test.ts
  • Review findings addressed:
    • Retired public almanac bootstrap command wiring from V1 lifecycle commands.
    • Added populated-wiki guard for almanac init unless --force is passed.
    • Stopped empty capture invocations from launching an Absorb run without transcript context.
    • Added child-side cancelled-record check before a background job starts harness execution.
    • Rerouted capture status and ps to the V1 jobs surface with deprecation warnings.
    • Tightened Codex capabilities and rejected unsupported Codex exec fields.
  • Tests run:
    • npm test
    • npm run lint
    • git diff --check
  • Result: 47 test files passed, 473 tests passed; TypeScript lint passed; diff whitespace check passed.
  • Remaining known follow-up:
    • Capture session discovery for Codex/Cursor and cross-app --all-apps still needs the provider-specific resolver layer.

2026-05-09 20:33 PDT#

  • Built: Claude transcript discovery for V1 capture.
  • Files changed:
    • src/commands/session-transcripts.ts
    • src/commands/operations.ts
    • test/operation-commands.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
    • docs/plans/2026-05-10-v1-decision-log.md
  • Behavior:
    • Explicit transcript files are validated and passed to Absorb.
    • No-arg capture defaults to Claude transcript discovery.
    • capture --session <id> finds matching Claude <id>.jsonl.
    • Codex/Cursor capture discovery still fails clearly unless transcript files are provided.
  • Tests run:
    • npm test
    • npm run lint
    • git diff --check
  • Result: 47 test files passed, 474 tests passed; TypeScript lint passed; diff whitespace check passed.

2026-05-09 20:35 PDT#

  • Built: foreground event observer path.
  • Files changed:
    • src/process/manager.ts
    • src/process/background.ts
    • src/operations/types.ts
    • src/operations/build.ts
    • src/operations/absorb.ts
    • src/operations/garden.ts
    • src/commands/operations.ts
    • src/cli/register-wiki-lifecycle-commands.ts
    • test/process-manager.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Behavior: foreground operations can now receive normalized harness events while the process manager also writes them to the JSONL run log. CLI foreground commands print compact progress lines for text, tool use, errors, and done events.
  • Tests run:
    • npm test -- test/process-manager.test.ts test/operation-commands.test.ts test/cli.test.ts
    • npm run lint
  • Result: 3 test files passed, 30 tests passed; TypeScript lint passed.

2026-05-09 20:39 PDT#

  • Built: streaming jobs attach path.
  • Files changed:
    • src/commands/jobs.ts
    • src/cli/register-wiki-lifecycle-commands.ts
    • test/jobs-command.test.ts
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Behavior: almanac jobs attach <run-id> now tails a run log until the run is terminal instead of printing only the current log snapshot.
  • Tests run:
    • npm test -- test/jobs-command.test.ts test/cli.test.ts
    • npm run lint
    • npm test
    • git diff --check
  • Result: focused tests passed, TypeScript lint passed, full suite passed with 47 test files and 476 tests, and diff whitespace check passed.

2026-05-09 20:45 PDT#

  • Built: Phase 8 old architecture cleanup.
  • Files removed:
    • src/commands/bootstrap.ts
    • src/commands/capture.ts
    • src/commands/captureStatus.ts
    • src/agent/sdk.ts
    • src/agent/selection.ts
    • prompts/bootstrap.md
    • prompts/writer.md
    • prompts/reviewer.md
    • old bootstrap/capture/capture-status test suites
  • Files changed:
    • src/agent/prompts.ts
    • src/agent/providers/prompt.ts
    • user-facing hints in list, doctor, setup, and wiki resolution
    • README.md
    • V1 implementation and decision logs
  • Behavior:
    • V1 operation prompts under prompts/operations/ are the required bundled prompts.
    • Public guidance now points at almanac init, not the removed almanac bootstrap.
    • Legacy capture status state readers are gone; status-like UX is the V1 jobs surface.
    • Generic non-programmatic-subagent fallback no longer hardcodes reviewer semantics.
  • Tests run:
    • npm run lint
    • npm test
  • Result: TypeScript lint passed; full suite passed with 44 test files and 421 tests.

2026-05-09 20:54 PDT#

  • Built: review-fix pass after V1 review agent.
  • Files changed:
    • src/commands/operations.ts
    • src/commands/session-transcripts.ts
    • test/operation-commands.test.ts
  • Review findings addressed:
    • Foreground operation failures now render error outcomes and nonzero exits.
    • Lifecycle commands now use configured provider/model defaults when --using is omitted.
    • Validation errors such as invalid --using and --json foreground conflicts now honor JSON output.
    • Claude capture discovery now applies --all, --limit, and --since, and fails clearly for unsupported --all-apps discovery.
  • Tests run:
    • npm test -- test/operation-commands.test.ts
    • npm run lint
    • npm test -- test/operation-commands.test.ts test/cli.test.ts
    • npm test
    • git diff --check
  • Result: focused tests passed, TypeScript lint passed, full suite passed with 44 test files and 424 tests, and diff whitespace check passed.

2026-05-09 21:05 PDT#

  • Built: code-quality review fixes and wiki gardening.
  • Review findings addressed:
    • Running-job cancellation can no longer be overwritten by a stale in-memory foreground record.
    • Process finalization failures now still attempt to write a terminal failed run record.
    • Codex and Cursor harness metadata now describes current adapter behavior instead of aspirational provider capabilities.
    • Build, Absorb, and Garden now share the common operation run-spec and process-dispatch plumbing in src/operations/run.ts.
  • Wiki gardened:
    • Removed stale bootstrap-agent page.
    • Added V1 pages for lifecycle operations, process manager runs, harness providers, lifecycle CLI, operation prompts, and build operation.
    • Updated capture/session/harness pages to describe Absorb, .almanac/runs/, provider adapters, and old pipeline removal.
    • Updated .almanac/README.md and topics so the wiki no longer points future agents at writer/reviewer/bootstrap as current architecture.
  • Files changed:
    • src/process/manager.ts
    • src/harness/providers/metadata.ts
    • src/operations/run.ts
    • src/operations/build.ts
    • src/operations/absorb.ts
    • src/operations/garden.ts
    • .almanac/ wiki pages and taxonomy
    • process/provider tests
  • Tests run:
    • npm test -- test/process-manager.test.ts test/harness-provider-registry.test.ts test/build-operation.test.ts test/absorb-operation.test.ts test/garden-operation.test.ts test/operation-commands.test.ts
    • npm run lint
  • Result: focused tests passed and TypeScript lint passed.

2026-05-09 21:09 PDT#

  • Built: second code-quality review fixes.
  • Review findings addressed:
    • Queued cancellation markers now prevent the child startup transition from overwriting cancellation before harness execution.
    • Claude harness metadata no longer advertises structured output until the adapter maps spec.output.
  • Files changed:
    • src/process/records.ts
    • src/process/manager.ts
    • src/commands/jobs.ts
    • src/harness/providers/metadata.ts
    • test/process-background.test.ts
    • test/harness-provider-registry.test.ts
    • .almanac/pages/process-manager-runs.md
  • Tests run:
    • npm test -- test/process-background.test.ts test/process-manager.test.ts test/harness-provider-registry.test.ts
    • npm run lint
  • Result: focused tests passed and TypeScript lint passed.

2026-05-10 Prompt Doctrine Split#

  • Built: shared base prompt modules for project-memory doctrine, page notability/graph structure, and page syntax/writing conventions.
  • Files added:
    • prompts/base/purpose.md
    • prompts/base/notability.md
    • prompts/base/syntax.md
  • Files changed:
    • prompts/operations/build.md
    • prompts/operations/absorb.md
    • prompts/operations/garden.md
    • src/agent/prompts.ts
    • src/operations/run.ts
    • operation prompt tests
    • .almanac/pages/operation-prompts.md
    • V1 architecture/implementation docs
  • Behavior:
    • All operation specs now assemble base/purpose, base/notability, base/syntax, the selected operation prompt, runtime context, and command-specific context.
    • Build/Absorb/Garden prompts now describe soft algorithms and optional helper/subagent usage without reintroducing fixed writer/reviewer roles.
    • Base syntax guidance covers frontmatter, grounding, natural slugs, topics, hubs, wikilinks, files:, and prompt-level sources: conventions.
  • Tests run:
    • npm test -- build-operation.test.ts absorb-operation.test.ts garden-operation.test.ts
    • npm run lint
    • npm test
    • npm run build
    • node dist/codealmanac.js health
    • git diff --check
  • Result: targeted operation tests passed with 3 files and 12 tests; TypeScript lint passed; full suite passed with 44 files and 427 tests; build passed; wiki health was clean; diff whitespace check passed.

2026-05-10 Codex App-Server Provider#

  • Built: Codex lifecycle operations now run through codex app-server --listen stdio:// instead of codex exec --json.
  • Behavior:
    • The Codex adapter keeps the same AgentRunSpec and HarnessEvent provider boundary.
    • It starts an ephemeral app-server thread, sends one turn, maps thread/turn/item notifications into normalized events, then shuts down the child process.
    • Structured tool display details are now preserved on tool_use and tool_result events so foreground output and run logs can show readable activity like reading files, listing files, searching, editing, and running commands.
    • Codex app-server turns use workspace-write filesystem access with network disabled by default.
    • Server-initiated approval and user-input requests get noninteractive denial or empty-answer responses instead of protocol errors.
    • App-server token usage is mapped from tokenUsage.last and tokenUsage.total.
  • Files changed:
    • src/harness/providers/codex.ts
    • src/harness/events.ts
    • src/cli/register-wiki-lifecycle-commands.ts
    • src/harness/providers/metadata.ts
    • test/codex-harness-provider.test.ts
    • test/cli.test.ts
    • test/harness-provider-registry.test.ts
    • .almanac/pages/harness-providers.md
    • .almanac/pages/process-manager-runs.md
  • Review:
    • Code-quality review found network access expansion, unsupported server request responses, wrong app-server token usage shape, and missing fake process coverage.
    • Fixes added no-network policy, valid denial/empty request responses, app-server usage parsing, and a fake codex app-server integration test.
  • Tests run:
    • Real temp-wiki smoke: dist/codealmanac.js ingest note.txt --foreground --using codex
    • npm test -- test/codex-harness-provider.test.ts test/cli.test.ts test/harness-provider-registry.test.ts
    • npm run lint
    • npm test
    • npm run build
  • Result: real Codex app-server smoke completed; focused tests passed with 37 tests; TypeScript lint passed; full suite passed with 44 files and 435 tests; build passed.

2026-05-10 Codex App-Server Review Fixes#

  • Built: final code-quality review fixes for the Codex app-server provider.
  • Behavior:
    • App-server launches now include --config mcp_servers={} so configured user-level Codex MCP servers are not exposed during CodeAlmanac runs.
    • initialize, thread/start, and turn/start JSON-RPC calls now fail with a provider error after a timeout instead of hanging forever.
    • Accepted turns now also have a terminal timeout, so an app-server that accepts turn/start but never emits turn/completed is recorded as failed.
    • App-server usage now trusts tokenUsage.last.totalTokens as the authoritative per-turn total.
    • Codex provider metadata now reports contextUsage: true because the app-server adapter emits context_usage events.
  • Files changed:
    • src/harness/providers/codex.ts
    • src/harness/providers/metadata.ts
    • test/codex-harness-provider.test.ts
    • test/harness-provider-registry.test.ts
    • .almanac/pages/harness-providers.md
    • docs/plans/2026-05-10-v1-decision-log.md
    • docs/plans/2026-05-10-v1-implementation-log.md
  • Tests run:
    • npm test -- test/codex-harness-provider.test.ts test/harness-provider-registry.test.ts
    • almanac health
    • npm run lint
    • npm test
    • npm run build
    • Real temp-wiki smoke: dist/codealmanac.js ingest note.txt --foreground --using codex
  • Result: focused tests passed with 2 files and 16 tests; wiki health was clean; TypeScript lint passed; full suite passed with 44 files and 439 tests; build passed; real Codex app-server smoke completed with the new config override.

Follow-up review found that the first timeout patch bounded only the handshake RPCs, not the post-turn/start execution phase. Added an accepted-turn timeout and regression coverage for a fake app-server that acknowledges turn/start and then never sends turn/completed.

Second follow-up review found a same-flush completion race: turn/start could resolve and turn/completed could settle the run before the async continuation started the watchdog. Added settled guards before late failure/watchdog paths and coverage for a fake app-server that emits the turn/start response and turn/completed notification back-to-back.