feat(agent): add machine-readable manageability CLI

[jonit-dev]

Summary

• Adds night-watch agent status --json as a stable machine-readable snapshot with schema versioning, legacy status data, pause state, queue state, board summary, health checks, and recent run telemetry.
• Adds JSON-first night-watch config list/get/set, night-watch health --json, and night-watch job pause/resume commands.
• Persists pause state in night-watch.config.json and makes cron/queue entry points skip paused jobs before starting new work.
• Adds focused Vitest coverage for JSON-only stdout, config dot paths, invalid path/value failures, and pause/resume config writes.
• Documents the agent CLI contract in README, command reference, the committed PRD, and SELF_REVIEW.md.

Tests Run

• yarn workspace @jonit-dev/night-watch-cli test src/__tests__/commands/agent.test.ts src/__tests__/commands/status.test.ts src/__tests__/commands/queue.test.ts
• bash -n scripts/night-watch-cron.sh scripts/night-watch-pr-reviewer-cron.sh scripts/night-watch-qa-cron.sh scripts/night-watch-audit-cron.sh scripts/night-watch-slicer-cron.sh scripts/night-watch-plan-cron.sh scripts/night-watch-merger-cron.sh scripts/night-watch-pr-resolver-cron.sh scripts/night-watch-helpers.sh
• yarn verify
• yarn workspace @jonit-dev/night-watch-cli build
• yarn lint (passes with existing warnings)

Docs

• Added docs/prds/agent-manageability-cli.md.
• Updated README with an Agent / Machine-Readable CLI section.
• Updated docs/reference/commands.md with command contracts, JSON behavior, examples, and pause semantics.
• Added SELF_REVIEW.md with implementation notes, tests, and limitations.

Known Limitations

• job pause prevents new cron/queue-dispatched starts; it does not terminate already running jobs.
• agent status includes board details only when a board is configured; board provider errors are captured in board.error rather than failing the entire snapshot.
• lastRuns depends on available job-run telemetry from the last 30 days.

Closes #99

[github-actions]

DiffGuard AI Analysis

AI Review Summary

🏆 Overall Score: 82/100

This PR implements a comprehensive agent-manageability CLI with JSON-first commands for external automation. The implementation is well-structured with good test coverage, but has a few behavioral concerns around queue handling for paused jobs.

---

✅ Key Strengths

• Comprehensive Feature Implementation: Complete implementation of agent status, config get/set, health checks, and job pause/resume with proper schema versioning for backward compatibility.
• Robust Config Validation: The setConfigValue function validates by reloading and rolls back on invalid persisted values, preventing config corruption.
• Clean Integration with Cron Scripts: The skip_if_job_paused helper integrates cleanly into all cron scripts, respecting pause state at the entry point.

---

⚠️ Areas for Improvement

• Queue Dispatch Behavior for Paused Jobs: In queue.ts, the dispatch command removes paused jobs from the queue entirely rather than leaving them for later execution. This could cause data loss if jobs are paused temporarily with expectation of resumption.
• Inconsistent lastExitCode Logic: In buildLastRuns, exit code is only set once (first success/failure), which can lead to lastExitCode: 1 while lastSuccessAt has a timestamp if a failure occurred before the success.
• Missing JSON Option for is-paused: The job is-paused command lacks a --json option, making it inconsistent with other job commands and harder for agents to parse programmatically.

---

📋 Issues Found

Issue Type	Issue Name	Affected Components	Description	Impact/Severity
Maintainability	Queue Job Removal on Pause	packages/cli/src/commands/queue.ts	Dispatch removes paused jobs instead of deferring them, potentially losing queued work during temporary pauses.	Medium
Maintainability	Stale Exit Code in Last Runs	packages/cli/src/commands/agent.ts	lastExitCode only captures the first success/failure, not the most recent run's actual exit code.	Low
Testing	JSON Parse Error Handling	packages/core/src/utils/config-path.ts	parseConfigValue doesn't wrap JSON.parse in try-catch; malformed JSON-like strings throw unhandled errors.	Low

---

🔚 Conclusion

This is a strong implementation that delivers the core agent-manageability contract well. The queue removal behavior for paused jobs should be clarified or adjusted before merge to avoid unexpected data loss. Minor exit code and error handling refinements can be addressed in follow-up.

---

Analyzed using z-ai/glm-5

[github-actions]

DiffGuard AI Analysis

AI Review Summary

🏆 Overall Score: 88/100

This PR implements a comprehensive agent-manageability CLI layer with stable JSON contracts, pause/resume job control, and config management. The implementation is well-structured, thoroughly documented, and integrates cleanly with existing systems.

---

✅ Key Strengths

• Comprehensive Implementation: Covers the full agent CLI surface (agent status, config get/set/list, health, job pause/resume/is-paused) with consistent JSON schemas and schema versioning.
• Safe Config Operations: config-path.ts validates paths against known config keys, blocks __proto__/constructor traversal, and implements rollback on validation failures after writes.
• Clean Cron Integration: skip_if_job_paused helper integrates pause checks into all cron scripts without disrupting existing flows, with proper result emission.

---

⚠️ Areas for Improvement

• Missing JSON Option on is-paused: The job is-paused command lacks a --json option unlike sibling commands, making programmatic parsing inconsistent for callers that expect uniform output modes.
• Hardcoded Job Types in Tests: The smoke tests inject if [[ "$1" == "job" && "$2" == "is-paused" ]]; then exit 1; fi into mock CLI scripts—this hardcodes "not paused" behavior and won't catch regressions if is-paused semantics change.
• Board Error Handling Verbosity: getBoardSnapshot catches errors but only preserves error.message; including error type/class would help agents distinguish permission issues from network failures.

---

📋 Issues Found

Issue Type	Issue Name	Affected Components	Description	Impact/Severity
Maintainability	Hardcoded Mock Behavior	core-flow-smoke.test.ts	Mock CLI scripts always return exit 1 for is-paused, bypassing actual pause logic and reducing test value.	Medium
Consistency	Missing JSON Flag	packages/cli/src/commands/agent.ts:jobCommand	job is-paused exits with code only; no JSON output option for callers preferring structured responses.	Low
Testing	No Negative Pause Tests	agent.test.ts	Tests verify pause/resume state changes but don't test that paused jobs are actually skipped by cron.	Low

---

🔚 Conclusion

Strong implementation that fulfills the PRD requirements with clean architecture and good test coverage. The issues are minor and non-blocking; the hardcoded mock behavior in smoke tests is the most notable follow-up for long-term maintainability. Ready to merge.

---

Analyzed using z-ai/glm-5