@astrosheep/keiyaku 2.8.4 → 2.9.0

package/build/cli/commands/akuma/list/handler.js

@@ -0,0 +1,15 @@
+import { assertSettingsKnobUsable } from "../../../../config/settings/disease.js";
+import { loadKeiyakuSettings } from "../../../../config/settings/loader.js";
+import { loadAkumaCatalog } from "../../../../config/akuma-loader.js";
+import { textResponse } from "../../../render/shared.js";
+import { projectDirectory } from "../../shared.js";
+import { renderAkumaList } from "../../akuma.js";
+export const handler = async (_stdin, flags) => {
+    const cwd = await projectDirectory(flags);
+    const loaded = await loadKeiyakuSettings(cwd);
+    // Role markers need settings pointers; catalog consumers keep legacy agents disease actionable.
+    assertSettingsKnobUsable(loaded, "agents");
+    assertSettingsKnobUsable(loaded, "default");
+    assertSettingsKnobUsable(loaded, "reviewer");
+    return textResponse(renderAkumaList(await loadAkumaCatalog(cwd), loaded.providerInstances, loaded.knobs));
+};

package/build/cli/commands/akuma/list/meta-ls.js

@@ -0,0 +1,9 @@
+export const meta = {
+    command: "akuma ls",
+    summary: "List Akuma profiles",
+    usage: ["keiyaku akuma ls [-C|--cwd DIR] [--repo DIR]"],
+    stdin: "none",
+    flags: ["cwd", "repo"],
+    purpose: "List configured helper profiles.",
+    notes: ["Project profiles override user profiles, which override builtins."],
+};

package/build/cli/commands/akuma/view/handler.js

@@ -0,0 +1,34 @@
+import { FlowError } from "../../../../flow-error.js";
+import { assertSettingsKnobUsable } from "../../../../config/settings/disease.js";
+import { loadKeiyakuSettings } from "../../../../config/settings/loader.js";
+import { loadAkumaCatalog } from "../../../../config/akuma-loader.js";
+import { readProjectionStatusBoard } from "../../../../core/projection-status.js";
+import { isResponseArtifactId } from "../../../../core/response-artifact-id.js";
+import { textResponse } from "../../../render/shared.js";
+import { renderProjectionStatusSection } from "../../../render/status.js";
+import { projectDirectory } from "../../shared.js";
+import { renderAkumaShow } from "../../akuma.js";
+const NONTERMINAL_PROJECTION_STATES = new Set([
+    "minting",
+    "startup-timeout",
+    "unknown",
+    "out",
+    "lost",
+]);
+export const handler = async (_stdin, flags, _signal, positional) => {
+    const [name] = positional;
+    if (!name)
+        throw new FlowError("EMPTY_PARAM", "akuma view requires an Akuma name");
+    if (isResponseArtifactId(name)) {
+        throw new FlowError("EMPTY_PARAM", `artifact ${name} is a response artifact; akuma view expects an Akuma profile name`);
+    }
+    const cwd = await projectDirectory(flags);
+    const loaded = await loadKeiyakuSettings(cwd);
+    assertSettingsKnobUsable(loaded, "agents");
+    assertSettingsKnobUsable(loaded, "default");
+    assertSettingsKnobUsable(loaded, "reviewer");
+    const profile = renderAkumaShow(await loadAkumaCatalog(cwd), loaded.providerInstances, loaded.knobs, name).trimEnd();
+    const rows = (readProjectionStatusBoard(cwd, Date.now(), { showAll: true })?.rows ?? []).filter((row) => row.akuma === name && NONTERMINAL_PROJECTION_STATES.has(row.state));
+    const projections = renderProjectionStatusSection({ rows }).trimEnd();
+    return textResponse(projections ? `${profile}\n\n${projections}` : profile);
+};

package/build/cli/commands/akuma/view/meta.js

@@ -0,0 +1,8 @@
+export const meta = {
+    command: "akuma view",
+    summary: "View one Akuma profile",
+    usage: ["keiyaku akuma view NAME [-C|--cwd DIR] [--repo DIR]"],
+    stdin: "none",
+    flags: ["cwd", "repo"],
+    purpose: "Read one configured helper profile and its current nonterminal projections.",
+};

package/build/cli/commands/akuma.js

@@ -1,4 +1,4 @@
-import { resolveDefaultAgentName, resolveReviewerAgentName, } from "../../config/settings.js";
+import { resolveDefaultAgentName, resolveReviewerAgentName } from "../../config/settings/knobs.js";
 import { FlowError } from "../../flow-error.js";
 import { nativePolicyOwnership } from "../../config/provider-policy-ownership.js";
 function formatRoleMarkers(settings, name) {

package/build/cli/commands/contract/amend/handler.js

@@ -0,0 +1,10 @@
+import { amendKeiyaku } from "../../../../core/amend.js";
+import { buildAmendInput } from "../../../../core/command-io.js";
+import { buildAmendResponse } from "../../../render/arc.js";
+import { renderCoreResult } from "../../../render/shared.js";
+import { effectiveDirectory, repositoryDirectory } from "../../shared.js";
+export const handler = async (stdin, flags) => {
+    const parsed = buildAmendInput(stdin, effectiveDirectory(flags), flags.contractId, flags.contractAddressSource);
+    const cwd = await repositoryDirectory(flags);
+    return renderCoreResult(amendKeiyaku({ ...parsed, cwd }), buildAmendResponse);
+};

package/build/cli/commands/contract/amend/meta.js

@@ -0,0 +1,12 @@
+export const meta = {
+    command: "amend",
+    summary: "Record an amendment",
+    usage: [
+        "keiyaku amend [-C|--cwd DIR] [--repo DIR] [--contract ADDR] < amendment.md",
+        "keiyaku @addr amend [-C|--cwd DIR] [--repo DIR] < amendment.md",
+    ],
+    stdin: "required",
+    flags: ["cwd", "repo", "contract"],
+    purpose: "Append a prose amendment and optional structured scope delta.",
+    completionRank: 8,
+};

package/build/cli/commands/contract/arc/handler.js

@@ -0,0 +1,9 @@
+import { arcKeiyaku, buildArcInput } from "../../../../core/arc.js";
+import { buildArcResponse } from "../../../render/arc.js";
+import { renderCoreResult } from "../../../render/shared.js";
+import { effectiveDirectory, repositoryDirectory } from "../../shared.js";
+export const handler = async (stdin, flags) => {
+    const parsed = buildArcInput(stdin, effectiveDirectory(flags), flags.waivePaths, flags.contractId, flags.contractAddressSource);
+    const cwd = await repositoryDirectory(flags);
+    return renderCoreResult(arcKeiyaku({ ...parsed, cwd }), buildArcResponse);
+};

package/build/cli/commands/contract/arc/meta.js

@@ -0,0 +1,26 @@
+export const meta = {
+    command: "arc",
+    summary: "Optional iteration; seals current intent first",
+    usage: [
+        "keiyaku arc [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--waive PATH] < arc.md",
+        "keiyaku @addr arc [-C|--cwd DIR] [--repo DIR] [--waive PATH] < arc.md",
+    ],
+    stdin: "required",
+    flags: ["cwd", "repo", "contract", "waive"],
+    purpose: "Optional iteration boundary: record the next title, objective, and brief, and seal the current intent first.",
+    input: [
+        "# <arc title>",
+        "",
+        "## Objective",
+        "<what this arc should accomplish>",
+        "",
+        "## Brief",
+        "<scope, constraints, relevant files, instructions>",
+    ],
+    notes: [
+        "An empty seal is valid.",
+        "The command does not create delivery commits.",
+        "The first explicit arc seals a0; later arcs seal the previous open explicit arc.",
+    ],
+    completionRank: 1,
+};

package/build/cli/commands/contract/bind/handler.js

@@ -0,0 +1,23 @@
+import { bindContract } from "../../../../core/bind.js";
+import { defaultActorClock } from "../../../../core/command-io.js";
+import { writeDraftArtifact } from "../../../draft-artifact.js";
+import { buildBindDraftResponse, buildBindResponse, textResponse } from "../../../render/shared.js";
+import { repositoryDirectory } from "../../shared.js";
+export const handler = async (stdin, flags) => {
+    if (flags.dryRun) {
+        return textResponse(stdin);
+    }
+    const cwd = await repositoryDirectory(flags);
+    if (flags.draftOnly) {
+        return buildBindDraftResponse(await writeDraftArtifact({ cwd, title: "bind-draft", content: stdin }));
+    }
+    const result = await bindContract({
+        cwd, draft: stdin, ...defaultActorClock(), workspace: "worktree",
+        after: flags.after ?? [], exclusive: flags.exclusive,
+        ...(flags.bindTaskId === undefined ? {} : { taskId: flags.bindTaskId }),
+        onProgress: (line) => {
+            process.stdout.write(`${line}\n`);
+        },
+    });
+    return buildBindResponse(result, cwd);
+};

package/build/cli/commands/contract/bind/meta.js

@@ -0,0 +1,30 @@
+export const meta = {
+    command: "bind",
+    summary: "Create a contract ledger and workspace files",
+    usage: [
+        "keiyaku bind [-C|--cwd DIR] [--repo DIR] [--task ID] < keiyaku.md",
+        "keiyaku bind [-C|--cwd DIR] [--repo DIR] [--task ID] --place NAME --objective TEXT --scope GLOB --checks CHECK [--dry-run]",
+    ],
+    stdin: "optional",
+    flags: ["cwd", "repo", "after", "exclusive", "draft-only", "place", "objective", "scope", "checks", "task", "dry-run"],
+    // contract is parseable only so the mouth can reject it with bind-specific copy.
+    parseFlags: ["cwd", "repo", "contract", "after", "exclusive", "draft-only", "place", "objective", "scope", "checks", "task", "dry-run"],
+    purpose: "Bind a Keiyaku from a contract draft.",
+    input: [
+        "# <name>",
+        "",
+        "## Objective",
+        "<what the commission should accomplish>",
+        "",
+        "## Scope",
+        "- <glob>",
+        "",
+        "## Checks",
+        "- <acceptance check>",
+    ],
+    notes: [
+        "bind creates a commission and does not accept @addr or --contract.",
+        "Use either stdin Markdown or all four domain flags; they cannot be combined.",
+    ],
+    completionRank: 0,
+};

package/build/cli/commands/contract/catalog.js

@@ -0,0 +1,16 @@
+import { meta as bindMeta } from "./bind/meta.js";
+import { meta as arcMeta } from "./arc/meta.js";
+import { meta as logMeta } from "./log/meta.js";
+import { meta as amendMeta } from "./amend/meta.js";
+import { meta as renewMeta } from "./renew/meta.js";
+import { meta as petitionMeta } from "./petition/meta.js";
+import { meta as forfeitMeta } from "./forfeit/meta.js";
+export const contractCatalog = [
+    { meta: bindMeta, load: () => import("./bind/handler.js") },
+    { meta: arcMeta, load: () => import("./arc/handler.js") },
+    { meta: logMeta, load: () => import("./log/handler.js") },
+    { meta: amendMeta, load: () => import("./amend/handler.js") },
+    { meta: renewMeta, load: () => import("./renew/handler.js") },
+    { meta: petitionMeta, load: () => import("./petition/handler.js") },
+    { meta: forfeitMeta, load: () => import("./forfeit/handler.js") },
+];

package/build/cli/commands/contract/forfeit/handler.js

@@ -0,0 +1,13 @@
+import { resolveContractAddress, withResolvedAddress } from "../../../../core/addressing.js";
+import { defaultActorClock } from "../../../../core/command-io.js";
+import { forfeitContractCommand } from "../../../../core/forfeit.js";
+import { buildForfeitResponse } from "../../../render/shared.js";
+import { repositoryDirectory } from "../../shared.js";
+export const handler = async (_stdin, flags) => {
+    const cwd = await repositoryDirectory(flags);
+    const address = await resolveContractAddress(cwd, flags.contractId, flags.contractAddressSource);
+    return await withResolvedAddress(address, async () => buildForfeitResponse({
+        ...await forfeitContractCommand({ cwd, contractId: address.binding.commissionId, ...defaultActorClock(), note: flags.reason }),
+        address,
+    }));
+};

package/build/cli/commands/contract/forfeit/meta.js

@@ -0,0 +1,12 @@
+export const meta = {
+    command: "forfeit",
+    summary: "Forfeit an addressed contract",
+    usage: [
+        "keiyaku forfeit [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--reason TEXT]",
+        "keiyaku @addr forfeit [-C|--cwd DIR] [--repo DIR] [--reason TEXT]",
+    ],
+    stdin: "none",
+    flags: ["cwd", "repo", "contract", "reason"],
+    purpose: "Record an abandoned contract without sealing it.",
+    completionRank: 11,
+};

package/build/cli/commands/contract/log/handler.js

@@ -0,0 +1,12 @@
+import { resolveContractAddress, withResolvedAddress } from "../../../../core/addressing.js";
+import { readContractLog } from "../../../../core/log.js";
+import { buildLogResponse } from "../../../render/misc.js";
+import { repositoryDirectory } from "../../shared.js";
+export const handler = async (_stdin, flags) => {
+    const cwd = await repositoryDirectory(flags);
+    const address = await resolveContractAddress(cwd, flags.contractId, flags.contractAddressSource);
+    return await withResolvedAddress(address, async () => {
+        const result = await readContractLog({ cwd, contractId: address.binding.commissionId });
+        return buildLogResponse({ ...result, address });
+    });
+};

package/build/cli/commands/contract/log/meta.js

@@ -0,0 +1,12 @@
+export const meta = {
+    command: "log",
+    summary: "Render a contract ledger",
+    usage: [
+        "keiyaku log [-C|--cwd DIR] [--repo DIR] [--contract ADDR]",
+        "keiyaku @addr log [-C|--cwd DIR] [--repo DIR]",
+    ],
+    stdin: "none",
+    flags: ["cwd", "repo", "contract"],
+    purpose: "Read a contract ledger.",
+    completionRank: 5,
+};

package/build/cli/commands/contract/petition/handler.js

@@ -0,0 +1,26 @@
+import { FlowError } from "../../../../flow-error.js";
+import { resolveContractAddress, withResolvedAddress } from "../../../../core/addressing.js";
+import { buildPetitionClaimInput } from "../../../../core/petition.js";
+import { previewPetition } from "../../../../core/petition-preview.js";
+import { petitionKeiyaku } from "../../../../core/petition-run.js";
+import { buildPetitionClaimResponse, buildPetitionPreviewResponse } from "../../../render/petition.js";
+import { repositoryDirectory } from "../../shared.js";
+export const handler = async (stdin, flags, signal) => {
+    if (flags.json && !flags.dryRun) {
+        throw new FlowError("EMPTY_PARAM", "petition --json requires --dry-run");
+    }
+    const cwd = await repositoryDirectory(flags);
+    const address = await resolveContractAddress(cwd, flags.contractId, flags.contractAddressSource);
+    return await withResolvedAddress(address, async () => {
+        const input = buildPetitionClaimInput({ cwd, contractId: address.binding.commissionId, stdin, signal, waivePaths: flags.waivePaths });
+        if (flags.dryRun) {
+            return buildPetitionPreviewResponse(await previewPetition({
+                cwd,
+                contractId: address.binding.commissionId,
+                oath: input.oath,
+                waivePaths: flags.waivePaths,
+            }), flags.json === true);
+        }
+        return buildPetitionClaimResponse({ ...await petitionKeiyaku(input), address }, input);
+    });
+};

package/build/cli/commands/contract/petition/meta.js

@@ -0,0 +1,23 @@
+export const meta = {
+    command: "petition",
+    summary: "Run or preview the gated settlement pipeline",
+    usage: [
+        "keiyaku petition [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--waive PATH] [< petition.md]",
+        "keiyaku @<id> petition [-C|--cwd DIR] [--repo DIR] [--waive PATH] [< petition.md]",
+        "keiyaku @<id> petition --dry-run [--json] [< petition.md]",
+    ],
+    stdin: "optional",
+    flags: ["cwd", "repo", "contract", "waive", "dry-run", "json"],
+    purpose: "Seal the current a0 or open explicit arc, queue the contract, and run verdict and claim processing; dry-run previews deterministic gates without mutation.",
+    input: [
+        "## Oath",
+        "<free first-person attestation>",
+    ],
+    notes: [
+        "Petition stdin is optional at the command mouth; a missing, empty, or blank oath is rejected by the settlement gate with OATH_MISSING.",
+        "The machine checks only that the oath is present. Accepted oath text is persisted in the petition entry and hidden from the reviewer.",
+        "Base drift requires explicit `keiyaku renew` before petition.",
+        "Dry-run never runs verification or review and exits 0, 1, or 2.",
+    ],
+    completionRank: 10,
+};

package/build/cli/commands/contract/renew/handler.js

@@ -0,0 +1,10 @@
+import { resolveContractAddress } from "../../../../core/addressing.js";
+import { renewKeiyaku } from "../../../../core/renew.js";
+import { buildRenewResponse } from "../../../render/arc.js";
+import { renderCoreResult } from "../../../render/shared.js";
+import { repositoryDirectory } from "../../shared.js";
+export const handler = async (_stdin, flags) => {
+    const cwd = await repositoryDirectory(flags);
+    const address = await resolveContractAddress(cwd, flags.contractId, flags.contractAddressSource);
+    return renderCoreResult(renewKeiyaku({ cwd, address, waivePaths: flags.waivePaths }), buildRenewResponse);
+};

package/build/cli/commands/contract/renew/meta.js

@@ -0,0 +1,17 @@
+export const meta = {
+    command: "renew",
+    summary: "Rewrite delivery onto the current base",
+    usage: [
+        "keiyaku renew [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--waive PATH]",
+        "keiyaku @<id> renew [-C|--cwd DIR] [--repo DIR] [--waive PATH]",
+    ],
+    stdin: "none",
+    flags: ["cwd", "repo", "contract", "waive"],
+    purpose: "Capture receipts, rewrite delivery onto the default branch, then seal the current a0 or open explicit arc and record the renewal.",
+    notes: [
+        "After an explicit arc closes, refuses loose commits until another arc is open.",
+        "Refuses while an Akuma is in flight.",
+        "Conflicts restore the worktree without ledger writes.",
+    ],
+    completionRank: 9,
+};

package/build/cli/commands/projection/call/handler.js

@@ -0,0 +1,39 @@
+import { runCallAndPersist } from "../../../../core/call-persist.js";
+import { projectionDir } from "../../../../core/projection-core.js";
+import { waitForProjection } from "../../../../core/projection-wait.js";
+import { buildCallResponse, renderAdoptedLaunchReceipt } from "../../../render/call.js";
+import { buildWaitResponse } from "../../../render/wait.js";
+import { buildCallInput, projectDirectory } from "../../shared.js";
+export const handler = async (stdin, flags, signal) => {
+    const outcome = await runCallAndPersist({
+        ...buildCallInput(stdin, flags, "call"),
+        // Bounded outer join: same durable launch/adoption as detach, without core's unbounded join.
+        ...(flags.timeoutMs !== undefined ? { detach: true } : {}),
+        signal,
+        ...(!flags.detach
+            ? {
+                onLaunch: ({ address, projection }) => {
+                    process.stdout.write(`${renderAdoptedLaunchReceipt(address, projection.id, projection.alias, projection.previousAliasTarget)}\n`);
+                },
+            }
+            : {}),
+    });
+    if (flags.timeoutMs !== undefined) {
+        const projection = outcome.result.projection;
+        if (!projection)
+            throw new Error("call --wait requires projection facts after launch");
+        return buildWaitResponse(projection.id, await waitForProjection({
+            projectionDirectory: projectionDir(await projectDirectory(flags), projection.id),
+            timeoutMs: flags.timeoutMs,
+            signal,
+        }), { alias: projection.alias });
+    }
+    if (outcome.result.foregroundWait && outcome.result.projection) {
+        return buildWaitResponse(outcome.result.projection.id, outcome.result.foregroundWait, { alias: outcome.result.projection.alias });
+    }
+    return buildCallResponse(outcome.result, {
+        responsePath: outcome.responsePath,
+        artifactId: outcome.artifactId,
+        addressPlacement: flags.detach ? "stdout" : "none",
+    });
+};

package/build/cli/commands/projection/call/meta.js

@@ -0,0 +1,9 @@
+export const meta = {
+    command: "call",
+    summary: "Start an Akuma helper session",
+    usage: ["keiyaku call NAME [--wait DURATION] <BODY|->"],
+    stdin: "none",
+    flags: ["cwd", "repo", "contract", "akuma", "model", "effort", "incognito", "bare", "detach", "alias", "wait"],
+    purpose: "Run a scoped helper task.",
+    completionRank: 2,
+};

package/build/cli/commands/projection/catalog.js

@@ -0,0 +1,14 @@
+import { meta as callMeta } from "./call/meta.js";
+import { meta as reviveMeta } from "./revive/meta.js";
+import { meta as waitMeta } from "./wait/meta.js";
+import { meta as tellMeta } from "./tell/meta.js";
+import { meta as killMeta } from "./kill/meta.js";
+import { meta as statusMeta } from "./status/meta.js";
+export const projectionCatalog = [
+    { meta: callMeta, load: () => import("./call/handler.js") },
+    { meta: reviveMeta, load: () => import("./revive/handler.js") },
+    { meta: waitMeta, load: () => import("./wait/handler.js") },
+    { meta: tellMeta, load: () => import("./tell/handler.js") },
+    { meta: killMeta, load: () => import("./kill/handler.js") },
+    { meta: statusMeta, load: () => import("./status/handler.js") },
+];

package/build/cli/commands/projection/kill/handler.js

@@ -0,0 +1,35 @@
+import { FlowError } from "../../../../flow-error.js";
+import { resolveContractAddress, withResolvedAddress, } from "../../../../core/addressing.js";
+import { projectionDir } from "../../../../core/projection-core.js";
+import { killProjectionGeneration } from "../../../../core/projection-kill.js";
+import { waitForProjection } from "../../../../core/projection-wait.js";
+import { resolveProjectionAddress } from "../../../projection-address.js";
+import { textResponse } from "../../../render/shared.js";
+import { buildWaitResponse } from "../../../render/wait.js";
+import { projectDirectory, repositoryDirectory } from "../../shared.js";
+export const handler = async (_stdin, flags, signal, positional) => {
+    const cwd = flags.contractId ? await repositoryDirectory(flags) : await projectDirectory(flags);
+    const [projectionAddress] = positional;
+    if (!projectionAddress)
+        throw new FlowError("EMPTY_PARAM", "kill requires a projection address");
+    const address = flags.contractId ? await resolveContractAddress(cwd, flags.contractId, flags.contractAddressSource) : undefined;
+    const operation = async () => {
+        const projection = await resolveProjectionAddress({
+            cwd,
+            address: projectionAddress,
+            scope: address,
+            verb: "kill",
+        });
+        const directory = projectionDir(cwd, projection.id);
+        const result = killProjectionGeneration(directory);
+        if (result.status === "already-closed") {
+            return textResponse(`· ${projection.id} already closed`);
+        }
+        if (flags.timeoutMs === undefined) {
+            return textResponse(`✓ kill ${projection.id}\n» keiyaku wait ${projection.id}`);
+        }
+        // Accepted with --wait: no acceptance receipt or address preamble.
+        return buildWaitResponse(projection.id, await waitForProjection({ projectionDirectory: directory, timeoutMs: flags.timeoutMs, signal }), { alias: projection.alias });
+    };
+    return address ? await withResolvedAddress(address, operation) : await operation();
+};

package/build/cli/commands/projection/kill/meta.js

@@ -0,0 +1,11 @@
+export const meta = {
+    command: "kill",
+    summary: "Stop the current projection generation",
+    usage: [
+        "keiyaku kill <projection-address> [--wait DURATION]",
+        "keiyaku @addr kill <projection-address> [--wait DURATION]",
+    ],
+    stdin: "none",
+    flags: ["cwd", "repo", "contract", "wait"],
+    purpose: "Terminate the current generation while keeping the projection identity and tell ledger.",
+};

package/build/cli/commands/projection/revive/handler.js

@@ -0,0 +1,53 @@
+import * as fs from "node:fs/promises";
+import { FlowError } from "../../../../flow-error.js";
+import { buildArtifactResolutionAttempt, } from "../../../../core/addressing.js";
+import { runCallAndPersist } from "../../../../core/call-persist.js";
+import { locateResponseArtifact, reconcileResponseArtifactCatalog, } from "../../../../core/transcripts.js";
+import { isGitRepo } from "../../../../git/branches.js";
+import { stableRepoRoot } from "../../../../core/worktree-path.js";
+import { buildCallResponse } from "../../../render/call.js";
+import { buildCallInput, effectiveDirectory, projectDirectory, revivePrompt } from "../../shared.js";
+export const handler = async (stdin, flags, signal, positional) => {
+    const cwd = effectiveDirectory(flags);
+    const artifactCwd = await projectDirectory(flags);
+    const artifactId = positional[0];
+    const isRepo = await isGitRepo(artifactCwd);
+    const responseStoreCwd = isRepo ? await stableRepoRoot(artifactCwd) : await fs.realpath(artifactCwd);
+    try {
+        await reconcileResponseArtifactCatalog(responseStoreCwd);
+    }
+    catch {
+        // The catalog is disposable and cannot make an otherwise valid revive fail.
+    }
+    const artifact = await locateResponseArtifact({
+        cwd: responseStoreCwd,
+        artifactId,
+        attempt: buildArtifactResolutionAttempt({
+            repo: isRepo
+                ? { kind: "repository", stableRoot: responseStoreCwd }
+                : { kind: "user" },
+            workdir: cwd,
+            supplied: artifactId,
+            inference: ["response artifact identity lookup"],
+        }),
+    });
+    let executionCwd;
+    let repo;
+    if (artifact.provenance.authority.kind === "repository") {
+        executionCwd = artifact.storageRoot;
+        repo = flags.repo ? responseStoreCwd : undefined;
+    }
+    else {
+        if (!("workdir" in artifact.provenance.evidence)) {
+            throw new FlowError("INVALID_RESPONSE_PATH", `Invalid response artifact '${artifactId}': field 'provenance.evidence.workdir' is missing.`);
+        }
+        executionCwd = artifact.provenance.evidence.workdir;
+        repo = undefined;
+    }
+    const outcome = await runCallAndPersist({
+        ...buildCallInput(revivePrompt(stdin), { ...flags, cwd: executionCwd, repo }, "revive"),
+        reviveArtifact: artifact,
+        signal,
+    });
+    return buildCallResponse(outcome.result, { responsePath: outcome.responsePath, artifactId: outcome.artifactId, addressPlacement: "footer" });
+};

package/build/cli/commands/projection/revive/meta.js

@@ -0,0 +1,9 @@
+export const meta = {
+    command: "revive",
+    summary: "Revive an Akuma helper session",
+    usage: ["keiyaku revive ARTIFACT [BODY|-]"],
+    stdin: "none",
+    flags: ["cwd", "repo", "model", "effort"],
+    purpose: "Continue a persisted helper session.",
+    completionRank: 4,
+};

package/build/cli/commands/projection/status/handler.js

@@ -0,0 +1,23 @@
+import { readKanshiBoard } from "../../../../core/status/board.js";
+import { normalizeTargetRef } from "../../../../core/target-ref.js";
+import { isProjectionId } from "../../../../core/projection-core.js";
+import { FlowError } from "../../../../flow-error.js";
+import { renderProjectionFilteredStatus, renderStatusBoard } from "../../../render/status.js";
+import { textResponse } from "../../../render/shared.js";
+import { projectDirectory } from "../../shared.js";
+export const handler = async (_stdin, flags, _signal, positional) => {
+    // Status is read-only and must open outside Git. projectDirectory still
+    // honors --repo as a repository coordinate when the operator names one.
+    const cwd = await projectDirectory(flags);
+    const target = flags.target === undefined ? undefined : normalizeTargetRef(flags.target);
+    const board = await readKanshiBoard(cwd, Date.now(), {
+        ...(target === undefined ? {} : { target }),
+        showAllProjections: flags.all === true || positional.length === 1,
+    });
+    const [projectionId] = positional;
+    if (projectionId === undefined)
+        return textResponse(renderStatusBoard(board));
+    if (!isProjectionId(projectionId))
+        throw new FlowError("EMPTY_PARAM", `invalid projection id: ${projectionId}`);
+    return textResponse(renderProjectionFilteredStatus(board, projectionId));
+};

package/build/cli/commands/projection/status/meta.js

@@ -0,0 +1,9 @@
+export const meta = {
+    command: "status",
+    summary: "Show the Kanshi board",
+    usage: ["keiyaku status [PROJECTION] [-C|--cwd DIR] [--repo DIR] [--target REF] [--all]"],
+    stdin: "none",
+    flags: ["cwd", "repo", "target", "all"],
+    purpose: "Read the Kanshi board or filter it to one projection without mutation.",
+    completionRank: 14,
+};

package/build/cli/commands/projection/tell/handler.js

@@ -0,0 +1,34 @@
+import { FlowError } from "../../../../flow-error.js";
+import { resolveContractAddress, withResolvedAddress, } from "../../../../core/addressing.js";
+import { projectionDir, writeInboxTell } from "../../../../core/projection-core.js";
+import { assertTellEffortSupported, tellProjection } from "../../../../core/projection-wake.js";
+import { waitForProjection } from "../../../../core/projection-wait.js";
+import { resolveProjectionAddress } from "../../../projection-address.js";
+import { prependAddressReceipt } from "../../../render/address.js";
+import { textResponse } from "../../../render/shared.js";
+import { buildWaitResponse } from "../../../render/wait.js";
+import { projectDirectory, repositoryDirectory } from "../../shared.js";
+export const handler = async (body, flags, signal, positional) => {
+    const cwd = flags.contractId ? await repositoryDirectory(flags) : await projectDirectory(flags);
+    const projectionAddress = positional[0];
+    if (!projectionAddress)
+        throw new FlowError("EMPTY_PARAM", "tell requires a projection address and message");
+    const address = flags.contractId ? await resolveContractAddress(cwd, flags.contractId, flags.contractAddressSource) : undefined;
+    const operation = async () => {
+        const projection = await resolveProjectionAddress({
+            cwd,
+            address: projectionAddress,
+            scope: address,
+            verb: "tell",
+        });
+        const directory = projectionDir(cwd, projection.id);
+        assertTellEffortSupported(directory, flags.effort);
+        // Mailbox first: do not inspect phase before this immutable write.
+        writeInboxTell(directory, body, Date.now(), { effort: flags.effort });
+        await tellProjection(directory, flags.effort);
+        if (flags.timeoutMs === undefined)
+            return textResponse("");
+        return prependAddressReceipt(buildWaitResponse(projection.id, await waitForProjection({ projectionDirectory: directory, timeoutMs: flags.timeoutMs, signal }), { alias: projection.alias }), address, { projectionId: projection.id, projectionAlias: projection.alias });
+    };
+    return address ? await withResolvedAddress(address, operation) : await operation();
+};

package/build/cli/commands/projection/tell/meta.js

@@ -0,0 +1,9 @@
+export const meta = {
+    command: "tell",
+    summary: "Send intent to a projection mailbox",
+    usage: ["keiyaku tell PROJECTION [--wait DURATION] [--] <BODY|->"],
+    stdin: "none",
+    flags: ["cwd", "repo", "contract", "effort", "wait"],
+    purpose: "Write intent to the mailbox and wake only when eligible.",
+    completionRank: 3,
+};