@webpresso/agent-kit 3.3.2 → 3.3.4

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>>>;

package/dist/esm/daemon/handlers/blueprints-handlers.js

@@ -1,10 +1,22 @@
 /**
- * Blueprint-domain product handlers: `blueprints.list` is a real
- * implementation over the `blueprints/<status>/` directories; `blueprints.exec`
- * is not implemented (exec remains CLI-owned).
+ * Blueprint-domain product handlers.
+ *
+ * - `blueprints.list` enumerates the `blueprints/<status>/` directories.
+ * - `blueprints.exec` composes an executor launch spec and prepares it as an
+ *   opaque, single-use launch handle. It returns **only** identifiers: no
+ *   command, no argv, no cwd, no env ever crosses to the webview, and this
+ *   module never spawns anything (spawning is Rust-only, through the PTY
+ *   manager, after a rust-credentialed `launch.claim`).
+ * - `blueprints.execBind` is rust-role-only and records the spawned PTY
+ *   session against the job so attribution survives a UI restart.
+ * - `blueprints.execStatus` joins ledger rows with executor-written blueprint
+ *   frontmatter metadata. Status is never parsed out of PTY output — the
+ *   terminal stream is human-viewing only.
  */
 import { readdirSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { composeBlueprintExecSpec, readBlueprintExecProgress, } from "#daemon/domains/blueprint-exec.js";
+import { asRecord, requireString } from "./shared.js";
 function listBlueprintRows(repoRoot) {
     const statuses = ["completed", "in-progress", "planned", "parked", "draft", "archived"];
     const rows = [];
@@ -21,16 +33,146 @@ function listBlueprintRows(repoRoot) {
     rows.sort((a, b) => a.slug.localeCompare(b.slug));
     return rows;
 }
+/**
+ * Executor statuses that mean the run is over. Mirrors `executionStatusSchema`
+ * terminal values; a job in one of these retires from the ledger.
+ */
+const TERMINAL_EXECUTION_STATUSES = new Set([
+    "completed",
+    "failed",
+    "stopped",
+]);
+function optionalString(record, key) {
+    const value = record[key];
+    if (value === undefined || value === null || value === "")
+        return null;
+    if (typeof value !== "string") {
+        throw new Error(`param ${key} must be a string when present`);
+    }
+    return value;
+}
+/**
+ * Params `blueprints.exec` accepts. `requestNonce`/`confirmationToken` belong
+ * to the auth envelope and may still be present on the domain record.
+ *
+ * The protocol contract's strict Zod schema is a declarative helper and is not
+ * applied on the dispatch path, so unknown keys would otherwise be silently
+ * ignored rather than refused. Ignoring is already fail-safe here (the handler
+ * reads only known keys), but refusing is what makes "exec params are data,
+ * not command" an enforced boundary instead of an aspirational one — and it
+ * stops a future edit that naively spreads params from becoming an injection.
+ */
+const EXEC_ALLOWED_PARAM_KEYS = new Set([
+    "slug",
+    "taskId",
+    "confirmationToken",
+    "requestNonce",
+]);
+/** O(#keys) on a bounded record. Never echoes caller-controlled key text. */
+function assertNoSmuggledExecParams(record) {
+    for (const key of Object.keys(record)) {
+        if (!EXEC_ALLOWED_PARAM_KEYS.has(key)) {
+            throw new Error("unexpected param for blueprints.exec: only slug and taskId are accepted " +
+                "(command, args, cwd, and env are composed by the daemon)");
+        }
+    }
+}
+function requireSessionId(record) {
+    const value = record["sessionId"];
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error("missing or invalid param: sessionId");
+    }
+    return value;
+}
+function requireExecDeps(deps) {
+    const { launchLedger, execLedger } = deps;
+    if (launchLedger === undefined || execLedger === undefined) {
+        throw new Error("blueprints exec is unavailable: daemon ledgers are not wired");
+    }
+    return { launchLedger, execLedger };
+}
 /**
  * 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 function createBlueprintsHandlers(repoRoot) {
+export function createBlueprintsHandlers(repoRoot, deps = {}) {
+    const allowlistedRoots = deps.allowlistedRoots !== undefined && deps.allowlistedRoots.length > 0
+        ? deps.allowlistedRoots
+        : [repoRoot];
     return {
         "blueprints.list": () => ({
             blueprints: listBlueprintRows(repoRoot),
         }),
-        "blueprints.exec": () => {
-            throw new Error("blueprints.exec is not implemented (exec remains CLI-owned)");
+        "blueprints.exec": (_session, params) => {
+            const { launchLedger, execLedger } = requireExecDeps(deps);
+            const record = asRecord(params);
+            assertNoSmuggledExecParams(record);
+            const slug = requireString(record, "slug");
+            const taskId = optionalString(record, "taskId");
+            // Validation, path confinement, and daemon-side argv composition.
+            const spec = composeBlueprintExecSpec({
+                slug,
+                taskId,
+                repoRoot,
+                allowlistedRoots,
+            });
+            const { handle } = launchLedger.prepareComposed({
+                command: spec.command,
+                args: spec.args,
+                cwd: spec.cwd,
+                env: spec.env,
+            });
+            const { jobId } = execLedger.register({
+                slug: spec.slug,
+                taskId: spec.taskId,
+                launchHandle: handle,
+            });
+            // Opaque only: the rust-role claim is what yields command/args/env.
+            return { jobId, handle };
+        },
+        "blueprints.execBind": (_session, params) => {
+            const { execLedger } = requireExecDeps(deps);
+            const record = asRecord(params);
+            const jobId = requireString(record, "jobId");
+            const sessionId = requireSessionId(record);
+            const job = execLedger.bindSession(jobId, sessionId);
+            return { jobId: job.jobId, sessionId: job.sessionId, state: job.state };
+        },
+        "blueprints.execStatus": (_session, params) => {
+            const { execLedger } = requireExecDeps(deps);
+            const record = asRecord(params);
+            const slugFilter = optionalString(record, "slug");
+            const jobs = execLedger
+                .list()
+                .filter((job) => slugFilter === null || job.slug === slugFilter)
+                .map((job) => {
+                // Executor-written frontmatter metadata — never PTY bytes.
+                const progress = readBlueprintExecProgress(repoRoot, job.slug);
+                // Drive the terminal transition from the executor's own status.
+                // This is what keeps `markTerminal` (and therefore ledger eviction)
+                // live in production without inventing a push transport: the daemon
+                // has no server-push seam, so the pull that reports status is also
+                // the pull that retires the job.
+                const settled = progress !== null && TERMINAL_EXECUTION_STATUSES.has(progress.status)
+                    ? execLedger.markTerminal(job.jobId)
+                    : null;
+                const state = settled?.state ?? job.state;
+                return {
+                    jobId: job.jobId,
+                    slug: job.slug,
+                    taskId: job.taskId,
+                    sessionId: job.sessionId,
+                    state,
+                    startedAt: job.startedAt,
+                    executionId: progress?.executionId ?? null,
+                    executionStatus: progress?.status ?? null,
+                    executionUpdatedAt: progress?.updatedAt ?? null,
+                };
+            });
+            return { jobs };
         },
     };
 }