@astrosheep/keiyaku 1.0.0 → 1.0.2

package/build/core/stored-agent-event.js

@@ -0,0 +1,101 @@
+import { activityEventBodySchema, AGENT_EVENT_TEXT_MAX_CHARS, AGENT_UNKNOWN_PAYLOAD_MAX_CHARS, } from "../agents/harness/index.js";
+import { EXEC_EVENT_BUFFER_HARD_CAP } from "../agents/harness/event-channel.js";
+import { isSubagentProvider } from "../keiyaku.js";
+const FAIL_CODES = new Set(["SUBAGENT_TIMEOUT", "SUBAGENT_NON_ZERO_EXIT", "SUBAGENT_SPAWN_ERROR", "SUBAGENT_EXEC_ERROR", "SUBAGENT_PROVIDER_UNAVAILABLE", "PROJECTION_STATE_ERROR"]);
+const KNOWN = new Set(["message", "unknown", "activity", "thought", "plan", "turn", "usage", "warning", "diagnostic", "truncation", "done", "fail"]);
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+const optionalString = (value, key) => value[key] === undefined || typeof value[key] === "string";
+export function classifyStoredAgentEvent(value) {
+    if (!record(value) || typeof value.type !== "string")
+        return "malformed";
+    if (value.type === "action")
+        return "malformed";
+    if (!KNOWN.has(value.type))
+        return "unknown";
+    if (typeof value.at !== "string"
+        || !Number.isFinite(Date.parse(value.at))
+        || !Number.isInteger(value.seq)
+        || !Number.isSafeInteger(value.turn)
+        || value.turn < 0)
+        return "malformed";
+    switch (value.type) {
+        case "message": return typeof value.text === "string" ? "valid" : "malformed";
+        case "unknown": {
+            if (typeof value.provider !== "string" || value.provider.length > AGENT_EVENT_TEXT_MAX_CHARS ||
+                typeof value.nativeType !== "string" || value.nativeType.length > AGENT_EVENT_TEXT_MAX_CHARS ||
+                typeof value.payload !== "string" || value.payload.length > AGENT_UNKNOWN_PAYLOAD_MAX_CHARS ||
+                (value.truncated !== undefined && value.truncated !== true))
+                return "malformed";
+            if (value.elided === undefined)
+                return "valid";
+            if (!record(value.elided))
+                return "malformed";
+            if (value.elided.reason !== "truncated" && value.elided.reason !== "unserializable")
+                return "malformed";
+            if (!Number.isInteger(value.elided.retainedChars) || value.elided.retainedChars < 0)
+                return "malformed";
+            if (value.elided.retainedChars !== value.payload.length)
+                return "malformed";
+            if (value.elided.originalChars !== undefined && (!Number.isInteger(value.elided.originalChars) || value.elided.originalChars < 0))
+                return "malformed";
+            if (value.elided.reason === "truncated" && (!Number.isInteger(value.elided.originalChars) || value.elided.originalChars <= value.payload.length))
+                return "malformed";
+            return "valid";
+        }
+        case "activity": {
+            const { seq: _seq, at: _at, turn: _turn, ...body } = value;
+            return activityEventBodySchema.safeParse(body).success ? "valid" : "malformed";
+        }
+        case "thought": return typeof value.id === "string" && typeof value.text === "string" && typeof value.final === "boolean" && (value.truncated === undefined || value.truncated === true) ? "valid" : "malformed";
+        case "plan": return typeof value.id === "string" && Array.isArray(value.items) && value.items.every((item) => record(item) && typeof item.text === "string" && typeof item.done === "boolean" && (item.active === undefined || item.active === true)) ? "valid" : "malformed";
+        case "turn": return value.phase === "started" || value.phase === "completed" ? "valid" : "malformed";
+        case "usage": return finite(value.inputTokens) && finite(value.outputTokens) && (value.cachedInputTokens === undefined || finite(value.cachedInputTokens)) && (value.costUsd === undefined || finite(value.costUsd)) && optionalString(value, "model") ? "valid" : "malformed";
+        case "warning": return record(value.warning) && (value.warning.reason === "refusal" || value.warning.reason === "overload") && optionalString(value.warning, "originalModel") && optionalString(value.warning, "fallbackModel") && optionalString(value.warning, "direction") && (value.warning.requestId === undefined || value.warning.requestId === null || typeof value.warning.requestId === "string") && optionalString(value.warning, "signerModel") ? "valid" : "malformed";
+        case "diagnostic": return typeof value.text === "string" ? "valid" : "malformed";
+        case "truncation": {
+            return Number.isInteger(value.limit)
+                && Number.isInteger(value.admitted)
+                && value.limit >= 0
+                && value.admitted >= 0
+                && value.limit === EXEC_EVENT_BUFFER_HARD_CAP
+                && value.admitted === EXEC_EVENT_BUFFER_HARD_CAP
+                ? "valid"
+                : "malformed";
+        }
+        case "done": return optionalString(value, "finalMessage") && record(value.session) && typeof value.session.provider === "string" && isSubagentProvider(value.session.provider) && finite(value.session.version) && Number.isInteger(value.session.version) && value.session.version > 0 && "handle" in value.session ? "valid" : "malformed";
+        case "fail": return typeof value.message === "string" && (value.code === undefined || (typeof value.code === "string" && FAIL_CODES.has(value.code))) && (value.exitCode === undefined || value.exitCode === null || finite(value.exitCode)) && optionalString(value, "diagnostics") ? "valid" : "malformed";
+    }
+    return "unknown";
+}
+export function selectValidStoredAgentEvents(values) {
+    const events = [];
+    const activityTools = new Map();
+    let malformed = 0;
+    for (const value of values) {
+        const shape = classifyStoredAgentEvent(value);
+        if (shape === "valid") {
+            const event = value;
+            if (event.type === "activity") {
+                const priorTool = activityTools.get(event.id);
+                if (priorTool !== undefined && priorTool !== event.tool) {
+                    malformed += 1;
+                    continue;
+                }
+                activityTools.set(event.id, event.tool);
+            }
+            events.push(event);
+        }
+        if (shape === "malformed")
+            malformed += 1;
+    }
+    return { events, malformed };
+}
+export function invalidActivityEventDiagnostic(malformed) {
+    return malformed > 0
+        ? {
+            kind: "invalid-activity-event",
+            detail: `${malformed} persisted activity event${malformed === 1 ? "" : "s"} malformed`,
+        }
+        : undefined;
+}

package/build/core/transcripts.js

@@ -1,286 +1,272 @@
+import { randomBytes } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { RESPONSE_ARTIFACT_NOTICE, RESPONSE_HISTORY_DIR } from "../keiyaku.js";
+import { parseResolvedAkumaLaunchSnapshot, } from "../agents/launch-snapshot_v2.js";
 import { resolvePersistedSubagentSession } from "../agents/session.js";
 import { isErrnoException } from "../errno.js";
 import { FlowError, requireText } from "../flow-error.js";
+import { getCurrentBranch } from "../git/branches.js";
+import { getLatestCommitHash } from "../git/staging.js";
+import { RESPONSE_ARTIFACT_NOTICE, RESPONSE_HISTORY_DIR } from "../keiyaku.js";
+import { parseExecutionCoordinates } from "./execution-coordinate.js";
+import { createUlid } from "./ids.js";
 import { parseToAST } from "./markdown/parser.js";
 const RESPONSE_HISTORY_SLUG_MAX_LENGTH = 24;
 const RESPONSE_HISTORY_SESSION_KEY = "session";
+const RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY = "launch_snapshot";
+const RESPONSE_HISTORY_PROVENANCE_KEY = "provenance";
 const REVIEW_HISTORY_FILE_RE = /^\d{8}-\d{9}_REVIEW_(\d+)\.md$/;
+export const RESPONSE_ARTIFACT_ID_RE = /^rsp_[0-9A-HJKMNP-TV-Z]{26}$/;
 export const RESPONSE_ARTIFACT_HEADINGS = {
-    summon: "# Summon",
+    call: "# Call",
     bind: "# Bind",
     arc: "# Arc",
     renew: "# Renew",
     review: "# Review",
 };
 const RESUMABLE_RESPONSE_HEADINGS = Object.values(RESPONSE_ARTIFACT_HEADINGS);
-function toTimestampParts(now) {
-    const year = String(now.getFullYear());
-    const month = String(now.getMonth() + 1).padStart(2, "0");
-    const day = String(now.getDate()).padStart(2, "0");
-    const hour = String(now.getHours()).padStart(2, "0");
-    const minute = String(now.getMinutes()).padStart(2, "0");
-    const second = String(now.getSeconds()).padStart(2, "0");
-    const millisecond = String(now.getMilliseconds()).padStart(3, "0");
-    return {
-        fileStamp: `${year}${month}${day}-${hour}${minute}${second}${millisecond}`,
-        iso: now.toISOString(),
-    };
+function artifactError(locator, field, reason) {
+    return new FlowError("INVALID_RESPONSE_PATH", `Invalid response artifact '${locator}': field '${field}' ${reason}.`);
 }
-function toSlug(text, fallback) {
-    const normalized = text.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-");
-    const truncated = normalized
-        .slice(0, RESPONSE_HISTORY_SLUG_MAX_LENGTH)
-        .replace(/^-+/, "")
-        .replace(/-+$/, "");
-    return truncated || fallback;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function toYamlSingleQuoted(value) {
-    return `'${value.replace(/'/g, "''")}'`;
+function assertExactFields(value, required, locator, prefix) {
+    for (const field of required) {
+        if (!(field in value))
+            throw artifactError(locator, `${prefix}.${field}`, "is missing");
+    }
+    const allowed = new Set(required);
+    const unknown = Object.keys(value).filter((field) => !allowed.has(field)).sort()[0];
+    if (unknown !== undefined)
+        throw artifactError(locator, `${prefix}.${unknown}`, "is unknown");
 }
-function toSectionBody(value) {
-    const trimmed = value?.trim();
-    return trimmed && trimmed.length > 0 ? value : "(none)";
+function nonBlank(value, locator, field) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw artifactError(locator, field, "must be a non-blank string");
 }
-function buildResponseHistoryMarkdown(input, timestampIso) {
-    const branch = input.branch?.trim() || "(unknown)";
-    const commit = input.commit?.trim();
-    const sessionText = input.session ? JSON.stringify(input.session) : undefined;
-    const subagentName = input.subagentName?.trim();
-    const frontMatterLines = [
-        "---",
-        `branch: ${toYamlSingleQuoted(branch)}`,
-        ...(commit ? [`commit: ${toYamlSingleQuoted(commit)}`] : []),
-        ...(sessionText ? [`${RESPONSE_HISTORY_SESSION_KEY}: ${toYamlSingleQuoted(sessionText)}`] : []),
-        ...(subagentName ? [`subagent_name: ${toYamlSingleQuoted(subagentName)}`] : []),
-        ...(input.effectivePolicy ? [`effective_policy: ${toYamlSingleQuoted(JSON.stringify(input.effectivePolicy))}`] : []),
-        `time: ${toYamlSingleQuoted(timestampIso)}`,
-        `notice: ${toYamlSingleQuoted(RESPONSE_ARTIFACT_NOTICE)}`,
-        "---",
-        "",
-    ];
-    if (input.tool === "summon") {
-        return [
-            ...frontMatterLines,
-            "# Summon",
-            "",
-            "## Task",
-            toSectionBody(input.task),
-            "",
-            "## Context",
-            toSectionBody(input.context),
-            "",
-            "## Response",
-            toSectionBody(input.response),
-            "",
-        ].join("\n");
+/** The sole durable provenance parser. */
+export function parseResponseArtifactProvenance(value, locator) {
+    if (!isRecord(value))
+        throw artifactError(locator, "provenance", "must be an object");
+    assertExactFields(value, ["artifactId", "authority", "binding", "evidence"], locator, "provenance");
+    nonBlank(value.artifactId, locator, "provenance.artifactId");
+    if (!RESPONSE_ARTIFACT_ID_RE.test(value.artifactId)) {
+        throw artifactError(locator, "provenance.artifactId", "must be rsp_ followed by a ULID");
     }
-    if (input.tool === "review") {
-        return [
-            ...frontMatterLines,
-            "# Review",
-            "",
-            "## Prompt",
-            toSectionBody(input.prompt),
-            "",
-            "## Response",
-            toSectionBody(input.response),
-            "",
-        ].join("\n");
+    const { authority, binding } = parseExecutionCoordinates(value.authority, value.binding, (field, reason) => artifactError(locator, `provenance.${field}`, reason));
+    if (!isRecord(value.evidence))
+        throw artifactError(locator, "provenance.evidence", "must be an object");
+    if (authority.kind === "repository") {
+        assertExactFields(value.evidence, ["branch", "commit"], locator, "provenance.evidence");
+        nonBlank(value.evidence.branch, locator, "provenance.evidence.branch");
+        nonBlank(value.evidence.commit, locator, "provenance.evidence.commit");
+        return { artifactId: value.artifactId, authority, binding, evidence: { branch: value.evidence.branch, commit: value.evidence.commit } };
     }
-    if (input.tool === "arc") {
-        return [
-            ...frontMatterLines,
-            "# Arc",
-            "",
-            "## Objective",
-            toSectionBody(input.objective),
-            "",
-            "## Brief",
-            toSectionBody(input.brief),
-            "",
-            "## Ledger Commit",
-            toSectionBody(input.ledgerCommit),
-            "",
-            "## Summary",
-            toSectionBody(input.summary),
-            "",
-            "## Diff",
-            toSectionBody(input.diff),
-            "",
-        ].join("\n");
+    assertExactFields(value.evidence, ["workdir"], locator, "provenance.evidence");
+    nonBlank(value.evidence.workdir, locator, "provenance.evidence.workdir");
+    if (!path.isAbsolute(value.evidence.workdir)) {
+        throw artifactError(locator, "provenance.evidence.workdir", "must be an absolute path");
     }
-    return [
-        ...frontMatterLines,
-        "# Renew",
-        "",
-        "## Base",
-        `${input.oldBase} -> ${input.newBase}`,
-        "",
-        "## Head",
-        `${input.oldHead} -> ${input.newHead}`,
-        "",
-        "## Ledger Commit",
-        toSectionBody(input.ledgerCommit),
-        "",
-        "## Summary",
-        toSectionBody(input.summary),
-        "",
-        "## Diff",
-        toSectionBody(input.diff),
-        "",
-    ].join("\n");
+    return { artifactId: value.artifactId, authority, binding, evidence: { workdir: value.evidence.workdir } };
 }
+async function captureArtifactEvidence(coordinate) {
+    const evidenceCwd = path.resolve(coordinate.evidenceCwd);
+    if (coordinate.authority.kind === "user")
+        return { workdir: evidenceCwd };
+    const [branch, commit] = await Promise.all([getCurrentBranch(evidenceCwd), getLatestCommitHash(evidenceCwd)]);
+    if (!branch.trim())
+        throw artifactError("new response artifact", "provenance.evidence.branch", "must be a non-blank string");
+    if (!commit.trim())
+        throw artifactError("new response artifact", "provenance.evidence.commit", "must be a non-blank string");
+    return { branch, commit };
+}
+function timestampParts(now) {
+    const part = (value, width) => String(value).padStart(width, "0");
+    return {
+        fileStamp: `${now.getFullYear()}${part(now.getMonth() + 1, 2)}${part(now.getDate(), 2)}-${part(now.getHours(), 2)}${part(now.getMinutes(), 2)}${part(now.getSeconds(), 2)}${part(now.getMilliseconds(), 3)}`,
+        iso: now.toISOString(),
+    };
+}
+function slug(text, fallback) {
+    return text.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, RESPONSE_HISTORY_SLUG_MAX_LENGTH).replace(/^-+|-+$/g, "") || fallback;
+}
+function yamlQuote(value) { return `'${value.replace(/'/g, "''")}'`; }
+function section(value) { return value?.trim() ? value : "(none)"; }
+function buildMarkdown(input, iso, provenance) {
+    const frontmatter = [
+        "---",
+        `${RESPONSE_HISTORY_PROVENANCE_KEY}: ${yamlQuote(JSON.stringify(provenance))}`,
+        ...(input.session ? [`${RESPONSE_HISTORY_SESSION_KEY}: ${yamlQuote(JSON.stringify(input.session))}`] : []),
+        ...(input.launchSnapshot ? [`${RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY}: ${yamlQuote(JSON.stringify(input.launchSnapshot))}`] : []),
+        ...(input.subagentName?.trim() ? [`subagent_name: ${yamlQuote(input.subagentName.trim())}`] : []),
+        ...(input.effectivePolicy ? [`effective_policy: ${yamlQuote(JSON.stringify(input.effectivePolicy))}`] : []),
+        `time: ${yamlQuote(iso)}`,
+        `notice: ${yamlQuote(RESPONSE_ARTIFACT_NOTICE)}`,
+        "---", "",
+    ];
+    if (input.tool === "call")
+        return [...frontmatter, "# Call", "", "## Task", section(input.task), "", "## Context", section(input.context), "", "## Response", section(input.response), ""].join("\n");
+    if (input.tool === "review")
+        return [...frontmatter, "# Review", "", "## Prompt", section(input.prompt), "", "## Response", section(input.response), ""].join("\n");
+    if (input.tool === "arc")
+        return [...frontmatter, "# Arc", "", "## Objective", section(input.objective), "", "## Brief", section(input.brief), "", "## Ledger Commit", section(input.ledgerCommit), "", "## Summary", section(input.summary), "", "## Diff", section(input.diff), ""].join("\n");
+    return [...frontmatter, "# Renew", "", "## Base", `${input.oldBase} -> ${input.newBase}`, "", "## Head", `${input.oldHead} -> ${input.newHead}`, "", "## Ledger Commit", section(input.ledgerCommit), "", "## Summary", section(input.summary), "", "## Diff", section(input.diff), ""].join("\n");
+}
+/** The sole response artifact writer. */
 export async function persistResponseHistory(input) {
+    const coordinates = parseExecutionCoordinates(input.provenance.authority, input.provenance.binding, (field, reason) => artifactError("new response artifact", `provenance.${field}`, reason));
     const now = input.now ?? new Date();
-    const { fileStamp, iso } = toTimestampParts(now);
-    const slug = toSlug(input.title ?? "", input.tool);
-    const toolNameForFile = input.tool.toUpperCase();
+    const artifactId = `rsp_${createUlid(now.getTime(), [...randomBytes(10)])}`;
+    const provenance = {
+        artifactId,
+        ...coordinates,
+        evidence: await captureArtifactEvidence({ ...input.provenance, ...coordinates }),
+    };
+    const { fileStamp, iso } = timestampParts(now);
     const historyDir = path.join(input.cwd, RESPONSE_HISTORY_DIR);
-    const responsePath = path.join(historyDir, `${fileStamp}_${toolNameForFile}_${slug}.md`);
-    const markdown = buildResponseHistoryMarkdown(input, iso);
+    const responsePath = path.join(historyDir, `${fileStamp}_${input.tool.toUpperCase()}_${slug(input.title ?? "", input.tool)}.md`);
     await fs.mkdir(historyDir, { recursive: true });
-    await fs.writeFile(responsePath, markdown, "utf-8");
-    return path.relative(input.cwd, responsePath);
+    await fs.writeFile(responsePath, buildMarkdown(input, iso, provenance), "utf8");
+    return { artifactId, responsePath: path.relative(input.cwd, responsePath) };
 }
-export async function nextReviewResponseNumber(cwd) {
-    const historyDir = path.join(cwd, RESPONSE_HISTORY_DIR);
-    let names;
+function detectTool(document) {
+    const lines = document.split("\n");
+    let index = 0;
+    if (lines[0] === "---") {
+        index = lines.indexOf("---", 1);
+        if (index < 0)
+            return null;
+        index += 1;
+    }
+    for (; index < lines.length; index += 1) {
+        const line = lines[index].trim();
+        if (!line)
+            continue;
+        const found = Object.entries(RESPONSE_ARTIFACT_HEADINGS).find(([, heading]) => heading === line);
+        return found?.[0] ?? null;
+    }
+    return null;
+}
+export async function readResponseArtifact(input) {
+    const locator = requireText("responsePath", input.responsePath);
+    const absolutePath = path.isAbsolute(locator) ? locator : path.resolve(input.cwd, locator);
+    let document;
     try {
-        names = await fs.readdir(historyDir);
+        document = await fs.readFile(absolutePath, "utf8");
     }
     catch (error) {
-        if (isErrnoException(error) && error.code === "ENOENT") {
-            return 1;
-        }
+        if (isErrnoException(error) && (error.code === "ENOENT" || error.code === "EISDIR"))
+            throw new FlowError("INVALID_RESPONSE_PATH", `Response artifact not found: '${locator}'.`);
         throw error;
     }
-    const maxReview = names.reduce((max, name) => {
-        const match = REVIEW_HISTORY_FILE_RE.exec(name);
-        if (!match)
-            return max;
-        return Math.max(max, Number(match[1]));
-    }, 0);
-    return maxReview + 1;
-}
-export async function listResumableResponseCandidates(cwd, limit) {
-    const historyDir = path.join(cwd, RESPONSE_HISTORY_DIR);
-    let names;
+    const ast = parseToAST(document);
+    const frontmatter = ast.frontmatter?.entries;
+    if (!frontmatter)
+        throw artifactError(locator, "provenance", "is missing");
+    if (frontmatter.notice !== RESPONSE_ARTIFACT_NOTICE)
+        throw artifactError(locator, "notice", "does not identify a Keiyaku response artifact");
+    const rawProvenance = frontmatter[RESPONSE_HISTORY_PROVENANCE_KEY];
+    if (rawProvenance === undefined)
+        throw artifactError(locator, "provenance", "is missing");
+    let provenanceValue;
     try {
-        names = await fs.readdir(historyDir);
+        provenanceValue = JSON.parse(rawProvenance);
     }
     catch (error) {
-        if (isErrnoException(error) && error.code === "ENOENT") {
-            return [];
-        }
-        throw error;
+        throw artifactError(locator, "provenance", `contains malformed JSON${error instanceof Error ? ` (${error.message})` : ""}`);
+    }
+    const provenance = parseResponseArtifactProvenance(provenanceValue, locator);
+    const tool = detectTool(document);
+    if (!tool)
+        throw artifactError(locator, "artifactType", "is unsupported");
+    if (input.allowedTools?.length && !input.allowedTools.includes(tool)) {
+        if (input.onArtifactTypeMismatch === "return-null")
+            return undefined;
+        throw artifactError(locator, "artifactType", `must be ${input.allowedTools.join("/")}`);
     }
-    const candidates = [];
-    const sorted = names
-        .filter((name) => name.endsWith(".md"))
-        .sort((left, right) => right.localeCompare(left));
-    for (const name of sorted) {
-        const relativePath = path.join(RESPONSE_HISTORY_DIR, name);
+    const session = frontmatter[RESPONSE_HISTORY_SESSION_KEY] === undefined ? undefined : resolvePersistedSubagentSession({ resumePath: locator, sessionText: frontmatter[RESPONSE_HISTORY_SESSION_KEY] });
+    let launchSnapshot;
+    const rawLaunchSnapshot = frontmatter[RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY];
+    if (rawLaunchSnapshot !== undefined) {
+        let launchSnapshotValue;
         try {
-            const resolution = await resolveSummonResumePath({ cwd, resumePath: relativePath });
-            candidates.push({ path: relativePath, subagentName: resolution.subagentName });
+            launchSnapshotValue = JSON.parse(rawLaunchSnapshot);
         }
         catch (error) {
-            if (isFlowErrorCode(error, "INVALID_RESPONSE_PATH")) {
-                continue;
-            }
-            throw error;
+            throw artifactError(locator, RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY, `contains malformed JSON${error instanceof Error ? ` (${error.message})` : ""}`);
+        }
+        try {
+            launchSnapshot = parseResolvedAkumaLaunchSnapshot(launchSnapshotValue);
         }
-        if (limit !== undefined && candidates.length >= limit) {
-            break;
+        catch (error) {
+            throw artifactError(locator, RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY, `is invalid${error instanceof Error ? ` (${error.message})` : ""}`);
         }
     }
-    return candidates;
+    const subagentName = frontmatter.subagent_name?.trim() || undefined;
+    const storageRoot = path.resolve(path.dirname(absolutePath), "..", "..");
+    return { artifactId: provenance.artifactId, responsePath: path.relative(input.cwd, absolutePath), absolutePath, storageRoot, provenance, tool, ...(session ? { session } : {}), ...(launchSnapshot ? { launchSnapshot } : {}), ...(subagentName ? { subagentName } : {}) };
 }
-export async function resolveResumePath(cwd, explicitPath) {
-    if (explicitPath)
-        return explicitPath;
-    const candidates = await listResumableResponseCandidates(cwd, 4);
-    if (candidates.length === 1) {
-        return candidates[0].path;
+export async function locateResponseArtifact(cwd, artifactId) {
+    const identity = requireText("artifactId", artifactId);
+    if (!RESPONSE_ARTIFACT_ID_RE.test(identity))
+        throw artifactError(identity, "provenance.artifactId", "must be rsp_ followed by a ULID");
+    const historyDir = path.join(cwd, RESPONSE_HISTORY_DIR);
+    let names;
+    try {
+        names = await fs.readdir(historyDir);
     }
-    if (candidates.length === 0) {
-        throw new FlowError("EMPTY_PARAM", "resume requires a response path because no resumable response artifacts were found.");
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT")
+            throw new FlowError("INVALID_RESPONSE_PATH", `Response artifact '${identity}' was not found in ${historyDir}.`);
+        throw error;
     }
-    const shown = candidates.slice(0, 3).map((candidate) => `- ${candidate.path}`);
-    throw new FlowError("EMPTY_PARAM", ["resume found multiple resumable response artifacts; choose one explicitly:", ...shown].join("\n"));
-}
-function isFlowErrorCode(error, code) {
-    return error instanceof FlowError && error.code === code;
-}
-function detectArtifactHeading(document) {
-    const lines = document.split("\n");
-    let index = 0;
-    if (lines[0] === "---") {
-        index = 1;
-        while (index < lines.length && lines[index] !== "---") {
-            index += 1;
-        }
-        if (index === lines.length) {
-            return null;
+    let match;
+    for (const name of names.filter((candidate) => candidate.endsWith(".md")).sort()) {
+        const responsePath = path.join(RESPONSE_HISTORY_DIR, name);
+        const document = await fs.readFile(path.join(cwd, responsePath), "utf8");
+        const encoded = parseToAST(document).frontmatter?.entries?.[RESPONSE_HISTORY_PROVENANCE_KEY];
+        if (encoded === undefined)
+            continue;
+        let indexed;
+        try {
+            indexed = JSON.parse(encoded);
         }
-        index += 1;
-    }
-    for (; index < lines.length; index += 1) {
-        const line = lines[index].trim();
-        if (line.length === 0) {
+        catch {
             continue;
         }
-        return RESUMABLE_RESPONSE_HEADINGS.find((heading) => heading === line) ?? null;
+        if (!isRecord(indexed) || indexed.artifactId !== identity)
+            continue;
+        const parsed = await readResponseArtifact({ cwd, responsePath });
+        if (!parsed)
+            continue;
+        if (match)
+            throw new FlowError("INVALID_RESPONSE_PATH", `Response artifact identity '${identity}' is duplicated in ${historyDir}.`);
+        match = parsed;
     }
-    return null;
+    if (!match)
+        throw new FlowError("INVALID_RESPONSE_PATH", `Response artifact '${identity}' was not found in ${historyDir}.`);
+    return match;
 }
-export async function resolveSummonResumePath(input) {
-    const responsePath = requireText("resumePath", input.resumePath);
-    const resolvedPath = path.isAbsolute(responsePath) ? responsePath : path.resolve(input.cwd, responsePath);
-    let document;
+export function requireResumableArtifact(artifact) {
+    if (!artifact.session)
+        throw artifactError(artifact.artifactId, RESPONSE_HISTORY_SESSION_KEY, "is missing; this conversation cannot be revived");
+    if (!artifact.subagentName)
+        throw artifactError(artifact.artifactId, "subagent_name", "is missing; this conversation cannot be revived");
+    if (!artifact.launchSnapshot)
+        throw artifactError(artifact.artifactId, RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY, "is missing; this conversation cannot be revived");
+    return artifact;
+}
+export async function nextReviewResponseNumber(cwd) {
+    const historyDir = path.join(cwd, RESPONSE_HISTORY_DIR);
+    let names;
     try {
-        document = await fs.readFile(resolvedPath, "utf-8");
+        names = await fs.readdir(historyDir);
     }
     catch (error) {
-        if (isErrnoException(error) && (error.code === "ENOENT" || error.code === "EISDIR")) {
-            throw new FlowError("INVALID_RESPONSE_PATH", `Resume path file not found: '${responsePath}'.`);
-        }
+        if (isErrnoException(error) && error.code === "ENOENT")
+            return 1;
         throw error;
     }
-    const ast = parseToAST(document);
-    const frontmatter = ast.frontmatter?.entries;
-    if (!frontmatter) {
-        throw new FlowError("INVALID_RESPONSE_PATH", `Resume path file '${responsePath}' is missing YAML frontmatter.`);
-    }
-    if (frontmatter.notice !== RESPONSE_ARTIFACT_NOTICE) {
-        throw new FlowError("INVALID_RESPONSE_PATH", `Resume path file '${responsePath}' is not a Keiyaku response artifact.`);
-    }
-    const artifactHeading = detectArtifactHeading(document);
-    if (!artifactHeading) {
-        throw new FlowError("INVALID_RESPONSE_PATH", `Resume path file '${responsePath}' is not a supported Keiyaku response artifact.`);
-    }
-    if (input.allowedTools?.length) {
-        const allowedHeadings = input.allowedTools.map((tool) => RESPONSE_ARTIFACT_HEADINGS[tool]);
-        if (!allowedHeadings.includes(artifactHeading)) {
-            if (input.onArtifactTypeMismatch === "return-null") {
-                return undefined;
-            }
-            throw new FlowError("INVALID_RESPONSE_PATH", `Resume path file '${responsePath}' is not a supported ${input.allowedTools.join("/")} response artifact.`);
-        }
-    }
-    const session = resolvePersistedSubagentSession({
-        resumePath: responsePath,
-        sessionText: frontmatter[RESPONSE_HISTORY_SESSION_KEY],
-    });
-    if (!session) {
-        throw new FlowError("INVALID_RESPONSE_PATH", `Resume path file '${responsePath}' does not include '${RESPONSE_HISTORY_SESSION_KEY}'; this conversation cannot be resumed.`);
-    }
-    const subagentName = frontmatter.subagent_name?.trim();
-    if (!subagentName) {
-        throw new FlowError("INVALID_RESPONSE_PATH", `Resume path file '${responsePath}' does not include 'subagent_name'; this conversation cannot be resumed.`);
-    }
-    return { session, subagentName };
+    return names.reduce((max, name) => Math.max(max, Number(REVIEW_HISTORY_FILE_RE.exec(name)?.[1] ?? 0)), 0) + 1;
 }