@litfamily/litopencode 1.0.0

package/dist/deliverable-hedge-guard.js

@@ -0,0 +1,302 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { mutatedFilePaths } from "./tool-guards.js";
+export const artifactGenres = [
+    "client_deliverable",
+    "internal_analysis",
+    "audit_report",
+    "working_note",
+    "no_artifact"
+];
+const limitationsByGenre = Object.freeze({
+    client_deliverable: "reply",
+    internal_analysis: "designated_section",
+    audit_report: "methodology_paragraph",
+    working_note: "inline",
+    no_artifact: "reply"
+});
+const defaultSkillsRoot = fileURLToPath(new URL("../skills", import.meta.url));
+const lazyOutputChannelSkills = new Set(["frontend-ui-ux", "visual-qa"]);
+const readerFacingExtensions = new Set([".adoc", ".html", ".md", ".mdx", ".rst", ".tex", ".txt"]);
+const maxArtifactBytes = 2 * 1024 * 1024;
+const maxTrackedSessions = 256;
+const maxHedgeFindings = 32;
+const maxReportedLines = 16;
+const maxAdditionalContextBytes = 512;
+const textKeysByTool = Object.freeze({
+    write: ["content"],
+    edit: ["newString", "new_string"]
+});
+const phrasePatterns = [
+    { className: "deferred", pattern: /보류\s*중|별도로\s*진행|추후\s*진행|to be determined separately/giu },
+    { className: "scope-limit", pattern: /한정됩니다|국한됩니다|범위\s*내에서만|limited to the provided evidence/giu },
+    { className: "negated-action", pattern: /하지\s*않았습니다|포함되지\s*않습니다|다루지\s*않습니다|was not performed|is not included/giu },
+    { className: "self-protection", pattern: /참고용|추가\s*검증이\s*필요|완전하지\s*않을\s*수\s*있|for reference only|may be incomplete/giu },
+    { className: "process-meta", pattern: /as an AI|이\s*작업에서는|프롬프트가/giu }
+];
+const evidenceSubject = /근거|자료|측정값|관찰\s*기록|데이터|증거|출처|참고문헌|평가\s*자료|검토\s*자료|시험\s*결과|검증\s*결과|수치|통계|evidence|data|measurement|observation|source|citation|test result/iu;
+const evaluativeSubject = /접근성|성능|효과|유효성|품질|평가|결과|점수|충족\s*여부|적합성|안전성|accessibility|performance|effect|validity|quality|score|compliance|safety/iu;
+const koreanAbsence = /없(?:어(?:서)?|습니다|음)|부족|부재|제공되지\s*않|주어지지\s*않|확인되지\s*않|검증되지\s*않/u;
+const koreanEpistemicInability = /(?:평가|판단|산정)할\s*수\s*없|알\s*수\s*없/u;
+const englishAbsence = /\b(?:no evidence yet|not yet substantiated|(?:evidence|data|measurements?|observations?|sources?|citations?|test results?) (?:is|are|was|were)?\s*(?:missing|absent|unavailable|insufficient|not (?:provided|available|verified|substantiated)))\b/iu;
+const englishEpistemicInability = /\b(?:cannot|can not|unable to)\s+(?:assess|determine|calculate|establish|substantiate|verify)\b/iu;
+function isArtifactGenre(value) {
+    return typeof value === "string" && artifactGenres.some((candidate) => candidate === value);
+}
+function outputChannelBlock(markdown) {
+    return markdown.match(/^## #contract\.output_channels\s*\n\s*```ya?ml\s*\n([\s\S]*?)\n```\s*$/mu)?.[1];
+}
+function parseScalarBlock(block, source) {
+    const values = {};
+    for (const line of block.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const scalar = line.match(/^([a-z_]+):\s*([a-z_]+)\s*$/u);
+        if (scalar === null || values[scalar[1]] !== undefined) {
+            throw new Error(`OUTPUT_CHANNEL_INVALID source=${source}`);
+        }
+        values[scalar[1]] = scalar[2];
+    }
+    return values;
+}
+function parseOutputChannel(markdown, source) {
+    const block = outputChannelBlock(markdown);
+    if (block === undefined)
+        return undefined;
+    const parsed = parseScalarBlock(block, source);
+    const artifactGenre = parsed.artifact_genre;
+    const limitationsChannel = parsed.limitations_channel;
+    if (!isArtifactGenre(artifactGenre)) {
+        throw new Error(`OUTPUT_CHANNEL_GENRE_INVALID source=${source}`);
+    }
+    const expectedChannel = limitationsByGenre[artifactGenre];
+    if (expectedChannel !== limitationsChannel) {
+        throw new Error(`OUTPUT_CHANNEL_LIMITATIONS_MISMATCH source=${source}`);
+    }
+    return { artifactGenre, limitationsChannel: expectedChannel };
+}
+export async function readOutputChannelContract(skillId, root = defaultSkillsRoot) {
+    if (!/^[a-z][a-z0-9-]{0,63}$/u.test(skillId))
+        throw new Error(`OUTPUT_CHANNEL_SKILL_INVALID skill=${skillId}`);
+    const skillPath = path.join(root, skillId, "SKILL.md");
+    const direct = parseOutputChannel(await fs.readFile(skillPath, "utf8"), skillPath);
+    if (direct !== undefined)
+        return direct;
+    if (!lazyOutputChannelSkills.has(skillId))
+        throw new Error(`OUTPUT_CHANNEL_MISSING skill=${skillId}`);
+    const completeContractPath = path.join(root, skillId, "references", "complete-contract.md");
+    const referenced = parseOutputChannel(await fs.readFile(completeContractPath, "utf8"), completeContractPath);
+    if (referenced === undefined)
+        throw new Error(`OUTPUT_CHANNEL_MISSING skill=${skillId}`);
+    return referenced;
+}
+function canonicalSkillId(routeId) {
+    const normalized = routeId.trim().replace(/^\//u, "").toLowerCase();
+    if (normalized.startsWith("autoresearch-"))
+        return "autoresearch";
+    if (normalized.startsWith("autoconference-"))
+        return "autoconference";
+    if (normalized.startsWith("wikify-"))
+        return "wikify";
+    const aliases = Object.freeze({
+        lit: "workflow-loop",
+        "lit-loop": "workflow-loop",
+        "lit-work": "litwork",
+        litgoal: "durable-litgoal",
+        "lit-goal": "durable-litgoal",
+        "lit-research": "litresearch",
+        "text-neutralization": "lit-korean"
+    });
+    return aliases[normalized] ?? normalized;
+}
+export function createDeliverableHedgeSessionState(root = defaultSkillsRoot) {
+    const active = new Map();
+    return {
+        async activate(sessionID, routeId) {
+            const skillId = canonicalSkillId(routeId);
+            try {
+                if (!active.has(sessionID) && active.size >= maxTrackedSessions) {
+                    const oldest = active.keys().next().value;
+                    if (oldest !== undefined)
+                        active.delete(oldest);
+                }
+                active.set(sessionID, { skillId, contract: await readOutputChannelContract(skillId, root) });
+            }
+            catch {
+                active.delete(sessionID);
+            }
+        },
+        clear(sessionID) {
+            active.delete(sessionID);
+        },
+        dispose() {
+            active.clear();
+        },
+        contractFor(sessionID) {
+            return active.get(sessionID);
+        }
+    };
+}
+function quotedRangeContains(line, index) {
+    for (const quote of ['"', "'"]) {
+        let start = line.indexOf(quote);
+        while (start !== -1) {
+            const end = line.indexOf(quote, start + 1);
+            if (end === -1)
+                break;
+            if (start < index && index < end)
+                return true;
+            start = line.indexOf(quote, end + 1);
+        }
+    }
+    return false;
+}
+function isStateScalarOrTable(line) {
+    const scalar = /^\s*["']?[A-Za-z_][\w.-]*["']?\s*:\s*["']?(?:pending|deferred|보류\s*중)["']?\s*[,}]?\s*$/iu;
+    return scalar.test(line) || (line.includes("|") && /(?:status|state|상태|pending|deferred|보류\s*중)/iu.test(line));
+}
+function isAbsentEvidence(line) {
+    if (englishAbsence.test(line))
+        return true;
+    if (englishEpistemicInability.test(line) && evidenceSubject.test(line))
+        return true;
+    const hasEvidenceSubject = evidenceSubject.test(line);
+    const hasEvaluativeSubject = evaluativeSubject.test(line);
+    if (hasEvidenceSubject && (koreanAbsence.test(line) || koreanEpistemicInability.test(line)))
+        return true;
+    return hasEvaluativeSubject && koreanEpistemicInability.test(line) && /(?:없|부족|부재|제공되지|주어지지|확인되지|검증되지)/u.test(line);
+}
+function headingLevel(line) {
+    return line.match(/^(#{1,6})\s+/u)?.[1].length ?? 0;
+}
+function permittedLineMask(lines, genre) {
+    const permitted = lines.map(() => false);
+    if (genre === "working_note" || genre === "no_artifact")
+        return lines.map(() => true);
+    if (genre === "client_deliverable")
+        return permitted;
+    if (genre === "audit_report") {
+        const heading = lines.findIndex((line) => /^#{1,6}\s+.*(?:방법론|methodology)/iu.test(line));
+        if (heading === -1)
+            return permitted;
+        let began = false;
+        for (let index = heading + 1; index < lines.length; index += 1) {
+            if (/^#{1,6}\s+/u.test(lines[index]))
+                break;
+            if (lines[index].trim() === "") {
+                if (began)
+                    break;
+                continue;
+            }
+            began = true;
+            permitted[index] = true;
+        }
+        return permitted;
+    }
+    const heading = lines.findIndex((line) => /^#{1,6}\s+.*(?:한계|limitations?)/iu.test(line));
+    if (heading === -1)
+        return permitted;
+    const level = headingLevel(lines[heading]);
+    for (let index = heading + 1; index < lines.length; index += 1) {
+        const nextLevel = headingLevel(lines[index]);
+        if (nextLevel !== 0 && nextLevel <= level)
+            break;
+        permitted[index] = true;
+    }
+    return permitted;
+}
+export function inspectDeliverableHedges(text, genre) {
+    const lines = text.replaceAll("\r\n", "\n").split("\n");
+    const permitted = permittedLineMask(lines, genre);
+    const findings = [];
+    let fence;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const fenceMatch = line.match(/^\s*(```|~~~)/u)?.[1];
+        if (fenceMatch !== undefined) {
+            fence = fence === undefined ? fenceMatch : fence === fenceMatch ? undefined : fence;
+            continue;
+        }
+        if (fence !== undefined || permitted[index])
+            continue;
+        if (isAbsentEvidence(line))
+            findings.push({ className: "absent-evidence", line: index + 1 });
+        if (findings.length >= maxHedgeFindings)
+            break;
+        for (const candidate of phrasePatterns) {
+            candidate.pattern.lastIndex = 0;
+            const match = candidate.pattern.exec(line);
+            if (match === null)
+                continue;
+            if (candidate.className === "deferred" && (quotedRangeContains(line, match.index) || isStateScalarOrTable(line)))
+                continue;
+            findings.push({ className: candidate.className, line: index + 1 });
+            if (findings.length >= maxHedgeFindings)
+                break;
+        }
+        if (findings.length >= maxHedgeFindings)
+            break;
+    }
+    return findings;
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isReaderFacingPath(candidate) {
+    return !candidate.includes("\0") && readerFacingExtensions.has(path.extname(candidate).toLowerCase());
+}
+function toolInputText(input) {
+    if (!isPlainRecord(input.args))
+        return undefined;
+    const args = input.args;
+    const keys = textKeysByTool[input.tool];
+    if (keys === undefined)
+        return undefined;
+    const values = keys
+        .map((key) => args[key])
+        .filter((value) => typeof value === "string");
+    if (values.length !== 1)
+        return undefined;
+    const text = values[0];
+    if (Buffer.byteLength(text, "utf8") > maxArtifactBytes)
+        return undefined;
+    const paths = mutatedFilePaths(args);
+    return paths.some(isReaderFacingPath) ? text : undefined;
+}
+function boundedUtf8(text, maxBytes) {
+    if (Buffer.byteLength(text, "utf8") <= maxBytes)
+        return text;
+    let end = Math.min(text.length, maxBytes);
+    while (end > 0 && Buffer.byteLength(text.slice(0, end), "utf8") > maxBytes)
+        end -= 1;
+    return text.slice(0, end);
+}
+function modelVisibleContext(skillId, contract, findings) {
+    const uniqueLines = [...new Set(findings.map((finding) => finding.line))];
+    const reported = uniqueLines.slice(0, maxReportedLines);
+    const omitted = uniqueLines.length - reported.length;
+    const lines = `${reported.join(",")}${omitted > 0 ? `,+${omitted}` : ""}`;
+    return boundedUtf8(`DELIVERABLE_HEDGE_VIOLATION skill=${skillId} genre=${contract.artifactGenre} findings=${findings.length} lines=${lines}. Revise the artifact so limitations use ${contract.limitationsChannel}.`, maxAdditionalContextBytes);
+}
+export async function applyDeliverableHedgeAfterHook(state, input, output) {
+    const active = state.contractFor(input.sessionID);
+    if (active === undefined)
+        return;
+    const text = toolInputText(input);
+    if (text === undefined)
+        return;
+    const findings = inspectDeliverableHedges(text, active.contract.artifactGenre);
+    if (findings.length === 0)
+        return;
+    const context = modelVisibleContext(active.skillId, active.contract, findings);
+    output.output = output.output.trim().length === 0 ? context : `${output.output}\n\n${context}`;
+    output.metadata = {
+        ...output.metadata,
+        litopencodeDeliverableHedgeGuard: {
+            skillId: active.skillId,
+            artifactGenre: active.contract.artifactGenre,
+            findings: findings.length
+        }
+    };
+}

package/dist/durable-plan.d.ts

@@ -0,0 +1,23 @@
+export type ApprovedPlanRequest = {
+    readonly schemaVersion: 1;
+    readonly slug: string;
+    readonly markdown: string;
+    readonly approved: true;
+    readonly requestId: string;
+    readonly revision: number;
+    readonly expiresAt?: string;
+};
+export type DurablePlan = {
+    readonly relativePath: string;
+    readonly absolutePath: string;
+    readonly text: string;
+    readonly requestId: string;
+    readonly revision: number;
+    readonly expiresAt?: string;
+    readonly replayed?: boolean;
+};
+export declare function parsePlanSaveArgument(argumentsText: string): ApprovedPlanRequest | undefined;
+export declare function persistApprovedPlan(projectRoot: string, request: ApprovedPlanRequest): Promise<DurablePlan>;
+export declare function resolveLatestDurablePlan(projectRoot: string): Promise<DurablePlan | undefined>;
+export declare function formatResolvedPlanNotice(plan: DurablePlan): string;
+export declare function formatSavedPlanNotice(plan: DurablePlan, replayed: boolean): string;

package/dist/durable-plan.js

@@ -0,0 +1,349 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+const PLAN_DIRECTORY = path.join(".litopencode", "plans");
+const MAX_PLAN_BYTES = 256 * 1024;
+const MAX_ARGUMENT_BYTES = 512 * 1024;
+const PLAN_HEADER_PREFIX = "<!-- litopencode-durable-plan: ";
+const PLAN_HEADER_SUFFIX = " -->";
+const PLAN_LOCK_OWNER = "owner.json";
+const SAFE_REQUEST_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const SHA256 = /^[a-f0-9]{64}$/u;
+function hasErrorCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+async function acquirePlanLock(lockPath) {
+    const token = randomUUID();
+    while (true) {
+        try {
+            await fs.mkdir(lockPath, { mode: 0o700 });
+            break;
+        }
+        catch (error) {
+            if (!hasErrorCode(error, "EEXIST"))
+                throw error;
+            let stat;
+            try {
+                stat = await fs.lstat(lockPath);
+            }
+            catch (lockError) {
+                if (hasErrorCode(lockError, "ENOENT"))
+                    continue;
+                throw lockError;
+            }
+            if (stat.isSymbolicLink() || !stat.isDirectory())
+                throw new Error("unsafe plan persistence lock");
+            throw new Error("plan persistence lock is held");
+        }
+    }
+    const ownerPath = path.join(lockPath, PLAN_LOCK_OWNER);
+    try {
+        await fs.writeFile(ownerPath, `${JSON.stringify({ token, pid: process.pid })}\n`, {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600
+        });
+    }
+    catch (error) {
+        await fs.rmdir(lockPath).catch(() => undefined);
+        throw error;
+    }
+    return async () => {
+        let stat;
+        try {
+            stat = await fs.lstat(ownerPath);
+        }
+        catch (error) {
+            if (hasErrorCode(error, "ENOENT"))
+                return;
+            throw error;
+        }
+        if (stat.isSymbolicLink() || !stat.isFile())
+            throw new Error("unsafe plan persistence lock owner");
+        let owner;
+        try {
+            owner = JSON.parse(await fs.readFile(ownerPath, "utf8"));
+        }
+        catch (error) {
+            if (hasErrorCode(error, "ENOENT"))
+                return;
+            throw error;
+        }
+        if (!isRecord(owner) || owner.token !== token)
+            return;
+        await fs.rm(ownerPath, { force: true });
+        await fs.rmdir(lockPath).catch((error) => {
+            if (!hasErrorCode(error, "ENOENT"))
+                throw error;
+        });
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSafeSlug(value) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(value) && value.length <= 64;
+}
+function digest(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function normalizeMarkdown(markdown) {
+    return markdown.endsWith("\n") ? markdown : `${markdown}\n`;
+}
+function validExpiry(value) {
+    if (typeof value !== "string" || value.trim() === "")
+        return false;
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) && timestamp > Date.now();
+}
+function validSavedAt(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function validateRequest(request) {
+    if (!isSafeSlug(request.slug))
+        return "plan slug must be a lowercase hyphenated identifier";
+    if (request.schemaVersion !== 1)
+        return "plan schemaVersion must be 1";
+    if (request.approved !== true)
+        return "plan approval must be explicit";
+    if (typeof request.markdown !== "string" || request.markdown.trim() === "")
+        return "plan markdown must be non-empty";
+    if (!SAFE_REQUEST_ID.test(request.requestId))
+        return "plan requestId is invalid";
+    if (!Number.isSafeInteger(request.revision) || request.revision < 1)
+        return "plan revision must be a positive integer";
+    if (request.expiresAt !== undefined && !validExpiry(request.expiresAt))
+        return "plan expiry is stale or invalid";
+    const body = normalizeMarkdown(request.markdown);
+    const header = `${PLAN_HEADER_PREFIX}${JSON.stringify({
+        schemaVersion: 1,
+        slug: request.slug,
+        requestId: request.requestId,
+        revision: request.revision,
+        approved: true,
+        status: "active",
+        savedAt: new Date().toISOString(),
+        ...(request.expiresAt === undefined ? {} : { expiresAt: request.expiresAt }),
+        digest: digest(body)
+    })}${PLAN_HEADER_SUFFIX}\n`;
+    if (Buffer.byteLength(header + body, "utf8") > MAX_PLAN_BYTES)
+        return "plan markdown exceeds the durable size bound";
+    return "";
+}
+function requestFromRecord(value) {
+    const schemaVersion = value.schemaVersion === undefined ? 1 : value.schemaVersion;
+    const revision = value.revision === undefined ? 1 : value.revision;
+    const requestId = value.requestId === undefined && typeof value.slug === "string" && typeof value.markdown === "string"
+        ? `save-${digest(`${value.slug}\u0000${value.markdown}\u0000${String(revision)}`).slice(0, 32)}`
+        : value.requestId;
+    if (schemaVersion !== 1 ||
+        value.approved !== true ||
+        typeof value.slug !== "string" ||
+        typeof value.markdown !== "string" ||
+        typeof requestId !== "string" ||
+        typeof revision !== "number" ||
+        !Number.isSafeInteger(revision))
+        return undefined;
+    if (value.expiresAt !== undefined && typeof value.expiresAt !== "string")
+        return undefined;
+    const request = {
+        schemaVersion: 1,
+        slug: value.slug,
+        markdown: value.markdown,
+        approved: true,
+        requestId,
+        revision,
+        ...(value.expiresAt === undefined ? {} : { expiresAt: value.expiresAt })
+    };
+    return validateRequest(request) === "" ? request : undefined;
+}
+export function parsePlanSaveArgument(argumentsText) {
+    if (typeof argumentsText !== "string" || Buffer.byteLength(argumentsText, "utf8") > MAX_ARGUMENT_BYTES)
+        return undefined;
+    const match = /^save-plan\s+([\s\S]+)$/u.exec(argumentsText.trim());
+    if (match === null)
+        return undefined;
+    try {
+        const value = JSON.parse(match[1]);
+        return isRecord(value) ? requestFromRecord(value) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function metadataFromRequest(request, body) {
+    return {
+        schemaVersion: 1,
+        slug: request.slug,
+        requestId: request.requestId,
+        revision: request.revision,
+        approved: true,
+        status: "active",
+        savedAt: new Date().toISOString(),
+        ...(request.expiresAt === undefined ? {} : { expiresAt: request.expiresAt }),
+        digest: digest(body)
+    };
+}
+function serializePlan(metadata, body) {
+    return Buffer.from(`${PLAN_HEADER_PREFIX}${JSON.stringify(metadata)}${PLAN_HEADER_SUFFIX}\n${body}`, "utf8");
+}
+function validMetadata(value, slug, body) {
+    if (!isRecord(value))
+        return false;
+    if (value.schemaVersion !== 1 ||
+        value.slug !== slug ||
+        typeof value.requestId !== "string" ||
+        !SAFE_REQUEST_ID.test(value.requestId) ||
+        typeof value.revision !== "number" ||
+        !Number.isSafeInteger(value.revision) ||
+        value.revision < 1 ||
+        value.approved !== true ||
+        value.status !== "active" ||
+        !validSavedAt(value.savedAt) ||
+        (value.expiresAt !== undefined && !validExpiry(value.expiresAt)) ||
+        typeof value.digest !== "string" ||
+        !SHA256.test(value.digest) ||
+        value.digest !== digest(body))
+        return false;
+    return true;
+}
+function parseStoredPlan(text, slug) {
+    const newline = text.indexOf("\n");
+    if (newline < 0)
+        return undefined;
+    const header = text.slice(0, newline);
+    if (!header.startsWith(PLAN_HEADER_PREFIX) || !header.endsWith(PLAN_HEADER_SUFFIX))
+        return undefined;
+    let metadata;
+    try {
+        metadata = JSON.parse(header.slice(PLAN_HEADER_PREFIX.length, -PLAN_HEADER_SUFFIX.length));
+    }
+    catch {
+        return undefined;
+    }
+    const body = text.slice(newline + 1);
+    if (body.trim() === "" || !validMetadata(metadata, slug, body))
+        return undefined;
+    return { metadata, text: body };
+}
+async function readStoredPlan(filePath, slug) {
+    let stat;
+    try {
+        stat = await fs.lstat(filePath);
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size === 0 || stat.size > MAX_PLAN_BYTES)
+        return undefined;
+    try {
+        return parseStoredPlan(await fs.readFile(filePath, "utf8"), slug);
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+}
+function toDurablePlan(directory, name, stored) {
+    return {
+        relativePath: path.join(PLAN_DIRECTORY, name),
+        absolutePath: path.join(directory, name),
+        text: stored.text,
+        requestId: stored.metadata.requestId,
+        revision: stored.metadata.revision,
+        ...(stored.metadata.expiresAt === undefined ? {} : { expiresAt: stored.metadata.expiresAt })
+    };
+}
+export async function persistApprovedPlan(projectRoot, request) {
+    const validationError = validateRequest(request);
+    if (validationError !== "")
+        throw new Error(validationError);
+    const body = normalizeMarkdown(request.markdown);
+    const directory = path.join(projectRoot, PLAN_DIRECTORY);
+    const name = `${request.slug}.md`;
+    const absolutePath = path.join(directory, name);
+    const lockPath = `${absolutePath}.lock`;
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    const releaseLock = await acquirePlanLock(lockPath);
+    try {
+        const existing = await readStoredPlan(absolutePath, request.slug);
+        if (existing !== undefined) {
+            if (existing.metadata.requestId === request.requestId) {
+                if (existing.metadata.revision === request.revision && existing.metadata.digest === digest(body)) {
+                    return { ...toDurablePlan(directory, name, existing), replayed: true };
+                }
+                throw new Error("repeated plan request conflicts with the existing durable plan");
+            }
+            if (request.revision <= existing.metadata.revision)
+                throw new Error("stale plan revision");
+        }
+        else {
+            try {
+                await fs.lstat(absolutePath);
+                throw new Error("plan target exists but is not a valid approved durable plan");
+            }
+            catch (error) {
+                if (!hasErrorCode(error, "ENOENT"))
+                    throw error;
+            }
+        }
+        const metadata = metadataFromRequest(request, body);
+        const encoded = serializePlan(metadata, body);
+        if (encoded.byteLength > MAX_PLAN_BYTES)
+            throw new Error("plan markdown exceeds the durable size bound");
+        const staging = `${absolutePath}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await fs.writeFile(staging, encoded, { flag: "wx", mode: 0o600 });
+            await fs.rename(staging, absolutePath);
+        }
+        finally {
+            await fs.rm(staging, { force: true });
+        }
+        return { ...toDurablePlan(directory, name, { metadata, text: body }), replayed: false };
+    }
+    finally {
+        await releaseLock();
+    }
+}
+export async function resolveLatestDurablePlan(projectRoot) {
+    const directory = path.join(projectRoot, PLAN_DIRECTORY);
+    let names;
+    try {
+        names = await fs.readdir(directory);
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+    const candidates = [];
+    for (const name of names) {
+        if (!name.endsWith(".md") || !isSafeSlug(name.slice(0, -3)))
+            continue;
+        const absolutePath = path.join(directory, name);
+        try {
+            const stored = await readStoredPlan(absolutePath, name.slice(0, -3));
+            if (stored === undefined)
+                continue;
+            candidates.push({
+                plan: toDurablePlan(directory, name, stored),
+                savedAt: Date.parse(stored.metadata.savedAt)
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    candidates.sort((left, right) => right.savedAt - left.savedAt || right.plan.revision - left.plan.revision || left.plan.relativePath.localeCompare(right.plan.relativePath));
+    return candidates[0]?.plan;
+}
+export function formatResolvedPlanNotice(plan) {
+    return `Durable plan: ${plan.relativePath}. Discovery only. This does not grant start-work authority.\n\n<durable-plan>\n${plan.text}</durable-plan>`;
+}
+export function formatSavedPlanNotice(plan, replayed) {
+    const verb = replayed ? "Durable plan already persisted" : "Saved durable plan";
+    return `${verb}: ${plan.relativePath}. Discovery only. This does not grant start-work authority.`;
+}