sept-agent 0.1.3 → 0.1.4

package/dist/src/cli/hands-owner.js

@@ -0,0 +1,83 @@
+/** 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, } from "../execution/index.js";
+import { handsDocker } from "./hands-docker.js";
+import { readHandsMetadata, writeHandsReceipt } from "./hands-record.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function record(value) {
+    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) {
+    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, receipt, engine) {
+    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, receipt, configuration, engine) {
+    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, receipt, engine) {
+    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, receipt, engine) {
+    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((resolve) => setTimeout(resolve, 100));
+    }
+    throw new SeptError("Hands setup shutdown could not be verified");
+}
+//# sourceMappingURL=hands-owner.js.map

package/dist/src/cli/hands-owner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hands-owner.js","sourceRoot":"","sources":["../../../src/cli/hands-owner.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/hands-record.d.ts

@@ -0,0 +1,33 @@
+/** 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 declare function handsPaths(root: string): HandsPaths;
+/** Refuse lexical aliases and mutable ancestors before creating or reading ownership. */
+export declare function trustedHandsRoot(value: string | undefined, fresh?: boolean): string;
+/** Create only a new root: a failed or foreign instance is never overwritten or adopted by init. */
+export declare function createHandsRoot(root: string): HandsPaths;
+/** Persist recovery ownership before creating a container and after every identity transition. */
+export declare function writeHandsReceipt(root: string, receipt: HandsReceipt): void;
+/** Read bounded private ownership, refusing edited schema, symlinks, hardlinks or broad permissions. */
+export declare function readHandsReceipt(root: string): HandsReceipt;
+/** Read private bounded setup metadata without presenting hostile JSON or filesystem diagnostics. */
+export declare function readHandsMetadata(path: string, maximum: number): unknown;
+/** Generate the unguessable container ownership label before any Engine effect. */
+export declare function newHandsOwner(): string;

package/dist/src/cli/hands-record.js

@@ -0,0 +1,164 @@
+/** 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";
+/** Derive the sole supported fresh-instance layout. */
+export function handsPaths(root) {
+    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, fresh = false) {
+    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) {
+    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) {
+    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) {
+    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, receipt) {
+    atomicWrite(join(root, "evidence", "setup.json"), receipt);
+}
+/** Read bounded private ownership, refusing edited schema, symlinks, hardlinks or broad permissions. */
+export function readHandsReceipt(root) {
+    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, maximum) {
+    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 = JSON.parse(readFileSync(path, "utf8"));
+        return raw;
+    }
+    catch (error) {
+        throw new SeptError("Hands setup metadata is unavailable or malformed", { cause: error });
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function decodeReceipt(raw) {
+    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, pattern) {
+    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) {
+    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() {
+    return randomUUID();
+}
+//# sourceMappingURL=hands-record.js.map

package/dist/src/cli/hands-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hands-record.js","sourceRoot":"","sources":["../../../src/cli/hands-record.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/hands.d.ts

@@ -0,0 +1,3 @@
+import type { CliInvocation } from "./options.js";
+/** Execute the two installed operator commands; signals join cleanup before the process exits. */
+export declare function runHands(invocation: CliInvocation): Promise<unknown>;

package/dist/src/cli/hands.js

@@ -0,0 +1,169 @@
+/** 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 { createHandsRoot, handsPaths, newHandsOwner, trustedHandsRoot, writeHandsReceipt, } 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) {
+    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 = () => {
+        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) {
+    if (signal.aborted) {
+        throw new SeptError("Hands setup cancelled; ownership and recovery receipts retained");
+    }
+}
+async function initialize(options, signal) {
+    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, options, engine, signal) {
+    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) {
+        await initializationFailure(root, receipt, engine);
+        throw new SeptError("Hands initialization failed; recovery evidence retained under --root", {
+            cause: error,
+        });
+    }
+    finally {
+        release();
+    }
+}
+function resolveImage(root, receipt, imageName) {
+    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, engine) {
+    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, receipt, engine, signal) {
+    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, files) {
+    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, receipt, engine) {
+    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,
+        });
+    }
+}
+//# sourceMappingURL=hands.js.map

package/dist/src/cli/hands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hands.js","sourceRoot":"","sources":["../../../src/cli/hands.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/options.d.ts

@@ -3,6 +3,7 @@
  * strings toward command composition without interpreting runtime or credential semantics.
  */
 declare const OPTION_KEYS: {
+    readonly hands: readonly ["root", "engine-socket", "image", "access"];
     readonly worker: readonly ["hands", "agent-dir", "host", "port", "state-dir", "workspace-root"];
     readonly run: readonly ["hands", "agent-dir", "resume", "message", "max-epochs", "max-invocations", "model", "provider", "role", "state-dir", "task", "thinking", "timeout", "workspace"];
     readonly doctor: readonly ["agent-dir", "provider"];

package/dist/src/cli/options.js

@@ -4,6 +4,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",
@@ -68,7 +69,7 @@ export function parseCliInvocation(argv) {
     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/dist/src/cli/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/cli/options.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/cli/options.ts"],"names":[],"mappings":"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"}

package/dist/src/cli.js

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

package/dist/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,IAAI,SAAS,GAAG,cAAc,CAAC;AAE/B,KAAK,UAAU,IAAI;IACjB,MAAM,UAAU,GAAG,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,mFAAmF,CACpF,CAAC;QACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;IACnC,IAAI,UAAU,CAAC,OAAO,KAAK,QAAQ,IAAI,UAAU,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QACpE,SAAS,GAAG,eAAe,CAAC;YAC1B,cAAc,EAAE,QAAQ,CAAC,WAAW;YACpC,OAAO,EAAE,UAAU,CAAC,OAAO;SAC5B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,CAAC,KAAK,GAAG,QAAQ,UAAU,CAAC,OAAO,EAAE,CAAC;IAC7C,MAAM,cAAc,CAAC;QACnB,GAAG,UAAU;QACb,GAAG,QAAQ;QACX,QAAQ,EAAE,qBAAqB,CAAC,UAAU,CAAC,OAAO,CAAC;QACnD,SAAS;KACV,CAAC,CAAC;AACL,CAAC;AAED,MAAM,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,KAAc,EAAE,EAAE;IAC1C,SAAS,CAAC,GAAG,CACX,gBAAgB,EAChB,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,EACjE,OAAO,CACR,CAAC;IACF,MAAM,SAAS,CAAC,QAAQ,EAAE,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1F,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,IAAI,SAAS,GAAG,cAAc,CAAC;AAE/B,KAAK,UAAU,IAAI;IACjB,MAAM,UAAU,GAAG,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,yFAAyF,CAC1F,CAAC;QACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;IACnC,IAAI,UAAU,CAAC,OAAO,KAAK,QAAQ,IAAI,UAAU,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QACpE,SAAS,GAAG,eAAe,CAAC;YAC1B,cAAc,EAAE,QAAQ,CAAC,WAAW;YACpC,OAAO,EAAE,UAAU,CAAC,OAAO;SAC5B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,CAAC,KAAK,GAAG,QAAQ,UAAU,CAAC,OAAO,EAAE,CAAC;IAC7C,MAAM,cAAc,CAAC;QACnB,GAAG,UAAU;QACb,GAAG,QAAQ;QACX,QAAQ,EAAE,qBAAqB,CAAC,UAAU,CAAC,OAAO,CAAC;QACnD,SAAS;KACV,CAAC,CAAC;AACL,CAAC;AAED,MAAM,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,KAAc,EAAE,EAAE;IAC1C,SAAS,CAAC,GAAG,CACX,gBAAgB,EAChB,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,EACjE,OAAO,CACR,CAAC;IACF,MAAM,SAAS,CAAC,QAAQ,EAAE,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1F,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/src/execution/index.d.ts

@@ -9,3 +9,7 @@ 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";

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.3"
+    "sept-agent": "0.1.4"
   }
 }