@jitsusama/agentic-harness.core 0.1.0

package/dist/bin/notes.js

@@ -0,0 +1,67 @@
+/**
+ * The `notes` domain's CLI handler: one process per call, no
+ * persisted state -- every verb is fully determined by
+ * `notesRoot` plus its own params, so unlike `bin/quest.ts`
+ * there is no `.agentic-harness/notes-state.json` to load or
+ * save.
+ *
+ * notesRoot resolves the same way quest's questsRoot does: a
+ * single default location every tool on the machine sees
+ * unless told otherwise, not something that shifts under you
+ * as cwd changes. There's no sibling pi extension to alias
+ * onto (quest's default points at the exact path
+ * agentic-harness.pi's quest-workflow extension already
+ * writes to), so notes gets its own XDG-rooted default
+ * instead. Override with `--notes-root` or
+ * `AGENTIC_HARNESS_NOTES_ROOT` when the archive lives
+ * somewhere else -- e.g. a specific repo's notes tree.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { create } from "../notes/verbs/create.js";
+import { reparent, retitle, retype, tag } from "../notes/verbs/mutate.js";
+import { find, show, tree, types } from "../notes/verbs/queries.js";
+import { reindex } from "../notes/verbs/reindex.js";
+/**
+ * Default notesRoot: an XDG data-dir location, mirroring how
+ * `bin/quest.ts`'s `defaultQuestsRoot` resolves.
+ */
+export function defaultNotesRoot(env = process.env, home = homedir()) {
+    const override = env.XDG_DATA_HOME;
+    const root = override && override.length > 0 ? override : join(home, ".local", "share");
+    return join(root, "agentic-harness", "notes");
+}
+function resolveNotesRoot(flagValue) {
+    return (flagValue ?? process.env.AGENTIC_HARNESS_NOTES_ROOT ?? defaultNotesRoot());
+}
+/** Run one notes action against `notesRoot`, resolved from the flag/env/cwd chain. */
+export async function runNotesAction(options, params) {
+    const notesRoot = resolveNotesRoot(options.notesRoot);
+    switch (options.action) {
+        case "create":
+            return create(notesRoot, params);
+        case "find":
+            return find(notesRoot, params);
+        case "show":
+            return show(notesRoot, params);
+        case "retype":
+            return retype(notesRoot, params);
+        case "retitle":
+            return retitle(notesRoot, params);
+        case "tag":
+            return tag(notesRoot, params);
+        case "reparent":
+            return reparent(notesRoot, params);
+        case "tree":
+            return tree(notesRoot, params);
+        case "types":
+            return types(notesRoot);
+        case "reindex":
+            return reindex(notesRoot);
+        default:
+            return {
+                ok: false,
+                guidance: `Unknown action "${options.action}". See the notes skill for the full list.`,
+            };
+    }
+}

package/dist/bin/process-exec.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A real `Exec`, spawning a child process.
+ *
+ * The one CLI-adapter concern this needs it for today is
+ * runRedirectGate's own `subject.exec`, which asks git about the
+ * checkout the way review's own git provider does — but through a
+ * plain process spawn rather than through any richer runtime a host
+ * might otherwise offer, since a stateless CLI invocation is not
+ * running inside one.
+ */
+import type { Exec } from "../exec/index.js";
+/** Run a command as a real child process. Never throws: a spawn failure
+ * (missing binary, ENOENT) reports as a non-zero code instead. */
+export declare const processExec: Exec;

package/dist/bin/process-exec.js

@@ -0,0 +1,31 @@
+/**
+ * A real `Exec`, spawning a child process.
+ *
+ * The one CLI-adapter concern this needs it for today is
+ * runRedirectGate's own `subject.exec`, which asks git about the
+ * checkout the way review's own git provider does — but through a
+ * plain process spawn rather than through any richer runtime a host
+ * might otherwise offer, since a stateless CLI invocation is not
+ * running inside one.
+ */
+import { execFile } from "node:child_process";
+/** Run a command as a real child process. Never throws: a spawn failure
+ * (missing binary, ENOENT) reports as a non-zero code instead. */
+export const processExec = (command, args) => new Promise((resolve) => {
+    execFile(command, args, (error, stdout, stderr) => {
+        if (!error) {
+            resolve({ code: 0, stdout, stderr });
+            return;
+        }
+        // A real exit code is a number; a spawn failure (ENOENT, no
+        // permission) carries a string error code instead, and there
+        // is no process exit code to report, so it counts as failed.
+        const exitCode = error
+            .code;
+        resolve({
+            code: typeof exitCode === "number" ? exitCode : 1,
+            stdout,
+            stderr,
+        });
+    });
+});

package/dist/bin/quest.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The `quest` domain's CLI handler: one process per call, state
+ * read from and written back to a small JSON file the caller owns
+ * -- the same shape `bin/cli.ts`'s tdd handlers use.
+ *
+ * Unlike tdd's loop state, a quest's on-disk questsRoot is shared,
+ * deliberate infrastructure: by default it resolves to the exact
+ * XDG path agentic-harness.pi's own quest-workflow extension
+ * writes to (`~/.local/share/pi/agentic-harness.pi/quest-workflow/
+ * quests`, honouring XDG_DATA_HOME). That's not incidental -- an
+ * adapter with no override should see the same quest tree pi does,
+ * on the same machine, out of the box, since a quest tree is meant
+ * to be one shared campaign log across every tool that touches it.
+ * Override with `--quests-root` or `AGENTIC_HARNESS_QUESTS_ROOT`
+ * when that's not what's wanted.
+ *
+ * This CLI covers the subset of pi's quest-workflow verb surface
+ * that has no pi-specific session concept baked in: no per-session
+ * liveness in `show`/`list`, no automatic session-attach on `load`,
+ * no `session-*`/`spawn-*`/`workspace`/`recent`/`restore` (all keyed
+ * to pi's own session JSONL log and terminal-reopen mechanism, which
+ * this CLI has no equivalent for). An adapter with its own session
+ * story layers that on top of these verbs the way pi's own
+ * `extensions/quest-workflow` does.
+ */
+import type { QuestResult, QuestToolParams } from "../quest/verbs/shared.js";
+export interface QuestCliOptions {
+    action: string;
+    stateFile: string;
+    questsRoot: string | undefined;
+}
+/**
+ * Run one quest action: load state, dispatch, persist state, return
+ * the result. `params` is the caller's full params bag (parsed from
+ * stdin JSON by the caller); `action` is set on it from the CLI
+ * argv so callers don't have to repeat it in the JSON body.
+ */
+export declare function runQuestAction(options: QuestCliOptions, params: QuestToolParams): Promise<QuestResult>;

package/dist/bin/quest.js

@@ -0,0 +1,187 @@
+/**
+ * The `quest` domain's CLI handler: one process per call, state
+ * read from and written back to a small JSON file the caller owns
+ * -- the same shape `bin/cli.ts`'s tdd handlers use.
+ *
+ * Unlike tdd's loop state, a quest's on-disk questsRoot is shared,
+ * deliberate infrastructure: by default it resolves to the exact
+ * XDG path agentic-harness.pi's own quest-workflow extension
+ * writes to (`~/.local/share/pi/agentic-harness.pi/quest-workflow/
+ * quests`, honouring XDG_DATA_HOME). That's not incidental -- an
+ * adapter with no override should see the same quest tree pi does,
+ * on the same machine, out of the box, since a quest tree is meant
+ * to be one shared campaign log across every tool that touches it.
+ * Override with `--quests-root` or `AGENTIC_HARNESS_QUESTS_ROOT`
+ * when that's not what's wanted.
+ *
+ * This CLI covers the subset of pi's quest-workflow verb surface
+ * that has no pi-specific session concept baked in: no per-session
+ * liveness in `show`/`list`, no automatic session-attach on `load`,
+ * no `session-*`/`spawn-*`/`workspace`/`recent`/`restore` (all keyed
+ * to pi's own session JSONL log and terminal-reopen mechanism, which
+ * this CLI has no equivalent for). An adapter with its own session
+ * story layers that on top of these verbs the way pi's own
+ * `extensions/quest-workflow` does.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { registerBuiltinUrlFetchers } from "../quest/index.js";
+import { createQuestState } from "../quest/state.js";
+import { aliasAdd, aliasRemove } from "../quest/verbs/alias.js";
+import { create, focus, list, load, reclassify, show, unfocus, unload, } from "../quest/verbs/lifecycle.js";
+import { ancestors, expand, find, linksAction, locate, tree, who, } from "../quest/verbs/queries.js";
+import { priorityJump, priorityShift, reorder, } from "../quest/verbs/reorder.js";
+import { concludeOrRetire, reopenQuest, stageTransition, } from "../quest/verbs/stage.js";
+import { reparent, undo } from "../quest/verbs/structural.js";
+import { treeAdd, treeAdopt, treeExpand, treeList, treePrune, } from "../quest/verbs/tree-ops.js";
+import { registerBuiltinRefTypes } from "../refs/index.js";
+import { registerBuiltinTerminalDrivers } from "../terminal/index.js";
+import { registerBuiltinTreeProviders } from "../tree/index.js";
+/**
+ * Default questsRoot: the same location agentic-harness.pi's own
+ * quest-workflow extension resolves to, so both hosts see the same
+ * quest tree by default.
+ */
+function defaultQuestsRoot(env = process.env, home = homedir()) {
+    const override = env.XDG_DATA_HOME;
+    const root = override && override.length > 0 ? override : join(home, ".local", "share");
+    return join(root, "pi", "agentic-harness.pi", "quest-workflow", "quests");
+}
+function resolveQuestsRoot(flagValue) {
+    return (flagValue ?? process.env.AGENTIC_HARNESS_QUESTS_ROOT ?? defaultQuestsRoot());
+}
+let registered = false;
+function ensureRegistries() {
+    if (registered)
+        return;
+    registerBuiltinRefTypes();
+    registerBuiltinUrlFetchers();
+    registerBuiltinTerminalDrivers();
+    registerBuiltinTreeProviders();
+    registered = true;
+}
+async function loadState(stateFile, questsRoot) {
+    let state;
+    try {
+        const raw = await readFile(stateFile, "utf8");
+        state = JSON.parse(raw);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        state = createQuestState({ questsRoot });
+    }
+    state.questsRoot = questsRoot;
+    return state;
+}
+async function saveState(stateFile, state) {
+    await mkdir(dirname(stateFile), { recursive: true });
+    await writeFile(stateFile, `${JSON.stringify(state, null, 2)}\n`);
+}
+/**
+ * Run one quest action: load state, dispatch, persist state, return
+ * the result. `params` is the caller's full params bag (parsed from
+ * stdin JSON by the caller); `action` is set on it from the CLI
+ * argv so callers don't have to repeat it in the JSON body.
+ */
+export async function runQuestAction(options, params) {
+    ensureRegistries();
+    const questsRoot = resolveQuestsRoot(options.questsRoot);
+    const state = await loadState(options.stateFile, questsRoot);
+    params.action = options.action;
+    const result = await dispatch(state, options.action, params);
+    await saveState(options.stateFile, state);
+    return result;
+}
+async function dispatch(state, action, params) {
+    switch (action) {
+        case "create":
+            return create(state, params);
+        case "load":
+            return load(state, params);
+        case "unload":
+            return unload(state);
+        case "show":
+        case "status":
+            return show(state, params);
+        case "list":
+            return list(state, params);
+        case "focus":
+            return focus(state, params);
+        case "unfocus":
+            return unfocus(state);
+        case "think":
+        case "draft":
+        case "build":
+            return stageTransition(state, action, params);
+        case "conclude":
+        case "retire":
+            return concludeOrRetire(state, action, params);
+        case "reopen":
+            return reopenQuest(state);
+        case "top":
+        case "bottom":
+        case "bump":
+        case "sink":
+        case "renumber":
+        case "before":
+        case "after":
+            return reorder(state, params);
+        case "reparent":
+            return reparent(state, params);
+        case "undo":
+            return undo(state);
+        case "alias-add":
+            return aliasAdd(state, params);
+        case "alias-remove":
+            return aliasRemove(state, params);
+        case "promote":
+            return priorityShift(state, "up", params);
+        case "demote":
+            return priorityShift(state, "down", params);
+        case "drive":
+            return priorityJump(state, "driving");
+        case "park":
+            return priorityJump(state, "bench");
+        case "defer":
+            return priorityJump(state, "someday");
+        case "reclassify":
+            return reclassify(state, params);
+        case "tree":
+            return tree(state, params);
+        case "tree-add":
+            return treeAdd(state, params);
+        case "tree-adopt":
+            return treeAdopt(state, params);
+        case "tree-list":
+            return treeList(state);
+        case "tree-prune":
+            return treePrune(state, params);
+        case "tree-expand":
+            return treeExpand(state, params);
+        case "expand":
+            return expand(state, params);
+        case "find":
+            return find(state, params);
+        case "who":
+            return who(state, params);
+        case "links":
+            return linksAction(state, params);
+        case "locate":
+            return locate(state, params);
+        case "ancestors":
+            return ancestors(state, params);
+        case "config":
+            return {
+                ok: true,
+                message: `Quests root: ${state.questsRoot}`,
+                details: { questsRoot: state.questsRoot },
+            };
+        default:
+            return {
+                ok: false,
+                guidance: `Unknown action "${action}". See the CLI's quest skill for the full list.`,
+            };
+    }
+}

package/dist/bin/slack-auth.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Claude Code's Slack setup: the CLI-adapter half of the OAuth
+ * setup wizard port.
+ *
+ * pi's own setup wizard is interactive UI (promptSingle, a modal
+ * offering three paths) - genuinely adapter-local, since it drives
+ * a host's own confirmation surface the way a guardian's review()
+ * does. What is NOT adapter-local is everything the wizard actually
+ * runs once a path is chosen: extracting a browser session,
+ * running an OAuth exchange, storing the result. All of that
+ * already lives in the slack package (ported alongside the API
+ * client), untouched here.
+ *
+ * The adapter decision this needed: unlike a guardian, a setup
+ * wizard is not something a tool call needs to pause for - nothing
+ * intercepts anything. It is a workflow the user asks for, which is
+ * exactly the shape a Claude Code *skill* already covers (see
+ * skills/tdd, skills/quest): a markdown file teaching Claude to run
+ * a sequence of Bash-invoked CLI calls and carry the human-facing
+ * conversation itself (ask for a client ID, tell the user to check
+ * their browser, report success). No hook, no new capability -
+ * just a CLI surface for the skill to call, the same shape every
+ * other skill here already uses.
+ *
+ * Only the browser-extraction path is wired up so far: it needs no
+ * OAuth app (Slack's own "recommended" path in pi's wizard too),
+ * so it is the one genuinely zero-setup way in. The OAuth-app path
+ * (buildAuthUrl/waitForOAuthCallback/exchangeCodeForToken, all
+ * already portable in slack/auth/oauth.ts and server.ts) is the
+ * natural next CLI verb when someone wants it; not built here
+ * because nothing in this repo yet needs it, and it is a
+ * mechanical follow-on once it does; see google-auth.ts for a
+ * companion note on the device flow, which is the same shape again.
+ */
+/** Report whether a usable Slack session is currently stored. */
+export declare function runSlackAuthStatus(): Promise<unknown>;
+/**
+ * Extract a Slack session by opening a real browser window and
+ * waiting for the user to be (or become) logged in, then verify
+ * and store it. Blocks for up to five minutes; the skill calling
+ * this should say so before it runs.
+ *
+ * Writes step-by-step sign-in guidance to stderr the moment the
+ * browser opens (see extractFromBrowser's onStep), not just the
+ * final JSON result: a live run with no guidance at all left a
+ * person guessing their way through a multi-tab sign-in flow with
+ * no idea what came next or what a stuck-looking screen wanted.
+ */
+export declare function runSlackAuthLogin(): Promise<unknown>;

package/dist/bin/slack-auth.js

@@ -0,0 +1,107 @@
+/**
+ * Claude Code's Slack setup: the CLI-adapter half of the OAuth
+ * setup wizard port.
+ *
+ * pi's own setup wizard is interactive UI (promptSingle, a modal
+ * offering three paths) - genuinely adapter-local, since it drives
+ * a host's own confirmation surface the way a guardian's review()
+ * does. What is NOT adapter-local is everything the wizard actually
+ * runs once a path is chosen: extracting a browser session,
+ * running an OAuth exchange, storing the result. All of that
+ * already lives in the slack package (ported alongside the API
+ * client), untouched here.
+ *
+ * The adapter decision this needed: unlike a guardian, a setup
+ * wizard is not something a tool call needs to pause for - nothing
+ * intercepts anything. It is a workflow the user asks for, which is
+ * exactly the shape a Claude Code *skill* already covers (see
+ * skills/tdd, skills/quest): a markdown file teaching Claude to run
+ * a sequence of Bash-invoked CLI calls and carry the human-facing
+ * conversation itself (ask for a client ID, tell the user to check
+ * their browser, report success). No hook, no new capability -
+ * just a CLI surface for the skill to call, the same shape every
+ * other skill here already uses.
+ *
+ * Only the browser-extraction path is wired up so far: it needs no
+ * OAuth app (Slack's own "recommended" path in pi's wizard too),
+ * so it is the one genuinely zero-setup way in. The OAuth-app path
+ * (buildAuthUrl/waitForOAuthCallback/exchangeCodeForToken, all
+ * already portable in slack/auth/oauth.ts and server.ts) is the
+ * natural next CLI verb when someone wants it; not built here
+ * because nothing in this repo yet needs it, and it is a
+ * mechanical follow-on once it does; see google-auth.ts for a
+ * companion note on the device flow, which is the same shape again.
+ */
+import { extractFromBrowser } from "../slack/auth/browser-extract.js";
+import { getToken, hasToken, SlackClient, storeToken } from "../slack/index.js";
+/** Report whether a usable Slack session is currently stored. */
+export async function runSlackAuthStatus() {
+    if (!hasToken())
+        return { authenticated: false };
+    const token = getToken();
+    if (!token)
+        return { authenticated: false };
+    const client = new SlackClient(token.accessToken, token.cookie);
+    try {
+        const auth = await client.call("auth.test");
+        return {
+            authenticated: true,
+            team: auth.team ?? token.teamName,
+            user: auth.user,
+        };
+    }
+    catch {
+        return {
+            authenticated: false,
+            reason: "the stored session no longer works; run login again",
+        };
+    }
+}
+/**
+ * Extract a Slack session by opening a real browser window and
+ * waiting for the user to be (or become) logged in, then verify
+ * and store it. Blocks for up to five minutes; the skill calling
+ * this should say so before it runs.
+ *
+ * Writes step-by-step sign-in guidance to stderr the moment the
+ * browser opens (see extractFromBrowser's onStep), not just the
+ * final JSON result: a live run with no guidance at all left a
+ * person guessing their way through a multi-tab sign-in flow with
+ * no idea what came next or what a stuck-looking screen wanted.
+ */
+export async function runSlackAuthLogin() {
+    let credentials;
+    try {
+        credentials = await extractFromBrowser(undefined, undefined, (message) => {
+            process.stderr.write(`${message}\n`);
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    const client = new SlackClient(credentials.token, credentials.cookie);
+    try {
+        const auth = await client.call("auth.test");
+        storeToken({
+            accessToken: credentials.token,
+            cookie: credentials.cookie,
+            userId: typeof auth.user_id === "string" ? auth.user_id : "",
+            teamId: typeof auth.team_id === "string" ? auth.team_id : "",
+            teamName: typeof auth.team === "string" ? auth.team : undefined,
+            // Not an OAuth grant, so there is no scope list; named so a
+            // reader of the stored file can tell this token apart from
+            // one that came through the OAuth app path.
+            scopes: "browser-session",
+        });
+        return { ok: true, team: auth.team, user: auth.user };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `extracted a session but it did not verify: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}

package/dist/clock/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What a duration bounding a child process may be.
+ *
+ * These rules belong to the runner: it is the thing that refuses a
+ * timeout below a floor, above a ceiling, or paired with an idle clock
+ * that outlives it. But the runner is the last place they can be
+ * applied, and by then somebody's roster has been read, a change has
+ * been fetched, a tree has been cut, and the refusal arrives as a
+ * thrown error in the middle of a round instead of as an answer about
+ * a config file.
+ *
+ * So the rules live in neither surface, the same way the thinking
+ * levels do. One definition, two readers: the runner throws with it
+ * and the roster refuses with it, and they cannot come to disagree
+ * about what a usable clock is.
+ */
+/** The shortest duration worth calling a timeout. */
+export declare const CLOCK_FLOOR_MS = 1000;
+/** The longest one, past which a runaway is indistinguishable. */
+export declare const CLOCK_CEILING_MS: number;
+/**
+ * Why this duration cannot be used, if it cannot.
+ *
+ * Names the value and the bound it missed, because the reader of this
+ * has a number in a file and needs to know which way to move it. The
+ * common mistake is writing seconds where milliseconds are meant,
+ * which is why the floor exists at all: 45 is a perfectly plausible
+ * thing to write and stops the child before it has started.
+ */
+export declare function whyUnusableClock(field: string, value: number | undefined): string | undefined;
+/**
+ * Why this set of clocks cannot be used together, if it cannot.
+ *
+ * The pair rule is the one nobody trips over by writing a bad number:
+ * an idle guard that outlives the wall means the wall fires first
+ * however patient the guard is, which is a footgun for somebody who
+ * moved one column of the sizing table.
+ *
+ * A zero reserve is the documented way to switch the soft deadline
+ * off, so it is the one value under the floor that means something.
+ */
+export declare function whyUnusableClocks(clocks: {
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    wrapUpReserveMs?: number;
+}): string | undefined;

package/dist/clock/index.js

@@ -0,0 +1,72 @@
+/**
+ * What a duration bounding a child process may be.
+ *
+ * These rules belong to the runner: it is the thing that refuses a
+ * timeout below a floor, above a ceiling, or paired with an idle clock
+ * that outlives it. But the runner is the last place they can be
+ * applied, and by then somebody's roster has been read, a change has
+ * been fetched, a tree has been cut, and the refusal arrives as a
+ * thrown error in the middle of a round instead of as an answer about
+ * a config file.
+ *
+ * So the rules live in neither surface, the same way the thinking
+ * levels do. One definition, two readers: the runner throws with it
+ * and the roster refuses with it, and they cannot come to disagree
+ * about what a usable clock is.
+ */
+/** The shortest duration worth calling a timeout. */
+export const CLOCK_FLOOR_MS = 1000;
+/** The longest one, past which a runaway is indistinguishable. */
+export const CLOCK_CEILING_MS = 8 * 60 * 60 * 1000;
+/**
+ * Why this duration cannot be used, if it cannot.
+ *
+ * Names the value and the bound it missed, because the reader of this
+ * has a number in a file and needs to know which way to move it. The
+ * common mistake is writing seconds where milliseconds are meant,
+ * which is why the floor exists at all: 45 is a perfectly plausible
+ * thing to write and stops the child before it has started.
+ */
+export function whyUnusableClock(field, value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        !Number.isInteger(value)) {
+        return `${field} must be a whole number of milliseconds, and is ${String(value)}.`;
+    }
+    if (value < CLOCK_FLOOR_MS) {
+        return `${field} is ${value}ms, which is below the ${CLOCK_FLOOR_MS}ms floor and would stop the run almost at once. Milliseconds, not seconds.`;
+    }
+    if (value > CLOCK_CEILING_MS) {
+        return `${field} is ${value}ms, which is past the ${CLOCK_CEILING_MS}ms ceiling.`;
+    }
+    return undefined;
+}
+/**
+ * Why this set of clocks cannot be used together, if it cannot.
+ *
+ * The pair rule is the one nobody trips over by writing a bad number:
+ * an idle guard that outlives the wall means the wall fires first
+ * however patient the guard is, which is a footgun for somebody who
+ * moved one column of the sizing table.
+ *
+ * A zero reserve is the documented way to switch the soft deadline
+ * off, so it is the one value under the floor that means something.
+ */
+export function whyUnusableClocks(clocks) {
+    const each = whyUnusableClock("timeoutMs", clocks.timeoutMs) ??
+        whyUnusableClock("idleTimeoutMs", clocks.idleTimeoutMs) ??
+        (clocks.wrapUpReserveMs === 0
+            ? undefined
+            : whyUnusableClock("wrapUpReserveMs", clocks.wrapUpReserveMs));
+    if (each !== undefined)
+        return each;
+    const { timeoutMs, idleTimeoutMs } = clocks;
+    if (timeoutMs !== undefined &&
+        idleTimeoutMs !== undefined &&
+        idleTimeoutMs > timeoutMs) {
+        return `idleTimeoutMs (${idleTimeoutMs}ms) outlives timeoutMs (${timeoutMs}ms), so the wall clock fires first however patient the idle guard is.`;
+    }
+    return undefined;
+}

package/dist/command/cwd.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Effective working directory of a command line: the base cwd
+ * composed with the leading `cd` segments. Consumers that resolve a
+ * relative path (the `git commit -F <file>` reader, say) ask here
+ * instead of scraping the first `cd` with a regex.
+ */
+import type { CommandLine } from "./types.js";
+/** The resolved directory, or a signal that it cannot be resolved. */
+export type EffectiveCwd = {
+    dir: string;
+} | {
+    unresolvable: true;
+    reason: string;
+};
+/**
+ * Compose the base cwd with the cd segments of the command line. A
+ * `before` source position bounds it to the cd segments that begin
+ * before that position, so a cd after the consuming command does
+ * not move the directory it runs in.
+ */
+export declare function effectiveCwd(line: CommandLine, baseCwd: string, before?: number): EffectiveCwd;