@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/installed-flow-source.js

@@ -0,0 +1,261 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { readSetupStatus } from "./setup.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { hybridDigest, validateHybridShape } from "./hybrid-contracts.js";
+import { admitBundledFlow } from "./stage-handlers.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+const limit = 1024 * 1024;
+const flowIds = ["mb-init", "mb-upgrade", "mb-audit", "project-review", "mb-distill", "mb-fix", "review-fix", "release", "deploy", "publish"];
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("installed_flow_source_invalid", "Installed flow source is not the selected verified canon", 1, { reason, phase: "prepare", effect: "no_effect" });
+}
+function directory(target) {
+    if (!fs.lstatSync(target).isDirectory())
+        refuse("unsafe_source_directory");
+}
+function containedFile(root, logical) {
+    if (!/^[A-Za-z0-9_-][A-Za-z0-9_.-]*(\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$/.test(logical)
+        || logical.split("/").some(part => part === "." || part === ".."))
+        refuse("unsafe_source_path");
+    let current = root;
+    for (const part of logical.split("/").slice(0, -1)) {
+        current = path.join(current, part);
+        directory(current);
+    }
+    return path.join(root, logical);
+}
+/** Initial RUN materialization input, not handler/engine/storage admission.
+ * Built-in memory flows live in the global canon, not the curated project pack.
+ * Existing RUNs must restore their retained bundle rather than call this reader.
+ */
+export class PreparedInstalledFlowSource {
+    sha256;
+    #home;
+    #installationSha256;
+    #flowId;
+    #descriptor;
+    #canon;
+    #blobs;
+    constructor(home, installationSha256, flowId, descriptor, canon, blobs) {
+        this.#home = home;
+        this.#installationSha256 = installationSha256;
+        this.#flowId = flowId;
+        this.#descriptor = descriptor;
+        this.#canon = canon;
+        this.#blobs = blobs;
+        this.sha256 = hybridDigest({ installation_sha256: installationSha256, canon, inventory: this.inventory() });
+        Object.freeze(this);
+    }
+    static fromInstalledRelease(home, expectedInstallationSha256, flowId) {
+        try {
+            if (!path.isAbsolute(home) || !/^[a-f0-9]{64}$/.test(expectedInstallationSha256) || !flowIds.includes(flowId))
+                refuse("invalid_selection");
+            const selected = readSetupStatus(home);
+            if (!selected.installation || selected.installation_readiness !== "installed")
+                refuse("installed_release_unavailable");
+            const installation = selected.installation;
+            if (installation.manifest_sha256 !== expectedInstallationSha256)
+                refuse("installation_selection_changed");
+            directory(installation.canon_root);
+            const roots = fs.readdirSync(installation.canon_root);
+            if (roots.length !== 1)
+                refuse("ambiguous_archive_root");
+            const canonRoot = path.join(installation.canon_root, roots[0]);
+            directory(canonRoot);
+            const dotRoot = path.join(canonRoot, ".memory-bank"), memoryRoot = fs.existsSync(dotRoot) ? dotRoot : canonRoot;
+            directory(memoryRoot);
+            const flowRoot = path.join(memoryRoot, "dd-flow");
+            directory(flowRoot);
+            const descriptorPath = `${flowId}/flow-descriptor.json`;
+            const bytes = readBoundedReleaseFile(containedFile(flowRoot, descriptorPath), limit);
+            const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+            if (validateHybridShape("flow-descriptor", value).length || value.id !== flowId || value.origin !== "canon"
+                || value.stages.length > 64)
+                refuse("invalid_descriptor");
+            const blobs = new Map([[descriptorPath, Buffer.from(bytes)]]), folded = new Map([[descriptorPath.toLowerCase(), descriptorPath]]);
+            let total = bytes.length;
+            for (const stage of value.stages)
+                for (const kind of ["instruction", "result_schema"]) {
+                    const reference = stage[kind], existing = blobs.get(reference.path);
+                    if (existing) {
+                        if (hash(existing) !== reference.sha256)
+                            refuse("conflicting_source_reference");
+                        continue;
+                    }
+                    if (folded.has(reference.path.toLowerCase()))
+                        refuse("conflicting_source_path");
+                    const content = readBoundedReleaseFile(containedFile(flowRoot, reference.path), limit);
+                    if (!content.length || (total += content.length) > 32 * limit || hash(content) !== reference.sha256)
+                        refuse("source_bytes_changed");
+                    new TextDecoder("utf-8", { fatal: true }).decode(content);
+                    if (kind === "result_schema")
+                        JSON.parse(content.toString("utf8"));
+                    folded.set(reference.path.toLowerCase(), reference.path);
+                    blobs.set(reference.path, Buffer.from(content));
+                }
+            if (isDiagnosticFlow(flowId)) {
+                const support = ["mbb/index.md", "mbb/memory-bank-structure.md", "mbb/frontmatter-standards.md", "mbb/cross-references.md", "mbb/named-deferrals-guide.md",
+                    ...fs.readdirSync(path.join(memoryRoot, "mbb/aspects")).filter(name => name.endsWith(".md")).map(name => `mbb/aspects/${name}`),
+                    "dd-flow/mb-sdlc/review/aspects.md", "dd-flow/mb-sdlc/review/critics/universal.md", "dd-flow/mb-sdlc/review/critics/architectural-harmonization.md",
+                    ...fs.readdirSync(path.join(flowRoot, "mb-audit/aspects")).filter(name => name.endsWith(".md")).map(name => `dd-flow/mb-audit/aspects/${name}`)];
+                for (const logical of support) {
+                    const content = readBoundedReleaseFile(containedFile(memoryRoot, logical), limit), name = `support/${logical}`;
+                    if (!content.length || (total += content.length) > 32 * limit || folded.has(name.toLowerCase()))
+                        refuse("invalid_support_inventory");
+                    new TextDecoder("utf-8", { fatal: true }).decode(content);
+                    folded.set(name.toLowerCase(), name);
+                    blobs.set(name, Buffer.from(content));
+                }
+                const workSchema = "schemas/diagnostic-work-result.schema.json";
+                const content = readBoundedReleaseFile(containedFile(flowRoot, workSchema), limit);
+                if (!content.length || (total += content.length) > 32 * limit || folded.has(workSchema.toLowerCase()))
+                    refuse("invalid_support_inventory");
+                JSON.parse(content.toString("utf8"));
+                blobs.set(workSchema, Buffer.from(content));
+            }
+            if (flowId === "mb-fix" || flowId === "review-fix") {
+                for (const logical of [`dd-flow/${flowId}/hybrid/index.md`, "mbb/frontmatter-standards.md", "mbb/cross-references.md", "mbb/named-deferrals-guide.md"]) {
+                    const content = readBoundedReleaseFile(containedFile(memoryRoot, logical), limit), name = `support/${logical}`;
+                    if (!content.length || (total += content.length) > 32 * limit || folded.has(name.toLowerCase()))
+                        refuse("invalid_support_inventory");
+                    new TextDecoder("utf-8", { fatal: true }).decode(content);
+                    folded.set(name.toLowerCase(), name);
+                    blobs.set(name, Buffer.from(content));
+                }
+            }
+            if (flowId === "mb-distill") {
+                // Both lenses need their actual comparison baseline, not only titles.
+                const directories = ["mbb", "mbb/aspects", "mbb/templates", "dd-flow/common", "dd-flow/vnext",
+                    "dd-flow/plan", "dd-flow/code", "dd-flow/merge", "dd-flow/workers", "dd-flow/def",
+                    "dd-flow/mb-distill/aspects", "dd-flow/mb-distill/process-aspects"];
+                const support = [...directories.flatMap(logical => {
+                        const source = containedFile(memoryRoot, logical);
+                        directory(source);
+                        return fs.readdirSync(source).filter(name => name.endsWith(".md")).sort().map(name => `${logical}/${name}`);
+                    }), "dd-flow/mb-audit.md", "dd-flow/mb-upgrade/index.md"];
+                for (const logical of support) {
+                    const content = readBoundedReleaseFile(containedFile(memoryRoot, logical), limit), name = `support/${logical}`;
+                    if (!content.length || (total += content.length) > 32 * limit || folded.has(name.toLowerCase()))
+                        refuse("invalid_support_inventory");
+                    new TextDecoder("utf-8", { fatal: true }).decode(content);
+                    folded.set(name.toLowerCase(), name);
+                    blobs.set(name, Buffer.from(content));
+                }
+                const workSchema = "schemas/distill-work-result.schema.json";
+                const content = readBoundedReleaseFile(containedFile(flowRoot, workSchema), limit);
+                if (!content.length || (total += content.length) > 32 * limit || folded.has(workSchema.toLowerCase()))
+                    refuse("invalid_support_inventory");
+                JSON.parse(content.toString("utf8"));
+                blobs.set(workSchema, Buffer.from(content));
+            }
+            // Verify compressed/expanded archive identity again after collecting bytes.
+            // A coherent descriptor+prompt edit cannot become a new trusted selection.
+            const final = readSetupStatus(home);
+            if (final.installation_readiness !== "installed" || hybridDigest(final.installation) !== hybridDigest(installation))
+                refuse("source_changed_during_preparation");
+            return new PreparedInstalledFlowSource(home, expectedInstallationSha256, flowId, { path: descriptorPath, sha256: hash(bytes) }, { version: installation.manifest.canon.version, commit: installation.manifest.canon.commit, archive_sha256: installation.manifest.canon.archive.sha256 }, blobs);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "installed_flow_source_invalid")
+                throw error;
+            return refuse("source_unavailable_or_changed");
+        }
+    }
+    descriptorReference() { return { ...this.#descriptor }; }
+    installationSha256() { return this.#installationSha256; }
+    snapshot() {
+        return { schema_id: "dd-flow/installed-flow-source@1", installation_sha256: this.#installationSha256,
+            descriptor: this.descriptorReference(), canon: this.canonProvenance(),
+            blobs: [...this.#blobs].map(([logical, bytes]) => ({ path: logical, base64: bytes.toString("base64") })) };
+    }
+    /** Copied source restoration only. expectedSha256 must come from independent
+     * request custody, not from the same input. This does not verify a new release
+     * or admit its engine/storage; those remain the bootstrap owner's duties.
+     */
+    static restoreRetained(input, expectedSha256) {
+        const result = this.restoreRetainedData(input, expectedSha256);
+        try {
+            result.resolveRegisteredFlow();
+            return result;
+        }
+        catch {
+            return refuse("invalid_retained_source");
+        }
+    }
+    /** Data recovery before storage/engine admission. This cannot register a
+     * handler; productive restoration still uses restoreRetained above. */
+    static restoreRetainedData(input, expectedSha256) {
+        try {
+            if (!input || typeof input !== "object" || Array.isArray(input) || typeof expectedSha256 !== "string"
+                || !/^[a-f0-9]{64}$/.test(expectedSha256))
+                refuse("invalid_retained_source");
+            const value = input;
+            if (Object.keys(value).sort().join() !== "blobs,canon,descriptor,installation_sha256,schema_id"
+                || value.schema_id !== "dd-flow/installed-flow-source@1" || typeof value.installation_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.installation_sha256)
+                || !value.canon || Object.keys(value.canon).sort().join() !== "archive_sha256,commit,version"
+                || typeof value.canon.commit !== "string" || !/^[a-f0-9]{40}$/.test(value.canon.commit)
+                || typeof value.canon.archive_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.canon.archive_sha256)
+                || typeof value.canon.version !== "string" || !/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(value.canon.version)
+                || !value.descriptor || Object.keys(value.descriptor).sort().join() !== "path,sha256"
+                || !flowIds.some(id => value.descriptor.path === `${id}/flow-descriptor.json`) || typeof value.descriptor.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.descriptor.sha256)
+                || !Array.isArray(value.blobs) || value.blobs.length < 1 || value.blobs.length > 512)
+                refuse("invalid_retained_source");
+            const blobs = new Map(), folded = new Set();
+            let total = 0;
+            for (const entry of value.blobs) {
+                if (!entry || Object.keys(entry).sort().join() !== "base64,path" || typeof entry.path !== "string"
+                    || !/^[A-Za-z0-9_-][A-Za-z0-9_.-]*(\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$/.test(entry.path)
+                    || entry.path.split("/").some(part => part === "." || part === "..")
+                    || folded.has(entry.path.toLowerCase()) || typeof entry.base64 !== "string" || entry.base64.length > 2 * limit)
+                    refuse("invalid_retained_source");
+                const content = Buffer.from(entry.base64, "base64");
+                if (!content.length || content.length > limit || content.toString("base64") !== entry.base64
+                    || (total += content.length) > 32 * limit)
+                    refuse("invalid_retained_source");
+                new TextDecoder("utf-8", { fatal: true }).decode(content);
+                folded.add(entry.path.toLowerCase());
+                blobs.set(entry.path, content);
+            }
+            const descriptor = blobs.get(value.descriptor.path);
+            if (!descriptor || hash(descriptor) !== value.descriptor.sha256)
+                refuse("retained_source_changed");
+            const flowId = value.descriptor.path.slice(0, -"/flow-descriptor.json".length);
+            const declared = JSON.parse(descriptor.toString("utf8"));
+            if (validateHybridShape("flow-descriptor", declared).length || declared.id !== flowId || declared.origin !== "canon")
+                refuse("invalid_retained_source");
+            for (const stage of declared.stages)
+                for (const kind of ["instruction", "result_schema"]) {
+                    const reference = stage[kind], content = blobs.get(reference.path);
+                    if (!content || hash(content) !== reference.sha256)
+                        refuse("retained_source_changed");
+                }
+            const result = new PreparedInstalledFlowSource(null, value.installation_sha256, flowId, { ...value.descriptor }, { ...value.canon }, blobs);
+            if (result.sha256 !== expectedSha256)
+                refuse("retained_source_changed");
+            return result;
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "installed_flow_source_invalid")
+                throw error;
+            return refuse("invalid_retained_source");
+        }
+    }
+    canonProvenance() { return { ...this.#canon }; }
+    blobs() { return new Map([...this.#blobs].map(([logical, bytes]) => [logical, Buffer.from(bytes)])); }
+    inventory() { return [...this.#blobs].map(([logical, bytes]) => ({ path: logical, sha256: hash(bytes) })).sort((a, b) => a.path.localeCompare(b.path, "en")); }
+    /** Production handler registry only: source declarations cannot register code. */
+    resolveRegisteredFlow() { return admitBundledFlow(this.#blobs.get(this.#descriptor.path), this.#descriptor.sha256, this.#blobs); }
+    /** Initial materialization only, outside SQL writers. */
+    revalidate() {
+        if (this.#home === null) {
+            PreparedInstalledFlowSource.restoreRetained(this.snapshot(), this.sha256);
+            return;
+        }
+        if (PreparedInstalledFlowSource.fromInstalledRelease(this.#home, this.#installationSha256, this.#flowId).sha256 !== this.sha256)
+            refuse("source_changed_after_preparation");
+    }
+}

package/dist/services/interactive-attached-session.js

@@ -0,0 +1,215 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { parse } from "shell-quote";
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { hookSessionIdentity } from "./hooks.js";
+import { prepareOperatorProfile } from "./operator-profiles.js";
+import { findProjectByRoot } from "./projects.js";
+import { parseCommandArgs } from "./lifecycle-command.js";
+const eventType = "interactive.attached_session";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("interactive_attached_session_required", "Interactive needs its current trusted attached Session; choose managed execution explicitly otherwise", 2, { phase: "prepare", effect: "no_effect", reason, next_action: "provide_matching_attached_session_or_choose_managed" });
+}
+function checkedScope(scope) {
+    if (!scope || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(scope.requestId)
+        || [scope.projectRoot, scope.workspace].some(value => typeof value !== "string" || !path.isAbsolute(value)))
+        refuse("invalid_scope");
+    try {
+        if ([scope.projectRoot, scope.workspace].some(value => fs.realpathSync(value) !== value))
+            refuse("noncanonical_scope");
+    }
+    catch {
+        refuse("workspace_unavailable");
+    }
+}
+function project(context, scope) {
+    const value = findProjectByRoot(context, scope.projectRoot);
+    if (!value)
+        refuse("registered_project_required");
+    return value;
+}
+function launchArguments(context, command) {
+    let dynamic = false;
+    const entries = parse(command, () => { dynamic = true; return ""; });
+    if (dynamic || entries.some(entry => typeof entry !== "string") || /[`\n\r]/.test(command))
+        refuse("standalone_launch_required");
+    const words = entries;
+    let index = 0;
+    if (words[0]?.startsWith("DD_FLOW_HOME=")) {
+        if (words[0].slice("DD_FLOW_HOME=".length) !== context.ddFlowHome)
+            refuse("launch_home_mismatch");
+        index++;
+    }
+    if (path.basename(words[index] ?? "") === "node" && path.basename(words[index + 1] ?? "") === "cli.js")
+        index++;
+    else if (path.basename(words[index] ?? "") !== "dd-flow")
+        refuse("standalone_launch_required");
+    return words.slice(index + 1);
+}
+function checkLaunchCommand(context, scope, command) {
+    const args = parseCommandArgs(launchArguments(context, command)), option = (key) => args.options.get(key);
+    if (args.positional.join(" ") !== "flow interactive" || option("help") || option("execution")?.some(value => value !== "attached")
+        || option("request-id")?.length !== 1 || option("request-id")[0] !== scope.requestId
+        || option("project-root")?.length !== 1 || option("project-root")[0] !== scope.projectRoot
+        || (option("workspace") ? option("workspace").length !== 1 || option("workspace")[0] !== scope.workspace : scope.workspace !== scope.projectRoot))
+        refuse("launch_scope_mismatch");
+}
+function binding(context, scope, selected, source, fresh) {
+    if (!source || typeof source.eventKey !== "string" || !source.eventKey || typeof source.command !== "string"
+        || !source.command.trim() || Buffer.byteLength(source.command) > 32 * 1024)
+        refuse("exact_launch_receipt_required");
+    checkLaunchCommand(context, scope, source.command);
+    const profile = prepareOperatorProfile(selected), selectedProject = project(context, scope);
+    const event = context.db.get("SELECT id,event_name,status,sanitized_summary,created_at FROM hook_events WHERE project_id=? AND event_key=?", [selectedProject.id, source.eventKey]);
+    if (!event || event.event_name !== "PreToolUse" || event.status !== (fresh ? "observed" : "claimed"))
+        refuse("unavailable_launch_receipt");
+    const age = Date.parse(context.now()) - Date.parse(event.created_at);
+    // Reuse the existing hook admission horizon; historical restore does not
+    // pretend that the original launch event proves a currently live Session.
+    if (fresh && (!Number.isFinite(age) || age < 0 || age > 60_000))
+        refuse("stale_launch_receipt");
+    let summary;
+    try {
+        summary = JSON.parse(event.sanitized_summary);
+    }
+    catch {
+        return refuse("exact_launch_receipt_required");
+    }
+    if ((summary?.command ?? summary?.tool_input?.command) !== source.command)
+        refuse("launch_command_mismatch");
+    const identity = hookSessionIdentity(context, selectedProject.id, source.eventKey);
+    if (identity.parentSessionId || !identity.providerSessionId || identity.harness !== runtimeHarness(profile))
+        refuse("root_session_mismatch");
+    if (identity.cwd !== scope.workspace)
+        refuse("session_workspace_mismatch");
+    if (identity.provider !== profile.provider || identity.model !== profile.model || identity.reasoning !== profile.reasoning
+        || identity.mode !== profile.mode)
+        refuse("session_profile_mismatch");
+    return { schema_id: "dd-flow/interactive-attached-session@1", scope: structuredClone(scope), profile,
+        hook_event_id: event.id, event_key: source.eventKey, command: source.command, harness: identity.harness,
+        provider_session_id: identity.providerSessionId, session_id: identity.sessionId, daemon_id: identity.daemonId, observed_at: event.created_at };
+}
+function retained(context, scope) {
+    const selectedProject = project(context, scope);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.binding.scope.requestId')=? LIMIT 2", [selectedProject.id, eventType, scope.requestId]);
+    if (rows.length > 1)
+        refuse("ambiguous_attached_binding");
+    if (!rows.length)
+        return null;
+    if (Buffer.byteLength(rows[0].payload_json) > 256 * 1024)
+        refuse("invalid_attached_binding");
+    let value;
+    try {
+        value = JSON.parse(rows[0].payload_json);
+    }
+    catch {
+        return refuse("invalid_attached_binding");
+    }
+    if (!value || !value.binding || !value.binding.scope || Object.keys(value).sort().join() !== "binding,sha256" || hybridDigest(value.binding.scope) !== hybridDigest(scope)
+        || hash(Buffer.from(JSON.stringify(value.binding))) !== value.sha256)
+        refuse("attached_binding_changed");
+    const actual = binding(context, scope, value.binding.profile, { eventKey: value.binding.event_key, command: value.binding.command }, false);
+    if (hybridDigest(actual) !== hybridDigest(value.binding))
+        refuse("attached_receipt_changed");
+    return value;
+}
+/** Produces generic execution receipt facts from the trusted hook ledger, not
+ * model-authored receipt JSON or ambient Session/model environment variables.
+ * This does not create a RUN or prove independent review/delegation capacity. */
+export class PreparedInteractiveAttachedSession {
+    sha256;
+    #binding;
+    constructor(value) {
+        this.#binding = structuredClone(value);
+        this.sha256 = hash(Buffer.from(JSON.stringify(value)));
+        Object.freeze(this);
+    }
+    static prepare(context, scope, profile, source) {
+        checkedScope(scope);
+        if (retained(context, scope))
+            refuse("restore_retained_attached_binding");
+        return new PreparedInteractiveAttachedSession(binding(context, scope, profile, source, true));
+    }
+    /** Discover only an exact current argv observation. Same request/root/profile
+     * with a different intake or selector is not evidence for this invocation. */
+    static prepareCurrent(context, scope, profile, args) {
+        checkedScope(scope);
+        if (!Array.isArray(args) || args.length > 1024 || args.some(arg => typeof arg !== "string" || arg.includes("\0"))
+            || args[0] !== "flow" || args[1] !== "interactive")
+            refuse("exact_launch_receipt_required");
+        if (retained(context, scope))
+            refuse("restore_retained_attached_binding");
+        const selectedProject = project(context, scope), matches = [];
+        const rows = context.db.all("SELECT event_key,sanitized_summary FROM hook_events WHERE project_id=? AND event_name='PreToolUse' AND status='observed' AND created_at>=? ORDER BY id DESC LIMIT 129", [selectedProject.id, new Date(Date.parse(context.now()) - 60_000).toISOString()]);
+        if (rows.length > 128)
+            refuse("launch_observation_window_exceeds_bound");
+        for (const row of rows) {
+            if (typeof row.sanitized_summary !== "string" || Buffer.byteLength(row.sanitized_summary) > 64 * 1024)
+                continue;
+            let summary;
+            try {
+                summary = JSON.parse(row.sanitized_summary);
+            }
+            catch {
+                continue;
+            }
+            const command = summary?.command ?? summary?.tool_input?.command;
+            if (typeof command !== "string" || Buffer.byteLength(command) > 32 * 1024)
+                continue;
+            try {
+                if (hybridDigest(launchArguments(context, command)) !== hybridDigest(args))
+                    continue;
+                matches.push(binding(context, scope, profile, { eventKey: row.event_key, command }, true));
+            }
+            catch (error) {
+                if (!(error instanceof AppError) || error.code !== "interactive_attached_session_required")
+                    throw error;
+            }
+        }
+        if (matches.length !== 1)
+            refuse(matches.length ? "ambiguous_launch_receipt" : "unavailable_launch_receipt");
+        return new PreparedInteractiveAttachedSession(matches[0]);
+    }
+    static restore(context, scope) {
+        checkedScope(scope);
+        const value = retained(context, scope);
+        if (!value)
+            refuse("attached_binding_missing");
+        return new PreparedInteractiveAttachedSession(value.binding);
+    }
+    snapshot() { return structuredClone(this.#binding); }
+    evidence() {
+        const value = this.#binding, bytes = Buffer.from(JSON.stringify(value));
+        const reference = { path: "receipts/interactive-attached-session.json", sha256: this.sha256 };
+        const receipts = new Map([[this.sha256, { kind: "attached-session-binding", ...value.scope,
+                    harness: value.profile.harness, profileRevision: hybridDigest(value.profile) }]]);
+        return { reference, bytes, receipts };
+    }
+    /** Pair hook claim and custody with the caller's request/RUN writer. */
+    retainPreparedSql(context) {
+        if (!context.db.isOwnedWriteTransaction?.())
+            refuse("owned_writer_required");
+        const value = this.#binding, prior = retained(context, value.scope);
+        if (prior) {
+            if (prior.sha256 !== this.sha256)
+                refuse("attached_binding_changed");
+            return { changed: false };
+        }
+        const current = binding(context, value.scope, value.profile, { eventKey: value.event_key, command: value.command }, true);
+        if (hybridDigest(current) !== hybridDigest(value))
+            refuse("attached_receipt_changed");
+        const selectedProject = project(context, value.scope);
+        const claimed = context.db.run("UPDATE hook_events SET status='claimed',claimed_at=? WHERE id=? AND project_id=? AND status='observed'", [context.now(), value.hook_event_id, selectedProject.id]);
+        if (claimed.changes !== 1)
+            refuse("launch_receipt_consumed");
+        appendAudit(context, { projectId: selectedProject.id, eventType, payload: { binding: value, sha256: this.sha256 } });
+        if (retained(context, value.scope)?.sha256 !== this.sha256)
+            refuse("attached_readback_failed");
+        return { changed: true };
+    }
+}

package/dist/services/interactive-baseline-custody.js

@@ -0,0 +1,54 @@
+import { AppError } from "../shared/errors.js";
+import { PreparedInteractiveGitBaseline } from "./interactive-git-baseline.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { restoreInteractiveBeforeVersions } from "./interactive-before-versions.js";
+import { readInteractiveBundleData } from "./interactive-bundle-data.js";
+const logical = "runtime/git-baseline.json";
+function refuse(reason) {
+    throw new AppError("interactive_baseline_custody_invalid", "Interactive requires its own retained entry baseline", 2, { reason, effect: "no_effect" });
+}
+function selected(context, scope, bundle, file = logical) {
+    if (bundle.manifest.flow_id !== "interactive" || bundle.manifest.run_id !== scope.runId)
+        refuse("interactive_bundle_required");
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    return readInteractiveBundleData(bundle, file);
+}
+/** Initial physical observation, not RUN allocation or mutation authority. The
+ * factory must revalidate before retaining these bytes and starting work. */
+export function prepareInteractiveGitBaseline(input) {
+    const baseline = PreparedInteractiveGitBaseline.capture(input);
+    return { path: logical, sha256: baseline.sha256, bytes: baseline.bytes(), baseline };
+}
+/** SQL/in-memory fence for Stage acceptance: no project/Git/filesystem lookup,
+ * profile selection, fresh capture or adoption of a caller's replacement JSON. */
+export function assertInteractiveGitBaselineCustody(context, scope, bundle, expectedSha256) {
+    if (selected(context, scope, bundle).sha256 !== expectedSha256)
+        refuse("baseline_binding_changed");
+}
+/** Historical custody uses the frozen execution scope. Current physical scope
+ * and supported relocation must be admitted separately before subsequent work. */
+export function readPreparedInteractiveGitBaseline(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        const { bytes, reference, sha256 } = selected(context, scope, bundle);
+        const baseline = PreparedInteractiveGitBaseline.restore(bytes, sha256), value = baseline.snapshot();
+        const frozen = bundle.execution.snapshot().scope;
+        if (value.project_root !== frozen.projectRoot || value.workspace !== frozen.workspace)
+            refuse("baseline_scope_changed");
+        return { baseline, sha256,
+            reference: { root: "run", path: `execution-bundle/${logical}`, sha256: reference.sha256 } };
+    });
+}
+export function assertInteractiveBeforeVersionsCustody(context, scope, bundle, expectedSha256) {
+    if (selected(context, scope, bundle, "runtime/before-versions.json").sha256 !== expectedSha256)
+        refuse("before_versions_binding_changed");
+}
+/** Initial before-images selected from this same RUN/baseline. Later per-turn
+ * before-images require their own accepted Work/packet custody, not bundle edits. */
+export function readPreparedInteractiveBeforeVersions(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        const baseline = readPreparedInteractiveGitBaseline(context, scope, bundle);
+        const { bytes, reference, sha256 } = selected(context, scope, bundle, "runtime/before-versions.json");
+        return { value: restoreInteractiveBeforeVersions(bytes, sha256, baseline.baseline), sha256,
+            reference: { root: "run", path: "execution-bundle/runtime/before-versions.json", sha256: reference.sha256 } };
+    });
+}