@webpresso/agent-kit 3.3.3 → 3.3.5

package/dist/esm/daemon/domains/blueprint-exec-ledger.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Blueprint exec run ledger: durable job ↔ PTY session ↔ blueprint attribution.
+ *
+ * Why this exists separately from the launch ledger: a launch handle is
+ * single-use and is consumed the moment Rust claims it, and the PTY reaper
+ * reports that *a* session ended but not which blueprint it belonged to.
+ * Neither can answer "what is this terminal running?" after a UI restart. A
+ * job id that outlives both can.
+ *
+ * Rows are deliberately env-free and argv-free: this ledger is readable by the
+ * webview, so it must never carry launch material.
+ */
+export declare const BLUEPRINT_EXEC_JOB_STATES: readonly ["preparing", "running", "terminal"];
+export type BlueprintExecJobState = (typeof BLUEPRINT_EXEC_JOB_STATES)[number];
+export type BlueprintExecJob = {
+    readonly jobId: string;
+    readonly slug: string;
+    readonly taskId: string | null;
+    /** Opaque single-use launch handle; never the composed argv or env. */
+    readonly launchHandle: string;
+    readonly sessionId: number | null;
+    readonly startedAt: number;
+    readonly state: BlueprintExecJobState;
+};
+export type RegisterBlueprintExecJobInput = {
+    readonly slug: string;
+    readonly taskId: string | null;
+    readonly launchHandle: string;
+};
+/**
+ * Bounded, insertion-ordered job store.
+ *
+ * Complexity: `register`, `bindSession`, `markTerminal`, and `get` are all
+ * Map-keyed O(1). Eviction is O(1) too — terminal job ids are appended to a
+ * FIFO queue as they terminate, so making room pops the front instead of
+ * rescanning the map. `list` is O(#jobs) over a capped map.
+ */
+/**
+ * Construction options. Shared by the class and {@link createBlueprintExecLedger}
+ * so the factory's public surface cannot drift away from what the constructor
+ * actually accepts.
+ */
+export type BlueprintExecLedgerOptions = {
+    readonly maxJobs?: number;
+    readonly staleUnboundMs?: number;
+    /** Injectable clock (tests). */
+    readonly now?: () => number;
+};
+export declare class BlueprintExecLedger {
+    private readonly byJobId;
+    /** FIFO of job ids that reached `terminal`, oldest first. */
+    private readonly terminalOrder;
+    private readonly maxJobs;
+    private readonly staleUnboundMs;
+    private readonly now;
+    constructor(options?: BlueprintExecLedgerOptions);
+    /** Evict the oldest terminal job. O(1) amortized via the FIFO queue. */
+    private evictOneTerminal;
+    /**
+     * Last-resort reclaim: the oldest job that never bound a session and whose
+     * launch handle can no longer be claimed.
+     *
+     * Without this, a daemon that only ever prepared launches which were never
+     * claimed (a crashing Rust peer) would wedge at the cap forever, because
+     * nothing would ever transition those jobs to terminal.
+     *
+     * O(#jobs) and only on the eviction path when the terminal queue is empty.
+     */
+    private evictOneStaleUnbound;
+    register(input: RegisterBlueprintExecJobInput): {
+        readonly jobId: string;
+    };
+    /**
+     * Bind the spawned PTY session to a job. Rust-only caller.
+     *
+     * Single-assignment: a second bind for the same job is rejected so a
+     * compromised or buggy peer cannot re-point an existing job at another
+     * session.
+     */
+    bindSession(jobId: string, sessionId: number): BlueprintExecJob;
+    markTerminal(jobId: string): BlueprintExecJob | null;
+    get(jobId: string): BlueprintExecJob | undefined;
+    list(): readonly BlueprintExecJob[];
+    size(): number;
+}
+export declare function createBlueprintExecLedger(options?: BlueprintExecLedgerOptions): BlueprintExecLedger;

package/dist/esm/daemon/domains/blueprint-exec-ledger.js

@@ -0,0 +1,134 @@
+/**
+ * Blueprint exec run ledger: durable job ↔ PTY session ↔ blueprint attribution.
+ *
+ * Why this exists separately from the launch ledger: a launch handle is
+ * single-use and is consumed the moment Rust claims it, and the PTY reaper
+ * reports that *a* session ended but not which blueprint it belonged to.
+ * Neither can answer "what is this terminal running?" after a UI restart. A
+ * job id that outlives both can.
+ *
+ * Rows are deliberately env-free and argv-free: this ledger is readable by the
+ * webview, so it must never carry launch material.
+ */
+import { randomBytes } from "node:crypto";
+export const BLUEPRINT_EXEC_JOB_STATES = ["preparing", "running", "terminal"];
+const DEFAULT_MAX_JOBS = 256;
+/**
+ * A job that was prepared but never bound to a session within this window is
+ * dead: its launch handle has long since expired (the launch ledger TTL is a
+ * minute), so no Rust peer can still claim it.
+ */
+const DEFAULT_STALE_UNBOUND_MS = 5 * 60_000;
+export class BlueprintExecLedger {
+    byJobId = new Map();
+    /** FIFO of job ids that reached `terminal`, oldest first. */
+    terminalOrder = [];
+    maxJobs;
+    staleUnboundMs;
+    now;
+    constructor(options) {
+        this.maxJobs = options?.maxJobs ?? DEFAULT_MAX_JOBS;
+        this.staleUnboundMs = options?.staleUnboundMs ?? DEFAULT_STALE_UNBOUND_MS;
+        this.now = options?.now ?? Date.now;
+    }
+    /** Evict the oldest terminal job. O(1) amortized via the FIFO queue. */
+    evictOneTerminal() {
+        while (this.terminalOrder.length > 0) {
+            const candidate = this.terminalOrder.shift();
+            if (candidate === undefined)
+                break;
+            const job = this.byJobId.get(candidate);
+            // Skip stale queue entries whose job was already removed.
+            if (job === undefined)
+                continue;
+            if (job.state !== "terminal")
+                continue;
+            this.byJobId.delete(candidate);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Last-resort reclaim: the oldest job that never bound a session and whose
+     * launch handle can no longer be claimed.
+     *
+     * Without this, a daemon that only ever prepared launches which were never
+     * claimed (a crashing Rust peer) would wedge at the cap forever, because
+     * nothing would ever transition those jobs to terminal.
+     *
+     * O(#jobs) and only on the eviction path when the terminal queue is empty.
+     */
+    evictOneStaleUnbound() {
+        const cutoff = this.now() - this.staleUnboundMs;
+        for (const [jobId, job] of this.byJobId) {
+            if (job.sessionId === null && job.state === "preparing" && job.startedAt < cutoff) {
+                this.byJobId.delete(jobId);
+                return true;
+            }
+        }
+        return false;
+    }
+    register(input) {
+        if (this.byJobId.size >= this.maxJobs &&
+            !this.evictOneTerminal() &&
+            !this.evictOneStaleUnbound()) {
+            throw new Error(`blueprint exec ledger full (max ${this.maxJobs} tracked jobs)`);
+        }
+        const jobId = `bpexec-${Date.now().toString(36)}-${randomBytes(6).toString("hex")}`;
+        this.byJobId.set(jobId, {
+            jobId,
+            slug: input.slug,
+            taskId: input.taskId,
+            launchHandle: input.launchHandle,
+            sessionId: null,
+            startedAt: this.now(),
+            state: "preparing",
+        });
+        return { jobId };
+    }
+    /**
+     * Bind the spawned PTY session to a job. Rust-only caller.
+     *
+     * Single-assignment: a second bind for the same job is rejected so a
+     * compromised or buggy peer cannot re-point an existing job at another
+     * session.
+     */
+    bindSession(jobId, sessionId) {
+        const job = this.byJobId.get(jobId);
+        if (job === undefined) {
+            throw new Error("unknown blueprint exec job id");
+        }
+        if (job.sessionId !== null) {
+            throw new Error("blueprint exec job already bound to a session");
+        }
+        if (!Number.isSafeInteger(sessionId) || sessionId < 0) {
+            throw new Error("blueprint exec session id must be a non-negative integer");
+        }
+        const bound = { ...job, sessionId, state: "running" };
+        this.byJobId.set(jobId, bound);
+        return bound;
+    }
+    markTerminal(jobId) {
+        const job = this.byJobId.get(jobId);
+        if (job === undefined)
+            return null;
+        if (job.state === "terminal")
+            return job;
+        const done = { ...job, state: "terminal" };
+        this.byJobId.set(jobId, done);
+        this.terminalOrder.push(jobId);
+        return done;
+    }
+    get(jobId) {
+        return this.byJobId.get(jobId);
+    }
+    list() {
+        return [...this.byJobId.values()];
+    }
+    size() {
+        return this.byJobId.size;
+    }
+}
+export function createBlueprintExecLedger(options) {
+    return new BlueprintExecLedger(options);
+}

package/dist/esm/daemon/domains/blueprint-exec.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Blueprint exec launch-spec composition (desktop "exec a blueprint" seam).
+ *
+ * Two invariants this module exists to protect:
+ *
+ * 1. **Exec params are data, not command.** The webview may supply only a
+ *    blueprint slug and an optional task id. Both are validated against
+ *    anchored, bounded patterns, and the resolved blueprint folder is
+ *    path-confined against the daemon's allowlisted roots. The executor
+ *    program, argv, cwd, and env are composed *here*, daemon-side. No
+ *    caller-supplied program, flag, path, or env value ever reaches a spawn
+ *    line, and argv is always an ARRAY — never a shell string.
+ * 2. **Spawning is Rust-only.** Nothing in this module spawns a process; it
+ *    returns a spec that Rust claims and spawns through the PTY manager. No
+ *    process-spawning API is imported here, and a test enforces that.
+ *
+ * Execution status is read from blueprint frontmatter metadata written by the
+ * executor itself (`#execution/metadata.js`), never inferred from PTY output.
+ */
+import { type PathConfineFs } from "#daemon/path-confinement.js";
+import { type BlueprintExecutionMetadata } from "#execution/metadata.js";
+/**
+ * Lifecycle directories searched for a slug, most-active first.
+ *
+ * Fixed-size list: slug resolution is O(1) directory probes, never a walk.
+ */
+export declare const BLUEPRINT_LIFECYCLE_DIRS: readonly ["in-progress", "planned", "draft", "completed", "parked", "archived"];
+/** Upper bound on an accepted slug, mirrored by {@link BLUEPRINT_SLUG_PATTERN}. */
+export declare const MAX_BLUEPRINT_SLUG_LENGTH = 64;
+/**
+ * Anchored, linear-time (no nested quantifier) slug pattern. Rejects `..`,
+ * `/`, `\`, leading `-`, uppercase, whitespace, NUL, and every shell
+ * metacharacter by construction rather than by blocklist.
+ */
+export declare const BLUEPRINT_SLUG_PATTERN: RegExp;
+/** Dotted blueprint task id, e.g. `1.2` or `10.3.1`. */
+export declare const BLUEPRINT_TASK_ID_PATTERN: RegExp;
+/** Rejected caller input. Carries no attacker-controlled text. */
+export declare class BlueprintExecValidationError extends Error {
+    constructor(message: string);
+}
+export type BlueprintExecSpec = {
+    /** Executor program path, resolved daemon-side. */
+    readonly command: string;
+    /** Full argv array (excluding `command`). Never a shell string. */
+    readonly args: readonly string[];
+    readonly cwd: string;
+    /** Allowlist-filtered env, safe to hand to Rust. */
+    readonly env: Readonly<Record<string, string>>;
+    readonly slug: string;
+    readonly taskId: string | null;
+    /** Confined absolute path of the blueprint folder. */
+    readonly blueprintDir: string;
+    readonly lifecycleStatus: string;
+};
+export type ComposeBlueprintExecSpecInput = {
+    readonly slug: string;
+    readonly taskId?: string | null;
+    readonly repoRoot: string;
+    readonly allowlistedRoots: readonly string[];
+    /** Base env; defaults to `process.env`. Always allowlist-filtered. */
+    readonly env?: NodeJS.ProcessEnv;
+    readonly fs?: PathConfineFs;
+    /** Injectable existence probe (tests); defaults to `existsSync`. */
+    readonly exists?: (path: string) => boolean;
+    /**
+     * Injectable executor invocation prefix (tests). Production resolves the
+     * stable `wp` launcher via {@link buildSelfInvocationCommand}.
+     */
+    readonly selfCommand?: readonly string[];
+    /**
+     * Injectable probe for the resolved executor binary. Defaults to
+     * `existsSync`; tests that inject a synthetic `selfCommand` stub this.
+     */
+    readonly commandExists?: (path: string) => boolean;
+};
+/**
+ * Validate a caller-supplied blueprint slug.
+ *
+ * O(len) with an anchored, backtracking-free pattern on a length-capped input.
+ * The rejected value is never echoed back into the error.
+ */
+export declare function assertValidBlueprintSlug(slug: unknown): string;
+/** Validate an optional dotted task id. O(len) on a bounded input. */
+export declare function assertValidBlueprintTaskId(taskId: unknown): string | null;
+/**
+ * Compose the executor launch spec for a validated slug.
+ *
+ * Hot-path complexity: O(len(slug)) validation + O(1) lifecycle probes +
+ * O(|allowlist|) env filtering, where the env allowlist is a fixed constant
+ * set. No input-proportional nesting anywhere.
+ */
+export declare function composeBlueprintExecSpec(input: ComposeBlueprintExecSpecInput): BlueprintExecSpec;
+/**
+ * Read executor-written progress for a blueprint.
+ *
+ * Source of truth is the blueprint's own frontmatter execution metadata, which
+ * the executor maintains. PTY bytes are never read here — the terminal stream
+ * is human-viewing only and is not a status input.
+ *
+ * Returns `null` when the blueprint has no execution metadata yet.
+ */
+export declare function readBlueprintExecProgress(repoRoot: string, slug: string, options?: {
+    readonly exists?: (path: string) => boolean;
+    readonly readFile?: (path: string) => string;
+}): BlueprintExecutionMetadata | null;

package/dist/esm/daemon/domains/blueprint-exec.js

@@ -0,0 +1,161 @@
+/**
+ * Blueprint exec launch-spec composition (desktop "exec a blueprint" seam).
+ *
+ * Two invariants this module exists to protect:
+ *
+ * 1. **Exec params are data, not command.** The webview may supply only a
+ *    blueprint slug and an optional task id. Both are validated against
+ *    anchored, bounded patterns, and the resolved blueprint folder is
+ *    path-confined against the daemon's allowlisted roots. The executor
+ *    program, argv, cwd, and env are composed *here*, daemon-side. No
+ *    caller-supplied program, flag, path, or env value ever reaches a spawn
+ *    line, and argv is always an ARRAY — never a shell string.
+ * 2. **Spawning is Rust-only.** Nothing in this module spawns a process; it
+ *    returns a spec that Rust claims and spawns through the PTY manager. No
+ *    process-spawning API is imported here, and a test enforces that.
+ *
+ * Execution status is read from blueprint frontmatter metadata written by the
+ * executor itself (`#execution/metadata.js`), never inferred from PTY output.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildSelfInvocationCommand } from "#cli/auto-update/self-invocation.js";
+import { filterAllowlistedEnv } from "#daemon/launch/env-allowlist.js";
+import { confinePaths } from "#daemon/path-confinement.js";
+import { readBlueprintExecutionMetadata, } from "#execution/metadata.js";
+/**
+ * Lifecycle directories searched for a slug, most-active first.
+ *
+ * Fixed-size list: slug resolution is O(1) directory probes, never a walk.
+ */
+export const BLUEPRINT_LIFECYCLE_DIRS = [
+    "in-progress",
+    "planned",
+    "draft",
+    "completed",
+    "parked",
+    "archived",
+];
+/** Upper bound on an accepted slug, mirrored by {@link BLUEPRINT_SLUG_PATTERN}. */
+export const MAX_BLUEPRINT_SLUG_LENGTH = 64;
+/**
+ * Anchored, linear-time (no nested quantifier) slug pattern. Rejects `..`,
+ * `/`, `\`, leading `-`, uppercase, whitespace, NUL, and every shell
+ * metacharacter by construction rather than by blocklist.
+ */
+export const BLUEPRINT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/u;
+/** Dotted blueprint task id, e.g. `1.2` or `10.3.1`. */
+export const BLUEPRINT_TASK_ID_PATTERN = /^[0-9]+(?:\.[0-9]+)+$/u;
+/** Rejected caller input. Carries no attacker-controlled text. */
+export class BlueprintExecValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BlueprintExecValidationError";
+    }
+}
+/**
+ * Validate a caller-supplied blueprint slug.
+ *
+ * O(len) with an anchored, backtracking-free pattern on a length-capped input.
+ * The rejected value is never echoed back into the error.
+ */
+export function assertValidBlueprintSlug(slug) {
+    if (typeof slug !== "string" || slug.length > MAX_BLUEPRINT_SLUG_LENGTH) {
+        throw new BlueprintExecValidationError("blueprint slug must be a bounded string");
+    }
+    if (!BLUEPRINT_SLUG_PATTERN.test(slug)) {
+        throw new BlueprintExecValidationError("blueprint slug must match ^[a-z0-9][a-z0-9-]{0,63}$");
+    }
+    return slug;
+}
+/** Validate an optional dotted task id. O(len) on a bounded input. */
+export function assertValidBlueprintTaskId(taskId) {
+    if (taskId === undefined || taskId === null || taskId === "")
+        return null;
+    if (typeof taskId !== "string" || taskId.length > 32) {
+        throw new BlueprintExecValidationError("blueprint task id must be a bounded string");
+    }
+    if (!BLUEPRINT_TASK_ID_PATTERN.test(taskId)) {
+        throw new BlueprintExecValidationError("blueprint task id must match ^[0-9]+(\\.[0-9]+)+$");
+    }
+    return taskId;
+}
+function locateBlueprintDir(repoRoot, slug, exists) {
+    for (const lifecycleStatus of BLUEPRINT_LIFECYCLE_DIRS) {
+        const dir = join(repoRoot, "blueprints", lifecycleStatus, slug);
+        if (exists(dir))
+            return { dir, lifecycleStatus };
+    }
+    throw new BlueprintExecValidationError("no blueprint folder found for the requested slug");
+}
+/**
+ * Compose the executor launch spec for a validated slug.
+ *
+ * Hot-path complexity: O(len(slug)) validation + O(1) lifecycle probes +
+ * O(|allowlist|) env filtering, where the env allowlist is a fixed constant
+ * set. No input-proportional nesting anywhere.
+ */
+export function composeBlueprintExecSpec(input) {
+    const slug = assertValidBlueprintSlug(input.slug);
+    const taskId = assertValidBlueprintTaskId(input.taskId);
+    const exists = input.exists ?? existsSync;
+    const located = locateBlueprintDir(input.repoRoot, slug, exists);
+    const confined = confinePaths({ repoRoot: input.repoRoot, blueprintDir: located.dir }, input.allowlistedRoots, input.fs);
+    if (!confined.ok) {
+        throw new BlueprintExecValidationError(`blueprint exec path rejected: ${confined.reason}`);
+    }
+    const cwd = confined.resolvedPaths.repoRoot ?? input.repoRoot;
+    const blueprintDir = confined.resolvedPaths.blueprintDir ?? located.dir;
+    // Daemon-authored argv. The only caller-derived element is the validated
+    // slug, and it can never begin with `-` so it cannot become a flag.
+    const execArgs = ["blueprint", "exec", slug];
+    const invocation = input.selfCommand === undefined
+        ? buildSelfInvocationCommand([...execArgs])
+        : [...input.selfCommand, ...execArgs];
+    const [command, ...args] = invocation;
+    if (command === undefined || command.length === 0) {
+        throw new BlueprintExecValidationError("could not resolve the wp executor binary");
+    }
+    // Fail fast with a readable reason instead of preparing a launch whose PTY
+    // would die immediately with an opaque spawn error.
+    const commandExists = input.commandExists ?? existsSync;
+    if (command.includes("/") && !commandExists(command)) {
+        throw new BlueprintExecValidationError("the resolved wp executor binary does not exist on this system");
+    }
+    return {
+        command,
+        args,
+        cwd,
+        env: filterAllowlistedEnv(input.env ?? process.env),
+        slug,
+        taskId,
+        blueprintDir,
+        lifecycleStatus: located.lifecycleStatus,
+    };
+}
+/**
+ * Read executor-written progress for a blueprint.
+ *
+ * Source of truth is the blueprint's own frontmatter execution metadata, which
+ * the executor maintains. PTY bytes are never read here — the terminal stream
+ * is human-viewing only and is not a status input.
+ *
+ * Returns `null` when the blueprint has no execution metadata yet.
+ */
+export function readBlueprintExecProgress(repoRoot, slug, options) {
+    const validSlug = assertValidBlueprintSlug(slug);
+    const exists = options?.exists ?? existsSync;
+    const readFile = options?.readFile ?? ((path) => readFileSync(path, "utf8"));
+    for (const lifecycleStatus of BLUEPRINT_LIFECYCLE_DIRS) {
+        const overview = join(repoRoot, "blueprints", lifecycleStatus, validSlug, "_overview.md");
+        if (!exists(overview))
+            continue;
+        try {
+            return readBlueprintExecutionMetadata(readFile(overview));
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}

package/dist/esm/daemon/domains/launch.d.ts

@@ -21,6 +21,17 @@ export type PrepareLaunchInput = {
     /** When null/omitted, assembly uses profile none (no secret-provider fetch). */
     readonly secretsConfig?: import("#runtime/secrets-config.js").SecretsConfig | null;
 };
+/**
+ * A launch spec the daemon composed itself (not via provider assembly).
+ * `args` is always an array — the ledger never accepts a shell string.
+ */
+export type PrepareComposedLaunchInput = {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly resolvedSecretKeys?: readonly string[];
+};
 export declare class LaunchLedger {
     private readonly byHandle;
     private readonly ttlMs;
@@ -33,6 +44,20 @@ export declare class LaunchLedger {
     prepare(input: PrepareLaunchInput): {
         readonly handle: string;
     };
+    /**
+     * Register an already-composed spec (e.g. a blueprint exec launch) under the
+     * same opaque-handle / single-use-claim contract as {@link prepare}.
+     *
+     * Used when the command is not an agent provider and so cannot go through
+     * provider env assembly. The env is re-filtered through the mandatory
+     * allowlist here as well, so this entry point can never widen delivery
+     * beyond what `prepare` would allow even if a caller passes a raw map.
+     *
+     * O(1) apart from the shared TTL purge.
+     */
+    prepareComposed(input: PrepareComposedLaunchInput): {
+        readonly handle: string;
+    };
     /**
      * Single-use claim for the Rust peer. Removes the entry so env is not retained.
      * Returns null if unknown, expired, or already claimed.

package/dist/esm/daemon/domains/launch.js

@@ -3,7 +3,7 @@
  * Returns opaque handles to UI; raw env is only claimable by the rust peer.
  */
 import { randomBytes } from "node:crypto";
-import { assembleAllowlistedLaunchEnv, } from "#daemon/launch/env-allowlist.js";
+import { assembleAllowlistedLaunchEnv, filterAllowlistedEnv, } from "#daemon/launch/env-allowlist.js";
 const DEFAULT_TTL_MS = 60_000;
 const DEFAULT_MAX_UNCLAIMED = 64;
 export class LaunchLedger {
@@ -45,6 +45,35 @@ export class LaunchLedger {
         });
         return { handle };
     }
+    /**
+     * Register an already-composed spec (e.g. a blueprint exec launch) under the
+     * same opaque-handle / single-use-claim contract as {@link prepare}.
+     *
+     * Used when the command is not an agent provider and so cannot go through
+     * provider env assembly. The env is re-filtered through the mandatory
+     * allowlist here as well, so this entry point can never widen delivery
+     * beyond what `prepare` would allow even if a caller passes a raw map.
+     *
+     * O(1) apart from the shared TTL purge.
+     */
+    prepareComposed(input) {
+        this.purgeExpired();
+        if (this.byHandle.size >= this.maxUnclaimed) {
+            throw new Error(`launch ledger full (max ${this.maxUnclaimed} unclaimed handles)`);
+        }
+        const handle = `launch-${Date.now().toString(36)}-${randomBytes(6).toString("hex")}`;
+        this.byHandle.set(handle, {
+            handle,
+            preparedAt: Date.now(),
+            command: input.command,
+            args: [...input.args],
+            cwd: input.cwd,
+            env: filterAllowlistedEnv(input.env, {
+                resolvedSecretKeys: input.resolvedSecretKeys,
+            }),
+        });
+        return { handle };
+    }
     /**
      * Single-use claim for the Rust peer. Removes the entry so env is not retained.
      * Returns null if unknown, expired, or already claimed.

package/dist/esm/daemon/handlers/blueprints-handlers.d.ts

@@ -1,5 +1,16 @@
+import type { BlueprintExecLedger } from "#daemon/domains/blueprint-exec-ledger.js";
+import type { LaunchLedger } from "#daemon/domains/launch.js";
 import type { MethodHandler } from "#daemon/rpc.js";
+export type BlueprintsHandlerDeps = {
+    readonly launchLedger?: LaunchLedger;
+    readonly execLedger?: BlueprintExecLedger;
+    readonly allowlistedRoots?: readonly string[];
+};
 /**
  * Build blueprint-domain handlers scoped to `repoRoot`.
+ *
+ * The ledgers are created once per daemon (not per connection) and passed in,
+ * because the webview peer registers the job while the rust peer binds the
+ * session — two different connections must observe the same ledger.
  */
-export declare function createBlueprintsHandlers(repoRoot: string): Readonly<Partial<Record<string, MethodHandler>>>;
+export declare function createBlueprintsHandlers(repoRoot: string, deps?: BlueprintsHandlerDeps): Readonly<Partial<Record<string, MethodHandler>>>;