release-skill 0.9.22 → 0.9.24

package/src/schemas/professional-conclusion.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/professional-conclusion.json",
+  "title": "ProfessionalConclusion",
+  "description": "Minimal exchange contract for a provider-owned professional conclusion. Foundation fixes the common shape and completion semantics without interpreting the provider's domain code or details.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "provider", "subject", "scope", "outcome"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.professional-conclusion" },
+    "provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version", "entry"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "entry": { "type": "string", "minLength": 1 }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ref"],
+      "properties": {
+        "ref": { "type": "string", "minLength": 1 },
+        "revision": { "type": "string", "minLength": 1 }
+      }
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["checked", "limitations"],
+      "properties": {
+        "checked": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "limitations": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "outcome": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["completion", "code", "summary"],
+      "properties": {
+        "completion": { "enum": ["complete", "partial", "not-performed"] },
+        "code": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string", "minLength": 1 }
+      }
+    },
+    "details": {
+      "type": "object",
+      "description": "Provider-owned JSON object. Foundation does not interpret its domain fields."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "type": "object",
+            "properties": { "completion": { "const": "complete" } },
+            "required": ["completion"]
+          }
+        },
+        "required": ["outcome"]
+      },
+      "then": {
+        "properties": {
+          "scope": {
+            "type": "object",
+            "properties": { "checked": { "type": "array", "minItems": 1 } },
+            "required": ["checked"]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "type": "object",
+            "properties": { "completion": { "const": "partial" } },
+            "required": ["completion"]
+          }
+        },
+        "required": ["outcome"]
+      },
+      "then": {
+        "properties": {
+          "scope": {
+            "type": "object",
+            "properties": {
+              "checked": { "type": "array", "minItems": 1 },
+              "limitations": { "type": "array", "minItems": 1 }
+            },
+            "required": ["checked", "limitations"]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "type": "object",
+            "properties": { "completion": { "const": "not-performed" } },
+            "required": ["completion"]
+          }
+        },
+        "required": ["outcome"]
+      },
+      "then": {
+        "properties": {
+          "scope": {
+            "type": "object",
+            "properties": {
+              "checked": { "type": "array", "maxItems": 0 },
+              "limitations": { "type": "array", "minItems": 1 }
+            },
+            "required": ["checked", "limitations"]
+          }
+        }
+      }
+    }
+  ]
+}

package/src/schemas/project-manifest.schema.json

@@ -58,10 +58,101 @@
         "pattern": "^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$"
       }
     },
+    "engineering": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "releaseUnits": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/releaseUnit" }
+        },
+        "entries": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/engineeringEntry" }
+        }
+      }
+    },
     "updatedAt": {
       "type": "string",
       "format": "date-time",
       "description": "RFC 3339 date-time of the last manifest update; format enforcement is part of the contracts dialect support."
     }
+  },
+  "$defs": {
+    "versionReference": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "format"],
+          "properties": {
+            "path": { "$ref": "#/$defs/projectRelativePath" },
+            "format": { "const": "text" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "format", "jsonPointer"],
+          "properties": {
+            "path": { "$ref": "#/$defs/projectRelativePath" },
+            "format": { "const": "json" },
+            "jsonPointer": {
+              "type": "string",
+              "pattern": "^(/([^/~]|~[01])*)+$",
+              "description": "Non-empty RFC 6901 JSON Pointer."
+            }
+          }
+        }
+      ]
+    },
+    "releaseUnit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "versionSource"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "versionSource": { "$ref": "#/$defs/versionReference" },
+        "versionMirrors": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/versionReference" }
+        }
+      }
+    },
+    "engineeringEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "form", "physicalRef"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "form": { "enum": ["skill_md", "file"] },
+        "physicalRef": { "$ref": "#/$defs/projectRelativePath" }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "form": { "const": "skill_md" } },
+            "required": ["form"]
+          },
+          "then": {
+            "properties": {
+              "physicalRef": { "type": "string", "pattern": "(^|/)SKILL\\.md$" }
+            }
+          }
+        }
+      ]
+    },
+    "projectRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*(?:^|/)\\.(?:/|$))(?!.*\\\\)(?!.*\\u0000)[^/\\\\\\u0000]+(?:/[^/\\\\\\u0000]+)*$",
+      "description": "A non-empty path relative to the caller-provided project root. Containment and file identity are mechanism concerns."
+    }
   }
 }

package/src/schemas/state-store-recovery-observation.schema.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/state-store-recovery-observation.json",
+  "title": "State store recovery observation",
+  "description": "Read-only maintenance observation. The runtime rechecks identities and original bytes before any takeover; confirmation does not itself provide exclusion.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "root", "directories", "controls"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.state-store-recovery-observation" },
+    "root": { "type": "string", "pattern": "^/(?!.*(?:^|/)(?:\\.|\\.\\.)(?:/|$))(?!.*//)(?!.*[\\\\\\u0000])(?:[^/]+(?:/[^/]+)*)?$" },
+    "directories": {
+      "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true,
+      "items": { "$ref": "#/$defs/directory" },
+      "contains": { "type": "object", "properties": { "path": { "const": "." }, "exists": { "const": true } }, "required": ["path", "exists"] },
+      "minContains": 1, "maxContains": 1
+    },
+    "controls": {
+      "type": "array", "minItems": 3, "maxItems": 3,
+      "prefixItems": [
+        { "$ref": "#/$defs/control", "properties": { "path": { "const": "writer.lock" }, "record": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/writerRecord" }] } }, "type": "object" },
+        { "$ref": "#/$defs/control", "properties": { "path": { "const": "writer-mutation.lock" }, "record": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/mutationRecord" }] } }, "type": "object" },
+        { "$ref": "#/$defs/control", "properties": { "path": { "const": "writer-recovery.lock" }, "record": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/recoveryRecord" }] } }, "type": "object" }
+      ],
+      "items": false
+    }
+  },
+  "$defs": {
+    "identity": {
+      "type": "object", "additionalProperties": false,
+      "required": ["device", "inode", "mode", "type"],
+      "properties": {
+        "device": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" },
+        "inode": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" },
+        "mode": { "type": "integer", "minimum": 0, "maximum": 65535 },
+        "type": { "enum": ["file", "directory"] }
+      }
+    },
+    "directory": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "exists", "identity"],
+      "properties": {
+        "path": { "enum": [".", "events", "snapshots"] },
+        "exists": { "type": "boolean" },
+        "identity": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/identity" }] }
+      },
+      "allOf": [{
+        "if": { "properties": { "exists": { "const": true } }, "required": ["exists"] },
+        "then": { "properties": { "identity": { "$ref": "#/$defs/identity", "type": "object", "properties": { "type": { "const": "directory" } } } } },
+        "else": { "properties": { "identity": { "type": "null" } } }
+      }]
+    },
+    "control": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "exists", "identity", "nlink", "size", "sha256", "record"],
+      "properties": {
+        "path": { "enum": ["writer.lock", "writer-mutation.lock", "writer-recovery.lock"] },
+        "exists": { "type": "boolean" },
+        "identity": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/identity" }] },
+        "nlink": { "enum": [null, 1] },
+        "size": { "type": ["integer", "null"], "minimum": 0, "maximum": 9007199254740991 },
+        "sha256": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$" },
+        "record": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/record" }] }
+      },
+      "allOf": [{
+        "if": { "properties": { "exists": { "const": true } }, "required": ["exists"] },
+        "then": { "properties": {
+          "identity": { "$ref": "#/$defs/identity", "type": "object", "properties": { "type": { "const": "file" } } },
+          "nlink": { "const": 1 }, "size": { "type": "integer" }, "sha256": { "type": "string" }, "record": { "$ref": "#/$defs/record" }
+        } },
+        "else": { "properties": { "identity": { "type": "null" }, "nlink": { "type": "null" }, "size": { "type": "null" }, "sha256": { "type": "null" }, "record": { "type": "null" } } }
+      }]
+    },
+    "record": {
+      "type": "object", "additionalProperties": false,
+      "required": ["status", "value"],
+      "properties": { "status": { "enum": ["valid", "partial", "unsupported"] }, "value": { "type": ["object", "null"] } },
+      "allOf": [{
+        "if": { "properties": { "status": { "const": "valid" } }, "required": ["status"] },
+        "then": { "properties": { "value": { "type": "object" } } },
+        "else": { "properties": { "value": { "type": "null" } } }
+      }]
+    },
+    "writerRecord": {
+      "$ref": "#/$defs/record", "type": "object",
+      "allOf": [{
+        "if": { "properties": { "status": { "const": "valid" } }, "required": ["status"] },
+        "then": { "properties": { "value": {
+          "type": "object", "additionalProperties": false,
+          "required": ["schemaVersion", "owner", "fencing", "acquisitionId", "acquiredAt"],
+          "properties": {
+            "schemaVersion": { "const": 1 }, "owner": { "type": "string", "minLength": 1 },
+            "fencing": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+            "acquisitionId": { "type": "string", "pattern": "^[0-9a-f]{24}$" },
+            "acquiredAt": { "type": "string", "format": "date-time" }
+          }
+        } } }
+      }]
+    },
+    "mutationRecord": {
+      "$ref": "#/$defs/record", "type": "object",
+      "allOf": [{
+        "if": { "properties": { "status": { "const": "valid" } }, "required": ["status"] },
+        "then": { "properties": { "value": {
+          "type": "object", "additionalProperties": false,
+          "required": ["schemaVersion", "owner", "fencing", "acquisitionId", "operation", "mutationId"],
+          "properties": {
+            "schemaVersion": { "const": 1 }, "owner": { "type": "string", "minLength": 1 },
+            "fencing": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+            "acquisitionId": { "type": "string", "pattern": "^(?:[0-9a-f]{24}|recovery-claim)$" },
+            "operation": { "type": "string", "minLength": 1 },
+            "mutationId": { "type": "string", "pattern": "^[0-9a-f]{24}$" }
+          }
+        } } }
+      }]
+    },
+    "recoveryRecord": {
+      "$ref": "#/$defs/record", "type": "object",
+      "allOf": [{
+        "if": { "properties": { "status": { "const": "valid" } }, "required": ["status"] },
+        "then": { "properties": { "value": {
+          "type": "object", "additionalProperties": false, "required": ["schemaVersion", "recoveryId"],
+          "properties": { "schemaVersion": { "const": 1 }, "recoveryId": { "type": "string", "pattern": "^[0-9a-f]{24}$" } }
+        } } }
+      }]
+    }
+  }
+}

package/src/snapshot/frozen.mjs

@@ -199,9 +199,10 @@ export async function verifyFrozenDirectoryStructure(directory, label = 'frozen
  *
  * Consumption only: this never rebuilds objects and never reads the wall
  * clock. When `commitTimestamp` (the plan's `frozenSnapshot.commitTimestamp`)
- * is provided, the frozen commit's real `%aI`/`%cI` dates must match it
- * exactly, so a commit carrying any other author/committer time can never
- * pass pre-publish verification.
+ * is provided, the plan canonical form remains `+00:00`. Git may read the
+ * same UTC instant back as `Z` via `%aI`/`%cI`. Both sides pass through
+ * `normalizeGitTimestamp` before comparison, so a commit carrying any other
+ * author/committer instant can never pass pre-publish verification.
  */
 export async function verifyFrozenGitRepository({
   root,
@@ -225,13 +226,15 @@ export async function verifyFrozenGitRepository({
       ['--git-dir', gitDir, 'show', '-s', '--format=%aI%n%cI', commit],
       { shell: false },
     );
-    const [authorDate, committerDate] = datesOut.trim().split('\n');
+    const [rawAuthorDate, rawCommitterDate] = datesOut.trim().split('\n');
+    const authorDate = normalizeGitTimestamp(rawAuthorDate, 'frozen commit author date');
+    const committerDate = normalizeGitTimestamp(rawCommitterDate, 'frozen commit committer date');
     if (authorDate !== expectedTimestamp || committerDate !== expectedTimestamp) {
       throw frozenError('frozen git commit dates do not match the plan freeze timestamp', {
         commit,
         expectedTimestamp,
-        observedAuthorDate: authorDate,
-        observedCommitterDate: committerDate,
+        observedAuthorDate: rawAuthorDate,
+        observedCommitterDate: rawCommitterDate,
       });
     }
   }
@@ -314,9 +317,10 @@ const GIT_ISO8601_STRICT_RE =
  *
  * The value must be a non-empty, strict ISO 8601 timestamp with an explicit UTC
  * offset and a parseable calendar date. It is normalized to UTC with second
- * precision and a `+00:00` offset, which is exactly the form Git stores and
- * re-emits via `%aI`/`%cI`. Missing, empty, malformed, or out-of-range values
- * throw a closed `GATE_FAILED` error.
+ * precision and a `+00:00` offset. The plan canonical form remains `+00:00`.
+ * Git may read the same UTC instant back as `Z` via `%aI`/`%cI`; both sides
+ * pass through `normalizeGitTimestamp` before comparison. Missing, empty,
+ * malformed, or out-of-range values throw a closed `GATE_FAILED` error.
  *
  * Normalization is idempotent: re-normalizing an already-canonical value returns
  * the identical string, so prepare and the Git builder always agree byte-for-byte.
@@ -399,11 +403,12 @@ function publicGitRemote({ repo, githubHost = 'github.com' }) {
  * `commitTimestamp` is the plan freeze timestamp sampled exactly once during
  * production prepare. It is strictly validated BEFORE any filesystem or Git
  * write (missing, empty, malformed, or impossible values fail closed), then
- * written verbatim to both GIT_AUTHOR_DATE and GIT_COMMITTER_DATE, so the
- * frozen commit's `%aI` and `%cI` always equal the plan's
- * `frozenSnapshot.commitTimestamp` byte-for-byte. Identical inputs therefore
- * yield identical tree and commit identifiers, and a different freeze
- * timestamp alone yields a different commit with an identical tree.
+ * written verbatim to both GIT_AUTHOR_DATE and GIT_COMMITTER_DATE. The plan
+ * canonical form remains `+00:00`. Git may read the same UTC instant back as
+ * `Z` via `%aI`/`%cI`; both sides pass through `normalizeGitTimestamp` before
+ * comparison. Identical inputs therefore yield identical tree and commit
+ * identifiers, and a different freeze timestamp alone yields a different
+ * commit with an identical tree.
  */
 export async function buildFrozenGitRepository({
   snapshotDir,

package/src/core/run-retention.mjs

@@ -1,227 +0,0 @@
-/** Best-effort cleanup of superseded, complete production run lineages. */
-
-import { lstat, readFile, readdir, realpath, rm as fsRm } from 'node:fs/promises';
-import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import { resolveContained } from 'skill-family-harness-node';
-import { assertImmutablePlanAuthority, computePlanDigest, validatePlan } from './plan.mjs';
-import { loadRun, validateRunCheckpointMapping, validateRunLineage, validateRunPlanDigest } from './run.mjs';
-import { normalizePostPublishView, postPublishActionId } from './postpublish.mjs';
-
-const NON_TERMINAL = new Set(['PUBLISHING', 'PARTIAL', 'NEEDS_INPUT', 'BLOCKED', 'DISTRIBUTING']);
-const COMPLETED_CHECKPOINTS = new Set(['succeeded', 'skipped']);
-
-function validDirectName(name) {
-  return typeof name === 'string' && name.length > 0 && name !== '.' && name !== '..'
-    && !isAbsolute(name) && !name.includes('/') && !name.includes('\\');
-}
-
-async function jsonFile(path) {
-  try { return JSON.parse(await readFile(path, 'utf8')); } catch { return null; }
-}
-
-async function physicalContained(root, declaredPath) {
-  if (typeof declaredPath !== 'string' || !isAbsolute(declaredPath)) return null;
-  const lexicalRoot = resolve(root);
-  const physicalRoot = await realpath(lexicalRoot);
-  const lexical = relative(lexicalRoot, resolve(declaredPath));
-  if (!lexical || isAbsolute(lexical) || lexical === '..' || lexical.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)) return null;
-  try {
-    const contained = await resolveContained(lexicalRoot, lexical);
-    const target = await realpath(contained);
-    const targetRel = relative(physicalRoot, target);
-    if (!targetRel || isAbsolute(targetRel) || targetRel === '..' || targetRel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)) return null;
-    return target;
-  } catch { return null; }
-}
-
-async function loadPlanFromRun(releaseDir, run) {
-  if (!run?.planPath) return null;
-  const planPath = await physicalContained(releaseDir, run.planPath);
-  if (!planPath || basename(dirname(planPath)) !== 'plans') return null;
-  const plan = await jsonFile(planPath);
-  if (!plan) return null;
-  try {
-    validatePlan(plan);
-    assertImmutablePlanAuthority(planPath, plan);
-    const digest = computePlanDigest(plan);
-    if (run.planDigest !== digest || basename(planPath) !== `${digest}.json`) return null;
-    return { plan, planPath, digest };
-  } catch { return null; }
-}
-
-function postVerifyActions(plan) {
-  return normalizePostPublishView(plan).flatMap((declaration) => (
-    (declaration.hooks ?? []).filter((hook) => hook.phase === 'postVerify').map((hook) => ({
-      id: postPublishActionId({ planVersion: plan.planVersion, unitId: declaration.unitId, localId: hook.id }),
-      type: 'postpublish-hook',
-    }))
-  ));
-}
-
-function postVerificationComplete(run) {
-  return run.checkpoints.every((checkpoint) => (
-    checkpoint.status === 'succeeded' || checkpoint.status === 'NO_CHANGE'
-  ));
-}
-
-function publicationComplete(run) {
-  return run.checkpoints.every((cp) => COMPLETED_CHECKPOINTS.has(cp.status)
-    || (['failed', 'deferred'].includes(cp.status)
-      && ['claude-marketplace-install', 'codex-marketplace-install', 'kimi-marketplace-install', 'codebuddy-marketplace-install', 'qoder-marketplace-install'].includes(cp.actionType)));
-}
-
-async function lineagePathsContained(run, runsRoot) {
-  let cursor = run;
-  for (let depth = 0; depth < 32; depth += 1) {
-    if (!cursor.sourceRunPath) return true;
-    const sourcePath = await physicalContained(runsRoot, cursor.sourceRunPath);
-    if (!sourcePath) return false;
-    cursor = await loadRun(sourcePath, { requireDigest: true });
-  }
-  return false;
-}
-
-async function validatePublicationCheckpoints(run, plan, runsRoot) {
-  let cursor = run;
-  for (let depth = 0; depth < 32; depth += 1) {
-    if (cursor.command === 'publish') {
-      validateRunCheckpointMapping(cursor, plan.externalActions ?? []);
-      return cursor.status === 'PUBLISHED' ? publicationComplete(cursor) : true;
-    }
-    if (!cursor.sourceRunPath) return false;
-    const sourcePath = await physicalContained(runsRoot, cursor.sourceRunPath);
-    if (!sourcePath) return false;
-    cursor = await loadRun(sourcePath, { requireDigest: true });
-    if (cursor.command === 'reconcile') validateRunCheckpointMapping(cursor, plan.externalActions ?? []);
-  }
-  return false;
-}
-
-async function validateTerminal({ candidate, planInfo, runsRoot }) {
-  const { run, runPath } = candidate;
-  if (!run || !planInfo) return false;
-  const { plan, planPath } = planInfo;
-  try {
-    if (!(await lineagePathsContained(run, runsRoot))) return false;
-    await validateRunLineage(run, { plan, planPath, runPath, production: Boolean(plan.production) });
-    validateRunPlanDigest(run, plan, { planPath });
-    if (run.command === 'verify' && run.status === 'VERIFIED') {
-      return validatePublicationCheckpoints(run, plan, runsRoot);
-    }
-    if (run.command !== 'postverify' || run.status !== 'DISTRIBUTED') return false;
-    validateRunCheckpointMapping(run, postVerifyActions(plan));
-    return postVerificationComplete(run)
-      && validatePublicationCheckpoints(run, plan, runsRoot);
-  } catch { return false; }
-}
-
-async function scanCandidate(runsRoot, name) {
-  const dir = join(runsRoot, name);
-  const summary = await jsonFile(join(dir, 'summary.json'));
-  const runPath = join(dir, 'release-run.json');
-  let run = null;
-  let runExists = false;
-  let runCorrupt = false;
-  try {
-    const stat = await lstat(runPath);
-    runExists = true;
-    if (stat.isSymbolicLink() || !stat.isFile()) runCorrupt = true;
-    else run = await loadRun(runPath, { requireDigest: true });
-  } catch { if (runExists) runCorrupt = true; }
-  const statesExists = await lstat(join(dir, 'states')).then(() => true).catch(() => false);
-  let sealedFailedPrepare = false;
-  if (summary?.status === 'FAILED' && !runExists) {
-    try {
-      const evidence = await readFile(join(dir, 'evidence.jsonl'), 'utf8');
-      sealedFailedPrepare = evidence.split('\n').some((line) => JSON.parse(line)?.command === 'prepare');
-    } catch { sealedFailedPrepare = false; }
-  }
-  return {
-    dir, name, summary, run, runPath, runExists, runCorrupt, statesExists, sealedFailedPrepare,
-    planDigest: run?.planDigest ?? summary?.planDigest ?? null,
-  };
-}
-
-async function deleteCandidate(runsRoot, candidate, rmFn) {
-  const contained = await physicalContained(runsRoot, join(runsRoot, candidate.name));
-  const physicalRoot = await realpath(runsRoot);
-  if (!contained || dirname(contained) !== physicalRoot) throw new Error('run path containment failed');
-  const stat = await lstat(contained);
-  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('run candidate is not a real directory');
-  await rmFn(contained, { recursive: true, force: false });
-}
-
-/** @returns {Promise<{scanned:number,deleted:number,errors:number,diagnostics:Array}>} */
-export async function cleanupRunRetention({ releaseDir, currentRunDir, rmFn = fsRm } = {}) {
-  const result = { scanned: 0, deleted: 0, errors: 0, diagnostics: [] };
-  if (!releaseDir) return result;
-  const runsRoot = resolve(releaseDir, 'runs');
-  let rootStat;
-  try { rootStat = await lstat(runsRoot); } catch { return result; }
-  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) return result;
-  const physicalRunsRoot = await realpath(runsRoot).catch(() => null);
-  if (!physicalRunsRoot) return result;
-  let entries;
-  try { entries = await readdir(physicalRunsRoot, { withFileTypes: true }); } catch { return result; }
-  const candidates = [];
-  for (const entry of entries) {
-    result.scanned += 1;
-    if (!entry.isDirectory() || entry.isSymbolicLink() || !validDirectName(entry.name)) continue;
-    candidates.push(await scanCandidate(physicalRunsRoot, entry.name));
-  }
-  const protectedNames = new Set();
-  if (currentRunDir) protectedNames.add(basename(resolve(currentRunDir)));
-  const currentPlan = await jsonFile(join(releaseDir, 'release-plan.json'));
-  let currentPlanDigest = null;
-  try { if (currentPlan) currentPlanDigest = computePlanDigest(currentPlan); } catch { currentPlanDigest = null; }
-  const groups = new Map();
-  for (const candidate of candidates) {
-    if (!candidate.planDigest) continue;
-    if (!groups.has(candidate.planDigest)) groups.set(candidate.planDigest, []);
-    groups.get(candidate.planDigest).push(candidate);
-    if (currentPlanDigest && candidate.planDigest === currentPlanDigest) protectedNames.add(candidate.name);
-  }
-  const completeGroups = [];
-  for (const [planDigest, group] of groups) {
-    const authority = group.find((item) => item.run?.planDigest === planDigest);
-    const planInfo = authority ? await loadPlanFromRun(releaseDir, authority.run) : null;
-    const requiresPostVerify = Boolean(planInfo && normalizePostPublishView(planInfo.plan)
-      .some((declaration) => (declaration.hooks ?? []).some((hook) => hook.phase === 'postVerify')));
-    const terminals = group.filter((item) => requiresPostVerify
-      ? item.run?.status === 'DISTRIBUTED'
-      : item.run?.status === 'VERIFIED');
-    const terminalResults = planInfo
-      ? await Promise.all(terminals.map((item) => validateTerminal({ candidate: item, planInfo, runsRoot })))
-      : [];
-    const terminalValid = terminalResults.some(Boolean);
-    const unsafe = group.some((item) => item.runCorrupt
-      || (!item.run && item.summary?.status !== 'PREPARED')
-      || (item.run && NON_TERMINAL.has(item.run.status))
-      || (item.run?.status === 'PUBLISHED' && !publicationComplete(item.run))
-      || (item.run && ((requiresPostVerify && item.run.status === 'DISTRIBUTED')
-        || (!requiresPostVerify && item.run.status === 'VERIFIED'))
-        && !terminalResults[terminals.indexOf(item)]));
-    if (!terminalValid || unsafe) {
-      for (const item of group) protectedNames.add(item.name);
-    } else {
-      completeGroups.push({ group, createdAt: planInfo.plan.createdAt ?? '', planDigest });
-    }
-  }
-  completeGroups.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)) || b.planDigest.localeCompare(a.planDigest));
-  for (const old of completeGroups.slice(1)) {
-    for (const item of old.group) {
-      if (protectedNames.has(item.name)) continue;
-      try { await deleteCandidate(physicalRunsRoot, item, rmFn); result.deleted += 1; }
-      catch (error) { result.errors += 1; result.diagnostics.push({ name: item.name, code: error?.code ?? 'RUN_RETENTION_DELETE_FAILED' }); }
-    }
-  }
-  for (const candidate of candidates) {
-    const hasPlanTrace = Boolean(candidate.planDigest || candidate.summary?.planPath || candidate.summary?.externalActions || candidate.summary?.checkpoints);
-    const isFailedPrepare = candidate.name.startsWith('prepare-') && candidate.summary?.status === 'FAILED'
-      && candidate.sealedFailedPrepare && !candidate.runExists && !candidate.statesExists && !hasPlanTrace;
-    if (!isFailedPrepare || protectedNames.has(candidate.name)) continue;
-    try { await deleteCandidate(physicalRunsRoot, candidate, rmFn); result.deleted += 1; }
-    catch (error) { result.errors += 1; result.diagnostics.push({ name: candidate.name, code: error?.code ?? 'RUN_RETENTION_DELETE_FAILED' }); }
-  }
-  return result;
-}