#202 feat: #201 pino JSONL logging framework

[Anonymous]

Originally created by: kumaakh

Summary

Pino JSONL Logging Framework (#201)

• Replaces ad-hoc console.error logging with a pino-based JSONL framework writing to APRA_FLEET_DATA_DIR/logs/fleet-<pid>.log
• Lazy logger initialisation — log file only created on first write; no startup I/O
• Per-<pid> file naming eliminates cross-process contention
• Log rotation via fs.createWriteStream (replaces pino-roll worker-thread transport for SEA binary compatibility): 10 MB cap, 3 retained files
• Full console.* audit — all 8 server-side call sites migrated; CLI scripts (install.ts, auth.ts, smoke-test.ts) remain exempt (no member context)
• console.error retained alongside structured log (MCP stdio spec compliance; Claude Desktop captures stderr)
• maskSecrets() applied to all log output — credentials never leak to disk
• Fault-tolerant: writeLog wrapped in top-level try/catch; logging failures never throw or crash the server

LogScope — Scoped Invocation Logger

• New LogScope class in log-helpers.ts: generates a random inv ID shared across entry/intermediate/exit log lines for a single tool invocation
• scope.ok(), scope.fail(), scope.abort() exit methods record outcome + elapsed ms
• logWarn / logError severity levels added; fatal paths in index.ts upgraded to logError
• Applied to execute-command, execute-prompt, send-files, receive-files
• Token usage (in=/out=) logged at execute-prompt scope exit for all outcomes

memberId Threading

• memberId threaded through all member-context tool handlers: execute-prompt, execute-command, stop-prompt, provision-vcs-auth, revoke-vcs-auth, send-files, receive-files, ssh, strategy
• Each JSONL log line carries member_id for per-member log filtering

stop_prompt Fixes

• Removed the one-shot stopped flag (isAgentStopped / setAgentStopped / clearAgentStopped): after stop_prompt the PM previously had to call execute_prompt once to clear the gate before doing real work — eliminated; stop_prompt now kills the PID and returns immediately
• Fixed stop_prompt / TaskStop ordering: stop_prompt must be called before TaskStop — if TaskStop fires first it breaks the MCP connection, fleet clears the PID, and the member process becomes an orphan
• Updated src/index.ts tool description, docs/api/stop-prompt.md, docs/features/session-lifecycle.md, and skills/fleet/SKILL.md to document correct order

API Rename: timeout_ms to timeout_s / max_total_ms to max_total_s

• timeout_ms renamed to timeout_s and max_total_ms to max_total_s across all tools, docs, skills, and README
• Conversion to milliseconds happens at the tool boundary (internal implementation unchanged)
• Cleaner, human-readable parameter surface for all callers

Test Suite — agent to member Rename

• All test local variables and fixture names renamed from agent to member for consistency with the public API naming
• Broken import paths fixed: member-helpers.js and update-member-cli.js references corrected
• Dead-code test deleted: tests/unit/pid-extraction.test.ts (tested extractAndStorePid removed from strategy.ts)

Windows Fixes

• CreateNoWindow=$true added to pidWrapWindows ProcessStartInfo — suppresses flashing console windows on Windows members
• windowsHide: true added to getCleanEnv execSync call

PM Skill / Docs Improvements

• skills/pm/context-file.md: guidance replaced with cleanup.md reference and recovery steps for accidentally committed context files
• skills/pm/SKILL.md: project sandboxing added as Core Rule 2; deploy description improved
• skills/fleet/SKILL.md and troubleshooting.md: Fleet Logs section added (log location, filtering by member_id)
• docs/api/stop-prompt.md, docs/features/session-lifecycle.md: updated to reflect kill-only behavior and correct stop/TaskStop order

Cleanup

• Removed feedback-skills.md from repo root (accidentally slipped into main via PR [#183])
• Removed stale fleet control files
• Removed extractAndStorePid dead code from strategy.ts
• llms-full.txt regenerated

Test plan

• [ ] npm run build — 0 errors, 0 type errors
• [ ] npm test — all tests pass (1017+)
• [ ] npm run build:binary — SEA binary builds and starts cleanly (verifies fs.createWriteStream is SEA-compatible, unlike pino worker-thread transport)
• [ ] Unit tests for logLine(): directory creation, JSONL field shape, member_id inclusion/exclusion, maskSecrets(), rotation config, console.error parity
• [ ] Unit tests for LogScope: inv propagation, ok/fail/abort exit methods, elapsed ms
• [ ] stop_prompt tests: assert kill-only behavior, no stopped-gate, immediate re-dispatch after stop
• [ ] Cancellation integration suite: verify immediate re-dispatch after stop_prompt without a dummy execute_prompt call
• [ ] timeout_s / max_total_s parameter validation: ensure old timeout_ms names are rejected
• [ ] Three-phase review by fleet-rev — all phases APPROVED (on record in commit history)

Closes [#201]

[Anonymous]

Ticket changed by: kumaakh

• status: open --> closed