owlrunkit 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.25.0
+
+- Adds opt-in same-host peer recovery for macOS-contained workers. A cooperating
+  agent can request a wake, observe a fresh correlated checkpoint, or continue
+  from the last checkpoint as the designated successor.
+- Records a single successor generation and rejects writes and checkpoint
+  submissions from the superseded attempt. Recovery remains scoped to the
+  managed task and preserves the existing manual path for legacy leases.
+- Retains 0.24.1 as the exact published rollback baseline.
+
 ## 0.24.1
 
 - Corrects the optional Stop hook to notify on RunKit data file changes, including

package/README.md

@@ -136,7 +136,7 @@ separate authority boundaries.
 
 ## Install
 
-This package is the lifecycle-stable, registry-gated `owlrunkit@0.24.1`
+This package is the lifecycle-stable, registry-gated `owlrunkit@0.25.0`
 artifact. Registry adoption remains fail-closed until its exact official npm
 version, shasum, integrity, and tarball URL are independently verified. Local
 tarballs remain candidate-test inputs and are never adoption provenance. Until
@@ -144,7 +144,7 @@ that registry evidence exists, use the package only for isolated candidate
 verification; do not treat the command below as available release truth.
 
 ```bash
-npm install --save-exact owlrunkit@0.24.1
+npm install --save-exact owlrunkit@0.25.0
 ```
 
 Use `npx --no-install owlrunkit` for project commands. The package bootstrap
@@ -160,9 +160,9 @@ the project Config must independently bind the same Core.
 ```bash
 npx --no-install owlrunkit --version
 npx --no-install owlrunkit bootstrap --workspace /absolute/path/to/project \
-  --exact owlrunkit@0.24.1 --dry-run
+  --exact owlrunkit@0.25.0 --dry-run
 npx --no-install owlrunkit bootstrap --workspace /absolute/path/to/project \
-  --exact owlrunkit@0.24.1 --apply
+  --exact owlrunkit@0.25.0 --apply
 npx --no-install owlrunkit init --workspace /absolute/path/to/project
 npx --no-install owlrunkit doctor --workspace /absolute/path/to/project
 npx --no-install owlrunkit inspect --workspace /absolute/path/to/project --json --compact
@@ -995,6 +995,55 @@ Installing the package enables nothing and changes no global configuration,
 shared Skill or other workspace. This is same-session synchronous Stop
 continuation; fully idle Desktop wake requires a separate supported ingress.
 
+## Managed local peer recovery
+
+On macOS, opt a new task into peer recovery before starting its writer. The
+project controller names the current agent, successor, and exact checkpoint
+paths in `peer.json`, for example:
+
+```json
+{"owner":"alpha","successor":"bravo","paths":["result.txt"]}
+```
+
+```bash
+npx --no-install owlrunkit peer create --workspace . --task repair --request peer.json
+npx --no-install owlrunkit peer run --workspace . --task repair --agent alpha --generation 1 -- /absolute/worker
+npx --no-install owlrunkit peer inspect --workspace . --task repair
+npx --no-install owlrunkit peer recover --workspace . --task repair --agent bravo --generation 1 --revision 2
+```
+
+Run the last two commands from the cooperating agent while it is investigating
+an interruption. Use the actual generation and revision returned by `inspect`.
+Recovery requests a wake from the current worker. A matching, changed checkpoint
+keeps that worker in charge. If wake remains unconfirmed after the bounded wait,
+recovery can move ownership to the designated successor because the current
+attempt already runs in an isolated directory. One durable revision binds the
+successor generation to the last accepted checkpoint. The successor explicitly
+runs its own worker using that generation. An ACK or timeout is not a proof of
+worker death. Retry the same observed revision to read back a race or recovery.
+
+Use a local worker that speaks newline-delimited JSON. RunKit seeds the attempt
+directory from the previous checkpoint and sets `OWLRUNKIT_PEER_PATHS` to the
+ordered path array. The worker reads a wake challenge from stdin as
+`{"type":"wake","wakeId":"..."}`. Stdout is reserved for protocol messages.
+Report work as `{"type":"checkpoint","wakeId":"...","files":[{"path":"result.txt","content":"..."}]}`.
+Use the wake ID only when reporting progress in response to that challenge.
+The `files` array covers the exact ordered paths, with canonical base64 bytes
+or `null` for a missing file. The decoded checkpoint limit is 1 MiB. Emit
+`finish` with the same `files` shape to record the result. Human diagnostics
+go to stderr. `inspect` returns the checkpoint path and hash for handoff and
+review. Only accepted checkpoints seed the next attempt, and the previous
+scratch directory is reported for inspection while it remains on disk.
+
+The macOS backend confines each worker's writes to its own attempt and denies
+network and additional processes. The host caller explicitly authorizes the
+worker command, and supplies the peer identity. This is a supported boundary
+for contained workers and their checkpoints. An unmanaged file lease, a raw
+shared-directory writer, or an existing Desktop session needs its own recovery
+procedure. Legacy lease records and `control.lock` are untouched. The result
+is task evidence for the existing acceptance process. Canonical source
+integration remains a separate authorized step.
+
 ## Shared Skill upgrades
 
 Process-wide Codex Skill updates automatically use the registered fleet:

package/integrations/codex/skills/owlcoda-runkit/SKILL.md

@@ -7,18 +7,29 @@ description: Run receipt-backed, project-owned work with OwlCoda RunKit. Use whe
 
 Use the bundled deterministic Core to coordinate work through project artifacts rather than chat memory. Require Node.js 20 or later.
 
-Bundled registry-gated artifact: standalone `owlrunkit@0.24.1`, bundling Contract
-`0.2` and Core `0.24.1` with manifest
-`sha256:94aaa2e3a6d504374fa78cfcd341e31b33087806c9ddf5f84b3d3b47a6328e08`.
+Bundled registry-gated artifact: standalone `owlrunkit@0.25.0`, bundling Contract
+`0.2` and Core `0.25.0` with manifest
+`sha256:20e75c386f1408f11e908a6d3ee1a39316d9728d5719fa06f8d6a5aa45abd83e`.
 Registry adoption remains fail-closed until exact official npm registry
-provenance for `owlrunkit@0.24.1` is independently verified. The
-published rollback baseline for this artifact is `owlrunkit@0.24.0`, with SHA-1
-`9408b579faf58f85a3e8d7bd3d64c34256f85fe8` and canonical npm tarball URL
-`https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.24.0.tgz`.
+provenance for `owlrunkit@0.25.0` is independently verified. The
+published rollback baseline for this artifact is `owlrunkit@0.24.1`, with SHA-1
+`b70b857c128f67d19d401acaa096a6cf9f1f348e` and canonical npm tarball URL
+`https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.24.1.tgz`.
 The root `owlcoda` package has a separate version lifecycle.
 
 The session is an execution interface. Project artifacts are the system of record.
 
+## Optional managed local peer recovery
+
+For a task already enrolled in `owlrunkit peer` with an isolated worker, inspect
+the task when your cooperating agent stops progressing. As the designated
+successor, run `peer recover` with the observed generation and revision. A
+new checkpoint tied to the wake challenge keeps the original agent active.
+When recovery grants a successor generation, explicitly run the authorized
+worker in that generation and resume from its seeded checkpoint. Treat an ACK
+without progress as unconfirmed. Keep legacy shared-workspace leases on the
+manual recovery path. Use the package README and `peer --help` for setup.
+
 ## Optional file-event continuation
 
 RunKit includes `scripts/runkit-contract/file-event-stop-hook.mjs` for an
@@ -357,9 +368,9 @@ below has no CLI entry.
 
 ```bash
 npx --no-install owlrunkit bootstrap --workspace "$PROJECT_ROOT" \
-  --exact owlrunkit@0.24.1 --dry-run
+  --exact owlrunkit@0.25.0 --dry-run
 npx --no-install owlrunkit bootstrap --workspace "$PROJECT_ROOT" \
-  --exact owlrunkit@0.24.1 --apply
+  --exact owlrunkit@0.25.0 --apply
 npx --no-install owlrunkit init --workspace "$PROJECT_ROOT"
 npx --no-install owlrunkit inspect --json --workspace "$PROJECT_ROOT"
 npx --no-install owlrunkit inspect --json --compact --workspace "$PROJECT_ROOT"

package/integrations/codex/skills/owlcoda-runkit/assets/templates/config.json

@@ -2,9 +2,9 @@
   "schemaVersion": "OwlCodaRunKitConfigV2",
   "core": {
     "contractVersion": "0.2",
-    "coreVersion": "0.24.1",
-    "coreManifestSha256": "sha256:94aaa2e3a6d504374fa78cfcd341e31b33087806c9ddf5f84b3d3b47a6328e08",
-    "coreSourceRef": "artifact:sha256:94aaa2e3a6d504374fa78cfcd341e31b33087806c9ddf5f84b3d3b47a6328e08"
+    "coreVersion": "0.25.0",
+    "coreManifestSha256": "sha256:20e75c386f1408f11e908a6d3ee1a39316d9728d5719fa06f8d6a5aa45abd83e",
+    "coreSourceRef": "artifact:sha256:20e75c386f1408f11e908a6d3ee1a39316d9728d5719fa06f8d6a5aa45abd83e"
   },
   "authorizationPolicy": "external_explicit_authority_required"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "owlrunkit",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Project Driver for cross-Agent project continuity and progression; execution, evidence, verification, and recovery are the underlying trust substrate.",
   "license": "GPL-3.0-or-later",
   "author": "yeemio <owlclaw@163.com>",

package/packages/attest/distribution-manifest-v1.json

@@ -42,6 +42,11 @@
     "sha256": "sha256:3972dc9744f6499f0f9b2dbf76696f2ae7ad8af9b23dde66d6af86c9dfb36986"
   },
   "supportedProducerCoreIdentities": [
+    {
+      "contractVersion": "0.2",
+      "coreVersion": "0.25.0",
+      "coreManifestSha256": "sha256:20e75c386f1408f11e908a6d3ee1a39316d9728d5719fa06f8d6a5aa45abd83e"
+    },
     {
       "contractVersion": "0.2",
       "coreVersion": "0.24.1",

package/packages/attest/src/quick.mjs

@@ -23,6 +23,11 @@ import {
 export { validQuickReceiptShape } from "./quick-receipt-contract.mjs";
 
 export const SUPPORTED_QUICK_CORE_IDENTITIES = Object.freeze([
+  {
+    contractVersion: "0.2",
+    coreVersion: "0.25.0",
+    coreManifestSha256: "sha256:20e75c386f1408f11e908a6d3ee1a39316d9728d5719fa06f8d6a5aa45abd83e",
+  },
   {
     contractVersion: "0.2",
     coreVersion: "0.24.1",

package/registry-release-policy-v2.json

@@ -2,7 +2,7 @@
   "schemaVersion": "OwlCodaRunKitRegistryReleasePolicyV2",
   "status": "release_artifact_registry_gated",
   "packageName": "owlrunkit",
-  "artifactVersion": "0.24.1",
+  "artifactVersion": "0.25.0",
   "registry": "https://registry.npmjs.org",
   "registryRequiredBeforeAdoption": true,
   "exactVersionRequired": true,
@@ -23,10 +23,10 @@
   ],
   "rollbackRelease": {
     "packageName": "owlrunkit",
-    "version": "0.24.0",
-    "shasum": "9408b579faf58f85a3e8d7bd3d64c34256f85fe8",
-    "integrity": "sha512-AbivZPDxYhOCxemfsT8Q01P6igKCed2P0V15kSzhrNLW548aHqUmIHVmvdZOnvWI/f8p5YBe53cVa4wRq8O1lg==",
-    "tarballUrl": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.24.0.tgz"
+    "version": "0.24.1",
+    "shasum": "b70b857c128f67d19d401acaa096a6cf9f1f348e",
+    "integrity": "sha512-8Fr5XTAbtRlxyYboDSB8C257sxSWWiAFqGU6yexF99NXgilJ3pbxtMwq4FcbrlHN5V6yJLME04vTceI2s9F4bA==",
+    "tarballUrl": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.24.1.tgz"
   },
   "registryEvidenceMustBeExternal": true,
   "registryEvidenceSchemaVersion": "OwlCodaRunKitRegistryReleaseEvidenceV1",

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "owlrunkit-0.24.1",
-  "documentNamespace": "https://owlcoda.com/spdx/owlrunkit/0.24.1",
+  "name": "owlrunkit-0.25.0",
+  "documentNamespace": "https://owlcoda.com/spdx/owlrunkit/0.25.0",
   "creationInfo": {
-    "created": "2026-10-08T00:00:00Z",
+    "created": "2026-11-11T00:00:00Z",
     "creators": [
       "Organization: OwlCoda"
     ]
@@ -14,7 +14,7 @@
     {
       "name": "owlrunkit",
       "SPDXID": "SPDXRef-Package-OwlRunKit",
-      "versionInfo": "0.24.1",
+      "versionInfo": "0.25.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "GPL-3.0-or-later",
@@ -24,7 +24,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/owlrunkit@0.24.1"
+          "referenceLocator": "pkg:npm/owlrunkit@0.25.0"
         }
       ]
     }

package/scripts/runkit-contract/core-contract.mjs

@@ -14,7 +14,7 @@ import { fileURLToPath } from "node:url";
 import { parseProjectControlState } from "./project-control-parser.mjs";
 
 export const CONTRACT_VERSION = "0.2";
-export const CORE_VERSION = "0.24.1";
+export const CORE_VERSION = "0.25.0";
 export const RUNTIME_ROOT = ".owlcoda/runkit";
 
 const CORE_FILES = [
@@ -42,6 +42,7 @@ const CORE_FILES = [
   "lifecycle-orchestration.mjs",
   "offline-store.mjs",
   "outcome-presentation.mjs",
+  "peer-recovery.mjs",
   "onboarding-doctor.mjs",
   "onboarding-bootstrap.mjs",
   "owner-authority-trust.mjs",

package/scripts/runkit-contract/peer-recovery.mjs

@@ -0,0 +1,442 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import {
+  closeSync, constants, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync,
+  mkdtempSync, openSync, readSync, readdirSync, realpathSync, unlinkSync,
+  watch, writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { RUNTIME_ROOT, currentCoreIdentity } from "./core-contract.mjs";
+import { safeIdentifier } from "./provenance-common.mjs";
+import { resolveVerificationEnvelopeBackendV1 } from "./verification-envelope.mjs";
+
+const SCHEMA = "OwlRunKitPeerRecoveryRevisionV1";
+const CHECKPOINT_LIMIT = 1024 * 1024;
+const RECORD_LIMIT = 2 * CHECKPOINT_LIMIT;
+const MAX_REVISIONS = 4096;
+const REVISION_NAME = /^([0-9]{6})\.json$/u;
+
+function digest(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function realDirectory(ref) {
+  if (!lstatSync(ref).isDirectory() || realpathSync(ref) !== ref) {
+    throw new Error("peer_recovery_redirected_directory");
+  }
+  return ref;
+}
+
+function directoryBelow(root, segments, create) {
+  let current = root;
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    if (create && !existsSync(current)) {
+      try { mkdirSync(current, { mode: 0o700 }); }
+      catch (error) { if (error.code !== "EEXIST") throw error; }
+    }
+    realDirectory(current);
+  }
+  return current;
+}
+
+function taskDirectory(workspaceRoot, taskId, create = false) {
+  safeIdentifier(taskId, "peer recovery task");
+  const root = realpathSync(workspaceRoot);
+  const runtime = directoryBelow(root, RUNTIME_ROOT.split("/"), false);
+  const directory = directoryBelow(runtime, ["peer-recovery", taskId], create);
+  return { root, directory, taskId, core: currentCoreIdentity() };
+}
+
+function regularBytes(ref, limit) {
+  const stat = lstatSync(ref);
+  if (!stat.isFile() || stat.size > limit || realpathSync(ref) !== ref) {
+    throw new Error("peer_recovery_invalid_file");
+  }
+  const fd = openSync(ref, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const buffer = Buffer.alloc(limit + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const bytes = readSync(fd, buffer, length, buffer.length - length, null);
+      if (bytes === 0) break;
+      length += bytes;
+    }
+    if (length > limit) throw new Error("peer_recovery_file_too_large");
+    return buffer.subarray(0, length);
+  } finally { closeSync(fd); }
+}
+
+function revisionPath(task, revision) {
+  return path.join(task.directory, `${String(revision).padStart(6, "0")}.json`);
+}
+
+function readRevision(task, revision) {
+  const record = JSON.parse(regularBytes(revisionPath(task, revision), RECORD_LIMIT).toString("utf8"));
+  if (record.schemaVersion !== SCHEMA || record.workspaceRoot !== task.root
+    || record.taskId !== task.taskId || record.revision !== revision
+    || record.authorizationGranted !== false || !Number.isSafeInteger(record.generation)
+    || record.generation < 1 || !Number.isSafeInteger(record.checkpointRevision)
+    || record.checkpointRevision < 1 || record.checkpointRevision > revision
+    || !["ready", "running", "exited", "completed"].includes(record.phase)
+    || JSON.stringify(validatePaths(record.paths)) !== JSON.stringify(record.paths)) {
+    throw new Error("peer_recovery_revision_invalid");
+  }
+  if (record.core?.coreManifestSha256 !== task.core.coreManifestSha256
+    || record.core?.coreVersion !== task.core.coreVersion) {
+    throw new Error("peer_recovery_core_pin_mismatch");
+  }
+  safeIdentifier(record.owner, "recorded current peer");
+  safeIdentifier(record.successor, "recorded successor peer");
+  return record;
+}
+
+function current(task) {
+  const revisions = readdirSync(task.directory).map(name => REVISION_NAME.exec(name))
+    .filter(Boolean).map(match => Number(match[1])).sort((a, b) => a - b);
+  if (revisions.length === 0) throw new Error("peer_recovery_task_uninitialized");
+  if (revisions.some((revision, index) => revision !== index + 1)) {
+    throw new Error("peer_recovery_revision_gap");
+  }
+  return readRevision(task, revisions.length);
+}
+
+// Exactly one contender can link the next revision. A crash before the link
+// leaves only ignored scratch, and after the link the whole transition is visible.
+function append(task, previous, fields) {
+  const revision = (previous?.revision ?? 0) + 1;
+  if (revision > MAX_REVISIONS) throw new Error("peer_recovery_revision_limit");
+  const record = {
+    ...previous, files: undefined, ...fields,
+    schemaVersion: SCHEMA, workspaceRoot: task.root, taskId: task.taskId, core: task.core,
+    revision, recordedAt: new Date().toISOString(), authorizationGranted: false,
+  };
+  const bytes = Buffer.from(`${JSON.stringify(record)}\n`);
+  if (bytes.length > RECORD_LIMIT) throw new Error("peer_recovery_record_too_large");
+  const scratch = path.join(task.directory, `.tmp-${randomUUID()}`);
+  const fd = openSync(scratch, "wx", 0o600);
+  try {
+    writeFileSync(fd, bytes);
+    fsyncSync(fd);
+    try { linkSync(scratch, revisionPath(task, revision)); }
+    catch (error) { if (error.code === "EEXIST") return null; throw error; }
+    const directoryFd = openSync(task.directory, "r");
+    try { fsyncSync(directoryFd); } finally { closeSync(directoryFd); }
+    return record;
+  } finally { closeSync(fd); unlinkSync(scratch); }
+}
+
+function validatePaths(paths) {
+  if (!Array.isArray(paths) || paths.length < 1 || paths.length > 64) {
+    throw new Error("peer_recovery_paths_required");
+  }
+  const normalized = paths.map(ref => {
+    if (typeof ref !== "string" || ref.length > 240 || /[\\:\p{Cc}]/u.test(ref)
+      || ref.split("/").some(part => !part || part === "." || part === ".."
+        || /^(?:\.git|\.owlcoda|node_modules)$/iu.test(part))) {
+      throw new Error("peer_recovery_invalid_path");
+    }
+    return ref;
+  }).sort();
+  const folded = normalized.map(ref => ref.normalize("NFC").toLowerCase()).sort();
+  if (folded.some((ref, index) => index && (ref === folded[index - 1]
+    || folded.some(parent => ref.startsWith(`${parent}/`))))) {
+    throw new Error("peer_recovery_overlapping_paths");
+  }
+  return normalized;
+}
+
+function checkedFiles(paths, input) {
+  if (!Array.isArray(input) || input.length !== paths.length) {
+    throw new Error("peer_recovery_checkpoint_paths_mismatch");
+  }
+  let bytes = 0;
+  const files = paths.map((ref, index) => {
+    const item = input[index];
+    if (item?.path !== ref || (item.content !== null && typeof item.content !== "string")) {
+      throw new Error("peer_recovery_checkpoint_paths_mismatch");
+    }
+    if (item.content !== null) {
+      const content = Buffer.from(item.content, "base64");
+      if (content.toString("base64") !== item.content) throw new Error("peer_recovery_checkpoint_base64_invalid");
+      bytes += content.length;
+      if (bytes > CHECKPOINT_LIMIT) throw new Error("peer_recovery_checkpoint_too_large");
+    }
+    return { path: ref, content: item.content };
+  });
+  return { files, sha256: digest(JSON.stringify(files)) };
+}
+
+function initialFile(root, ref) {
+  const target = path.join(root, ref);
+  try {
+    const content = regularBytes(target, CHECKPOINT_LIMIT).toString("base64");
+    return { path: ref, content };
+  } catch (error) {
+    if (error.code === "ENOENT") return { path: ref, content: null };
+    throw error;
+  }
+}
+
+function checkpoint(task, state) {
+  const source = readRevision(task, state.checkpointRevision);
+  const result = checkedFiles(state.paths, source.files);
+  if (result.sha256 !== state.checkpointSha256) throw new Error("peer_recovery_checkpoint_drift");
+  return result;
+}
+
+function projection(task, state) {
+  const { files: _files, ...record } = state;
+  return {
+    ...record, checkpointPath: revisionPath(task, state.checkpointRevision),
+    status: state.event, exitCode: 0, authorizationGranted: false,
+  };
+}
+
+function requireBackend() {
+  const backend = resolveVerificationEnvelopeBackendV1();
+  if (!backend.available) throw new Error("peer_recovery_enforced_backend_unavailable");
+  return backend;
+}
+
+export function createPeerRecoveryTask({ workspaceRoot, taskId, owner, successor, paths }) {
+  requireBackend();
+  safeIdentifier(owner, "initial peer");
+  safeIdentifier(successor, "successor peer");
+  if (owner === successor) throw new Error("peer_recovery_requires_distinct_peers");
+  const ownedPaths = validatePaths(paths);
+  const root = realpathSync(workspaceRoot);
+  const initial = checkedFiles(ownedPaths, ownedPaths.map(ref => initialFile(root, ref)));
+  const task = taskDirectory(root, taskId, true);
+  const created = append(task, null, {
+    generation: 1, owner, successor, paths: ownedPaths, phase: "ready", attempt: null,
+    wake: null, event: "peer_task_ready", checkpointRevision: 1,
+    checkpointSha256: initial.sha256, files: initial.files,
+  });
+  if (!created) throw new Error("peer_recovery_task_already_exists");
+  return projection(task, created);
+}
+
+export function inspectPeerRecoveryTask({ workspaceRoot, taskId }) {
+  const task = taskDirectory(workspaceRoot, taskId);
+  return projection(task, current(task));
+}
+
+function observe(task, examine, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let watcher, timer, settled = false;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      watcher?.close();
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const check = () => {
+      try {
+        const value = examine(current(task));
+        if (value) finish(null, value);
+      } catch (error) { finish(error); }
+    };
+    try {
+      watcher = watch(task.directory, check);
+      watcher.once("error", finish);
+      timer = setTimeout(() => { check(); finish(null, null); }, timeoutMs);
+      check();
+    } catch (error) { finish(error); }
+  });
+}
+
+export async function recoverPeerTask({ workspaceRoot, taskId, agent, generation, revision, waitMs = 5000 }) {
+  requireBackend();
+  safeIdentifier(agent, "successor peer");
+  if (!Number.isSafeInteger(generation) || generation < 1 || !Number.isSafeInteger(revision)
+    || revision < 1 || !Number.isInteger(waitMs)
+    || waitMs < 100 || waitMs > 60000) throw new Error("peer_recovery_invalid_request");
+  const task = taskDirectory(workspaceRoot, taskId);
+  let requestedWakeId;
+  for (;;) {
+    const state = current(task);
+    if (state.generation !== generation) {
+      if (state.generation === generation + 1 && state.owner === agent) return projection(task, state);
+      throw new Error("peer_recovery_generation_changed");
+    }
+    if (state.successor !== agent) throw new Error("peer_recovery_successor_mismatch");
+    if (state.phase === "completed") return projection(task, state);
+    if (state.wake?.observed && (state.wake.id === requestedWakeId
+      || state.wake.requestedFromRevision === revision)) return projection(task, state);
+    if (state.phase === "running" && (!state.wake || state.wake.observed)) {
+      if (state.revision !== revision) throw new Error("peer_recovery_observation_stale");
+      const wake = { id: randomUUID(), requestedFromRevision: revision,
+        deadline: Date.now() + waitMs, observed: false };
+      if (append(task, state, { wake, event: "peer_wake_requested" })) requestedWakeId = wake.id;
+      continue;
+    }
+    if (state.wake && !state.wake.observed && state.wake.requestedFromRevision === revision) {
+      requestedWakeId = state.wake.id;
+    }
+    if (state.revision !== revision && (!requestedWakeId || state.wake?.id !== requestedWakeId)) {
+      throw new Error("peer_recovery_observation_stale");
+    }
+    if (state.phase === "running" && Date.now() < state.wake.deadline) {
+      requestedWakeId = state.wake.id;
+      await observe(task, next => next.generation !== generation || next.phase !== "running"
+        || next.wake?.id !== requestedWakeId || next.wake.observed,
+      Math.max(1, state.wake.deadline - Date.now()));
+      continue;
+    }
+    checkpoint(task, state);
+    const replacement = append(task, state, {
+      owner: agent, successor: state.owner, generation: generation + 1,
+      phase: "ready", attempt: null, wake: null, processExit: null, event: "peer_takeover_ready",
+      recovery: {
+        fromGeneration: generation, fromAgent: state.owner, previousAttempt: state.attempt,
+        wakeId: state.wake?.id ?? null,
+        evidence: state.phase === "running" ? "wake_unconfirmed_isolated"
+          : state.phase === "exited" ? "managed_process_exited" : "attempt_not_started",
+      },
+    });
+    if (replacement) return projection(task, replacement);
+  }
+}
+
+function materialize(files, directory) {
+  for (const file of files) {
+    if (file.content === null) continue;
+    const ref = path.join(directory, file.path);
+    mkdirSync(path.dirname(ref), { recursive: true, mode: 0o700 });
+    writeFileSync(ref, Buffer.from(file.content, "base64"), { flag: "wx", mode: 0o600 });
+  }
+}
+
+function sandboxPolicy(executable, directory) {
+  // Only the host process receives control-store access. The worker inherits
+  // pipes, never a writable descriptor into the project or the next attempt.
+  return [
+    "(version 1)", "(allow default)", "(deny file-write*)", "(deny file-read-data)",
+    `(allow file-read-data file-write* (subpath ${JSON.stringify(directory)}))`,
+    `(allow file-read-data (literal ${JSON.stringify(executable)}))`,
+    '(allow file-read-data (literal "/") (subpath "/System") (subpath "/usr/lib"))',
+    "(deny network*)", "(deny mach-lookup)", "(deny signal)", "(deny process-fork)", "(deny process-exec)",
+    `(allow process-exec (literal ${JSON.stringify(executable)}))`,
+  ].join("\n");
+}
+
+function reportCheckpoint(task, attemptId, message) {
+  for (;;) {
+    const state = current(task);
+    if (state.phase !== "running" || state.attempt?.id !== attemptId) return false;
+    const value = checkedFiles(state.paths, message.files);
+    const finish = message.type === "finish";
+    const changed = value.sha256 !== state.checkpointSha256;
+    if (!finish && !changed) return true;
+    const observed = changed && state.wake?.id === message.wakeId && state.wake !== null;
+    if (append(task, state, {
+      files: value.files, checkpointRevision: state.revision + 1, checkpointSha256: value.sha256,
+      wake: observed ? { ...state.wake, observed: true } : state.wake,
+      phase: finish ? "completed" : "running",
+      event: finish ? "peer_task_completed" : observed ? "peer_wake_progress_observed" : "peer_checkpoint_recorded",
+    })) return true;
+  }
+}
+
+function reportExit(task, attemptId, processExit) {
+  for (;;) {
+    const state = current(task);
+    if (state.attempt?.id !== attemptId) {
+      return { ...projection(task, state), status: "peer_attempt_superseded", exitCode: 2 };
+    }
+    if (state.phase !== "running") return projection(task, state);
+    const next = append(task, state, {
+      phase: "exited", event: "peer_attempt_exited", processExit,
+    });
+    if (next) return { ...projection(task, next), exitCode: 2 };
+  }
+}
+
+export async function runPeerTask({ workspaceRoot, taskId, agent, generation, command }) {
+  const backend = requireBackend();
+  safeIdentifier(agent, "current peer");
+  if (!Array.isArray(command) || !path.isAbsolute(command[0] ?? "")) {
+    throw new Error("peer_recovery_absolute_worker_required");
+  }
+  const executable = realpathSync(command[0]);
+  if (!lstatSync(executable).isFile()) throw new Error("peer_recovery_worker_invalid");
+  const task = taskDirectory(workspaceRoot, taskId);
+  const state = current(task);
+  if (state.phase !== "ready" || state.owner !== agent || state.generation !== generation) {
+    throw new Error("peer_recovery_attempt_not_available");
+  }
+  const id = randomUUID();
+  const directory = mkdtempSync(path.join(realpathSync(tmpdir()), "owlrunkit-peer-"));
+  materialize(checkpoint(task, state).files, directory);
+  const attempt = { id, directory, backend: backend.id };
+  const claimed = append(task, state, {
+    attempt, phase: "running", processExit: null, event: "peer_attempt_started",
+  });
+  if (!claimed) throw new Error("peer_recovery_attempt_already_claimed");
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(backend.executable, ["-p", sandboxPolicy(executable, directory),
+      executable, ...command.slice(1)], {
+      cwd: directory, env: {
+        PATH: "/usr/bin:/bin", TMPDIR: directory, OWLRUNKIT_PEER_ATTEMPT: id,
+        OWLRUNKIT_PEER_PATHS: JSON.stringify(state.paths),
+      }, stdio: ["pipe", "pipe", "pipe"],
+    });
+    let watcher, pending = Buffer.alloc(0), sentWake, protocolError = null;
+    let diagnostic = Buffer.alloc(0);
+    const stop = error => {
+      protocolError ??= error.message;
+      child.kill("SIGKILL");
+    };
+    const wake = () => {
+      try {
+        const live = current(task);
+        if (live.attempt?.id !== id || live.phase !== "running") return;
+        if (live.wake && !live.wake.observed && live.wake.id !== sentWake) {
+          sentWake = live.wake.id;
+          child.stdin.write(`${JSON.stringify({ type: "wake", wakeId: sentWake })}\n`);
+        }
+      } catch (error) { stop(error); }
+    };
+    child.stdin.on("error", error => { if (error.code !== "EPIPE") stop(error); });
+    child.stderr.on("data", chunk => {
+      const remaining = 4096 - diagnostic.length;
+      if (remaining > 0) diagnostic = Buffer.concat([diagnostic, chunk.subarray(0, remaining)]);
+    });
+    child.stdout.on("data", chunk => {
+      if (protocolError) return;
+      try {
+        pending = Buffer.concat([pending, chunk]);
+        let end;
+        while ((end = pending.indexOf(10)) >= 0) {
+          if (end > RECORD_LIMIT) throw new Error("peer_recovery_worker_message_too_large");
+          const message = JSON.parse(pending.subarray(0, end).toString("utf8"));
+          pending = pending.subarray(end + 1);
+          if (message?.type === "ack") continue;
+          if (!new Set(["checkpoint", "finish"]).has(message?.type)) {
+            throw new Error("peer_recovery_worker_message_invalid");
+          }
+          reportCheckpoint(task, id, message);
+        }
+        if (pending.length > RECORD_LIMIT) throw new Error("peer_recovery_worker_message_too_large");
+      } catch (error) { stop(error); }
+    });
+    child.once("error", error => { protocolError ??= error.message; });
+    child.once("close", (code, signal) => {
+      watcher?.close();
+      try { resolve(reportExit(task, id, { code, signal, protocolError,
+        diagnostic: diagnostic.toString("utf8") || null })); }
+      catch (error) { reject(error); }
+    });
+    try {
+      watcher = watch(task.directory, wake);
+      watcher.once("error", stop);
+      wake();
+    } catch (error) { stop(error); }
+  });
+}

package/scripts/runkit-contract/project-cli-resolver.mjs

@@ -26,10 +26,14 @@ const SELF_NORMALIZED_QUICK_CORE_VERSIONS = new Set([
   "0.23.0",
   "0.24.0",
   "0.24.1",
+  "0.25.0",
 ]);
 const EXACT_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
 const SHA256_REF = /^sha256:[a-f0-9]{64}$/;
 const TRUSTED_PRIOR_CORE_IDENTITIES = new Map([
+  ["0.24.1", new Set([
+    "sha256:94aaa2e3a6d504374fa78cfcd341e31b33087806c9ddf5f84b3d3b47a6328e08",
+  ])],
   ["0.24.0", new Set([
     "sha256:02e3607701a275014fe95e95e025aeca7cac34ebe4a47e603b8c9db0e45596ff",
   ])],

package/scripts/runkit-contract/runkit-cli.mjs

@@ -92,6 +92,12 @@ import {
   formatInspectHuman,
 } from "./inspect-presentation.mjs";
 import { buildHookRecoveryV1 } from "./hook-recovery.mjs";
+import {
+  createPeerRecoveryTask,
+  inspectPeerRecoveryTask,
+  recoverPeerTask,
+  runPeerTask,
+} from "./peer-recovery.mjs";
 import { attestQuickReceiptDetails } from "./quick-attest.mjs";
 import { readLocalQuickMetrics } from "./quick-metrics.mjs";
 import { runQuickEvidenceReuse } from "./quick-evidence-reuse.mjs";
@@ -265,6 +271,7 @@ Agent team projects
   npx --no-install owlrunkit project <init|assign|checkpoint|handoff|reject-and-return|reopen-upstream|transfer|work-item revise-scope|work-item require-evidence|reconcile|delivery record|decision|verification|capture|target-snapshot|import-delivery|status|takeover|successor|successor scaffold> [options]
   npx --no-install owlrunkit team <recommend|status|packet validate> [options]
   Durable project truth plus read-only Team recommendation and packet validation. No Agent dispatch.
+Managed local peer recovery: npx --no-install owlrunkit peer --help
 Core successor: npx --no-install owlrunkit core-successor <plan|apply|resume> --workspace . [...]
 Other onboarding commands:
   npx --no-install owlrunkit profiles validate --workspace .; npx --no-install owlrunkit profiles impact --workspace . --changed <path>
@@ -2443,6 +2450,52 @@ function requestCommand(options, handler) {
   return handler({ workspaceRoot: root, runId, request: readJson(requestPath) });
 }
 
+const PEER_HELP = `Usage:
+  owlrunkit peer create --workspace <dir> --task <id> --request <json>
+  owlrunkit peer inspect --workspace <dir> --task <id>
+  owlrunkit peer run --workspace <dir> --task <id> --agent <id> --generation <n> -- /absolute/worker [args]
+  owlrunkit peer recover --workspace <dir> --task <id> --agent <id> --generation <n> --revision <n> [--wait-ms <n>]
+`;
+
+function runPeerCommand(rest) {
+  const [action, ...args] = rest;
+  const separator = args.indexOf("--");
+  const optionArgs = separator === -1 ? args : args.slice(0, separator);
+  if (["--help", "-h"].includes(action) || optionArgs.includes("--help") || optionArgs.includes("-h")) {
+    return withHumanOutput({ status: "help", exitCode: 0, authorizationGranted: false }, PEER_HELP);
+  }
+  const flags = {
+    create: ["request"], inspect: [], run: ["agent", "generation"],
+    recover: ["agent", "generation", "revision", "wait-ms"],
+  };
+  if (!Object.hasOwn(flags, action) || (separator !== -1 && action !== "run")) {
+    throw new Error(PEER_HELP);
+  }
+  const options = parseOptions(optionArgs);
+  const allowed = new Set(["workspace", "task", "json", ...flags[action]]);
+  if (Object.keys(options).some(key => !allowed.has(key))) throw new Error(PEER_HELP);
+  const task = { workspaceRoot: workspace(options), taskId: requireOption(options, "task") };
+  if (action === "inspect") return inspectPeerRecoveryTask(task);
+  if (action === "create") {
+    const request = readJson(realpathSync(requireOption(options, "request")));
+    return createPeerRecoveryTask({ ...task, owner: request.owner,
+      successor: request.successor, paths: request.paths });
+  }
+  const peer = {
+    ...task, agent: requireOption(options, "agent"),
+    generation: parseCanonicalNonnegativeSafeInteger(requireOption(options, "generation"), "generation"),
+  };
+  if (action === "run") {
+    if (separator === -1) throw new Error(PEER_HELP);
+    return runPeerTask({ ...peer, command: args.slice(separator + 1) });
+  }
+  return recoverPeerTask({ ...peer,
+    revision: parseCanonicalNonnegativeSafeInteger(requireOption(options, "revision"), "revision"),
+    waitMs: options["wait-ms"] === undefined ? undefined
+      : parseCanonicalNonnegativeSafeInteger(options["wait-ms"], "wait-ms"),
+  });
+}
+
 export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
   try {
     const [command, ...rest] = argv;
@@ -2461,6 +2514,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         authorizationGranted: false,
       }, `owlrunkit ${CORE_VERSION}\n`);
     }
+    if (command === "peer") return await runPeerCommand(rest);
     const separatorIndex = rest.indexOf("--");
     const acceptsExactCommand = command === "verify"
       || command === "quick-verify"