sortie-dogs 0.9.12 → 0.10.0

package/README.md

@@ -1,87 +1,172 @@
 # Sortie-dogs
 
-**Add a bounded, cost-aware execution loop to OpenCode without taking OpenCode over.**
+**A goal-preserving, adaptive execution harness for OpenCode
+that optimizes cost, time, and proof without taking your setup over.**
 
-Sortie-dogs is an opt-in overlay, not a replacement. It stays passive until you
-invoke `/sortie` or select `dog-coordinator`. Standard OpenCode agents and
-unrelated sessions remain available and unchanged.
+Use OpenCode normally. Invoke Sortie only when you want
+scoped implementation, validation, review, and model routing.
 
-> **Project status: Beta.** v0.9.x is under active stabilization. Runtime
-> behavior, configuration, and runtime assets may still change before 1.0.
+### Four design pillars
 
-[![npm](https://img.shields.io/npm/v/sortie-dogs)](https://www.npmjs.com/package/sortie-dogs)
-[![license](https://img.shields.io/npm/l/sortie-dogs)](LICENSE)
-[![Node.js](https://img.shields.io/node/v/sortie-dogs)](https://www.npmjs.com/package/sortie-dogs)
+- **Goal invariance** — Accepted outcomes and proof requirements survive delegation, continuation, and remediation. A child agent cannot silently weaken the job to make it easier to finish.
+- **Adaptive execution** — Small work stays small. Parallel workers, stronger models, and independent review are added only when task shape and risk justify them.
+- **Coexistence and portability** — Sortie activates only when invited, preserves normal OpenCode agents and settings, and keeps project-local setup as the default.
+- **Cost, time, and proof** — The objective is not maximum agent count. It is the lowest practical cost and effort for a verified outcome, with explicit evidence when work does or does not pass.
 
-![Sortie-dogs coordinating a bounded implementation workflow](https://raw.githubusercontent.com/zufall-upon/Sortie-dogs/main/docs/assets/sortie-workflow.gif)
+### Direction for v0.10.x
 
-Sortie-dogs turns selected work into a scoped plan, optional evidence gathering,
-bounded implementation, canonical validation, and evidence-backed completion.
+The v0.10.x line is being developed around an **Astra operator / Terra dogs** split. Astra is the
+top-level decision authority that protects the accepted goal, quality bar, escalation decisions,
+and final acceptance. Because Astra is expensive, it should do only the small amount of work that
+requires that level of judgment. Terra-based dogs handle most bounded planning, coordination, and
+execution. The intended result is Astra-level judgment with Terra-level operating cost.
+
+This is an architectural direction under active validation, not a demonstrated benchmark result.
+Goal and quality authority remain centralized; implementation volume does not.
+
+## Try it
 
 Requirements: Node.js 22.6 or newer, npm, and OpenCode.
+Start in your project directory. This block covers all four steps;
+the JSON belongs in the configuration file, and `/sortie` runs inside OpenCode.
+If the configuration already exists, add `sortie-dogs` to its `plugin` array
+while keeping existing entries and settings.
 
-Guides: [日本語](docs/guide-ja.md) · [简体中文](docs/guide-zh-CN.md) · [テスト実行](docs/testing.md) · [CLI testing](docs/cli-testing.md)
+```text
+1. Install — run in your terminal
+   npm install --save-dev sortie-dogs
+   npx sortie-dogs init .
+
+2. Add plugin — save or merge into .opencode/opencode.json
+   {
+     "plugin": ["sortie-dogs"]
+   }
+
+3. Restart OpenCode
 
-Release: [v0.9.12](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.9.12)
+4. Start a task — enter in OpenCode
+   /sortie <task>
+```
+
+Project-local setup is recommended. `init` installs runtime assets;
+the plugin entry enables the plugin, including model routing.
+See [configuration details](#configuration) for model selection and other setup options.
 
-## Provisional quality–cost position
+> **v0.10.x migration:** Give workflow instructions to **`dog-operator`**, not
+> `dog-coordinator`. `dog-operator` is the user-facing authority in v0.10.x;
+> coordinator roles are internal delegates and are not the task entry point.
 
-**Reference values, not a successful benchmark claim.** Quality and end-to-end completion
-problems remain. The latest completed qualification attempt ended at `IN_PROGRESS`, so its official
-verifier was not run. Further benchmarks are frozen while completion defects are repaired.
+> **Project status: Beta.** v0.10.x is under active stabilization. Runtime
+> behavior, configuration, and runtime assets may still change before 1.0.
 
-The last complete measured **Bare OpenCode vs Sortie** pair below used one frozen task,
-`datacurve/anko-typed-variable-bindings`, on 2026-09-10. It used Sortie **v0.9.5**, not the
-current release. Both candidates failed the official verifier.
+[![npm](https://img.shields.io/npm/v/sortie-dogs)](https://www.npmjs.com/package/sortie-dogs)
+[![license](https://img.shields.io/npm/l/sortie-dogs)](LICENSE)
+[![Node.js](https://img.shields.io/node/v/sortie-dogs)](https://www.npmjs.com/package/sortie-dogs)
 
-| Metric · one task, one trial per arm | Bare OpenCode | Sortie v0.9.5 |
-| --- | ---: | ---: |
-| Verified PASS | 0/1 | 0/1 |
-| Task-check completion · F2P | 55.6% · 5/9 | 88.9% · 8/9 |
-| Retained checks · P2P | 94/94 | 93/94 |
-| Estimated API-equivalent total cost | $5.42 | $1.46 |
-| Median agent wall · n=1 | 28.7 min | 10.0 min |
-| Premium-model token share · Sol | 100% | 20.1% |
+![Sortie-dogs coordinating a bounded implementation workflow](https://raw.githubusercontent.com/zufall-upon/Sortie-dogs/main/docs/assets/sortie-workflow.gif)
 
-Later Sortie-only evidence is weaker: the v0.9.9 recovery candidate passed **5/9** task
-checks with **0/1 Verified PASS**; `0.9.11-bench.2` did not reach a gradeable completion.
-Those attempts are not pooled into the historical pair above.
+Sortie-dogs turns selected work into a scoped plan, optional evidence gathering,
+bounded implementation, canonical validation, and evidence-backed completion.
 
-![Historical quality–cost reference: Bare at $5.42 and 55.6% task-check completion; Sortie v0.9.5 at $1.46 and 88.9%. Neither achieved Verified PASS.](docs/assets/quality-cost-reference.svg)
+Guides: [日本語](docs/guide-ja.md) · [简体中文](docs/guide-zh-CN.md) · [テスト実行](docs/testing.md) · [CLI testing](docs/cli-testing.md)
 
-The goal is **higher OpenCode task success with selective use of premium models**.
-These reference observations do not yet establish that success-rate claim: Sortie missed
-one task check and regressed one retained check. Codex, Pi, and Oh My OpenCode belong to
-separate methodologies and are not assigned comparable positions on this chart.
+Release: [v0.10.0](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.10.0)
+
+## Latest local benchmark case study
+
+**Completion-filtered reference values, not a successful benchmark or leaderboard claim.**
+On 2026-09-14, Bare OpenCode and Sortie-dogs v0.9.12 each collected three completed runs of the
+same frozen task, `datacurve/anko-typed-variable-bindings`. Bare needed three attempts; Sortie
+needed five because two attempts returned `INTERRUPTED`. These were separate local trial batches,
+not three matched pairs. Docker and Runta were intentionally unused.
+
+Run configuration was fixed per product configuration:
+
+- **Bare OpenCode:** standard `build` agent, `openai/gpt-5.6-sol` / `high`, with no Sortie plugin
+  or Sortie runtime assets in the effective configuration.
+- **Sortie v0.9.12:** `dog-coordinator` on `openai/gpt-5.6-terra` / `high`; observed implementation
+  children on `openai/gpt-5.6-sol` / `medium`, with the pinned Sortie package and runtime assets.
+  No Luna, Astra, or Opus messages were observed in these trials.
+
+| Metric · one frozen task | Bare OpenCode | Sortie v0.9.12 | Sortie v0.10.0 clean qualification |
+| --- | ---: | ---: | ---: |
+| Attempts needed | 3 | 5 | 1 |
+| Completed runs compared | 3 | 3 | 1 |
+| Verified PASS | 0/3 | 0/3 | 0/1 |
+| Task checks · F2P | 11.1% · 3/27 | 85.2% · 23/27 | 88.9% · 8/9 |
+| Retained checks · P2P | 282/282 | 282/282 | 94/94 |
+| Median agent wall | 24.5 min | 25.7 min | 29.9 min · n=1 |
+| Median model steps | 43 | 39 | 33 · CLI stream only |
+| Implementation child sessions · total | 0 | 13 | 4 |
+| Estimated API-equivalent cost · median completed run | $3.53 | $2.85 | **$3.94** · n=1 |
+| Estimated cost · completed runs | $10.69 | $9.74 | **$3.94** |
+| Additional interrupted-attempt cost | $0 | $6.20 | $0 |
+| Total cost to acquire completed runs | $10.69 | $15.94 | **$3.94** |
+
+All three Bare runs passed 1/9 task checks. The three completed Sortie runs passed 7/9, 8/9,
+and 8/9. Every compared candidate retained 94/94 prior checks, but every official verifier still
+returned reward 0. The two interrupted Sortie attempts are excluded from completed-run quality,
+time, and cost aggregates; their attempt count and estimated cost remain visible above.
+
+The v0.10 value is a standalone qualification-only reference, not a fourth matched run or a
+FrontierHarness leaderboard result. It used no fresh Bare control and a localized Docker-free
+verifier. Its estimated API-equivalent cost is **$3.94**: $3.26 from Sol and $0.68 from Terra,
+calculated from the root and descendant session tokens with 100% pricing coverage. A preceding
+debug run returned reward 1 (F2P 9/9, P2P 94/94), so that pass is not presented as reproducible.
+
+![Latest local case study: Bare completed 11.1 percent of task checks at a median estimated API-equivalent cost of $3.53; Sortie completed 85.2 percent at $2.85. Sortie needed five attempts and $15.94 to collect three completed runs. Neither configuration achieved a Verified PASS.](docs/assets/quality-cost-reference.svg)
+
+Cost uses exported root and child session tokens, grouped by the model that produced each message,
+with a fixed standard short-context rate schedule. Completed-run cost shows execution efficiency;
+total acquisition cost includes the two interrupted Sortie attempts and shows reliability overhead.
+These are API-equivalent estimates, not invoices.
+
+The product objective is **more verified outcomes per unit of cost and time without weakening the
+accepted goal**. This small, single-task local case study does not establish that claim, isolate
+orchestration from model quality, or establish a cost advantage. Codex, Pi, and Oh My OpenCode use
+separate methodologies and are not assigned quantitative positions from these observations.
 
 [Definitions, frozen inputs, current failure status, and limitations](docs/benchmark-reference.md)
 · [Machine-readable reference values](docs/benchmarks/provisional-reference.json)
 
-## Why Sortie-dogs?
+## How the design is enforced
 
-### Invisible until invited
+The four pillars above become operational constraints rather than a second set
+of product promises:
 
-Use normal OpenCode normally. Sortie activates only for `/sortie` or
-`dog-coordinator`; it does not disable or replace OpenCode's standard agents.
+### 1. Keep the goal invariant
 
-### Spend strong models only where they matter
+Sortie turns the requested outcome into explicit acceptance criteria and carries
+them through planning, delegation, continuation, validation, and remediation.
+Workers receive bounded units, but unit boundaries do not redefine success. A
+child result, local process limit, or convenient partial implementation cannot
+silently remove an unmet criterion. Only an explicit user-authorized revision
+changes the accepted goal.
 
-Lower-cost models handle bounded retrieval and parallel volume work. Stronger
-models are reserved for implementation, escalation, and independent review.
+### 2. Adapt execution to the work
 
-### Return with proof
+Small changes can use one worker and targeted validation without paying for Scout,
+parallel coordination, independent review, or a full-suite run. Larger work can be
+split into bounded units; safely independent units may use a Luna fabric DAG.
+Higher-risk candidates add stronger implementation or independent review. The
+harness expands because the task requires it, not because more agents look better.
 
-Writes stay scoped, and completion requires validation evidence. Every completed
-run can return a concise Speed / Cost / Proof debrief.
+### 3. Coexist with OpenCode
+
+Use normal OpenCode normally. Sortie activates only for `/sortie` or
+`dog-coordinator`; it does not disable or replace standard agents. Project-local
+installation is the default, existing settings remain authoritative, and unknown
+user-owned runtime files are preserved. The same package can move with a project
+without requiring users to surrender their global OpenCode environment.
 
-### Use only as much harness as the task needs
+### 4. Optimize cost, time, and proof together
 
-Small changes can skip Scout and independent review when one worker and targeted
-validation are sufficient. Larger work can be decomposed into multiple units;
-units that are safely independent can use a Luna fabric DAG for bounded parallel
-execution. Higher-risk candidates add independent review, while full-suite and
-package verification are reserved for release work. Not every task pays the
-cost of the heaviest workflow.
+Lower-cost models handle bounded retrieval and parallel volume work; stronger
+models are reserved for implementation, escalation, and independent review where
+their capability can change the outcome. Writes remain scoped, and completion
+requires validation evidence rather than agent confidence. The returned Speed /
+Cost / Proof debrief makes incomplete and failed outcomes visible too. Agent count
+is an implementation detail, not the optimization target.
 
 ## Designed to coexist with OpenCode
 
@@ -99,17 +184,11 @@ Sortie-dogs adds a workflow to your existing setup rather than replacing it.
 
 Use OpenCode normally. Invoke the pack only when you want it.
 
-## Quick start
+## Configuration
 
-Install the public npm package in the project and generate the project-local
-OpenCode runtime files:
-
-```sh
-npm install --save-dev sortie-dogs
-npx sortie-dogs init .
-```
-
-This is the recommended setup. Runtime assets stay project-local.
+The [Try it](#try-it) steps above are the recommended project-local installation.
+Runtime assets stay with the project. This section covers plugin behavior, model
+selection, and alternative loading after installation.
 
 Installing the runtime assets does not load the plugin, and without the plugin
 every role runs on whichever model the caller happened to use. Add the package
@@ -130,6 +209,10 @@ as `.opencode/sortie-dogs.json`:
 
 ```json
 {
+  "dedicatedWorkerModel": {
+    "model": "openai/gpt-5.6-sol",
+    "variant": "medium"
+  },
   "modelRouting": {
     "dog-coordinator": {
       "preferred": { "model": "provider/model" }
@@ -292,18 +375,18 @@ dog-coordinator: completion evidence accepted
 
 ## The workflow
 
-1. **Brief and plan** — `dog-coordinator` turns the request into acceptance
-   criteria, a write manifest, and validation requirements.
+1. **Freeze the goal and plan** — `dog-coordinator` turns the request into invariant
+   acceptance criteria, a write manifest, and validation requirements.
 2. **Optional scout** — one bounded, read-only investigation runs only for a
    concrete pre-worker evidence gap.
-3. **Dedicated worker** — the dedicated worker implements only the approved
-   manifest and also owns scoped remediation or blocker resolution.
+3. **Adaptive execution** — the coordinator selects one worker or bounded parallel
+   units according to task shape; workers implement only their approved manifests.
 4. **Canonical validation** — the declared test or build command must produce
    acceptable evidence.
 5. **Risk-based review** — high-risk candidates receive independent review;
    low-risk candidates can skip that extra pass after validation.
-6. **Coordinator completion** — only the coordinator closes the loop and owns
-   any commit after manifest, validation, review, and evidence gates pass.
+6. **Goal-level completion** — only the coordinator closes the loop after every
+   accepted criterion has manifest, validation, review, and evidence coverage.
 7. **Bounded continuation** — restart recovery and compaction handoffs preserve
    progress; repeated batches remain bounded rather than becoming endless
    delegation.
@@ -413,6 +496,10 @@ model you can actually serve.
 
 ```json
 {
+  "dedicatedWorkerModel": {
+    "model": "openai/gpt-5.6-sol",
+    "variant": "medium"
+  },
   "modelRouting": {
     "dog-coordinator": {
       "preferred": { "model": "openai/gpt-5.6-luna", "variant": "max" }
@@ -438,6 +525,10 @@ model you can actually serve.
 }
 ```
 
+`dog-worker` intentionally has no `modelRouting` entry. It uses
+`dedicatedWorkerModel`, shared with the other stable serial implementation roles.
+`dog-luna-worker` remains a separate fixed fabric route.
+
 Save project configuration as `.opencode/sortie-dogs.json`. `modelCatalog`
 declares provider models and named variants that are actually available;
 Sortie-dogs does not invent, probe, or translate variants. The built-in catalog

package/dist/asset-version.d.ts

@@ -3,4 +3,5 @@
  * installed project marker without importing every asset body.
  */
 export declare const RUNTIME_ASSET_VERSION = "0.3.89-completion-proof-v1";
-export type RuntimeAssetVersion = typeof RUNTIME_ASSET_VERSION;
+export declare const V010_RUNTIME_ASSET_VERSION = "0.10.0-v0912-language4-cost-rpt10-compaction-ref1-proposal1-review-remediation1-surface3";
+export type RuntimeAssetVersion = typeof RUNTIME_ASSET_VERSION | typeof V010_RUNTIME_ASSET_VERSION;

package/dist/asset-version.js

@@ -3,3 +3,4 @@
  * installed project marker without importing every asset body.
  */
 export const RUNTIME_ASSET_VERSION = "0.3.89-completion-proof-v1";
+export const V010_RUNTIME_ASSET_VERSION = "0.10.0-v0912-language4-cost-rpt10-compaction-ref1-proposal1-review-remediation1-surface3";

package/dist/cli/main.js

@@ -29,8 +29,9 @@ const USAGE = `Usage: sortie-dogs lint <handoff.json> [<handoff.json> ...]
   [--changed-paths-from <file|->]
   [--changed-path <path> ...]
   [--format text|json] [--quiet] [--strict]`;
-const INIT_USAGE = `Usage: sortie-dogs init [project-root]
-       sortie-dogs init --global`;
+const INIT_USAGE = `Usage: sortie-dogs init [project-root] [--profile stable|v010]
+       sortie-dogs init --global [--profile stable|v010]
+This beta package defaults to the v010 profile.`;
 class InputFailure extends Error {
     safeMessage;
     constructor(safeMessage) {
@@ -229,16 +230,21 @@ export async function run(argv) {
             process.stdout.write(`${INIT_USAGE}\n`);
             return 0;
         }
-        const global = argv[1] === "--global";
-        if (argv.length > 2 || (argv[1]?.startsWith("-") === true && !global)) {
+        const initArgs = [...argv.slice(1)];
+        const profileIndex = initArgs.indexOf("--profile");
+        const profile = profileIndex < 0 ? "v010" : initArgs[profileIndex + 1];
+        if (profileIndex >= 0)
+            initArgs.splice(profileIndex, 2);
+        const global = initArgs[0] === "--global";
+        if ((profile !== "stable" && profile !== "v010") || initArgs.length > 1 || (initArgs[0]?.startsWith("-") === true && !global)) {
             process.stderr.write(`${INIT_USAGE}\n`);
             return 2;
         }
         try {
             const target = global ? await initializer.resolveGlobalConfigRoot() : undefined;
             const initialized = global
-                ? await initializer.initializeGlobal(target)
-                : await initializer.initializeProject(argv[1]);
+                ? await initializer.initializeGlobal(target, profile)
+                : await initializer.initializeProject(initArgs[0], profile);
             if (global) {
                 process.stdout.write(initialized.status === "installed"
                     ? `Initialized Sortie-dogs ${initialized.version} globally at ${target}.\n`

package/dist/core/consultation.d.ts

@@ -1,4 +1,5 @@
 export declare const CONSULTATION_CAPABILITIES: readonly ["strategy", "sourceReview"];
+export declare const SOURCE_REVIEW_PHASES: readonly ["initial", "verification", "final"];
 export type ConsultationCapability = typeof CONSULTATION_CAPABILITIES[number];
 export declare const CONSULTATION_ROLE_POLICY: Readonly<{
     readonly strategy: "dog-advisor";

package/dist/core/consultation.js

@@ -1,4 +1,5 @@
 export const CONSULTATION_CAPABILITIES = ["strategy", "sourceReview"];
+export const SOURCE_REVIEW_PHASES = ["initial", "verification", "final"];
 export const CONSULTATION_ROLE_POLICY = Object.freeze({
     strategy: "dog-advisor",
     sourceReview: "dog-reviewer",

package/dist/core/contract-limits.d.ts

@@ -0,0 +1,8 @@
+/** Common text bounds shared by handoff, manifest and goal evidence validation. */
+export declare const CONTRACT_TEXT_LIMITS: Readonly<{
+    title: 160;
+    objective: 2000;
+    statement: 1000;
+    command: 1000;
+    path: 512;
+}>;

package/dist/core/contract-limits.js

@@ -0,0 +1,2 @@
+/** Common text bounds shared by handoff, manifest and goal evidence validation. */
+export const CONTRACT_TEXT_LIMITS = Object.freeze({ title: 160, objective: 2000, statement: 1000, command: 1000, path: 512 });

package/dist/core/git-managed-state.d.ts

@@ -0,0 +1,8 @@
+import { type RuntimeProfile } from "./runtime-profile.js";
+/**
+ * Keep only the plugin-owned profile state invisible to normal Git status.
+ * The repository-local exclude file is Git metadata, not a source-tree policy.
+ * Callers invoke this only for an explicitly requested Git workflow; an
+ * enclosing repository is not the source root and therefore fails closed.
+ */
+export declare function ensureGitManagedStateExcluded(sourceRoot: string, profile: RuntimeProfile, executable?: string): Promise<boolean>;

package/dist/core/git-managed-state.js

@@ -0,0 +1,101 @@
+import { execFile } from "node:child_process";
+import { open, lstat, mkdir, realpath } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { RUNTIME_PROFILES } from "./runtime-profile.js";
+const samePath = (left, right) => process.platform === "win32"
+    ? resolve(left).toLowerCase() === resolve(right).toLowerCase()
+    : resolve(left) === resolve(right);
+function inside(root, candidate) {
+    const path = relative(root, candidate);
+    return path === "" || (path !== ".." && !path.startsWith(`..${sep}`));
+}
+async function git(root, executable, args) {
+    try {
+        return (await promisify(execFile)(executable, [...args], {
+            cwd: root, encoding: "utf8", timeout: 30_000, windowsHide: true, maxBuffer: 1024 * 1024,
+        })).stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+async function safeDirectory(path) {
+    const metadata = await lstat(path);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink() || !samePath(await realpath(path), path)) {
+        throw new Error("operator-git-managed-state-path-unsafe");
+    }
+}
+/**
+ * Keep only the plugin-owned profile state invisible to normal Git status.
+ * The repository-local exclude file is Git metadata, not a source-tree policy.
+ * Callers invoke this only for an explicitly requested Git workflow; an
+ * enclosing repository is not the source root and therefore fails closed.
+ */
+export async function ensureGitManagedStateExcluded(sourceRoot, profile, executable = "git") {
+    const root = resolve(sourceRoot);
+    const known = Object.values(RUNTIME_PROFILES).some(candidate => candidate.id === profile.id && candidate.stateDirectory === profile.stateDirectory);
+    if (!known || !/^\.[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(profile.stateDirectory)) {
+        throw new Error("operator-git-managed-state-profile-unknown");
+    }
+    const top = await git(root, executable, ["rev-parse", "--show-toplevel"]);
+    if (top === undefined)
+        return false;
+    if (!samePath(top, root))
+        throw new Error("operator-git-managed-state-root-mismatch");
+    const commonValue = await git(root, executable, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+    const excludeValue = await git(root, executable, ["rev-parse", "--path-format=absolute", "--git-path", "info/exclude"]);
+    if (commonValue === undefined || excludeValue === undefined) {
+        throw new Error("operator-git-managed-state-metadata-unavailable");
+    }
+    const common = resolve(root, commonValue);
+    const exclude = resolve(root, excludeValue);
+    if (!inside(common, exclude) || !samePath(exclude, join(common, "info", "exclude"))) {
+        throw new Error("operator-git-managed-state-path-unsafe");
+    }
+    await safeDirectory(common);
+    const info = dirname(exclude);
+    try {
+        await mkdir(info);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    await safeDirectory(info);
+    const pattern = `/${profile.stateDirectory}/`;
+    try {
+        const existing = await lstat(exclude);
+        if (!existing.isFile() || existing.isSymbolicLink())
+            throw new Error("operator-git-managed-state-path-unsafe");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    let handle;
+    try {
+        handle = await open(exclude, "a+");
+    }
+    catch (error) {
+        throw new Error("operator-git-managed-state-exclude-open-failed", { cause: error });
+    }
+    try {
+        const pathMetadata = await lstat(exclude);
+        const fileMetadata = await handle.stat();
+        if (!pathMetadata.isFile() || pathMetadata.isSymbolicLink() || !fileMetadata.isFile() ||
+            !samePath(await realpath(exclude), exclude)) {
+            throw new Error("operator-git-managed-state-path-unsafe");
+        }
+        const source = await handle.readFile();
+        if (source.toString("utf8").split(/\r?\n/u).includes(pattern))
+            return true;
+        const newline = source.includes(Buffer.from("\r\n")) ? "\r\n" : "\n";
+        const prefix = source.length === 0 || source.at(-1) === 0x0a ? "" : newline;
+        await handle.writeFile(`${prefix}${pattern}${newline}`);
+        return true;
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/core/goal-bound.d.ts

@@ -83,6 +83,20 @@ export interface GoalTerminalReceipt {
 interface GoalEventBase {
     readonly at: string;
 }
+export interface GoalValidationRetryAuthorization {
+    readonly authority: "operator-repair-validation-retry";
+    readonly operator_run_id: string;
+    readonly unit_id: string;
+    readonly operator_generation: number;
+    readonly plan_hash: string;
+    readonly control_hash: string;
+    readonly goal_fingerprint: string;
+    readonly repair_fingerprint: string;
+}
+export interface GoalValidationReopen extends GoalValidationRetryAuthorization {
+    readonly prior_reservation_id: string;
+    readonly prior_operation_id: string;
+}
 export type GoalFlightEvent = (GoalEventBase & {
     readonly kind: "goal.accepted";
     readonly goal_id: string;
@@ -151,6 +165,12 @@ export type GoalFlightEvent = (GoalEventBase & {
     readonly evidence: readonly GoalEvidence[];
     readonly elapsed_ms: number | null;
     readonly cost_usd: number | null;
+}) | (GoalEventBase & {
+    readonly kind: "unit.evidence-reconciled";
+    readonly goal_id: string;
+    readonly unit_id: string;
+    readonly previous_receipt_id: string;
+    readonly evidence: readonly GoalEvidence[];
 }) | (GoalEventBase & {
     readonly kind: "validation.admission";
     readonly goal_id: string;
@@ -162,6 +182,7 @@ export type GoalFlightEvent = (GoalEventBase & {
     readonly reason: string;
     readonly consumed: number;
     readonly limit: number;
+    readonly reopen?: GoalValidationReopen;
 }) | (GoalEventBase & {
     readonly kind: "validation.settled";
     readonly goal_id: string;