@infinitedusky/indusk-mcp 1.36.2 → 1.37.0

package/dist/lib/stray-state-audit.js

@@ -10,7 +10,8 @@
  * operator can manually `rm -rf` after confirming nothing important is in them.
  *
  * Workbench mode is detected by reading `.indusk/config.json` at the
- * `workbenchRoot` and checking for a `worktree.wrapped_repo` field. Single-
+ * `workbenchRoot` and resolving its declared repo set via `readWorkbenchRepos`
+ * (which reduces the legacy `wrapped_repo` into a one-element list). Single-
  * repo mode skips the audit entirely (no false positives).
  *
  * Worktrees that live at the workbench-root level (sibling to the wrapped
@@ -18,24 +19,14 @@
  * and are NOT flagged as stray. Only `.indusk/` inside the explicit wrapped
  * repo path is flagged.
  */
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-function readWorkbenchConfig(workbenchRoot) {
-    const configPath = join(workbenchRoot, ".indusk/config.json");
-    if (!existsSync(configPath))
-        return null;
-    try {
-        return JSON.parse(readFileSync(configPath, "utf-8"));
-    }
-    catch {
-        return null;
-    }
-}
+import { readWorkbenchRepos } from "./worktree/repos.js";
 /**
  * Find stray `.indusk/` directories in a workbench-shaped project.
  *
  * Returns an empty array if:
- * - `workbenchRoot` is not a workbench-mode project (no `worktree.wrapped_repo`
+ * - `workbenchRoot` is not a workbench-mode project (no declared repos
  *   in config) — single-repo projects are not audited
  * - the wrapped repo doesn't exist (nothing to audit)
  * - no stray state is found (clean workbench)
@@ -45,15 +36,18 @@ function readWorkbenchConfig(workbenchRoot) {
  * to the wrapped repo) are permitted to have their own `.indusk/` for scratch.
  */
 export function findStrayState(workbenchRoot) {
-    const config = readWorkbenchConfig(workbenchRoot);
-    const wrappedRepoName = config?.worktree?.wrapped_repo;
+    // Every declared repo is audited, not just the first. A workbench that
+    // wraps N repos can accumulate stray state in any of them, and auditing
+    // only one produces a clean report about a dirty workbench.
+    const repos = readWorkbenchRepos(workbenchRoot);
     // Not a workbench project — skip audit.
-    if (!wrappedRepoName)
+    if (repos.length === 0)
         return [];
     const findings = [];
-    // Check the wrapped repo for a stray `.indusk/`.
-    const wrappedRepoPath = join(workbenchRoot, wrappedRepoName);
-    if (existsSync(wrappedRepoPath)) {
+    for (const repo of repos) {
+        const wrappedRepoPath = join(workbenchRoot, repo.name);
+        if (!existsSync(wrappedRepoPath))
+            continue;
         const strayInsideWrapped = walkForStrayIndusk(wrappedRepoPath, 2);
         for (const strayPath of strayInsideWrapped) {
             findings.push({

package/dist/lib/telemetry/daemon.d.ts

@@ -47,6 +47,24 @@ export interface DaemonStopResult {
 export declare function resolveBinary(name: "jaeger" | "otelcol"): string;
 export declare function isPortListening(port: number): Promise<boolean>;
 export declare function findFreePort(requested: number): Promise<number>;
+/**
+ * Thrown when a requested port is already served by a process we do not own.
+ *
+ * Typed so callers can tell it apart from a real start failure: an explicit
+ * `telemetry start` should surface it and stop, but the opportunistic auto-start
+ * on extension enable must NOT fail the whole command over it — a daemon is
+ * evidently already serving those ports, which is the state auto-start wanted.
+ */
+export declare class PortsOccupiedError extends Error {
+    readonly ports: {
+        name: string;
+        port: number;
+    }[];
+    constructor(message: string, ports: {
+        name: string;
+        port: number;
+    }[]);
+}
 /**
  * Refuse to start when a requested port is already served by something we do
  * not own.

package/dist/lib/telemetry/daemon.js

@@ -287,6 +287,22 @@ service:
 `;
 }
 // ---- daemonStart / daemonStop / daemonStatus / daemonRestart ---------------
+/**
+ * Thrown when a requested port is already served by a process we do not own.
+ *
+ * Typed so callers can tell it apart from a real start failure: an explicit
+ * `telemetry start` should surface it and stop, but the opportunistic auto-start
+ * on extension enable must NOT fail the whole command over it — a daemon is
+ * evidently already serving those ports, which is the state auto-start wanted.
+ */
+export class PortsOccupiedError extends Error {
+    ports;
+    constructor(message, ports) {
+        super(message);
+        this.name = "PortsOccupiedError";
+        this.ports = ports;
+    }
+}
 /**
  * Refuse to start when a requested port is already served by something we do
  * not own.
@@ -321,12 +337,12 @@ export async function assertRequestedPortsFree(opts) {
     if (occupied.length === 0)
         return;
     const detail = occupied.map((p) => `${p.name} :${p.port}`).join(", ");
-    throw new Error(`Refusing to start: ${detail} already in use by a process this daemon does not own.\n` +
+    throw new PortsOccupiedError(`Refusing to start: ${detail} already in use by a process this daemon does not own.\n` +
         `Starting anyway would bind a random port instead, and anything configured for the ` +
         `requested port would keep talking to whatever is there — silently.\n` +
         `  If it is a leaked telemetry process:  indusk telemetry reap\n` +
         `  If it is another tool you want to keep: indusk telemetry start --allow-port-bump\n` +
-        `  Or choose explicitly:                  indusk telemetry start --otlp-port <n> --ui-port <n>`);
+        `  Or choose explicitly:                  indusk telemetry start --otlp-port <n> --ui-port <n>`, occupied);
 }
 export async function daemonStart(opts = {}) {
     ensureHome();

package/dist/lib/verify/git.d.ts

@@ -3,10 +3,17 @@ export { git };
 /**
  * Assert the root is inside a git work tree, failing LOUD when it is not.
  *
- * A workbench root is deliberately not a git repo, and the cleanup library's
- * silent-`[]` on that shape made its ritual vacuous there. The same silence in
- * a verifier would report "clean" for a phase it never examined — the worst
- * shape a verification bug can take.
+ * The cleanup library's silent-`[]` on a non-git root made its ritual vacuous
+ * there. The same silence in a verifier would report "clean" for a phase it
+ * never examined — the worst shape a verification bug can take.
+ *
+ * NOTE (versioned-workbench): this guard used to be free. A workbench root was
+ * deliberately not a git repo, so it refused there by a property nobody
+ * maintained. Making the root a git repo removes that accident, and the
+ * refusal is now MAINTAINED — by `resolveVerifyRoots`, which separates the
+ * repo holding `impl.md` from the repo holding the code and refuses when they
+ * differ. Changing this function is no longer the whole story; see
+ * `verify/roots.ts`.
  */
 export declare function assertGitRepo(root: string): Promise<void>;
 export declare function headSha(root: string): Promise<string>;

package/dist/lib/verify/git.js

@@ -19,10 +19,17 @@ export { git };
 /**
  * Assert the root is inside a git work tree, failing LOUD when it is not.
  *
- * A workbench root is deliberately not a git repo, and the cleanup library's
- * silent-`[]` on that shape made its ritual vacuous there. The same silence in
- * a verifier would report "clean" for a phase it never examined — the worst
- * shape a verification bug can take.
+ * The cleanup library's silent-`[]` on a non-git root made its ritual vacuous
+ * there. The same silence in a verifier would report "clean" for a phase it
+ * never examined — the worst shape a verification bug can take.
+ *
+ * NOTE (versioned-workbench): this guard used to be free. A workbench root was
+ * deliberately not a git repo, so it refused there by a property nobody
+ * maintained. Making the root a git repo removes that accident, and the
+ * refusal is now MAINTAINED — by `resolveVerifyRoots`, which separates the
+ * repo holding `impl.md` from the repo holding the code and refuses when they
+ * differ. Changing this function is no longer the whole story; see
+ * `verify/roots.ts`.
  */
 export async function assertGitRepo(root) {
     try {

package/dist/lib/verify/roots.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Where the plan lives, and where its code lives.
+ *
+ * These were one value for as long as every project kept both in the same
+ * repository. A workbench separates them: `impl.md` sits in the workbench's
+ * `.indusk/planning/`, while the code it describes sits across a trunk symlink
+ * in a wrapped repo with its own history.
+ *
+ * Until versioned-workbench a workbench root was not a git repo, so
+ * `assertGitRepo` refused and no detector ever ran there. That refusal was
+ * correct and it was FREE — it held because of a property nobody maintained.
+ * Making the root a git repo removes it by accident, and what is left is a
+ * repository whose diff *structurally cannot contain* the code being judged:
+ * phantom detection fires when nothing outside `impl.md` changed, which in a
+ * workbench is always. Every honest checkoff would be reported as phantom, and
+ * a detector that cries wolf gets switched off — taking its real catches with
+ * it.
+ *
+ * So the refusal is now maintained on purpose, here.
+ */
+export interface VerifyRoots {
+    /** Repository holding `impl.md`, the ledger, and the plan's documents. */
+    planRoot: string;
+    /** Repository holding the code those documents describe. */
+    codeRoot: string;
+    /** True when the two differ — a workbench. */
+    split: boolean;
+}
+export interface VerifyRootsRefusal {
+    error: string;
+}
+/**
+ * Resolve both roots, or refuse.
+ *
+ * **Never falls back to the plan root.** A diff of plan documents is not
+ * evidence about code, and reporting it as such is precisely the "could not
+ * check" reported as "checked" failure this module exists to prevent.
+ */
+export declare function resolveVerifyRoots(planRoot: string): VerifyRoots | VerifyRootsRefusal;
+export declare function isRefusal(r: VerifyRoots | VerifyRootsRefusal): r is VerifyRootsRefusal;

package/dist/lib/verify/roots.js

@@ -0,0 +1,54 @@
+import { join } from "node:path";
+import { isWorkbench, readWorkbenchRepos } from "../worktree/repos.js";
+/**
+ * Resolve both roots, or refuse.
+ *
+ * **Never falls back to the plan root.** A diff of plan documents is not
+ * evidence about code, and reporting it as such is precisely the "could not
+ * check" reported as "checked" failure this module exists to prevent.
+ */
+export function resolveVerifyRoots(planRoot) {
+    // Normal-mode project: `.indusk/` ships inside the code repo, so the two
+    // roots genuinely are the same directory. Unchanged from every release
+    // before this one — dusk itself takes this path.
+    if (!isWorkbench(planRoot)) {
+        return { planRoot, codeRoot: planRoot, split: false };
+    }
+    const repos = readWorkbenchRepos(planRoot);
+    const declared = repos.map((r) => r.name).join(", ");
+    // EVERY workbench refuses, and the reason differs by shape.
+    //
+    // This is the floor the ADR scopes to this plan, not the finished feature.
+    // Even with a single declared repo, verify cannot honestly judge a phase
+    // here: the baseline sha comes from the plan repo's ledger and does not
+    // exist in the code repo's history, so there is nothing to diff the code
+    // against. Producing a verdict anyway would mean judging code by a diff
+    // that cannot contain it.
+    //
+    // Refusing costs nothing that worked before — a workbench root was not a
+    // git repo, so `assertGitRepo` already refused every run. What changes is
+    // that the refusal is now maintained deliberately and says why, instead of
+    // holding by an accident this plan removes.
+    if (repos.length === 0) {
+        return {
+            error: `${planRoot} is workbench-shaped but declares no repos, so there is no code root to verify against. ` +
+                "Refusing rather than judging a phase against the plan documents alone.",
+        };
+    }
+    if (repos.length > 1) {
+        return {
+            error: `${planRoot} is a workbench wrapping ${repos.length} repos (${declared}), and nothing in the plan says which holds its code. ` +
+                "Refusing rather than picking one — a verdict against the wrong repository is indistinguishable from a correct one. " +
+                "Run verify inside the repo the phase's code lives in.",
+        };
+    }
+    return {
+        error: `${planRoot} is a workbench: its plan documents and its code (${declared}) live in different repositories, ` +
+            "and the verify ledger records a baseline from the plan repo that has no meaning in the code repo. " +
+            "Refusing rather than judging code against a diff that cannot contain it. " +
+            `Run verify inside ${join(planRoot, declared)} instead; cross-repo verification is a named follow-on.`,
+    };
+}
+export function isRefusal(r) {
+    return "error" in r;
+}

package/dist/lib/verify/verify.js

@@ -8,6 +8,7 @@ import { assertGitRepo, headSha, resolveBootstrapBaseline } from "./git.js";
 import { appendVerifyRecord, findBaselineRecord, hashTrajectory, readLedger } from "./ledger.js";
 import { detectPhantomWork } from "./phantom.js";
 import { detectRedTests } from "./red-tests.js";
+import { isRefusal, resolveVerifyRoots } from "./roots.js";
 /** A rejected verdict must fail a calling script; a clean one must not. */
 export function exitCodeForReport(report) {
     return report.verdict === "rejected" ? 1 : 0;
@@ -16,6 +17,15 @@ export async function runVerify(options) {
     const root = resolve(options.root);
     // LOUD before anything else: a non-git root must never yield a clean report.
     await assertGitRepo(root);
+    // Where the plan lives is not always where its code lives. In a workbench
+    // they are different repositories, and judging a phase against the plan
+    // repo's diff would report every honest checkoff as phantom.
+    const roots = resolveVerifyRoots(root);
+    if (isRefusal(roots))
+        throw new Error(roots.error);
+    const codeRoot = roots.codeRoot;
+    if (roots.split)
+        await assertGitRepo(codeRoot);
     const implPath = resolveImplPath(root, options.plan);
     if (implPath === null) {
         throw new Error(`Plan "${options.plan}" not found — expected an impl.md path, a directory containing one, or a plan under .indusk/planning/.`);
@@ -56,8 +66,13 @@ export async function runVerify(options) {
     });
     findings.push(...redTests.findings);
     const unverifiedRows = redTests.unverifiedRows;
-    findings.push(...(await detectPhantomWork({
-        root,
+    findings.push(
+    // Phantom asks "did anything but the plan file change?", which is a
+    // question about the CODE repo. `resolveVerifyRoots` has already
+    // guaranteed the two are the same repository here — a workbench refuses
+    // before reaching this point rather than diffing the wrong history.
+    ...(await detectPhantomWork({
+        root: codeRoot,
         baselineSha: baseline.sha,
         implRepoRelPath,
         currentContent: content,

package/dist/lib/worktree/layout.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Facts about a workbench's on-disk layout, defined once.
+ *
+ * Three things every workbench command needs: which root directories are not
+ * worktrees, which declared repo owns a worktree, and how a trunk symlink is
+ * made. Each of them lived in two places before this module — `worktree.ts`
+ * and `workbench.ts` — because the second command group re-authored what the
+ * first already knew.
+ *
+ * They are here, rather than in either command, for the standing reason a
+ * primitive kept inside a domain folder gets COPIED by the next domain instead
+ * of imported: it is how `git()` and the phase-block scan each ended up with
+ * two definitions, and it is exactly what happened here. Every divergence in
+ * this file's subject matter is silent — a missing reserved name renders a
+ * machine directory as a worktree, a drifted attribution reads like a correct
+ * one, and a trunk link that was not made reports as one that was.
+ */
+/**
+ * Root entries that are never worktrees.
+ *
+ * `docs` is D7's reserved workbench-root internal-docs directory. Absent from
+ * this set it renders as a worktree, which is how the POC's `docs/` looked
+ * before anyone noticed — the reason it is listed, kept with the listing.
+ */
+export declare const RESERVED_ROOT_DIRS: ReadonlySet<string>;
+/**
+ * Root entries that could be worktrees — directories and symlinks, sorted.
+ *
+ * Symlinks are included because a trunk is one, and callers filter the trunks
+ * out by their DECLARED paths; excluding symlinks here would hide a trunk from
+ * the collision checks that need to see it.
+ */
+export declare function listWorkbenchSubdirs(root: string): string[];
+/**
+ * Which declared repo does this worktree belong to?
+ *
+ * Asked of git rather than inferred from the slug: `--git-common-dir` resolves
+ * to the OWNING repo's `.git`, so the answer survives any naming convention a
+ * developer invents. A name-prefix heuristic would attribute `alpha-feature`
+ * to `alpha` by luck and `experiment` to nothing at all — and a wrong
+ * attribution reads exactly like a right one.
+ *
+ * Null means "could not tell", which renders as unattributed rather than being
+ * quietly assigned to the first repo.
+ */
+export declare function worktreeOwner(worktreePath: string, repoPaths: Map<string, string>): string | null;
+/**
+ * Point `<workbenchRoot>/<name>` at `target`, and say whether it did.
+ *
+ * Relative target, so the workbench stays portable. Returns false in exactly
+ * one case: a real directory occupies the path. That is not ours to remove,
+ * and reporting it as linked would be a claim about something that never
+ * happened — the falsification A30 fixed in `restore`, and the reason `init`
+ * routes through here rather than keeping its own subset.
+ */
+export declare function linkTrunk(workbenchRoot: string, name: string, target: string): boolean;

package/dist/lib/worktree/layout.js

@@ -0,0 +1,136 @@
+/**
+ * Facts about a workbench's on-disk layout, defined once.
+ *
+ * Three things every workbench command needs: which root directories are not
+ * worktrees, which declared repo owns a worktree, and how a trunk symlink is
+ * made. Each of them lived in two places before this module — `worktree.ts`
+ * and `workbench.ts` — because the second command group re-authored what the
+ * first already knew.
+ *
+ * They are here, rather than in either command, for the standing reason a
+ * primitive kept inside a domain folder gets COPIED by the next domain instead
+ * of imported: it is how `git()` and the phase-block scan each ended up with
+ * two definitions, and it is exactly what happened here. Every divergence in
+ * this file's subject matter is silent — a missing reserved name renders a
+ * machine directory as a worktree, a drifted attribution reads like a correct
+ * one, and a trunk link that was not made reports as one that was.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, readlinkSync, realpathSync, rmSync, symlinkSync, } from "node:fs";
+import { join, relative } from "node:path";
+/**
+ * Root entries that are never worktrees.
+ *
+ * `docs` is D7's reserved workbench-root internal-docs directory. Absent from
+ * this set it renders as a worktree, which is how the POC's `docs/` looked
+ * before anyone noticed — the reason it is listed, kept with the listing.
+ */
+export const RESERVED_ROOT_DIRS = new Set([
+    ".indusk",
+    ".claude",
+    ".git",
+    ".vscode",
+    ".cursor",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    "scripts",
+    "env",
+    "docs",
+]);
+/**
+ * Root entries that could be worktrees — directories and symlinks, sorted.
+ *
+ * Symlinks are included because a trunk is one, and callers filter the trunks
+ * out by their DECLARED paths; excluding symlinks here would hide a trunk from
+ * the collision checks that need to see it.
+ */
+export function listWorkbenchSubdirs(root) {
+    const entries = [];
+    for (const name of readdirSync(root)) {
+        if (RESERVED_ROOT_DIRS.has(name))
+            continue;
+        try {
+            const st = lstatSync(join(root, name));
+            if (st.isDirectory() || st.isSymbolicLink())
+                entries.push(name);
+        }
+        catch {
+            // Unreadable entry — skip rather than fail the whole listing.
+        }
+    }
+    return entries.sort();
+}
+/**
+ * Which declared repo does this worktree belong to?
+ *
+ * Asked of git rather than inferred from the slug: `--git-common-dir` resolves
+ * to the OWNING repo's `.git`, so the answer survives any naming convention a
+ * developer invents. A name-prefix heuristic would attribute `alpha-feature`
+ * to `alpha` by luck and `experiment` to nothing at all — and a wrong
+ * attribution reads exactly like a right one.
+ *
+ * Null means "could not tell", which renders as unattributed rather than being
+ * quietly assigned to the first repo.
+ */
+export function worktreeOwner(worktreePath, repoPaths) {
+    const r = spawnSync("git", ["-C", worktreePath, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf-8" });
+    if (r.status !== 0 || !r.stdout)
+        return null;
+    const commonDir = r.stdout.trim();
+    for (const [name, repoPath] of repoPaths) {
+        try {
+            if (realpathSync(commonDir).startsWith(realpathSync(repoPath)))
+                return name;
+        }
+        catch {
+            // unresolvable path — treat as no match rather than guessing
+        }
+    }
+    return null;
+}
+/** Whether `p` is a symlink, dangling or not. Private: `linkTrunk` is the surface. */
+function isSymlink(p) {
+    try {
+        return lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A symlink whose target no longer exists.
+ *
+ * `existsSync` follows the link and so reports FALSE for these — which is why
+ * a naive "create it if it does not exist" throws EEXIST on a workbench whose
+ * sibling parent moved.
+ */
+function isDanglingLink(p) {
+    return isSymlink(p) && !existsSync(p);
+}
+/**
+ * Point `<workbenchRoot>/<name>` at `target`, and say whether it did.
+ *
+ * Relative target, so the workbench stays portable. Returns false in exactly
+ * one case: a real directory occupies the path. That is not ours to remove,
+ * and reporting it as linked would be a claim about something that never
+ * happened — the falsification A30 fixed in `restore`, and the reason `init`
+ * routes through here rather than keeping its own subset.
+ */
+export function linkTrunk(workbenchRoot, name, target) {
+    const link = join(workbenchRoot, name);
+    const rel = relative(workbenchRoot, target);
+    if (existsSync(link) || isDanglingLink(link)) {
+        // A correct link needs nothing doing — report it as linked.
+        if (isSymlink(link) && readlinkSync(link) === rel)
+            return true;
+        // Repair a link that points somewhere else, dangling included.
+        if (isSymlink(link))
+            rmSync(link);
+        else
+            return false;
+    }
+    symlinkSync(rel, link);
+    return true;
+}

package/dist/lib/worktree/repos.d.ts

@@ -0,0 +1,46 @@
+import type { WorkbenchRepo } from "../config.js";
+export type { WorkbenchRepo } from "../config.js";
+/**
+ * Read the declared repo set, newest shape first, singular reduced into it.
+ *
+ * **The reduction IS the backward-compatibility guarantee**, not a claim about
+ * one: `wrapped_repo: "numero"` reads as `[{ name: "numero" }]`, so every
+ * workbench written before this plan keeps working with no config edit and no
+ * migration step. The same shape as `phaseOrdinal` reducing to the phase
+ * number when a document has no test phase.
+ *
+ * Names are boundary values — sanitized before any caller can join them into a
+ * path, and first-occurrence-deduped so declared order survives. A malformed
+ * declaration degrades to fewer repos, never to a traversal.
+ *
+ * Returns `[]` for a project that declares nothing, which callers read as
+ * "not a workbench" exactly as they read a missing `wrapped_repo` today.
+ */
+export declare function readWorkbenchRepos(root: string): WorkbenchRepo[];
+/** Whether this project is workbench-shaped at all. */
+export declare function isWorkbench(root: string): boolean;
+/** The parent directory the sibling clones live in, or null when undeclared. */
+export declare function readSiblingParent(root: string): string | null;
+/**
+ * The refusal a command owes a project that is not a workbench.
+ *
+ * One string, because the *rule* it belongs to lives in bash. `worktree
+ * create`/`refresh`/`preflight` all resolve which repo the user meant inside
+ * `_resolve_workbench_repo`, and `worktreeCreate` deliberately passes `--repo`
+ * straight through rather than deciding first — so there is exactly one
+ * implementation of pick-one and it is the shell one.
+ *
+ * A TypeScript `resolveRepo` stood here with no caller, its docblock claiming
+ * to be "the rule the CLI surface needs in one place" while the CLI surface
+ * read the shell. Dead code that describes itself as authoritative is worse
+ * than dead code; what the TS lane actually shares with bash is this message.
+ */
+export declare const NOT_A_WORKBENCH = "this project is not a workbench (set worktree.shape=\"workbench\" and worktree.repos[] in .indusk/config.json, or run `indusk init --workbench`).";
+/**
+ * Where this repo's checkout lives, relative to the workbench root.
+ *
+ * The declared `path`, or the name when nothing is declared. One function so
+ * no caller re-derives it — a second copy would be the place the two answers
+ * quietly diverge.
+ */
+export declare function repoDir(repo: WorkbenchRepo): string;

package/dist/lib/worktree/repos.js

@@ -0,0 +1,100 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isCleanSegment, isUsableSegment } from "../path-segment.js";
+function readRawConfig(root) {
+    const configPath = join(root, ".indusk", "config.json");
+    if (!existsSync(configPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the declared repo set, newest shape first, singular reduced into it.
+ *
+ * **The reduction IS the backward-compatibility guarantee**, not a claim about
+ * one: `wrapped_repo: "numero"` reads as `[{ name: "numero" }]`, so every
+ * workbench written before this plan keeps working with no config edit and no
+ * migration step. The same shape as `phaseOrdinal` reducing to the phase
+ * number when a document has no test phase.
+ *
+ * Names are boundary values — sanitized before any caller can join them into a
+ * path, and first-occurrence-deduped so declared order survives. A malformed
+ * declaration degrades to fewer repos, never to a traversal.
+ *
+ * Returns `[]` for a project that declares nothing, which callers read as
+ * "not a workbench" exactly as they read a missing `wrapped_repo` today.
+ */
+export function readWorkbenchRepos(root) {
+    const worktree = readRawConfig(root)?.worktree;
+    if (!worktree)
+        return [];
+    const declared = Array.isArray(worktree.repos)
+        ? worktree.repos
+        : typeof worktree.wrapped_repo === "string"
+            ? [{ name: worktree.wrapped_repo }]
+            : [];
+    const seen = new Set();
+    const repos = [];
+    for (const entry of declared) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const { name, remote } = entry;
+        if (typeof name !== "string" || !isCleanSegment(name))
+            continue;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        // `path` and `worktrees` are joined into filesystem paths, so they are
+        // boundary values exactly as `name` is. A declared value that is not a
+        // clean segment is DROPPED, degrading to the default rather than
+        // resolving to a traversal.
+        const { path, worktrees } = entry;
+        const repo = { name };
+        if (typeof remote === "string" && remote.trim() !== "")
+            repo.remote = remote;
+        if (typeof path === "string" && isUsableSegment(path))
+            repo.path = path;
+        if (typeof worktrees === "string" && isUsableSegment(worktrees))
+            repo.worktrees = worktrees;
+        repos.push(repo);
+    }
+    return repos;
+}
+/** Whether this project is workbench-shaped at all. */
+export function isWorkbench(root) {
+    return readRawConfig(root)?.worktree?.shape === "workbench";
+}
+/** The parent directory the sibling clones live in, or null when undeclared. */
+export function readSiblingParent(root) {
+    const value = readRawConfig(root)?.worktree?.sibling_parent;
+    return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+/**
+ * The refusal a command owes a project that is not a workbench.
+ *
+ * One string, because the *rule* it belongs to lives in bash. `worktree
+ * create`/`refresh`/`preflight` all resolve which repo the user meant inside
+ * `_resolve_workbench_repo`, and `worktreeCreate` deliberately passes `--repo`
+ * straight through rather than deciding first — so there is exactly one
+ * implementation of pick-one and it is the shell one.
+ *
+ * A TypeScript `resolveRepo` stood here with no caller, its docblock claiming
+ * to be "the rule the CLI surface needs in one place" while the CLI surface
+ * read the shell. Dead code that describes itself as authoritative is worse
+ * than dead code; what the TS lane actually shares with bash is this message.
+ */
+export const NOT_A_WORKBENCH = 'this project is not a workbench (set worktree.shape="workbench" and worktree.repos[] in .indusk/config.json, or run `indusk init --workbench`).';
+/**
+ * Where this repo's checkout lives, relative to the workbench root.
+ *
+ * The declared `path`, or the name when nothing is declared. One function so
+ * no caller re-derives it — a second copy would be the place the two answers
+ * quietly diverge.
+ */
+export function repoDir(repo) {
+    return repo.path ?? repo.name;
+}