audit-tools 0.51.7 → 0.51.10

package/dist/shared/io/frictionCapture.js

@@ -1,7 +1,7 @@
 import { join } from "node:path";
 import { hashContent } from "../hash.js";
 import { cp, readdir } from "node:fs/promises";
-import { readOptionalJsonFile } from "./json.js";
+import { isFileMissingError, readOptionalJsonFile } from "./json.js";
 import { discardOnSchemaVersionMismatch } from "./schemaVersion.js";
 /**
  * Tool-emitted end-of-run friction capture, single-sourced for BOTH orchestrators
@@ -133,19 +133,32 @@ export async function frictionCaptured(artifactsDir, runId) {
 }
 /**
  * Every per-run friction record filename under `<artifactsDir>/friction/`, sorted by
- * name — a stable, content-derived order, never `readdir` order. A missing friction
- * dir yields `[]` (nothing captured yet is not an error). Single-sourced here, where
- * the dir itself is owned, so every reader of the dir applies the same `.json` filter.
+ * name — a stable, content-derived order, never `readdir` order. Single-sourced here,
+ * where the dir itself is owned, so every reader of the dir applies the same `.json`
+ * filter.
+ *
+ * ERRNO-SPLIT: an ABSENT friction dir yields `[]` (nothing captured yet is not an
+ * error — the ordinary clean run); any OTHER readdir failure PROPAGATES. The two
+ * used to collapse into one `catch { return [] }`, which made a directory that
+ * exists but cannot be READ (ENOTDIR when the path is a file, EACCES, EPERM)
+ * indistinguishable from an empty one — and the audit promote walk compares this
+ * listing against what {@link archiveFrictionRecords} archived, so BOTH sides
+ * returned zero and the rm that follows destroyed the records with nothing gating
+ * it. Errno-blind, the CP-NODE-5 class at lower stakes. The throw is the refusal:
+ * a caller whose next act is a delete must treat it as "records may exist and were
+ * NOT archived", never as "there was nothing to archive".
  */
 export async function listFrictionRecordFilenames(artifactsDir) {
+    let entries;
     try {
-        return (await readdir(frictionCaptureDir(artifactsDir)))
-            .filter((name) => name.endsWith(".json"))
-            .sort();
+        entries = await readdir(frictionCaptureDir(artifactsDir));
     }
-    catch {
-        return [];
+    catch (error) {
+        if (isFileMissingError(error))
+            return [];
+        throw error;
     }
+    return entries.filter((name) => name.endsWith(".json")).sort();
 }
 /**
  * Archive every per-run friction record out of `<artifactsDir>/friction/` into
@@ -158,6 +171,14 @@ export async function listFrictionRecordFilenames(artifactsDir) {
  * rides along with the promoted deliverables. Best-effort per file: a failed
  * copy is reported through `warn` and never blocks completion (parity with the
  * promoted-findings copy).
+ *
+ * NOT best-effort about the LISTING: the walk starts from
+ * {@link listFrictionRecordFilenames}, so an UNLISTABLE dir throws out of here
+ * rather than degrading to "no records". That is the half a caller cannot
+ * recover from — `[]` reads as "nothing to archive" and licenses the delete that
+ * follows — so the refusal is raised where the errno is still visible. A caller
+ * that must complete at any cost catches it and reads it as a shortfall (see the
+ * audit promote walk's `friction Listing failed` leg).
  */
 export async function archiveFrictionRecords(params) {
     const copyFile = params.copyFile ?? cp;

package/dist/shared/io/frictionCapture.js.map

@@ -1 +1 @@
-{"version":3,"file":"frictionCapture.js","sourceRoot":"","sources":["../../../src/shared/io/frictionCapture.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"frictionCapture.js","sourceRoot":"","sources":["../../../src/shared/io/frictionCapture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,CAAC,MAAM,+BAA+B,GAAG,2BAA2B,CAAC;AAE3E,6EAA6E;AAC7E,MAAM,CAAC,MAAM,wBAAwB,GAAG,UAAU,CAAC;AA2FnD,kFAAkF;AAClF,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IACrD,OAAO,IAAI,CAAC,YAAY,EAAE,wBAAwB,CAAC,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAoB,EAAE,KAAa;IACrE,OAAO,IAAI,CAAC,kBAAkB,CAAC,YAAY,CAAC,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,iFAAiF;AACjF,MAAM,uBAAuB,GAAG,GAAG,CAAC;AACpC,2EAA2E;AAC3E,MAAM,2BAA2B,GAAG,EAAE,CAAC;AACvC,MAAM,qBAAqB,GAAG,6CAA6C,CAAC;AAE5E,SAAS,eAAe,CAAC,EAAU;IACjC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC;QAC3C,GAAG,IAAI,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,EAAE,KAAK,GAAG,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAC9C,GAAG,IAAI,EAAE,CAAC;YACV,SAAS;QACX,CAAC;QACD,GAAG,IAAI,eAAe,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IACD,6EAA6E;IAC7E,8EAA8E;IAC9E,+EAA+E;IAC/E,8DAA8D;IAC9D,IAAI,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,GAAG,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,8EAA8E;IAC9E,+EAA+E;IAC/E,IAAI,GAAG,CAAC,MAAM,GAAG,uBAAuB,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,EAAE;YAChC,MAAM,EAAE,2BAA2B;SACpC,CAAC,CAAC,WAAW,EAAE,CAAC;QACjB,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,uBAAuB,GAAG,CAAC,GAAG,2BAA2B,CAAC,GAAG,GAAG,GAAG,MAAM,CAAC;IAC/F,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,YAAoB,EACpB,KAAa;IAEb,gFAAgF;IAChF,+EAA+E;IAC/E,+EAA+E;IAC/E,4EAA4E;IAC5E,MAAM,QAAQ,GAAG,8BAA8B,CAC7C,MAAM,oBAAoB,CACxB,mBAAmB,CAAC,YAAY,EAAE,KAAK,CAAC,CACzC,EACD,+BAA+B,CAChC,CAAC;IACF,OAAO,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,YAAoB;IACpE,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC;IAC5D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,kBAAkB,CAAC,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACzC,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAM5C;IACC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC,CAAC;IAChF,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,MAAM,2BAA2B,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACrE,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9D,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CACF,qCAAqC,IAAI,OAAO,WAAW,IAAI;gBAC7D,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC3D,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/shared/io/schemaVersion.d.ts

@@ -5,9 +5,10 @@
  * State written by an older version of the tool is read back under the CURRENT
  * version's semantics. A reader that never compares the stamped version (spelled
  * `schema_version` on artifacts, `contract_version` on contracts — both are read
- * here) silently reinterprets old bytes as new-shape data. Stamping a version on
- * WRITE and not comparing it on READ is therefore not "versioned" at all — it is
- * an unchecked cast wearing a version field.
+ * here, at the top level or on the `payload` of a content-hash envelope) silently
+ * reinterprets old bytes as new-shape data. Stamping a version on WRITE and not
+ * comparing it on READ is therefore not "versioned" at all — it is an unchecked
+ * cast wearing a version field.
  *
  * There are exactly two correct policies, and which one applies is a property
  * of the STATE, not of the module:

package/dist/shared/io/schemaVersion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemaVersion.d.ts","sourceRoot":"","sources":["../../../src/shared/io/schemaVersion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;aAEjC,YAAY,EAAE,MAAM;aACpB,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;gBAFd,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CASjC;AAoBD;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,SAAS,MAAM,EAC7D,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI,EAC3B,QAAQ,EAAE,MAAM,GACf,CAAC,GAAG,SAAS,CAGf;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAChC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,IAAI,CASN"}
+{"version":3,"file":"schemaVersion.d.ts","sourceRoot":"","sources":["../../../src/shared/io/schemaVersion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;aAEjC,YAAY,EAAE,MAAM;aACpB,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;gBAFd,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CASjC;AAsCD;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,SAAS,MAAM,EAC7D,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI,EAC3B,QAAQ,EAAE,MAAM,GACf,CAAC,GAAG,SAAS,CAGf;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAChC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,IAAI,CASN"}

package/dist/shared/io/schemaVersion.js

@@ -5,9 +5,10 @@
  * State written by an older version of the tool is read back under the CURRENT
  * version's semantics. A reader that never compares the stamped version (spelled
  * `schema_version` on artifacts, `contract_version` on contracts — both are read
- * here) silently reinterprets old bytes as new-shape data. Stamping a version on
- * WRITE and not comparing it on READ is therefore not "versioned" at all — it is
- * an unchecked cast wearing a version field.
+ * here, at the top level or on the `payload` of a content-hash envelope) silently
+ * reinterprets old bytes as new-shape data. Stamping a version on WRITE and not
+ * comparing it on READ is therefore not "versioned" at all — it is an unchecked
+ * cast wearing a version field.
  *
  * There are exactly two correct policies, and which one applies is a property
  * of the STATE, not of the module:
@@ -60,9 +61,31 @@ export class SchemaVersionMismatchError extends Error {
 // always-discard is indistinguishable from a working guard in review, so the
 // helper resolves the key rather than making each call site remember it.
 // `schema_version` wins when a payload carries both.
+//
+// TWO DEPTHS are recognized for the same reason, on the contract-pipeline's own
+// file family. Every artifact the pipeline writes to disk is a content-hash
+// ENVELOPE (`{artifact_name, content_hash, dependency_hashes, payload}`) whose
+// `payload` is the contract, and the contract's version is `contract_version` —
+// one level DOWN. A helper that read only the top level therefore returned
+// `undefined` for every envelope, i.e. treated each one as stale and reported a
+// version problem that did not exist. The payload arm applies only when the top
+// level carried NO version at all: an envelope that stamps its own version is
+// judged by that, never by whatever its payload happens to say.
 function stampedVersion(value) {
     const record = value;
-    return "schema_version" in record ? record.schema_version : record.contract_version;
+    if ("schema_version" in record)
+        return record.schema_version;
+    if ("contract_version" in record)
+        return record.contract_version;
+    const payload = record.payload;
+    if (payload !== null && typeof payload === "object" && !Array.isArray(payload)) {
+        const inner = payload;
+        if ("schema_version" in inner)
+            return inner.schema_version;
+        if ("contract_version" in inner)
+            return inner.contract_version;
+    }
+    return undefined;
 }
 /**
  * REGENERABLE state: return the payload only when its stamped `schema_version`

package/dist/shared/io/schemaVersion.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemaVersion.js","sourceRoot":"","sources":["../../../src/shared/io/schemaVersion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;GAIG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAEjC;IACA;IACA;IAHlB,YACkB,YAAoB,EACpB,QAAgB,EAChB,MAAc;QAE9B,KAAK,CACH,aAAa,YAAY,yBAAyB,MAAM,mBAAmB,QAAQ,KAAK;YACtF,uFAAuF;YACvF,UAAU,YAAY,iDAAiD,CAC1E,CAAC;QARc,iBAAY,GAAZ,YAAY,CAAQ;QACpB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAQ;QAO9B,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED,8EAA8E;AAC9E,6EAA6E;AAC7E,mEAAmE;AACnE,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,uEAAuE;AACvE,6EAA6E;AAC7E,yEAAyE;AACzE,qDAAqD;AACrD,SAAS,cAAc,CAAC,KAAa;IACnC,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,OAAO,gBAAgB,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC;AACtF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,8BAA8B,CAC5C,KAA2B,EAC3B,QAAgB;IAEhB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,OAAO,cAAc,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAChE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAC1C,KAAgC,EAChC,YAAoB,EACpB,QAAgB;IAEhB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO;IAClD,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,0BAA0B,CAAC,YAAY,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,MAAM,IAAI,0BAA0B,CAAC,YAAY,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACvE,CAAC;AACH,CAAC"}
+{"version":3,"file":"schemaVersion.js","sourceRoot":"","sources":["../../../src/shared/io/schemaVersion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;GAIG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAEjC;IACA;IACA;IAHlB,YACkB,YAAoB,EACpB,QAAgB,EAChB,MAAc;QAE9B,KAAK,CACH,aAAa,YAAY,yBAAyB,MAAM,mBAAmB,QAAQ,KAAK;YACtF,uFAAuF;YACvF,UAAU,YAAY,iDAAiD,CAC1E,CAAC;QARc,iBAAY,GAAZ,YAAY,CAAQ;QACpB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAQ;QAO9B,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED,8EAA8E;AAC9E,6EAA6E;AAC7E,mEAAmE;AACnE,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,uEAAuE;AACvE,6EAA6E;AAC7E,yEAAyE;AACzE,qDAAqD;AACrD,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,+EAA+E;AAC/E,gFAAgF;AAChF,2EAA2E;AAC3E,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,gEAAgE;AAChE,SAAS,cAAc,CAAC,KAAa;IACnC,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,IAAI,gBAAgB,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,cAAc,CAAC;IAC7D,IAAI,kBAAkB,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,gBAAgB,CAAC;IACjE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/E,MAAM,KAAK,GAAG,OAAkC,CAAC;QACjD,IAAI,gBAAgB,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC,cAAc,CAAC;QAC3D,IAAI,kBAAkB,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC,gBAAgB,CAAC;IACjE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,8BAA8B,CAC5C,KAA2B,EAC3B,QAAgB;IAEhB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,OAAO,cAAc,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAChE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAC1C,KAAgC,EAChC,YAAoB,EACpB,QAAgB;IAEhB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO;IAClD,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,0BAA0B,CAAC,YAAY,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,MAAM,IAAI,0BAA0B,CAAC,YAAY,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACvE,CAAC;AACH,CAAC"}

package/dist/shared/io/stepContractWriter.d.ts

@@ -21,7 +21,7 @@
  *    current-prompt.md.
  *
  * Each orchestrator extends `BaseStepContract` with its own `step_kind` enum
- * and optional fields (progress, allowed_mcp_tools, access, ...) and calls
+ * and optional fields (progress, access, ...) and calls
  * `writeStepContract` with its concrete types; neither writes raw paths.
  */
 /**
@@ -65,7 +65,7 @@ export interface BaseStepContract<TStepKind extends string = string, TArtifactVa
  * `extraFields` is a shallow object spread onto the contract AFTER the base
  * fields but BEFORE the canonical `prompt_path`/`repo_root`/`artifacts_dir`/
  * `artifact_paths` normalization — so an orchestrator's optional fields
- * (progress, allowed_mcp_tools, access, ...) ride along without this module
+ * (progress, access, ...) ride along without this module
  * knowing about them, and can never clobber the normalized path fields.
  */
 export interface WriteStepContractInput<TStepKind extends string = string, TArtifactValue extends string | null = string | null> {
@@ -85,8 +85,8 @@ export interface WriteStepContractInput<TStepKind extends string = string, TArti
      */
     artifactPaths?: Record<string, TArtifactValue>;
     /**
-     * Orchestrator-specific optional fields (progress, allowed_mcp_tools,
-     * access, ...). Spread onto the contract before the canonical path fields,
+     * Orchestrator-specific optional fields (progress, access, ...). Spread onto
+     * the contract before the canonical path fields,
      * so they can never overwrite the normalized paths or `artifact_paths`.
      */
     extraFields?: Record<string, unknown>;
@@ -108,6 +108,40 @@ export interface WriteStepContractInput<TStepKind extends string = string, TArti
  * commands from.
  */
 export declare function writeStepContract<TStep extends BaseStepContract<TStepKind, TArtifactValue>, TStepKind extends string = string, TArtifactValue extends string | null = string | null>(input: WriteStepContractInput<TStepKind, TArtifactValue>): Promise<TStep>;
+/**
+ * Invalidate the persisted step contract after a verb MUTATED run state without
+ * emitting a step of its own.
+ *
+ * The step contract is a live INSTRUCTION ("do this work, then call next-step"),
+ * and the two operator recovery verbs — `recover-ingest` and
+ * `recover-submission` — mutate the run behind the host's back. Left alone, the
+ * last persisted contract keeps describing work that the mutation just resolved
+ * (or whose `host_handoff` binding it just cleared), so a host that re-reads it
+ * resumes a prompt for a run that no longer exists. That is why `next-step`
+ * carries `runWithBlockedStepBackstop` for its own exits: after ANY terminal
+ * exit of a state-mutating invocation, the on-disk contract must reflect that
+ * invocation's outcome.
+ *
+ * Both slots are removed — the per-agent ones (which are what a peer actually
+ * addresses) and the shared "latest" mirror. The per-agent slot is removed as a
+ * DIRECTORY, the same operation {@link gcStaleAgentSlots}' own removal path
+ * performs, because deleting only its two files would leave the slot dir behind
+ * holding a stale `owner.json`: `gcStaleAgentSlots` stats `current-step.json`
+ * FIRST, so every later `next-step` write would take the `unreadable_marker`
+ * branch on that husk forever (and never reach the removal path that could clear
+ * it). The shared mirror is two FILES with no directory of its own, so both are
+ * removed because a reader takes the prompt from `current-prompt.md` and the
+ * binding from `current-step.json`; leaving either one behind leaves a half-live
+ * instruction.
+ * Absence is the correct invalidation here: unlike `next-step`, a bare recovery
+ * verb has no successor step to write, and a stale step is worse than none —
+ * `next-step` re-emits a fresh contract on the very next call, which is the
+ * action the refresh prompt names.
+ *
+ * Best-effort and idempotent: an already-absent contract is not an error, and a
+ * recovery must never fail because it could not clean up a stale prompt.
+ */
+export declare function invalidateStepContracts(artifactsDir: string): Promise<void>;
 /**
  * Run `body` under the terminal-exit backstop both next-step CLIs share
  * (backlog: abnormal-exit no-step-contract). If `body` throws — a

package/dist/shared/io/stepContractWriter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stepContractWriter.d.ts","sourceRoot":"","sources":["../../../src/shared/io/stepContractWriter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stepContractWriter.d.ts","sourceRoot":"","sources":["../../../src/shared/io/stepContractWriter.ts"],"names":[],"mappings":"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"}

package/dist/shared/io/stepContractWriter.js

@@ -26,7 +26,7 @@ import { toPromptPathToken } from "../tooling/exec.js";
  *    current-prompt.md.
  *
  * Each orchestrator extends `BaseStepContract` with its own `step_kind` enum
- * and optional fields (progress, allowed_mcp_tools, access, ...) and calls
+ * and optional fields (progress, access, ...) and calls
  * `writeStepContract` with its concrete types; neither writes raw paths.
  */
 /**
@@ -236,6 +236,64 @@ export async function writeStepContract(input) {
     await gcStaleAgentSlots(stepsDirPath, agentId);
     return step;
 }
+/**
+ * Invalidate the persisted step contract after a verb MUTATED run state without
+ * emitting a step of its own.
+ *
+ * The step contract is a live INSTRUCTION ("do this work, then call next-step"),
+ * and the two operator recovery verbs — `recover-ingest` and
+ * `recover-submission` — mutate the run behind the host's back. Left alone, the
+ * last persisted contract keeps describing work that the mutation just resolved
+ * (or whose `host_handoff` binding it just cleared), so a host that re-reads it
+ * resumes a prompt for a run that no longer exists. That is why `next-step`
+ * carries `runWithBlockedStepBackstop` for its own exits: after ANY terminal
+ * exit of a state-mutating invocation, the on-disk contract must reflect that
+ * invocation's outcome.
+ *
+ * Both slots are removed — the per-agent ones (which are what a peer actually
+ * addresses) and the shared "latest" mirror. The per-agent slot is removed as a
+ * DIRECTORY, the same operation {@link gcStaleAgentSlots}' own removal path
+ * performs, because deleting only its two files would leave the slot dir behind
+ * holding a stale `owner.json`: `gcStaleAgentSlots` stats `current-step.json`
+ * FIRST, so every later `next-step` write would take the `unreadable_marker`
+ * branch on that husk forever (and never reach the removal path that could clear
+ * it). The shared mirror is two FILES with no directory of its own, so both are
+ * removed because a reader takes the prompt from `current-prompt.md` and the
+ * binding from `current-step.json`; leaving either one behind leaves a half-live
+ * instruction.
+ * Absence is the correct invalidation here: unlike `next-step`, a bare recovery
+ * verb has no successor step to write, and a stale step is worse than none —
+ * `next-step` re-emits a fresh contract on the very next call, which is the
+ * action the refresh prompt names.
+ *
+ * Best-effort and idempotent: an already-absent contract is not an error, and a
+ * recovery must never fail because it could not clean up a stale prompt.
+ */
+export async function invalidateStepContracts(artifactsDir) {
+    const stepsDirPath = stepsDir(artifactsDir);
+    let slots;
+    try {
+        const entries = await readdir(stepsDirPath, { withFileTypes: true });
+        slots = entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        // No steps dir at all: nothing was ever persisted, so nothing is stale.
+        return;
+    }
+    // The path helpers take the ARTIFACTS dir (plus an optional agent id) and
+    // derive `steps/` themselves — passing them a steps dir would silently build
+    // `steps/steps/current-step.json` and delete nothing, which is exactly the
+    // bug this function shipped with until a test asserted the files were gone.
+    const sharedTargets = [currentStepPath(artifactsDir), currentPromptPath(artifactsDir)];
+    await Promise.all([
+        ...sharedTargets.map((path) => rm(path, { force: true }).catch(() => undefined)),
+        // Whole slot DIRECTORY, not its two files: see the header. Best-effort and
+        // idempotent like the rest of this function (a vanished slot is not an error).
+        ...slots.map((slot) => rm(join(stepsDirPath, slot), { recursive: true, force: true }).catch(() => undefined)),
+    ]);
+}
 /**
  * Run `body` under the terminal-exit backstop both next-step CLIs share
  * (backlog: abnormal-exit no-step-contract). If `body` throws — a

package/dist/shared/io/stepContractWriter.js.map

@@ -1 +1 @@
-{"version":3,"file":"stepContractWriter.js","sourceRoot":"","sources":["../../../src/shared/io/stepContractWriter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stepContractWriter.js","sourceRoot":"","sources":["../../../src/shared/io/stepContractWriter.ts"],"names":[],"mappings":"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"}

package/dist/shared/loopCorePaths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loopCorePaths.d.ts","sourceRoot":"","sources":["../../src/shared/loopCorePaths.ts"],"names":[],"mappings":"AA4BA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EA4B/C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUpD"}
+{"version":3,"file":"loopCorePaths.d.ts","sourceRoot":"","sources":["../../src/shared/loopCorePaths.ts"],"names":[],"mappings":"AA4BA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAoC/C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUpD"}

package/dist/shared/loopCorePaths.js

@@ -56,6 +56,14 @@ export const LOOP_CORE_PATTERNS = [
     "src/remediate/steps/dispatch/",
     "src/remediate/steps/nextStep.ts",
     "src/shared/engine/",
+    // The host-facing step-contract WRITE-AND-LOG site: `createStepEmissionScaffold`
+    // owns the ONE call site that turns a plan into a written, logged step for BOTH
+    // orchestrators. It is the boundary every host handoff is emitted through —
+    // "written exactly once, logged exactly once" is a property of this module, not
+    // of each adopter remembering to do both — so a change here can alter what any
+    // host is handed, which is the blast radius this set exists to cover. It was
+    // the last emission-path module outside the set.
+    "src/shared/steps/",
     "src/shared/submission/",
 ];
 /**

package/dist/shared/loopCorePaths.js.map

@@ -1 +1 @@
-{"version":3,"file":"loopCorePaths.js","sourceRoot":"","sources":["../../src/shared/loopCorePaths.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,kFAAkF;AAClF,0EAA0E;AAC1E,qBAAqB;AACrB,EAAE;AACF,4EAA4E;AAC5E,wEAAwE;AACxE,uBAAuB;AACvB,2EAA2E;AAC3E,4CAA4C;AAC5C,EAAE;AACF,yEAAyE;AACzE,6DAA6D;AAC7D,sDAAsD;AACtD,+EAA+E;AAC/E,gFAAgF;AAChF,kFAAkF;AAClF,0DAA0D;AAC1D,uEAAuE;AACvE,wEAAwE;AACxE,qDAAqD;AACrD,EAAE;AACF,kFAAkF;AAClF,iFAAiF;AACjF,+EAA+E;AAE/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD,8EAA8E;IAC9E,uEAAuE;IACvE,4EAA4E;IAC5E,4EAA4E;IAC5E,qEAAqE;IACrE,yEAAyE;IACzE,iDAAiD;IACjD,yBAAyB;IACzB,oFAAoF;IACpF,sFAAsF;IACtF,sFAAsF;IACtF,iEAAiE;IACjE,kCAAkC;IAClC,kCAAkC;IAClC,iCAAiC;IACjC,kCAAkC;IAClC,yBAAyB;IACzB,8EAA8E;IAC9E,4EAA4E;IAC5E,8EAA8E;IAC9E,wCAAwC;IACxC,6BAA6B;IAC7B,yCAAyC;IACzC,+BAA+B;IAC/B,iCAAiC;IACjC,oBAAoB;IACpB,wBAAwB;CACzB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,CAAC,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IACrC,KAAK,MAAM,OAAO,IAAI,kBAAkB,EAAE,CAAC;QACzC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;gBAAE,OAAO,IAAI,CAAC;QACzC,CAAC;aAAM,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"loopCorePaths.js","sourceRoot":"","sources":["../../src/shared/loopCorePaths.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,kFAAkF;AAClF,0EAA0E;AAC1E,qBAAqB;AACrB,EAAE;AACF,4EAA4E;AAC5E,wEAAwE;AACxE,uBAAuB;AACvB,2EAA2E;AAC3E,4CAA4C;AAC5C,EAAE;AACF,yEAAyE;AACzE,6DAA6D;AAC7D,sDAAsD;AACtD,+EAA+E;AAC/E,gFAAgF;AAChF,kFAAkF;AAClF,0DAA0D;AAC1D,uEAAuE;AACvE,wEAAwE;AACxE,qDAAqD;AACrD,EAAE;AACF,kFAAkF;AAClF,iFAAiF;AACjF,+EAA+E;AAE/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD,8EAA8E;IAC9E,uEAAuE;IACvE,4EAA4E;IAC5E,4EAA4E;IAC5E,qEAAqE;IACrE,yEAAyE;IACzE,iDAAiD;IACjD,yBAAyB;IACzB,oFAAoF;IACpF,sFAAsF;IACtF,sFAAsF;IACtF,iEAAiE;IACjE,kCAAkC;IAClC,kCAAkC;IAClC,iCAAiC;IACjC,kCAAkC;IAClC,yBAAyB;IACzB,8EAA8E;IAC9E,4EAA4E;IAC5E,8EAA8E;IAC9E,wCAAwC;IACxC,6BAA6B;IAC7B,yCAAyC;IACzC,+BAA+B;IAC/B,iCAAiC;IACjC,oBAAoB;IACpB,iFAAiF;IACjF,gFAAgF;IAChF,4EAA4E;IAC5E,gFAAgF;IAChF,+EAA+E;IAC/E,6EAA6E;IAC7E,iDAAiD;IACjD,mBAAmB;IACnB,wBAAwB;CACzB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,CAAC,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IACrC,KAAK,MAAM,OAAO,IAAI,kBAAkB,EAAE,CAAC;QACzC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;gBAAE,OAAO,IAAI,CAAC;QACzC,CAAC;aAAM,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/shared/opencodePermissions.d.ts

@@ -19,6 +19,29 @@
 /** The broad value the deploy helpers historically wrote ("tool-managed"). */
 export declare const OPENCODE_MANAGED_BROAD_VALUE = "allow";
 type PermissionRule = Record<string, string>;
+/**
+ * Emit a permission rule block in a STABLE, content-derived key order: the `"*"`
+ * wildcard first (when present), then every other key lexicographically.
+ *
+ * Every merge below composes three sources (generated / existing / managed)
+ * whose relative key order depends on which installer wrote the file last, so
+ * emitting in composition order made `opencode.json` a pure key-reorder diff on
+ * every `ensure` — the file churned between the audit-first and
+ * remediate-first orders without a single value changing, dirtying every tree
+ * it touches and violating the stable content-derived ordering invariant. The
+ * merged key SET was already order-independent; only its emission was not.
+ *
+ * EXPORTED because ordering the merges is not sufficient: a deployer that finds
+ * no existing block returns its generated seed VERBATIM (the postinstall agent
+ * scope short-circuits on a fresh config), so the seed literals must already be
+ * in this order or the first run emits composition order and the second emits
+ * sorted — the same churn, one run later. Every seed and every merge goes
+ * through here, so one canonical order exists in the file's whole lifecycle.
+ *
+ * Callers pass already precedence-resolved values, so this changes placement
+ * only — the same reason `unionOpenCodeBashCeiling` emits `"*"` first, then sorts.
+ */
+export declare function orderOpenCodePermissionRule(rule: Record<string, unknown> | null | undefined): PermissionRule;
 /** Returns a copy of `rules` without its `"*"` wildcard entry. */
 export declare function withoutOpenCodeWildcard(rules: PermissionRule): PermissionRule;
 /**
@@ -70,9 +93,10 @@ export declare function migrateOpenCodeGlobalExternalDirectory(existingRule: unk
 export declare function unionOpenCodeBashCeiling(agentBashRuleSets: ReadonlyArray<unknown>): PermissionRule;
 /**
  * Compose the top-level bash block an installer should write: the managed union
- * ceiling of all agents (emitted in its stable, content-derived order — `"*"`
- * first, then sorted keys) followed by any user-authored top-level keys the
- * union does not cover (appended in sorted order, non-clobber). The result is
+ * ceiling of all agents followed by any user-authored top-level keys the union
+ * does not cover (non-clobber). The union's own managed keys stay in their
+ * stable order (a test pins `"*"` first, then lexicographic); the user extras
+ * follow in a stable sorted order. The result is
  * therefore order-stable regardless of which installer ran last: the managed
  * portion is always the same sorted union, so re-running either installer in
  * any order is byte-idempotent and never churns the artifact's content hash.

package/dist/shared/opencodePermissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"opencodePermissions.d.ts","sourceRoot":"","sources":["../../src/shared/opencodePermissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,4BAA4B,UAAU,CAAC;AAEpD,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAQ7C,kEAAkE;AAClE,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,CAI7E;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,YAAY,EAAE,OAAO,EACrB,aAAa,EAAE,OAAO,EACtB,YAAY,GAAE,cAAmB,GAChC,OAAO,CA2BT;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,OAAO,EACrB,aAAa,EAAE,cAAc,EAC7B,YAAY,GAAE,cAAmB,GAChC,cAAc,CAwBhB;AAED;;;;;;;GAOG;AACH,wBAAgB,sCAAsC,CACpD,YAAY,EAAE,OAAO,GACpB,OAAO,CAcT;AA6BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAItC,iBAAiB,EAAE,aAAa,CAAC,OAAO,CAAC,GACxC,cAAc,CAkChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAC3D,iBAAiB,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GACnE,cAAc,CAYhB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EACA,kBAAkB,GAClB,0BAA0B,GAC1B,wBAAwB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EACxD,iBAAiB,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,EACpE,OAAO,GAAE;IAAE,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAAO,GACjD,wBAAwB,EAAE,CAwC5B"}
+{"version":3,"file":"opencodePermissions.d.ts","sourceRoot":"","sources":["../../src/shared/opencodePermissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,4BAA4B,UAAU,CAAC;AAEpD,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAQ7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAC/C,cAAc,CAUhB;AAED,kEAAkE;AAClE,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,CAI7E;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,YAAY,EAAE,OAAO,EACrB,aAAa,EAAE,OAAO,EACtB,YAAY,GAAE,cAAmB,GAChC,OAAO,CAkCT;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,OAAO,EACrB,aAAa,EAAE,cAAc,EAC7B,YAAY,GAAE,cAAmB,GAChC,cAAc,CA2BhB;AAED;;;;;;;GAOG;AACH,wBAAgB,sCAAsC,CACpD,YAAY,EAAE,OAAO,GACpB,OAAO,CAoBT;AA6BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAItC,iBAAiB,EAAE,aAAa,CAAC,OAAO,CAAC,GACxC,cAAc,CAkChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAC3D,iBAAiB,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GACnE,cAAc,CAehB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EACA,kBAAkB,GAClB,0BAA0B,GAC1B,wBAAwB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EACxD,iBAAiB,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,EACpE,OAAO,GAAE;IAAE,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAAO,GACjD,wBAAwB,EAAE,CAwC5B"}

package/dist/shared/opencodePermissions.js

@@ -23,6 +23,40 @@ function permissionRuleObject(value) {
         ? value
         : {};
 }
+/**
+ * Emit a permission rule block in a STABLE, content-derived key order: the `"*"`
+ * wildcard first (when present), then every other key lexicographically.
+ *
+ * Every merge below composes three sources (generated / existing / managed)
+ * whose relative key order depends on which installer wrote the file last, so
+ * emitting in composition order made `opencode.json` a pure key-reorder diff on
+ * every `ensure` — the file churned between the audit-first and
+ * remediate-first orders without a single value changing, dirtying every tree
+ * it touches and violating the stable content-derived ordering invariant. The
+ * merged key SET was already order-independent; only its emission was not.
+ *
+ * EXPORTED because ordering the merges is not sufficient: a deployer that finds
+ * no existing block returns its generated seed VERBATIM (the postinstall agent
+ * scope short-circuits on a fresh config), so the seed literals must already be
+ * in this order or the first run emits composition order and the second emits
+ * sorted — the same churn, one run later. Every seed and every merge goes
+ * through here, so one canonical order exists in the file's whole lifecycle.
+ *
+ * Callers pass already precedence-resolved values, so this changes placement
+ * only — the same reason `unionOpenCodeBashCeiling` emits `"*"` first, then sorts.
+ */
+export function orderOpenCodePermissionRule(rule) {
+    const values = permissionRuleObject(rule);
+    const ordered = {};
+    if (values["*"] !== undefined) {
+        ordered["*"] = values["*"];
+    }
+    for (const key of Object.keys(values).sort()) {
+        if (key !== "*")
+            ordered[key] = values[key];
+    }
+    return ordered;
+}
 /** Returns a copy of `rules` without its `"*"` wildcard entry. */
 export function withoutOpenCodeWildcard(rules) {
     const copy = { ...rules };
@@ -43,25 +77,30 @@ export function mergeOpenCodeAgentPermissionRule(existingRule, generatedRule, ma
     }
     const generatedObject = generatedRule;
     const existingObject = permissionRuleObject(existingRule);
-    const merged = {};
-    if (typeof existingRule === "string") {
-        merged["*"] = existingRule;
-    }
-    else {
-        merged["*"] = existingObject["*"] ?? generatedObject["*"] ?? "ask";
-    }
+    // Precedence is resolved first (managed > existing > generated), then the
+    // block is emitted in the one canonical order — see orderOpenCodePermissionRule.
+    const values = {};
     for (const [key, value] of Object.entries(generatedObject)) {
         if (key !== "*")
-            merged[key] = value;
+            values[key] = value;
     }
     for (const [key, value] of Object.entries(existingObject)) {
         if (key !== "*")
-            merged[key] = value;
+            values[key] = value;
     }
     for (const [key, value] of Object.entries(managedRules)) {
-        merged[key] = value;
+        if (key !== "*")
+            values[key] = value;
     }
-    return merged;
+    // A managed wildcard wins outright (it is the caller's explicit policy); then
+    // a string-form existing rule promotes to the wildcard; then the existing
+    // wildcard beats the generated one; then the generated default "ask".
+    const wildcard = managedRules["*"] ??
+        (typeof existingRule === "string"
+            ? existingRule
+            : existingObject["*"] ?? generatedObject["*"] ?? "ask");
+    values["*"] = wildcard;
+    return orderOpenCodePermissionRule(values);
 }
 /**
  * Global-scope rule merge: never seeds a wildcard. An existing wildcard is
@@ -74,25 +113,27 @@ export function mergeOpenCodeGlobalPermissionRule(existingRule, generatedRule, m
     const existingObject = typeof existingRule === "string"
         ? { "*": existingRule }
         : permissionRuleObject(existingRule);
-    const merged = {};
-    const existingWildcard = existingObject["*"];
-    if (existingWildcard !== undefined &&
-        existingWildcard !== OPENCODE_MANAGED_BROAD_VALUE) {
-        merged["*"] = existingWildcard;
-    }
+    const values = {};
     for (const [key, value] of Object.entries(generatedRule)) {
         if (key !== "*")
-            merged[key] = value;
+            values[key] = value;
     }
     for (const [key, value] of Object.entries(existingObject)) {
         if (key !== "*")
-            merged[key] = value;
+            values[key] = value;
     }
     for (const [key, value] of Object.entries(managedRules)) {
         if (key !== "*")
-            merged[key] = value;
+            values[key] = value;
     }
-    return merged;
+    // An existing wildcard survives verbatim unless it IS the managed broad
+    // value, in which case it is migration cleanup. Never seeded from generated.
+    const existingWildcard = existingObject["*"];
+    if (existingWildcard !== undefined &&
+        existingWildcard !== OPENCODE_MANAGED_BROAD_VALUE) {
+        values["*"] = existingWildcard;
+    }
+    return orderOpenCodePermissionRule(values);
 }
 /**
  * Global-scope `external_directory` migration: the deploy helpers
@@ -113,7 +154,13 @@ export function migrateOpenCodeGlobalExternalDirectory(existingRule) {
         return existingRule;
     }
     const rest = withoutOpenCodeWildcard(existingObject);
-    return Object.keys(rest).length > 0 ? rest : undefined;
+    if (Object.keys(rest).length === 0) {
+        return undefined;
+    }
+    // The survivors go through the same canonical order, so a migrated entry
+    // matches every other generated block rather than keeping the order it
+    // happened to have on disk.
+    return orderOpenCodePermissionRule(rest);
 }
 // ── Union permission ceiling (INV-RCI-16, reframed) ──────────────────────────
 //
@@ -204,9 +251,10 @@ agentBashRuleSets) {
 }
 /**
  * Compose the top-level bash block an installer should write: the managed union
- * ceiling of all agents (emitted in its stable, content-derived order — `"*"`
- * first, then sorted keys) followed by any user-authored top-level keys the
- * union does not cover (appended in sorted order, non-clobber). The result is
+ * ceiling of all agents followed by any user-authored top-level keys the union
+ * does not cover (non-clobber). The union's own managed keys stay in their
+ * stable order (a test pins `"*"` first, then lexicographic); the user extras
+ * follow in a stable sorted order. The result is
  * therefore order-stable regardless of which installer ran last: the managed
  * portion is always the same sorted union, so re-running either installer in
  * any order is byte-idempotent and never churns the artifact's content hash.
@@ -214,7 +262,10 @@ agentBashRuleSets) {
 export function composeOpenCodeBashCeiling(existingTopBash, agentBashRuleSets) {
     const ceiling = unionOpenCodeBashCeiling(agentBashRuleSets);
     const existing = permissionRuleObject(existingTopBash);
-    const composed = { ...ceiling };
+    const composed = {};
+    for (const [key, value] of Object.entries(ceiling)) {
+        composed[key] = value;
+    }
     // Append user-authored keys the union does not manage, in a stable sorted
     // order so their placement can't churn either.
     for (const key of Object.keys(existing).sort()) {