sept-agent 0.1.2 → 0.1.4

package/dist/src/execution/index.js

@@ -9,4 +9,8 @@ export { capabilityBinding, defaultCapabilities, validateCapabilities, capabilit
 export { initializeCapabilityEngine, validateDockerConfiguration, revokeDockerBinding, revokeRecordedHandsBinding, reconcileDockerBinding, assertHandsRunProfile, } from "./docker-control.js";
 /** Exact-family filter generation for trusted consumer-owned network setup. */
 export { networkFirewall } from "./network-profile.js";
+/** Local setup uses the same authenticated Engine and pinned namespace cleanup as the worker. */
+export { DockerEngineControl } from "./docker-engine.js";
+export { captureNamespaceLifetime, stopCapturedNamespace, parseNamespaceLifetime, } from "./hands-processes.js";
+export { guardedCommand } from "./hands-guarded-command.js";
 //# sourceMappingURL=index.js.map

package/dist/src/execution/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/execution/index.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,OAAO,EACL,4BAA4B,GAO7B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AAEnC,qGAAqG;AACrG,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,EAC3B,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,+EAA+E;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/execution/index.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,OAAO,EACL,4BAA4B,GAO7B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AAEnC,qGAAqG;AACrG,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,EAC3B,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,+EAA+E;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,iGAAiG;AACjG,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC"}

package/examples/incident-investigator/README.md

@@ -10,9 +10,9 @@ npm install --omit=dev --save-exact "$SEPT_TARBALL"
 npm ls --omit=dev --json > production-dependencies.json
 ```
 
-Follow the [supplied-hands setup](../../docs/pi-contract.md#executable-supplied-hands-setup) using **separate fresh** brain/agent/state/workspace/initially-empty resources/profile/generation from the native file example. Valid hands is mandatory even for inline text. Before any worker/factory/direct initialization, installed `permissions show` must show absent policy/revision0; installed `permissions set --revision 0` sets scoped workspace read/write false, selected empty, execute/network false. Assert `freshBackendRequired:false` and unchanged running generation. Keep network none and `shell:false`; do not grant file/shell/network rights to make this app pass.
+Follow the [fresh-instance setup](../../README.md#install-and-prepare) with `--root "$SEPT_INCIDENT_APP/instance" --access none`, choosing the actual local Engine socket and locally available image. Use an instance separate from the native file example. Valid hands is mandatory even for inline text. The helper activates zero workspace/selected/execute/network rights before worker initialization; do not grant file/shell/network rights to make this app pass.
 
-Configure a suitable provider/model in the private agent directory using [models](../../docs/models.md). Start the installed complete worker with explicit paths and a privately supplied token (or use the [Node host](../node-app/worker.mjs) with these incident roots). The app's five explicit inputs are the authenticated worker origin, token, workspace, provider and model; a stable event ID identifies the logical investigation.
+Set `SEPT_STATE_DIR`, `PI_CODING_AGENT_DIR`, `SEPT_WORKSPACE_ROOT` and `SEPT_HANDS_CONFIGURATION` from setup's `stateRoot`, `agentDir`, `workspaceRoot` and `handsConfigurationPath` fields. Configure a suitable provider/model through [model authentication](../../README.md#model-authentication). Start the installed complete worker with explicit paths and a privately supplied token (or use the [Node host](../node-app/worker.mjs) with these incident roots). The app's five explicit inputs are the authenticated worker origin, token, workspace, provider and model; a stable event ID identifies the logical investigation.
 
 ```sh
 sept worker --state-dir "$SEPT_STATE_DIR" --agent-dir "$PI_CODING_AGENT_DIR" \
@@ -32,7 +32,7 @@ node investigate.mjs wait
 
 The `wait` command prints authoritative WAIT and exits, deliberately retaining the coherent waiting run. Stop/join the worker. Export any needed workspace, then stop and verify its exact owned generation using the supplied-hands guards. Create a **fresh minimal** generation and a dedicated initially-empty resources root/profile; preserve the same private state/agent/workspace roots and model selection. Use installed `permissions show` to obtain the current revision and `permissions set --revision CURRENT` with the same zero-rights policy and fresh profile; confirm `freshBackendRequired:false` and the fresh running generation. Start the worker again with that profile and the same persistent roots. The earlier generation must remain stopped/PID0; never reuse it.
 
-With the original setup's explicit-socket `sept_docker`/`sept_socket_matches` functions and exported roots/image still in this operator shell, the fresh generation and current-revision activation are:
+The fresh-instance helper does not orchestrate this durable restart/rebind. The advanced operator-managed snippet below requires separately supplied `sept_docker`/`sept_socket_matches` guards pinned to the original local socket identity and daemon, `SEPT_ENGINE_ID`, immutable `SEPT_IMAGE`, private `SEPT_OPERATOR_ROOT`, `SEPT_EVIDENCE/socket.json`, and `SEPT_OPERATOR_ROOT/minimal-policy.json` containing the same zero-rights policy. These guards, receipts and exact-generation finalizers are prerequisites, not outputs of the helper. With those existing operator inputs, the fresh generation and current-revision activation are:
 
 ```sh
 set -eu
@@ -105,4 +105,4 @@ Expected output is a `WAIT` record from `getTask`, followed by a `report` record
 
 On failure or SIGINT/SIGTERM, `finally` independently attempts bounded cancellation of an unfinished admitted run. Cancellation can return while settlement continues; inspect authoritative state and reconcile an ambiguous request. The app does not own an external worker/provider/hands process. Their operator must independently stop/join each worker/provider/listener/attachment/lease and the exact owned generation using the setup's authority guards, verify stopped/PID0, and retain mutexes/stopped resources/recovery. A successful wait command retains WAIT; a successful report retains the terminal run. The external worker remains under its caller's lifecycle control.
 
-Persistent WAIT/stop/reopen is supported by the [SDK lifecycle](../../docs/sdk.md#worker-lifecycle): await stop, supply a fresh hands generation under current revision CAS, reopen the same persistent roots, and then send later evidence. Do not reuse a stopped generation or reset the task's budget/history. Provider outages/OAuth refresh, full Darwin/Intel/Windows and arbitrary Docker hosts remain unqualified.
+Persistent WAIT/stop/reopen requires the existing SDK lifecycle: await stop, supply a fresh hands generation under current revision CAS, reopen the same persistent roots, and then send later evidence. Do not reuse a stopped generation or reset the task's budget/history. Provider outages/OAuth refresh, full Darwin/Intel/Windows and arbitrary Docker hosts remain unqualified.

package/examples/incident-investigator/package.json

@@ -10,6 +10,6 @@
     "report": "node investigate.mjs report"
   },
   "dependencies": {
-    "sept-agent": "0.1.2"
+    "sept-agent": "0.1.4"
   }
 }

package/examples/node-app/README.md

@@ -30,9 +30,9 @@ npm run build:extension
 
 No installed header, ambient shim, alias or skipped declaration check is used. This configuration resolves the declarations actually reached by the extension; it does not repair Pi AI's separate model-catalog JSON imports without NodeNext attributes. Importing that broader catalog still needs upstream repair. SEPT's public package declarations remain independently checked with Node-only types.
 
-Follow [supplied-hands setup](../../docs/pi-contract.md#executable-supplied-hands-setup) with `SEPT_OPERATIONS_ROOT="$SEPT_APP"`. Use a **fresh separate** state/workspace/initially-empty resources/profile/generation for this example. Before any worker initialization, installed `sept permissions show` must show absent revision0, then installed `permissions set --revision 0` grants scoped workspace read/write true, selected empty, execute/network false. Confirm `freshBackendRequired:false` and the unchanged running generation. Keep `shell:false` and network none. Never widen the incident app's policy for this example.
+Follow the [fresh-instance setup](../../README.md#install-and-prepare) with `--root "$SEPT_APP/instance" --access files`, choosing the actual local Engine socket and locally available image. Use a fresh separate instance for this example. The helper activates workspace read/write before worker initialization and leaves selected mounts, shell and networking disabled. Never widen the incident app's policy for this example.
 
-Set `PI_CODING_AGENT_DIR`, `SEPT_STATE_DIR`, `SEPT_WORKSPACE_ROOT`, `SEPT_HANDS_CONFIGURATION` to the setup's absolute paths, and supply `SEPT_TOKEN` privately. Configure the desired provider/model through [Pi model configuration](../../docs/models.md) in that agent directory. The physical agent directory must be below this external app, so normal ancestor lookup finds its matching `node_modules`.
+Set `PI_CODING_AGENT_DIR`, `SEPT_STATE_DIR`, `SEPT_WORKSPACE_ROOT`, `SEPT_HANDS_CONFIGURATION` to the setup's absolute `agentDir`, `stateRoot`, `workspaceRoot`, `handsConfigurationPath` fields, and supply `SEPT_TOKEN` privately. Configure the desired provider/model through [model authentication](../../README.md#model-authentication) in that agent directory. The physical agent directory must be below this external app, so normal ancestor lookup finds its matching `node_modules`.
 
 ```sh
 test -f extension-dist/example.js
@@ -56,9 +56,9 @@ export SEPT_EVENT_ID=node-marker-001
 node dist/client.js
 ```
 
-The client requires authoritative complete state and prints its bounded public conversation. Actual acceptance additionally requires the section in the real provider request, Harness selecting `write_marker`, and exported hands bytes exactly `SEPT_NATIVE_EXAMPLE` plus newline. Compilation or directly calling the extension object cannot establish this. Use the setup's explicit-socket export command to retain `/workspace` before stopping the exact owned generation.
+The client requires authoritative complete state and prints its bounded public conversation. Actual acceptance additionally requires the section in the real provider request, Harness selecting `write_marker`, and exported hands bytes exactly `SEPT_NATIVE_EXAMPLE` plus newline. Compilation or directly calling the extension object cannot establish this.
 
-Send SIGINT/SIGTERM to the worker host; it awaits `worker.stop()` and removes its handlers. Readiness covers listener/router and durable adoption admission; native execution may still fail afterward and is observed through the task API. Normal stop retains idle hands. Follow the setup's independent worker/provider/listener/lease/attachment and exact-generation export/stop finalizers, verify stopped/PID0, and retain stopped resources/mutexes/recovery. Cancel/loss can stop hands earlier, so later export is not guaranteed.
+Send SIGINT/SIGTERM to the worker host; it awaits `worker.stop()` and removes its handlers. Readiness covers listener/router and durable adoption admission; native execution may still fail afterward and is observed through the task API. Normal stop retains idle hands. After the host has joined, run `sept hands finish --root "$SEPT_APP/instance"` to retain the private workspace archive and verify the exact owned generation stopped/PID0. Preserve its receipts and archive. Cancel/loss can stop hands earlier, so later export is not guaranteed.
 
 After editing an extension, stop/join the host and start a **fresh Node process**. Stable canonical module-URL caching survives Pi host replacement and same-process stop/reopen; reopening resumes durable state without promising edited-code reload. There is no hot reload.
 

package/examples/node-app/package.json

@@ -12,7 +12,7 @@
     "client": "node dist/client.js"
   },
   "dependencies": {
-    "sept-agent": "0.1.2",
+    "sept-agent": "0.1.4",
     "@earendil-works/pi-durable": "1.1.0",
     "@earendil-works/pi-ai": "1.1.0"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sept-agent",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Durable Pi-native single-slot task worker",
   "type": "module",
   "engines": {
@@ -77,13 +77,6 @@
     "CONTRIBUTING.md",
     "LICENSE",
     "NOTICE",
-    "docs/index.md",
-    "docs/sdk.md",
-    "docs/models.md",
-    "docs/worker-api.md",
-    "docs/pi-contract.md",
-    "docs/architecture.md",
-    "docs/observability.md",
     "examples/node-app",
     "examples/incident-investigator",
     "image/pi-native-search/README.md",

package/src/cli/commands.ts

@@ -19,6 +19,7 @@ import {
   createWorker,
   type Worker,
 } from "../worker/index.js";
+import { runHands } from "./hands.js";
 import { runPermissions } from "./permissions.js";
 import { resumePermissionRun, assertLocalRunSlot } from "./permission-decisions.js";
 import { CliError } from "./errors.js";
@@ -291,6 +292,9 @@ async function runHealth(context: CommandContext): Promise<void> {
 /** Execute one parsed command through public mechanism boundaries without retaining credentials. */
 export async function executeCommand(context: CommandContext): Promise<void> {
   switch (context.command) {
+    case "hands":
+      writeJson(await runHands(context));
+      return;
     case "permissions":
       writeJson(await runPermissions(context, stateRoot(context.options), context.agentDir));
       return;

package/src/cli/hands-docker.ts

@@ -0,0 +1,198 @@
+/** Setup-only Docker CLI calls use one explicit socket and no ambient Docker context or credentials. */
+import { spawn, spawnSync } from "node:child_process";
+import { createWriteStream, fsyncSync, closeSync, openSync } from "node:fs";
+import { join } from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { SeptError } from "../durable/index.js";
+import { guardedCommand, parseNamespaceLifetime } from "../execution/index.js";
+import { readHandsMetadata, type HandsReceipt } from "./hands-record.js";
+
+// Lifetime is checked inside the exec: a replacement namespace can never emit an archive.
+const ARCHIVE_ENTRY = `const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+const stat = fs.readFileSync('/proc/1/stat', 'utf8');
+if (stat.length > 16384) process.exit(126);
+const start = stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+if (fs.readlinkSync('/proc/self/ns/pid') !== process.argv[1] || start !== process.argv[2]) process.exit(126);
+const result = spawnSync('/bin/tar', ['-C', '/workspace', '-cf', '-', '.'], { stdio: 'inherit', env: { PATH: '/usr/bin:/bin' }, timeout: 25000 });
+process.exit(result.status === 0 && result.signal === null ? 0 : 126);`;
+
+const MAX_ARCHIVE_BYTES = 134217728 + 32768 * 2048;
+
+function commandArguments(root: string, receipt: HandsReceipt, arguments_: string[]): string[] {
+  return [
+    "--config",
+    join(root, "docker-cli"),
+    "--host",
+    `unix://${receipt.engineSocket}`,
+    ...arguments_,
+  ];
+}
+
+/** Bounded setup controls never invoke a shell, pull an image, or read the user's Docker config. */
+export function handsDocker(root: string, receipt: HandsReceipt, arguments_: string[]): string {
+  const result = spawnSync("docker", commandArguments(root, receipt, arguments_), {
+    env: { PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin" },
+    encoding: "utf8",
+    timeout: 30_000,
+    maxBuffer: 16 * 1024,
+  });
+  if (result.status !== 0 || result.signal !== null || result.error !== undefined) {
+    throw new SeptError("Hands setup Docker command failed; retained receipt requires inspection", {
+      cause: result.error,
+    });
+  }
+  return result.stdout.trim();
+}
+
+/** The sole supported offline, file-only profile uses existing finite kernel limits. */
+export function createHandsArguments(root: string, receipt: HandsReceipt): string[] {
+  return [
+    "create",
+    "--pull",
+    "never",
+    "--name",
+    `sept-hands-${receipt.owner}`,
+    "--label",
+    `sept.setup.owner=${receipt.owner}`,
+    "--init",
+    "--no-healthcheck",
+    "--entrypoint",
+    "",
+    "--user",
+    "10002:10002",
+    "--read-only",
+    "--cap-drop",
+    "ALL",
+    "--security-opt",
+    "no-new-privileges",
+    "--pids-limit",
+    "128",
+    "--memory",
+    "1g",
+    "--cpus",
+    "2",
+    "--network",
+    "none",
+    "--tmpfs",
+    "/tmp:rw,nosuid,nodev,noexec,size=16777216,mode=1777",
+    "--tmpfs",
+    "/workspace:rw,nosuid,nodev,noexec,size=134217728,nr_inodes=32768,mode=2770,uid=10002,gid=10002",
+    "--mount",
+    `type=bind,src=${join(root, "resources")},dst=/resources,readonly`,
+    receipt.image,
+    "sleep",
+    "infinity",
+  ];
+}
+
+/** Stream a bounded tar archive to a new private file; hostile archive paths are never extracted. */
+export async function exportHandsWorkspace(
+  root: string,
+  receipt: HandsReceipt,
+  path: string,
+): Promise<void> {
+  if (receipt.containerId === undefined) {
+    throw new SeptError("Hands export requires captured container ownership");
+  }
+  const child = archiveChild(root, receipt);
+  const completion = childCompletion(child);
+  const timer = setTimeout(() => {
+    child.kill("SIGKILL");
+  }, 30_000);
+  try {
+    await archivePipeline(child.stdout, path);
+    await completion;
+    syncArchive(path);
+  } catch (error: unknown) {
+    child.kill("SIGKILL");
+    await completion.catch(() => undefined);
+    throw new SeptError("Hands workspace export failed; partial archive retained", {
+      cause: error,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function archiveChild(
+  root: string,
+  receipt: HandsReceipt,
+): import("node:child_process").ChildProcessWithoutNullStreams {
+  if (receipt.containerId === undefined) {
+    throw new SeptError("Hands export requires captured container ownership");
+  }
+  const child = spawn(
+    "docker",
+    commandArguments(root, receipt, [
+      "exec",
+      "--user",
+      "10002:10002",
+      receipt.containerId,
+      ...archiveCommand(root),
+    ]),
+    {
+      env: { PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin" },
+      stdio: ["pipe", "pipe", "pipe"],
+    },
+  );
+  child.stdin.end();
+  let stderrBytes = 0;
+  child.stderr.on("data", (chunk: Buffer) => {
+    stderrBytes += chunk.byteLength;
+    if (stderrBytes > 16 * 1024) {
+      child.kill("SIGKILL");
+    }
+  });
+  return child;
+}
+
+function archiveCommand(root: string): string[] {
+  const path = join(root, "evidence", "lifetime.json");
+  const raw = readHandsMetadata(path, 1024);
+  const lifetime = parseNamespaceLifetime(raw);
+  return guardedCommand(["--eval", ARCHIVE_ENTRY, lifetime.pidNamespace, lifetime.initStart]);
+}
+
+function childCompletion(child: import("node:child_process").ChildProcess): Promise<void> {
+  const completed = new Promise<void>((resolve, reject) => {
+    child.once("error", () => {
+      reject(new SeptError("Hands archive process could not start"));
+    });
+    child.once("close", (code, signal) => {
+      if (code === 0 && signal === null) {
+        resolve();
+      } else {
+        reject(new SeptError("Hands archive process failed"));
+      }
+    });
+  });
+  // Attach a rejection owner immediately: an Engine failure may arrive before stream finalization.
+  void completed.catch(() => undefined);
+  return completed;
+}
+
+async function archivePipeline(source: NodeJS.ReadableStream, path: string): Promise<void> {
+  let bytes = 0;
+  const bound = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      bytes += chunk.byteLength;
+      if (bytes > MAX_ARCHIVE_BYTES) {
+        callback(new SeptError("Hands workspace archive exceeds its fixed capacity"));
+      } else {
+        callback(null, chunk);
+      }
+    },
+  });
+  await pipeline(source, bound, createWriteStream(path, { flags: "wx", mode: 0o600 }));
+}
+
+function syncArchive(path: string): void {
+  const descriptor = openSync(path, "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}

package/src/cli/hands-finish.ts

@@ -0,0 +1,204 @@
+/** Export before stopping one exclusively owned hands generation; never extract archive bytes on host. */
+import { existsSync, lstatSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { randomUUID } from "node:crypto";
+import { acquireStateRootLease, atomicWrite, SeptError } from "../durable/index.js";
+import {
+  handsPaths,
+  readHandsReceipt,
+  readHandsMetadata,
+  trustedHandsRoot,
+  writeHandsReceipt,
+  type HandsReceipt,
+} from "./hands-record.js";
+import { exportHandsWorkspace } from "./hands-docker.js";
+import { inspectHandsOwner, openHandsEngine, stopHandsOwner } from "./hands-owner.js";
+/** Refuse a live worker, serialize setup ownership, then independently finalize export and stop. */
+export async function finishHands(options: Record<string, string>): Promise<unknown> {
+  if (Object.keys(options).some((key) => key !== "root")) {
+    throw new SeptError("hands finish accepts only --root");
+  }
+  const root = trustedHandsRoot(options.root);
+  assertSetupLayout(root);
+  // Preflight schema grants no authority; the owner is re-read after serialized lease acquisition.
+  readHandsReceipt(root);
+  const releaseSetup = acquireStateRootLease(join(root, "evidence"));
+  try {
+    const releaseWorker = acquireStateRootLease(handsPaths(root).stateRoot);
+    try {
+      return await finishOwned(root, readHandsReceipt(root));
+    } finally {
+      releaseWorker();
+    }
+  } finally {
+    releaseSetup();
+  }
+}
+
+function assertSetupLayout(root: string): void {
+  try {
+    // Lease acquisition creates lock files: prove a setup-owned layout before any such mutation.
+    for (const name of ["state", "evidence"]) {
+      const directory = lstatSync(join(root, name));
+      if (
+        !directory.isDirectory() ||
+        directory.uid !== process.getuid?.() ||
+        (directory.mode & 0o077) !== 0
+      ) {
+        throw new SeptError("Hands setup directories must be private and owned");
+      }
+    }
+    assertSetupReceipt(root);
+  } catch (error: unknown) {
+    throw new SeptError("Hands finish requires an existing private owned setup layout", {
+      cause: error,
+    });
+  }
+}
+
+function assertSetupReceipt(root: string): void {
+  const receipt = lstatSync(join(root, "evidence", "setup.json"));
+  if (
+    !receipt.isFile() ||
+    receipt.nlink !== 1 ||
+    receipt.uid !== process.getuid?.() ||
+    (receipt.mode & 0o077) !== 0 ||
+    receipt.size > 16 * 1024
+  ) {
+    throw new SeptError("Hands setup receipt must be private and owned");
+  }
+}
+
+async function finishOwned(root: string, receipt: HandsReceipt): Promise<unknown> {
+  const previous = reusableExport(root);
+  const engine = await openHandsEngine(receipt);
+  const archive = join(root, "evidence", `workspace-${randomUUID()}.tar`);
+  let exported = previous !== undefined;
+  let stopped = false;
+  try {
+    const state = await inspectHandsOwner(root, receipt, engine);
+    if (receipt.phase === "finished") {
+      return verifiedFinalization(root, state, previous);
+    }
+    exported ||= await tryExport(root, receipt, archive, state.Running === true);
+    await stopHandsOwner(root, receipt, engine);
+    stopped = true;
+  } finally {
+    await engine.close();
+    if (receipt.phase !== "finished") {
+      atomicWrite(join(root, "evidence", "finish.json"), {
+        exported,
+        stopped,
+        archive: previous ?? (existsSync(archive) ? archive : null),
+      });
+    }
+  }
+  if (!exported) {
+    throw new SeptError(
+      "Hands workspace export failed or unavailable; stop verified; inspect evidence/finish.json",
+    );
+  }
+  receipt.phase = "finished";
+  writeHandsReceipt(root, receipt);
+  return readFinalization(root);
+}
+
+function verifiedFinalization(
+  root: string,
+  state: Record<string, unknown>,
+  previous: string | undefined,
+): Finalization {
+  if (state.Running !== false || state.Pid !== 0 || previous === undefined) {
+    throw new SeptError(
+      "Previously finished hands has no verified stopped namespace and retained archive",
+    );
+  }
+  const result = readFinalization(root);
+  if (!result.exported || !result.stopped) {
+    throw new SeptError("Hands finished receipt has no verified successful outcomes");
+  }
+  return result;
+}
+
+interface Finalization {
+  exported: boolean;
+  stopped: boolean;
+  archive: string | null;
+}
+
+function readFinalization(root: string): Finalization {
+  const result = readHandsMetadata(join(root, "evidence", "finish.json"), 1024);
+  if (
+    typeof result !== "object" ||
+    result === null ||
+    !("exported" in result) ||
+    !("stopped" in result) ||
+    !("archive" in result)
+  ) {
+    throw new SeptError("Hands finalization receipt is malformed");
+  }
+  if (
+    typeof result.exported !== "boolean" ||
+    typeof result.stopped !== "boolean" ||
+    (typeof result.archive !== "string" && result.archive !== null)
+  ) {
+    throw new SeptError("Hands finalization outcomes are malformed");
+  }
+  return { exported: result.exported, stopped: result.stopped, archive: result.archive };
+}
+
+function reusableExport(root: string): string | undefined {
+  try {
+    return previousExport(root);
+  } catch {
+    // Invalid export evidence grants no reuse, but cannot skip independently owned namespace shutdown.
+    return undefined;
+  }
+}
+
+function previousExport(root: string): string | undefined {
+  if (!existsSync(join(root, "evidence", "finish.json"))) {
+    return undefined;
+  }
+  const previous = readFinalization(root);
+  if (!previous.exported || previous.archive === null) {
+    return undefined;
+  }
+  if (
+    dirname(previous.archive) !== join(root, "evidence") ||
+    !/^workspace-[a-f0-9-]{36}\.tar$/.test(basename(previous.archive))
+  ) {
+    throw new SeptError("Hands archive receipt escapes the owned evidence directory");
+  }
+  assertArchive(previous.archive);
+  return previous.archive;
+}
+
+function assertArchive(path: string): void {
+  const file = lstatSync(path);
+  if (
+    !file.isFile() ||
+    file.nlink !== 1 ||
+    file.uid !== process.getuid?.() ||
+    (file.mode & 0o077) !== 0
+  ) {
+    throw new SeptError("Hands retained archive ownership is malformed");
+  }
+}
+
+async function tryExport(
+  root: string,
+  receipt: HandsReceipt,
+  archive: string,
+  running: boolean,
+): Promise<boolean> {
+  if (!running || receipt.generation === undefined) {
+    return false;
+  }
+  try {
+    await exportHandsWorkspace(root, receipt, archive);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/cli/hands-owner.ts

@@ -0,0 +1,118 @@
+/** Exact Engine, setup label, image and kernel lifetime checks precede every setup finalizer. */
+import { join } from "node:path";
+import { atomicWrite, SeptError } from "../durable/index.js";
+import {
+  DockerEngineControl,
+  captureNamespaceLifetime,
+  stopCapturedNamespace,
+  parseNamespaceLifetime,
+  type DockerHandsConfiguration,
+} from "../execution/index.js";
+import { handsDocker } from "./hands-docker.js";
+import { readHandsMetadata, writeHandsReceipt, type HandsReceipt } from "./hands-record.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (!isRecord(value)) {
+    throw new SeptError("Hands setup inspection is malformed");
+  }
+  return value;
+}
+
+/** Open the originally captured socket/daemon only; ambient context and replacement daemons refuse. */
+export async function openHandsEngine(receipt: HandsReceipt): Promise<DockerEngineControl> {
+  const engine = await DockerEngineControl.open(receipt.engineSocket);
+  if (engine.socketIdentity !== receipt.socketIdentity || engine.daemonId !== receipt.daemonId) {
+    await engine.close();
+    throw new SeptError("Hands setup Engine ownership changed");
+  }
+  return engine;
+}
+
+/** A pre-create receipt can recover only its unique setup-labelled container, never a foreign name. */
+export async function inspectHandsOwner(
+  root: string,
+  receipt: HandsReceipt,
+  engine: DockerEngineControl,
+): Promise<Record<string, unknown>> {
+  const containerId =
+    receipt.containerId ??
+    handsDocker(root, receipt, ["inspect", "--format", "{{.Id}}", `sept-hands-${receipt.owner}`]);
+  if (!/^[a-f0-9]{64}$/.test(containerId)) {
+    throw new SeptError("Hands setup container identity is malformed");
+  }
+  const inspected = record(await engine.inspect(containerId));
+  const labels = record(record(inspected.Config).Labels);
+  const state = record(inspected.State);
+  if (
+    labels["sept.setup.owner"] !== receipt.owner ||
+    inspected.Image !== receipt.image ||
+    inspected.Id !== containerId ||
+    (receipt.generation !== undefined && state.StartedAt !== receipt.generation)
+  ) {
+    throw new SeptError("Hands setup container ownership or generation changed");
+  }
+  receipt.containerId = containerId;
+  writeHandsReceipt(root, receipt);
+  return state;
+}
+
+/** Capture the native pinned stop receipt before granting the first permission revision. */
+export async function captureHandsOwner(
+  root: string,
+  receipt: HandsReceipt,
+  configuration: DockerHandsConfiguration,
+  engine: DockerEngineControl,
+): Promise<void> {
+  const lifetime = await captureNamespaceLifetime(configuration, engine);
+  atomicWrite(join(root, "evidence", "lifetime.json"), lifetime);
+  receipt.phase = "running";
+  writeHandsReceipt(root, receipt);
+}
+
+/** Stop only the captured namespace lifetime, independently verifying stopped/PID0 after helper teardown. */
+export async function stopHandsOwner(
+  root: string,
+  receipt: HandsReceipt,
+  engine: DockerEngineControl,
+): Promise<void> {
+  const state = await inspectHandsOwner(root, receipt, engine);
+  if (state.Running === false && state.Pid === 0) {
+    return;
+  }
+  if (receipt.containerId === undefined || receipt.generation === undefined) {
+    throw new SeptError("Hands generation was not captured; manual reconciliation required");
+  }
+  const path = join(root, "evidence", "lifetime.json");
+  const raw = readHandsMetadata(path, 1024);
+  const lifetime = parseNamespaceLifetime(raw);
+  try {
+    await stopCapturedNamespace(
+      { containerId: receipt.containerId, generation: receipt.generation },
+      lifetime,
+      engine,
+    );
+  } catch {
+    // A successful pinned namespace stop also tears down its own helper; closure decides success.
+  }
+  await verifyStopped(root, receipt, engine);
+}
+
+async function verifyStopped(
+  root: string,
+  receipt: HandsReceipt,
+  engine: DockerEngineControl,
+): Promise<void> {
+  const deadline = performance.now() + 30_000;
+  while (performance.now() < deadline) {
+    const state = await inspectHandsOwner(root, receipt, engine);
+    if (state.Running === false && state.Pid === 0) {
+      return;
+    }
+    await new Promise<void>((resolve) => setTimeout(resolve, 100));
+  }
+  throw new SeptError("Hands setup shutdown could not be verified");
+}