feat(agent-watchdog): add --dump-job one-shot CLI lookup - #75
Merged
Conversation
Adds `--dump-job <job-id>` to scripts/agent-watchdog.py: searches every workspace's jobs/<job-id>.json directly (no team/session/worktree setup required), prints the full record including result.rawOutput/touchedFiles, and exits without starting the persistent poll loop. Not-found and malformed-record cases exit 1 with a clear stderr message, no traceback. Ported from a doctrine gap identified in a user-level codex-monitoring skill, which had converged on the same field list via a hand-rolled python3 snippet. Replaces that copy-paste approach in skills/codex-crew/references/sandbox-and-recovery.md with a pointer to the new tested flag. Co-Authored-By: Codex Sol <noreply@openai.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a one-shot CLI mode to scripts/agent-watchdog.py for dumping Codex job state by id, and updates docs/tests/versioning to make it a supported, reusable workflow in the Claudius plugin.
Changes:
- Add
--dump-job <job-id>toscripts/agent-watchdog.pyto locate and print matchingjobs/<id>.jsonrecords across workspaces, then exit. - Add pytest coverage for found / not-found / malformed job record cases.
- Update
codex-crewreference docs and bump plugin version + changelog.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
scripts/agent-watchdog.py |
Adds --dump-job one-shot mode and CLI parsing/dispatch. |
tests/test_agent_watchdog.py |
Adds targeted tests ensuring dump mode output and clean error behavior. |
skills/codex-crew/references/sandbox-and-recovery.md |
Replaces hand-rolled snippet with the new --dump-job workflow. |
CHANGELOG.md |
Documents the new capability under 5.13.0. |
.claude-plugin/plugin.json |
Bumps plugin version to 5.13.0 (minor). |
Comments suppressed due to low confidence (1)
scripts/agent-watchdog.py:2116
- The USAGE text says stdout contains only transition lines, but --dump-job intentionally prints job records to stdout. Adjust the help text so it remains accurate when --dump-job is used.
--dump-job ID prints every matching Codex job record once and exits.
--worktrees precedence: flag > $CLAUDIUS_WORKTREE_ROOT > .claude/worktrees.
--codex-job-recency-secs defaults to 604800 (7 days); older job files are not parsed.
Emits ONLY transition lines to stdout; diagnostics to stderr.
"""
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+2216
to
+2219
| state_root = codex_state_root(env) | ||
| try: | ||
| matches = sorted(state_root.glob(f"*/jobs/{job_id}.json")) | ||
| except OSError as error: |
Comment on lines
+2246
to
+2257
| try: | ||
| with path.open(encoding="utf-8") as handle: | ||
| record = json.load(handle) | ||
| if not isinstance(record, dict): | ||
| raise TypeError("expected a JSON object") | ||
| except ( | ||
| OSError, | ||
| UnicodeError, | ||
| json.JSONDecodeError, | ||
| RecursionError, | ||
| TypeError, | ||
| ) as error: |
This was referenced Jul 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why this PR exists
A user-level
codex-monitoringskill had independently converged on the same doctrine ascodex-crew's job-state monitoring, plus one genuine addition: a hand-rolledpython3 -c "..."snippet to read a Codex job's full state file (result.rawOutput,result.touchedFiles, etc.) by id. Porting that as a raw doc snippet would have duplicated logicagent-watchdog.pyalready has tested (codex_state_root(), workspace resolution) — so instead it's now a real CLI feature on the script itself.What changed
scripts/agent-watchdog.py: new--dump-job <job-id>one-shot mode. Searches every workspace'sjobs/<job-id>.jsondirectly (bypasses all team/session/ownership discovery — deliberately, since this is meant to work even when you don't know which team/session a job belongs to), prints the full record (id,status,phase,pid,startedAt,completedAt,errorMessage,result.rawOutput,result.touchedFiles) for every match, and exits without starting the persistent poll loop. Not-found and malformed-record cases exit 1 with a clear stderr message — no traceback.tests/test_agent_watchdog.py: found-case, not-found-case, and malformed-file-case coverage for the new flag.skills/codex-crew/references/sandbox-and-recovery.md: § On-Disk Job State now points at--dump-jobinstead of leaving the read as a hand-rolled snippet..claude-plugin/plugin.json/CHANGELOG.md: version bump 5.12.1 → 5.13.0 (minor — new CLI capability).Test plan
python3 -m pytest tests/test_agent_watchdog.py -q— 91 passed (independently re-run by coordinator, not just Codex's self-report)ruff check/ruff format --check— cleantask-mrto0ofc-ojhhry) — resolved correctly viaresolve_workspace()🤖 Co-authored by Claudius the Magnificent — implementation by Codex Sol (
gpt-5.6-sol, high effort), verified and committed by the coordinator.