sept-agent 0.1.3 → 0.1.4

package/src/cli/hands-record.ts

@@ -0,0 +1,213 @@
+/** Private ownership receipts for the optional local hands setup commands. */
+import {
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  chmodSync,
+  openSync,
+  fsyncSync,
+  closeSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, normalize } from "node:path";
+import { randomUUID } from "node:crypto";
+import { atomicWrite, SeptError } from "../durable/index.js";
+
+/** Fixed paths returned directly as existing createWorker options; no credential is generated. */
+export interface HandsPaths {
+  stateRoot: string;
+  agentDir: string;
+  workspaceRoot: string;
+  handsConfigurationPath: string;
+}
+
+/** Durable exclusive setup identity survives partial creation and never grants task authority. */
+export interface HandsReceipt {
+  version: 1;
+  owner: string;
+  engineSocket: string;
+  socketIdentity: string;
+  daemonId: string;
+  image: string;
+  containerId?: string;
+  generation?: string;
+  phase: "prepared" | "creating" | "running" | "ready" | "failed" | "finished";
+}
+
+/** Derive the sole supported fresh-instance layout. */
+export function handsPaths(root: string): HandsPaths {
+  return {
+    stateRoot: join(root, "state"),
+    agentDir: join(root, "agent"),
+    workspaceRoot: join(root, "workspace"),
+    handsConfigurationPath: join(root, "hands.json"),
+  };
+}
+
+/** Refuse lexical aliases and mutable ancestors before creating or reading ownership. */
+export function trustedHandsRoot(value: string | undefined, fresh = false): string {
+  if (
+    value === undefined ||
+    !isAbsolute(value) ||
+    value.length > 4096 ||
+    /[\x00-\x1f,]/.test(value)
+  ) {
+    throw new SeptError(
+      "hands requires a canonical absolute --root without control characters or commas",
+    );
+  }
+  const existing = fresh ? dirname(value) : value;
+  if (realpathSync(existing) !== existing || normalize(value) !== value) {
+    throw new SeptError("Hands root must be canonical");
+  }
+  validateAncestors(existing);
+  return value;
+}
+
+function validateAncestors(existing: string): void {
+  for (let path = existing; ; path = dirname(path)) {
+    const stat = lstatSync(path);
+    const owner = stat.uid === 0 || stat.uid === process.getuid?.();
+    const sticky = stat.uid === 0 && (stat.mode & 0o1000) !== 0;
+    if (!stat.isDirectory() || !owner || ((stat.mode & 0o022) !== 0 && !sticky)) {
+      throw new SeptError("Hands root ancestry is not trusted");
+    }
+    if (path === dirname(path)) {
+      return;
+    }
+  }
+}
+
+/** Create only a new root: a failed or foreign instance is never overwritten or adopted by init. */
+export function createHandsRoot(root: string): HandsPaths {
+  mkdirSync(root, { mode: 0o755 });
+  chmodSync(root, 0o755);
+  const paths = handsPaths(root);
+  for (const directory of [
+    paths.stateRoot,
+    paths.agentDir,
+    paths.workspaceRoot,
+    join(root, "evidence"),
+    join(root, "docker-cli"),
+  ]) {
+    mkdirSync(directory, { mode: 0o700 });
+  }
+  mkdirSync(join(root, "resources"), { mode: 0o755 });
+  chmodSync(join(root, "resources"), 0o755);
+  syncSetupDirectory(root);
+  syncSetupDirectory(dirname(root));
+  return paths;
+}
+
+function syncSetupDirectory(path: string): void {
+  const descriptor = openSync(path, "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+/** Persist recovery ownership before creating a container and after every identity transition. */
+export function writeHandsReceipt(root: string, receipt: HandsReceipt): void {
+  atomicWrite(join(root, "evidence", "setup.json"), receipt);
+}
+
+/** Read bounded private ownership, refusing edited schema, symlinks, hardlinks or broad permissions. */
+export function readHandsReceipt(root: string): HandsReceipt {
+  const path = join(root, "evidence", "setup.json");
+  const raw = readHandsMetadata(path, 16 * 1024);
+  if (!isRecord(raw)) {
+    throw new SeptError("Hands setup ownership is malformed");
+  }
+  return decodeReceipt(raw);
+}
+
+/** Read private bounded setup metadata without presenting hostile JSON or filesystem diagnostics. */
+export function readHandsMetadata(path: string, maximum: number): unknown {
+  try {
+    const file = lstatSync(path);
+    if (
+      !file.isFile() ||
+      file.nlink !== 1 ||
+      file.uid !== process.getuid?.() ||
+      (file.mode & 0o077) !== 0 ||
+      file.size > maximum
+    ) {
+      throw new SeptError("Hands metadata must be a bounded private owned regular file");
+    }
+    const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return raw;
+  } catch (error: unknown) {
+    throw new SeptError("Hands setup metadata is unavailable or malformed", { cause: error });
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function decodeReceipt(raw: Record<string, unknown>): HandsReceipt {
+  const keys = [
+    "version",
+    "owner",
+    "engineSocket",
+    "socketIdentity",
+    "daemonId",
+    "image",
+    "containerId",
+    "generation",
+    "phase",
+  ];
+  if (Object.keys(raw).some((key) => !keys.includes(key)) || raw.version !== 1) {
+    throw new SeptError("Hands setup ownership is malformed");
+  }
+  const containerId =
+    raw.containerId === undefined ? undefined : text(raw.containerId, /^[a-f0-9]{64}$/);
+  const generation = raw.generation === undefined ? undefined : text(raw.generation);
+  return {
+    version: 1,
+    owner: text(raw.owner, /^[a-f0-9-]{36}$/),
+    engineSocket: text(raw.engineSocket),
+    socketIdentity: text(raw.socketIdentity),
+    daemonId: text(raw.daemonId),
+    image: text(raw.image, /^sha256:[a-f0-9]{64}$/),
+    phase: receiptPhase(raw.phase),
+    ...(containerId === undefined ? {} : { containerId }),
+    ...(generation === undefined ? {} : { generation }),
+  };
+}
+
+function text(value: unknown, pattern?: RegExp): string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > 4096 ||
+    /[\x00-\x1f]/.test(value)
+  ) {
+    throw new SeptError("Hands setup ownership text is malformed");
+  }
+  if (pattern !== undefined && !pattern.test(value)) {
+    throw new SeptError("Hands setup ownership identity is malformed");
+  }
+  return value;
+}
+
+function receiptPhase(value: unknown): HandsReceipt["phase"] {
+  switch (value) {
+    case "prepared":
+    case "creating":
+    case "running":
+    case "ready":
+    case "failed":
+    case "finished":
+      return value;
+    default:
+      throw new SeptError("Hands setup phase is malformed");
+  }
+}
+
+/** Generate the unguessable container ownership label before any Engine effect. */
+export function newHandsOwner(): string {
+  return randomUUID();
+}

package/src/cli/hands.ts

@@ -0,0 +1,207 @@
+/** Optional local setup composition; the existing worker and policy authority remain unchanged. */
+import { realpathSync } from "node:fs";
+import { join } from "node:path";
+import { acquireStateRootLease, atomicWrite, SeptError } from "../durable/index.js";
+import { DockerEngineControl, loadHandsConfiguration } from "../execution/index.js";
+import { finishHands } from "./hands-finish.js";
+import { runPermissions } from "./permissions.js";
+import type { CliInvocation } from "./options.js";
+import {
+  createHandsRoot,
+  handsPaths,
+  newHandsOwner,
+  trustedHandsRoot,
+  writeHandsReceipt,
+  type HandsReceipt,
+} from "./hands-record.js";
+import { createHandsArguments, handsDocker } from "./hands-docker.js";
+import { captureHandsOwner, inspectHandsOwner, stopHandsOwner } from "./hands-owner.js";
+
+/** Execute the two installed operator commands; signals join cleanup before the process exits. */
+export async function runHands(invocation: CliInvocation): Promise<unknown> {
+  if (invocation.action !== "init" && invocation.action !== "finish") {
+    throw new SeptError("Usage: sept hands init|finish --root <absolute-new-instance>");
+  }
+  const abort = new AbortController();
+  const cancel = (): void => {
+    abort.abort();
+  };
+  process.on("SIGINT", cancel);
+  process.on("SIGTERM", cancel);
+  try {
+    return invocation.action === "init"
+      ? await initialize(invocation.options, abort.signal)
+      : await finishHands(invocation.options);
+  } finally {
+    process.off("SIGINT", cancel);
+    process.off("SIGTERM", cancel);
+  }
+}
+
+function assertNotCancelled(signal: AbortSignal): void {
+  if (signal.aborted) {
+    throw new SeptError("Hands setup cancelled; ownership and recovery receipts retained");
+  }
+}
+
+async function initialize(options: Record<string, string>, signal: AbortSignal): Promise<unknown> {
+  const root = trustedHandsRoot(options.root, true);
+  if (options.access !== "files" && options.access !== "none") {
+    throw new SeptError("hands init requires explicit --access files|none");
+  }
+  if (
+    options.image === undefined ||
+    options.image.length > 512 ||
+    options.image.startsWith("-") ||
+    options["engine-socket"] === undefined
+  ) {
+    throw new SeptError("hands init requires --image and explicit local --engine-socket");
+  }
+  const engine = await DockerEngineControl.open(options["engine-socket"]);
+  try {
+    assertNotCancelled(signal);
+    createHandsRoot(root);
+    return await initializeOwned(root, options, engine, signal);
+  } finally {
+    await engine.close();
+  }
+}
+
+async function initializeOwned(
+  root: string,
+  options: Record<string, string>,
+  engine: DockerEngineControl,
+  signal: AbortSignal,
+): Promise<unknown> {
+  const release = acquireStateRootLease(join(root, "evidence"));
+  const receipt = initialReceipt(options, engine);
+  try {
+    writeHandsReceipt(root, receipt);
+    resolveImage(root, receipt, options.image ?? "");
+    await createContainer(root, receipt, engine, signal);
+    await activatePermissions(root, options.access === "files");
+    assertNotCancelled(signal);
+    receipt.phase = "ready";
+    writeHandsReceipt(root, receipt);
+    return {
+      ...handsPaths(root),
+      containerId: receipt.containerId,
+      generation: receipt.generation,
+      access: options.access,
+    };
+  } catch (error: unknown) {
+    await initializationFailure(root, receipt, engine);
+    throw new SeptError("Hands initialization failed; recovery evidence retained under --root", {
+      cause: error,
+    });
+  } finally {
+    release();
+  }
+}
+
+function resolveImage(root: string, receipt: HandsReceipt, imageName: string): void {
+  const image = handsDocker(root, receipt, ["image", "inspect", "--format", "{{.Id}}", imageName]);
+  if (!/^sha256:[a-f0-9]{64}$/.test(image)) {
+    throw new SeptError("Hands image must already be locally available with immutable identity");
+  }
+  receipt.image = image;
+}
+
+function initialReceipt(
+  options: Record<string, string>,
+  engine: DockerEngineControl,
+): HandsReceipt {
+  return {
+    version: 1,
+    owner: newHandsOwner(),
+    engineSocket: realpathSync(options["engine-socket"] ?? ""),
+    socketIdentity: engine.socketIdentity,
+    daemonId: engine.daemonId,
+    image: `sha256:${"0".repeat(64)}`,
+    phase: "prepared",
+  };
+}
+
+async function createContainer(
+  root: string,
+  receipt: HandsReceipt,
+  engine: DockerEngineControl,
+  signal: AbortSignal,
+): Promise<void> {
+  receipt.phase = "creating";
+  writeHandsReceipt(root, receipt);
+  receipt.containerId = handsDocker(root, receipt, createHandsArguments(root, receipt));
+  await inspectHandsOwner(root, receipt, engine);
+  assertNotCancelled(signal);
+  handsDocker(root, receipt, ["start", receipt.containerId]);
+  const state = await inspectHandsOwner(root, receipt, engine);
+  if (typeof state.StartedAt !== "string" || state.Running !== true) {
+    throw new SeptError("Hands start generation was not established");
+  }
+  receipt.generation = state.StartedAt;
+  writeHandsReceipt(root, receipt);
+  const paths = handsPaths(root);
+  atomicWrite(paths.handsConfigurationPath, {
+    profile: "docker-linux-warm-v1",
+    engineSocket: receipt.engineSocket,
+    containerId: receipt.containerId,
+    generation: receipt.generation,
+    workspace: paths.workspaceRoot,
+    resources: join(root, "resources"),
+    dataDomain: "private",
+    workspaceLimits: { bytes: 134217728, inodes: 32768 },
+    shell: false,
+    readOnlyMounts: [],
+  });
+  await captureHandsOwner(
+    root,
+    receipt,
+    loadHandsConfiguration(paths.handsConfigurationPath),
+    engine,
+  );
+  assertNotCancelled(signal);
+}
+
+async function activatePermissions(root: string, files: boolean): Promise<void> {
+  const paths = handsPaths(root);
+  const policy = join(root, "evidence", "initial-policy.json");
+  atomicWrite(policy, {
+    mode: "scoped",
+    workspace: { read: files, write: files },
+    selected: [],
+    execute: false,
+    network: false,
+  });
+  await runPermissions(
+    {
+      command: "permissions",
+      action: "set",
+      options: { hands: paths.handsConfigurationPath, policy, revision: "0" },
+    },
+    paths.stateRoot,
+    paths.agentDir,
+  );
+}
+
+async function initializationFailure(
+  root: string,
+  receipt: HandsReceipt,
+  engine: DockerEngineControl,
+): Promise<void> {
+  let stopped = receipt.phase === "prepared";
+  try {
+    if (!stopped) {
+      await stopHandsOwner(root, receipt, engine);
+      stopped = true;
+    }
+  } catch {
+    // Unknown ownership never authorizes a broader stop; retain evidence for explicit reconciliation.
+  } finally {
+    receipt.phase = "failed";
+    writeHandsReceipt(root, receipt);
+    atomicWrite(join(root, "evidence", "initialization-failure.json"), {
+      stopped,
+      reconciliationRequired: !stopped,
+    });
+  }
+}

package/src/cli/options.ts

@@ -6,6 +6,7 @@
 import { CliError } from "./errors.js";
 
 const OPTION_KEYS = {
+  hands: ["root", "engine-socket", "image", "access"],
   worker: ["hands", "agent-dir", "host", "port", "state-dir", "workspace-root"],
   run: [
     "hands",
@@ -83,7 +84,8 @@ export function parseCliInvocation(argv: string[]): CliInvocation | undefined {
   if (!isCommand(command)) {
     return undefined;
   }
-  const hasAction = command === "models" || command === "auth" || command === "permissions";
+  const hasAction =
+    command === "models" || command === "auth" || command === "permissions" || command === "hands";
   const action = hasAction ? argv[3] : undefined;
   const options = parseOptions(argv.slice(hasAction ? 4 : 3), OPTION_KEYS[command]);
   return action === undefined ? { command, options } : { command, action, options };

package/src/cli.ts

@@ -15,7 +15,7 @@ async function main(): Promise<void> {
   const invocation = parseCliInvocation(process.argv);
   if (invocation === undefined) {
     process.stderr.write(
-      "Usage: sept worker|run|doctor|health|models|auth|permissions [action] [options]\n",
+      "Usage: sept worker|run|doctor|health|models|auth|permissions|hands [action] [options]\n",
     );
     process.exitCode = 2;
     return;

package/src/execution/index.ts

@@ -34,3 +34,13 @@ export {
 
 /** 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";

package/docs/architecture.md

@@ -1,168 +0,0 @@
-# SEPT module map
-
-SEPT exposes three npm entries over one runtime: `sept-agent` composes a complete worker, `sept-agent/client` is bounded HTTP transport, and `sept-agent/hands` exposes existing trusted operator configuration/filter helpers. Only those entries are consumer APIs.
-
-SEPT is organized by the mechanisms it owns. Each mechanism has one public `index.ts`; production callers outside that folder use that surface rather than implementation files. Focused tests may import an implementation directly when doing so avoids widening a runtime facade.
-
-```text
-src/
-  index.ts                       export-only root npm entry
-  hands.ts                       export-only operator npm entry
-  worker-api.ts                  shared public worker contracts/identical function binding
-  hands-api.ts                   shared public hands contracts/identical helper bindings
-  package-metadata.ts            import-safe installed package/Pi metadata
-  worker/
-    index.ts                     internal complete-composition boundary
-    worker.ts                    createWorker, bound readiness and shared idempotent stop
-    capabilities.ts              shared CLI/factory/direct policy and Pi/backend wiring
-  client/
-    index.ts                     export-only public client entry and type-only DTOs
-    client.ts                    five existing HTTP operations, stable caller IDs
-    request-codecs.ts            origin/header/identifier/page/request bounds
-    response-codecs.ts           unknown JSON, durable DTO/status/identity/cursor checks
-    transport.ts                 fetch, first abort/timeout, streamed byte bounds
-    errors.ts                    fixed safe TaskClientError classifications
-  cli.ts                         installed dispatch, argv/env/defaults/signals/telemetry
-  cli/
-    auth-interaction.ts          terminal adapter for Pi AuthInteraction
-  model-access/
-    index.ts                     intentional public surface
-    contracts.ts                 credential-blind provider/model/auth/selection DTOs
-    input.ts                     hostile-object narrowing at configuration boundaries
-    jsonc.ts                     bounded JSONC parsing for Pi models.json
-    custom-configuration.ts      endpoint, credential, and rollover-metadata safety
-    model-metadata.ts            identifiers, model limits, and built-in fallback pair
-    pod-selection.ts             atomic credential-free Pod default persistence
-    normalization.ts             credential-blind Pi metadata and error projection
-    runtime-factory.ts           validated installed Pi ModelRuntime construction
-    service.ts                   catalogue, authentication, selection, and preflight facade
-  durable/
-    index.ts                     durable state public surface
-    contracts.ts                 run, task, handover, conversation, lifecycle contracts
-    errors.ts                    classified durability and capacity failures
-    limits.ts                    queue, record, conversation, and control bounds
-    filesystem.ts                atomic files, fsync ordering, bounded JSONL scanning
-    validation-primitives.ts     shared hostile-input narrowing primitives
-    state-codecs.ts              manifest and lifecycle-snapshot codecs
-    evidence-codecs.ts           event, message, conversation, and readiness codecs
-    control-codecs.ts            assistant control and handover validation
-    lease.ts                     stable process identity and exclusive durable leases
-    run-evidence.ts              sequenced internal events and bounded lifecycle logs
-    conversation-store.ts        bounded client conversation retention and recovery
-    operator-queue.ts            exact input admission, proof, and compaction
-    context-transfer-store.ts    checkpoint and handover durability ordering
-    run-store.ts                 cohesive facade over one run's durable mechanisms
-    run-discovery.ts             fail-closed restart discovery
-    worker-lifecycle-store.ts    durable drain/readiness authority
-  ingress/
-    index.ts                     HTTP public surface
-    errors.ts                    request errors and HTTP status mapping
-    service.ts                   authenticated HTTP, model projection, replay, SSE
-    validation.ts                task/workspace validation and model preflight composition
-    webhook.ts                   normalized event validation, hashes, receipts
-    webhook-router.ts            idempotent event-to-worker routing
-  observability/
-    index.ts                     injected facade and construction surface
-    contract.ts                  business-facing observability contract
-    configuration.ts             identity, resource, exporter selection
-    logger.ts                    bounded redacted JSON stderr logging
-    safe-fields.ts               field allowlist and value bounds
-    exporters.ts                 contained exporter wrappers
-    metrics.ts                   runtime instruments and bounded state
-    setup.ts                     SDK/exporter selection and signal-owner construction
-    telemetry.ts                 facade implementation and signal lifecycle
-    tracing.ts                   spans, propagation, limits, provider
-  pi-integration/
-    index.ts                     Pi session-policy public surface
-    diagnostics.ts               non-secret installed diagnostics
-    prompts.ts                   control, continuation, handover prompts
-    rollover.ts                  adaptive arithmetic and durable evidence
-    durable-host.ts              native Harness/conversation lifetime and sanitized events
-    durable-runtime.ts           authenticated Models, registry and SQLite FULL construction
-    durable-invocation.ts        native submission/recovery and finalized-usage steering
-    durable-admission.ts         bounded captured operator IDs for native admission
-    durable-session-files.ts     strict native locators and unique successor discovery
-    durable-resources.ts         operator prompts/skills and untrusted repository instructions
-    durable-extensions.ts        bounded trusted native module loading
-    durable-tools.ts             existing Pi tools registered as native durable tasks
-    message-text.ts              text-only native response projection
-  execution/
-    index.ts                     supplied backend public boundary
-    contracts.ts                 one bounded effect/resource port and profile identity
-    profile.ts                   actual Linux isolation and mount provenance validation
-    protocol.ts                  bounded hostile request/result codecs
-    docker-backend.ts            exclusive namespace lease, live authority and joined cancellation
-    docker-engine.ts             explicit local Unix-socket Engine HTTP/exec control
-    warm-channel.ts              authenticated resident RPC and serial parent operations
-    hands-entry.ts               retained installed Pi body dispatch inside hands
-    hands-resident.ts            resident frames and operation-local effect acknowledgements
-    hands-processes.ts           guarded attachments and exact namespace lifetime
-    hands-process-owner.ts       fixed command UID and bounded descendant joins
-    hands-native-child.ts        minimal native search child streams/events over that owner
-    hands-selected-inputs.ts     opening image/sealed-host checks and exact image aliases
-    hands-resources.ts           protected authorized resource epoch view
-    native-env.ts                minimum native environment with typed unsupported operations
-  runtime/
-    index.ts                     runtime public surface
-    controller.ts               durable cycling and Pi-native cancellation state machine
-    worker.ts                   single resident slot, drain, controller ownership
-```
-
-The dependency direction is:
-
-```text
-public root / CLI worker -> worker -> ingress -> runtime -> pi-integration -> model-access
-CLI direct -----------------> worker capability helpers -> native host/backend
-public client -> HTTP -> ingress (no root/CLI/worker import)
-public hands -> existing configuration/firewall functions
-
-composition -> ingress -> runtime -> pi-integration -> model-access
- |        |                         |               |
- +--------+-------------------------+---------------+-> durable
-          +-------------------------+-----------------> observability contract
-```
-
-`model-access` is normalization and control around the installed Pi `ModelRuntime`, not another provider layer. Pi owns provider/model discovery, auth, credential storage/refresh, availability, compatible endpoint execution, and model requests. SEPT exposes only approved metadata, reads the atomic credential-free Pod default for every admission, and preflights the final pair before `RunStore.create()`. Direct and webhook tasks use the same admission function and service. Login remains UI-neutral in the service; only the installed CLI supplies an interaction adapter. Plain HTTP exposes authenticated read/selection routes but no secret mutation.
-
-`durable` has no dependency on higher mechanisms. Existing format-2 manifests with fixed rollover options remain readable and normalize to format 3; all new manifests contain the resolved provider/model and no rollover knobs or credentials. The state-root `worker-state.json` remains authoritative for accepting/draining/drained readiness. Each run's bounded `conversation.jsonl` remains the sole client-facing event contract, separate from internal lifecycle events, logs, Pi sessions, rollover evidence, and checkpoint/handover controls.
-
-`pi-integration` receives the selected Pi model from the manifest, verifies context/output metadata again, and opens the run's native Durable Harness with SQLite FULL and compaction disabled. Native conversation IDs are numeric; SEPT exposes their string form and bounded versioned locators. `rollover.json` remains scoped to provider, model, conversation identity and context window. Native finalized-response hooks supply usage; a stable steering submission is reused after restart or resumed with a distinct interrupted-handover recovery input. Handover JSON, Markdown, event and state commit before a fresh native conversation and provider UUID are created. Exact captured operator IDs accompany admission, so later queue arrivals cannot be marked in an earlier prompt.
-
-Trusted agent-directory modules follow Node process/module-URL caching: host replacement and same-process worker stop/reopen do not guarantee edited-code reload; use a fresh Node process. They register native declarative extensions, including supported tools, sections, hooks, wrappers and tasks. Project trust remains false; repository instructions do not execute plugins. The existing Pi tools are adapted into native Durable tasks with explicit replay safety and cancellation. Both their complete existing bodies and the minimum native environment operations use the consumer-supplied `execution` backend. The backend enforces effects separately from brain; Pi remains the scheduler, replay and provider owner. New runs have one engine, with no coding-agent production host or historical transcript converter.
-
-`runtime` retains execution, cancellation, wait/wake, shutdown, limits, restart adoption, and slot ownership without knowing HTTP. `ingress` translates the authenticated API and webhook contract onto runtime and model-access services. `observability` imports no business mechanisms and receives only bounded classifications/numbers; model identifiers, credentials, auth interactions, prompts, and provider errors are not telemetry fields.
-
-The architecture suite enforces index-only cross-mechanism imports. `npm run build` cleans `dist`, so deleted or moved modules cannot survive as stale executable output. SEPT does not add ACP, a second agent loop, provider client, tokenizer, compactor, dashboard, cloud service, or model server.
-
-`worker/worker.ts:createWorker` composes the authenticated service, capability admission and actual post-bind endpoint closure. The installed CLI worker calls that same factory; direct run reuses the extracted capability helpers. Library options are explicit, imports are inert, and the caller owns signals/telemetry shutdown. Ready means listener/router plus synchronous adoption, while native Pi work continues asynchronously and publishes task state. Stop reuses the durable boundary; waiting reopen preserves session and budgets.
-
-This shared composition binds the single consumer-supplied Docker Linux hands container into the installed callers. Brain retains credentials, Models/Harness and SEPT control state; hands gets namespace aliases, a clean environment and exact bounded read-only resource projections. Missing/unsupported enforcement refuses without a local fallback. The `docker-linux-warm-v1` profile uses the same finite private `/workspace` tmpfs with default file rights and explicitly granted commands. Consumers seed/export it and preserve bytes before stopping. Selected data/code may be baked read-only image trees, with genuinely `FS_IMMUTABLE`-sealed Linux host inputs retained as optional compatibility. Ordinary RO binds and private-domain RW host binds refuse. The file-only `mutable-file-bind` alternative omits command/discovery traversal and image aliases. Completed commands join namespace descendants; normal close retains the consumer-owned idle namespace. Cancellation/loss stops and verifies it before settlement, and unverified cleanup durably blocks instead of publishing cancellation. Projection refresh relies on private bounded ownership receipts; consumer markers grant no deletion authority. See [the profile contract](pi-contract.md#supplied-hands-reference-profile) and [consumer image recipe](pi-contract.md#selected-image-data-and-code).
-
-The bounded channel carries version/generation/configuration/session/sequence-correlated operation, effect check/ack and command frames. Authentication grants no rights: the live parent rechecks policy, roots, task identity, pins, expiry and cancellation at admission, immediately before effects/command start and at result acceptance. Opening qualifies immutable source/image/kernel facts; live checks retain bounded generation/mount/topology and anchored inode ownership without scanning the workspace on each call. Limits remain 512 KiB request, 4 MiB result and FIFO eight. Ordinary body errors preserve a healthy resident; broken framing/identity/cleanup seals admission and stops the exact generation before truthful settlement.
-
-## Capability policy ownership
-
-`durable/capability-policy.ts` owns the bounded private record, exact codec, fsync and revision CAS; it imports no lifecycle or execution behavior. `cli/permissions.ts` is the local operator writer; `worker/capabilities.ts` owns the shared worker/direct capability composition. `execution/capability-admission.ts` maps validated rights onto the supplied namespace and effective registrations. `DockerExecutionBackend` owns live revision/generation checks, queued/active ownership, policy-change shutdown and run binding reconciliation. `docker-control.ts` owns kernel qualification, bound lifetime receipts and exact-generation stop verification through the explicit `DockerEngineControl` Unix-socket HTTP client; `profile-configuration.ts` decodes trusted configuration while `profile.ts` validates actual kernel containment. `hands-files.ts` supplies complete supported Pi file operation seams within hands, with retained directory descriptors, independent rights and bounded regular single-link inode access.
-
-`hands-selected-inputs.ts` parses optional `imageSelected` exact `{ alias }` objects, normalizes absence to `[]` and runs opening selected-tree/image qualification from `docker-control.qualifyKernelProfile`. Image aliases use `[A-Za-z0-9_-]{1,64}`; existing host aliases retain `[A-Za-z0-9_-]+`, including longer aliases. All image/RO/RW aliases share the existing eight-unique-alias bound and policy grants. Image roots have no host source/stat/seed path. The C checker retains one descriptor-anchored bounded type/link/device/depth/count/path walk, requiring per-inode immutable flags only for the sealed-host mode. Exact image/read-only-rootfs and live image/generation/mount receipts protect baked roots; equal, ancestor and subtree mounts refuse. Configuration/data/code changes require fresh image where applicable, fresh generation and authority after quiescence. Literal `uid-dac-fixed-helper-v1` in the kernel receipt prevents old authority being silently reused; incompatible history remains intact.
-
-Policy authority never enters HTTP task/webhook/model input. Nonempty old state without policy remains dormant; malformed present state fails closed. Native Harness still owns scheduling, safe/unsafe replay and task identity; the worker still owns its single slot, drain, exact queues and budgets. Live denial wins before any queued/replayed effect, while already accepted durable inputs remain recoverable. Supported uniform-read policy retains whole native search/resource bodies. Partial-read namespaces omit search/list and workspace resource discovery; they keep independent anchored file tools and trusted global sections. There is no alternate scheduler, policy editor, provisioner or new operation journal.
-
-`hands-guard.c` is the fixed Linux constructor for trusted entry process protection. The build stage alone compiles its shared library; the runtime image contains the fixed library under its read-only root. `hands-guarded-command.ts` composes the cleared offline environment, fixed preload and disabled SIGUSR1 inspection; a fixed Node prelude verifies version-2 constructor acknowledgement before the resident starts. The resident UID10002 retains imports, private resource epoch and a correlated non-TTY RPC attachment. Commands run UID10003:GID10002 without the brain group; `/app` is UID10002:GID10001 mode 0750 and resident HOME/epoch/MIME captures are private 0700 with files 0600. Root-owned0555 command/rg/fd executables live in `/usr/local/libexec/sept`; private HOME contains matching supplied discovery aliases. The command entry establishes a separate session for the SIGCONT boundary. Fixed command/join helpers retain sole execution/descendant ownership. DAC/nondumpability/guards protect resident bytes, memory, signals, imports and control descriptors. Some public proc metadata and resident command-line correlation remain visible; correlation and command stdout cannot acknowledge or dispatch authority.
-
-Pi still owns the full grep/find bodies. The image patch adds their optional native spawn callback, bound only during the current admitted operation. `hands-command-authority.ts` reconstructs exact native argv for the matching grep→rg/find→fd parent, requires current READ authority/uniform readability, rejects private roots and supplies network:false without a new helper timer. These children consume no Bash execute grant. Fixed `/tmp` capture-name exclusions remain. `hands-native-child.ts` adapts separate bounded stdout/stderr, kill/error/close and drain behavior to the existing command owner; it is not another scheduler or process owner. Per-stream UTF-8/order survives the transport; Bash alone combines chunks in arrival order. Custom results use only stdout (4096-byte bound), with stderr drained within the shared 4 MiB output budget. Helper loss/overflow/cancellation cannot yield partial normal success; close/settlement waits for exact joins and native limit/abort conventions remain Pi-owned.
-
-Image delivery uses exactly four assets in `image/pi-native-search`: overlay, patch, provenance and README. Revision `sept-native-search-v1` overlays only `dist/core/tools/{find,grep}.{js,d.ts}` after unchanged locked `npm ci`; host Pi 1.1.0 remains stock, with the exact locked package graph. Docker verifies upstream/overlay and effective bytes before compile, after prune and after final COPY; opening qualification rechecks pinned private provenance and effective installed hashes. The pinned registry archive omits LICENSE; the existing README retains the exact upstream MIT notice and is privately copied with provenance. See [reproduction/provenance](../image/pi-native-search/README.md).
-
-
-`durable/capability-request-codec.ts` validates exact bounded operation/content and decision facts; `capability-requests.ts` persists at most 32 immutable original denials and one matching retry claim through the existing policy lease/atomic helpers. `execution/capability-requests.ts` connects those facts to live run/policy/generation checks; the Docker backend retains effect ownership, expiry timers, cancellation and namespace joins. `cli/permission-decisions.ts` owns local inspection/decision/direct retry only. Native Pi remains the sole task journal/scheduler/provider loop. Pending wait is typed by `permissionRequestId`, published after closure and cleared only by the shared explicit accepted-message wake. Recovery of an interrupted request closes the captured namespace before checkpointing input without dispatching native work. One optional operator-registered hand uses anchored hash-verified code in `execution/custom-hand.ts`, outside the protected entry and brain API.
-
-The single custom tool pins its operator path/hash/replay in native task memo evidence before execution intent. Recovery requires that original pin to be present and unchanged before effects; replacement code needs a new native task. This memo grants no permission and never resumes a denied original call.
-
-Custom code must be below an admitted RO image or genuinely sealed host alias and satisfy the existing bounded arbitrary-execution profile. Anchored code is read/hash-checked once (64 KiB maximum), then the exact bytes/input are checked again by the parent and passed to the clean Node child. Native input has text `maxLength: 256` plus a 1024-byte transport bound, optional boolean network intent, stdout-only 4096-byte/64-line native output limits and the existing 5-second timeout. SAFE replay rechecks current pin/authority; UNSAFE interrupted effects retain uncertainty without replay. No native API object or credentials cross into the child.
-
-Hands networking has two enforced layers: the consumer owns an exact IPv4/IPv6 kernel filter excluding special/metadata and all reachable public/private brain endpoints, and the resident remains socket denied while each actual command installs inherited seccomp socket denial unless explicit policy/exact approval and call intent permit network. Explicit grants include legitimate private/CGNAT/ULA peers and private DNS. Shared protected/gateway resolvers permit only UDP/TCP destination53 with complete nonconflicting protected endpoint facts. SEPT validates current brain interfaces, runtime-derived topology, DNS and actual filter tables before effects through its trusted control client; configuration fingerprints bind the complete portable consumer inventory. It does not provision a namespace or run a network broker. Native Bash/custom schemas preserve bounded network intent in operator request/retry identities; network expansion uses the existing quiescent fresh-generation rule. Credentials and Models remain brain-owned.
-
-Support is bound to the exact qualified source/image/host combination. Native Windows worker operation remains unsupported because Unix control/POSIX leases remain; Intel Mac and Windows Docker Linux/WSL recipes remain unqualified. [The repository-only historical record at d361123](https://github.com/DB-Conneely/sept/blob/d361123d7c242db5af3ae2d1cb4daea4a2acdeff/docs/as-built/capability-confinement.md) retains source/image evidence and publicIPv6/UFW/provider-outage/OAuth and unknown original stream-loss qualifications.
-
-The package ships matching source maps/source, canonical docs, notices and all four image assets. Its allowlist excludes tests/audits/private evidence/state/credentials. `prepack` reuses the existing clean/build; it adds no compiler, bootstrap, provider or provisioner. The tarball is not a complete Docker build context. [SDK ownership](sdk.md) and [the documentation index](index.md) are the consumer entry points.