Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
6515311
fix: bind fail-fast validation to source and runtime (#356)
Oct 25, 2026
6e11c34
feat: announce governor activation and expose intervention delivery (…
Oct 25, 2026
a86c034
docs: record governor ticket ownership and acceptance checkpoints (#350)
Oct 25, 2026
3a813f1
feat(dispatch): send compact bounded agent assignments (#355)
Oct 25, 2026
7f81f0d
feat: add durable operator governor deactivation (#352)
Oct 25, 2026
c34592b
fix: carry operator governor choice through bounded dispatch (#352, #…
Oct 25, 2026
2d1914b
docs: expose governor controls and record verified delivery (#352, #355)
Oct 25, 2026
6118f13
feat(governance): preflight host dispatch and retain manual repair au…
Oct 25, 2026
49df3a9
fix: qualify preflight against actual native executable sizes (#353)
Oct 25, 2026
4a72367
feat: enforce reviewed HTTP request admission and settlement (#354)
Oct 25, 2026
fd4e205
fix: preserve paused work and document request-path qualification (#354)
Oct 25, 2026
f6a5b99
test: prove native admission and zero-allowance operator deactivation…
Oct 25, 2026
b5f5f77
fix: keep spawn preflight from blocking handoff correction (#353)
Oct 25, 2026
2ecf4e9
docs: record native request proof and six closed governor tickets (#350)
Oct 25, 2026
e8eaabe
feat(governance): protect completion resources in request admission (…
Oct 25, 2026
da2f848
test: prove protected completion funding through real native requests…
Oct 25, 2026
545ec79
docs: freeze completed governor tickets for requested review (#350)
Oct 25, 2026
0a76bdf
fix: enforce visible admission and honor disabled governor transport …
Oct 25, 2026
38afb9c
fix: preserve public preflight refusal reason after review (#353)
Oct 25, 2026
d69408e
docs: close governor ticket delivery and record final validation boun…
Oct 25, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,12 @@ and requires fresh grants before new work; original history stays fenced.
**Agent spawn**:
Starting a separate agent conversation with an explicit assignment and scope.

**Compact dispatch packet**:
A bounded assignment containing objective, authority, scope, acceptance, evidence
locators, allowance, stop conditions and governance readback requirements. It
starts fresh context by default; full-history context requires a recorded
task-specific reason and a pinned source. A packet snapshot creates no authority.

**Agent refresh**:
Reloading selected runtime resources while preserving the conversation identity
and unfinished work. Legacy profiles reopen its client; approved shared MCP
Expand Down Expand Up @@ -241,3 +247,20 @@ alone grants no permission, executes no effect and authorizes no uncertain repla
**Background job result wake**:
An existing exact-owner wake observing the durable result of one approved bounded
local job. Awaiting the result does not relaunch the job or renew its task allowance.

**Governor**:
The operator-visible controller that applies authorized resource limits to a selected objective and explains its interventions to the operator and model.

**Governor deactivation**:
The operator's durable choice to stop governor interventions in a selected scope. It preserves accounting and work, does not renew resources or resume stopped work, and remains in effect until explicitly changed.

**Host compatibility preflight**:
A bounded read-only check before opted-in dispatch, separating reusable static
host observations from fresh accounting, controller and operator-control state.
It reports the actual enforcement mode without granting work or resource authority.

**Protected completion resources**:
The unused acceptance, review and bounded remediation estimates retained inside
an existing objective allowance. Host-bound completion work may use them;
implementation must leave them available. Deferral keeps mandatory work pending,
and verified completion releases unused protection without renewing the grant.
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,14 @@ provides MCP enrollment and an independent watcher: request checkpoint,
then pause the current native goal and interrupt its exact active turn. Limits
persist across replacement goals until an explicit user reset. Start with the
[existing-session workflow](skills/codex-wake/references/existing-goal-limits.md).
Governor activation and interventions must be explicit to both the operator and
model. In builds with the new governor controls, send **Deactivate governor** in
the selected conversation to disable its scope without another confirmation;
**Reactivate governor** explicitly restores it. Deactivation survives continuation,
delegation and restart, preserves accounting, and resumes nothing. See
[governor controls and offline host access](docs/governor-control.md) for capability
requirements; these source changes do not upgrade an installed runtime.

Each new conversation needs its own approved host grant; reusing a tab or CWD
does not transfer a previous conversation's resource authority.
Host setup and qualified accounting are required; polling and publication make
Expand Down
73 changes: 73 additions & 0 deletions docs/agent-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,11 @@ admits a bounded initial assignment only after its exact client is ready. Use
`sessions open` for attachment without task delivery. Tab creation, task
admission and completed execution have separate receipt evidence.

New assignments use a [compact bounded packet](task-briefs.md#compact-delegated-dispatch),
including plain `--task` launches. Inspect `dispatch` for input byte size/hash and
`execution.output_summary` for bounded native output metadata. Packet snapshots
never replenish allowance or override current operator controls.

The operator supplies a host launch registry, an existing approved workspace,
an existing owned app-server socket and tmux session. The workspace must already
be trusted in the selected Codex home. Example registry:
Expand Down Expand Up @@ -369,3 +374,71 @@ separates paid native candidate runs, public fixture coverage and exact released
installation checks. The [0.15.1 installed closeout](dev/evidence/plan0162/final-acceptance.md)
records later tab targeting and installation qualification. These receipts do not
configure profiles or grant authority on another host.

## Host compatibility before delegated dispatch

An operator can opt a spawn profile into a read-only compatibility preflight.
Add this field to that existing approved launch profile; it does not change the
strict private goal-policy grant schema or introduce caller-selected authority:

```json
{
"governance_preflight": {
"policy": "/owned/goal-policy.json",
"requested_mode": "sampled_stop",
"manual_authorization": "existing approved repair ticket or authorization locator"
}
}
```

`manual_authorization` is optional. It records already authorized manual work,
not a request for another approval. `thread_id` can name the host-selected source
for an operator CLI launch; a caller-bound launch must match its exact caller.
The goal grant must select the same endpoint, client path and Codex home as the
launch profile. Existing profiles without this field retain their behavior;
preflight neither enrolls them nor inserts a governor.

Public spawn returns `compatibility_preflight` before thread, tab or task effects
when a required capability is unavailable. It also rechecks at effect boundaries.
The worker's compact packet carries the initial mode/notice and a receipt locator;
retry retains its exact input, while current dynamic preflight results are fresh.

- `hard_admission` is a requested guarantee, currently **unsupported**. The result
is `degraded`, `admitted:false`, with actionable supported routes; it does not
silently use sampled stopping or manual fallback. No native per-request hook
or enforceable output ceiling is claimed, even when a ledger exists.
- `sampled_stop` requires current qualified accounting, a fresh resident first
poll, existing control readback and observed notice-read/model-delivery proof.
It has no exact token overshoot bound. Read-only preflight does not attest that
the operator UI rendered a notice; that remains an independent qualification.
- `manual` requires the retained host authorization locator. It can also be an
explicitly preauthorized fallback when sampled requirements are unavailable.
It carries an explicit notice and may bypass the resident *lifecycle watcher*
prerequisite for that repair assignment. It still checks and settles existing
budget reservations, original deadlines, permissions and strict executor gates.
It never starts/unmasks a service, clears a stop, changes counters, enrolls or
resumes the original goal, or renews an exhausted campaign.
- `inactive` requires an explicit disabled control snapshot for the exact selected
allocation. Unavailable/unknown governance is not deactivation or revocation.
Independent lifecycle/strict-executor controls remain unchanged.
- `degraded` identifies missing requested supervision, accounting, notice or
control proof without granting authority or blocking unrelated ordinary work.

Static observations are private receipts beneath
`WAKE_ROOT/goal-supervision/host-preflight/`. Reuse is keyed by the selected source
file hashes, client executable hash, connected Unix peer process generation and
executable hash, native metadata, exact profile/policy hashes and caller/workspace
identity. A connected peer executable is distinct from the selected client;
Python/wrapper/native binary differences and unqualified request-path coverage
remain explicit. The cache cannot promote a native admission guarantee.

Every attempt rechecks those bindings and performs fresh public `diagnose`/`show`
and operator-control reads. Controller heartbeat, accounting, usage, stop state
and current operator choices are not cached. Only the static notice-read capability probe is
reused; current notice/model-context evidence is read again. Unknown probe
outcomes are not qualified cache entries. Static probes use the
smaller selected timeout (at most five seconds); diagnostic/native-notice reads
retain the host grant timeout (also at most five seconds), and accounting scans
retain their owner's bounds. File hashing is capped at 256 MiB per executable
and 1 MiB per selected source/policy file. An unavailable static observation is
reported rather than turned into installed capability proof.
75 changes: 75 additions & 0 deletions docs/agents/source-bound-validation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Source-bound validation

For #356 / parent specification #350, run existing CI or host acceptance commands
through `scripts/validate_candidate.py` when their success gates a later automated
step. This is an operator development tool; it does not deploy, renew an allocation,
or authorize the commands in its manifest.

Create a manifest outside the candidate, for example:

```json
{
"checks": [
{
"name": "undefined names",
"axis": "ci",
"argv": ["{runtime}", "-m", "ruff", "check", "--select", "F821,F822,F823", "src", "scripts", "tests", ".codex/hooks"]
},
{
"name": "policy wiring",
"axis": "policy",
"argv": ["{runtime}", "scripts/check_policy_wiring.py"]
}
],
"on_success": []
}
```

```sh
python scripts/validate_candidate.py --repo "$PWD" \
--runtime /absolute/selected-prefix/bin/python \
--manifest /tmp/candidate-checks.json --receipt /tmp/candidate-checks-receipt.json
```

Use commands from `.github/workflows/ci.yml` and the existing public host acceptance
scripts for the relevant surface. This runner wraps their outcomes rather than
implementing another version of their checks. `{runtime}` expands to the absolute
invocation path, preserving virtual-environment selection. `--timeout` bounds each
command in seconds (default 300). Commands run from the candidate's Git root and
inherit the runner environment. Commands must report their own failures correctly;
an explicitly supplied shell program remains responsible for its exit status.

Every check is required by default. A required failure stops later checks and all
`on_success` actions, exits nonzero, and records its exact argv, exit code, stdout
and stderr. Unexecuted steps remain `BLOCKED`. Optional checks (`"required": false`)
retain their individual failure without blocking required checks; a run-level
`PASS` means its required checks and success actions passed, not that every axis
passed. Success actions stop on their first failure even if marked optional.

The new receipt is exclusively created outside the candidate; rerunning requires a
new receipt path and cannot overwrite an earlier failure. It binds outcomes to Git
HEAD, index digest, working content digest, dirty status and exact dirty paths,
selected runtime invocation/resolved path and binary digest, manifest digest, virtual environment `pyvenv.cfg` digest (or its absence),
platform, runner Python version, and a digest of the complete inherited environment.
Environment values are not published. Keep the environment/configuration used for
reproduction separately under its existing controls.

Source identity covers tracked and nonignored untracked files, modes, deletions,
and regular-file symlink targets. Ignored build artifacts are excluded. Submodule
candidates and directory/dangling symlinks fail qualification; validate those sources
separately. Checks must leave the candidate unchanged, including creating new
nonignored files. Put logs and artifacts outside it or in established ignored paths.
The manifest may list additional `runtime_files` paths (absolute or relative to the
candidate) to fingerprint external configuration or pinned dependency metadata.
External dependencies/configuration must be pinned by the existing acceptance
command; the runtime binary digest does not certify every dependency or remote host.

Identity is checked before and after each check and before each success action.
Detected source, manifest or runtime changes invalidate prior passing check results
and block remaining actions. This is drift detection, not a filesystem lock or a
sandbox against a command that changes and restores files during one check. For
concurrent editors, validate a dedicated immutable checkout. A success action may
intentionally commit the qualified candidate; receipts refer to the source identity
before that action. A source-changing action cannot precede another success action
without invalidating validation. Interrupted runs retain `FAIL` with the interrupted
step `RUNNING`; they cannot become passing by rerun overwrite.
15 changes: 15 additions & 0 deletions docs/dev/active-lanes.yaml
Original file line number Diff line number Diff line change
@@ -1,6 +1,21 @@
schema_version: 1
work_item_tracking: required
lanes:
- id: P175
owner: primary / ecochran76
objective: Transparent operator-controlled governor and bounded execution
work_items: [https://github.com/CochranResearchGroup/codex-wake/issues/351, https://github.com/CochranResearchGroup/codex-wake/issues/352, https://github.com/CochranResearchGroup/codex-wake/issues/353, https://github.com/CochranResearchGroup/codex-wake/issues/354, https://github.com/CochranResearchGroup/codex-wake/issues/355, https://github.com/CochranResearchGroup/codex-wake/issues/356, https://github.com/CochranResearchGroup/codex-wake/issues/357]
plan: docs/dev/plans/0175-2026-10-25-transparent-governor-delivery.md
branch: feat/transparent-governor
target: origin/main
plan_state: CLOSED
custody_state: PUBLISHED_REVIEW
checkpoint: 38afb9c44b7817a518b3a329fd9566b19ea7a0ec
pull_request: https://github.com/CochranResearchGroup/codex-wake/pull/358
dependencies: []
overlaps: []
updated_at: 2026-10-25
disposition: 351-357 CLOSED; review1/TDD1 complete with all3 findings addressed; native control/funding and source-bound checks PASS; final successor CI pending; PR358 integration open; no live effects
- id: P173-GOAL-UX
owner: primary / ecochran76
objective: Implement visible goal supervision and approved renewal
Expand Down
Loading
Loading