@fungi.computer/truffle 0.3.0 → 0.4.0

package/dist/private-local-delegation.js

@@ -114,15 +114,22 @@ export function createPrivateLocalDelegation(input) {
         if (mail.to.agentId !== input.agentId && mesh === undefined)
             throw new Error("Local addressed mail recipient is not authorized");
         const agents = mesh ?? (await members(new AbortController().signal));
+        const sender = mail.from;
         const delegation = mail.replyTo.length === 0 ? fleet.authenticateReply(mail) : undefined;
-        const frozenUndeliverable = delegation?.reply.outcome === "undeliverable" &&
-            delegation.reply.agentId === mail.from.agentId;
-        if (!agents.some(({ agentId }) => agentId === mail.from.agentId) &&
-            !frozenUndeliverable)
+        const authenticatedUndeliverable = delegation?.reply.outcome === "undeliverable";
+        const senderIsMember = sender.kind === "agent" &&
+            agents.some(({ agentId }) => agentId === sender.agentId);
+        if (!senderIsMember && !authenticatedUndeliverable) {
+            if (sender.kind === "system" &&
+                mail.replyTo.length === 0 &&
+                mail.reply?.outcome !== "accepted")
+                throw new Error("Local reply does not match work this Agent sent");
             throw new Error("Local mail sender is outside this project");
+        }
         if (mail.replyTo.length > 0) {
             const [destination] = mail.replyTo;
             if (mail.replyTo.length !== 1 ||
+                mail.from.kind !== "agent" ||
                 destination?.agentId !== mail.from.agentId ||
                 destination.sessionId !== mail.from.sessionId)
                 throw new Error("Local delegated work must reply to its sender");
@@ -137,7 +144,7 @@ export function createPrivateLocalDelegation(input) {
         if (delegation === undefined)
             throw new Error("Local reply does not match work this Agent sent");
         const replier = agents.find(({ agentId }) => agentId === delegation.reply.agentId);
-        if (replier === undefined && !frozenUndeliverable)
+        if (replier === undefined && !authenticatedUndeliverable)
             throw new Error("Local reply sender is outside this project");
         const meta = delegationReplyMeta(delegation, replier?.name ?? delegation.reply.agentId);
         return input.accept({ ...mail, meta }, meta, delegation.reply);

package/dist/private-local-exec-review.d.ts

@@ -7,4 +7,6 @@ export declare function localExecEscapeReview(request: {
     escape?: {
         justification: string;
     } | undefined;
-}, cwd: string): LocalApprovalReview;
+}, cwd: string, gitGrant?: {
+    configuredRemotes: ReadonlySet<string>;
+}): LocalApprovalReview;

package/dist/private-local-exec-review.js

@@ -1,4 +1,5 @@
-import { rulePrefix } from "./private-local-exec-rules.js";
+import { gitRuleCoverage, rulePrefix } from "./private-local-exec-rules.js";
+import { quote } from "shell-quote";
 const gitHookGrantSubcommands = new Set([
     "add",
     "branch",
@@ -17,34 +18,82 @@ const gitHookGrantSubcommands = new Set([
     "tag",
 ]);
 /** Build the host's review before the approval record is staged or displayed. */
-export function localExecEscapeReview(request, cwd) {
+export function localExecEscapeReview(request, cwd, gitGrant) {
     if (request.escape === undefined)
         throw new Error("An escape requires a justification");
-    const command = request.command ??
-        JSON.stringify([request.executable, ...(request.args ?? [])]);
-    const prefix = request.executable === undefined
+    const argv = request.executable === undefined
         ? undefined
-        : rulePrefix([request.executable, ...(request.args ?? [])]);
+        : [request.executable, ...(request.args ?? [])];
+    const command = request.command ?? quote(argv ?? []);
+    const prefix = argv === undefined || (argv[0] === "git" && gitGrant === undefined)
+        ? undefined
+        : rulePrefix(argv, gitGrant?.configuredRemotes);
     const review = {
         command,
         cwd,
         justification: request.escape.justification,
+        form: argv === undefined ? "shell" : "direct",
+        kind: argv?.[0] === "fungi" && argv[1] === "extension" && argv[2] === "add"
+            ? "extension-install"
+            : "exec",
     };
-    if (prefix !== undefined) {
+    if (argv !== undefined)
+        review.argv = argv;
+    if (prefix !== undefined && review.kind === "exec") {
         review.prefix = prefix;
+        review.alwaysAllowCoverage =
+            prefix[0] === "git"
+                ? gitRuleCoverage(prefix[1] ?? "")
+                : `Direct argv commands beginning ${JSON.stringify(prefix)} in this project; shell commands still ask.`;
         if (prefix[0] === "git") {
             const hookCapable = gitHookGrantSubcommands.has(prefix[1] ?? "");
-            review.warning =
-                (hookCapable
-                    ? "Project hooks can run code as you under this grant. Only the hooksPath setting must pre-exist; this Agent can create missing hook files there. A configured fsmonitor path in the worktree may also be Agent-writable."
-                    : "This command runs as you outside the sandbox.") +
-                    (prefix[1] === "push"
-                        ? " This grant can push all branches, force-update them, or delete remote branches."
-                        : "") +
-                    (["push", "fetch", "pull"].includes(prefix[1] ?? "")
-                        ? " Remote URLs can invoke ssh with your HOME and keys."
-                        : "");
+            const summary = (hookCapable
+                ? "Git hooks in this project can run code as you, and this Agent can add hooks."
+                : "This Git command will run outside the sandbox, as you.") +
+                (prefix[1] === "push"
+                    ? " It can push, force-push or delete any branch."
+                    : "") +
+                (["push", "fetch", "pull"].includes(prefix[1] ?? "")
+                    ? " Remotes can use your SSH keys."
+                    : "");
+            const detail = (hookCapable
+                ? "Git runs hook scripts from the folder the project's hooksPath setting names. That setting must already exist, but this Agent can add hook files there. A configured fsmonitor program in this folder may also be writable by this Agent."
+                : summary) +
+                (prefix[1] === "push"
+                    ? " A push grant can push all branches, force-update them or delete remote branches."
+                    : "") +
+                (["push", "fetch", "pull"].includes(prefix[1] ?? "")
+                    ? " Remote URLs can run ssh with your HOME and keys."
+                    : "");
+            review.risk = { summary, detail };
+        }
+        else {
+            const summary = `Every \`${prefix.join(" ")} …\` command will run outside the sandbox, as you.`;
+            review.risk = { summary, detail: summary };
         }
     }
+    if (request.executable === "git") {
+        const hookCapable = gitHookGrantSubcommands.has(request.args?.[0] ?? "");
+        review.warning =
+            (hookCapable
+                ? `Project hooks can run code as you ${review.prefix === undefined ? "when this command runs" : "under this grant"}. Only the hooksPath setting must pre-exist; this Agent can create missing hook files there. A configured fsmonitor path in the worktree may also be Agent-writable.`
+                : "This command runs as you outside the sandbox.") +
+                (request.args?.[0] === "push"
+                    ? " This grant can push all branches, force-update them, or delete remote branches."
+                    : "") +
+                (["push", "fetch", "pull"].includes(request.args?.[0] ?? "")
+                    ? " Remote URLs can invoke ssh with your HOME and keys."
+                    : "");
+    }
+    if (review.kind === "extension-install")
+        review.alwaysAllowUnavailableReason =
+            "Extension installs require a fresh approval; no reusable rule applies.";
+    else if (review.prefix === undefined)
+        review.alwaysAllowUnavailableReason =
+            request.executable === undefined
+                ? "Shell command text cannot match a saved argv rule; Approve once or Deny."
+                : request.executable === "git" && gitGrant === undefined
+                    ? "A protected project Git repository is unavailable; no reusable Git rule can match."
+                    : "This command or option cannot match a safe reusable rule; Approve once or Deny.";
     return review;
 }

package/dist/private-local-exec-rules.d.ts

@@ -1,9 +1,11 @@
-/** Offer only direct, narrow grants; extension installs require a fresh card. */
-export declare function rulePrefix(argv: readonly string[]): string[] | undefined;
+/** Offer only direct commands that this same matcher can authorize. */
+export declare function rulePrefix(argv: readonly string[], configuredRemotes?: ReadonlySet<string>): string[] | undefined;
+/** Text for the same Git option profile that gates matching, not a second list. */
+export declare function gitRuleCoverage(subcommand: string): string;
 /** One host-owned project file; every Agent in the project sees the same rules. */
 export declare function localExecRules(project: string): {
     list: () => string[][];
-    add: (prefix: readonly string[]) => void;
+    add: (prefix: readonly string[]) => import("@fungi.computer/cairn").CairnId<"local-exec-rules", "rule", 1>;
     remove: (prefix: readonly string[]) => void;
     match: (argv: readonly string[], configuredRemotes?: ReadonlySet<string>) => {
         ruleId: import("@fungi.computer/cairn").CairnId<"local-exec-rules", "rule", 1>;

package/dist/private-local-exec-rules.js

@@ -62,7 +62,7 @@ const gitOptions = {
             "-s",
             "--signoff",
         ],
-        values: ["-m", "--message"],
+        values: ["-m", "--message", "-am"],
     },
     diff: {
         flags: [
@@ -250,8 +250,8 @@ function validPrefix(prefix) {
                 prefix.length === 2 &&
                 gitBuiltins.has(prefix[1] ?? ""))));
 }
-/** Offer only direct, narrow grants; extension installs require a fresh card. */
-export function rulePrefix(argv) {
+/** Offer only direct commands that this same matcher can authorize. */
+export function rulePrefix(argv, configuredRemotes) {
     if (argv.length === 0 ||
         argv[0]?.startsWith(".") ||
         argv[0]?.includes("/") ||
@@ -260,7 +260,9 @@ export function rulePrefix(argv) {
         return undefined;
     if (basename(argv[0] ?? "") === "git") {
         const prefix = argv.slice(0, 2);
-        return validPrefix(prefix) ? prefix : undefined;
+        return validPrefix(prefix) && safeGitCommand(argv, configuredRemotes)
+            ? prefix
+            : undefined;
     }
     if (basename(argv[0] ?? "") === "fungi" &&
         argv[1] === "extension" &&
@@ -269,6 +271,21 @@ export function rulePrefix(argv) {
     const parsed = prefixSchema.safeParse(argv.slice(0, 2));
     return parsed.success && validPrefix(parsed.data) ? parsed.data : undefined;
 }
+/** Text for the same Git option profile that gates matching, not a second list. */
+export function gitRuleCoverage(subcommand) {
+    const profile = gitProfiles.get(subcommand);
+    if (profile === undefined)
+        throw new Error("No reusable Git option profile");
+    const flags = profile.flags.filter((flag) => flag !== "--").join(", ");
+    const values = profile.values.map((option) => `${option} VALUE`).join(", ");
+    const remote = subcommand === "push" ||
+        subcommand === "fetch" ||
+        subcommand === "pull" ||
+        subcommand === "remote"
+        ? " Remote operands must be configured names or permitted explicit URLs."
+        : "";
+    return `Direct argv git ${subcommand} for Workspace Agents in this protected project repository. Only these options are reusable: ${flags || "none"}${values ? `; ${values}` : ""}; -- and permitted operands.${remote} Shell commands and unlisted Git options still ask.`;
+}
 function safeRemote(remote, configuredRemotes) {
     if (remote === undefined)
         return true;
@@ -378,14 +395,18 @@ export function localExecRules(project) {
         const parsed = prefixSchema.parse(prefix);
         if (!validPrefix(parsed))
             throw new Error("Unsafe Always-allow prefix");
+        let ruleId;
         lockedUpdate(project, () => {
             const existing = readProject(project).rules;
-            if (!existing.some((rule) => JSON.stringify(rule.prefix) === JSON.stringify(parsed)))
-                writeProject(project, [
-                    ...existing,
-                    { id: projectRuleIds.rule.generate(), prefix: parsed },
-                ]);
+            ruleId = existing.find((rule) => JSON.stringify(rule.prefix) === JSON.stringify(parsed))?.id;
+            if (ruleId === undefined) {
+                ruleId = projectRuleIds.rule.generate();
+                writeProject(project, [...existing, { id: ruleId, prefix: parsed }]);
+            }
         });
+        if (ruleId === undefined)
+            throw new Error("Exec rule was not persisted");
+        return ruleId;
     };
     const remove = (prefix) => {
         const parsed = prefixSchema.parse(prefix);

package/dist/private-local-extension-archive-notice.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export declare const extensionArchiveNameSchema: z.ZodString;
+export declare function deferExtensionArchiveNotices(home: string): void;
+export declare function extensionArchiveNoticesAreDeferred(home: string): boolean;
+export declare function acquireExtensionOwnerLock(root: string): Promise<() => Promise<void>>;
+export declare function writeExtensionArchiveNotice(home: string, slug: "unversioned", filename: string, names: readonly string[]): Promise<void>;
+export declare function takePendingExtensionArchiveNoticesUnderOwnerLock(home: string): Promise<string[]>;
+export declare function takePendingExtensionArchiveNotices(home: string): Promise<string[]>;

package/dist/private-local-extension-archive-notice.js

@@ -0,0 +1,108 @@
+import { mkdir, readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import lockfile from "proper-lockfile";
+import writeFileAtomic from "write-file-atomic";
+import { z } from "zod";
+export const extensionArchiveNameSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(214)
+    .refine((name) => /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/iu.test(name));
+const noticeSchema = z.strictObject({
+    version: z.literal(3),
+    slug: z.literal("unversioned"),
+    filename: z.string().regex(/^installed(?:-[2-9])?\.json$/u),
+    names: z.array(extensionArchiveNameSchema).max(20),
+    additionalNameCount: z.number().int().min(0),
+    shown: z.boolean(),
+});
+const deferredHomes = new Set();
+function absent(cause) {
+    return (cause instanceof Error &&
+        "code" in cause &&
+        (cause.code === "ENOENT" || cause.code === "ENOTDIR"));
+}
+export function deferExtensionArchiveNotices(home) {
+    deferredHomes.add(resolve(home));
+}
+export function extensionArchiveNoticesAreDeferred(home) {
+    return deferredHomes.has(resolve(home));
+}
+export async function acquireExtensionOwnerLock(root) {
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    return lockfile.lock(root, {
+        realpath: false,
+        lockfilePath: join(root, ".owner.lock"),
+        stale: 30_000,
+        update: 10_000,
+        retries: { retries: 20, factor: 1.2, minTimeout: 25, maxTimeout: 100 },
+    });
+}
+function formatNotice(notice) {
+    const archivePath = `~/.fungi/archive/${notice.slug}/extensions/${notice.filename}`;
+    if (notice.names.length === 0)
+        return `Extensions from an earlier version were set aside, but no extension names could be read. Re-add each with: fungi extension add <its source>. Archived registry: ${archivePath}.`;
+    const more = notice.additionalNameCount > 0
+        ? `, and ${notice.additionalNameCount.toString()} more`
+        : "";
+    return `Extensions from an earlier version were set aside: ${notice.names.join(", ")}${more}. Re-add each with: fungi extension add <its source>. Archived registry: ${archivePath}.`;
+}
+export async function writeExtensionArchiveNotice(home, slug, filename, names) {
+    const notice = noticeSchema.parse({
+        version: 3,
+        slug,
+        filename,
+        names: names.slice(0, 20),
+        additionalNameCount: Math.max(0, names.length - 20),
+        shown: false,
+    });
+    const directory = join(resolve(home), ".fungi", "archive", slug, "extensions");
+    await writeFileAtomic(join(directory, `${filename}.notice.json`), `${JSON.stringify(notice)}\n`, { encoding: "utf8", fsync: true, mode: 0o600 });
+}
+export async function takePendingExtensionArchiveNoticesUnderOwnerLock(home) {
+    const directory = join(resolve(home), ".fungi", "archive", "unversioned", "extensions");
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (cause) {
+        if (absent(cause))
+            return [];
+        throw cause;
+    }
+    const notices = [];
+    for (const name of names
+        .filter((candidate) => /^installed(?:-[2-9])?\.json\.notice\.json$/u.test(candidate))
+        .sort()) {
+        const path = join(directory, name);
+        let value;
+        try {
+            value = JSON.parse(await readFile(path, "utf8"));
+        }
+        catch (cause) {
+            if (absent(cause) || cause instanceof SyntaxError)
+                continue;
+            throw cause;
+        }
+        const parsed = noticeSchema.safeParse(value);
+        if (!parsed.success || parsed.data.shown)
+            continue;
+        const archivedName = name.replace(/\.notice\.json$/u, "");
+        if (parsed.data.filename !== archivedName)
+            continue;
+        await writeFileAtomic(path, `${JSON.stringify({ ...parsed.data, shown: true })}\n`, { encoding: "utf8", fsync: true, mode: 0o600 });
+        notices.push(formatNotice(parsed.data));
+    }
+    return notices;
+}
+export async function takePendingExtensionArchiveNotices(home) {
+    const root = join(resolve(home), ".fungi", "extensions");
+    const release = await acquireExtensionOwnerLock(root);
+    try {
+        return await takePendingExtensionArchiveNoticesUnderOwnerLock(home);
+    }
+    finally {
+        await release();
+    }
+}

package/dist/private-local-extension-records.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/** One vocabulary for installed declarations and the activation reader. */
+export declare const capabilities: readonly ["state", "attention", "settled", "send", "timers", "commands", "projection", "run_tools", "files", "prompt", "compaction_handoff"];
+export declare const activationsSchema: z.ZodObject<{
+    projects: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>;
+    agents: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+        revision: z.ZodString;
+        capabilities: z.ZodArray<z.ZodEnum<{
+            state: "state";
+            attention: "attention";
+            settled: "settled";
+            send: "send";
+            timers: "timers";
+            commands: "commands";
+            projection: "projection";
+            run_tools: "run_tools";
+            files: "files";
+            prompt: "prompt";
+            compaction_handoff: "compaction_handoff";
+        }>>;
+        skills: z.ZodBoolean;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** Only refused activations belong to the home upgrader, not installed.json. */
+export declare function incompatibleLocalExtensionActivations(home: string): Promise<readonly string[]>;

package/dist/private-local-extension-records.js

@@ -0,0 +1,51 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+/** One vocabulary for installed declarations and the activation reader. */
+export const capabilities = [
+    "state",
+    "attention",
+    "settled",
+    "send",
+    "timers",
+    "commands",
+    "projection",
+    "run_tools",
+    "files",
+    "prompt",
+    "compaction_handoff",
+];
+export const activationsSchema = z.strictObject({
+    projects: z.record(z.string(), z.record(z.string(), z.string())),
+    agents: z.record(z.string(), z.record(z.string(), z.strictObject({
+        revision: z.string(),
+        capabilities: z.array(z.enum(capabilities)),
+        /** The opt-in to the revision's skills folder; separate from tools. */
+        skills: z.boolean(),
+    }))),
+});
+/** Only refused activations belong to the home upgrader, not installed.json. */
+export async function incompatibleLocalExtensionActivations(home) {
+    const path = join(resolve(home), ".fungi", "extensions", "activations.json");
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (cause) {
+        if (cause instanceof Error &&
+            "code" in cause &&
+            (cause.code === "ENOENT" || cause.code === "ENOTDIR"))
+            return [];
+        throw cause;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (cause) {
+        if (cause instanceof SyntaxError)
+            return [path];
+        throw cause;
+    }
+    return activationsSchema.safeParse(value).success ? [] : [path];
+}

package/dist/private-local-process-identity.d.ts

@@ -1,3 +1,11 @@
+export type ServiceProcessIdentity = Readonly<{
+    kind: "ours";
+    evidence: "start-time" | "command-line";
+}> | Readonly<{
+    kind: "other";
+}> | Readonly<{
+    kind: "gone";
+}>;
 /**
  * A process-start discriminator. `unverifiable` means no sufficiently precise
  * reader is implemented on this platform.
@@ -16,5 +24,11 @@ export type ProcessStart = Readonly<{
  * accepted as signal authority. No sub-second macOS reader is implemented.
  */
 export declare function readProcessStart(pid: number): Promise<ProcessStart>;
+/** Never signal a PID merely because a lease names it. */
+export declare function identifyLocalServiceProcess(claim: Readonly<{
+    pid: number;
+    startedAt: string;
+    directory: string;
+}>): Promise<ServiceProcessIdentity>;
 /** The owner's start discriminator; an unverifiable marker never permits signalling. */
 export declare function readOwnProcessStart(): Promise<string>;

package/dist/private-local-process-identity.js

@@ -1,6 +1,25 @@
+import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
 import { z } from "zod";
 const procStartSchema = z.string().regex(/^\d+$/u);
+const execFileAsync = promisify(execFile);
+/** Signal 0 checks existence, not identity; EPERM is still a live process. */
+function processIsGone(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause) {
+            if (cause.code === "ESRCH")
+                return true;
+            if (cause.code === "EPERM")
+                return false;
+        }
+        throw cause;
+    }
+}
 /**
  * Linux reads proc(5)'s `starttime` (field 22 of `/proc/<pid>/stat`, in clock
  * ticks since boot). macOS's ps lstart is only second-resolution and is not
@@ -29,6 +48,38 @@ export async function readProcessStart(pid) {
     }
     return { kind: "unverifiable" };
 }
+/** Never signal a PID merely because a lease names it. */
+export async function identifyLocalServiceProcess(claim) {
+    const start = await readProcessStart(claim.pid);
+    if (start.kind === "gone")
+        return { kind: "gone" };
+    if (start.kind === "running")
+        return start.start === claim.startedAt
+            ? { kind: "ours", evidence: "start-time" }
+            : { kind: "other" };
+    if (process.platform !== "darwin")
+        return { kind: "other" };
+    if (processIsGone(claim.pid))
+        return { kind: "gone" };
+    // ps is only a corroborating channel after the caller has checked the
+    // matching service.json and owner.sqlite lease. Its output is bounded; an
+    // unreadable or different argv never grants signal authority.
+    let argv;
+    try {
+        ({ stdout: argv } = await execFileAsync("ps", ["-p", String(claim.pid), "-o", "args="], { timeout: 2_000, maxBuffer: 4_096 }));
+    }
+    catch {
+        return processIsGone(claim.pid) ? { kind: "gone" } : { kind: "other" };
+    }
+    const marker = `--internal-service ${claim.directory}`;
+    const offset = argv.indexOf(marker);
+    return offset >= 0 &&
+        (offset === 0 || /\s/u.test(argv[offset - 1] ?? "")) &&
+        (offset + marker.length === argv.trimEnd().length ||
+            /\s/u.test(argv[offset + marker.length] ?? ""))
+        ? { kind: "ours", evidence: "command-line" }
+        : { kind: "other" };
+}
 /** The owner's start discriminator; an unverifiable marker never permits signalling. */
 export async function readOwnProcessStart() {
     const own = await readProcessStart(process.pid);

package/dist/private-local-runtime-host.d.ts

@@ -48,6 +48,13 @@ export type PrivateLocalTools = Readonly<{
     /** Background Computer processes, scoped per Session; the host closes them. */
     processes: PrivateLocalComputerProcesses;
 }>;
+export type ExecApprovalDecision = {
+    agentId: string;
+    recordId: string;
+    decision: "approve" | "deny";
+    scope?: "once" | "always";
+    ruleId?: string;
+};
 /** Inputs for the one private local Agent opener. */
 export type PrivateLocalRuntimeHostOptions = Readonly<{
     /** Service-selected host configuration, independent of this Agent's Files root. */
@@ -63,6 +70,8 @@ export type PrivateLocalRuntimeHostOptions = Readonly<{
         executable: string;
         ruleId: string;
     }>) => void;
+    /** The human's committed approval choice, without command text or secrets. */
+    onExecApprovalDecision?: (event: Readonly<ExecApprovalDecision>) => void;
     /** Existing Agent database to reopen instead of creating a fresh local store. */
     databasePath?: string | undefined;
     /** Stable Local store identity for replaying one Agent create request. */
@@ -71,6 +80,8 @@ export type PrivateLocalRuntimeHostOptions = Readonly<{
     name?: string | undefined;
     /** The Agent that created this one; recorded once with its identity. Absent when a human made it. */
     createdBy?: string | undefined;
+    /** The Session whose create request is durably bound to this Local receipt. */
+    createdBySessionId?: string | undefined;
     /** Immutable project-relative folder authority, inherited by child Agents. */
     folder?: string | undefined;
     /** Persist before constructing the Agent, which can recover durable work. */
@@ -163,8 +174,12 @@ export type PrivateLocalCreateStore = Readonly<{
     agentId: LocalStoreId;
     databasePath: string;
 }>;
+export type PrivateLocalCreateCreator = Readonly<{
+    agentId: string;
+    sessionId: string;
+}>;
 /** Resolve an Agent create request through its durable Local receipt. */
-export declare function resolvePrivateLocalCreateStore(root: string, requestId: string): Promise<PrivateLocalCreateStore>;
+export declare function resolvePrivateLocalCreateStore(root: string, requestId: string, creator?: PrivateLocalCreateCreator): Promise<PrivateLocalCreateStore>;
 /** Build the fixed source read by Shiitake once for each local run. */
 export declare function createPrivateLocalInstructionSource(port: Awaited<ReturnType<typeof createPrivateInvocationFilesPort>>): InstructionSource;
 export declare function createPrivateLocalModelSource(models: Models, providerId: string | undefined, modelId: string | undefined, providerCacheKey: string, selectedOwnerReasoning?: ThinkingLevel, defaults?: Readonly<{