Skip to content

Repository navigation

docs: CS-RG qualification report, supported modes, adoption and rollback (CSRG-U6) #99

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
novelKR merged 2 commits into from
Oct 14, 2026
+649 −14
Merged

docs: CS-RG qualification report, supported modes, adoption and rollback (CSRG-U6) #99

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
13fe686
docs: draft the CS-RG qualification report (CSRG-U6)
claude Oct 14, 2026
68e274d
docs: record the CS-RG control-path results (CSRG-U6)
claude Oct 14, 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
268 changes: 268 additions & 0 deletions docs/cs-rg-qualification-report.md
View file
Open in desktop

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions docs/cs-rg-qualification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

This page is the protocol for qualifying CodeSpace's use of DevGuard (CS-RG): which combination is qualified, which modes are claimed, how each claim is tested and measured, what makes a run pass, and what evidence a run leaves. It is frozen together with its harness, [`scripts/qualify-devguard.py`](../scripts/qualify-devguard.py), before any qualification run. A change to it, or to the harness, after the first qualification run is a new protocol: it is reviewed like any other change, and the runs it affects are repeated. The [integration roadmap](devguard-integration.md) describes what each unit built; this page decides whether the result qualifies.

**Status:** the protocol and the harness exist; no qualification run has been made, and nothing here is a qualification result. CS-RG stays in progress and not qualified until a run under this protocol passes and its evidence is reviewed.
**Status:** frozen with its harness ([#97](https://github.com/novelKR/CodeSpace/pull/97)) before the first qualification run. The runs on the candidate `ca306ee` passed, and CS-RG is qualified for that combination; the [qualification report](cs-rg-qualification-report.md) has the results and the evidence. The [regression command](#regressions) was corrected after the runs, as the report's [amendments](cs-rg-qualification-report.md#report-amendments) record; nothing else changed.

<a id="candidate"></a>

Expand Down Expand Up @@ -200,7 +200,7 @@ The harness checks DevGuard's record, never CodeSpace's own view. For each gover

## Regression and parity

On the candidate, on the qualification host in the minimal environment, `python3 scripts/validate-upstream.py all macos-core macos-fork-race` runs every stage, with the DevGuard test binaries required in the stages that use them; Linux is shown by CI on the candidate head, whose `dependencies` stage checks the dependency graph with the `devguard` feature on and off. A regression in any stage fails the qualification.
On the candidate, on the qualification host in the minimal environment, two invocations run every stage, with the DevGuard test binaries required in the stages that use them: `python3 scripts/validate-upstream.py all`, then `python3 scripts/validate-upstream.py macos-core macos-fork-race`. `all` runs every stage but the macOS-only ones and replaces any other stage named with it, so those need their own invocation. Linux is shown by CI on the candidate head, whose `dependencies` stage checks the dependency graph with the `devguard` feature on and off. A regression in any stage fails the qualification.

<a id="evidence"></a>

Expand Down
29 changes: 26 additions & 3 deletions docs/devguard-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

# DevGuard integration roadmap

> **Status: suspended as an implementation directive.** The CS-RG work order, the planned consumer boundary and the design revision 1 references on this page must not be implemented as described; current status and prerequisites are unaffected. This is pending the CS-RG integration-boundary revalidation, an owner-directed review of the CodeSpace integration plan; it is not a work unit. No replacement architecture has been approved; the owner decides after reviewing its results. This notice suspends directives only and relaxes no safety requirement. The text below is retained unchanged for historical traceability, except the current status, the [status-only connection](#devguard-status-connection) of CSRG-U1, which the owner approved on 2026-10-02 outside this suspension, the [execution-owner registration](#devguard-owner-registration) of CSRG-U2, which the owner directed on 2026-10-03, the [admission and pre-spawn preparation](#devguard-admission) of CSRG-U3, which the owner directed on 2026-10-07, the [managed launch](#devguard-launch) of CSRG-U4, which the owner directed on 2026-10-08, and the [lifecycle after launch](#devguard-lifecycle) of CSRG-U5, which the owner directed on 2026-10-09.
> **Status: suspended as an implementation directive.** The CS-RG work order, the planned consumer boundary and the design revision 1 references on this page must not be implemented as described; current status and prerequisites are unaffected. This is pending the CS-RG integration-boundary revalidation, an owner-directed review of the CodeSpace integration plan; it is not a work unit. No replacement architecture has been approved; the owner decides after reviewing its results. This notice suspends directives only and relaxes no safety requirement. The text below is retained unchanged for historical traceability, except the current status, the [status-only connection](#devguard-status-connection) of CSRG-U1, which the owner approved on 2026-10-02 outside this suspension, the [execution-owner registration](#devguard-owner-registration) of CSRG-U2, which the owner directed on 2026-10-03, the [admission and pre-spawn preparation](#devguard-admission) of CSRG-U3, which the owner directed on 2026-10-07, the [managed launch](#devguard-launch) of CSRG-U4, which the owner directed on 2026-10-08, the [lifecycle after launch](#devguard-lifecycle) of CSRG-U5, which the owner directed on 2026-10-09, and the [qualification and adoption](#devguard-qualification) of CSRG-U6, which the owner directed on 2026-10-12.

[English](devguard-integration.md) | [한국어](ko/devguard-integration.md)

[DevGuard](https://github.com/novelKR/DevGuard) is an independent resource authority for development workloads, licensed under Apache-2.0 like CodeSpace. Its approved integration path adds a shared admission and accounting layer while CodeSpace keeps process ownership, PTY, input/output, permissions, approval holds and workspace coordination.

**Current status:** DevGuard has completed DG-1 in its independent repository ([`395315d`](https://github.com/novelKR/DevGuard/tree/395315d34b5d458ea1774446727f0cb14bd8a120), [milestone ledger](https://github.com/novelKR/DevGuard/blob/395315d34b5d458ea1774446727f0cb14bd8a120/milestones.json)). On top of the DG-0 contracts it provides native macOS host evidence, an authenticated daemon installed as the current user's LaunchAgent, the fenced launch helper and reconciliation, the `devguard` command-line owner with Cargo adapters, parent leases for candidate tests, and upgrade and repair. Its macOS SLO is qualified for release `0.1.0-5daee5d-b3fa569e` (a release ID, not a Git tag) on the measured host and policy; Linux enforcement is not qualified. CodeSpace consumption (CS-RG) is in progress and not qualified. CSRG-U1 added an opt-in, status-only connection: a gateway built with the `devguard` feature and started with `--devguard status` reports DevGuard's status in `workspace_info`, through DevGuard's client pinned at [`6e7e065`](upstream-lock.md#devguard-client-pin). With CSRG-U2, the process that owns CodeSpace's executions registers itself with DevGuard (`--devguard register`), and a workspace's `resources` setting can require resource participation. With CSRG-U3, that owner takes a process slot and has DevGuard admit each such execution before anything is created. With CSRG-U4 and a configured launch helper (`--devguard-launch-helper`), it then launches the execution once through DevGuard's launch helper, which DevGuard authorizes after binding and policing its scope; without a helper it cancels the unstarted attempt and refuses the execution. Nothing runs without DevGuard. With CSRG-U5, each process has one reaper; DevGuard observes a governed execution's scope before its root is reaped, on a pipe through CodeSpace's own reaper and on a PTY through the pinned Codex PTY's waiter with the [recorded patch](upstream-lock.md#codex-downstream-patch); killing a governed process also terminates its scope; and an approval whose governed execution provably never started can be resumed again. Qualification is CSRG-U6: its protocol and harness are in [CS-RG qualification](cs-rg-qualification.md), and nothing is qualified yet. The qualified release remains a candidate for execution, not a selected pin; the client pin is a source pin of the client crates.
**Current status:** DevGuard has completed DG-1 in its independent repository ([`395315d`](https://github.com/novelKR/DevGuard/tree/395315d34b5d458ea1774446727f0cb14bd8a120), [milestone ledger](https://github.com/novelKR/DevGuard/blob/395315d34b5d458ea1774446727f0cb14bd8a120/milestones.json)). On top of the DG-0 contracts it provides native macOS host evidence, an authenticated daemon installed as the current user's LaunchAgent, the fenced launch helper and reconciliation, the `devguard` command-line owner with Cargo adapters, parent leases for candidate tests, and upgrade and repair. Its macOS SLO is qualified for release `0.1.0-6e7e065-94d85365` (a release ID, not a Git tag), built from the client pin's commit and measured on 2026-10-13 on the measured host under the policy that includes CodeSpace's `codespace` consumer ([DevGuard #34](https://github.com/novelKR/DevGuard/pull/34)); Linux enforcement is not qualified. CodeSpace consumption (CS-RG) is qualified on macOS for one exact combination. CSRG-U1 added an opt-in, status-only connection: a gateway built with the `devguard` feature and started with `--devguard status` reports DevGuard's status in `workspace_info`, through DevGuard's client pinned at [`6e7e065`](upstream-lock.md#devguard-client-pin). With CSRG-U2, the process that owns CodeSpace's executions registers itself with DevGuard (`--devguard register`), and a workspace's `resources` setting can require resource participation. With CSRG-U3, that owner takes a process slot and has DevGuard admit each such execution before anything is created. With CSRG-U4 and a configured launch helper (`--devguard-launch-helper`), it then launches the execution once through DevGuard's launch helper, which DevGuard authorizes after binding and policing its scope; without a helper it cancels the unstarted attempt and refuses the execution. Nothing runs without DevGuard. With CSRG-U5, each process has one reaper; DevGuard observes a governed execution's scope before its root is reaped, on a pipe through CodeSpace's own reaper and on a PTY through the pinned Codex PTY's waiter with the [recorded patch](upstream-lock.md#codex-downstream-patch); killing a governed process also terminates its scope; and an approval whose governed execution provably never started can be resumed again. CSRG-U6 qualified one exact combination under the [CS-RG qualification protocol](cs-rg-qualification.md), in the runner modes `in-process` and `uds` with `--runtime-bin`, each with pipe and PTY executions, as the [qualification report](cs-rg-qualification-report.md) records ([qualification and adoption](#devguard-qualification)); Linux `required` stays unsupported until DG-LINUX. The qualified release remains a candidate for execution, not a selected pin; the client pin is a source pin of the client crates.

DevGuard [design revision 1](https://github.com/novelKR/DevGuard/blob/d4981b4c241cff42687f5c2c681b583c7847776e/docs/design-revision-1.md), merged in [DevGuard PR #8](https://github.com/novelKR/DevGuard/pull/8) as `d4981b4c241cff42687f5c2c681b583c7847776e`, revised the CS-RG execution layer and work order. It changes plans and design decisions that bind later implementation. It does not change current CodeSpace behavior or any implementation or qualification status.

Expand Down Expand Up @@ -250,7 +250,30 @@ CSRG-U5 completes a governed execution's lifecycle after its launch: who reaps i

**No replay.** Without proof that the first attempt never started, nothing is started again: not after a transcript that does not settle in time, a lost or unknown `BeginLaunch` answer, a worker lost after it took a launch, a cancelled request, a root reaped before any observation, an authority restart or a repeated resume. After an authority restart DevGuard no longer knows a running scope: the process stays CodeSpace's, the owner registers again for new work, and the attempt stays charged as suspect after the process ends.

**Supported** as for CSRG-U4. **Not claimed:** CS-RG qualification (CSRG-U6) and Linux before DG-LINUX.
**Supported** as for CSRG-U4, and qualified for the combination of [CSRG-U6](#devguard-qualification). **Not claimed:** Linux before DG-LINUX.

<a id="devguard-qualification"></a>

## Qualification and adoption (CSRG-U6)

CSRG-U6 qualified CS-RG under the [CS-RG qualification protocol](cs-rg-qualification.md), on the qualification host, for one exact combination: CodeSpace `ca306ee`, or a later commit with the same code tree; DevGuard's client at `6e7e065`; the installed release `0.1.0-6e7e065-94d85365`, with DG-1's qualification under the same policy; Codex `6b9826e` with the recorded patch; and Rust 1.95.0. The [qualification report](cs-rg-qualification-report.md) records the combination, every result and the evidence.

**Supported.** On macOS with that release: participation `required` in the runner modes `in-process` and `uds` with `--runtime-bin`, each with pipe and PTY executions, and `off` and `required` workspaces in one gateway. Unsupported, and refused before anything runs: `uds` with `--runner-socket`, `required` under `--devguard status` or without the `devguard` feature, and Linux before DG-LINUX. Without a usable launch helper a governed execution is refused `MANAGED_LAUNCH_UNAVAILABLE`. Participation `off` keeps its existing behavior on every platform, as the [legacy `off` path decision](cs-rg-qualification.md#legacy-off-path) records.

**Adoption.** The claim holds for the qualified combination only: a different release, policy, host, toolchain or code tree is a new candidate that needs its own runs. To use it:

1. Run the qualified DevGuard release as the current user's service, with a consumer for CodeSpace provisioned as a control service: role `control_service`, a generation, a private credential file, one instance and a static control reservation, qualified at 150 mCPU, 512 MiB and 40 tasks. DevGuard reads its policy only when it starts, and a policy change needs DG-1's measurement again.
2. Build `codespace-mcp` with `-p codespace-server --features devguard`, and for `uds` the worker with `--features devguard`, from a commit with the qualified code tree.
3. Start the gateway with `--devguard register`, the consumer settings of the [status-only connection](#devguard-status-connection) and `--devguard-launch-helper` set to the release's `devguard-launch`, in `in-process` mode or in `uds` mode with `--runtime-bin`.
4. Give each workspace whose executions must be governed `"resources": {"participation": "required"}` and a `request` that fits the work capacity. `workspace_info.resource_authority` reports the owner `registered` and `governs_execution: true` once the owner is registered and has a launch helper.
5. Start or restart DevGuard's service while memory pressure is normal: a service that starts under memory warning admits nothing until memory has been normal for 30 seconds ([DevGuard operations](https://github.com/novelKR/DevGuard/blob/c077c747972cebca828a903968868f5713ce5664/docs/operations.md#available-commands)).

**Rollback.** None of these steps runs a governed workspace's execution without DevGuard, and none replays or forgets uncertain work.

- **New admissions.** Restart the gateway without `--devguard register`, or without the launch helper. `required` workspaces then refuse new executions with `RESOURCE_POLICY_UNSUPPORTED` or `MANAGED_LAUNCH_UNAVAILABLE`; they never fall back to `off`. Turning a workspace to `off` is a separate, explicit edit of the registry.
- **Running work.** The gateway's shutdown ends the executions it or its worker owns, governed ones included, and DevGuard releases their attempts once it observes their scopes' end. While DevGuard is stopped, stalled or rolled back, running governed processes stay CodeSpace's: status, output, stdin, resize, termination and timeouts never ask DevGuard, and new governed executions are refused. An attempt that DevGuard can no longer settle stays charged as Suspect, and CodeSpace never launches it again.
- **DevGuard.** Its journal is kept. Its own rollback is `devguard repair --use last-known-good` or an upgrade to an earlier release ([DevGuard operations](https://github.com/novelKR/DevGuard/blob/c077c747972cebca828a903968868f5713ce5664/docs/operations.md#compatibility-checks-and-rollback)), and the `codespace` consumer is removed only after its instances are retired. Each of these leaves the qualified combination.
- **Records.** DevGuard's milestone ledger records what was qualified. A rollback is recorded there, not hidden.

## CS-RG work order

Expand Down
Loading
Loading