sept-agent 0.1.3 → 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.3",
+    "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.3",
+  "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");
+}