@astrosheep/keiyaku 0.1.18 → 0.1.19

package/build/common/errors.js

@@ -70,57 +70,17 @@ function hintForFlowCode(code, message) {
             return `\`${preset.tools.start.name}\` requires a clean slate. Remove existing \`KEIYAKU.md\` before starting.`;
         case "DRAFT_FILE_EXISTS":
             return `Existing \`KEIYAKU.draft.md\` detected. Use it via \`from_file\` or delete it before starting.`;
+        case "DETACHED_HEAD":
+            return "Repository is in detached HEAD state. Switch to a branch and retry.";
+        case "INVALID_CLOSE_PETITION":
+            return "Invalid close petition. Use `CLAIM` or `FORFEIT`.";
+        case "INTERNAL_STATE":
+            return message;
     }
 }
-const MESSAGE_HINT_PATTERNS = [
-    { code: "NOT_GIT_REPO", patterns: ["is not a git repository"] },
-    { code: "ACTIVE_KEIYAKU_EXISTS", patterns: ["active keiyaku already exists"] },
-    { code: "EXISTING_KEIYAKU_BRANCH_FOUND", patterns: ["existing keiyaku branch found"] },
-    { code: "EMPTY_PARAM", patterns: ["cannot be empty"] },
-    { code: "DIRTY_WORKTREE", patterns: ["working tree has uncommitted changes"] },
-    { code: "NOT_ACTIVE_KEIYAKU_BRANCH", patterns: ["current branch is not an active keiyaku branch"] },
-    { code: "MISSING_KEIYAKU_BASE", patterns: ["is missing base metadata"] },
-    { code: "MISSING_PROTOCOL_FILES", patterns: ["missing protocol files"] },
-    { code: "DONE_MERGE_CONFLICT", patterns: ["DONE merge conflict"] },
-    { code: "CLOSE_QUALITY_GATE_FAILED", patterns: ["God's Wrath: CLAIM denied"] },
-    {
-        code: "OATH_MISMATCH",
-        patterns: [
-            "requires the sacred oath to exactly equal",
-            "requires oath to exactly match configured value",
-            "requires oath to match configured value. If template contains",
-            "To declare DONE, you must solemnly swear the sacred oath.",
-            "To declare DONE, oath mismatch.",
-            "Oath mismatch.",
-        ],
-    },
-    {
-        code: "SUBAGENT_DID_NOT_ADVANCE_ROUND",
-        patterns: ["subagent did not advance round", "did not append KEIYAKU_TRACE"],
-    },
-    { code: "ROUND_SUBAGENT_FAILED", patterns: ["failed during subagent execution"] },
-    { code: "INVALID_BRANCH_TITLE", patterns: ["cannot be converted to a valid branch name"] },
-    { code: "UNKNOWN_SUBAGENT", patterns: ["Unknown subagent"] },
-    { code: "FROM_FILE_NOT_FOUND", patterns: ["from_file path does not exist"] },
-    { code: "INVALID_KEIYAKU_DRAFT", patterns: ["invalid keiyaku draft"] },
-    { code: "KEIYAKU_FILE_EXISTS", patterns: ["pre-flight failed: KEIYAKU.md already exists"] },
-    { code: "DRAFT_FILE_EXISTS", patterns: ["pre-flight failed: KEIYAKU.draft.md exists but from_file does not target it"] },
-];
-function inferFlowCodeFromMessage(message) {
-    for (const entry of MESSAGE_HINT_PATTERNS) {
-        if (entry.patterns.some((pattern) => message.includes(pattern))) {
-            return entry.code;
-        }
-    }
-    return null;
-}
-export function pickHintFromError(err, message) {
+export function pickHintFromError(err) {
     if (isFlowError(err)) {
         return hintForFlowCode(err.code, err.message);
     }
-    const inferredCode = inferFlowCodeFromMessage(message);
-    if (inferredCode) {
-        return hintForFlowCode(inferredCode, message);
-    }
     return "Review the error details, fix the issue, and retry.";
 }

package/build/config/term-presets.js

@@ -57,7 +57,7 @@ export const DEFAULT_PRESET = {
             title: 'Sign Keiyaku',
             description: 'Initialize a Keiyaku (Contract). Bind a Servant to a dedicated workspace (branch).\nYou are the Architect; they are the Instrument. Define the Goal and Scope clearly.\nThe contract isolates their existence until the objective is met.\nCall ONCE to seal the bond.\n\nFlow: ${start} → [${drive} x N] → ${close}',
             args: {
-                from_file: "Optional markdown draft path. Loads `# title` + required sections from file (relative to cwd unless absolute).",
+                from_file: "Optional markdown draft path. Loads `# title` + required sections from file (relative to cwd unless absolute). Note: this file is auto-ignored by dirty-tree checks.",
                 title: 'Required unless provided via `from_file`. A concise codename for this hunt.',
                 goal: 'Required unless provided via `from_file`. The Kill Condition for this mission.',
                 directive: 'Optional First Step. Overrides `## Directive` from `from_file` when both are provided.',
@@ -162,7 +162,7 @@ export const POCKET_PRESET = {
             title: 'I Choose You!',
             description: 'Initialize the Battle Phase. Send a Critter (Servant) into a dedicated Arena (branch).\nYou are the Trainer; they are the Fighter. Define the Victory Condition (Goal) clearly.\nThe battle continues in this Arena until the Badge is won.\nCall ONCE to start the encounter.\n\nFlow: ${start} → [${drive} x N] → ${close}',
             args: {
-                from_file: 'Optional battle plan markdown path with title + sections.',
+                from_file: 'Optional battle plan markdown path with title + sections. This file is auto-ignored by dirty-tree checks.',
                 title: 'Required unless provided via `from_file`. Battle card title for this encounter.',
                 goal: 'Required unless provided via `from_file`. Victory condition for this battle.',
                 directive: 'Optional Turn 1 strategy (overrides draft directive).',
@@ -258,7 +258,7 @@ export const MISCHIEF_PRESET = {
             title: 'Oi!',
             description: "Initiate Grand Scheme. Summon a Minion to the Lair (branch).\nYou are the Mastermind; they are the Henchman. Define the Conquest (Goal) with dominance.\nThe minion is bound to this Lair until the plot is realized.\nCall ONCE to start the machine.\n\nFlow: ${start} → [${drive} x N] → ${close}",
             args: {
-                from_file: 'Optional scheme markdown path with title + sectioned objectives.',
+                from_file: 'Optional scheme markdown path with title + sectioned objectives. This file is auto-ignored by dirty-tree checks.',
                 title: 'Required unless provided via `from_file`. Operation codename.',
                 goal: 'Required unless provided via `from_file`. Conquest objective and end-state.',
                 directive: 'Optional first-order command (overrides draft directive).',

package/build/handlers/close.js

@@ -61,10 +61,10 @@ export function createCloseHandler() {
             const outcome = await presentWork(closeInput);
             if (input.petition === "CLAIM") {
                 if (!claimInput) {
-                    throw new Error("Unexpected CLAIM input shape");
+                    throw new FlowError("INTERNAL_STATE", "Unexpected CLAIM input shape");
                 }
                 if (!("result" in outcome) || outcome.result !== "merged") {
-                    throw new Error("Unexpected CLAIM outcome shape");
+                    throw new FlowError("INTERNAL_STATE", "Unexpected CLAIM outcome shape");
                 }
                 const finalOutcome = outcome;
                 appendDebugLog(`tool close CLAIM success branch=${finalOutcome.currentBranch} base=${finalOutcome.baseBranch}`, {
@@ -84,7 +84,7 @@ export function createCloseHandler() {
                 });
             }
             if (!("result" in outcome) || outcome.result !== "dropped") {
-                throw new Error("Unexpected FORFEIT outcome shape");
+                throw new FlowError("INTERNAL_STATE", "Unexpected FORFEIT outcome shape");
             }
             const finalOutcome = outcome;
             appendDebugLog(`tool close FORFEIT success branch=${finalOutcome.currentBranch} base=${finalOutcome.baseBranch}`, {

package/build/handlers/shared.js

@@ -17,7 +17,7 @@ export function classifyToolError(error) {
 export function handleToolError(input) {
     const message = asMessage(input.error);
     appendDebugLog(`${input.logLabel} error: ${message}`, { cwd: input.cwd, section: "script" });
-    const hint = pickHintFromError(input.error, message);
+    const hint = pickHintFromError(input.error);
     const { errorType, errorCode } = classifyToolError(input.error);
     return buildToolErrorResponse({
         tool: input.toolName,

package/build/utils/git-ops.js

@@ -1,4 +1,5 @@
 import { simpleGit } from "simple-git";
+import { FlowError } from "../common/errors.js";
 import { appendDebugBlock } from "./debug-log.js";
 const DEFAULT_GIT_TIMEOUT_MS = 15 * 1000;
 function readPositiveIntEnv(name, fallback) {
@@ -80,7 +81,7 @@ export async function getCurrentBranch(cwd) {
         throw wrapGitError("status", err, cwd);
     }
     if (!status.current) {
-        throw new Error("Detached HEAD or no branch found");
+        throw new FlowError("DETACHED_HEAD", "Detached HEAD or no branch found");
     }
     return status.current;
 }
@@ -234,6 +235,34 @@ export async function getDirtyPaths(cwd) {
     const files = await getDirtyFiles(cwd);
     return Array.from(new Set(files.map(f => f.path)));
 }
+export async function isPathTracked(cwd, filePath) {
+    const git = createGit(cwd);
+    let output;
+    try {
+        output = await git.raw(["ls-files", "--", filePath]);
+    }
+    catch (err) {
+        throw wrapGitError(`ls-files -- ${filePath}`, err, cwd);
+    }
+    return output
+        .split(/\r?\n/)
+        .some((line) => line.trim() === filePath);
+}
+export async function discardAllWorkingTreeChanges(cwd) {
+    const git = createGit(cwd);
+    try {
+        await git.raw(["reset", "--hard", "HEAD"]);
+    }
+    catch (err) {
+        throw wrapGitError("reset --hard HEAD", err, cwd);
+    }
+    try {
+        await git.raw(["clean", "-fd"]);
+    }
+    catch (err) {
+        throw wrapGitError("clean -fd", err, cwd);
+    }
+}
 export async function assertValidBranchName(cwd, branchName) {
     const git = createGit(cwd);
     try {

package/build/utils/text-utils.js

@@ -8,17 +8,27 @@ function isPlainObject(value) {
 export function flattenMarkdownList(text) {
     const ast = parseToAST(text, { allowSections: false });
     const items = [];
-    let currentTitle;
+    const headingStack = [];
     const pushItem = (content) => {
         const trimmed = content.trim();
         if (!trimmed)
             return;
-        const prefix = currentTitle ? `**${currentTitle.replace(/^\d+\.\s*/, "")}**: ` : "";
+        const headingPath = headingStack.map((entry) => entry.title);
+        const prefix = headingPath.length > 0 ? `**${headingPath.join(" > ")}**: ` : "";
         items.push(`${prefix}${trimmed}`);
     };
+    const updateHeadingPath = (level, rawText) => {
+        const title = rawText.trim().replace(/^\d+\.\s*/, "");
+        if (!title)
+            return;
+        while (headingStack.length > 0 && headingStack[headingStack.length - 1].level >= level) {
+            headingStack.pop();
+        }
+        headingStack.push({ level, title });
+    };
     for (const node of ast.children) {
         if (node.type === "heading") {
-            currentTitle = node.text.trim();
+            updateHeadingPath(node.level, node.text);
             continue;
         }
         if (node.type === "list") {

package/build/workflow/contract.js

@@ -6,6 +6,7 @@ import { FlowError } from "../common/errors.js";
 import * as git from "../utils/git.js";
 import { resolveOath } from "./oath.js";
 export { resolveOath };
+const DIRTY_WORKTREE_LIST_LIMIT = 10;
 export async function ensureKeiyakuFiles(cwd) {
     const keiyakuPath = path.join(cwd, KEIYAKU_FILE);
     const tracePath = path.join(cwd, TRACE_FILE);
@@ -36,13 +37,21 @@ export async function assertCleanWorkingTree(cwd, ignorePatterns) {
         .getDirtyFiles(cwd)
         .then((files) => files.filter((file) => !ignoredPaths.has(normalizePathForDirtyMatch(cwd, file.path))));
     if (dirtyFiles.length > 0) {
-        const list = dirtyFiles
+        const shown = dirtyFiles.slice(0, DIRTY_WORKTREE_LIST_LIMIT);
+        const list = shown
             .map((f) => {
             const status = `${f.index}${f.working_dir}`;
             return `  ${status} ${f.path}`;
         })
             .join("\n");
-        throw new FlowError("DIRTY_WORKTREE", `Uncommitted changes detected in working tree:\n${list}\n\nPlease commit or stash them before proceeding to ensure a stable state.`);
+        const overflowCount = dirtyFiles.length - shown.length;
+        const overflowLine = overflowCount > 0 ? `\n  ... (+${overflowCount} more)` : "";
+        const ignoredList = ignoredPaths.size > 0
+            ? `\n\nIgnored uncommitted paths (not blocking):\n${Array.from(ignoredPaths)
+                .map((pathValue) => `  - ${pathValue}`)
+                .join("\n")}`
+            : "";
+        throw new FlowError("DIRTY_WORKTREE", `Uncommitted changes detected in working tree:\n${list}${overflowLine}${ignoredList}\n\nPlease commit or stash blocking changes before proceeding.`);
     }
 }
 export async function buildNoActiveKeiyakuGuidance(cwd, toolName) {

package/build/workflow/drive.js

@@ -55,6 +55,7 @@ export async function driveServant(input) {
         await appendReview(cwd, plan.targetRound, plan.reviewReason);
         await git.addFiles(cwd, TRACE_FILE);
         await git.commit(cwd, `keiyaku(${title}): iterate round ${plan.targetRound}`);
+        const commit = await git.getLatestCommitHash(cwd);
         const { roundSummary } = await runAndRecordRound(cwd, title, plan.targetRound, plan.prompt, {
             signal,
             name,
@@ -63,6 +64,7 @@ export async function driveServant(input) {
                 await appendRoundSystemNote(cwd, plan.targetRound, "Subagent execution cancelled by user/client.");
                 await git.addFiles(cwd, TRACE_FILE);
                 await git.commit(cwd, `keiyaku(${title}): round ${plan.targetRound} cancelled`);
+                await git.getLatestCommitHash(cwd);
             },
         });
         const summary = renderRoundSummary(roundSummary, TOOL_DEFAULT_POLICY);
@@ -77,6 +79,7 @@ export async function driveServant(input) {
             criteria,
             currentBranch: keiyakuBranch,
             baseBranch,
+            commit,
         };
     }
     catch (err) {

package/build/workflow/present.js

@@ -1,6 +1,6 @@
 import * as fs from "fs/promises";
 import * as path from "path";
-import { KEIYAKU_FILE, TRACE_FILE } from "../common/constants.js";
+import { KEIYAKU_DRAFT_FILE, KEIYAKU_DRAFT_NEW_FILE, KEIYAKU_FILE, TRACE_FILE } from "../common/constants.js";
 import { resolveTermPreset } from "../config/term-presets.js";
 import { appendDebugLog } from "../utils/debug-log.js";
 import { FlowError, wrapFlowError } from "../common/errors.js";
@@ -95,6 +95,27 @@ function requireChecks(name, values) {
     }
     return values;
 }
+async function removeClaimProtocolFiles(cwd) {
+    await fs.unlink(path.join(cwd, KEIYAKU_FILE));
+    await fs.unlink(path.join(cwd, TRACE_FILE));
+    const draftCandidates = [KEIYAKU_DRAFT_FILE, KEIYAKU_DRAFT_NEW_FILE];
+    for (const draftPath of draftCandidates) {
+        const tracked = await git.isPathTracked(cwd, draftPath);
+        if (tracked)
+            continue;
+        try {
+            await fs.unlink(path.join(cwd, draftPath));
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT") {
+                throw error;
+            }
+        }
+    }
+}
+function formatCloseDiffSummary(stats, baseBranch) {
+    return `Range ${baseBranch}...HEAD | Files ${stats.filesChanged} | +${stats.insertions} / -${stats.deletions}`;
+}
 export async function presentWork(input) {
     const { cwd } = input;
     const isRepo = await git.isGitRepo(cwd);
@@ -120,8 +141,12 @@ export async function presentWork(input) {
         catch {
             round = 0;
         }
-        await assertCleanWorkingTree(cwd);
+        const dirtyFiles = await git.getDirtyFiles(cwd);
+        const droppedChanges = dirtyFiles.map((file) => `${file.index}${file.working_dir} ${file.path}`);
         try {
+            if (droppedChanges.length > 0) {
+                await git.discardAllWorkingTreeChanges(cwd);
+            }
             await git.checkoutBranch(cwd, baseBranch);
             await git.deleteBranch(cwd, keiyakuBranch, true);
             await git.clearKeiyakuBase(cwd, keiyakuBranch);
@@ -136,7 +161,10 @@ export async function presentWork(input) {
             currentBranch: baseBranch,
             baseBranch,
             deletedBranch: keiyakuBranch,
-            diff: "Forfeited without merge.",
+            diff: droppedChanges.length > 0
+                ? `Forfeited without merge. Dropped ${droppedChanges.length} local change(s).`
+                : "Forfeited without merge.",
+            droppedChanges,
         };
     }
     await ensureKeiyakuFiles(cwd);
@@ -169,7 +197,7 @@ export async function presentWork(input) {
         if (!oathMatches(input.oath, expectedOath)) {
             throw new FlowError("OATH_MISMATCH", `Oath mismatch. Correct oath: ${expectedOath}`);
         }
-        await assertCleanWorkingTree(cwd);
+        await assertCleanWorkingTree(cwd, [KEIYAKU_DRAFT_FILE, KEIYAKU_DRAFT_NEW_FILE]);
         try {
             const invokeDiffLog = `[CLAIM] Collecting diff preview against base '${baseBranch}'`;
             console.error(invokeDiffLog);
@@ -179,14 +207,14 @@ export async function presentWork(input) {
             appendDebugLog(invokeReadLog, { cwd, section: "script" });
             const keiyakuContent = await fs.readFile(path.join(cwd, KEIYAKU_FILE), "utf-8");
             const message = buildMergeMessage(title, keiyakuContent, traceContent);
+            const diffStats = await git.getDiffStats(cwd, baseBranch);
+            const diff = formatCloseDiffSummary(diffStats, baseBranch);
             const invokeCleanupLog = "[CLAIM] Removing protocol files and creating cleanup commit";
             console.error(invokeCleanupLog);
             appendDebugLog(invokeCleanupLog, { cwd, section: "script" });
-            await fs.unlink(path.join(cwd, KEIYAKU_FILE));
-            await fs.unlink(path.join(cwd, TRACE_FILE));
+            await removeClaimProtocolFiles(cwd);
             await git.addFiles(cwd, "-A");
             await git.commit(cwd, `keiyaku(${title}): cleanup`);
-            const diff = await git.getDiffPreviewText(cwd, baseBranch);
             const invokeCheckoutLog = `[CLAIM] Checking out base branch '${baseBranch}'`;
             console.error(invokeCheckoutLog);
             appendDebugLog(invokeCheckoutLog, { cwd, section: "script" });
@@ -195,7 +223,7 @@ export async function presentWork(input) {
             console.error(invokeMergeLog);
             appendDebugLog(invokeMergeLog, { cwd, section: "script" });
             await git.merge(cwd, keiyakuBranch, message);
-            const mergedCommit = await git.getLatestCommitHash(cwd);
+            const commit = await git.getLatestCommitHash(cwd);
             const invokeFinalizeLog = `[CLAIM] Deleting merged branch '${keiyakuBranch}' and clearing metadata`;
             console.error(invokeFinalizeLog);
             appendDebugLog(invokeFinalizeLog, { cwd, section: "script" });
@@ -208,7 +236,7 @@ export async function presentWork(input) {
                 round,
                 currentBranch: baseBranch,
                 baseBranch,
-                mergedCommit,
+                commit,
                 mergedInto: baseBranch,
                 deletedBranch: keiyakuBranch,
                 diff,
@@ -222,5 +250,5 @@ export async function presentWork(input) {
             throw wrapFlowError(`execute CLAIM (merge ${keiyakuBranch} into ${baseBranch})`, err);
         }
     }
-    throw new Error(`unsupported close petition: ${petition}`);
+    throw new FlowError("INVALID_CLOSE_PETITION", `unsupported close petition: ${petition}`);
 }

package/build/workflow/response-builders.js

@@ -135,8 +135,12 @@ export function buildKeiyakuSuccessResponse(result, input) {
         ...formatMaybe("Path", input.cwd, 300),
         ...formatMaybe("Current Branch", result.currentBranch, 200),
         ...formatMaybe("Base Branch", result.baseBranch, 200),
+        ...formatMaybe("Commit", result.commit, 100),
     ];
-    const text = assembleResponse(`◆ Started (Round ${result.round})`, `Created branch '${result.currentBranch}' (base: '${result.baseBranch}').`, [summarySection, constraintsSection, diffSection].filter((section) => section !== null), infoLines);
+    const summaryLine = result.commit
+        ? `Created branch '${result.currentBranch}' (base: '${result.baseBranch}') [${result.commit}].`
+        : `Created branch '${result.currentBranch}' (base: '${result.baseBranch}').`;
+    const text = assembleResponse(`◆ Started (Round ${result.round})`, summaryLine, [summarySection, constraintsSection, diffSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(getStartToolName(), resultData),
@@ -154,8 +158,12 @@ export function buildDriveResponse(result, input) {
         ...formatMaybe("Path", input.cwd, 300),
         ...formatMaybe("Current Branch", result.currentBranch, 200),
         ...formatMaybe("Base Branch", result.baseBranch, 200),
+        ...formatMaybe("Commit", result.commit, 100),
     ];
-    const text = assembleResponse(`◆ Driven (Round ${result.round})`, `Updated branch '${result.currentBranch}'.`, [summarySection, goalSection, constraintsSection, criteriaSection, diffSection].filter((section) => section !== null), infoLines);
+    const summaryLine = result.commit
+        ? `Updated branch '${result.currentBranch}' [${result.commit}].`
+        : `Updated branch '${result.currentBranch}'.`;
+    const text = assembleResponse(`◆ Driven (Round ${result.round})`, summaryLine, [summarySection, goalSection, constraintsSection, criteriaSection, diffSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(getDriveToolName(), resultData),
@@ -181,7 +189,7 @@ export function buildCloseDoneResponse(result, input) {
     const infoLines = [
         ...formatMaybe("Path", input.cwd, 300),
         ...formatMaybe("Result", result.result, 100),
-        ...formatMaybe("Merged Commit", result.mergedCommit, 100),
+        ...formatMaybe("Commit", result.commit, 100),
         ...formatMaybe("Merged Into", result.mergedInto, 200),
         ...formatMaybe("Deleted Branch", result.deletedBranch, 200),
         ...formatMaybe("Current Branch", result.currentBranch, 200),
@@ -191,7 +199,9 @@ export function buildCloseDoneResponse(result, input) {
         `Scores: precise=${input.score_precise}/10 minimal=${input.score_minimal}/10 isolated=${input.score_isolated}/10 idiomatic=${input.score_idiomatic}/10 cohesive=${input.score_cohesive}/10`,
         ...formatMaybe("Oath", input.oath, 220),
     ];
-    const text = assembleResponse("✓ Keiyaku Fulfilled (CLAIM)", `Merged '${result.deletedBranch}' into '${result.mergedInto}' (commit: ${result.mergedCommit}). Deleted feature branch.`, [typeof diffSection === "string" ? null : diffSection].filter((section) => section !== null), infoLines);
+    const text = assembleResponse("✓ Keiyaku Fulfilled (CLAIM)", result.commit
+        ? `Merged '${result.deletedBranch}' into '${result.mergedInto}' [${result.commit}]. Deleted feature branch.`
+        : `Merged '${result.deletedBranch}' into '${result.mergedInto}'. Deleted feature branch.`, [typeof diffSection === "string" ? null : diffSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(closeToolName, resultData),
@@ -200,13 +210,17 @@ export function buildCloseDoneResponse(result, input) {
 export function buildCloseDropResponse(result, input) {
     const { status: _status, ...resultData } = result;
     const closeToolName = getCloseToolName();
+    const droppedChanges = result.droppedChanges ?? [];
+    const warningSection = buildSection("Warning", formatList("Dropped Local Changes", droppedChanges, { maxItems: 20, maxItemChars: 220 }));
     const infoLines = [
         ...formatMaybe("Path", input.cwd, 300),
         ...formatMaybe("Deleted Branch", result.deletedBranch, 200),
         ...formatMaybe("Current Branch", result.currentBranch, 200),
         ...formatMaybe("Base Branch", result.baseBranch, 200),
     ];
-    const text = assembleResponse("✗ Keiyaku Forfeited (FORFEIT)", `Deleted '${result.deletedBranch}'. Switched back to '${result.baseBranch}'.`, [], infoLines);
+    const text = assembleResponse("✗ Keiyaku Forfeited (FORFEIT)", droppedChanges.length > 0
+        ? `Deleted '${result.deletedBranch}'. Switched back to '${result.baseBranch}'. Dropped ${droppedChanges.length} local change(s).`
+        : `Deleted '${result.deletedBranch}'. Switched back to '${result.baseBranch}'.`, [warningSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(closeToolName, resultData),

package/build/workflow/start.js

@@ -15,6 +15,7 @@ import { runAndRecordRound } from "./round.js";
 const BASE_CONSTRAINTS_FILE = path.join(".keiyaku", "base-constraints.md");
 const ACTIVE_KEIYAKU_PREVIEW_MAX_CHARS = 8000;
 const KNOWN_SECTIONS = new Set(["goal", "directive", "context", "constraints", "criteria", "acceptance criteria"]);
+const INTERNAL_START_DIRTY_ALLOWLIST = [];
 function normalizeSectionTitle(title) {
     return title.trim().toLowerCase().replace(/\s+/g, " ");
 }
@@ -268,6 +269,7 @@ function normalizeTitleForBranch(title) {
 }
 async function resolveStartInput(cwd, input) {
     const fromFile = normalizeOptionalText(input.from_file);
+    const dirtyAllowlist = [...INTERNAL_START_DIRTY_ALLOWLIST];
     const provided = {
         title: normalizeOptionalText(input.title),
         goal: normalizeOptionalText(input.goal),
@@ -297,6 +299,7 @@ async function resolveStartInput(cwd, input) {
             criteria: normalizeMarkdownListItems("criteria", provided.criteria),
             constraints: normalizeMarkdownListItems("constraints", provided.constraints ?? []),
             fromFile: undefined,
+            dirtyAllowlist,
         };
     }
     const draftPath = path.isAbsolute(fromFile) ? fromFile : path.join(cwd, fromFile);
@@ -337,6 +340,7 @@ async function resolveStartInput(cwd, input) {
         criteria: normalizeMarkdownListItems("criteria", criteria),
         constraints: normalizeMarkdownListItems("constraints", constraints),
         fromFile,
+        dirtyAllowlist,
     };
 }
 async function readBaseConstraints(cwd) {
@@ -431,7 +435,8 @@ export async function startKeiyaku(input) {
             appendDebugLog(branchWarning, { cwd, section: "script" });
         }
         await assertStartPreFlight(cwd, resolved.fromFile);
-        await assertCleanWorkingTree(cwd, resolved.fromFile ? [resolved.fromFile] : undefined);
+        const dirtyAllowlist = Array.from(new Set([...(resolved.fromFile ? [resolved.fromFile] : []), ...resolved.dirtyAllowlist]));
+        await assertCleanWorkingTree(cwd, dirtyAllowlist.length > 0 ? dirtyAllowlist : undefined);
         baseBranch = await git.getCurrentBranch(cwd);
         const branchToken = normalizeTitleForBranch(resolved.title);
         keiyakuBranch = `keiyaku/${branchToken}`;
@@ -454,6 +459,7 @@ export async function startKeiyaku(input) {
         await fs.writeFile(path.join(cwd, TRACE_FILE), "# Keiyaku Trace\n");
         await git.addFiles(cwd, [KEIYAKU_FILE, TRACE_FILE]);
         await git.commit(cwd, `keiyaku(${branchToken}): open`);
+        const commit = await git.getLatestCommitHash(cwd);
         const prompt = buildStartPrompt(resolved.title, resolved.goal, resolved.directive);
         const { roundSummary } = await runAndRecordRound(cwd, branchToken, 1, prompt, {
             signal,
@@ -480,6 +486,7 @@ export async function startKeiyaku(input) {
             constraints: constraintsSection,
             currentBranch: keiyakuBranch,
             baseBranch,
+            commit,
         };
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "MCP server for running iterative keiyaku workflows with Codex subagents.",
   "license": "MIT",
   "type": "module",