Observability: document agenttrail as the recommended live lane view; evaluate PLAN.md as the plan-context format

[jeffhuber]

Owner review + trial 2026-08-28 of https://github.com/sodiumsun/agenttrail (MIT, local-only observability board for Claude Code/Codex/Cursor: fs watcher + optional Claude hooks + a PLAN.md convention; 127.0.0.1 only, no telemetry, dependency-free Node daemon).

Why it complements Code Mower

AgentTrail is the live "what are the lanes doing right now" pane Code Mower lacks. Code Mower judges at issue/PR/audit/gate/reporting time; AgentTrail observes local lane activity while the work is happening. Its declared-vs-observed drift signal is a useful live analogue to Code Mower's plan-conformance lens.

Decision

Make this a docs-plus-wrapper spike, not a fork. Code Mower should provide a safe launcher that can start AgentTrail without invoking agenttrail init by default. The wrapper must not edit PLAN.md, AGENTS.md, or CLAUDE.md, and AgentTrail must remain optional.

Scope

1. Add a safe observe-only launcher, likely code-mower observe agenttrail, that pins a reviewed AgentTrail version and starts npx -y agenttrail@<version> <repo> --no-open.
2. Before and after the launch, inspect tracked/untracked repo status and fail or warn if the wrapper changed repository files. Observe-only launch should leave tracked files unchanged.
3. Optional higher-fidelity mode may enable Claude Code local hooks only when explicitly requested. If implemented via AgentTrail's current init --hooks-only, document that it writes .claude/settings.local.json locally and is still opt-in.
4. Document AgentTrail as optional live lane visibility for operators using Code Mower with Claude Code, Codex, Cursor, and reviewer lanes. Keep Code Mower's privacy boundary unchanged: no source, raw diffs, transcripts, issue bodies, raw stdout/stderr, auth output, or secrets in CodeMower.com uploads.
5. Explicitly say component-map mode waits on upstream alternate plan-file support, such as agenttrail --plan-file .code-mower/agenttrail-plan.md / agenttrail init --plan-file ... --no-agent-docs. Do not fake this with top-level PLAN.md symlinks or temp mirrors.

Acceptance criteria

• Wrapper starts AgentTrail safely in observe-only mode with a pinned reviewed version.
• A focused test proves observe-only mode does not call agenttrail init and includes --no-open.
• A focused test proves the wrapper detects repository file changes after launch.
• Docs cover observe-only usage and optional Claude hooks.
• Docs explicitly state component-map support waits on upstream alternate plan-file support.
• No CodeMower.com event shape changes and no privacy-boundary widening.

Not release-blocking; candidate "pairs well with" line for the announcement.

[jeffhuber]

Implementation is in PR #440 and now through the gate after a fix round.

State:

• observe-only AgentTrail wrapper added, pinned to agenttrail@0.2.0; dry-run proves no agenttrail init and --no-open.
• optional Claude hooks documented as explicit opt-in via init --hooks-only.
• component-map mode explicitly waits on upstream alternate plan-file support.
• Claude initially BLOCKED on process-group shutdown; fixed and reran to PASS on b4b56a08e64df2ba850e1d1a6f83e8a7aefb1625.
• Gitar approved; CI green; local verification passed.
• Metadata-only CodeMower.com bundles are dry-run/upload-ready, but the actual upload is blocked here because CODE_MOWER_CLOUD_TOKEN is not set after restart.

Awaiting owner merge decision for PR #440.

[jeffhuber]

CodeMower.com upload blocker resolved for PR #440.

The saved local token env file existed but had not been sourced in this restarted shell. After sourcing it, both uploads passed cloud doctor + live health probe and were accepted:

• Dogfood/provenance upload id: b030abe9-4903-40f8-bcc5-13963ad21fef
• Reviewer-run upload id: 22974c14-6ec3-4230-8f2a-3737a08f759c

I kept the reviewer spend input narrow to the PASS run for the current head, avoiding the broader-ledger behavior tracked in #439. Privacy boundary unchanged.