@jitsusama/agentic-harness.core 0.1.0

package/dist/quest/verbs/structural.js

@@ -0,0 +1,310 @@
+/**
+ * Structural verbs: reparent (single or bulk). These move
+ * quests within the tree under an explicit scope, offer a
+ * dry-run preview and report exactly what changed, so a cleanup
+ * can be trusted and reversed.
+ */
+import { appendJourneyByPath } from "../../internal/quest/append-journey.js";
+import { discoverQuests, siblingRanks, } from "../../internal/quest/discovery.js";
+import { lensForField } from "../../internal/quest/fields.js";
+import { nextRank } from "../../internal/quest/ranking.js";
+import { isSealedStatus } from "../../internal/quest/status.js";
+import { planReparent, planStatusChange, } from "../../internal/quest/structural.js";
+import { dropLastStructuralOp, lastStructuralOp, recordStructuralOp, } from "../../internal/quest/structural-journal.js";
+import { count, verb } from "../../ui/count.js";
+import { sealQuestDocuments, setQuestFieldByDir, setQuestParent, setQuestPriorityByDir, setQuestRankByDir, setQuestStatusByDir, } from "../lifecycle.js";
+import { ok, refuse, } from "./shared.js";
+/**
+ * Reparent one or more quests under a new parent (or to top
+ * level with `parent: null`). The whole batch is atomic: if any
+ * target is missing or would form a cycle, nothing is written.
+ * With `dryRun`, the plan is returned without any writes.
+ */
+export function reparent(state, params) {
+    const targets = (params.id ?? "")
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    if (targets.length === 0) {
+        return refuse("Pass the quest id to move in `id`, comma-separated for a batch.");
+    }
+    if (params.parent === undefined) {
+        return refuse("Pass the new `parent` quest id, or `null` to move to top level.");
+    }
+    const newParent = params.parent === "null" ? null : params.parent.trim();
+    const { index } = discoverQuests(state.questsRoot);
+    const plan = planReparent(index, targets, newParent);
+    if (plan.errors.length > 0) {
+        return refuse(`Refusing the batch; nothing was moved:\n- ${plan.errors.join("\n- ")}`);
+    }
+    if (plan.changes.length === 0) {
+        return ok("Nothing to reparent; every target is already there.", {
+            changes: [],
+            dryRun: Boolean(params.dryRun),
+        });
+    }
+    if (params.dryRun) {
+        const lines = plan.changes
+            .map((c) => `  ${c.id}: ${c.oldParent ?? "top level"} -> ${c.newParent ?? "top level"}`)
+            .join("\n");
+        return ok(`Dry run: would reparent ${count(plan.changes.length, "quest")}.\n${lines}`, { changes: plan.changes, dryRun: true });
+    }
+    // Journal incrementally: record each write the moment it lands so
+    // a mid-batch failure leaves the journal reflecting exactly what
+    // is on disk, and undo can reverse the partial application.
+    //
+    // A moved quest leaves its old sibling set and joins a new one, so
+    // its old rank can collide there. Place it at the next free rank in
+    // the destination (parent, priority) group and journal the rank
+    // change too, so undo restores both. `taken` tracks ranks claimed
+    // this batch so several quests moved into the same group get
+    // distinct ranks rather than all landing on the same next free one.
+    const applied = [];
+    const takenByGroup = new Map();
+    const placeRank = (parent, priority) => {
+        const key = `${parent ?? ""}|${priority}`;
+        let taken = takenByGroup.get(key);
+        if (!taken) {
+            taken = new Set(siblingRanks(index, parent, priority));
+            takenByGroup.set(key, taken);
+        }
+        const rank = nextRank([...taken]);
+        taken.add(rank);
+        return rank;
+    };
+    for (const change of plan.changes) {
+        const entry = index.quests.get(change.id);
+        if (!entry)
+            continue;
+        const result = setQuestParent(entry.dir, change.newParent);
+        if (!result.ok) {
+            if (applied.length > 0) {
+                recordStructuralOp(state.questsRoot, "reparent", applied);
+            }
+            return refuse(`${result.guidance} Applied ${applied.length} of ${plan.changes.length} before the failure; recorded for undo.`);
+        }
+        applied.push({
+            id: change.id,
+            field: "parent",
+            old: change.oldParent,
+            new: change.newParent,
+        });
+        const priority = entry.doc.frontMatter.priority;
+        const oldRank = entry.doc.frontMatter.rank;
+        const newRank = placeRank(change.newParent, priority);
+        if (newRank !== oldRank) {
+            const rankResult = setQuestRankByDir(entry.dir, newRank);
+            if (!rankResult.ok) {
+                recordStructuralOp(state.questsRoot, "reparent", applied);
+                return refuse(`${rankResult.guidance} Applied ${count(applied.length, "change")} before the failure; recorded for undo.`);
+            }
+            applied.push({
+                id: change.id,
+                field: "rank",
+                old: String(oldRank),
+                new: String(newRank),
+            });
+        }
+    }
+    recordStructuralOp(state.questsRoot, "reparent", applied);
+    return ok(`Reparented ${count(plan.changes.length, "quest")}.`, {
+        changes: plan.changes,
+        dryRun: false,
+    });
+}
+/**
+ * Bulk conclude or retire an explicit comma-separated id set.
+ * Atomic on any missing target, dry-run previewable, journalled
+ * for undo. Unlike the single-quest conclude, this does not
+ * prune trees: it is a lightweight, reversible status sweep.
+ */
+export function bulkConcludeOrRetire(state, action, params) {
+    const targets = (params.id ?? "")
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    if (targets.length === 0) {
+        return refuse("Pass the quest ids to sweep in `id`, comma-separated.");
+    }
+    const reason = params.reason?.trim();
+    if (action === "retire" && !reason) {
+        return refuse("Bulk retire needs a `reason`: why are these being abandoned?");
+    }
+    const newStatus = action === "conclude" ? "concluded" : "retired";
+    const { index } = discoverQuests(state.questsRoot);
+    const plan = planStatusChange(index, targets, newStatus);
+    if (plan.errors.length > 0) {
+        return refuse(`Refusing the batch; nothing was changed:\n- ${plan.errors.join("\n- ")}`);
+    }
+    if (plan.changes.length === 0) {
+        return ok(`Nothing to ${action}; every target is already ${newStatus}.`, {
+            changes: [],
+            dryRun: Boolean(params.dryRun),
+        });
+    }
+    if (params.dryRun) {
+        const lines = plan.changes
+            .map((c) => `  ${c.id}: ${c.oldStatus} -> ${c.newStatus}`)
+            .join("\n");
+        return ok(`Dry run: would ${action} ${count(plan.changes.length, "quest")}.\n${lines}`, { changes: plan.changes, dryRun: true });
+    }
+    const journey = action === "conclude"
+        ? "Concluded the quest (bulk)."
+        : `Retired the quest (bulk): ${reason}.`;
+    const applied = [];
+    for (const change of plan.changes) {
+        const entry = index.quests.get(change.id);
+        if (!entry)
+            continue;
+        const result = setQuestStatusByDir(entry.dir, newStatus);
+        if (!result.ok) {
+            if (applied.length > 0) {
+                recordStructuralOp(state.questsRoot, action, applied);
+            }
+            return refuse(`${result.guidance} Applied ${applied.length} of ${plan.changes.length} before the failure; recorded for undo.`);
+        }
+        // Cascade the seal the same way the loaded-quest path does: drop
+        // the priority to someday (journalled, so undo restores it) and
+        // seal every still-active document to the terminal stage.
+        const oldPriority = entry.doc.frontMatter.priority;
+        if (oldPriority !== "someday") {
+            setQuestPriorityByDir(entry.dir, "someday");
+            applied.push({
+                id: change.id,
+                field: "priority",
+                old: oldPriority,
+                new: "someday",
+            });
+        }
+        sealQuestDocuments(entry.dir, newStatus);
+        appendJourneyByPath(entry.dir, journey);
+        applied.push({
+            id: change.id,
+            field: "status",
+            old: change.oldStatus,
+            new: change.newStatus,
+        });
+    }
+    recordStructuralOp(state.questsRoot, action, applied);
+    // A sealed quest with live children leaves them orphaned but live.
+    // Warn rather than cascade: the operator chose these ids, so seal
+    // only what was named and surface the children to decide on next.
+    const sealedIds = new Set(plan.changes.map((c) => c.id));
+    const liveChildren = [];
+    for (const id of sealedIds) {
+        for (const childId of index.children.get(id) ?? []) {
+            const child = index.quests.get(childId);
+            if (child && !isSealedStatus(child.doc.frontMatter.status)) {
+                liveChildren.push(childId);
+            }
+        }
+    }
+    const warning = liveChildren.length > 0
+        ? ` Warning: ${count(liveChildren.length, "live child quest")} ${verb(liveChildren.length, "remains", "remain")} under a sealed parent: ${liveChildren.join(", ")}.`
+        : "";
+    return ok(`${action === "conclude" ? "Concluded" : "Retired"} ${count(plan.changes.length, "quest")}.${warning}`, {
+        changes: plan.changes,
+        dryRun: false,
+        liveChildren,
+    });
+}
+/**
+ * Read the current on-disk value of a journalled field, so undo can
+ * check it still equals what the operation wrote before reverting.
+ */
+function currentValue(fm, field) {
+    const lens = lensForField(field);
+    if (lens)
+        return lens.read(fm);
+    // No lens means the field is not on a quest README at all (`stage`
+    // is journallable but belongs to a document). Return a sentinel that
+    // can never equal the recorded `new`, so the change is skipped and
+    // preserved in the journal rather than mis-reverted.
+    return UNREVERTABLE_FIELD;
+}
+/**
+ * A value no real front-matter field can hold, used to force an
+ * unhandled journalled field down undo's skip-and-preserve path.
+ */
+const UNREVERTABLE_FIELD = "|__unrevertable_field__";
+/** Reverse a single journalled change, restoring its recorded old value. */
+function revertField(dir, change) {
+    const lens = lensForField(change.field);
+    if (!lens) {
+        // Unreachable for today's journalled ops, since currentValue skips
+        // a lensless field before this is ever called for it. Kept as a
+        // refusal so a field that starts being journalled without a lens
+        // cannot land on whichever branch happened to be last.
+        return {
+            ok: false,
+            guidance: `undo cannot reverse a ${change.field} change yet.`,
+        };
+    }
+    // Validate the journalled value against the field's vocabulary
+    // before writing it. This used to be an unchecked cast, which is
+    // safe only while every entry was written by the current build.
+    const result = setQuestFieldByDir(dir, lens, change.old);
+    if (!result.ok)
+        return result;
+    // Reparenting announces itself in the Journey, and undoing one has
+    // to say so too, or the original line stands uncontradicted.
+    if (change.field === "parent") {
+        appendJourneyByPath(dir, `Reparented to ${change.old ?? "top level"}.`);
+    }
+    return { ok: true };
+}
+export function undo(state) {
+    const last = lastStructuralOp(state.questsRoot);
+    if (!last) {
+        return refuse("Nothing to undo; the structural journal is empty.");
+    }
+    const { index } = discoverQuests(state.questsRoot);
+    const skipped = [];
+    const skippedChanges = [];
+    const reverted = [];
+    for (const change of last.changes) {
+        const entry = index.quests.get(change.id);
+        if (!entry) {
+            skipped.push(change.id);
+            skippedChanges.push(change);
+            continue;
+        }
+        // Verify the on-disk value still equals what this operation
+        // wrote. An intervening manual edit means the recorded `new` no
+        // longer holds, so reverting to `old` would clobber that edit;
+        // skip instead.
+        const current = currentValue(entry.doc.frontMatter, change.field);
+        if (current !== change.new) {
+            skipped.push(change.id);
+            skippedChanges.push(change);
+            continue;
+        }
+        const result = revertField(entry.dir, change);
+        if (!result.ok)
+            return refuse(result.guidance);
+        // revertField announces a reparent in the Journey; a status
+        // reversal needs an explicit compensating entry too, so the
+        // original conclude/retire line does not stand uncontradicted.
+        if (change.field === "status") {
+            appendJourneyByPath(entry.dir, `Reverted the ${last.op} (undo).`);
+        }
+        reverted.push(change.id);
+    }
+    // Consume the op, but keep the changes we could not apply: rewrite
+    // the journal so the skipped changes survive as the operation's
+    // residue. A later undo can reverse them once the divergence
+    // resolves, instead of the partial undo swallowing them for good.
+    dropLastStructuralOp(state.questsRoot);
+    if (skippedChanges.length > 0) {
+        recordStructuralOp(state.questsRoot, last.op, skippedChanges);
+    }
+    const note = skipped.length > 0
+        ? ` (skipped ${count(skipped.length, "quest")} missing or changed since: ${skipped.join(", ")})`
+        : "";
+    return ok(`Undid ${last.op} of ${count(reverted.length, "quest")}${note}.`, {
+        op: last.op,
+        changes: last.changes,
+        reverted,
+        skipped,
+    });
+}

package/dist/quest/verbs/tree-ops.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tree-operation verbs: tree-add, tree-list, tree-prune,
+ * tree-expand. Each delegates to the resolved tree
+ * provider (built-in git-worktree, or a downstream
+ * provider like dev-tree for the World monorepo).
+ */
+import type { QuestState } from "../state.js";
+import { type QuestResult, type QuestToolParams } from "./shared.js";
+export declare function treeAdd(state: QuestState, params: QuestToolParams): Promise<QuestResult>;
+/**
+ * Adopt the existing git tree at the cwd: register it on the quest
+ * without creating anything, marked `adopted` so conclude and retire
+ * never auto-prune it. This is the deliberate, explicit alternative
+ * to scaffolding a fresh worktree; the act of running it is the
+ * consent, so there is no inference and no silent binding.
+ */
+export declare function treeAdopt(state: QuestState, params: QuestToolParams): QuestResult;
+export declare function treeList(state: QuestState): QuestResult;
+export declare function treePrune(state: QuestState, params: QuestToolParams): Promise<QuestResult>;
+export declare function treeExpand(state: QuestState, params: QuestToolParams): Promise<QuestResult>;

package/dist/quest/verbs/tree-ops.js

@@ -0,0 +1,289 @@
+/**
+ * Tree-operation verbs: tree-add, tree-list, tree-prune,
+ * tree-expand. Each delegates to the resolved tree
+ * provider (built-in git-worktree, or a downstream
+ * provider like dev-tree for the World monorepo).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { discoverQuests } from "../../internal/quest/discovery.js";
+import { parseQuestFrontMatter } from "../../internal/quest/frontmatter.js";
+import { canonicalPath, gitTreeRootOf, isMainWorkingTree, isWithin, } from "../../internal/quest/git-signals.js";
+import { isSealedStatus } from "../../internal/quest/status.js";
+import { addTreeToQuest, listTreesOnQuest, removeTreeFromQuest, setPendingPrune, } from "../../internal/quest/trees.js";
+import { getTreeProvider, resolveTreeProvider } from "../../tree/index.js";
+import { count, noun } from "../../ui/count.js";
+import { displayPath } from "../../ui/path.js";
+import { appendJourneyEntry, inventoryWorktrees } from "../lifecycle.js";
+import { ok, refuse, } from "./shared.js";
+function defaultRepoRoot(_state, params) {
+    if (params.cwd)
+        return params.cwd;
+    return process.cwd();
+}
+function readSessionsFromQuest(state) {
+    if (!state.questDir)
+        return [];
+    try {
+        const readme = join(state.questDir, "README.md");
+        const text = readFileSync(readme, "utf8");
+        const parsed = parseQuestFrontMatter(text);
+        return parsed?.frontMatter.sessions ?? [];
+    }
+    catch {
+        // Quest README missing or unreadable; treat as no
+        // sessions so we don't accidentally block pruning.
+        return [];
+    }
+}
+export async function treeAdd(state, params) {
+    if (!state.questDir || !state.questId) {
+        return refuse("Load a quest first.");
+    }
+    let repoRoot = defaultRepoRoot(state, params);
+    let provider = resolveTreeProvider(repoRoot);
+    if (!provider) {
+        // The cwd may be a subdirectory of a repository, where the
+        // built-in git-worktree provider (which looks for .git at the
+        // root) does not apply. Resolve to the enclosing git root and
+        // retry, so tree-add from a deep working directory no longer
+        // hard-fails on the wrong cwd. Downstream providers that match
+        // the raw root are untouched; this only rescues the no-match case.
+        const root = gitTreeRootOf(repoRoot);
+        if (root) {
+            repoRoot = root;
+            provider = resolveTreeProvider(repoRoot);
+        }
+    }
+    if (!provider) {
+        return refuse(`No tree provider applies to ${repoRoot}, and it is not inside a git repository. Pass cwd pointing at your repo (you do not need to change your session's directory), or register a provider (the harness ships git-worktree as a default).`);
+    }
+    const name = params.name?.trim() || params.title?.trim() || state.questId.toLowerCase();
+    try {
+        const handle = await provider.create({
+            name,
+            repoRoot,
+            baseBranch: params.ref,
+        });
+        const tree = {
+            path: handle.path,
+            branch: handle.branch,
+            repoRoot: handle.repoRoot,
+            providerId: handle.providerId,
+            origin: "scaffolded",
+        };
+        const result = addTreeToQuest(state.questDir, tree);
+        if (!result.ok)
+            return refuse(result.reason);
+        appendJourneyEntry(state, `Added ${handle.providerId} tree at ${handle.path}.`);
+        return ok(`Tree ready at ${handle.path}.`, { tree });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return refuse(`Tree create failed: ${message}`);
+    }
+}
+/**
+ * Adopt the existing git tree at the cwd: register it on the quest
+ * without creating anything, marked `adopted` so conclude and retire
+ * never auto-prune it. This is the deliberate, explicit alternative
+ * to scaffolding a fresh worktree; the act of running it is the
+ * consent, so there is no inference and no silent binding.
+ */
+export function treeAdopt(state, params) {
+    if (!state.questDir || !state.questId) {
+        return refuse("Load a quest first.");
+    }
+    const start = defaultRepoRoot(state, params);
+    const root = gitTreeRootOf(start);
+    if (!root) {
+        return refuse(`${start} is not inside a git working tree. Pass cwd pointing at a path inside the tree you want to adopt; you do not need to change your session's directory.`);
+    }
+    // Guard a shared checkout before binding: a path another quest
+    // already tracks, or a repository's main working tree, is the shape
+    // that lets many quests bind to one checkout and magnetize a
+    // session ambiguously. Warn and require force rather than adopt
+    // silently; tree-adopt stays first-class, the guard just makes a
+    // shared bind a deliberate act.
+    if (!params.force) {
+        const otherQuest = pathAdoptedByAnotherQuest(state, root);
+        if (otherQuest) {
+            return refuse(`${root} is already tracked by ${otherQuest}. Adopting one checkout on several quests is what makes a fresh session resolve to an arbitrary quest. Pass force:true to adopt it here as well, or scaffold a private worktree with tree-add.`);
+        }
+        if (isMainWorkingTree(root)) {
+            return refuse(`${root} is a repository's main working tree, not a scaffolded worktree. Adopting a shared main checkout binds this quest to it. Pass force:true to confirm, or scaffold a private worktree with tree-add.`);
+        }
+    }
+    const provider = resolveTreeProvider(root);
+    // repoRoot is recorded as the adopted tree's own root. For a
+    // linked worktree that is the worktree dir rather than the main
+    // repo, unlike a scaffolded tree, but it is sufficient here: an
+    // adopted tree is never auto-pruned, and the provider resolves
+    // from the path either way, so the value is only a reference.
+    const tree = {
+        path: root,
+        repoRoot: root,
+        providerId: provider?.id ?? "git-worktree",
+        origin: "adopted",
+    };
+    const result = addTreeToQuest(state.questDir, tree);
+    if (!result.ok)
+        return refuse(result.reason);
+    if (!result.added) {
+        return ok(`Tree at ${root} is already tracked on this quest.`, { tree });
+    }
+    // The Journey is prose held to the column rule, and an absolute
+    // path is the one thing in it that cannot be wrapped. A tilde is a
+    // courtesy for a reader, and the Journey has no other kind of
+    // audience: nothing reads a path back out of it.
+    appendJourneyEntry(state, `Adopted tree at ${displayPath(root)}.`);
+    return ok(`Adopted tree at ${root}; it will not be auto-pruned.`, { tree });
+}
+/**
+ * The id of another quest that already tracks a tree at this path, or
+ * undefined when only the loaded quest (or no quest) does. Paths are
+ * canonicalized so a /var versus /private/var spelling still matches.
+ */
+function pathAdoptedByAnotherQuest(state, root) {
+    const target = canonicalPath(root);
+    const { index } = discoverQuests(state.questsRoot);
+    for (const entry of index.quests.values()) {
+        const fm = entry.doc.frontMatter;
+        if (fm.id === state.questId)
+            continue;
+        // Only a live quest is a competing claim. The guard exists because
+        // two quests holding one checkout make a fresh session resolve to
+        // an arbitrary one, and a sealed quest cannot magnetize a session:
+        // the cwd resolver prefers a live quest over a sealed one wherever
+        // both match. Counting a finished quest's claim strands the
+        // checkout instead, because the only quest that could release it
+        // is the one that is over.
+        if (isSealedStatus(fm.status))
+            continue;
+        for (const tree of fm.trees ?? []) {
+            if (canonicalPath(tree.path) === target)
+                return fm.id;
+        }
+    }
+    return undefined;
+}
+export function treeList(state) {
+    if (!state.questDir) {
+        // No quest loaded: return the cross-quest inventory so
+        // the harness-created trees can be seen in one place.
+        const inventory = inventoryWorktrees(state);
+        // scope tells a consumer which shape `trees` carries: the
+        // global inventory entries are attributed (questId/questTitle),
+        // the per-quest records are not.
+        const missing = inventory.filter((t) => !t.exists).length;
+        const missingNote = missing > 0 ? ` (${missing} missing on disk)` : "";
+        return ok(`${count(inventory.length, "tree")} across all quests${missingNote}.`, {
+            scope: "global",
+            trees: inventory,
+        });
+    }
+    const result = listTreesOnQuest(state.questDir);
+    if (!result.ok)
+        return refuse(result.reason);
+    return ok(`${count(result.trees.length, "tree")} on the loaded quest.`, {
+        scope: "quest",
+        trees: result.trees,
+    });
+}
+export async function treePrune(state, params) {
+    if (!state.questDir || !state.questId) {
+        return refuse("Load a quest first.");
+    }
+    const listing = listTreesOnQuest(state.questDir);
+    if (!listing.ok)
+        return refuse(listing.reason);
+    if (listing.trees.length === 0) {
+        return refuse("No trees on the loaded quest to prune.");
+    }
+    const target = listing.trees.find((t) => t.path === params.target || t.path === params.ref) ?? listing.trees[0];
+    // `force` is a typed boolean parameter. The caller flips it only
+    // after confirming destructive intent with the user. We
+    // deliberately do NOT key off a `note` string because notes are
+    // free-form prose, not consent. `force: true` is the consent
+    // signal.
+    const force = params.force === true;
+    // Only a tool-scaffolded tree may be pruned without force. An
+    // adopted or unmarked (legacy, hand-registered) tree is a shared
+    // checkout the tool did not create, so deleting it needs explicit,
+    // confirmed consent rather than a mistyped target.
+    if (target.origin !== "scaffolded" && !force) {
+        const kind = target.origin ?? "unmarked";
+        return refuse(`Tree at ${displayPath(target.path)} is ${kind}, not scaffolded by the tool. Pruning it would delete a shared checkout; pass force:true after confirming with the user.`);
+    }
+    const sessions = readSessionsFromQuest(state);
+    const attached = sessions.filter((s) => s.cwd && isWithin(s.cwd, target.path));
+    if (attached.length > 0 && !force) {
+        const names = attached.map((s) => s.name ?? s.id).join(", ");
+        return refuse(`Tree at ${displayPath(target.path)} has an attached ${noun(attached.length, "session")} (${names}). Detach them with \`session-detach\` before pruning, or pass force:true after confirming with the user.`);
+    }
+    // Prefer the provider that created the tree, recorded as its
+    // providerId, so a prune reaches the same provider even if the
+    // registry's resolution order changed since the tree was made.
+    // Fall back to repo-root resolution for legacy trees with no id.
+    const provider = (target.providerId ? getTreeProvider(target.providerId) : undefined) ??
+        resolveTreeProvider(target.repoRoot ?? target.path) ??
+        resolveTreeProvider(process.cwd());
+    if (!provider) {
+        return refuse(`No tree provider applies to ${target.repoRoot ?? target.path}.`);
+    }
+    try {
+        await provider.prune({ path: target.path, force });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const detectedAt = new Date().toISOString();
+        setPendingPrune(state.questDir, {
+            path: target.path,
+            reason: message,
+            detectedAt,
+        });
+        return refuse(`Tree prune blocked: ${message} Resolve the conflict and retry, or pass force:true after confirming with the user.`);
+    }
+    const removal = removeTreeFromQuest(state.questDir, target.path);
+    if (!removal.ok)
+        return refuse(removal.reason);
+    setPendingPrune(state.questDir, null, { clearPath: target.path });
+    appendJourneyEntry(state, `Pruned tree at ${target.path}.`);
+    // The tilde form for the person reading; the absolute path stays in details,
+    // which is what a caller acts on.
+    return ok(`Tree at ${displayPath(target.path)} pruned.`, {
+        path: target.path,
+    });
+}
+export async function treeExpand(state, params) {
+    if (!state.questDir)
+        return refuse("Load a quest first.");
+    const zone = params.ref?.trim();
+    if (!zone) {
+        return refuse("Pass the zone to add in `ref` (e.g. system/gitstream).");
+    }
+    const listing = listTreesOnQuest(state.questDir);
+    if (!listing.ok)
+        return refuse(listing.reason);
+    if (listing.trees.length === 0) {
+        return refuse("No trees on the loaded quest. Run tree-add first.");
+    }
+    const target = listing.trees[0];
+    const provider = resolveTreeProvider(target.repoRoot ?? target.path);
+    if (!provider) {
+        return refuse("No tree provider applies to the loaded quest's tree.");
+    }
+    const expander = provider.expand;
+    if (typeof expander !== "function") {
+        return refuse(`Provider ${provider.id} does not support expand. (zone-aware providers, like dev-tree in joel.gerber.pi, implement this.)`);
+    }
+    try {
+        await expander({ path: target.path, zone });
+        appendJourneyEntry(state, `Expanded ${target.path} with zone ${zone}.`);
+        return ok(`Zone ${zone} added to ${displayPath(target.path)}.`, { zone });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return refuse(`Tree expand failed: ${message}`);
+    }
+}

package/dist/refs/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public surface of the refs library.
+ *
+ * Pluggable registry of external-system reference types
+ * (GitHub issues, Slack threads, anything with a URL and a
+ * recognisable shape). Consumers register their types; the
+ * library extracts matches from text and builds canonical
+ * URLs on demand. Built-in types are opt-in via
+ * `registerBuiltinRefTypes`.
+ */
+export { getRefType, listRefTypes, parseAllRefs, parseRef, urlForRef, whyRefHasNoUrl, } from "./lookup.js";
+export { clearRefTypes, registerBuiltinRefTypes, registerRefType, unregisterRefType, } from "./register.js";
+export type { Ref, RefType } from "./types.js";

package/dist/refs/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public surface of the refs library.
+ *
+ * Pluggable registry of external-system reference types
+ * (GitHub issues, Slack threads, anything with a URL and a
+ * recognisable shape). Consumers register their types; the
+ * library extracts matches from text and builds canonical
+ * URLs on demand. Built-in types are opt-in via
+ * `registerBuiltinRefTypes`.
+ */
+export { getRefType, listRefTypes, parseAllRefs, parseRef, urlForRef, whyRefHasNoUrl, } from "./lookup.js";
+export { clearRefTypes, registerBuiltinRefTypes, registerRefType, unregisterRefType, } from "./register.js";