codex-log-monitor

name

codex-log-monitor

description

Start one direct background Codex log-monitoring sub-agent that uses non-mutating queries, distills findings for the parent, and never delays the parent's primary task or final response. Resolve log authority from explicit input or the governing AGENTS.md, monitor for at least one real hour at a 60-second cadence, keep clean cycles silent, resume immediately after reports, and ask whether to continue at each hour boundary. Use after runtime changes, when a user asks to check, inspect, tail, watch, or monitor logs, or when independent live-log validation should continue while the parent works.

Codex Log Monitor

On activation, immediately delegate recurring log inspection to one direct sub-agent. The child is non-mutating against the monitored runtime, log sources, and repository; it is not silent. It must distill decision-relevant findings, send them to the parent immediately, and resume monitoring without waiting for acknowledgement.

Keep source discovery, repository edits, renewal decisions, and final user-facing synthesis with the parent.

Activation means the first Codex turn in which this skill is invoked, not skill installation. A skill cannot launch an install-time daemon by itself.

Primary Mission Invariant

Treat monitoring as a background sidecar, never as a completion gate for the user's original request.

• Immediately resume the primary task after starting or reusing the child.
• Never classify the child's one-hour duration, cycle count, clean status, or renewal boundary as remaining parent work.
• Deliver the primary result as soon as its own implementation, verification, and handoff criteria are satisfied. Do not wait for monitoring to finish.
• Let a new finding interrupt the primary workflow only when it materially affects the requested result or requires parent action. Monitoring does not authorize remediation or broader scope.
• Let renewal arrive as a later parent continuation or check-in after the primary result has been delivered.
• If the host cannot keep the child active after the parent responds, stop the monitor and report BACKGROUND_MONITOR_UNSUPPORTED. Never keep the parent turn open, poll repeatedly, or emit heartbeats to simulate background work.

Source Gate

Require one of these before the child queries logs:

1. An explicit log contract in the parent prompt.
2. A usable log contract in the AGENTS.md instructions governing the target project or service.

A usable contract identifies:

• the project root and runtime environment;
• the exact working directory;
• the authoritative log path, read-only command, or provider query;
• a bounded time window and result limit;
• a source-health or freshness check;
• any required service, deployment, request, trace, conversation, or tab id;
• fallback sources and their authority limits;
• sensitive fields that must be redacted.

A plausible command discovered in compose files, package scripts, or general runtime documentation is only a candidate. If any required field is missing, the child must send LOG_SOURCE_REQUIRED before its first log query. The parent must verify and document the complete contract before monitoring begins; do not query first and backfill AGENTS.md afterward.

Treat an empty buffer as UNKNOWN unless source reachability, collector health, and freshness are proven for the stated window.

Parent Workflow

1. Identify the target project, runtime surfaces touched, environment, and relevant time window. Capture stable ids from current context; never guess them.
2. Find the AGENTS.md files governing the target path. Pass their exact paths to the child.
3. Check the current agent tree for a live monitor with the same project, environment, and scope. Reuse it when present; never create duplicate monitors for the same authority.
4. Otherwise spawn one direct goal-backed sub-agent with agent_type: "log_debugger" when available. The parent running this skill must fill and pass the Child Contract directly. Do not ask the child to invoke $codex-log-monitor; that can create a coordinator child which then spawns a second monitor. The monitoring child must not spawn sub-agents. Use a non-mutating general sub-agent only when it supports the same recurring lifecycle. Do not delegate final user-facing status.
5. Immediately resume the parent's primary task after dispatch. Do not wait for the first child result or any later cycle before continuing implementation.
6. Give the child an explicit log contract when one is already available. Otherwise require it to read the governing AGENTS.md files before running any log command.
7. If the child reports LOG_SOURCE_REQUIRED, establish the authority using the recovery workflow below, document it, then use followup_task on the same child. Dispatch a replacement only after the original child is confirmed stopped.
8. Keep the child handle. Respond promptly to every MONITOR_RENEWAL_REQUIRED message with CONTINUE <seconds> or STOP. If the primary response has already been delivered, handle renewal as a later check-in; never delay the earlier handoff.
9. Do not poll, interrupt, or re-prompt the child once per cadence interval. The child owns recurrence. Intervene only for a reported blocker, renewal, explicit stop, or missing progress lasting more than two cadence intervals. Never interrupt an in-progress wait merely to request status.
10. Verify surprising failures against the named primary source. Synthesize the result for the user using the report contract without ending the child goal. Do not mirror clean-cycle messages to the user.

If Codex sub-agents or native goals are unavailable, report that blocker. Do not silently replace the required recurring check with a parent-only or one-shot check.

Child Contract

Give the child this task, filled with current values:

/goal: Monitor the request-relevant runtime logs with non-mutating queries for
at least 3,600 real seconds. You are the single direct monitoring child. Do not
invoke $codex-log-monitor and do not spawn another agent.

Run the first bounded query immediately after resolving log authority, then
start each later cycle on a real 60-second wall-clock cadence. Distill every
new or materially changed issue or observability blocker, send the essential
information to the parent immediately, and return directly to monitoring. Do
not wait for acknowledgement and do not finish because an issue was reported.

Project root: <absolute path>
Environment: <local, staging, production, or other>
Scope: <services, surfaces, and behavior being verified>
Time window: <bounded window>
Stable ids: <only ids already established, or none>
Governing AGENTS.md: <exact paths>
Log authority: <explicit contract, or "read governing AGENTS.md">
Minimum active duration: 3,600 seconds after the first successful query
Cadence: 60 seconds

First resolve the authoritative log source. If the prompt does not provide a
usable source, read the listed AGENTS.md files. Do not guess a path or command.
If no usable contract exists, send LOG_SOURCE_REQUIRED to the parent with the
AGENTS.md files checked, missing contract fields, and any clearly labeled
candidate sources. Do not query logs yet.

After authority is resolved, prove reachability and freshness, then run only
bounded read-only queries. Do not edit files, start or stop services, build,
deploy, reload, clear state, delete data, print secrets, or broaden scope.
Query bounded deltas with a small overlap and keep a timestamp/fingerprint
watermark so repeated cycles do not duplicate alerts. Start cycles from the
original schedule, not 60 seconds after the previous query ends.

Keep one long-lived monitoring turn active across cycles when the available
tools support it. Wait until the next scheduled deadline, run the bounded
query, inspect the result, and repeat without returning a final answer. If the
runtime forces goal continuations between cycles, persist the next deadline
and watermark, wait until that real deadline, and only then run and count the
next query. A goal continuation, parent message, status check, or elapsed chat
turn is never a completed monitoring cycle.

Do not require the parent to remain active while you wait. If the host cannot
preserve this child goal after the parent returns its primary result, send
`BACKGROUND_MONITOR_UNSUPPORTED`, complete the monitoring goal, and stop.
Never create rapid continuation turns, empty finals, or parent-supervision
loops as a substitute for background execution.

Treat more than one continuation before the next scheduled deadline, or three
consecutive child turns without a completed scheduled query, as unsupported
background execution. Send `BACKGROUND_MONITOR_UNSUPPORTED` and stop instead
of consuming more turns or tokens on orchestration retries.

After every issue or observability-blocker report, continue the same goal
immediately. Send findings through collaboration messaging when available;
reporting is an allowed and required outbound action, not a mutation of the
monitored system. After every parent message except `STOP`, return directly to
monitoring. A report is never a completion condition.

Keep clean cycles silent. Do not send or return `No new issue`, `.`, clean
progress snapshots, or other heartbeat messages. Do not end the monitoring
turn after a clean cycle.

If missing authority makes log queries unsafe, keep the goal active while the
parent resolves `LOG_SOURCE_REQUIRED`, then start the first cycle immediately.
If source access later fails, report the blocker once, attempt the same
documented read-only source with the required approval or documented fallback,
and resume from the same watermark. Do not count blocked intervals or
parent-proxied checks as successful child cycles.

After at least 3,600 seconds and 60 completed cycles, send
MONITOR_RENEWAL_REQUIRED with elapsed time, completed cycles, maximum cadence
gap, sources checked, issue fingerprints/counts, coverage gaps, and current
source health. Ask the parent for CONTINUE <seconds> or STOP. Keep monitoring
on the same cadence while awaiting the answer. On CONTINUE, begin the requested
extension without resetting the watermark. On STOP, send a final continuity
summary and complete the goal.

Require the child to activate this contract with the native create_goal tool. It must keep that goal active across notifications and renewal checks and must not mark it complete until the parent says STOP or relays an explicit user stop.

When collaboration messaging is available, require the child to send LOG_SOURCE_REQUIRED, distilled new or changed issues, observability blockers, and renewal requests to the parent immediately. If messaging is unavailable, report that as a blocker because the required recurring parent check-in cannot be completed.

Recover Missing Log Authority

When the child reports LOG_SOURCE_REQUIRED:

1. Inspect only decision-relevant repository and runtime sources, such as service scripts, compose files, process-manager config, provider config, observability config, and current development documentation.
2. Verify the candidate source with a bounded read-only query. A filename, script name, or stale document alone is not proof.
3. Ask the user for the missing access detail when multiple sources remain plausible or the primary source cannot be reached. Do not substitute a lower-authority source.
4. Add or update this section in the nearest AGENTS.md that governs the runtime. Create a project-root AGENTS.md only when no governing file exists:

## Runtime log authority

- Scope: `<service or runtime surface>`
- Environment: `<local, staging, production, or other>`
- Working directory: `<exact path>`
- Primary source: `<log path, read-only command, or provider query>`
- Bounded status query: `<time-bounded and result-limited command>`
- Health and freshness check: `<how collection is proven current>`
- Fallback: `<secondary source and its limitations, or none>`
- Required handles: `<service/deployment/request/trace ids, or none>`
- Redaction: `<secret and sensitive fields to omit>`
- Prohibited monitor actions: `<mutating commands the child must not run>`

5. Never place credentials, tokens, personal data, or machine-specific secrets in AGENTS.md.
6. If the current request is strictly read-only, obtain permission before editing or creating AGENTS.md. Keep the log conclusion blocked until the contract is documented or explicitly supplied.
7. Re-dispatch the child and require it to resolve the newly documented source from AGENTS.md.

Mandatory Recurring Lifecycle

Run every activation as recurring monitoring, including requests phrased as check, inspect, query, status, tail, watch, or monitor:

1. Run the first bounded query immediately after authority is proven. Start the one-hour clock with that successful query; source-discovery time does not count toward monitoring coverage.
2. Run at least 60 real bounded-query cycles over at least 3,600 seconds. Count a cycle only after the scheduled query completes; never count agent turns, goal continuations, status messages, or parent prompts.
3. Use one direct child for the entire lifecycle. The parent must not create a coordinator child, and the monitor must not spawn another agent.
4. Run independently of the parent lifecycle. Parent task completion is never a reason to stop, and monitor completion is never required before the parent returns the primary result.
5. Notify the parent only for new or materially changed issues, source-health regressions, observability blockers, and the one-hour renewal boundary.
6. After sending any notification, return directly to the scheduled monitoring loop. Never wait for the parent to acknowledge an issue report.
7. On clean cycles, stay in the monitoring turn and emit no parent-facing status or final answer.
8. At the one-hour boundary, ask the parent whether to continue, but keep monitoring until the parent explicitly replies STOP.
9. On CONTINUE <seconds>, extend the same goal and preserve source handles, schedule, and deduplication watermarks.
10. On STOP, send the final report and complete the goal.

An issue does not authorize remediation and is never a stop condition.

Report Contract

Require the child to send this distilled report for each new or materially changed finding:

Logs: PASS | WARN | FAIL | UNKNOWN | BLOCKED

Issues:
- <severity> <timestamp> <service/surface> - <symptom>; impact: <why it
  matters>; evidence: <minimal specific evidence>; confidence: <high, medium,
  or low>; fingerprint: <stable deduplication key>

Checked:
- <source/surface>: <status>, <window>, <freshness evidence>

Coverage gaps:
- <source/surface>: <unknown or inaccessible authority>

Skipped:
- <source/surface>: <reason>

Sources:
- <read-only paths, commands, or provider queries used>

Blocked:
- <none or exact missing access, handle, service, or tool>

Parent action:
- <none, verify a named surface, investigate a likely owner, or provide exact
  missing authority; never perform remediation without authorization>

Use this renewal message at each one-hour boundary:

MONITOR_RENEWAL_REQUIRED
Elapsed: <seconds>
Cycles: <completed count>
Maximum cadence gap: <seconds>
Current status: <PASS | WARN | FAIL | UNKNOWN | BLOCKED>
Issues: <new fingerprints and counts>
Coverage gaps: <none or exact gaps>
Source health: <current reachability and freshness>
Decision required: CONTINUE <seconds> | STOP

Do not paste raw logs unless the user asks. Redact secrets and unnecessary personal or message content.

Hard Stops

• Do not infer a log location from convention alone.
• Do not query a candidate source and backfill its authority afterward.
• Do not let monitoring delay or replace the parent's primary mission.
• Do not treat monitor duration, cycle count, or renewal as remaining parent work.
• Do not keep the parent turn open to simulate unsupported background work.
• Do not ask the monitoring child to invoke this skill.
• Do not let the monitoring child spawn another agent.
• Do not let the child edit AGENTS.md or any repository file.
• Do not run unbounded log dumps or indefinite tails.
• Do not start collectors or services as part of a read-only check.
• Do not report PASS from stale, unreachable, or unproven collection paths.
• Do not count chat turns, goal continuations, or status messages as cycles.
• Do not emit clean-cycle status, heartbeat, or final messages to the parent.
• Do not interrupt an in-progress cadence wait merely to request status.
• Do not finish after reporting an issue, blocker, or interim status.
• Do not wait for acknowledgement before resuming the next monitoring cycle.
• Do not stop at the one-hour boundary until the parent explicitly says STOP.
• Do not let the child decide the final user-facing conclusion.