@jitsusama/agentic-harness.core 0.1.0

package/dist/quest/lifecycle.js

@@ -0,0 +1,900 @@
+/**
+ * Lifecycle mutations for the quest workflow: focus, unfocus,
+ * document stage, journey entries, aliasing, reordering,
+ * priority/status/parent changes, session attach/detach.
+ *
+ * Everything here operates on a `QuestState` value and plain
+ * arguments, with no dependency on an adapter's own extension API
+ * or session log. The pi-only counterparts -- loading a quest
+ * (which sets pi's session name), persisting/restoring the loaded
+ * quest across a pi session (which reads/writes pi's own session
+ * log), and pruning phantom sessions against pi's session-log
+ * directory -- stay in agentic-harness.pi's own lifecycle.ts,
+ * which imports the mutations here for everything else.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, } from "node:fs";
+import { join } from "node:path";
+import { buildAliasIndex, } from "../internal/quest/alias-index.js";
+import { appendJourneyByPath } from "../internal/quest/append-journey.js";
+import { nowYmd } from "../internal/quest/dates.js";
+import { discoverQuests, siblingRanks, } from "../internal/quest/discovery.js";
+import { explainDocumentFrontMatter } from "../internal/quest/frontmatter.js";
+import { atomicWriteFile, atomicWriteUnderLock } from "../internal/quest/io.js";
+import { mutateQuestFrontMatter } from "../internal/quest/mutate.js";
+import { currentInstanceId, currentProcessIdentity, } from "../internal/quest/process-liveness.js";
+import { diffRanks, nextRank, after as rankAfter, before as rankBefore, bottom as rankBottom, bump as rankBump, renumber as rankRenumber, sink as rankSink, top as rankTop, } from "../internal/quest/ranking.js";
+import { isSealedStatus } from "../internal/quest/status.js";
+import { identifyCurrentTerminal } from "../terminal/index.js";
+import { checkboxProgress, documentFrontMatterProblem, parseDocumentFrontMatter, parseQuestDoc, serializeDocumentFrontMatter, } from "./index.js";
+/**
+ * Persist the focused document's progress (or, when no
+ * document is focused, the loaded quest's) into the
+ * QuestState struct so the widget can paint without
+ * re-parsing the body on every keystroke.
+ *
+ * Uses the broad `checkboxProgress` walk so every `- [ ]`
+ * / `- [x]` in the body contributes regardless of which
+ * section holds it. The plan, research, brief and report
+ * templates each use a different section name for their
+ * work list; one counter serves them all.
+ */
+export function refreshProgress(state) {
+    if (state.documentPath) {
+        try {
+            const text = readFileSync(state.documentPath, "utf8");
+            const parsed = parseDocumentFrontMatter(text);
+            if (parsed) {
+                const progress = checkboxProgress(parsed.body);
+                state.done = progress.done;
+                state.total = progress.total;
+                state.currentItem = progress.currentItem;
+                state.documentStage = parsed.frontMatter.stage;
+                return;
+            }
+        }
+        catch {
+            // Document missing or unreadable; fall through.
+        }
+    }
+    if (state.questDir) {
+        try {
+            const text = readFileSync(join(state.questDir, "README.md"), "utf8");
+            const parsed = parseQuestDoc(text);
+            if (parsed) {
+                const progress = checkboxProgress(parsed.body);
+                state.done = progress.done;
+                state.total = progress.total;
+                state.currentItem = progress.currentItem;
+                return;
+            }
+        }
+        catch {
+            // Quest missing; fall through.
+        }
+    }
+    state.done = 0;
+    state.total = 0;
+    state.currentItem = undefined;
+}
+/** Find a quest entry by id across the quests root. */
+export function findQuestEntry(state, id) {
+    const { index } = discoverQuests(state.questsRoot);
+    return index.quests.get(id);
+}
+/**
+ * Load a quest by id into `state`: the state-mutation half of pi's
+ * own `loadQuest`. pi's version additionally calls
+ * `pi.setSessionName?.()` once this succeeds -- a pi-only
+ * enrichment with no equivalent host concept, so it stays out of
+ * this pure version; an adapter that wants it layers it on after
+ * calling this.
+ */
+export function loadQuestById(state, id) {
+    const entry = findQuestEntry(state, id);
+    if (!entry) {
+        return {
+            ok: false,
+            guidance: `No quest with id "${id}" under ${state.questsRoot}.`,
+        };
+    }
+    state.questDir = entry.dir;
+    state.questId = entry.doc.frontMatter.id;
+    state.questTitle = entry.doc.title ?? null;
+    state.questKind = entry.doc.frontMatter.kind;
+    state.questStatus = entry.doc.frontMatter.status;
+    state.questPriority = entry.doc.frontMatter.priority;
+    state.questVerify = entry.doc.frontMatter.verify ?? null;
+    state.scratchDir = entry.doc.frontMatter.scratchDir ?? null;
+    state.documentPath = null;
+    state.documentId = null;
+    state.documentKind = null;
+    state.documentTitle = null;
+    state.documentStage = "idle";
+    refreshProgress(state);
+    return { ok: true };
+}
+/**
+ * Re-read the loaded quest's README and refresh the in-memory
+ * slice (title, kind, status, priority) so an edit to the quest's
+ * own README shows up in the status line without a manual reload.
+ * No-op when no quest is loaded or the README cannot be read.
+ */
+export function refreshLoadedSlice(state) {
+    if (!state.questDir)
+        return;
+    let text;
+    try {
+        text = readFileSync(join(state.questDir, "README.md"), "utf8");
+    }
+    catch {
+        // README missing or unreadable; leave the slice as-is.
+        return;
+    }
+    const parsed = parseQuestDoc(text);
+    if (!parsed)
+        return;
+    state.questTitle = parsed.title ?? null;
+    state.questKind = parsed.frontMatter.kind;
+    state.questStatus = parsed.frontMatter.status;
+    state.questPriority = parsed.frontMatter.priority;
+    state.questVerify = parsed.frontMatter.verify ?? null;
+    state.scratchDir = parsed.frontMatter.scratchDir ?? null;
+}
+/** Unload the currently loaded quest. */
+export function unloadQuest(state) {
+    state.questDir = null;
+    state.questId = null;
+    state.questTitle = null;
+    state.questKind = null;
+    state.questStatus = null;
+    state.questPriority = null;
+    state.questVerify = null;
+    state.scratchDir = null;
+    state.documentPath = null;
+    state.documentId = null;
+    state.documentKind = null;
+    state.documentTitle = null;
+    state.documentStage = "idle";
+    state.done = 0;
+    state.total = 0;
+}
+/** Focus a document under the loaded quest. */
+export function focusDocument(state, docPath) {
+    if (!state.questDir) {
+        return { ok: false, guidance: "Load a quest first." };
+    }
+    let text;
+    try {
+        text = readFileSync(docPath, "utf8");
+    }
+    catch (err) {
+        return {
+            ok: false,
+            guidance: `Cannot read ${docPath}: ${err.message}`,
+        };
+    }
+    const parsed = parseDocumentFrontMatter(text);
+    if (!parsed) {
+        // Which field, not just that one is wrong. The answer used to be found
+        // by diffing the file against a sibling document.
+        return {
+            ok: false,
+            guidance: `Cannot focus ${docPath}: ${documentFrontMatterProblem(text) ?? "its front-matter will not parse"}.`,
+        };
+    }
+    state.documentPath = docPath;
+    state.documentId = parsed.frontMatter.id;
+    state.documentKind = parsed.frontMatter.kind;
+    state.documentTitle = extractTitle(parsed.body);
+    state.documentStage = parsed.frontMatter.stage;
+    refreshProgress(state);
+    return { ok: true };
+}
+/** Unfocus the active document. */
+export function unfocusDocument(state) {
+    state.documentPath = null;
+    state.documentId = null;
+    state.documentKind = null;
+    state.documentTitle = null;
+    state.documentStage = "idle";
+    refreshProgress(state);
+}
+/**
+ * Persist the focused document's stage to its file and mirror it in
+ * state. Returns true when the stage reached disk, false when there
+ * is nothing to write to or the file is unreadable or unparseable,
+ * so the caller can refuse rather than let memory run ahead of disk.
+ */
+export function writeDocumentStage(state, stage) {
+    if (!state.documentPath)
+        return false;
+    const questDir = state.questDir;
+    let text;
+    try {
+        text = readFileSync(state.documentPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const parsed = parseDocumentFrontMatter(text);
+    if (!parsed)
+        return false;
+    const newFm = {
+        ...parsed.frontMatter,
+        stage: stage,
+        updated: nowYmd(),
+    };
+    const newText = `${serializeDocumentFrontMatter(newFm)}\n${parsed.body}`;
+    // Validate by parse-back, matching the quest mutation core: never
+    // write a document the strict parser cannot read back, which would
+    // drop it to an out-of-vocabulary stage and make it invisible.
+    const reparsed = parseDocumentFrontMatter(newText);
+    if (!reparsed || reparsed.frontMatter.stage !== newFm.stage)
+        return false;
+    const documentPath = state.documentPath;
+    if (questDir) {
+        atomicWriteUnderLock(questDir, documentPath, newText);
+    }
+    else {
+        atomicWriteFile(documentPath, newText);
+    }
+    state.documentStage = stage;
+    return true;
+}
+const DOC_KIND_DIRS = ["plans", "research", "briefs", "reports"];
+const ACTIVE_DOC_STAGES = new Set(["think", "draft", "build"]);
+/**
+ * Seal every still-active document under a quest to the quest's
+ * terminal stage, so concluding or retiring a quest does not leave
+ * documents stranded mid-stage. Returns how many were sealed.
+ * Best-effort per file: an unreadable document is skipped, not fatal.
+ */
+export function sealQuestDocuments(questDir, target) {
+    let sealed = 0;
+    for (const kindDir of DOC_KIND_DIRS) {
+        const dir = join(questDir, kindDir);
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith(".md"))
+                continue;
+            const docPath = join(dir, entry.name);
+            let text;
+            try {
+                text = readFileSync(docPath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const parsed = parseDocumentFrontMatter(text);
+            if (!parsed)
+                continue;
+            if (!ACTIVE_DOC_STAGES.has(parsed.frontMatter.stage))
+                continue;
+            const newFm = {
+                ...parsed.frontMatter,
+                stage: target,
+                updated: nowYmd(),
+            };
+            const sealedText = `${serializeDocumentFrontMatter(newFm)}\n${parsed.body}`;
+            // Validate by parse-back before writing, so the seal can never
+            // produce a document the strict parser drops to invisible.
+            const reparsed = parseDocumentFrontMatter(sealedText);
+            if (!reparsed || reparsed.frontMatter.stage !== target)
+                continue;
+            atomicWriteUnderLock(questDir, docPath, sealedText);
+            sealed++;
+        }
+    }
+    return sealed;
+}
+/** Append a Journey entry to the loaded quest's README. */
+export function appendJourneyEntry(state, prose) {
+    if (!state.questDir)
+        return;
+    const ok = appendJourneyByPath(state.questDir, prose);
+    if (!ok) {
+        console.warn(`[quest] failed to append Journey entry to ${state.questDir}; README missing or unreadable.`);
+        return;
+    }
+    stampQuestUpdated(state);
+}
+/** Update the loaded quest's `updated` frontmatter to today. */
+export function stampQuestUpdated(state) {
+    if (!state.questDir)
+        return;
+    // The identity transform still stamps updated in the core, so a
+    // touch is validated and locked like every other quest write.
+    mutateQuestFrontMatter(state.questDir, (fm) => fm);
+}
+function extractTitle(body) {
+    const match = /^#\s+(.+)$/m.exec(body);
+    return match ? match[1].trim() : null;
+}
+/** Create a new document under the loaded quest. */
+export function createDocument(state, opts) {
+    if (!state.questDir)
+        return undefined;
+    const subDir = {
+        plan: "plans",
+        research: "research",
+        brief: "briefs",
+        report: "reports",
+    };
+    // Born readable or not born at all, the same rule the quest README
+    // writers meet. This is the writer that produced the five documents
+    // found invisible to discovery, and repairing the reader to fail
+    // open and explain itself left this end of it untouched: a document
+    // whose front matter will not parse is written, reported as drafted,
+    // and never listed again.
+    const complaints = explainDocumentFrontMatter(opts.scaffoldBody);
+    if (complaints.length > 0)
+        return undefined;
+    const dir = join(state.questDir, subDir[opts.kind]);
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${opts.id}.md`);
+    // New document; scaffold atomically. Subsequent writes go
+    // through writeDocumentStage which holds the lock too.
+    atomicWriteUnderLock(state.questDir, path, opts.scaffoldBody);
+    return path;
+}
+/**
+ * Inventory every working tree recorded across all quests,
+ * attributing each to its owning quest. This is what lets the
+ * harness-created trees be seen and reaped in one place instead
+ * of being a mystery pile of directories.
+ */
+export function inventoryWorktrees(state) {
+    const { index } = discoverQuests(state.questsRoot);
+    const entries = [];
+    for (const quest of index.quests.values()) {
+        const fm = quest.doc.frontMatter;
+        for (const tree of fm.trees ?? []) {
+            const entry = {
+                path: tree.path,
+                questId: fm.id,
+                questTitle: quest.doc.title ?? null,
+                exists: existsSync(tree.path),
+            };
+            if (tree.branch)
+                entry.branch = tree.branch;
+            entries.push(entry);
+        }
+    }
+    return entries.sort((a, b) => a.path.localeCompare(b.path));
+}
+/** Discover quests for /quest-list etc. */
+export function listAllQuests(state) {
+    const { index } = discoverQuests(state.questsRoot);
+    return [...index.quests.values()];
+}
+/** Ensure the quests root exists on disk. */
+export function ensureQuestsRoot(state) {
+    if (!existsSync(state.questsRoot)) {
+        mkdirSync(state.questsRoot, { recursive: true });
+    }
+}
+/**
+ * Reorder the sibling set the given quest belongs to.
+ * Siblings share both `parent` and `priority`. Writes the
+ * updated rank back to every quest whose rank changed.
+ */
+export function reorderSiblings(state, questId, action) {
+    const { index } = discoverQuests(state.questsRoot);
+    const pivot = index.quests.get(questId);
+    if (!pivot) {
+        return {
+            ok: false,
+            guidance: `No quest with id "${questId}" under ${state.questsRoot}.`,
+        };
+    }
+    if (isSealedStatus(pivot.doc.frontMatter.status)) {
+        return {
+            ok: false,
+            guidance: `Quest "${questId}" is ${pivot.doc.frontMatter.status}; reopen it before reordering.`,
+        };
+    }
+    const siblings = [];
+    for (const entry of index.quests.values()) {
+        if (entry.doc.frontMatter.parent === pivot.doc.frontMatter.parent &&
+            entry.doc.frontMatter.priority === pivot.doc.frontMatter.priority &&
+            !isSealedStatus(entry.doc.frontMatter.status)) {
+            siblings.push(entry);
+        }
+    }
+    const before = siblings.map((e) => ({
+        id: e.doc.frontMatter.id,
+        rank: e.doc.frontMatter.rank,
+    }));
+    let after;
+    switch (action.kind) {
+        case "top":
+            after = rankTop(before, questId);
+            break;
+        case "bottom":
+            after = rankBottom(before, questId);
+            break;
+        case "bump":
+            after = rankBump(before, questId);
+            break;
+        case "sink":
+            after = rankSink(before, questId);
+            break;
+        case "before":
+            after = rankBefore(before, questId, action.target);
+            break;
+        case "after":
+            after = rankAfter(before, questId, action.target);
+            break;
+        case "renumber":
+            after = rankRenumber(before);
+            break;
+    }
+    const changes = diffRanks(before, after);
+    const rankById = new Map(after.map((e) => [e.id, e.rank]));
+    for (const entry of siblings) {
+        const newRank = rankById.get(entry.doc.frontMatter.id);
+        if (newRank === undefined)
+            continue;
+        if (newRank === entry.doc.frontMatter.rank)
+            continue;
+        writeQuestRank(entry.dir, newRank);
+    }
+    return { ok: true, result: { siblings, changes } };
+}
+function writeQuestRank(questDir, rank) {
+    // Routed through the validated mutation core so a rank write is
+    // validated and stamped the same way every other field write is.
+    mutateQuestFrontMatter(questDir, (fm) => ({ ...fm, rank }));
+}
+/**
+ * Set a quest's rank by directory. The by-dir counterpart to the
+ * internal `writeQuestRank`, exported so undo can reverse a journalled
+ * rank change (a reparent re-ranks into its new sibling set).
+ */
+export function setQuestRankByDir(questDir, rank) {
+    const result = writeQuestFrontMatter(questDir, (fm) => ({ ...fm, rank }));
+    if (!result.ok)
+        return result;
+    return { ok: true };
+}
+/**
+ * Set any journalled field by directory, through the lens that knows
+ * how to write it.
+ *
+ * Undo used to reach for one exported setter per field and cast the
+ * journalled string to that field's type on the way in. The lens
+ * checks the value against the field's vocabulary instead, so a
+ * journal entry carrying a word the vocabulary has since lost is
+ * refused with a reason rather than written back unexamined.
+ */
+export function setQuestFieldByDir(questDir, lens, value) {
+    let refusal;
+    const result = writeQuestFrontMatter(questDir, (fm) => {
+        const written = lens.write(fm, value);
+        if (written.ok)
+            return written.fm;
+        refusal = written.reason;
+        return undefined;
+    });
+    if (refusal)
+        return { ok: false, guidance: refusal };
+    if (!result.ok)
+        return result;
+    return { ok: true };
+}
+/** Build a reverse alias index across every discovered quest. */
+export function buildQuestsAliasIndex(state) {
+    const { index } = discoverQuests(state.questsRoot);
+    return buildAliasIndex(index);
+}
+function writeQuestFrontMatter(questDir, mutate) {
+    const result = mutateQuestFrontMatter(questDir, mutate);
+    if (!result.ok)
+        return result;
+    return { ok: true, fm: result.fm };
+}
+/**
+ * Set a quest's parent by directory, stamping `updated` and
+ * appending a Journey entry. Used by the reparent verb, which
+ * may move quests other than the loaded one.
+ */
+export function setQuestParent(questDir, newParent) {
+    const result = writeQuestFrontMatter(questDir, (fm) => ({
+        ...fm,
+        parent: newParent,
+    }));
+    if (!result.ok)
+        return result;
+    appendJourneyByPath(questDir, `Reparented to ${newParent ?? "top level"}.`);
+    return { ok: true };
+}
+/** Set a quest's status by directory, stamping `updated`. */
+export function setQuestStatusByDir(questDir, status) {
+    const result = writeQuestFrontMatter(questDir, (fm) => ({ ...fm, status }));
+    if (!result.ok)
+        return result;
+    return { ok: true };
+}
+/**
+ * Set a quest's priority by directory (the by-id counterpart to
+ * `setLoadedPriority`). Used by the bulk seal cascade and by undo
+ * when it reverses a journalled priority change.
+ */
+export function setQuestPriorityByDir(questDir, priority) {
+    const result = writeQuestFrontMatter(questDir, (fm) => ({ ...fm, priority }));
+    if (!result.ok)
+        return result;
+    return { ok: true };
+}
+/**
+ * Add one or more aliases to the loaded quest in a single front-matter
+ * write, so a list either lands whole or not at all and no partial
+ * state survives a failure. Aliases already present, and duplicates
+ * within the batch, are reported as already and added only once.
+ */
+export function addAliasesToLoaded(state, aliases) {
+    if (!state.questDir)
+        return { ok: false, guidance: "Load a quest first." };
+    let added = [];
+    let already = [];
+    const result = writeQuestFrontMatter(state.questDir, (fm) => {
+        // Reset on every invocation so a retried write does not
+        // accumulate duplicate report entries.
+        added = [];
+        already = [];
+        const next = [...fm.aliases];
+        for (const alias of aliases) {
+            const present = next.some((a) => a.type === alias.type && a.value === alias.value);
+            if (present) {
+                already.push(alias);
+                continue;
+            }
+            added.push(alias);
+            next.push(alias);
+        }
+        return { ...fm, aliases: next };
+    });
+    if (!result.ok)
+        return result;
+    return { ok: true, added, already };
+}
+/** Remove an alias from the loaded quest. */
+export function removeAliasFromLoaded(state, alias) {
+    if (!state.questDir)
+        return { ok: false, guidance: "Load a quest first." };
+    let removed = false;
+    const result = writeQuestFrontMatter(state.questDir, (fm) => {
+        const next = fm.aliases.filter((a) => !(a.type === alias.type && a.value === alias.value));
+        if (next.length === fm.aliases.length)
+            return undefined;
+        removed = true;
+        return { ...fm, aliases: next };
+    });
+    if (!result.ok)
+        return result;
+    return { ok: true, removed };
+}
+/**
+ * Remove one or more aliases from the loaded quest in a single write,
+ * the batch counterpart to addAliasesToLoaded. Reports which were
+ * removed and which were absent, so the verb can signal a partial or
+ * whole no-op the same way the add path does.
+ */
+export function removeAliasesFromLoaded(state, aliases) {
+    if (!state.questDir)
+        return { ok: false, guidance: "Load a quest first." };
+    let removed = [];
+    let absent = [];
+    const result = writeQuestFrontMatter(state.questDir, (fm) => {
+        removed = [];
+        absent = [];
+        const drop = (a) => aliases.some((t) => t.type === a.type && t.value === a.value);
+        for (const target of aliases) {
+            if (fm.aliases.some((a) => a.type === target.type && a.value === target.value)) {
+                removed.push(target);
+            }
+            else {
+                absent.push(target);
+            }
+        }
+        if (removed.length === 0)
+            return undefined;
+        return { ...fm, aliases: fm.aliases.filter((a) => !drop(a)) };
+    });
+    if (!result.ok)
+        return result;
+    return { ok: true, removed, absent };
+}
+/** Attach a session id to the loaded quest. */
+export function attachSessionToLoaded(state, session) {
+    if (!state.questDir)
+        return { ok: false, guidance: "Load a quest first." };
+    let added = false;
+    const result = writeQuestFrontMatter(state.questDir, (fm) => {
+        const existing = fm.sessions.find((s) => s.id === session.id);
+        if (existing) {
+            // Refresh status to active and merge any new fields, but keep
+            // the original started: it records when the session first
+            // touched this quest, not the latest attach. Letting the
+            // incoming started win would defeat the no-op guard below and
+            // churn the README on every load.
+            const merged = {
+                ...existing,
+                ...session,
+                started: existing.started ?? session.started,
+                status: "active",
+            };
+            if (JSON.stringify(merged) === JSON.stringify(existing)) {
+                return undefined;
+            }
+            return {
+                ...fm,
+                sessions: fm.sessions.map((s) => (s.id === session.id ? merged : s)),
+            };
+        }
+        added = true;
+        const next = { status: "active", ...session };
+        return { ...fm, sessions: [...fm.sessions, next] };
+    });
+    if (!result.ok)
+        return result;
+    return { ok: true, added };
+}
+/**
+ * Capture the current process's liveness identity for a session
+ * attach: its instance id, OS process identity and the terminal
+ * surface it runs in (when a driver recognises one). Read once at
+ * attach time; the stored handle is what a later reader probes.
+ */
+export function captureSessionIdentity() {
+    const handle = identifyCurrentTerminal();
+    return {
+        instanceId: currentInstanceId(),
+        process: currentProcessIdentity(),
+        terminal: handle
+            ? {
+                driverId: handle.driverId,
+                value: handle.value,
+                scope: handle.scope,
+                hostId: handle.hostId,
+            }
+            : undefined,
+    };
+}
+/**
+ * Attach the current session to the loaded quest.
+ *
+ * This is the automatic-capture path: a session-start or load flow
+ * calls it so a quest's sessions frontmatter records where work
+ * happened without the user attaching by hand. It refreshes an
+ * existing record rather than duplicating, and no-ops cleanly when
+ * no quest is loaded or the session id is unknown.
+ */
+export function attachCurrentSession(state, opts) {
+    // An ephemeral session has an id but writes no log, so attaching it
+    // would leave a phantom entry that can never be resumed. Skip it;
+    // only a persisted session earns a record.
+    if (opts.persisted === false)
+        return { attached: false };
+    if (!state.questDir || !opts.id)
+        return { attached: false };
+    const session = {
+        id: opts.id,
+        started: new Date().toISOString(),
+        status: "active",
+    };
+    if (opts.cwd?.trim())
+        session.cwd = opts.cwd.trim();
+    if (opts.instanceId)
+        session.instanceId = opts.instanceId;
+    if (opts.process)
+        session.process = opts.process;
+    if (opts.terminal)
+        session.terminal = opts.terminal;
+    const result = attachSessionToLoaded(state, session);
+    return { attached: result.ok };
+}
+/**
+ * Detach a session only when the caller's process instance owns the
+ * record, so a process that resumed a session is not detached by the
+ * delayed shutdown of the process that used to hold it. A record with
+ * no recorded instance id is legacy and detaches unconditionally,
+ * preserving the pre-lease behaviour.
+ */
+export function detachSessionIfOwner(questDir, sessionId, instanceId) {
+    let detached = false;
+    const result = writeQuestFrontMatter(questDir, (fm) => {
+        let hit = false;
+        const next = fm.sessions.map((s) => {
+            if (s.id !== sessionId || s.status === "detached")
+                return s;
+            // A different live instance owns the record: leave it be.
+            if (s.instanceId !== undefined && s.instanceId !== instanceId)
+                return s;
+            hit = true;
+            return { ...s, status: "detached" };
+        });
+        if (!hit)
+            return undefined;
+        detached = true;
+        return { ...fm, sessions: next };
+    });
+    if (!result.ok)
+        return result;
+    return { ok: true, detached };
+}
+/** Mark a session as detached on the loaded quest. */
+export function detachSessionFromLoaded(state, sessionId) {
+    if (!state.questDir)
+        return { ok: false, guidance: "Load a quest first." };
+    return detachSessionInQuestDir(state.questDir, sessionId);
+}
+/**
+ * Reconcile a session's membership so it reads active on exactly one
+ * quest: detach the session from every quest other than the one being
+ * kept. The switch path already releases the immediate prior quest;
+ * this catches stragglers left by earlier runs or a lost state, so a
+ * session never lingers active on several quests at once. Returns the
+ * ids it detached the session from.
+ */
+export function reconcileSessionMembership(state, sessionId, keepQuestId) {
+    const { index } = discoverQuests(state.questsRoot);
+    const detachedFrom = [];
+    for (const entry of index.quests.values()) {
+        const fm = entry.doc.frontMatter;
+        if (fm.id === keepQuestId)
+            continue;
+        const holdsActive = fm.sessions.some((s) => s.id === sessionId && s.status !== "detached");
+        if (!holdsActive)
+            continue;
+        const result = detachSessionInQuestDir(entry.dir, sessionId);
+        if (result.ok && result.detached)
+            detachedFrom.push(fm.id);
+    }
+    return detachedFrom;
+}
+export function detachSessionInQuestDir(questDir, sessionId) {
+    let detached = false;
+    const result = writeQuestFrontMatter(questDir, (fm) => {
+        let hit = false;
+        const next = fm.sessions.map((s) => {
+            if (s.id !== sessionId)
+                return s;
+            if (s.status === "detached")
+                return s;
+            hit = true;
+            return { ...s, status: "detached" };
+        });
+        if (!hit)
+            return undefined;
+        detached = true;
+        return { ...fm, sessions: next };
+    });
+    if (!result.ok)
+        return result;
+    return { ok: true, detached };
+}
+const PRIORITY_ORDER = [
+    "driving",
+    "active",
+    "queued",
+    "bench",
+    "someday",
+];
+/** Set the loaded quest's priority bucket. */
+export function setLoadedPriority(state, priority) {
+    if (!state.questDir)
+        return { ok: false, guidance: "Load a quest first." };
+    let changed = false;
+    const result = writeQuestFrontMatter(state.questDir, (fm) => {
+        if (fm.priority === priority)
+            return undefined;
+        changed = true;
+        // Append to the end of the destination bucket rather than
+        // colliding at rank 1: take the next free rank in the target
+        // (parent, priority) group, excluding the quest being moved.
+        const { index } = discoverQuests(state.questsRoot);
+        const destRanks = siblingRanks(index, fm.parent ?? null, priority, fm.id);
+        return { ...fm, priority, rank: nextRank(destRanks) };
+    });
+    if (!result.ok)
+        return result;
+    if (changed) {
+        state.questPriority = priority;
+    }
+    return { ok: true, changed };
+}
+/**
+ * Change the loaded quest's kind. A subquest needs a parent to rank
+ * within, so refuse the move to subquest when the quest has none.
+ * Returns whether the kind actually changed.
+ */
+export function setLoadedKind(state, kind) {
+    if (!state.questDir)
+        return { ok: false, guidance: "Load a quest first." };
+    let changed = false;
+    let refusal;
+    const result = writeQuestFrontMatter(state.questDir, (fm) => {
+        if (fm.kind === kind)
+            return undefined;
+        if (kind === "subquest" && (fm.parent ?? null) === null) {
+            refusal =
+                "A subquest needs a parent to rank within; reparent it under a quest first.";
+            return undefined;
+        }
+        changed = true;
+        return { ...fm, kind };
+    });
+    if (refusal)
+        return { ok: false, guidance: refusal };
+    if (!result.ok)
+        return result;
+    return { ok: true, changed };
+}
+/** Shift the loaded quest one bucket up or down the priority ladder. */
+export function bumpLoadedPriority(state, direction) {
+    if (!state.questDir || !state.questPriority) {
+        return { ok: false, guidance: "Load a quest first." };
+    }
+    const i = PRIORITY_ORDER.indexOf(state.questPriority);
+    if (i < 0)
+        return { ok: false, guidance: "Unknown priority on the loaded quest." };
+    const step = direction === "up" ? -1 : 1;
+    const j = Math.min(PRIORITY_ORDER.length - 1, Math.max(0, i + step));
+    const next = PRIORITY_ORDER[j];
+    const from = state.questPriority;
+    if (next === from)
+        return { ok: true, from, to: from };
+    const result = setLoadedPriority(state, next);
+    if (!result.ok)
+        return result;
+    return { ok: true, from, to: next };
+}
+/** Set the loaded quest's coarse status enum. */
+export function setLoadedStatus(state, status) {
+    if (!state.questDir)
+        return { ok: false, guidance: "Load a quest first." };
+    let changed = false;
+    const result = writeQuestFrontMatter(state.questDir, (fm) => {
+        if (fm.status === status)
+            return undefined;
+        changed = true;
+        return { ...fm, status };
+    });
+    if (!result.ok)
+        return result;
+    if (changed) {
+        state.questStatus = status;
+    }
+    return { ok: true, changed };
+}
+/** Rename a session on the loaded quest. */
+export function renameSessionOnLoaded(state, sessionId, name) {
+    if (!state.questDir)
+        return { ok: false, guidance: "Load a quest first." };
+    let renamed = false;
+    const result = writeQuestFrontMatter(state.questDir, (fm) => {
+        let hit = false;
+        const next = fm.sessions.map((s) => {
+            if (s.id !== sessionId)
+                return s;
+            if (s.name === name)
+                return s;
+            hit = true;
+            return { ...s, name };
+        });
+        if (!hit)
+            return undefined;
+        renamed = true;
+        return { ...fm, sessions: next };
+    });
+    if (!result.ok)
+        return result;
+    return { ok: true, renamed };
+}