feat: establish Codex supervised workflow foundation - #8
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 85f6e5fea6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if (found.run.status !== "approved" || task.status !== "ready") { | ||
| throw new Error(`Checkpoint cannot execute from run=${found.run.status}, task=${task.status}.`); | ||
| } | ||
| ensureOperationBudget(found.run, "implementation"); |
There was a problem hiding this comment.
In repositories that keep the default safe policy, cewp supervise execute <run> --yes still reaches the managed codex-exec dispatch path because this flow never calls assertPolicyAllows, unlike the existing dispatch worker/pipeline commands. That starts a child Codex process and mutates the managed worktree while .cewp/policy.json says worker execution is not allowed, so the new supervised path bypasses the Core policy gate. Add the same policy check before creating the worktree or consuming budget.
AGENTS.md reference: AGENTS.md:L5-L5
Useful? React with 👍 / 👎.
| if (run.status === "verifying" && run.tasks[0].status === "awaiting-verification") { | ||
| return { | ||
| action: "verify", | ||
| command: `cewp supervise verify ${run.runId}`, |
There was a problem hiding this comment.
After a successful supervised dispatch, the run enters verifying and this next-action command is shown to the operator, but runSupervise only handles plan, approve, status, and execute, so cewp supervise verify <run> immediately fails as an unsupported command. In every successful supervised checkpoint, users are directed to a dead-end exactly when targeted verification is required, leaving the run unable to advance through the CEWP Core verification path.
AGENTS.md reference: AGENTS.md:L5-L5
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Establishes a Codex-first supervised workflow foundation in CEWP, including initial supervised run state/CLI, ownership/budget controls, deterministic capability evidence, and packaging a thin Codex plugin skeleton with expanded CI/test contracts.
Changes:
- Add supervised run planning/approval/execution state machine with budget/ownership gating and structured usage parsing.
- Introduce focused contract tests + deterministic fixtures (including Windows/Unicode path coverage) and expand CI matrix (Windows/Linux, Node 22/24/26).
- Package an opt-in read-only Codex plugin skeleton and ensure plugin/marketplace artifacts are included in
npm pack --dry-run.
Reviewed changes
Copilot reviewed 48 out of 50 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/harness/run-smoke.js | Updates smoke assertions for 0.8.0-beta.0 packaging + plugin artifacts. |
| tests/harness/README.md | Documents focused contract entrypoints and optional plugin lifecycle probe. |
| tests/harness/lib/fake-adapter.js | Adds --json output mode for deterministic structured usage events. |
| tests/fixtures/ownership/native-conflict.json | Adds ownership conflict fixture (native vs managed). |
| tests/fixtures/ownership/managed-active.json | Adds active managed ownership fixture. |
| tests/fixtures/contracts/process-results.json | Adds deterministic process-result fixture including Windows crash code. |
| tests/fixtures/contracts/managed-run.json | Adds deterministic managed run fixture. |
| tests/fixtures/contracts/filesystem.json | Adds deterministic filesystem fixture with Unicode root. |
| tests/fixtures/contracts/events.jsonl | Adds deterministic supervised event fixture data. |
| tests/fixtures/contracts/adapter-result.json | Adds deterministic adapter result fixture. |
| tests/fixtures/compat/v0.7.0-beta.0/contracts.json | Adds v0.7 compatibility fixture for schema/adapter surface. |
| tests/contracts/supervised-intake.js | Adds contract test for supervised plan/approve/status persistence. |
| tests/contracts/supervised-execution.js | Adds contract test for supervised execute dispatch/ownership/usage capture. |
| tests/contracts/skill-format.js | Adds contract test for skill format validation (optional components). |
| tests/contracts/plugin-package.js | Adds contract test for plugin packaging + v0.7 compatibility invariants. |
| tests/contracts/ownership-gates.js | Adds contract test for Core gate + ownership conflict evaluation. |
| tests/contracts/operator-json.js | Adds contract test for operator JSON envelope, inventory, and timeline normalization. |
| tests/contracts/init-install.js | Adds Unicode-path init/install regression contract using safe copy traversal. |
| tests/contracts/hook-output.js | Adds deterministic hook output/deny contract fixture test. |
| tests/contracts/deterministic-fixtures.js | Adds contract to ensure fixtures remain parseable/deterministic. |
| tests/contracts/adapter-profile.js | Adds contract tests for adapter registry, availability, profiles, and result normalization. |
| tests/capabilities/plugin-lifecycle.js | Adds optional Codex CLI plugin lifecycle probe (install/disable/upgrade/uninstall). |
| tests/capabilities/fixtures/deny-shell-hook.js | Adds deterministic hook fixture emitting deny output shape. |
| tests/capabilities/codex-app-server.js | Adds Codex app-server stdio capability probe (isolated CODEX_HOME). |
| src/supervise/state.js | Introduces supervised run schema/state persistence, approval flow, progress rendering, next action selection. |
| src/supervise/profiles.js | Adds assurance profiles, budget envelopes, and usage preview contracts. |
| src/supervise/execution.js | Adds supervised dispatch implementation (worktree ownership, budget gating, scope evidence, usage parsing). |
| src/supervise/cli.js | Adds supervise subcommand CLI output (operator-json envelope) and console UX. |
| src/skills/install.js | Replaces fs.cpSync usage with explicit recursive copy to improve Windows/Unicode safety. |
| src/skills/format.js | Adds skill directory format validator for optional components. |
| src/run/ownership.js | Adds execution ownership record schema + conflict detection logic. |
| src/run/control-gates.js | Adds Core gate + ownership conflict evaluation for controlled operations. |
| src/run/adapters/codex-exec.js | Adds optional --json structured output mode toggle for codex exec adapter. |
| src/cli/usage.js | Documents new cewp supervise ... CLI surface. |
| src/cli/parse.js | Adds supervise CLI parsing for plan/approve/status/execute and related options. |
| plugins/cewp/skills/inspect-cewp-run/SKILL.md | Adds read-only plugin skill for inspecting CEWP run state via CLI. |
| plugins/cewp/README.md | Documents plugin boundary and intentional limitations. |
| plugins/cewp/assets/cewp.svg | Adds plugin icon asset. |
| plugins/cewp/.codex-plugin/plugin.json | Adds Codex plugin manifest for CEWP. |
| package.json | Bumps version to 0.8.0-beta.0, raises Node floor, adds focused contracts + package file inclusions. |
| docs/skill-plugin-compatibility.md | Adds documented skill optional-component + plugin boundary compatibility evidence. |
| docs/release-notes.md | Adds 0.8.0-beta.0 release notes entry. |
| docs/codex-capability-matrix.md | Adds capability matrix separating host/plugin/app-server boundaries with evidence. |
| docs/adr/0003-cost-assurance-and-safe-pauses.md | Adds ADR formalizing budget/assurance/usage truth labels and safe pause states. |
| docs/adr/0002-execution-ownership.md | Adds ADR formalizing single execution owner/backend and ownership conflict requirements. |
| docs/adr/0001-codex-first-supervised-goals.md | Adds ADR defining Codex-first product boundary and provider constraints. |
| bin/cewp.js | Wires the new supervise command into the CLI entrypoint. |
| AGENTS.md | Adds contributor instructions aligned with Codex-first scope/ownership/budget constraints. |
| .github/workflows/ci.yml | Adds Windows/Linux CI matrix coverage for Node 22/24/26 plus pack/whitespace checks. |
| .agents/plugins/marketplace.json | Adds local marketplace entry to surface the CEWP plugin as opt-in. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| function outputJson(command, data) { | ||
| console.log(JSON.stringify({ | ||
| schemaVersion: "operator-json/v1", | ||
| command, | ||
| generatedAt: new Date().toISOString(), | ||
| data, | ||
| warnings: data.run.warnings || [], | ||
| }, null, 2)); | ||
| } |
| - Attempts: ${task.attempts.length} | ||
| - Latest verification: none | ||
| - Blockers: none | ||
| - Next safe action: ${nextAction.summary} |
| if (run.status === "verifying" && run.tasks[0].status === "awaiting-verification") { | ||
| return { | ||
| action: "verify", | ||
| command: `cewp supervise verify ${run.runId}`, | ||
| summary: "run targeted verification for checkpoint-1", | ||
| }; | ||
| } |
Summary
0.8.0-beta.0package surfaceWhy
This gives CEWP a trustworthy Codex-first foundation for long-running work without claiming unsupported host control. The runtime keeps execution ownership, scope gates, budget controls, and provider readiness explicit while preserving the existing reviewer and verification boundaries.
Validation
npm run checknpm run pack:dry-rungit diff --checkAll validation was run against the exact ten-commit PR head
85f6e5f.