feat(agent): add durable Claude print mode

.ai-devkit.json

@@ -108,6 +108,10 @@
     {
       "registry": "codeaholicguy/ai-devkit",
       "name": "changelog"
+    },
+    {
+      "registry": "codeaholicguy/ai-devkit",
+      "name": "agent-management"
     }
   ],
   "updatedAt": "2026-06-27T20:37:59.097Z"

docs/ai/implementation/2026-08-07-feature-agent-print-mode.md

@@ -0,0 +1,91 @@
+---
+phase: implementation
+title: Claude Print-Mode Agent Implementation
+description: Implementation record, decisions, validation, and deviations
+---
+
+# Claude Print-Mode Agent Implementation
+
+## Status
+
+- Current task: 4.4 validation and formal reviews.
+- Completed: Tasks 1.1–4.3.
+- Task tracing: unavailable (`unknown command 'task'`).
+
+## Changes
+
+### Task 1.1
+
+- Added `packages/agent-manager/src/print/PrintAgent.ts` with the durable record, state, session health, last-result, active-run, and process-identity contracts.
+- Added classified print-agent/store/Claude errors that do not carry prompt content.
+- Exported the public contracts from `@ai-devkit/agent-manager`.
+
+## TDD Evidence
+
+- Red: `npx vitest run src/__tests__/print/PrintAgent.test.ts` failed because `PrintAgentBusyError` was absent.
+- Green/refactor: the same focused test passed (1/1), followed by `npm run typecheck` exit 0.
+- Task 1.2 red: three focused store tests failed because `PrintAgentStore` was absent.
+- Task 1.2 green/refactor: all three store tests passed and `npm run typecheck` exited 0.
+- Task 1.3 red: two run-ownership tests failed because acquisition/completion methods were absent.
+- Task 1.3 green/refactor: all five store tests passed and `npm run typecheck` exited 0.
+- Task 2.1 red: two probe tests failed because `ClaudeCliProbe` was absent.
+- Task 2.1 green/refactor: both probe tests passed and `npm run typecheck` exited 0.
+- Task 2.2 red: runner tests failed because `ClaudePrintRunner` was absent.
+- Task 2.2 green/refactor: both runner tests passed; an initial typecheck caught an unsafe spread narrowing, then the full test/typecheck gate passed after correction.
+- Tasks 2.3–3.3 used focused service and CLI red/green cycles for create, first/resumed send, list/detail, and direct-send routing.
+- Task 4.1 added an executable fake Claude fixture proving no invocation at create, prompt-only stdin, exact first `--session-id`, and exact later `--resume`.
+- Task 4.2 red/green hardening covered stale/incomplete locks, cwd replacement, abandoned mutation locks, secret-bearing stderr, and unsupported timeout behavior.
+
+### Task 1.2
+
+- Added a separate versioned `~/.ai-devkit/print-agents.json` store.
+- Added canonical cwd validation, distinct UUID generation, exact ID/name resolution, duplicate-name rejection, atomic exclusive temp-file replacement, owner-only mode, bounded mutation locking, and symlink rejection.
+
+### Task 1.3
+
+- Added atomic per-agent lock directories, random ownership tokens, owner/provider PID-start fingerprints, fail-fast busy errors, token-checked state changes, and no-signal stale recovery.
+- Provider identity can be persisted before prompt delivery, closing the material parent-crash race described by the design.
+
+### Task 2.1
+
+- Added an injectable capability probe that invokes only `claude --version` and `claude --help`, requires the documented print/session/stream flags, and sanitizes bounded diagnostics.
+
+### Task 2.2
+
+- Added exact first/resume argv construction with `shell: false`, prompt-only stdin after durable provider identity, bounded NDJSON parsing, drained-but-undisclosed stderr, tolerant unknown events, strict session verification, and terminal-result plus exit-code success criteria.
+
+### Tasks 2.3–4.3
+
+- Added create/send orchestration with fail-fast ownership and no retries.
+- Added the narrow CLI integrations for print start, merged list/detail, and synchronous direct send while leaving interactive defaults and excluded commands unchanged.
+- Added deterministic unit/integration fixtures that never invoke a real model.
+- Added crash recovery for old mutation and incomplete run locks and exact cwd/session binding checks.
+- Documented inherited Claude permissions, hooks, MCP/tool side effects, and explicit print-mode timeout rejection.
+
+## Design Alignment
+
+- `AgentInfo` remains unchanged and process-specific.
+- Print-agent identity is a separate durable type.
+- No channel, task, receipt, daemon, queue, cancellation, deletion, transcript, or non-Claude provider behavior was added.
+
+## Deviations and Follow-ups
+
+- Claude CLI output details beyond the locally verified 2.1.220 help and captured official documentation remain protected by the startup capability probe and are tracked as compatibility behavior, not hard-coded version assumptions.
+
+## Formal Security Review
+
+- Scope: new print-agent domain/store/probe/runner/service, direct CLI integrations, fixtures, and documentation. Trust boundaries are CLI caller → local state → ephemeral Claude process → untrusted stream/output; the local OS account is the authorization boundary.
+- Remediated `SEC-PRINT-001` (medium, data exposure): provider stderr could contain an echoed prompt or tool secret. The runner now drains stderr but never reflects or persists it; a regression test uses a secret-bearing failure.
+- Remediated `SEC-PRINT-002` (medium, availability/business logic): a crash could strand the global mutation lock. Old empty mutation locks are atomically quarantined and removed after a bounded age; live short operations remain protected.
+- Remediated `SEC-PRINT-003` (medium, workflow correctness): print `--timeout` was accepted but unenforced. It is now explicitly rejected, because adding termination/cancellation is outside scope.
+- Remediated `SEC-PRINT-004` (low, terminal injection): human-rendered provider results now strip OSC and control bytes; JSON output remains structured data.
+- Verified controls: prompt only on stdin, `shell: false`, fixed allowlisted argv, canonical cwd binding, exact provider UUID matching, atomic fail-fast run lock, PID/start fingerprints, bounded stream lines, owner-only state files, symlink rejection, no retries, and no permission-bypass flags.
+- Dependency audit: 0 critical, 29 high, 11 moderate, and 2 low advisories in the existing workspace dependency graph. No dependency was added by this feature; remediation of repository-wide advisory chains is outside this feature scope.
+- Residual risk: Claude still inherits user/project settings, hooks, MCP servers, permissions, and tool side effects. A parent/process crash may leave the provider action outcome unknown; the agent becomes degraded and AI DevKit never retries automatically. Local users who can already modify the same account's state/config remain inside the authorization boundary.
+
+## Validation Evidence
+
+- Agent manager: lint/build passed; 24 files and 497 tests passed; coverage 89.66% statements, 77.98% branches, 96.13% functions, 92.88% lines (new print module: 80.5% statements, 70.08% branches, 95.71% functions, 85.51% lines).
+- CLI: lint/build passed with five pre-existing warnings in untouched files; 78 files and 921 tests passed; coverage 70.97% statements, 61.29% branches, 69.58% functions, 72.04% lines.
+- Base and feature lifecycle lint passed. The executable fake-provider journey passed without a real or billable Claude prompt.
+- Existing agent-manager tests emit process-listener count warnings; no new persistent listeners are registered by the print implementation.

docs/ai/planning/2026-08-07-feature-agent-print-mode.md

@@ -0,0 +1,153 @@
+---
+phase: planning
+title: Claude Print-Mode Agent Implementation Plan
+description: Ordered TDD tasks for durable Claude print agents
+---
+
+# Claude Print-Mode Agent Implementation Plan
+
+## Milestones
+
+- [x] Milestone 1: Durable identity, safe storage, and locking foundation.
+- [x] Milestone 2: Claude capability validation and synchronous provider execution.
+- [x] Milestone 3: CLI start/list/detail/send integration with interactive compatibility.
+- [ ] Milestone 4: Offline end-to-end validation, security hardening, and documentation.
+
+## Task Breakdown
+
+Every production behavior follows strict red → green → refactor. After each task, run its focused tests and reconcile this checklist before beginning the next task.
+
+### Phase 1: Durable foundation
+
+- [x] Task 1.1: Add print-agent domain types and typed errors.
+  - Outcome: stable record/state/result/process-identity contracts exported from `agent-manager`.
+  - Dependencies: approved requirements/design.
+  - Validation: type-level/unit tests for valid public shapes and error classification.
+  - Scenarios: store, locking, list/detail contract foundations.
+
+- [x] Task 1.2: Implement atomic JSON persistence and safe create/list/resolve.
+  - Outcome: separate versioned `print-agents.json`, canonical cwd, UUID creation, case-insensitive unique names, atomic replacement, and symlink rejection.
+  - Dependencies: Task 1.1.
+  - Validation: focused store tests including malformed storage, permissions, contention, and unsafe paths.
+  - Scenarios: print store/resolution unit tests and create/list integration.
+
+- [x] Task 1.3: Implement per-agent run locking and reconciliation.
+  - Outcome: atomic fail-fast busy acquisition, token-checked completion, PID/start fingerprinting, provider identity persistence, and safe abandoned-state recovery.
+  - Dependencies: Task 1.2.
+  - Validation: concurrent store instances, PID reuse, live provider, incomplete lock, stale recovery, and late-finisher tests.
+  - Scenarios: all busy-locking/recovery tests.
+
+### Phase 2: Claude execution
+
+- [x] Task 2.1: Implement non-billable Claude CLI capability probe.
+  - Outcome: injectable `--version`/`--help` validation for required flags only.
+  - Dependencies: Task 1.1.
+  - Validation: focused probe tests; no prompt/provider call.
+  - Scenarios: capability probe tests.
+
+- [x] Task 2.2: Implement bounded Claude stream parser and safe runner.
+  - Outcome: exact initial/resume argv, stdin prompt handshake, canonical cwd, bounded NDJSON/stderr, session verification, and terminal-result/exit validation.
+  - Dependencies: Tasks 1.1 and 1.3.
+  - Validation: fake spawn/executable tests for all normal and malformed stream cases.
+  - Scenarios: all runner/parser tests and provider identity mismatch integration.
+
+- [x] Task 2.3: Implement print-agent create/send orchestration.
+  - Outcome: start validates then persists without spawn; send acquires, runs once, completes ready or records degraded, and never retries.
+  - Dependencies: Tasks 1.2, 1.3, 2.1, and 2.2.
+  - Validation: service-level first-send, resume, busy, failure, and recovery tests.
+  - Scenarios: print service tests.
+
+### Phase 3: CLI integration
+
+- [x] Task 3.1: Add print mode to `agent start` without changing interactive defaults.
+  - Outcome: `--mode interactive|print`, Claude-only validation, correct output, and existing tmux path unchanged.
+  - Dependencies: Task 2.3.
+  - Validation: command tests for omitted/interactive/print/invalid combinations.
+  - Scenarios: CLI start tests.
+
+- [x] Task 3.2: Add combined print/live list and detail presentation.
+  - Outcome: durable agents remain visible without PIDs and expose required human/JSON metadata.
+  - Dependencies: Task 2.3.
+  - Validation: list/detail command tests, ambiguity fixtures, no fake terminal fields.
+  - Scenarios: CLI list/detail and create/list/detail integration.
+
+- [x] Task 3.3: Add combined direct-send resolution and synchronous print output.
+  - Outcome: exact stable ID/unique name resolution, cross-mode ambiguity, print send execution, and documented wait/timeout/JSON behavior.
+  - Dependencies: Tasks 3.1 and 3.2.
+  - Validation: direct-send command/service tests plus existing interactive send regression tests.
+  - Scenarios: all CLI send tests.
+
+- [x] Task 3.4: Prove excluded integrations remain unchanged.
+  - Outcome: groups, open, rename, kill, channels, and TUI retain live-agent behavior.
+  - Dependencies: Task 3.3.
+  - Validation: focused existing tests and diff inspection show no print routing in excluded paths.
+  - Scenarios: adjacent regression checklist.
+
+### Phase 4: Validation and hardening
+
+- [x] Task 4.1: Add fake-provider end-to-end fixture and CLI journey.
+  - Outcome: offline start → first send → resume → busy validation through built CLI/service boundary.
+  - Dependencies: Phase 3.
+  - Validation: deterministic E2E output and invocation/stdin capture.
+  - Scenarios: all end-to-end tests.
+
+- [x] Task 4.2: Complete coverage and edge-case hardening.
+  - Outcome: new code reaches target coverage; uncovered error/path/parser branches receive TDD tests and fixes.
+  - Dependencies: Task 4.1.
+  - Validation: agent-manager/CLI coverage reports plus performance/limit tests.
+  - Scenarios: coverage and performance sections.
+
+- [x] Task 4.3: Update implementation/testing/user documentation.
+  - Outcome: implementation record, completed testing evidence, CLI/package docs, permission/side-effect warnings, and compatibility notes.
+  - Dependencies: verified behavior.
+  - Validation: base/feature docs lint and documentation review.
+
+- [x] Task 4.4: Run implementation check, formal security review, and holistic code review; fix all blocking findings via TDD.
+  - Outcome: design alignment, security coverage, review readiness, and known-risk record.
+  - Dependencies: Tasks 4.1–4.3.
+  - Validation: lifecycle Phase 7, Phase 8, security-review, Phase 9, and fresh verification commands.
+
+- [ ] Task 4.5: Commit, fetch/rebase latest `origin/main`, revalidate, push, and open PR.
+  - Outcome: conventional local commit, clean rebased branch, published PR against main.
+  - Dependencies: Task 4.4 and user publication approval.
+  - Validation: clean status, commit SHA, post-rebase full validation, remote branch, and PR URL.
+
+## Dependencies
+
+- Tasks are sequential because storage contracts underpin runner/service/CLI behavior.
+- Task 2.1 can technically run beside storage work but remains sequential to preserve strict lifecycle reconciliation.
+- No real Claude credentials, model access, transcript, channel, task database, or daemon is required.
+- Official docs and local `claude --help` define required capabilities; unverified drift is handled by the startup capability probe.
+- Optional AI DevKit task tracing is unavailable (`npx ai-devkit@latest task list --name agent-print-mode --json` → `unknown command 'task'`).
+
+## Timeline & Estimates
+
+- Foundation: medium effort; locking/path safety is the highest-risk portion.
+- Claude execution: medium effort; protocol parsing and spawn handshake require careful fixtures.
+- CLI integration: medium effort; compatibility tests dominate.
+- Validation/review/publication: medium effort; coverage and rebase may reveal additional work.
+
+No calendar commitment is inferred; work proceeds sequentially through the approved lifecycle.
+
+## Risks & Mitigation
+
+- **Concurrent session corruption:** atomic per-agent lock; fail fast; exact process identities.
+- **Parent crash around spawn:** persist provider PID/start before sending prompt through stdin.
+- **Unsafe filesystem targets:** `realpath`/`lstat`, exclusive temp creation, same-directory rename, token-checked lock removal.
+- **Provider protocol drift:** capability probe, tolerant unknown events, strict required result/session validation.
+- **Secret leakage:** stdin prompt, bounded sanitized diagnostics, no prompt/transcript persistence.
+- **Permission/tool side effects:** inherit user configuration, add no bypass flags, never auto-retry.
+- **Interactive regression:** separate durable type and narrow CLI integration; full relevant regressions.
+- **Scope expansion:** excluded commands/integrations are explicitly checked and documented.
+
+## Resources Needed
+
+- Existing agent-manager and CLI packages/tests.
+- Local Claude CLI help/version only; no model invocation.
+- Official Claude headless/session/permission/hook documentation.
+- Temporary filesystem and fake-provider fixtures.
+- AI DevKit TDD, verify, testing, security-review, dev-review, commit, and PR skills.
+
+## Progress Summary
+
+Milestones 1–3 and Tasks 4.1–4.3 are complete. TDD hardening added age-bounded incomplete run-lock recovery, abandoned mutation-lock recovery, cwd binding checks, provider stderr non-disclosure, and explicit rejection of unsupported print timeouts. Task 4.4 lifecycle reviews and fresh validation are in progress; no scope blockers were discovered.