@astrosheep/keiyaku 2.9.6 → 2.9.8

package/build/agents/harness/event-persistence.js

@@ -1,4 +1,4 @@
-import { AGENT_ACTIVITY_MAX_CHANGES, AGENT_EVENT_TEXT_MAX_CHARS, AGENT_UNKNOWN_PAYLOAD_MAX_CHARS, } from "./events.js";
+import { AGENT_ACTIVITY_MAX_CHANGES, AGENT_DONE_FINAL_MESSAGE_PERSISTENCE_PREVIEW_MAX_CHARS, AGENT_EVENT_TEXT_MAX_CHARS, AGENT_UNKNOWN_PAYLOAD_MAX_CHARS, } from "./events.js";
 import { EXEC_EVENT_BUFFER_HARD_CAP } from "./event-channel.js";
 export function createTruncationMarker(envelope = {
     seq: EXEC_EVENT_BUFFER_HARD_CAP,
@@ -23,10 +23,10 @@ export function overflowMarkerFromDropped(dropped) {
         turn: dropped.turn,
     });
 }
-function truncateText(value) {
+function truncateText(value, limit = AGENT_EVENT_TEXT_MAX_CHARS) {
     return {
-        value: value.slice(0, AGENT_EVENT_TEXT_MAX_CHARS),
-        truncated: value.length > AGENT_EVENT_TEXT_MAX_CHARS,
+        value: value.slice(0, limit),
+        truncated: value.length > limit,
     };
 }
 /** Bound unknown native payloads before they enter the projection event stream. */
@@ -186,7 +186,9 @@ function normalizeBodyForPersistence(body) {
             return { body: { ...body, text: text.value }, truncated: text.truncated };
         }
         case "done": {
-            const finalMessage = body.finalMessage === undefined ? undefined : truncateText(body.finalMessage);
+            const finalMessage = body.finalMessage === undefined
+                ? undefined
+                : truncateText(body.finalMessage, AGENT_DONE_FINAL_MESSAGE_PERSISTENCE_PREVIEW_MAX_CHARS);
             return {
                 body: { ...body, ...(finalMessage ? { finalMessage: finalMessage.value } : {}) },
                 truncated: finalMessage?.truncated ?? false,

package/build/agents/harness/events.js

@@ -1,10 +1,11 @@
 import { z } from "zod";
-export const AGENT_EVENT_TEXT_MAX_CHARS = 4_096;
+export const AGENT_EVENT_TEXT_MAX_CHARS = 16_384;
+export const AGENT_DONE_FINAL_MESSAGE_PERSISTENCE_PREVIEW_MAX_CHARS = 65_536;
 export const AGENT_THOUGHT_TEXT_MAX_CHARS = 4_000;
 export const AGENT_PLAN_MAX_ITEMS = 64;
 export const AGENT_PLAN_ITEM_TEXT_MAX_CHARS = 200;
 export const AGENT_ACTIVITY_MAX_CHANGES = 32;
-export const AGENT_UNKNOWN_PAYLOAD_MAX_CHARS = 4_096;
+export const AGENT_UNKNOWN_PAYLOAD_MAX_CHARS = AGENT_EVENT_TEXT_MAX_CHARS;
 export const activityCallSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("run"), command: z.string(), description: z.string().optional() }).strict(),
     z.object({

package/build/agents/harness/outcome.js

@@ -86,6 +86,16 @@ export function classifyFailure(shared, state, error, idleTimedOut, transportFai
             warnings: [...state.warnings],
         });
     }
+    if (shared.explicitlyAborted && isProviderTerminalError(error) && error.fact.kind === "aborted") {
+        return mintOutcome({
+            status: "interrupted",
+            finalMessage: state.finalMessageCandidate ?? "",
+            output: renderCapturedText(state.outputBuffer),
+            diagnostics: renderCapturedText(state.diagnosticsBuffer),
+            session: state.session ?? fallbackSession(shared),
+            warnings: [...state.warnings],
+        });
+    }
     if (transportFailure) {
         const message = transportFailure instanceof Error ? transportFailure.message : `${shared.terms.provider} session transport probe failed`;
         const timeoutMs = isProviderTerminalError(transportFailure) && transportFailure.fact.kind === "failed"

package/build/agents/providers/codex-app-server/adapter.js

@@ -243,7 +243,12 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
             builderDiagnostic = (text) => builder.emit({ type: "diagnostic", text });
             emitTurnStarted = () => builder.emit({ type: "turn", phase: "started" });
             const env = buildSubagentEnv(options.env);
-            server = new CodexAppServerProcess(executable, env, options.codexHome, options.onEvidence, (text) => builder.emit({ type: "diagnostic", text }));
+            server = new CodexAppServerProcess(executable, env, {
+                cwd,
+                codexHome: options.codexHome,
+                onEvidence: options.onEvidence,
+                onEvidenceDiagnostic: (text) => builder.emit({ type: "diagnostic", text }),
+            });
             const { turnCompleted } = createCodexAppServerTurnMonitor({
                 server,
                 builder,

package/build/agents/providers/codex-app-server/session.js

@@ -3,8 +3,6 @@ import { emitProviderEvidence, sha256Utf8 } from "../../harness/runtime.js";
 import { coerceString } from "../../harness/runtime.js";
 import { CODEX_APP_SERVER_PROVIDER } from "./identity.js";
 export class CodexAppServerProcess {
-    onEvidence;
-    onEvidenceDiagnostic;
     child;
     pending = new Map();
     notificationListeners = new Set();
@@ -17,15 +15,18 @@ export class CodexAppServerProcess {
     gracefulClose;
     forceClose;
     codexHome;
-    constructor(executable, env, codexHome, onEvidence, onEvidenceDiagnostic) {
-        this.onEvidence = onEvidence;
-        this.onEvidenceDiagnostic = onEvidenceDiagnostic;
-        this.codexHome = codexHome;
+    onEvidence;
+    onEvidenceDiagnostic;
+    constructor(executable, env, options) {
+        this.codexHome = options.codexHome;
+        this.onEvidence = options.onEvidence;
+        this.onEvidenceDiagnostic = options.onEvidenceDiagnostic;
         const spawnEnv = {
             ...env,
-            ...(codexHome ? { CODEX_HOME: codexHome } : {}),
+            ...(options.codexHome ? { CODEX_HOME: options.codexHome } : {}),
         };
         this.child = spawn(executable, ["app-server", "--listen", "stdio://"], {
+            cwd: options.cwd,
             env: spawnEnv,
             stdio: ["pipe", "pipe", "pipe"],
         });

package/build/agents/selector.js

@@ -77,7 +77,18 @@ export async function selectSubagent(agentName, cwd) {
         throw new FlowError("INVALID_SETTINGS", `Akuma '${selected}' references missing provider instance '${instanceName}'.`);
     }
     if (!("instance" in providerCandidate) || providerCandidate.instance === undefined) {
-        throw new FlowError("INVALID_SETTINGS", `Akuma '${selected}' references invalid provider instance '${instanceName}': ${providerCandidate.reason}`);
+        const source = providerCandidate.source === "global" ? "global" : "local";
+        throw new FlowError("INVALID_SETTINGS", `Akuma '${selected}' references invalid provider instance '${instanceName}': ${providerCandidate.reason}`, {
+            facts: {
+                kind: "invalid_settings",
+                diseases: [{
+                        source,
+                        coordinate: providerCandidate.coordinate,
+                        knob: "providers",
+                        reason: providerCandidate.reason,
+                    }],
+            },
+        });
     }
     const providerInstance = providerCandidate.instance;
     const adapter = providerInstance.kind;

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

@@ -2,19 +2,12 @@ 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/index.js";
+import { readAkumaNonterminalProjectionStatus } from "../../../../core/projection/index.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, renderAkumaView } 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)
@@ -28,8 +21,7 @@ export const handler = async (_stdin, flags, _signal, positional) => {
     assertSettingsKnobUsable(loaded, "default");
     assertSettingsKnobUsable(loaded, "reviewer");
     const profile = renderAkumaShow(await loadAkumaCatalog(cwd), loaded.providerInstances, loaded.knobs, name).trimEnd();
-    const projectionStatus = await readProjectionStatusBoard(cwd, Date.now(), { showAll: true });
-    const rows = (projectionStatus?.rows ?? []).filter((row) => row.akuma === name && NONTERMINAL_PROJECTION_STATES.has(row.state));
-    const projections = renderProjectionStatusSection({ rows }).trimEnd();
+    const projectionStatus = await readAkumaNonterminalProjectionStatus(cwd, Date.now(), name);
+    const projections = renderProjectionStatusSection(projectionStatus).trimEnd();
     return textResponse(renderAkumaView(profile, projections));
 };

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

@@ -5,7 +5,7 @@ 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 parsed = buildAmendInput(stdin, effectiveDirectory(flags), flags.contractId, flags.contractAddressSource, flags.appendScope);
     const cwd = await repositoryDirectory(flags, "amend");
     const address = await resolveExistingContractAddress(cwd, flags.contractId, flags.contractAddressSource, effectiveDirectory(flags));
     return renderCoreResult(amendKeiyaku({

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

@@ -2,11 +2,11 @@ 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",
+        "keiyaku amend [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--append-scope PATTERN] - < amendment.md",
+        "keiyaku @addr amend [-C|--cwd DIR] [--repo DIR] [--append-scope PATTERN] - < amendment.md",
     ],
     stdin: { mode: "document", selector: { kind: "positional", index: 0, required: true, rejectBlank: true } },
-    flags: ["cwd", "repo", "contract"],
-    purpose: "Append a prose amendment and optional Scope Append gitignore-pattern delta.",
+    flags: ["cwd", "repo", "contract", "append-scope"],
+    purpose: "Append a prose amendment and one optional ordered scope-pattern delta from --append-scope or Scope Append.",
     completionRank: 8,
 };

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

@@ -1,13 +1,19 @@
-import { bindContract } from "../../../../core/bind.js";
+import { bindContract, previewBindContract } from "../../../../core/bind.js";
 import { defaultActorClock } from "../../../../core/outcome-base.js";
 import { writeDraftArtifact } from "../../../draft-artifact.js";
-import { buildBindDraftResponse, buildBindResponse, textResponse } from "../../../render/shared.js";
+import { buildBindDraftResponse, buildBindPreviewResponse, buildBindResponse } from "../../../render/shared.js";
 import { repositoryDirectory } from "../../shared.js";
 export const handler = async (stdin, flags, signal) => {
+    const cwd = await repositoryDirectory(flags, "bind");
     if (flags.dryRun) {
-        return textResponse(stdin);
+        const preview = await previewBindContract({
+            cwd, draft: stdin, ...defaultActorClock(), workspace: "worktree",
+            after: flags.after ?? [], exclusive: flags.exclusive,
+            ...(flags.bindTaskIds === undefined ? {} : { taskIds: flags.bindTaskIds }),
+            signal,
+        });
+        return buildBindPreviewResponse(preview);
     }
-    const cwd = await repositoryDirectory(flags, "bind");
     if (flags.draftOnly) {
         return buildBindDraftResponse(await writeDraftArtifact({ cwd, title: "bind-draft", content: stdin }));
     }

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

@@ -17,10 +17,10 @@ export const meta = {
         "<what the commission should accomplish>",
         "",
         "## Scope",
-        "```",
+        "~~~",
         "<pattern>",
         "<another-pattern>",
-        "```",
+        "~~~",
         "",
         "## Checks",
         "- <verification>",
@@ -40,10 +40,10 @@ export const meta = {
             "<what the commission should accomplish>",
             "",
             "## Scope",
-            "```",
+            "~~~",
             "<pattern>",
             "<another-pattern>",
-            "```",
+            "~~~",
             "",
             "## Checks",
             "- <verification>",
@@ -52,10 +52,10 @@ export const meta = {
         [
             "keiyaku bind --task fix-flaky-pump - <<'KEIYAKU'",
             "## Scope",
-            "```",
+            "~~~",
             "<pattern>",
             "<another-pattern>",
-            "```",
+            "~~~",
             "",
             "## Checks",
             "- <verification>",

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

@@ -1,23 +1,36 @@
 import { FlowError } from "../../../../flow-error.js";
 import { resolveExistingContractAddress, withResolvedAddress } from "../../../../core/addressing.js";
 import { buildPetitionClaimInput, petitionKeiyaku, previewPetition, } from "../../../../core/settlement/index.js";
-import { buildPetitionClaimResponse, buildPetitionPreviewResponse } from "../../../render/petition.js";
+import { renewKeiyaku } from "../../../../core/renew.js";
+import { buildPetitionClaimResponse, buildPetitionPreviewResponse, renderPetitionRenewedConsequence, } from "../../../render/petition.js";
+import { writeCliOutput } from "../../../output-stream-error-policy.js";
 import { effectiveDirectory, 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");
     }
+    if (flags.renewBeforePetition && flags.dryRun) {
+        throw new FlowError("EMPTY_PARAM", "petition --renew cannot be used with --dry-run");
+    }
     const cwd = await repositoryDirectory(flags, "petition");
     const address = await resolveExistingContractAddress(cwd, flags.contractId, flags.contractAddressSource, effectiveDirectory(flags));
     return await withResolvedAddress(address, async () => {
-        const input = buildPetitionClaimInput({ cwd, contractId: address.binding.commissionId, stdin, signal, appendScope: flags.appendScope });
         if (flags.dryRun) {
+            const input = buildPetitionClaimInput({ cwd, contractId: address.binding.commissionId, stdin, signal });
             return buildPetitionPreviewResponse(await previewPetition({
                 cwd,
                 contractId: address.binding.commissionId,
                 oath: input.oath,
             }), flags.json === true);
         }
-        return buildPetitionClaimResponse({ ...await petitionKeiyaku(input), address }, input);
+        const renewed = flags.renewBeforePetition
+            ? await renewKeiyaku({ cwd, address, appendScope: flags.appendScope })
+            : undefined;
+        if (renewed && !renewed.alreadyFresh) {
+            await writeCliOutput(process.stdout, `${renderPetitionRenewedConsequence(renewed)}\n`);
+        }
+        const input = buildPetitionClaimInput({ cwd, contractId: address.binding.commissionId, stdin, signal, appendScope: flags.appendScope });
+        const petitionInput = renewed ? { ...input, appendScope: undefined } : input;
+        return buildPetitionClaimResponse({ ...await petitionKeiyaku(petitionInput), address }, input);
     });
 };

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

@@ -2,12 +2,12 @@ export const meta = {
     command: "petition",
     summary: "Run or preview the gated settlement pipeline",
     usage: [
-        "keiyaku petition [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--append-scope PATTERN] [- < petition.md]",
-        "keiyaku @<id> petition [-C|--cwd DIR] [--repo DIR] [--append-scope PATTERN] [- < petition.md]",
+        "keiyaku petition [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--renew] [--append-scope PATTERN] [- < petition.md]",
+        "keiyaku @<id> petition [-C|--cwd DIR] [--repo DIR] [--renew] [--append-scope PATTERN] [- < petition.md]",
         "keiyaku @<id> petition --dry-run [--json] [- < petition.md]",
     ],
     stdin: { mode: "document", selector: { kind: "positional", index: 0, required: false, rejectBlank: false } },
-    flags: ["cwd", "repo", "contract", "append-scope", "dry-run", "json"],
+    flags: ["cwd", "repo", "contract", "renew", "append-scope", "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",
@@ -16,7 +16,7 @@ export const meta = {
     notes: [
         "Petition stdin is optional and read only when literal - is supplied; 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.",
+        "Use --renew to run ordinary renew before petition; renew failures stop the command before settlement.",
         "Dry-run never runs verification or review and exits 0, 1, or 2.",
     ],
     completionRank: 10,

package/build/cli/commands/metadata.js

@@ -23,6 +23,7 @@ import { meta as taskMeta } from "./task/task/meta.js";
 import { meta as taskAddMeta } from "./task/add/meta.js";
 import { meta as taskShowMeta } from "./task/show/meta.js";
 import { meta as taskLsMeta } from "./task/ls/meta.js";
+import { meta as taskLogMeta } from "./task/log/meta.js";
 import { meta as taskStartMeta } from "./task/start/meta.js";
 import { meta as taskStopMeta } from "./task/stop/meta.js";
 import { meta as taskDoneMeta } from "./task/done/meta.js";
@@ -34,14 +35,14 @@ export const COMMAND_METADATA_ORDER = [
     "bind", "arc", "call", "revive", "wait", "tell", "kill", "log",
     "akuma", "akuma ls", "akuma view", "skills", "skills install", "amend", "audit",
     "renew", "petition", "forfeit", "guide", "completion", "status", "task",
-    "task add", "task show", "task ls", "task start", "task stop", "task done",
+    "task add", "task show", "task ls", "task log", "task start", "task stop", "task done",
     "task drop", "task update", "task doctor", "dump-env",
 ];
 const COMMAND_METADATA = [
     bindMeta, arcMeta, callMeta, reviveMeta, waitMeta, tellMeta, killMeta, logMeta,
     akumaMeta, akumaLsMeta, akumaViewMeta, skillsMeta, skillsInstallMeta, amendMeta, auditMeta,
     renewMeta, petitionMeta, forfeitMeta, guideMeta, completionMeta, statusMeta,
-    taskMeta, taskAddMeta, taskShowMeta, taskLsMeta, taskStartMeta, taskStopMeta,
+    taskMeta, taskAddMeta, taskShowMeta, taskLsMeta, taskLogMeta, taskStartMeta, taskStopMeta,
     taskDoneMeta, taskDropMeta, taskUpdateMeta, taskDoctorMeta, dumpEnvMeta,
 ];
 export const CLI_COMMAND_METADATA = Object.fromEntries(COMMAND_METADATA.map((meta) => [meta.command, meta]));

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

@@ -6,6 +6,10 @@ import { renderProjectionFilteredStatus, renderStatusBoard } from "../../../rend
 import { textResponse } from "../../../render/shared.js";
 import { projectDirectory, repositoryDirectory } from "../../shared.js";
 export const handler = async (_stdin, flags, _signal, positional) => {
+    const [projectionId] = positional;
+    if (projectionId !== undefined && !isProjectionId(projectionId)) {
+        throw new FlowError("EMPTY_PARAM", `invalid projection id: ${projectionId}`);
+    }
     // Status is read-only and must open outside Git. projectDirectory still
     // honors --repo as a repository coordinate when the operator names one.
     const cwd = flags.target === undefined
@@ -14,12 +18,9 @@ export const handler = async (_stdin, flags, _signal, positional) => {
     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,
+        ...(projectionId === undefined ? {} : { projectionId }),
     });
-    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

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

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

@@ -1,5 +1,5 @@
 import { FlowError } from "../../../../flow-error.js";
-import { assertTellEffortSupported, tellProjection, writeInboxTell } from "../../../../core/projection/index.js";
+import { assertTellEffortSupported, interruptProjectionGeneration, tellProjection, writeInboxTell } from "../../../../core/projection/index.js";
 import { waitForProjection } from "../../../../core/projection/index.js";
 import { prependAddressReceipt } from "../../../render/address.js";
 import { buildSilentTellResponse } from "../../../render/tell.js";
@@ -13,7 +13,15 @@ export const handler = async (body, flags, signal, positional) => runProjectionC
     assertTellEffortSupported(projection.directory, flags.effort);
     // Address admission and any effort validation precede the durable mailbox write.
     writeInboxTell(projection.directory, body, Date.now(), { effort: flags.effort });
-    await tellProjection(projection.directory, projection.id, flags.effort);
+    if (flags.interrupt) {
+        const interrupted = interruptProjectionGeneration(projection.directory);
+        if (interrupted.status === "already-closed") {
+            await tellProjection(projection.directory, projection.id, flags.effort);
+        }
+    }
+    else {
+        await tellProjection(projection.directory, projection.id, flags.effort);
+    }
     if (flags.timeoutMs === undefined)
         return buildSilentTellResponse();
     return prependAddressReceipt(buildWaitResponse(projection.id, await waitForProjection({ projectionDirectory: projection.directory, timeoutMs: flags.timeoutMs, signal }), { alias: projection.alias }), ctx.address, { projectionId: projection.id, projectionAlias: projection.alias });

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

@@ -1,12 +1,12 @@
 export const meta = {
     command: "tell",
     summary: "Send intent to a projection mailbox",
-    usage: ["keiyaku tell PROJECTION [--wait DURATION] [--] <BODY|->"],
+    usage: ["keiyaku tell PROJECTION [--interrupt] [--wait DURATION] [--] <BODY|->"],
     stdin: {
         mode: "argument",
         selector: { kind: "positional", index: 1, required: true, rejectBlank: true },
     },
-    flags: ["cwd", "repo", "contract", "effort", "wait"],
-    purpose: "Write intent to the mailbox and wake only when eligible.",
+    flags: ["cwd", "repo", "contract", "effort", "interrupt", "wait"],
+    purpose: "Write intent to the mailbox; --interrupt terminates the active turn before successor wake.",
     completionRank: 3,
 };

package/build/cli/commands/task/add/meta.js

@@ -1,11 +1,19 @@
+const TASK_ADD_USAGE_PREFIX = "keiyaku task add [-C|--cwd DIR] [--needs ID]... [--parent ID] [--from ID]... [--pri 0-3]";
 export const meta = {
     command: "task add",
     summary: "Add a task",
-    usage: ["keiyaku task add [-C|--cwd DIR] [--needs ID] [--parent ID] [--from ID] [--pri 0-3] <BODY|->"],
+    usage: [
+        `${TASK_ADD_USAGE_PREFIX} <BODY>`,
+        `${TASK_ADD_USAGE_PREFIX} - < task.md`,
+    ],
     stdin: {
         mode: "argument",
         selector: { kind: "positional", index: 0, required: true, rejectBlank: true },
     },
     flags: ["cwd", "needs", "parent", "from", "pri"],
     purpose: "Create a lightweight task from a title and optional body.",
+    notes: [
+        "<BODY> and literal - are mutually exclusive body selectors. Use literal - with stdin for multiline prose.",
+        "Only literal - reads stdin; unselected piped bytes are ignored and never change a literal <BODY>.",
+    ],
 };

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

@@ -2,6 +2,7 @@ import { meta as taskMeta } from "./task/meta.js";
 import { meta as addMeta } from "./add/meta.js";
 import { meta as showMeta } from "./show/meta.js";
 import { meta as lsMeta } from "./ls/meta.js";
+import { meta as logMeta } from "./log/meta.js";
 import { meta as startMeta } from "./start/meta.js";
 import { meta as stopMeta } from "./stop/meta.js";
 import { meta as doneMeta } from "./done/meta.js";
@@ -13,6 +14,7 @@ export const taskCatalog = [
     { meta: addMeta, load: () => import("./add/handler.js") },
     { meta: showMeta, load: () => import("./show/handler.js") },
     { meta: lsMeta, load: () => import("./ls/handler.js") },
+    { meta: logMeta, load: () => import("./log/handler.js") },
     { meta: startMeta, load: () => import("./start/handler.js") },
     { meta: stopMeta, load: () => import("./stop/handler.js") },
     { meta: doneMeta, load: () => import("./done/handler.js") },

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

@@ -0,0 +1,12 @@
+import { FlowError } from "../../../../flow-error.js";
+import { readTaskBoard, readTaskHistory, resolveTaskReadId, } from "../../../../core/task/index.js";
+import { textResponse } from "../../../render/shared.js";
+import { withTaskCommandRepository } from "../shared.js";
+export const handler = async (_stdin, flags, _signal, positional) => withTaskCommandRepository(flags, async (repository, cwd) => {
+    const board = await readTaskBoard(repository);
+    const task = board.byId.get(resolveTaskReadId(board, positional[0]));
+    if (!task)
+        throw new FlowError("INTERNAL_STATE", "resolved task disappeared from the board");
+    const rows = await readTaskHistory(cwd, task.id);
+    return textResponse(rows.map(({ timestamp, actor, subject }) => `${timestamp}\t${actor}\t${subject}`).join("\n"));
+});

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

@@ -0,0 +1,8 @@
+export const meta = {
+    command: "task log",
+    summary: "Show one task's Git history",
+    usage: ["keiyaku task log [-C|--cwd DIR] ID"],
+    stdin: { mode: "argument" },
+    flags: ["cwd"],
+    purpose: "Read the current hub branch's task micro-commit history.",
+};

package/build/cli/commands/task/shared.js

@@ -17,7 +17,8 @@ export function parseTaskAddInput(input) {
     if (!input.trim())
         throw new FlowError("EMPTY_PARAM", "task add input cannot be blank");
     const lines = input.split(/\r?\n/);
-    const title = lines[0]?.trim() ?? "";
+    const firstLine = lines[0]?.startsWith("# ") ? lines[0].slice(2) : lines[0];
+    const title = firstLine?.trim() ?? "";
     if (!title)
         throw new FlowError("EMPTY_PARAM", "task title cannot be blank");
     if (lines.length > 1 && lines[1].trim() !== "") {

package/build/cli/completion.js

@@ -19,6 +19,10 @@ function topLevelCommands() {
 function subcommandsFor(parent) {
     return [...(getCommandMetadata(parent).subcommands ?? [])];
 }
+function topLevelOptionsFor(command) {
+    const metadata = allCommandMetadata().find((meta) => meta.command === command && !command.includes(" "));
+    return metadata ? metadata.flags.map((flag) => `--${flag}`) : [];
+}
 function filterPrefix(items, word) {
     return items.filter((item) => item.startsWith(word));
 }
@@ -50,6 +54,10 @@ export async function renderCompletionCandidates(input) {
     if (input.previous === "--filter") {
         return filterPrefix([TASK_FILTER_COMPLETION], word).join("\n");
     }
+    const options = input.previous ? topLevelOptionsFor(input.previous) : [];
+    if (options.length > 0) {
+        return filterPrefix(options, word).join("\n");
+    }
     return filterPrefix(topLevelCommands(), word).join("\n");
 }
 export function renderCompletionScript(shell = "bash") {

package/build/cli/flags.js

@@ -68,6 +68,10 @@ export const FLAG_SPECS = {
         kind: "boolean",
         description: "Return after durable launch instead of waiting for completion.",
     },
+    interrupt: {
+        kind: "boolean",
+        description: "Interrupt the current projection turn after saving the tell.",
+    },
     "draft-only": {
         kind: "boolean",
         description: "Write a draft artifact without creating a contract workspace.",
@@ -124,6 +128,10 @@ export const FLAG_SPECS = {
         placeholder: "PATTERN",
         description: "Append one ordered scope pattern to the contract before audit. May be repeated.",
     },
+    renew: {
+        kind: "boolean",
+        description: "Renew onto the current target before petitioning.",
+    },
     resolve: {
         kind: "boolean",
         description: "Open a durable Keiyaku-owned renew recovery session when the rewrite conflicts.",

package/build/cli/index.js

@@ -57,9 +57,6 @@ function prepareBindInput(stdin, flags) {
             checks: flags.bindChecks,
         });
     }
-    if (flags.dryRun) {
-        throw new FlowError("EMPTY_PARAM", "--dry-run requires --place, --objective, --scope, and --checks");
-    }
     if (!nonblankStdin) {
         // --task may supply name/objective defaults; core merges and reports missing sections.
         if (flags.bindTaskIds !== undefined && flags.bindTaskIds.length > 0) {
@@ -188,11 +185,17 @@ function selectedArgument(parsed) {
     if (stdin.selector === undefined)
         return undefined;
     if (stdin.selector.kind === "positional") {
-        return { token: parsed.positional[stdin.selector.index], replace: () => parsed.flags };
+        const token = parsed.positional[stdin.selector.index];
+        if (token === undefined && !stdin.selector.required)
+            return undefined;
+        return { token, replace: () => parsed.flags };
     }
     const flagName = stdin.selector.name;
+    const token = parsed.flags[flagName];
+    if (token === undefined && !stdin.selector.required)
+        return undefined;
     return {
-        token: parsed.flags[flagName],
+        token,
         replace: (value) => ({ ...parsed.flags, [flagName]: value }),
     };
 }
@@ -248,7 +251,8 @@ export async function runCliCommand(tokens) {
         await printFailure(error, cwd);
         return 1;
     }
-    // Bind dry-run must compile and return before repository/cwd resolution or filesystem effects.
+    // Bind input compilation is side-effect free. Dry-run then performs the same
+    // repository admission as bind but does not persist an artifact on failure.
     if (parsed.command === "bind") {
         try {
             stdin = prepareBindInput(stdin, parsed.flags);

package/build/cli/parse-flags.js

@@ -54,6 +54,9 @@ export function assignFlag(flags, name, value) {
         case "detach":
             flags.detach = Boolean(value);
             return;
+        case "interrupt":
+            flags.interrupt = Boolean(value);
+            return;
         case "draft-only":
             flags.draftOnly = Boolean(value);
             return;
@@ -102,6 +105,9 @@ export function assignFlag(flags, name, value) {
         case "append-scope":
             flags.appendScope = [...(flags.appendScope ?? []), String(value)];
             return;
+        case "renew":
+            flags.renewBeforePetition = Boolean(value);
+            return;
         case "resolve":
             flags.renewResolve = Boolean(value);
             return;

package/build/cli/parse-metadata.js

@@ -83,7 +83,7 @@ export function commandPositionalRange(command) {
     if (command === "task add") {
         return { min: 1, max: 1, label: "<BODY|->" };
     }
-    if (command === "task show" || command === "task start" || command === "task drop") {
+    if (command === "task show" || command === "task log" || command === "task start" || command === "task drop") {
         return { min: 1, max: 1, label: "<ID>" };
     }
     if (command === "task update") {