Chronos for Codex

View saved version →

---
name: chronos
description: Fully set up Chronos supervision and Heartbeats in one local Governor, or detect and mitigate Codex process, CPU, memory, handle, disk, diagnostic SQLite log, and token-quota degradation on Windows. Use for first-use setup, long-running task monitoring, Codex or PC lag, logs_2.sqlite growth, disproportionate token or quota use, and before or after long-running parallel work.
---

# Chronos

## Installation preflight

Run this lightweight check once when Chronos is first used in a task:

```powershell
"<skill-root>\scripts\chronos.cmd" -Action install-status
```

`sourceObservation=cache_inventory_not_enabled_state` means the result shows
valid cached package sources; cache presence alone does not prove that a source
is enabled. `sourceConflict=CONFIRMED` requires the running Directory package
and an enabled legacy Git configuration. If both cached sources exist but that
proof is absent, report `POSSIBLE` and inspect the plugin manager before making
changes. Explain that Codex treats the Git marketplace and Plugins Directory as
separate sources. Prefer `openai-curated-remote`. For a confirmed conflict,
with narrow user approval,
remove the legacy source through the Codex plugin manager, never by editing
configuration or cache files directly:

```powershell
codex.cmd plugin remove chronos@chronos
codex.cmd plugin marketplace remove chronos
```

Then fully quit and reopen Codex before starting a fresh task. An existing
process or task's loaded skill catalog cannot be hot-swapped. Do not remove the
legacy source when the Directory source is
absent, and do not imply that Chronos changed the active task catalog.

Keep inspection and Heartbeat evaluation lean and on-demand. Do not create an
operating-system scheduler, daemon, service, telemetry file, or persistent log.
When trusted and dispatched by Codex, the plugin's five monitoring hooks write
protected task, subagent, and completed-turn events to a bounded local inbox.
The next status or Governor cycle merges them into the supervision registry
under its mutex. It validates DPAPI identities inside the per-file boundary and
persists bounded slot-and-content receipts before deletion. It scans both
bounded inboxes before pruning receipts and defers temporarily unreadable files,
so one bad, locked, or queued file cannot block or replay supervision. Four request
asynchronous execution where supported; `SessionEnd` remains synchronous. They do not run on tools, commands, approvals, or prompts and
return no model context. Direct diagnostic hooks use the same protected event
format if registry contention prevents an immediate write. On Windows, each
definition uses a quote-free encoded launcher
because Codex passes the configured command through `cmd.exe`; the decoded
payload only resolves the installed plugin root and invokes the small intake
script. Do not rewrite it as a quoted `-File` command or route configured hooks
through the full supervision engine.

## Full setup request

When the user asks to set up Chronos fully, treat the request as an explicit
request to verify the installed source, run compact native status, and apply the
`chronos-governor` skill's Automatic Supervision Bootstrap. That bootstrap must
reuse or create one dedicated Governor, enable one host recurrence for
supervision and due Heartbeat evaluation, and verify zero worker recurrences.
This is a hard gate, not a best-effort sequence: the host must create or enable
no recurrence until initialization succeeds, supervision and Heartbeat status
are readable, one complete caller-aware inventory accounts for the selected
Governor exactly once, and the cycle returns `recurrenceEligible=true`. Any
earlier failure must end with zero active current-key recurrences and no recovery
recurrence.
Do not stop after an inspection or return setup instructions for the user to
relay. Never bypass or auto-approve Codex hook trust. If hooks remain untrusted,
complete setup through authoritative host inventory without asking the user to
register tasks; state only that optional hook acceleration is pending trust. An installed, active, or
trusted `/hooks` entry is configuration evidence, not proof that the command
executed. Read `hookExecutionObservation`, `hookRuns`, and `lastHookUtc` from
native supervision status. Report `not_observed` until a fresh post-trust
lifecycle or completed-turn event advances those fields. Keep one complete host
inventory per Governor cycle as the task-discovery and liveness authority
whether hooks execute or not. Hooks are an optional accelerator only.
`hookRequiredForAutonomy=false` must remain true, and a non-dispatching host
must not make setup fail after complete inventory and topology postconditions
pass.

Treat a nonempty `CODEX_HOME` as the installation boundary. Otherwise use the
current user's `.codex` directory. The native modules canonicalize and hash this
value; they never return the raw path. Invalid or inaccessible overrides fail
closed before state, claim, or recurrence eligibility can exist. Reject a
reparse point in any path component, including an ancestor junction. Consider
unscoped state from older releases only for the default `.codex` home; an
explicit or environment-provided home must not import it.
## Complete status request

When the user asks for a complete Chronos status, run the Inspector, supervision
status, and Heartbeat status. Present machine health separately from workflow,
quota, approval, rule, SQLite, and supervision conditions. A numeric zero is
not evidence of absence when coverage is partial, unsupported, outside the
window, or discontinuous; preserve those coverage labels. Report hook trust and
observed hook execution separately. This status-only request must not create a
Governor task, recurrence, worker, Heartbeat event, or task wake.
Heartbeat status without an input snapshot is prior-state inspection. Report its
`statusMode=prior_state` and its `evaluation` field as `observed`, `partial`, or
`unsupported`; do not call unsupported coverage healthy. A new partial or
unsupported family label replaces prior observed coverage and breaks continuity.

## Supervision

`-Action supervise` exposes compact status and discovery for one host-managed
Governor task. Worker tasks do not invoke Chronos, run a recurrence, or receive
routine wakes. Their model choice is independent of Governor. The host should
reconcile an existing matching host recurrence, reuse a verified Governor, or
create one fresh task with no inherited history; never automatically fork a
working task. The default is at most one Governor turn per active hour or one
per six idle hours, with a 336-cycle or 14-day rotation bound. Host reconciliation
uses the complete scoped equivalence key returned by status, deterministic immutable-ID winner
ordering, at most three attempts, and the exact postcondition one live Governor,
one active recurrence, and zero active duplicates. Only Governor cycles zero and
one repeat the installation-scoped host convergence check; normal cycles do not rescan host
automations.

```powershell
"<skill-root>\scripts\chronos.cmd" -Action supervise -SupervisionAction status
```

Only the Governor task runs `-SupervisionAction initialize`, `cycle`,
`reconcile-host`, and `discover`. Every Governor recurrence must use `cycle`
with one fresh complete host inventory. Schema v1 requires the Governor in the
raw list. Schema v2 may declare `callerVisibility=excluded_by_host`, omit only
the current Governor, and let the same cycle account for that registry-verified
caller without a second host query. Passive `discover` does not increment
the Governor cycle counter. The `.cmd` launcher always applies the required noninteractive
Windows PowerShell 5.1 execution-policy flags.
Host task tools remain the authority for whether a task is live. The registry
is a privacy-bounded discovery hint, not a task transport or security boundary.
See the public [supervision contract](https://github.com/FaxanFM/chronos/blob/main/docs/SUPERVISION.md).

## Heartbeats

Heartbeat evaluation is an opt-in action of this installed Chronos skill, not a
separate product. A host-side collector supplies a privacy-safe normalized JSON
snapshot; Chronos persists compact transition and dedupe state, then routes only
meaningful changes to one Governor inbox. Monitored tasks can use any model and
do not run Heartbeats. The recommended host configuration is one Governor task
using `gpt-5.6-terra` with Medium reasoning. The host selects that model; Chronos
cannot change a task's model setting.

`OwningSolThread` is always `governor`. `Owner` and `Subject` are compact routing
hints, not authority by themselves. The native script never sends a message or
starts another task. The Codex-host Governor may use `send_message_to_thread`
for one fixed-template intervention after it verifies exactly one live affected
task. It never broadcasts or gives monitored tasks a recurrence. The host supplies collector coverage
and chooses when to invoke the action. The engine enforces its registered
minimum cadence for each observed family. Supply a stable
`sourceEpoch` and increasing `sourceSequence`; without continuity proof, Chronos
can open a condition but will not resolve one. Governor-generated snapshots use
schema v2 and include all eight public family coverage labels. Every accepted
schema-v2 snapshot advances the source watermark before family cadence is
checked, including partial, unsupported, and cadence-skipped snapshots. Host inventory is
the liveness authority, but it is not a substitute for this collector snapshot.

```powershell
"<skill-root>\scripts\chronos.cmd" -Action heartbeat -HeartbeatInputPath snapshot.json
```

Use `-HeartbeatStatePath` only for controlled test or host-managed state. The
default state is
`%TEMP%\Chronos\Heartbeat-v2\<scope-sha256>\heartbeat-state.json`.
Explicit state paths are accepted only beneath that versioned TEMP root or the
LocalAppData Heartbeat root.
Chronos imports readable prior state without modifying its source directory. If
the prior sandbox-owned directory is inaccessible, it starts safely in the new
namespace and reports that migration result in compact status.
`priorStateDisposition=unavailable_preserved` and
`priorStateWriteAttempted=false` mean Chronos made no write or ownership-change
attempt against that prior state; they do not claim access to protected data.
Run the same action without an input path to show compact Heartbeat status.
After the host deduplicates and successfully delivers an event, pass its stable
ID with `-HeartbeatAcknowledgeEventId <event-id>`. Unacknowledged events remain
in a bounded local outbox and receive at most one retry after 15 minutes with the
same ID. `plan` and `fail-closed` consume actionable events atomically.
Use `-HeartbeatInspectorOutputPath` only with captured compact `CHRONOS` and
`CHRONOS EFFICIENCY` lines from a policy-authorized Inspector run. Pass
`-HeartbeatInspectorAuthorized` with the schema-v2 companion snapshot. The
adapter rejects missing, incompatible, or stale provenance. See the public
[Heartbeat contract](https://github.com/FaxanFM/chronos/blob/main/docs/HEARTBEATS.md)
for the strict normalized input contract and coverage limits. Complete Guardian
coverage also requires every required Inspector metric to parse and pass its
range check. Malformed complete evidence fails closed; it is never converted to
an observed result or a zero.

Only the dedicated Governor uses `-HeartbeatInterventionAction`. It must plan
all events before sending, keep one active intervention per target generation, recheck the
target generation before claiming a send, and use fixed returned instructions.
Transport acceptance is not task acknowledgement. A task response is not proof
of recovery; a later observed Heartbeat cycle or allowed independent host check
must verify the postcondition. Unknown delivery never retries. Definite failure
gets one retry. Governor/self-origin events never target the Governor.

Token volume is not price. Do not infer cost, quota impact, or efficiency from a
model name. Governor-origin `USAGE_BURN` remains Governor-local unless a second
same-subject, same-window event independently shows stall, review amplification,
or machine degradation. When it returns `GovernorLocalAction`, update only the
Governor recurrence, verify one active recurrence at the returned cadence, and
acknowledge the event only after that postcondition holds. Do not message a
monitored task or turn routine findings into user chores.

Before running Chronos, resolve `<skill-root>` to the directory containing this `SKILL.md`. Do not assume the user's workspace is the skill directory and do not search the whole disk.

## Run an inspection

Inspect only when lag is reported, before extending an already long-running session, or when long-running parallel work finishes:

```powershell
"<skill-root>\scripts\chronos.cmd" -Action inspect
```

Return only the compact `CHRONOS` summary unless details are requested. Do not paste raw process tables into the conversation.

The inspection opens only the exact Codex `logs_2.sqlite` database in logical
read-only mode. It does not change rows or schemas. SQLite can create or update
`-wal` or `-shm` coordination sidecars while opening a WAL-mode database, so
read `sqliteOpenMode`, `sqliteJournalMode`,
`sqliteSidecarMutationPossible`, and `sqliteSidecarMutationObserved`. It reports
database size, reclaimable freelist space, WAL activity, sequence movement, and
the aggregate TRACE percentage from up to 2,000 recent rows. It never reads log
bodies.

It also scans only the tail of recent, known Codex `sandbox*.log` files for two
exact filesystem-helper failure markers. It returns aggregate booleans and
never returns log text or paths.

For quota diagnostics, it streams at most 20,000 session inventory entries
under a three-second target, then reads at most 2 MiB from each of up to eight
rollout files modified in the last six hours. One filesystem call can exceed
the target. It retains only structured token-count,
turn-context, compaction, approval-state, and worker-call fields. It counts an
automatic review only when a `turn_context` record reports
`model=codex-auto-review`; similarly named bookkeeping records do not count as
reviews. It never returns raw rollout lines, prompts, responses, tool arguments,
tool output, identifiers, or paths. It reports aggregate parser-integrity,
reviewer, safe categorical approval, lineage, fork-context, and exact
cross-rollout duplication counters. Structured proposed-prefix arrays and
approval identifiers may be hashed in memory for repetition and state-transition
analysis. The inspector never returns prefixes, hashes, rule text, identifiers,
or credential-shaped values. Ephemeral hashes are discarded when the process
exits. Those counters do not alter health thresholds or scoring.

The same on-demand inspection reads up to 32 supported files only from the known
Codex rules directory. It returns aggregate rule structure and secret-shape
counts, never rules, commands, assignments, paths, hashes, or values. It does not
edit a rule.

Use `machineHealth` and the leading `CHRONOS` level for process, memory, handle,
CPU, disk, and filesystem-helper operability. Read `resourceDiagnosticLevel`
for the separate diagnostic-database condition and `overallDiagnosticLevel`
for the most severe observed diagnostic domain. Do not present storage or rule
hygiene as current machine failure when `machineHealth=HEALTHY`.

Read `tokenCoverageWindowHours`, eligible and selected file counts,
`tokenCoverageCapped`, truncated tails, and `tokenCoverageContinuity` before
interpreting numeric totals. `tokenSpawnObservation` and
`tokenCompactionObservation` distinguish observed events, a complete
not-observed result, partial coverage, unsupported event formats, and
unavailable data. A zero with `partial`, `unsupported`, or `unavailable` is not
evidence that the event never occurred.

`approvalReviewTurnsObserved`, `approvalReviewerSessionsObserved`, review rate,
interval, burst, confidence, parent-link, source, repeat-class, allowed/denied,
inspection-shaped, boundary-cause, and persistence fields
are bounded observations, not account-wide billing totals. Check
`approvalReviewObservation`, `approvalReviewCoverage`, and
`approvalRequestObservation` before interpreting them. `unsupported_schema` or
`observed_insufficient_structure` means the rollout did not expose enough safe
categorical data; do not infer a cause from model names or unstructured text.
Current structured escalation calls are counted without returning commands,
justifications, tool output, call IDs, prefixes, or hashes. Read
`approvalRequestSchemas`, resolved/unresolved request counts,
`approvalResolutionObservation`, and latency sample fields together. A function
call output proves only that a request reached a terminal tool result; it does
not prove an allow or deny decision without an explicit structured decision.
`metricSource=local_rollout`, `dashboardEquivalence=unsupported`, and
`billingInference=unsupported` are hard semantic boundaries. The inspector is
diagnostic-only: it never changes reviewer models, approval modes, or trusted
command rules.

Interpret approval problem classes independently:

- `persistence_runaway` requires a structured `ALLOW`, unresolved pending
  state, and a later equivalent request. An explicit persistence failure is
  reported separately and does not by itself establish a runaway.
  Recommend repairing approval persistence before changing reviewer cost.
- `rule_miss_amplification` means one structural equivalence repeated across at
  least two independently resolved `ALLOW` reviews. Denied, unknown, mixed, or
  unresolved repetition is not a rule miss. Review the exact operation manually before
  considering one narrow, reversible rule.
- `legitimate_or_diverse_boundary_volume` means the available evidence does not
  prove either defect. Do not weaken the sandbox.

`reviewerEscalationsObserved` means reviewer-originated escalation traffic. Do
not call it reviewer recursion unless `approvalRecursionRisk=observed`, which
also requires directly observed nested reviewer lineage.

Use the Rule Governor fields separately. `rule_secret_exposure` requires removal
of credential material and rotation if it may remain valid, but never repeat the
value. `rule_brittleness_warning` identifies literals longer than 256 characters.
`broad_interpreter_rule` identifies interpreter-wide trust. Never create or
recommend broad PowerShell, shell, Python, Node, curl, network, filesystem-write,
or outside-workspace rules.
`ruleSecretCandidateOrdinals`, `ruleSecretCandidateClasses`, and
`ruleSecretConfidence` identify only the bounded local rule order and safe shape
category. Use an ordinal for local follow-up; never paste the rule or value.

`machineHealthContributors` names the unchanged threshold clauses that produced
the process diagnosis. `machineHealthConfidence=threshold_observation_only` and
`responsivenessObservation=not_measured` mean the result is resource pressure,
not a measured UI-latency or freeze prediction.

Use `approvalModesObserved`, `reviewerControlCapability`, and
`reviewerCompatibility` as a capability probe. `supported` means only that the
runtime explicitly reported configurability; it does not prove a compatible
lightweight reviewer is advertised. `unsupported` or `unavailable` must remain
diagnostic-only.

`rolloutSelectedMiB`, growth, projection, lineage, replay, and compaction fields
describe only the bounded selected files. Growth and 24-hour projection use
file-lifetime metadata and are estimates, as declared by
`rolloutGrowthObservation`. Exact cross-file duplicates are a replay signal, not
proof of billed-token duplication. `tokenInheritedSnapshots` and
`tokenLineageDeltaFiles` show exact ancestor deltas that were removed;
non-exact history is not inferred. `tokenUsageScope` means the token total is not
a usage invoice and must not be presented as one.
`tokenSelectedCumulativeInputM` retains the frozen cumulative heuristic input.
Use `tokenIntervalInputM` and the other `tokenInterval*` fields for the marginal
difference between comparable timestamped snapshots in the selected tails.
`rolloutProjectionComparable=false` or
`rolloutGrowthObservation=suppressed_partial_coverage` means no 24-hour
projection should be quoted. `quotaRiskBasis=frozen_selected_cumulative_heuristic`
confirms that this engineering release did not recalibrate scoring.

Use task-age, top-lineage review share, fork, effort, and spawn-origin fields as
bounded efficiency observations. For simple work with
`spawnContextAmplification=observed`, recommend `fork_turns="none"` or the
smallest sufficient positive history. `nestedAgentObservation=not_observed`
must not be described as recursive fan-out. Surface a configured/effective
reviewer difference as a possible mapping or policy layer, not automatically a
defect. Do not rewrite the primary reasoning default.

Interpret the result:

- `HEALTHY`: continue normally.
- `WARNING`: recommend reducing concurrency when convenient.
- `CRITICAL`: recommend saving active work and restarting Codex at a convenient
  checkpoint.

Every status is advisory. After reporting it, continue the user's requested
work unless the user independently asks to pause. Never use a Chronos status to
refuse, suspend, cancel, or stop a Codex task.

Interpret the filesystem-helper fields separately:

- `fsHelper=WARNING`: warn that the helper is degrading and recommend saving
  work before relying on more sandboxed file operations.
- `fsHelper=CRITICAL` with `pcRestartAdvised=true`: advise a full Windows
  restart at a convenient checkpoint after work is saved. Continue the task if
  the user chooses not to restart yet.

Treat `logDb=WARNING` or `logDb=CRITICAL` as a product-level diagnostic-log
churn condition. Explain that sequence counts demonstrate row churn, not exact
physical SSD writes or confirmed drive damage. Report `logDbReasons` and keep
`logDbPerformanceImpact=not_measured` separate from `machineHealth`.

Interpret `quotaRisk` separately from the overall machine-health status:

- `LOW`: no current aggregate quota-amplification signal.
- `ELEVATED`: call out the reported contributors and recommend a clean
  checkpoint soon.
- `HIGH`: recommend the relevant `tokenAdvice` actions before extending the
  task substantially. Continue the user's requested work.
- `UNAVAILABLE`: no recent compatible rollout aggregate was found.

Report `tokenQuotaContributors` whenever quota risk is elevated or high. These
tags identify the already-measured threshold clauses responsible for the
classification; they are explanatory and do not change scoring. `tokenAdvice`
may still be `none` when no supported remediation tag matches; use
`tokenAdviceReason` to explain that case.

Apply the `tokenAdvice` tags:

- `lower-effort`: use Medium for routine stages; reserve High, Extra High, Max,
  and Ultra for bounded work that benefits from them.
- `fresh-task`: at the next clean milestone, start a focused new task instead
  of continuing to resend a large context.
- `bound-subagents`: avoid Ultra when quota constrained. If agents are needed,
  use `fork_turns="none"` or the smallest useful positive count and prefer
  Medium reasoning.
- `avoid-repeat-compaction`: repeated compaction is itself model work; prefer a
  focused new task after preserving the required handoff.
- `cache-write-risk`: GPT-5.6 cache writes can be more expensive than uncached
  input. Chronos can expose the volume but cannot patch Codex request fields.

When automatic review is materially active, remove pathological review
regeneration first, then reduce avoidable tool calls, then inspect rule quality,
then bound task and worker amplification. Make unavoidable reviews cheaper only
after those causes are addressed. Try operations expected to be sandbox-safe
before escalating; request escalation only after a real boundary is identified.

Do not describe a high `tokenCachedReadPct` as a leak or as equivalent spend.
Cache reads indicate reuse and are discounted, but they still contribute to
token-throughput limits. Interpret `cacheWriteObservation=unsupported_schema`
as unavailable telemetry. Only interpret `tokenCacheWriteObserved=false` as a
measured zero when `cacheWriteObservation=observed`; neither proves that no
upstream cache activity occurred.

When the user requests durable quota tuning, recommend this conservative
starting point but do not edit configuration without an explicit request:

```toml
tool_output_token_limit = 4000
model_auto_compact_token_limit_scope = "body_after_prefix"

[agents]
max_concurrent_threads_per_session = 2
default_subagent_reasoning_effort = "medium"
```

## Legacy actions

Older Chronos versions exposed `plan` and `cleanup` actions. They remain
accepted for command compatibility, but they are advisory-only:

```powershell
"<skill-root>\scripts\chronos.cmd" -Action plan
```

`plan` reports only a candidate count. `cleanup`, including `cleanup -Force`,
is disabled and always stops zero processes. Do not attempt an alternative
process-termination command.

## Safety

- Never block, pause, or end a Codex task based on a Chronos result.
- This Inspector skill never terminates a process. Governor can stop only the
  bounded Git subprocess it started when fingerprinting exceeds its time or
  byte limit; it does not terminate Codex or unrelated user processes.
- Never delete logs, caches, worktrees, or user data.
- Never create SQLite triggers, delete rows, change schemas, checkpoint, or
  vacuum Codex databases. SQLite coordination-sidecar activity remains possible
  under the documented logical read-only connection.
- Never change Codex reviewer configuration, approval mode, trusted-command
  rules, model catalogs, or sandbox permissions.
- Never expose usernames, local paths, prompts, responses, tool arguments,
  tool output, environment values, or unrelated process details.

Chronos mitigates symptoms; it cannot patch an internal Codex lifecycle defect. Restarting Codex remains the reliable recovery when app-owned helpers or handles remain elevated.

Referenced files: 5

View saved version →

---
name: chronos-governor
description: Set up one dedicated Chronos Governor for passive supervision and Heartbeats, or coordinate bounded read tasks for low-complexity repository exploration, review, and verification with Codex native workers while limiting concurrency, context, attempts, health impact, and token use. Shared-folder write delegation is disabled.
---

# Chronos Governor

Delegate small read-only side tasks while the coordinator retains all edits,
architecture, safety decisions, verification, and acceptance. Use Codex native
workers only. Do not create a daemon, operating-system scheduler, external
service, or unbounded autonomous loop.

## Automatic Supervision Bootstrap

When the user asks to enable Chronos supervision, enable Heartbeats, or set up
Chronos fully, perform this setup once. The request authorizes one dedicated
Governor task and one host-owned recurrence for supervision and due Heartbeat
evaluation; it does not authorize an operating-system scheduler, service,
worker loop, or unbounded model use. Tell the user before creation that the
default cadence is at most one Governor turn per hour while work is active and
one every six hours while idle. Worker tasks receive no recurring turns.

**Hard gate:** Do not create or enable any Governor recurrence until native
initialization succeeds, supervision and Heartbeat status are readable, and one
complete host-inventory cycle accounts for the selected Governor exactly once
and returns `recurrenceEligible=true`. The raw inventory uses schema v1 when the
host includes its caller, or schema v2 with
`callerVisibility=excluded_by_host` when the host task list omits the current
Governor; v2 normalization adds only that registry-verified cycle caller and
makes no second host-status call. Any other result requires zero active
current-key recurrences, verified from fresh host state. Never use a recurrence
to retry, recover, or finish a failed setup.

Read `hostEquivalenceKey` from supervision status. It is
`chronos-supervision-v1:<opaque-installation-id>` and scopes the dedicated task,
its compact assignment, and the matching automation to one local Chronos
installation. Use the complete returned value; the prefix or exact automation
name alone is not an equivalence key. Never copy a key from another machine.

Native status also reports privacy-safe `codexHomeSource` and
`codexHomeIdentity` fields. A nonempty `CODEX_HOME` is authoritative; different
canonical Codex homes are different installations. Stop before host mutation
when the override is invalid, unavailable, or cannot be resolved consistently.
This includes a reparse point in any path component. Do not treat unscoped
legacy state as belonging to an explicit or environment-provided Codex home.

1. Run `chronos.cmd -Action install-status`, compact supervision status, and
   Heartbeat status. A confirmed enabled-source conflict or unreadable native
   state fails closed before host mutation. Cached copies alone are not proof
   of a conflict. Do not run the broad Inspector or packaged validation suites
   during normal first-use setup; use Inspector only when compact status reports
   a health problem or the user separately asks for diagnostics.
2. Reconcile host state before trusting local state or running initialization.
   Collect one all-same-name observation set containing every host
   automation named exactly `Chronos Governor pulse`, its immutable automation
   ID, creation time when available, target task, and equivalence key. Also run
   `chronos.cmd -Action supervise -SupervisionAction status`. Observation does
   not grant mutation authority.
3. Derive a separate current-key mutation set. Include only automations whose
   compact assignment contains the complete current `hostEquivalenceKey` and
   confirms the dedicated role. Never mutate a same-name automation carrying a
   different key or an unverified key. Build the host candidate set from live
   targets in the current-key mutation set. Sort valid
   automation candidates by creation time ascending, then immutable automation
   ID and target task ID using ordinal comparison; a missing creation time sorts
   after a present time. Every installer must select the first candidate. If no
   valid automation exists, apply the same creation-time and immutable-ID order
   to role-verified claimed Governor tasks. A name alone or a local claim alone
   is not proof of role compatibility. If several candidates exist and stable
   host IDs are unavailable, stop without creating another candidate or recovery
   turn.
4. If no valid Governor exists and the host exposes `create_thread`, create one
   fresh task titled `Chronos Governor`. Do not fork the current task or copy its
   history. Request `gpt-5.6-terra` with Medium reasoning only when the host
   advertises that exact task-model choice. Field validation requires reliable
   tool use and recovery judgment in the coordinator role. Never silently
   substitute another model. After any creation, re-list all live, role-verified
   current-key Governor tasks and apply the same stable creation-time and
   immutable-ID ordering. Only the first deterministic setup contender may
   proceed to recurrence mutation or initialization. Every other fresh-task
   contender performs no local or host recurrence mutation, verifies that no
   recurrence targets it, and stands down. If stable IDs are unavailable, no
   contender proceeds.
5. Before initializing the selected task, pause or delete every active
   recurrence from the current-key mutation set, including
   the deterministic winner from an earlier setup. Immediately before the first
   mutation, repeat the all-same-name observation, current-key filtering, and
   role-verified task listing in steps 2 and 3, then repeat the deterministic
   setup-contender election. If a new recurrence or task changes the winner, or
   the selected task is no longer first, skip `-SupervisionAction initialize`
   entirely and enter the loser-verification branch below. Otherwise re-list host
   state and prove
   that zero current-key recurrences are active. Recompute the mutation set after
   every host read or mutation and use at most three bounded mutation and
   verification attempts. Leave foreign-key and unverified-key observations
   unchanged. If zero cannot be proven, stop before initialization and create no
   additional task, recurrence, or recovery turn.
6. Have only the elected selected task run `-SupervisionAction initialize`. The
   registry mutex fences only one machine and state root. If native initialization
   returns `error=supervision_governor_conflict`, do not execute the generic
   initialization-failure cleanup in step 7 and do not retry initialization.
   Enter the same loser-verification branch below. Any other initialization error
   proceeds to the fail-closed current-key cleanup in step 7. Use `-Force` only
   after host task status proves the recorded owner is not live.

   **Loser verification:** This branch has exactly two entries: pre-mutation
   election loss in step 5, which skips initialization, or the literal native
   `error=supervision_governor_conflict` in step 6. Re-read native status and host
   state without recurrence mutation. Only when they identify one live,
   role-verified winner with the complete current key may the loser stand down.
   The loser creates no automation, mutates no recurrence belonging to the
   verified winner, verifies that no recurrence targets the losing task and no
   worker recurrence exists, and may be archived. The winning setup alone owns
   recurrence convergence; after at most three bounded reads, final converged
   state is exactly one current-key Governor recurrence. If the winner cannot be
   verified within the bound, stop with no recurrence mutation and no recovery
   turn. Never fall through from this branch to step 7.
7. Before creating or enabling any recurrence, require the successful
   initialization payload, re-read supervision and Heartbeat status, and run one
   complete host-inventory `cycle` that accounts for the selected Governor
   exactly once under the caller-visibility contract above. Continue only when
   native state is writable, Heartbeat is readable,
   the cycle returns `recurrenceEligible=true`, and its compact status includes
   the selected Governor. Except for the two non-fallthrough loser-verification
   entries above, if initialization, status, Heartbeat, or the complete
   cycle fails, create no recurrence. Pause or delete every recurrence
   in the current-key mutation set, including a pre-existing active recurrence,
   then re-list host state and prove that zero current-key recurrences are
   active. Leave foreign-key and unverified-key observations unchanged. Use at
   most three bounded mutation and verification attempts. Retain only bounded
   local recovery state. Do not schedule a recovery turn.
8. Reconcile only current-key automations after the claim and complete inventory
   cycle succeed. Update the
   deterministic winner in place when possible, or create one when none exists.
   Attach it to the selected task, pause or delete every non-winner, then re-list
   host state. Recompute the same winner after every mutation. Use at most three
   reconciliation attempts in one setup turn. Success requires this exact
   postcondition: one live dedicated Governor, one active automation carrying
   the complete current equivalence key, and zero active duplicates. On the third
   failure, stop all further retries in that setup attempt. If any create, update,
   duplicate cleanup, or exact postcondition verification fails, pause or delete
   every recurrence in the recomputed current-key mutation set, re-list host
   state, and prove zero current-key recurrences are active within three bounded
   attempts. Schedule no recovery turn. Never mutate a foreign or unverified key,
   turn routine convergence failure into a user chore, or rely on a create or
   allow result alone as proof.
9. Before `discover` on Governor cycles zero and one, repeat the host candidate
   scan and exact postcondition check. This catches a concurrently created
   recurrence that was not visible during setup. A non-winning Governor must
   pause or delete its own recurrence, verify that the deterministic winner
   remains active, and stand down. If the losing task itself owns the local
   claim, use the normal two-phase release only after its recurrence is proven
   absent; otherwise do not mutate the local claim. Never clear another task's
   claim. After cycle one, do not rescan all host
   automations during normal cycles unless claim loss, rotation, or recovery
   requires reconciliation.
10. Use the cadence returned by supervision: 60 minutes with active monitored
   work and 360 minutes while idle. The setup is an explicit opt-in to those
   recurring model turns. A Governor is bounded to 336 cycles or 14 days. At the
   bound, perform a verified fresh-task handoff when host tools support it;
   otherwise pause the recurrence and retain the reason in Governor-local state.
11. If task creation is unavailable, use the current task only when the user's
   setup request is explicit. State that it is the fallback and do not duplicate
   the current conversation through `fork_thread`.

This order is also the recovery protocol. It converges after a crash between
task creation, claim, or automation creation; after a stale local claim; and
after local registry loss. Unclaimed extra tasks do not get a recurrence.
Duplicate recurrences are paused or removed before setup is reported complete.
The scoped host equivalence key and stable ordering are the same-installation
ownership fence; the local mutex is not. Different machines have different
opaque keys and therefore retain separate Governors for their separate local
registries.

The dedicated task should receive this compact, self-contained assignment:

```text
Chronos equivalence key: <complete hostEquivalenceKey from status>. Act as the
single Chronos Governor. Maintain one verified Governor recurrence and zero
worker recurrences.

Start each pulse by resuming native intervention state. Follow only the returned
permitted next action. Then use one complete host task inventory as liveness
authority. Write only opaque IDs, safe status categories, optional opaque
generations, capture time, and completeness to one bounded TEMP file. Run one
native supervision cycle, then remove the file.

Evaluate Heartbeats only from a current schema-v2 normalized collector snapshot
with stable sourceEpoch, increasing sourceSequence, and explicit coverage for all
eight public families. A Heartbeat status read without input is prior-state
inspection, not evaluation. If evidence is unavailable, keep that family partial
or unsupported. Never describe unevaluated families as healthy or absent.

Run Inspector only when health is unknown and this pulse will extend long-running
work, when the user reports degradation, or before and after long-running parallel
work. Feed only its compact output to the collector, with the authorized-evidence
flag. Do not run Inspector on every routine pulse or infer its fields from task
liveness.

For a new, materially worse, or eligible resolution transition, use only native
plan, claim, send, and record. Contact one exact verified live target with the
returned fixed template. Normal cycles do not wake tasks. Never read transcripts,
edit repositories, create a worker recurrence, or ask the user to relay routine
remediation.

Apply a returned Governor-local cadence action only to this recurrence and verify
it. Use 60 minutes for active work or 360 minutes while idle. Never create a
second recurrence.
```

Do not report full setup complete until all observable postconditions hold:
the expected installed source is active, native status is healthy or explicitly
degraded, exactly one live dedicated Governor owns exactly one active matching
recurrence, Heartbeat status is readable from that Governor, its `evaluation` is
reported as `observed`, `partial`, or `unsupported`, and no worker task has a
recurrence. `unsupported` is a valid coverage result, not a healthy result.
Return a compact setup summary with those fields. Do not make
the user infer success from `governorClaimed` or another internal state name.
Initialization, status, Heartbeat, or inventory failure is a hard zero-recurrence
postcondition. It applies to matching recurrences that predate the setup attempt
as well as any created during it; it is not a reason to schedule a retrying
Governor.

Plugin monitoring hooks register `SessionStart`, `SessionEnd`,
`SubagentStart`, `SubagentStop`, and one `Stop` signal after each completed main
turn. Non-terminal handlers request asynchronous execution where the host
supports it; `SessionEnd` is synchronous. When Codex dispatches them, they run
headless, return no model context, and create no model turn. Hook trust is
optional acceleration and must never block setup. If hooks are disabled,
untrusted, or not dispatched, continue with one complete compact host task-list inventory and reconcile
it through `-SupervisionAction cycle`; do not ask the user to register
or relay tasks. Brief registry contention uses a bounded protected fallback event;
`status` and `discover` reconcile and remove it under the registry lock. Never
bypass hook trust.

Every Governor pulse starts by calling `-HeartbeatInterventionAction list` with
this Governor ID. Resume or retain each record only through its returned
`permittedNextAction`. Do this before fresh detector evaluation. Reclaim only an
expired claimed send; native state changes it to `delivery_unknown`, never a
blind retry.

Then apply the bounded cycle-zero/one host convergence check when required and
call the host task list exactly once. The inventory must be
complete for the cycle to advance. Write only opaque task
IDs, safe status categories, optional opaque generations, capture time, and a
completeness flag to a bounded JSON file under `%TEMP%`; schema v1 requires the
Governor in `tasks`. When the host list excludes its current caller, schema v2
must declare `callerVisibility=excluded_by_host` and omit the Governor from
`tasks`; Chronos then adds that registry-verified cycle caller intrinsically.
Never infer caller exclusion, supplement it from a second host call, or write titles,
paths, or transcript content. Run `-SupervisionAction cycle` with that file,
remove the file, and treat the returned inventory as liveness authority. Verify
that `hostInventoryCycle` advanced once, `hostInventoryRawObserved` matches the
one raw list, and `hostTaskStatuses` contains one hash-only normalized entry for
every listed task plus exactly one intrinsic Governor only in caller-excluded
schema v2. The host inventory proves discovery and liveness only. It does not
prove Heartbeat progress, approval health, quota state, rule health, SQLite
churn, tests, Git state, or machine health.

Create a separate bounded Heartbeat collector file under `%TEMP%`. Use schema
v2, one Governor-local opaque `sourceEpoch`, an increasing `sourceSequence`, and
an explicit `observed`, `partial`, or `unsupported` label for each of the eight
public families. Include only current compatible evidence. Every accepted
schema-v2 snapshot advances the source watermark even when a family is not due
or its coverage is partial or unsupported. Never substitute a zero for an
unavailable or malformed field. Run `chronos.cmd -Action heartbeat -HeartbeatInputPath <collector-file>`,
then remove the file. A plain
`chronos.cmd -Action heartbeat` call reads prior state only. It does not count as
the current pulse's evaluation. Require compact status to report
`evaluation=observed`, `partial`, or `unsupported` and retain all unsupported
family labels.

Inspector is a bounded diagnostic source, not the hourly workload. Run it only
when health is unknown and the pulse will extend long-running work, when the
user reports degradation, or before and after long-running parallel work. Save
only the compact `CHRONOS` output to a bounded TEMP file. Add it to the same
schema-v2 collector call with `-HeartbeatInspectorOutputPath` and
`-HeartbeatInspectorAuthorized`, then remove it. The adapter requires compatible
run provenance. Without that authorized output, Inspector-derived approval,
review, quota, rollout, SQLite, rule, and resource evidence stays unavailable;
task liveness cannot supply it.

Use compact `wait_threads` snapshots from the rotating `checkBatch`, which
contains at most eight entries. If host inventory is unavailable, fail closed
for task-directed sends, retain pending state, and retry next cycle without a
user handoff. If an ended registry entry is confirmed live by the host, use
`-SupervisionAction confirm-active -SupervisionSubjectId <id>`; a delayed start
hook cannot revive terminal state by itself. Do not repeatedly read full tasks
or transcripts. A normal cycle must end without messaging monitored tasks;
`taskWakePolicy=intervention_claim_required` is the native postcondition. If
`rotationRequired=true`, reconcile a fresh Governor or pause the recurrence
before the current cycle ends. See the public
[supervision contract](https://github.com/FaxanFM/chronos/blob/main/docs/SUPERVISION.md).

Before building a Governor `usage` record, run `chronos.cmd -Action heartbeat`
once and copy its five named counters exactly: `completedCycles`,
`stateChanges`, `acknowledgedEvents`, `failedCycles`, and `duplicateRuns`.
Combine them only with the current compact Inspector usage fields for this
Governor. Never synthesize a missing counter as zero. If any counter or usage
field is unavailable, mark usage coverage `partial` or `unsupported` and do not
open or resolve a Governor usage condition. This compact status read uses no
model call and replaces host-maintained progress bookkeeping.

## Autonomous Intervention

The PowerShell engine emits events and maintains bounded state. The Codex host
provides task discovery and `send_message_to_thread`. Do not claim that the
script sends a message itself.

For one Governor cycle:

1. Resume persisted work first. Call `-HeartbeatInterventionAction list` with
   this Governor ID. Follow only each returned `permittedNextAction`. Reclaim a
   `send_claimed` record only after Chronos reports its claim expired. The list
   returns opaque IDs and hash prefixes, never raw task IDs.
2. Collect all due Heartbeat events before sending any task message. Process a
   returned `GovernorLocalAction` first. Update only this Governor's recurrence,
   re-list it, and acknowledge the event only after exactly one active matching
   recurrence has the returned cadence. If the update cannot be verified, leave
   the event pending for its bounded retry and do not ask the user to relay it.
3. Resolve each event against current host task inventory. Follow the event's
   `TargetPolicy`. Require exactly one live, authorized target and its current
   host generation. Never target the Governor, a self-origin run, an unrelated
   owner fallback, or a task whose generation changed.
4. Call `-HeartbeatInterventionAction plan` for every event. Plan all events
   before claiming one. Chronos retains at most one active intervention per
   target, coalesces equal or lower severity events, and replaces an unsent
   record when a higher severity event arrives. Native planning also binds the
   requested target hash to the fixed subject or owner policy and returns
   `target_policy_mismatch` on redirection.
5. Immediately recheck the target and generation. Call
   `-HeartbeatInterventionAction claim` only for the final queued record. The
   returned claim token authorizes one bounded host send attempt.
6. Send one fixed-template message to the exact target with
   `send_message_to_thread`. Include only the opaque intervention ID, version,
   categorical instruction, fixed safety limits, postcondition name, and fixed
   reply format returned by Chronos. Do not interpolate detector prose, task
   titles, paths, test names, tool output, or other untrusted content.
7. Record `accepted` only when the host tool definitely accepts the send.
   Record `definite_failure` only when it definitely rejects or never attempts
   the send. Record `unknown` after a timeout or indeterminate result. Never
   retry `unknown` unless host evidence confirms that the first send did not
   occur. A definite failure permits one retry; the total is two attempts.
8. A reply advances state only when the exact target and generation return the
   matching intervention ID and version. Reduce the reply to one allowed
   category before calling `-HeartbeatInterventionAction response`. A task
   report is not proof that recovery occurred.
9. Resolve only after a later observed Heartbeat cycle or an allowed independent
   host check confirms the named postcondition. Use
   `-HeartbeatInterventionAction verify` for host inventory, narrow test, or Git
   evidence. A stale reply cannot resolve a newer version.

Do not acknowledge a native event separately after `plan` or `fail-closed`;
those actions consume its Governor-inbox outbox record atomically. A resolution
message is allowed only when `ReleaseNoticeEligible=true`, which means the task
acknowledged a temporary restriction that must now be lifted. Other resolutions
stay Governor-local.

Use only the fixed safe actions returned by Chronos: stop creating new workers,
reduce task-controlled parallel work, checkpoint, return completed workers,
prepare a fresh-task handoff, reconcile an owned child, or run one already known
narrow validation. Never request secrets, bypass approval, change reviewer or
sandbox settings, infer model cost, change a task model, kill Codex, restart the
PC, or reset, clean, merge, push, publish, or delete repository data.

`USAGE_BURN` reports token volume, not price. Keep `CostImpact` and
`QuotaImpact` as `unknown` without trusted runtime metadata. A Governor-origin
usage event stays Governor-local. It may target another task only when a second
event proves stall, review amplification, or machine degradation for the same
subject within the same observation window. It can never target the Governor.
`throttle_recurrence_to_idle_cadence` means set only the Governor recurrence to
360 minutes and verify the one-recurrence postcondition. On
`restore_supervision_recommended_cadence`, reconcile the 60-minute active or
360-minute idle cadence and verify it before closing the local action.

When ownership is ambiguous, the target is not live, transport is unavailable,
or user authority is required, call `-HeartbeatInterventionAction fail-closed`.
Do not broadcast, choose an arbitrary target, or manufacture a user action.

To disable supervision, first call `release` without confirmation and follow
its host cleanup instruction. Pause or delete every verified current-key
recurrence, leave foreign and unverified keys unchanged, verify that no
current-key recurrence remains active, then call `release` again with
`-SupervisionConfirmRecurrenceStopped`. Never clear the claim first.

## Boundary

Governor is an advisory coordination aid, not a sandbox or security boundary.
Its temporary state is worker-reachable, prompt restrictions are not runtime
permissions, and its Git-visible fingerprint cannot prove that no filesystem
effect occurred. Rely on the active Codex sandbox for actual permissions.

Defaults:

- At most two active read-task workers.
- Shared-folder write workers disabled.
- At most three attempts per task and one correction.
- Delegation depth one by coordinator policy.
- Worker-created agents prohibited by prompt contract, not runtime enforcement.
- Full parent history disabled with `fork_turns="none"` on Multi-Agent V2.
- Final coordinator verification required.
- Automatic merge, reset, cleanup, commit, and deletion disabled.
- Worker-task recurrence and per-turn monitoring disabled.

## Keep With The Coordinator

Do not delegate edits, architecture, authentication, authorization, payments,
secrets, security boundaries, migrations, CI, dependencies, lockfiles, central
routing, deployment, publishing, merge, release, destructive operations, or
ambiguous work. Delegate only a concrete read-only side task that can proceed
while the coordinator continues useful non-overlapping work.

## Runtime Routing

Before calling Governor `status` or `plan`, inspect the active `spawn_agent`
tool contract. Delegation requires Multi-Agent V2 with
`fork_turns="none"`. If that field or value is not advertised, do not reserve a
plan, create a lease, or spawn a worker; complete and verify the work with the
coordinator. This clean fallback is a successful bounded outcome.

When V2 is available, read the active tool's advertised models and supported
reasoning efforts for this task. Encode that current inventory in runtime order:

```text
model-a=low,medium,high;model-b=low,medium
```

Include `|cost=N` only when the runtime itself advertises a numeric rank for
every compatible model. Pass the result as `-RuntimeModels`. Never infer cost
from a model name or reuse inventory from another task or installation.

Use low effort for exploration, documentation review, formatting review, and
focused verification. Use medium only for nontrivial code review or test
analysis. If inventory is missing, malformed, or incompatible, keep the work
with the coordinator.

## Workflow

### 1. Inspect Once When Needed

Use the Chronos inspector once when health is unknown and degradation matters.
Interpret `machineHealth` separately from `resourceDiagnosticLevel`,
`overallDiagnosticLevel`, and quota/rule findings. At machine `CRITICAL`, do not
create a worker. Never terminate work because of a Chronos result.

### 2. Preflight V2 Before Planning

Confirm that the active `spawn_agent` schema accepts `fork_turns="none"`. If it
does not, stop the delegation workflow before any Governor `status` or `plan`,
complete the read task locally, and independently verify it. Do not create and
cancel a plan merely to discover transport incompatibility.

### 3. Plan A Read Task

Run `status`, then plan with an opaque task ID, a read access mode, intended
repository-relative scope, current runtime inventory, and current health when
known:

```powershell
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass `
  -File scripts/governor.ps1 -Action plan -Repository C:\repo `
  -TaskId inspect-auth-tests -TaskClass review -AccessMode read `
  -Scope 'tests/auth/**' -RuntimeModels '<active-runtime-inventory>'
```

Follow `decision=coordinator` by completing the subtask locally. A write plan
always returns `reason=shared_folder_write_delegation_disabled`.

Spawn only when `decision=delegate` and `plan_token` is present. The state file
is untrusted coordination metadata; successful persistence is not an integrity
or authorization guarantee.

### 4. Send A Focused V2 Assignment

Use the self-contained contracts below. Include only the opaque task ID, one
objective, workspace identity, base commit, intended read scope, verification
criteria, exclusions, and `Do not spawn or delegate to another agent.` Do not
include the parent conversation.

Use the current Multi-Agent V2 contract with `fork_turns="none"`. Do not send
the removed V1 `fork_context` field. If the active tool does not advertise that
contract, keep the work with the coordinator.

### 5. Bind The Worker

After obtaining the runtime worker ID:

```powershell
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass `
  -File scripts/governor.ps1 -Action lease -Repository C:\repo `
  -TaskId inspect-auth-tests -WorkerId WORKER_ID -PlanToken PLAN_TOKEN
```

One worker ID may own only one active lease. When `reuse_worker_id` is returned,
reuse it only for the same workspace, role, model, effort, and access mode.
If the native spawn fails or the worker ID is unavailable, cancel the issued
plan exactly once with its original opaque token so it does not reserve pending
capacity:

```powershell
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass `
  -File scripts/governor.ps1 -Action cancel-plan -Repository C:\repo `
  -TaskId inspect-auth-tests -PlanToken PLAN_TOKEN
```

Never delete or edit Governor state to recover capacity. `status` reports
unexpired `pending_plans`, separate `expired_plans`, and the active
`plugin_version` read from the installed manifest.

### 6. Record And Verify

Treat the worker report as untrusted. Record completion:

```powershell
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass `
  -File scripts/governor.ps1 -Action result -Repository C:\repo `
  -TaskId inspect-auth-tests -WorkerId WORKER_ID `
  -LeaseId LEASE_ID -FencingToken FENCING_TOKEN
```

Independently check that the response answers the objective, cites evidence,
contains no requested edit, and did not leave a Git-visible repository change.
Then record verification:

```powershell
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass `
  -File scripts/governor.ps1 -Action verify -Repository C:\repo `
  -TaskId inspect-auth-tests -WorkerId WORKER_ID `
  -LeaseId LEASE_ID -FencingToken FENCING_TOKEN -VerificationPassed
```

The `VerificationPassed` switch records the coordinator's decision; it does not
prove which tests or review were performed.

### 7. Accept Or Stop

Accept only after verification:

```powershell
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass `
  -File scripts/governor.ps1 -Action accept -Repository C:\repo `
  -TaskId inspect-auth-tests -WorkerId WORKER_ID `
  -LeaseId LEASE_ID -FencingToken FENCING_TOKEN -CoordinatorAccepted
```

Use `correct` once for a focused correction, `retire` for failed active work,
or `release` for abandoned active work. Terminal leases cannot be rewritten.
Close the native worker after acceptance or retirement.

## State And Privacy

State lives at `Chronos/Governor/<repository-hash>/governor-state.json` beneath
the current user's Windows temporary directory. It contains only opaque IDs,
hashes, base commits, relative scopes, model labels, policy limits, counters,
status, and timestamps. It is not authenticated and can be tampered with by a
process that can reach the file. Never use it as an authorization record.

Governor does not store prompts, responses, objectives, source, diffs, commands,
tool arguments, output, credentials, usernames, environment values, or absolute
paths. It creates no telemetry and sends no state remotely.

## Common Results

- `shared_folder_write_delegation_disabled`: perform the edit as coordinator.
- `model_inventory_unavailable`: refresh the active tool inventory.
- `state_store_unwritable`: no worker was authorized; continue locally.
- `state_store_unreadable` or `state_read_failed`: continue locally and report
  the compact result; do not delete or edit state.
- `state_invalid_json` or `state_schema_invalid`: preserve the state and report
  the compact result; do not overwrite it to force recovery.
- `state_lock_unavailable`: wait briefly or continue locally; do not delete it.
- `worker_already_leased`: finish or release the worker's active lease.
- `plan_token_mismatch`, `plan_expired`, or `plan_already_consumed`: plan again.
- `cancel-plan` is terminal; a canceled token cannot later create a lease.
- `invalid_worker_id`: use the exact runtime ID; `/root/name` is supported.
- `workspace_fingerprint_limit_exceeded`: stop delegation and inspect locally.
- `read_worker_modified_workspace`: preserve and inspect the changes; do not
  attribute them automatically.
- `invalid_lifecycle_transition`: preserve the terminal record.
- `internal_error`: continue locally and report only the compact result. The
  privacy-safe `failure_stage` and `exception_type` identify the failing code
  boundary without including paths, exception text, or state content.

## Honest Limits

- Read-only is a requested access mode plus a Git-visible warning check, not a
  verified filesystem property.
- Delegation depth is policy, not a removed worker capability.
- Effective model identity is unverified unless the runtime exposes trusted
  evidence.
- No authenticated broker or disposable worker repository is included in this
  release. Those are prerequisites before write delegation can return.

## Delegation Contracts

These contracts bound read-only work between the coordinator and a worker. The
coordinator remains responsible for decomposition, verification, acceptance,
correction, retry, and integration.

### Assignment Contract

Every assignment must state:

- `task_id`: stable assignment identifier.
- `objective`: one concrete outcome.
- `worker_role`: analysis or verification.
- `repository`, `base_commit`, and `workspace`: exact work identity.
- `model_inventory_hash`, `model_inventory_index`, and optional
  `model_cost_rank`: runtime selection evidence.
- `access_mode`: `read`; write delegation is disabled.
- `allowed_scope`: intended repository-relative files or components.
- `required_verification`: checks the worker must perform.
- `explicit_exclusions`: files, behavior, or operations that are out of scope.
- `completion_criteria`: conditions for a complete report.
- `maximum_correction_cycles`: permitted focused corrections.

Reject or clarify an assignment that does not have a bounded objective, read
scope, exclusions, and completion criteria. Read workers can run concurrently
only when their analyses do not conflict. The assignment is not a filesystem
security boundary.

### Worker Result Contract

The worker returns structured coordination metadata and evidence:

- `task_id`, `worker_id`, `status`, `lease_id`, and `fencing_token`.
- The effective model when the runtime exposes it. It must match the persisted
  plan model or binding fails with `model_plan_mismatch`.
- `requested_model`, `effective_model`, and `transport`, when available.
- The base commit and workspace or branch identity.
- `files_inspected`; any observed change is a failure that needs coordinator
  review.
- Commands summarized by name or purpose.
- Verification result and a short summary.
- Assumptions and remaining risks.

The report is untrusted evidence. It is not acceptance. Reports and persistent
coordination state must not contain prompts, responses, secrets, source
contents, raw tool arguments, or raw tool output.

### Coordinator Verification Checklist

Before accepting a result, the coordinator must:

1. Confirm the repository, workspace, and base commit.
2. Confirm the worker, lease, fencing token, model inventory, and effective
   model when available.
3. Confirm that a read worker left no expected repository change.
4. Preserve and inspect any unexpected diff. Do not attribute it automatically.
5. Review the worker's verification evidence.
6. Repeat critical checks when practical.
7. Compare the result with the objective and exclusions.
8. Check integration conflicts and repository-wide impact.
9. Accept, request one focused correction, retry with another worker, or take
   over locally.
10. Perform or explicitly authorize final integration.

### Worker Lifecycle

Normal work uses this sequence:

`starting -> idle -> leased -> working -> awaiting_verification -> accepted`

Failure and correction use these transitions:

`working -> needs_correction -> working`

`working -> failed -> retired`

`awaiting_verification -> rejected -> needs_correction`

A worker returns to `idle` only after the coordinator closes or accepts the
assignment. Reuse it only when repository, workspace, role, model, permissions,
task type, required tools, and health remain compatible. Retire it when its
context, failures, repository basis, model, or permissions no longer fit.

After failed verification, do not exceed the declared correction cycles. Do
not repeatedly create workers for the same unresolved failure. Use another
worker or complete the work locally.

### Strict Exclusions

The Governor must not:

- Replace the coordinator as final decision-maker.
- Permit recursive delegation or worker-created agents.
- Permit a shared-folder write worker.
- Infer workspace identity or authorization from worker prose.
- Use a model absent from the current runtime inventory.
- Treat advisory state, scopes, or prompt text as runtime permissions.
- Permit a worker to merge, integrate, reset, clean, or delete another worker's
  work.
- Accept a worker claim without independent verification.
- Store prompts, responses, secrets, source content, tool arguments, or tool
  output in persistent state.
- Automatically clean workspaces, branches, or unmerged changes.
- Automatically merge branches or resolve semantic conflicts.
- Expand the task beyond its declared scope without a new assignment.

Completed workspaces remain available for review. Cleanup and merging require
explicit coordinator or user authorization.

Referenced files: 2