@astrosheep/keiyaku 1.0.0 → 1.0.2

package/build/core/call.js

@@ -0,0 +1,658 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import { ACTOR_IDENTITY, BASE_RULES_FILE, KEIYAKU_FILE } from "../keiyaku.js";
+import { isErrnoException } from "../errno.js";
+import { FlowError, requireText } from "../flow-error.js";
+import { isGitRepo } from "../git/branches.js";
+import { createGit, wrapGitError } from "../git/core.js";
+import { createAbortError } from "../agents/harness/runtime.js";
+import { selectSubagentV2 } from "../agents/selector_v2.js";
+import { buildCallTermsV2 } from "../agents/call-terms_v2.js";
+import { applySnapshotEffort, resolveAkumaLaunchSnapshot, } from "../agents/launch-snapshot_v2.js";
+import { restoreOutcome } from "../agents/harness/index.js";
+import { mintProjection, mintRepositoryProjection } from "./projection-mint.js";
+import { waitForProjection } from "./projection-wait.js";
+import { requireResumableArtifact } from "./transcripts.js";
+import { appendDebugBlock } from "../telemetry/debug-log.js";
+import { logInfo } from "../telemetry/logger.js";
+import { SubagentFailure } from "../agents/types.js";
+import { AddressResolutionError, buildResolutionAttempt, buildUncommissionedAddress, resolveContractAddress, resolveUncommissionedRepositoryAddress, withResolvedAddress, } from "./addressing.js";
+import { readLedger } from "./ledger.js";
+import { findOpenArcView } from "./arc.js";
+import { deriveContractState, isTerminalState } from "./status.js";
+import { contractPresentedByWorktree, contractWorktreePathFromBind, stableRepoRoot } from "./worktree-path.js";
+import { createProjectionExecutionId } from "./projection-generation-identity.js";
+import { openProjectionGenerationStore, openProjectionGenerationStoreReadOnly, } from "./projection-generation-store.js";
+import { PROJECTION_ADOPTION_TIMEOUT_MS, startProjectionGeneration } from "./projection-generation-launcher.js";
+import { observeProjectionLife } from "./projection-life-observer.js";
+export function buildCallPrompt(input) {
+    const references = [...new Set((input.referenceFiles ?? []).map((file) => file.trim()).filter(Boolean))];
+    if (!input.arc) {
+        return [input.task, input.context?.trim() ?? "", references.length > 0 ? `Reference files:\n${references.map((file) => `- ${file}`).join("\n")}` : ""]
+            .filter(Boolean)
+            .join("\n\n");
+    }
+    const arc = input.arc;
+    return [
+        `You are a called ${ACTOR_IDENTITY} working inside open arc a${arc.arc}.`,
+        "Stay within the arc scope and do the requested work directly.",
+        `Title: ${arc.title}`,
+        `Objective: ${arc.objective}`,
+        `Brief:\n${arc.brief}`,
+        "",
+        `Task:\n${input.task}`,
+        `Context:\n${input.context?.trim() || "(none provided)"}`,
+        references.length > 0 ? `Reference files:\n${references.map((file) => `- ${file}`).join("\n")}` : "",
+        "Provide the final result for the caller/main agent.",
+    ].filter(Boolean).join("\n\n");
+}
+function renderSubagentWarning(warning) {
+    const modelTransition = warning.originalModel && warning.fallbackModel
+        ? `${warning.originalModel} -> ${warning.fallbackModel}`
+        : warning.originalModel ?? warning.fallbackModel;
+    const details = [
+        modelTransition,
+        warning.direction ? `direction=${warning.direction}` : undefined,
+        warning.requestId !== undefined ? `requestId=${warning.requestId ?? "null"}` : undefined,
+        warning.signerModel ? `signerModel=${warning.signerModel}` : undefined,
+    ].filter((value) => Boolean(value));
+    const summary = warning.reason === "refusal" ? "Provider warning: model fallback." : "Provider warning: overload fallback.";
+    return details.length > 0 ? `${summary} ${details.join(", ")}` : summary;
+}
+async function fileExists(cwd, relativePath) {
+    try {
+        await fs.access(path.join(cwd, relativePath));
+        return true;
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+async function collectCallReferenceFiles(cwd, input) {
+    const candidates = [
+        ...(input.activeKeiyaku ? [KEIYAKU_FILE] : []),
+        BASE_RULES_FILE,
+    ];
+    const existing = await Promise.all(candidates.map(async (file) => ({ file, exists: await fileExists(cwd, file) })));
+    return existing.filter((entry) => entry.exists).map((entry) => entry.file);
+}
+async function findWorktreePathForContract(cwd, contractId) {
+    const git = createGit(cwd);
+    let output;
+    try {
+        output = await git.raw(["worktree", "list", "--porcelain"]);
+    }
+    catch (error) {
+        throw wrapGitError("worktree list --porcelain", error, cwd);
+    }
+    let currentPath;
+    for (const line of output.split(/\r?\n/)) {
+        if (line.startsWith("worktree ")) {
+            currentPath = line.slice("worktree ".length);
+            continue;
+        }
+        if (line === `branch refs/heads/keiyaku/${contractId}`) {
+            return currentPath;
+        }
+    }
+    return undefined;
+}
+async function resolveWorkspaceCwd(cwd, contractId, bind) {
+    const repoRoot = cwd;
+    if (bind.data.workspace === "here")
+        return repoRoot;
+    const listedWorktreePath = await findWorktreePathForContract(cwd, contractId);
+    const worktreePath = listedWorktreePath ?? await contractWorktreePathFromBind(repoRoot, contractId, bind);
+    let stat;
+    try {
+        stat = await fs.stat(worktreePath);
+    }
+    catch (error) {
+        throw new FlowError("INTERNAL_STATE", `contract ${contractId} worktree not found at ${worktreePath}`, { cause: error });
+    }
+    if (!stat.isDirectory()) {
+        throw new FlowError("INTERNAL_STATE", `contract ${contractId} worktree path is not a directory: ${worktreePath}`);
+    }
+    return worktreePath;
+}
+async function readCallKeiyakuContext(executionCwd, input) {
+    const ledgerCandidate = input.repoCwd ?? executionCwd;
+    const isRepo = await isGitRepo(ledgerCandidate);
+    if (!isRepo) {
+        if (input.bare && input.contractId) {
+            const asTyped = input.contractAddressSource === "at-address"
+                ? `@${input.contractId}`
+                : input.contractId;
+            throw new AddressResolutionError("EMPTY_PARAM", `commission address ${asTyped} cannot be combined with --bare`, buildResolutionAttempt({
+                repo: { kind: "user" },
+                workdir: executionCwd,
+                spelling: {
+                    asTyped,
+                    source: input.contractAddressSource ?? "explicit-flag",
+                },
+            }));
+        }
+        if (input.contractId) {
+            const asTyped = input.contractAddressSource === "at-address"
+                ? `@${input.contractId}`
+                : input.contractId;
+            throw new AddressResolutionError("EMPTY_PARAM", `${asTyped} is a commission address, but ${ledgerCandidate} has no repository ledger; contract addressing requires a ledger`, buildResolutionAttempt({
+                repo: { kind: "user" },
+                workdir: executionCwd,
+                spelling: {
+                    asTyped,
+                    source: input.contractAddressSource ?? "explicit-flag",
+                },
+            }));
+        }
+        return {
+            activeKeiyaku: false,
+            effectiveCwd: executionCwd,
+            historyCwd: executionCwd,
+            profileCwd: executionCwd,
+            projectionCwd: executionCwd,
+            address: buildUncommissionedAddress({
+                repo: { kind: "user" },
+                workdir: executionCwd,
+                binding: input.bare ? "bare" : "unbound",
+            }),
+        };
+    }
+    const ledgerCwd = await stableRepoRoot(ledgerCandidate);
+    if (input.reviveBinding) {
+        if (input.reviveBinding.kind === "commission") {
+            input.contractId = input.reviveBinding.commissionId;
+            input.contractAddressSource = "artifact-provenance";
+        }
+        else {
+            return {
+                activeKeiyaku: false,
+                effectiveCwd: executionCwd,
+                historyCwd: ledgerCwd,
+                profileCwd: ledgerCwd,
+                projectionCwd: ledgerCwd,
+                address: await resolveUncommissionedRepositoryAddress({
+                    repoCwd: ledgerCwd,
+                    workdir: executionCwd,
+                    binding: input.reviveBinding.kind,
+                }),
+            };
+        }
+    }
+    if (input.bare && input.contractId) {
+        const repositoryAddress = await resolveUncommissionedRepositoryAddress({
+            repoCwd: ledgerCwd,
+            workdir: executionCwd,
+            binding: "bare",
+        });
+        const asTyped = input.contractAddressSource === "at-address"
+            ? `@${input.contractId}`
+            : input.contractId;
+        throw new AddressResolutionError("EMPTY_PARAM", `commission address ${asTyped} cannot be combined with --bare`, buildResolutionAttempt({
+            repo: repositoryAddress.repo,
+            workdir: repositoryAddress.workdir,
+            spelling: {
+                asTyped,
+                source: input.contractAddressSource ?? "explicit-flag",
+            },
+        }));
+    }
+    if (input.bare) {
+        return {
+            activeKeiyaku: false,
+            effectiveCwd: executionCwd,
+            historyCwd: ledgerCwd,
+            profileCwd: ledgerCwd,
+            projectionCwd: ledgerCwd,
+            address: await resolveUncommissionedRepositoryAddress({
+                repoCwd: ledgerCwd,
+                workdir: executionCwd,
+                binding: "bare",
+            }),
+        };
+    }
+    let address;
+    if (input.contractId) {
+        address = await resolveContractAddress(ledgerCwd, input.contractId, input.contractAddressSource);
+    }
+    else if (await isGitRepo(executionCwd)) {
+        const executionRepo = await stableRepoRoot(executionCwd);
+        if (input.repoCwd && executionRepo !== ledgerCwd) {
+            const presented = await contractPresentedByWorktree(executionCwd);
+            if (presented) {
+                throw new FlowError("EMPTY_PARAM", `cross-repository contract-worktree addressing is pending: -C presents @${presented} from ${executionRepo}, but --repo selects ${ledgerCwd}`);
+            }
+        }
+        else {
+            const presented = await contractPresentedByWorktree(executionCwd);
+            if (presented) {
+                address = await resolveContractAddress(ledgerCwd, presented, "worktree-presented");
+            }
+        }
+    }
+    if (!address) {
+        try {
+            address = await resolveContractAddress(ledgerCwd);
+        }
+        catch (error) {
+            if (error instanceof AddressResolutionError
+                && error.code === "EMPTY_PARAM"
+                && error.attempt.candidates.length === 0) {
+                return {
+                    activeKeiyaku: false,
+                    effectiveCwd: executionCwd,
+                    historyCwd: ledgerCwd,
+                    profileCwd: ledgerCwd,
+                    projectionCwd: ledgerCwd,
+                    address: await resolveUncommissionedRepositoryAddress({
+                        repoCwd: ledgerCwd,
+                        workdir: executionCwd,
+                        binding: "unbound",
+                    }),
+                };
+            }
+            throw error;
+        }
+    }
+    return await withResolvedAddress(address, async () => {
+        const contractId = address.binding.commissionId;
+        const ledger = await readLedger(ledgerCwd, contractId);
+        if (!ledger) {
+            throw new FlowError("INTERNAL_STATE", `contract ${contractId} not found or not active`);
+        }
+        const state = deriveContractState(ledger.entries);
+        if (state.state === "corrupt") {
+            throw new FlowError("INTERNAL_STATE", `contract ${contractId} is corrupt at entry ${state.at}: ${state.reason}`);
+        }
+        if (isTerminalState(state)) {
+            throw new FlowError("EMPTY_PARAM", `commission ${contractId} is terminal and cannot launch an Akuma`);
+        }
+        const bind = ledger.entries.find((entry) => entry.kind === "bind");
+        if (!bind) {
+            throw new FlowError("INTERNAL_STATE", `contract ${contractId} active ledger is missing bind entry`);
+        }
+        const effectiveCwd = await resolveWorkspaceCwd(ledgerCwd, contractId, bind);
+        const executionAddress = { ...address, workdir: effectiveCwd };
+        const openArc = findOpenArcView(ledger.entries);
+        return {
+            activeKeiyaku: true,
+            effectiveCwd,
+            historyCwd: ledgerCwd,
+            profileCwd: effectiveCwd,
+            projectionCwd: ledgerCwd,
+            openArc: openArc ?? undefined,
+            address: executionAddress,
+        };
+    });
+}
+export async function execSubagent(agentName, prompt, cwd, options) {
+    const { outcome } = await executeSubagent(agentName, prompt, cwd, options);
+    return outcome;
+}
+function readCurrentGenerationOrThrow(projectionDirectory) {
+    const store = openProjectionGenerationStoreReadOnly(projectionDirectory);
+    try {
+        const current = store.readCurrentGeneration();
+        if (!current)
+            throw new FlowError("INTERNAL_STATE", "projection has no current generation");
+        return current;
+    }
+    finally {
+        store.close();
+    }
+}
+function outcomeFromGeneration(current) {
+    const verdict = current.verdict;
+    if (!verdict)
+        throw new FlowError("INTERNAL_STATE", "projection generation has no terminal verdict");
+    const facts = verdict.facts;
+    const finalMessage = typeof facts.finalMessage === "string"
+        ? facts.finalMessage
+        : typeof facts.detail === "string"
+            ? facts.detail
+            : "";
+    if (facts.state === "failed" && typeof facts.detail === "string") {
+        throw new FlowError("SUBAGENT_EXEC_ERROR", facts.detail);
+    }
+    const session = facts.session;
+    if (session === null || typeof session !== "object" || Array.isArray(session)) {
+        throw new FlowError("INTERNAL_STATE", "projection verdict is missing its session envelope");
+    }
+    const record = {
+        status: facts.state === "completed"
+            ? "completed"
+            : facts.state === "dismissed"
+                ? "dismissed"
+                : "failed",
+        finalMessage,
+        output: typeof facts.output === "string" ? facts.output : "",
+        diagnostics: typeof facts.diagnostics === "string" ? facts.diagnostics : "",
+        session: session,
+        warnings: Array.isArray(facts.warnings)
+            ? facts.warnings
+            : [],
+        ...(facts.error && typeof facts.error === "object" && !Array.isArray(facts.error)
+            ? { error: facts.error }
+            : {}),
+    };
+    return restoreOutcome(record);
+}
+async function executeSubagent(agentName, prompt, cwd, options) {
+    const { projection: projectionCoordinate, launchSnapshot } = await buildCallConfig(agentName, prompt, cwd, options);
+    if (!projectionCoordinate) {
+        throw new FlowError("INTERNAL_STATE", "durable execution requires a projection coordinate");
+    }
+    const launched = await startProjectionGeneration(projectionCoordinate.dir, projectionCoordinate.executionId);
+    if (launched.status === "failed") {
+        throw new FlowError("SUBAGENT_EXEC_ERROR", launched.detail);
+    }
+    const joined = await waitForProjection({
+        projectionDirectory: projectionCoordinate.dir,
+        signal: options.signal,
+    });
+    if (joined.state !== "terminal") {
+        throw new FlowError("INTERNAL_STATE", "durable execution ended without a terminal generation");
+    }
+    const current = readCurrentGenerationOrThrow(projectionCoordinate.dir);
+    const providerOutcome = outcomeFromGeneration(current);
+    const outcome = {
+        status: providerOutcome.status,
+        finalMessage: providerOutcome.finalMessage,
+        output: providerOutcome.output,
+        diagnostics: providerOutcome.diagnostics,
+        session: providerOutcome.session,
+        warnings: providerOutcome.warnings,
+        ...(providerOutcome.error ? { error: providerOutcome.error } : {}),
+        launchSnapshot,
+    };
+    const completionFacts = current.verdict?.facts;
+    switch (outcome.status) {
+        case "completed":
+            return { outcome, projection: projectionCoordinate, ...(completionFacts ? { completionFacts } : {}) };
+        case "dismissed":
+            throw createAbortError("subagent exec cancelled by client");
+        case "failed": {
+            const error = outcome.error;
+            if (!error) {
+                throw new FlowError("SUBAGENT_EXEC_ERROR", "Subagent exec failed without an error payload.");
+            }
+            throw new FlowError(error.code, error.message, {
+                cause: new SubagentFailure(error.code, error.message, {
+                    timeoutMs: error.timeoutMs,
+                    exitCode: error.exitCode,
+                    output: outcome.output,
+                    diagnostics: outcome.diagnostics,
+                }),
+            });
+        }
+    }
+    throw new FlowError("INTERNAL_STATE", "Unhandled subagent outcome state.");
+}
+async function launchSubagentGeneration(agentName, prompt, cwd, options) {
+    const { projection, launchSnapshot } = await buildCallConfig(agentName, prompt, cwd, options);
+    if (!projection) {
+        throw new FlowError("INTERNAL_STATE", "durable launch requires a projection coordinate");
+    }
+    const launched = await startProjectionGeneration(projection.dir, projection.executionId);
+    if (launched.status === "failed") {
+        throw new FlowError("SUBAGENT_EXEC_ERROR", launched.detail);
+    }
+    return { projection, launchSnapshot };
+}
+async function buildCallConfig(agentName, prompt, cwd, options) {
+    const launchSnapshot = options.launchSnapshot ?? resolveAkumaLaunchSnapshot(await selectSubagentV2(agentName, cwd), {
+        executionCwd: cwd,
+        projectRoot: cwd,
+        ...(options.model !== undefined ? { model: options.model } : {}),
+        ...(options.effort !== undefined ? { effort: options.effort } : {}),
+    });
+    const resolvedTerms = buildCallTermsV2(launchSnapshot, prompt, cwd, {
+        signal: options.signal,
+        idleTimeoutMs: options.idleTimeoutMs,
+    });
+    // Mint projection directory for supervisor pump.
+    const slug = launchSnapshot.akuma.name.replace(/[^a-zA-Z0-9_-]/g, "-").toLowerCase();
+    const publishProjection = async () => {
+        const mintInput = {
+            cwd: options.projectionCwd ?? cwd,
+            workspaceRoot: cwd,
+            slug,
+            pid: process.pid,
+            akuma: launchSnapshot.akuma.name,
+            provider: launchSnapshot.provider.kind,
+            binding: options.binding,
+            effectivePolicy: launchSnapshot.akuma.policy,
+            nowMs: Date.now(),
+        };
+        const minted = options.authority.kind === "repository"
+            ? await mintRepositoryProjection({ ...mintInput, authority: { kind: "repository" } })
+            : mintProjection({ ...mintInput, authority: { kind: "user" } });
+        const executionId = createProjectionExecutionId();
+        const launchFacts = JSON.parse(JSON.stringify({
+            executionId,
+            createdAt: new Date().toISOString(),
+            launchedBy: "call",
+            inputs: {
+                prompt,
+                task: options.task ?? prompt,
+                launchSnapshot,
+                idleTimeoutMs: resolvedTerms.idleTimeoutMs,
+                cwd,
+                historyCwd: options.historyStorageCwd ?? cwd,
+                ...(options.evidenceCwd !== undefined ? { evidenceCwd: options.evidenceCwd } : {}),
+                ...(options.title !== undefined ? { title: options.title } : {}),
+                ...(options.context !== undefined ? { context: options.context } : {}),
+                persistProjectionResponse: options.persistProjectionResponse ?? false,
+                ...(options.continuation ? {
+                    session: options.continuation.session,
+                    resumePath: options.continuation.resumePath,
+                } : {}),
+            },
+        }));
+        const store = openProjectionGenerationStore(minted.dir);
+        try {
+            const launch = store.launchIfSettled({ executionId, facts: launchFacts });
+            if (launch.status !== "committed") {
+                throw new FlowError("INTERNAL_STATE", `initial generation launch rejected: ${launch.reason}`);
+            }
+        }
+        finally {
+            store.close();
+        }
+        return { id: minted.id, dir: minted.dir, executionId };
+    };
+    // Every public launch has one durable projection object. Repository-free
+    // authority changes the storage owner, not whether the object exists; mint
+    // failure is therefore a launch failure rather than an in-process fallback.
+    const projectionCoordinate = await publishProjection();
+    const terms = buildCallTermsV2(launchSnapshot, prompt, cwd, {
+        signal: options.signal,
+        idleTimeoutMs: resolvedTerms.idleTimeoutMs,
+        projectionDir: projectionCoordinate.dir,
+        projectionExecutionId: projectionCoordinate.executionId,
+    });
+    return {
+        terms,
+        projection: projectionCoordinate,
+        launchSnapshot,
+    };
+}
+export async function runCall(input) {
+    const { signal, agent } = input;
+    const reviveArtifact = input.reviveArtifact ? requireResumableArtifact(input.reviveArtifact) : undefined;
+    let rawCwd = input.cwd;
+    let rawRepo = input.repo;
+    if (reviveArtifact?.provenance.authority.kind === "user") {
+        if (!("workdir" in reviveArtifact.provenance.evidence)) {
+            throw new FlowError("INVALID_RESPONSE_PATH", `Invalid response artifact '${reviveArtifact.artifactId}': field 'provenance.evidence.workdir' is missing.`);
+        }
+        rawCwd = reviveArtifact.provenance.evidence.workdir;
+        rawRepo = undefined;
+    }
+    else if (reviveArtifact?.provenance.authority.kind === "repository") {
+        const artifactHome = await fs.realpath(reviveArtifact.storageRoot);
+        const addressed = input.repo ?? input.cwd;
+        if (await isGitRepo(addressed)) {
+            const addressedRoot = await stableRepoRoot(addressed);
+            if (addressedRoot !== artifactHome) {
+                throw new FlowError("INVALID_RESPONSE_PATH", `Response artifact '${reviveArtifact.artifactId}' belongs to ${artifactHome}, but the addressed repository is ${addressedRoot}.`);
+            }
+        }
+        rawCwd = artifactHome;
+        rawRepo = artifactHome;
+    }
+    const cwd = await fs.realpath(rawCwd);
+    const repoCwd = rawRepo ? await fs.realpath(rawRepo) : undefined;
+    const title = requireText("title", input.title);
+    const task = requireText("task", input.task);
+    if (input.incognito && reviveArtifact) {
+        throw new FlowError("EMPTY_PARAM", "Parameter 'incognito' cannot be used with 'reviveArtifact' — incognito calls cannot be revived or persist conversation history.");
+    }
+    const keiyakuContext = await readCallKeiyakuContext(cwd, {
+        bare: input.bare,
+        contractId: input.contractId,
+        contractAddressSource: input.contractAddressSource,
+        mode: input.mode ?? "call",
+        repoCwd,
+        reviveBinding: reviveArtifact?.provenance.binding,
+    });
+    return await withResolvedAddress(keiyakuContext.address, async () => {
+        const executionCwd = keiyakuContext.effectiveCwd;
+        const referenceFiles = await collectCallReferenceFiles(executionCwd, keiyakuContext);
+        const prompt = buildCallPrompt({
+            task,
+            context: input.context,
+            referenceFiles,
+            arc: keiyakuContext.openArc,
+        });
+        const launchSnapshot = reviveArtifact
+            ? input.effort !== undefined
+                ? applySnapshotEffort(reviveArtifact.launchSnapshot, input.effort)
+                : reviveArtifact.launchSnapshot
+            : resolveAkumaLaunchSnapshot(await selectSubagentV2(agent, keiyakuContext.profileCwd), {
+                executionCwd,
+                projectRoot: keiyakuContext.profileCwd,
+                ...(input.model !== undefined ? { model: input.model } : {}),
+                ...(input.effort !== undefined ? { effort: input.effort } : {}),
+            });
+        const continuation = reviveArtifact
+            ? { session: reviveArtifact.session, resumePath: reviveArtifact.absolutePath }
+            : undefined;
+        logInfo(`[${ACTOR_IDENTITY}] Running execution for '${launchSnapshot.akuma.name}' in ${executionCwd}`, {
+            cwd: executionCwd,
+            section: "script",
+            progressOnly: true,
+        });
+        // Storage coordinate: addressed repository stable root / caller cwd.
+        // Evidence coordinate: commission worktree for bound runs; execution cwd otherwise.
+        const historyStorageCwd = keiyakuContext.historyCwd;
+        const evidenceCwd = executionCwd;
+        const executionOptions = {
+            signal,
+            continuation,
+            task,
+            launchSnapshot,
+            persistProjectionResponse: !input.incognito,
+            historyStorageCwd,
+            evidenceCwd,
+            projectionCwd: keiyakuContext.projectionCwd,
+            authority: keiyakuContext.address.repo.kind === "repository"
+                ? { kind: "repository" }
+                : { kind: "user" },
+            binding: keiyakuContext.address.binding,
+            title,
+            context: input.context,
+        };
+        if ((input.mode ?? "call") === "call") {
+            const launched = await launchSubagentGeneration(launchSnapshot.akuma.name, prompt, executionCwd, executionOptions);
+            const adoptedProjection = {
+                id: launched.projection.id,
+                phase: observeProjectionLife(launched.projection.dir, {
+                    nowMs: Date.now(),
+                    startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS,
+                }).phase,
+            };
+            input.onLaunch?.({ address: keiyakuContext.address, projection: adoptedProjection });
+            if (input.detach) {
+                return {
+                    state: "launched",
+                    summary: "",
+                    agent: launchSnapshot.akuma.name,
+                    launchSnapshot,
+                    projectionOwnsResponsePersistence: true,
+                    projection: adoptedProjection,
+                    address: keiyakuContext.address,
+                };
+            }
+            const joined = await waitForProjection({
+                projectionDirectory: launched.projection.dir,
+                signal,
+            });
+            if (joined.state !== "terminal") {
+                throw new FlowError("INTERNAL_STATE", "foreground call wait ended without a terminal projection verdict");
+            }
+            return {
+                state: "completed",
+                summary: joined.outcomeText || `${ACTOR_IDENTITY} completed successfully.`,
+                agent: launchSnapshot.akuma.name,
+                launchSnapshot,
+                ...(joined.snapshot.responsePath ? { responsePath: joined.snapshot.responsePath } : {}),
+                ...(joined.snapshot.artifactId ? { artifactId: joined.snapshot.artifactId } : {}),
+                projectionOwnsResponsePersistence: true,
+                meta: { effectivePolicy: launchSnapshot.akuma.policy },
+                projection: { id: launched.projection.id, phase: joined.snapshot.phase },
+                foregroundWait: joined,
+                address: keiyakuContext.address,
+            };
+        }
+        const execution = await executeSubagent(launchSnapshot.akuma.name, prompt, executionCwd, executionOptions);
+        const subagentOutcome = execution.outcome;
+        if (subagentOutcome.diagnostics.trim()) {
+            appendDebugBlock("subagent diagnostics", subagentOutcome.diagnostics, { cwd: executionCwd, section: "subagent-stderr" });
+        }
+        let projection;
+        let responsePath;
+        let artifactId;
+        if (execution.projection) {
+            responsePath = typeof execution.completionFacts?.responsePath === "string"
+                ? execution.completionFacts.responsePath
+                : undefined;
+            artifactId = typeof execution.completionFacts?.artifactId === "string"
+                ? execution.completionFacts.artifactId
+                : undefined;
+            try {
+                projection = {
+                    id: execution.projection.id,
+                    phase: observeProjectionLife(execution.projection.dir, {
+                        nowMs: Date.now(),
+                        startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS,
+                    }).phase,
+                };
+            }
+            catch {
+                // Projection observations are best-effort and must not reverse success.
+            }
+        }
+        return {
+            state: "completed",
+            summary: subagentOutcome.finalMessage || `${ACTOR_IDENTITY} completed successfully.`,
+            agent: launchSnapshot.akuma.name,
+            session: subagentOutcome.session,
+            launchSnapshot: subagentOutcome.launchSnapshot,
+            ...(responsePath ? { responsePath } : {}),
+            ...(artifactId ? { artifactId } : {}),
+            ...(reviveArtifact ? { revivedArtifactId: reviveArtifact.artifactId } : {}),
+            projectionOwnsResponsePersistence: execution.projection !== undefined,
+            meta: {
+                ...(subagentOutcome.warnings.length > 0 ? { warnings: subagentOutcome.warnings.map(renderSubagentWarning) } : {}),
+                effectivePolicy: subagentOutcome.launchSnapshot.akuma.policy,
+            },
+            ...(projection ? { projection } : {}),
+            address: keiyakuContext.address,
+            ...(input.incognito ? {} : { evidenceCwd }),
+        };
+    });
+}