@fungi.computer/truffle 0.1.1 → 0.2.0

package/dist/private-local-sandbox-policy.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+/** Retained POSIX folder grammar; no separate safe/YOLO representation. */
+export declare const localAgentFolderSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/** Resolve stored folder authority before opening work, not after acquisition. */
+export declare function resolveAgentFolder(project: string, folder: string): {
+    folder: string;
+    absolute: string;
+};
+/** Containment authority, not an approval setting or an execution mode. */
+export type LocalSandboxPolicy = Readonly<{
+    writableRoot: string;
+    readOnly: readonly string[];
+    immovable: readonly string[];
+}>;
+/** One logical/resolved authority for Files, bwrap and Seatbelt. */
+export declare function protectedSandboxPaths(paths: readonly string[]): string[];
+/**
+ * Recompute for every command: the previous command may have initialized Git.
+ * An internal caller may tighten the directory budget, never widen the ceiling.
+ */
+export declare function sandboxPolicy(project: string, folder: string, directoryLimit?: number): LocalSandboxPolicy;

package/dist/private-local-sandbox-policy.js

@@ -0,0 +1,121 @@
+import { lstatSync, readdirSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep, } from "node:path";
+import { z } from "zod";
+/** Retained POSIX folder grammar; no separate safe/YOLO representation. */
+export const localAgentFolderSchema = z
+    .string()
+    .min(1)
+    .refine((value) => !posix.isAbsolute(value) &&
+    !value.includes("\\") &&
+    !value.includes("\0") &&
+    !value.split("/").includes(".."), "Agent folder must be a project-relative POSIX path without '..'")
+    .transform((value) => posix.normalize(value));
+/** Resolve stored folder authority before opening work, not after acquisition. */
+export function resolveAgentFolder(project, folder) {
+    const root = realpathSync(project);
+    const absolute = realpathSync(resolve(root, localAgentFolderSchema.parse(folder)));
+    const within = relative(root, absolute);
+    if (isAbsolute(within) || within === ".." || within.startsWith(`..${sep}`))
+        throw new Error("Agent folder resolves outside the project");
+    if (!lstatSync(absolute).isDirectory())
+        throw new Error("Agent folder must be a directory");
+    return { folder: within.split(sep).join("/") || ".", absolute };
+}
+/** Missing reserved names resolve through their nearest existing ancestor. */
+function canonicalPath(path) {
+    if (lstatSync(path, { throwIfNoEntry: false }) !== undefined)
+        return realpathSync(path);
+    return join(canonicalPath(dirname(path)), basename(path));
+}
+/** One logical/resolved authority for Files, bwrap and Seatbelt. */
+export function protectedSandboxPaths(paths) {
+    return [
+        ...new Set(paths.flatMap((path) => {
+            if (!isAbsolute(path))
+                throw new Error("Sandbox protected paths must be absolute");
+            const logical = resolve(path);
+            return [logical, canonicalPath(logical)];
+        })),
+    ];
+}
+// A project tree is untrusted input. Refuse incomplete discovery rather than
+// silently protecting only a prefix or allowing a bare command to bypass it.
+// Bound directory traversal, not ordinary dependency-file payloads.
+const maximumDiscoveryDirectories = 100_000;
+const discoveryDirectoryLimit = z
+    .number()
+    .int()
+    .min(1)
+    .max(maximumDiscoveryDirectories);
+function gitProtection(root, directoryLimit) {
+    const pending = [
+        { path: root, kind: "tree" },
+    ];
+    const readOnly = [];
+    const immovable = [];
+    let discoveredDirectories = 1; // The writable root itself.
+    for (let directory = pending.pop(); directory !== undefined; directory = pending.pop()) {
+        const entries = readdirSync(directory.path, { withFileTypes: true });
+        const has = (name) => entries.some((entry) => entry.name === name);
+        const git = directory.kind === "git" ||
+            basename(directory.path) === ".git" ||
+            (has("HEAD") && (has("objects") || has("commondir"))) ||
+            (directory.kind === "modules" &&
+                (has("HEAD") || has("config") || has("hooks")));
+        // A nested Git-file checkout is a repository boundary, not another copy of
+        // the selected project's payload to walk. The normal root scan owns common
+        // administration; never follow the pointer. Never prune the selected root or
+        // directories already recognized as Git administration.
+        if (directory.path !== root &&
+            !git &&
+            entries.some((entry) => entry.name === ".git" && entry.isFile())) {
+            readOnly.push(join(directory.path, ".git"));
+            continue;
+        }
+        if (git) {
+            immovable.push(directory.path);
+            readOnly.push(join(directory.path, "hooks"), join(directory.path, "config"), join(directory.path, "config.worktree"));
+        }
+        for (const entry of entries) {
+            const path = join(directory.path, entry.name);
+            if (entry.name === ".git" && !entry.isDirectory())
+                readOnly.push(path); // Never parse a Git pointer or grant an external dir.
+            if (!entry.isDirectory())
+                continue; // No symlink cycles or outside walks.
+            discoveredDirectories += 1;
+            if (discoveredDirectories > directoryLimit)
+                throw new Error(`Sandbox Git discovery exceeds ${String(directoryLimit)} directories`);
+            let kind = "tree";
+            if (git && entry.name === "modules")
+                kind = "modules";
+            else if (git && entry.name === "worktrees")
+                kind = "worktrees";
+            else if (!git && directory.kind === "modules")
+                kind = "modules";
+            else if (!git && directory.kind === "worktrees")
+                kind = "git";
+            pending.push({ path, kind });
+        }
+    }
+    return { readOnly, immovable };
+}
+/**
+ * Recompute for every command: the previous command may have initialized Git.
+ * An internal caller may tighten the directory budget, never widen the ceiling.
+ */
+export function sandboxPolicy(project, folder, directoryLimit = maximumDiscoveryDirectories) {
+    const limit = discoveryDirectoryLimit.parse(directoryLimit);
+    const root = realpathSync(project);
+    const writableRoot = realpathSync(folder);
+    const within = relative(root, writableRoot);
+    if (isAbsolute(within) || within === ".." || within.startsWith(`..${sep}`))
+        throw new Error("Sandbox folder resolves outside the project.");
+    if (!lstatSync(writableRoot).isDirectory())
+        throw new Error("Sandbox folder must be a directory.");
+    const git = gitProtection(writableRoot, limit);
+    return {
+        writableRoot,
+        readOnly: [join(writableRoot, ".fungi"), ...git.readOnly],
+        immovable: git.immovable,
+    };
+}

package/dist/private-local-sandbox.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import type { LocalSandboxWrites } from "./private-invocation-files.js";
+/** Availability is not a hostile-program security or an approval status. */
+export declare const sandboxStatusSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"available">;
+    requireSandbox: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"unavailable">;
+    requireSandbox: z.ZodBoolean;
+    reason: z.ZodObject<{
+        kind: z.ZodEnum<{
+            missing: "missing";
+            "invalid-digest": "invalid-digest";
+            "digest-mismatch": "digest-mismatch";
+            "not-executable": "not-executable";
+            "unsupported-platform": "unsupported-platform";
+            "invalid-folder": "invalid-folder";
+            "backend-refused": "backend-refused";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>], "state">;
+export type LocalSandboxStatus = z.output<typeof sandboxStatusSchema>;
+export type LocalSandboxControls = LocalSandboxWrites & Readonly<{
+    assertReady(): void;
+    status(): LocalSandboxStatus;
+    close(): void;
+}>;
+/**
+ * Native Local owns the live requirement; the adapter owns only preparation.
+ * Every consumer calls this authority immediately before launching or writing.
+ */
+export declare function createLocalSandboxControls(input: Readonly<{
+    project: string;
+    folder: string;
+    required(): boolean;
+}>): LocalSandboxControls;

package/dist/private-local-sandbox.js

@@ -0,0 +1,114 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+import { establishLocalSandbox, LocalSandboxUnavailable, sandboxUnavailableReasonSchema, } from "./private-local-containment.js";
+import { protectedSandboxPaths, resolveAgentFolder, sandboxPolicy, } from "./private-local-sandbox-policy.js";
+/** Availability is not a hostile-program security or an approval status. */
+export const sandboxStatusSchema = z.discriminatedUnion("state", [
+    z.strictObject({
+        state: z.literal("available"),
+        requireSandbox: z.boolean(),
+    }),
+    z.strictObject({
+        state: z.literal("unavailable"),
+        requireSandbox: z.boolean(),
+        reason: sandboxUnavailableReasonSchema,
+    }),
+]);
+function contains(root, path) {
+    const within = relative(root, path);
+    return (!isAbsolute(within) && within !== ".." && !within.startsWith(`..${sep}`));
+}
+/**
+ * Native Local owns the live requirement; the adapter owns only preparation.
+ * Every consumer calls this authority immediately before launching or writing.
+ */
+export function createLocalSandboxControls(input) {
+    const required = input.required();
+    const folder = resolveAgentFolder(input.project, input.folder);
+    const initial = establishLocalSandbox({
+        project: input.project,
+        folder: folder.absolute,
+    });
+    let sandbox = initial.state === "ready" ? initial.sandbox : undefined;
+    let unavailable = initial.state === "unavailable" ? initial.reason : undefined;
+    if (unavailable !== undefined) {
+        if (unavailable.kind === "invalid-folder")
+            throw new Error(unavailable.message);
+        if (required)
+            throw new LocalSandboxUnavailable(unavailable);
+    }
+    let closed = false;
+    const assertFolder = () => {
+        if (closed)
+            throw new Error("Local sandbox owner is closed");
+        const current = resolveAgentFolder(input.project, input.folder);
+        if (current.absolute !== folder.absolute)
+            throw new Error("Local Agent folder authority changed while open");
+    };
+    const launch = (cwd, argv) => {
+        assertFolder();
+        if (sandbox === undefined) {
+            const admission = establishLocalSandbox({
+                project: input.project,
+                folder: folder.absolute,
+            });
+            if (admission.state === "ready")
+                sandbox = admission.sandbox;
+            else
+                unavailable = admission.reason;
+        }
+        if (sandbox !== undefined) {
+            try {
+                const command = sandbox.command(cwd, argv);
+                unavailable = undefined;
+                return command;
+            }
+            catch (cause) {
+                if (!(cause instanceof LocalSandboxUnavailable))
+                    throw cause;
+                unavailable = cause.reason;
+            }
+        }
+        if (unavailable === undefined)
+            throw new Error("Local sandbox preparation produced no result");
+        if (unavailable.kind === "invalid-folder")
+            throw new Error(unavailable.message);
+        if (input.required())
+            throw new LocalSandboxUnavailable(unavailable);
+        // No executable has started. Only this owner admits the bare fallback.
+        return undefined;
+    };
+    const assertReady = () => {
+        launch(folder.absolute, ["/usr/bin/true"]);
+    };
+    return {
+        launch,
+        assertReady,
+        assertWrite: (path) => {
+            assertReady();
+            const target = resolve(path);
+            const policy = sandboxPolicy(input.project, folder.absolute);
+            if (!contains(policy.writableRoot, target) ||
+                protectedSandboxPaths(policy.readOnly).some((protectedPath) => contains(protectedPath, target)) ||
+                protectedSandboxPaths(policy.immovable).includes(target))
+                throw new Error("Files write targets a protected Local path");
+        },
+        status: () => {
+            if (closed)
+                throw new Error("Local sandbox owner is closed");
+            return unavailable === undefined
+                ? { state: "available", requireSandbox: input.required() }
+                : {
+                    state: "unavailable",
+                    requireSandbox: input.required(),
+                    reason: unavailable,
+                };
+        },
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            sandbox?.close();
+        },
+    };
+}

package/dist/private-local-seatbelt.d.ts

@@ -0,0 +1,24 @@
+import { type LocalSandboxPolicy } from "./private-local-sandbox-policy.js";
+/**
+ * The containment owner supplies temporary-directory lifetime and command-time
+ * protected paths; this adapter owns only the maintained Seatbelt translation.
+ */
+export type SeatbeltPolicy = LocalSandboxPolicy & Readonly<{
+    temporaryDirectory: string;
+}>;
+/**
+ * Paths are argv definitions, never SBPL source. Both the logical name and its
+ * resolved target are protected, including when a protected entry is a symlink.
+ */
+export declare function seatbeltCommand(policy: SeatbeltPolicy, argv: readonly [string, ...string[]]): {
+    executable: string;
+    args: string[];
+    temporaryDirectory: string;
+};
+/** A real startup probe; failure is data, never permission to execute bare. */
+export declare function seatbeltReadiness(policy: SeatbeltPolicy): Readonly<{
+    ready: true;
+}> | Readonly<{
+    ready: false;
+    reason: string;
+}>;

package/dist/private-local-seatbelt.js

@@ -0,0 +1,68 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { protectedSandboxPaths, } from "./private-local-sandbox-policy.js";
+const sandboxExecutable = "/usr/bin/sandbox-exec";
+/**
+ * Paths are argv definitions, never SBPL source. Both the logical name and its
+ * resolved target are protected, including when a protected entry is a symlink.
+ */
+export function seatbeltCommand(policy, argv) {
+    const definitions = [];
+    const parameter = (name, path) => {
+        definitions.push("-D", `${name}=${path}`);
+        return `(param "${name}")`;
+    };
+    const excluded = protectedSandboxPaths(policy.readOnly);
+    const carveouts = excluded.flatMap((path, index) => {
+        const value = parameter(`PROTECTED_${String(index)}`, path);
+        return [
+            `(require-not (literal ${value}))`,
+            `(require-not (subpath ${value}))`,
+        ];
+    });
+    const roots = [policy.writableRoot, policy.temporaryDirectory];
+    const grants = roots.map((path, index) => {
+        const value = parameter(`WRITABLE_ROOT_${String(index)}`, realpathSync(path));
+        return `(require-all (subpath ${value}) ${carveouts.join(" ")})`;
+    });
+    const anchors = [
+        ...new Set([
+            ...roots.map((path) => realpathSync(path)),
+            ...protectedSandboxPaths(policy.immovable),
+        ]),
+    ].map((path, index) => {
+        const value = parameter(`ANCHOR_${String(index)}`, path);
+        return `(deny file-write-unlink (require-all (vnode-type DIRECTORY) (literal ${value})))`;
+    });
+    const base = readFileSync(new URL("./seatbelt/safe-base.sbpl", import.meta.url), "utf8");
+    const profile = [
+        base,
+        "(allow file-read*)",
+        `(allow file-write* ${grants.join(" ")})`,
+        ...anchors,
+        "(deny system-fcntl (fcntl-command 80 110))",
+    ].join("\n");
+    return {
+        executable: sandboxExecutable,
+        args: ["-p", profile, ...definitions, "--", ...argv],
+        temporaryDirectory: realpathSync(policy.temporaryDirectory),
+    };
+}
+/** A real startup probe; failure is data, never permission to execute bare. */
+export function seatbeltReadiness(policy) {
+    const command = seatbeltCommand(policy, ["/usr/bin/true"]);
+    const result = spawnSync(command.executable, command.args, {
+        env: { TMPDIR: command.temporaryDirectory },
+        encoding: "utf8",
+        timeout: 5_000,
+    });
+    const diagnostic = result.error?.message ?? result.stderr.trim();
+    return result.status === 0
+        ? { ready: true }
+        : {
+            ready: false,
+            reason: diagnostic.length > 0
+                ? diagnostic
+                : `sandbox-exec exited ${String(result.status)} (${String(result.signal)})`,
+        };
+}

package/dist/private-local-service-contract.d.ts

@@ -1,19 +1,29 @@
-import type { PrivateFungiMcpSelection } from "./private-fungi-mcp-selection.js";
+import type { PrivateFungiMcpSelection } from "./private-fungi-mcp-selection-schema.js";
 import type { AuthInteraction } from "@earendil-works/pi-ai";
 import type { PrivateLocalAuthRequest } from "./private-local-auth-rpc.js";
 import type { LocalAuthResult } from "./auth-cli.js";
 import type { SessionSnapshot, ShiitakeAgent, ShiitakeSession } from "@fungi.computer/shiitake";
 import type { PrivateLocalModelChoice } from "./local-models.js";
 import type { PrivateLocalEffectiveModel } from "./private-local-effective-model.js";
-/** Service identity is checked by handshake, never inferred from a discovery PID. */
+import type { StopAllResult } from "./private-local-stop-all.js";
+import type { ServiceDiagnosticsStatus } from "./private-local-service-log.js";
+import type { LocalSandboxStatus } from "./private-local-sandbox.js";
+import type { LocalUiAttachmentLifetime } from "./private-local-ui-attachment.js";
+/** Live health, not the on-disk identity record or a cached connection snapshot. */
 export type PrivateLocalServiceStatus = Readonly<{
+    /** The client-service wire contract this service speaks. */
+    protocol: number;
+    /** The build: the packed CLI's content hash, or `source`. */
+    version: string;
     serviceId: string;
+    pid: number;
     baseUrl: string;
-    /** Captured from the packed CLI at service launch. */
-    buildId?: string | undefined;
+    diagnostics: ServiceDiagnosticsStatus;
 }>;
-export type PrivateLocalServiceStopResult = Readonly<{
-    kind: "stopped";
+export type PrivateLocalServiceStopResult = 
+/** `killed`: it did not exit within five seconds of SIGTERM. */
+Readonly<{
+    kind: "stopped" | "killed";
 }> | Readonly<{
     kind: "not-running";
     recordCleaned: boolean;
@@ -23,14 +33,20 @@ export type PrivateLocalServiceStopResult = Readonly<{
 /** Selection addresses an existing Agent store; Session identity is not a new store. */
 export type PrivateLocalServiceSelection = Readonly<{
     invocationRoot: string;
+    /** TUI/form watches own their attachment; ACP retains it until connection close. */
+    uiAttachmentLifetime?: LocalUiAttachmentLifetime | undefined;
     clientPath?: string | undefined;
+    /** Person-selected sandbox requirement, not an approval setting. */
+    requireSandbox?: boolean | undefined;
     databasePath?: string | undefined;
     sessionId?: string | undefined;
     fungiMcp?: PrivateFungiMcpSelection | undefined;
 }>;
 export type PrivateLocalSessionCreation = Readonly<{
     invocationRoot: string;
+    uiAttachmentLifetime?: LocalUiAttachmentLifetime | undefined;
     clientPath?: string | undefined;
+    requireSandbox?: boolean | undefined;
     databasePath: string;
     requestId: string;
     fungiMcp?: PrivateFungiMcpSelection | undefined;
@@ -38,22 +54,54 @@ export type PrivateLocalSessionCreation = Readonly<{
 export type PrivateLocalServiceRequestOptions = Readonly<{
     signal?: AbortSignal | undefined;
 }>;
+/** Discovery lists the Agents in use; `archived` lists only the archived ones. */
+export type PrivateLocalDiscoveryOptions = PrivateLocalServiceRequestOptions & Readonly<{
+    archived?: boolean | undefined;
+}>;
+/** One human request to archive or restore an Agent of this folder. */
+export type PrivateLocalArchiveRequest = Readonly<{
+    invocationRoot: string;
+    agentId: string;
+    archived: boolean;
+}>;
 export type PrivateLocalSessionInspection = Readonly<{
+    diagnostics: ServiceDiagnosticsStatus;
     session: ShiitakeSession;
     snapshot: SessionSnapshot;
     close: () => Promise<void>;
 }>;
 export type PrivateLocalServiceConnection = Readonly<{
+    /** The service this connection currently talks to; a rebind replaces it. */
     service: PrivateLocalServiceStatus;
     agentId: string;
     databasePath: string;
     sessionId: string;
     client: ShiitakeAgent;
     session: ShiitakeSession;
+    /** Stop this Agent and its made-by descendants without retiring their chats. */
+    stopAll: () => Promise<StopAllResult>;
     effectiveModel: (options?: PrivateLocalServiceRequestOptions) => Promise<PrivateLocalEffectiveModel>;
-    /** Releases this client's watches only. Work and service ownership remain alive. */
+    sandboxStatus: (options?: PrivateLocalServiceRequestOptions) => Promise<LocalSandboxStatus>;
+    /**
+     * Point this connection at the service now named by service.json, which may
+     * have a new port and id after a restart, and select the same Session
+     * there. The Session handle stays valid; observations on the old service
+     * must be reopened. Never starts a service.
+     */
+    rebind: (options?: PrivateLocalServiceRequestOptions) => Promise<PrivateLocalServiceRebind>;
+    /**
+     * Close observations and release this client's UI attachment. Other work and
+     * service ownership stay alive; unanswered forms lose this UI's authority.
+     */
     close: () => Promise<void>;
 }>;
+/** `unavailable`: service.json names no service that answers. */
+export type PrivateLocalServiceRebind = Readonly<{
+    kind: "rebound";
+    service: PrivateLocalServiceStatus;
+}> | Readonly<{
+    kind: "unavailable";
+}>;
 export type PrivateLocalSessionChoice = Readonly<{
     databasePath: string;
     sessionId: string;
@@ -63,28 +111,60 @@ export type PrivateLocalSessionChoice = Readonly<{
     /** Reopen this saved store through the persistent service connection. */
     resume: (options?: PrivateLocalServiceRequestOptions & {
         fungiMcp?: PrivateFungiMcpSelection | undefined;
+        requireSandbox?: boolean | undefined;
     }) => Promise<PrivateLocalServiceConnection>;
 }>;
 export type PrivateLocalSessionProblem = Readonly<{
     kind: "corrupt" | "in_use" | "unreadable";
 }>;
+/** One saved Agent store in the folder, whether or not it has conversations yet. */
+export type PrivateLocalAgentChoice = Readonly<{
+    agentId: string;
+    /** Why this Agent's store cannot be read (it predates the current schema); set, the row shows it. */
+    unreadable?: string | undefined;
+    /** The Agent's chosen display name; absent while its store is unreadable. */
+    name?: string | undefined;
+    /** Creating Agent id; null for a human-created Agent, absent if unreadable. */
+    createdBy?: string | null | undefined;
+    databasePath: string;
+    sessionCount: number;
+    /** Latest Session activity; absent while the Agent has no readable Session. */
+    updatedAt?: number | undefined;
+}>;
 export type PrivateLocalSessionDiscovery = Readonly<{
-    agentCount: number;
+    agents: readonly PrivateLocalAgentChoice[];
     sessions: readonly PrivateLocalSessionChoice[];
     problems: readonly PrivateLocalSessionProblem[];
 }>;
 /** Local process management stays outside the shared Session HTTP contract. */
 export type PrivateLocalServiceManager = Readonly<{
+    reload: (invocationRoot: string) => Promise<string>;
+    /** Throws `LocalServiceUpdated` when a live service speaks another protocol. */
     status: () => Promise<PrivateLocalServiceStatus | undefined>;
+    /**
+     * Ensure a service of this build: reuse a match, otherwise stop the
+     * registered one and start this build's. Once this client has reached a
+     * service it keeps any service of its protocol and throws
+     * `LocalServiceUpdated` for another protocol. Every request starts here.
+     */
     start: (options?: PrivateLocalServiceRequestOptions) => Promise<PrivateLocalServiceStatus>;
     createSession: (creation: PrivateLocalSessionCreation, options?: PrivateLocalServiceRequestOptions) => Promise<PrivateLocalServiceConnection>;
     connect: (selection: PrivateLocalServiceSelection, options?: PrivateLocalServiceRequestOptions) => Promise<PrivateLocalServiceConnection>;
-    discover: (invocationRoot: string, options?: PrivateLocalServiceRequestOptions) => Promise<PrivateLocalSessionDiscovery>;
-    inspect: (selection: Omit<PrivateLocalServiceSelection, "clientPath">, options?: PrivateLocalServiceRequestOptions & Readonly<{
+    discover: (invocationRoot: string, options?: PrivateLocalDiscoveryOptions) => Promise<PrivateLocalSessionDiscovery>;
+    /**
+     * Archive or restore any Agent of the folder; refused with
+     * `AgentArchiveRefused` while it has a running command. Nothing is deleted.
+     */
+    archive: (request: PrivateLocalArchiveRequest, options?: PrivateLocalServiceRequestOptions) => Promise<void>;
+    inspect: (selection: Omit<PrivateLocalServiceSelection, "clientPath" | "uiAttachmentLifetime">, options?: PrivateLocalServiceRequestOptions & Readonly<{
         limit?: number | undefined;
     }>) => Promise<PrivateLocalSessionInspection>;
     auth: (request: PrivateLocalAuthRequest, interaction: AuthInteraction) => Promise<LocalAuthResult>;
     models: (options?: PrivateLocalServiceRequestOptions) => Promise<readonly PrivateLocalModelChoice[]>;
-    /** An expected identity avoids stopping a replacement started by another client. */
+    /**
+     * SIGTERM, then SIGKILL after five seconds; the record and owner lock are
+     * cleared either way. An expected identity avoids stopping a replacement
+     * started by another client.
+     */
     stop: (expectedServiceId?: string) => Promise<PrivateLocalServiceStopResult>;
 }>;