toolroll 0.8.0 → 0.8.2

package/dist/operate.js

@@ -3,7 +3,8 @@ import { parseProtectedPaths } from "./approval-policy.js";
 import { rulesSummary } from "./approval-rules-ui.js";
 import { evidencePack, exportDay, ledgerExportChunks, standaloneEvidenceHtml } from "./evidence-pack.js";
 import { matchesOutsideCheckpoint } from "./ledger-chain.js";
-import { bytesWords, storageReport } from "./storage.js";
+import { CLEANUP_CHOICES, bytesWords, cleanupWords, parseCleanup, storageReport } from "./storage.js";
+import { checkoutPlan, cleanCheckouts, discardCheckout, whyWords } from "./checkout-cleanup.js";
 import { MIN_DAYS, RETENTION_KINDS, countWords, dailyRetention, isRetentionKind, lastSweepAt, parsePeriod, periodWords, retentionPlan, sweepWords } from "./retention.js";
 import { checkPolicy, parseList, policyParts } from "./policy.js";
 import { billingOf, budgetHoldWords, budgetLabel, budgetStates, monthNamed, monthOf, spendItems, teammateNames, usd as spendUsd } from "./spend.js";
@@ -74,7 +75,7 @@ import { sweepLiveLogs } from "./live.js";
 import { configPath, addRepos, removeRepos, updateRepos, loadRepos, loadProjectRegistry, updateProjectRegistry } from "./repos.js";
 import { deleteProject, holdingsWords, projectHoldings, projectRunning } from "./project-delete.js";
 import { pushPass } from "./push.js";
-import { chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, openSync, readFileSync, readSync, realpathSync, unlinkSync, writeSync, writeFileSync, mkdirSync } from "node:fs";
+import { chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, openSync, readFileSync, readSync, realpathSync, renameSync, unlinkSync, writeSync, writeFileSync, mkdirSync } from "node:fs";
 import { BRANCH_PREFIX, envTwins, envValue, existingOrFirst, namedPath, taskBranches } from "./names.js";
 import { createServer as createNetServer } from "node:net";
 import { spawn as spawnChild } from "node:child_process";
@@ -128,7 +129,7 @@ import { daemonLaunchCommand, daemonStatus, installReplacingLegacy, installedLeg
 import { bridgePass, clearBotToken, createTransport, followBridge, hashPairingCode, loadBotToken, mintPairingCode, redactToken, saveBotToken, PAIRING_TTL_MS, TOKEN_ENV, telegramHookSecret, telegramPushUrl, } from "./telegram.js";
 import { scanRepo } from "./capscan.js";
 import { computeGaps, describeCapability } from "./gaps.js";
-import { ask, askHidden, confirm, interactive } from "./prompt.js";
+import { ask, askHidden, confirm, interactive, underAgent } from "./prompt.js";
 import { runMateCli, answerContextLines } from "./mate-cli.js";
 import { confirmCoordinatorProposal, dismissCoordinatorProposal } from "./mate-doors.js";
 import { verifyApproverByPassword } from "./principal.js";
@@ -193,10 +194,6 @@ import { PACKAGE_VERSION } from "./version.js";
  * caller deciding whether to try the next task or wake somebody up.
  */
 export const EXIT = { ok: 0, failed: 1, usage: 2, refused: 3 };
-/** Storage retention: how long a finished task's clean checkout is kept after it was let go, and a result marked
- * complete's or a release candidate's after it was (its checkout holds the build a deploy installs). */
-export const CHECKOUT_KEEP_MS = 2 * 24 * 60 * 60_000;
-export const RESULT_KEEP_MS = 7 * 24 * 60 * 60_000;
 const STATES = ["queued", "running", "done", "failed", "cancelled"];
 export const OPERATE_HELP = `toolroll — operating the queue
 
@@ -213,6 +210,9 @@ export const OPERATE_HELP = `toolroll — operating the queue
                                         --not-requester on|off, --protect none|project, --protect-paths "a/**,b/**"
   toolroll task evidence <id>        the task's evidence pack as JSON (--html for a printable page; --out <file>)
   toolroll storage                   where the disk goes: database, build checkouts, releases, evidence
+  toolroll storage clean [--yes]     preview removing finished tasks' clean checkouts (their branches stay); --yes removes them
+  toolroll storage cleanup <when>    remove a finished task's clean checkout: finished|2d|7d|never (instance operator)
+  toolroll storage discard <path> --yes   throw away a checkout kept for its changes; its branch stays
   toolroll monitoring                where the audit stream and traces go, and how each destination is doing
   toolroll check-progress <run>      current or final approved check progress
   toolroll spend [--month YYYY-MM] [--csv]   what agent work cost, by project, person, teammate and model
@@ -823,13 +823,8 @@ async function dispatch(command, positional, flags, context) {
             return exportCommand(positional, flags, context);
         case "policy":
             return policyCommand(positional, flags, context);
-        case "storage": {
-            const report = storageReport(context.store, context.databaseFile, context.clock(), CHECKOUT_KEEP_MS);
-            return succeed(context.write, context.json, "storage", report, () => [
-                `${report.folder}: ${bytesWords(report.total)}`,
-                ...report.lines.map(one => `  ${one.what.padEnd(17)} ${bytesWords(one.bytes).padStart(8)}${one.count === undefined ? "" : `  (${one.count})`}${one.note === undefined ? "" : `  ${one.note}`}`),
-            ]);
-        }
+        case "storage":
+            return storageCommand(positional, flags, context);
         case "monitoring": {
             // Where the audit stream and traces go, and how each destination is doing. Settings → Monitoring changes it.
             const settings = readMonitoring(dirname(context.databaseFile));
@@ -4313,13 +4308,9 @@ async function reconcileCommand(flags, context) {
             reaped: reaped.map(claim => claim.leaseId),
         });
     }
-    // Storage retention: finished work's clean checkouts go two days after they were let go (their branches stay); a
-    // result marked complete, or a release candidate, a week after (a deploy installs the build in its checkout).
-    const pruned = await worktrees.prune(repo, clock(), CHECKOUT_KEEP_MS, () => store.keptBranches(repo, clock(), RESULT_KEEP_MS));
-    for (const row of pruned.removed) {
-        store.recordAction({ at: clock().toISOString(), actor: "worker", repo, taskId: row.taskRef === null ? null : store.externalIdFor(row.taskRef), runId: null,
-            action: "checkout removed", outcome: "removed", source: "work", detail: `${basename(row.path)} (released ${row.releasedAt?.slice(0, 10) ?? "?"})` });
-    }
+    // Checkout cleanup (Settings → Storage): finished work's clean checkouts go as the setting says (by default when
+    // the task is complete or cancelled); their branches stay. Each removal is in the ledger.
+    const pruned = await cleanCheckouts(store, worktrees, clock, { manual: false, actor: "worker", repo });
     // Retention (Settings → Retention): once a day, what's older than its setting goes; one ledger entry says what.
     let retention = null;
     try {
@@ -4341,7 +4332,7 @@ async function reconcileCommand(flags, context) {
         reaped: reaped.map(claim => claim.leaseId),
         adopted: adoption.adopted,
         forgotten: adoption.forgotten,
-        checkoutsRemoved: pruned.removed.map(row => row.path),
+        checkoutsRemoved: pruned.removed.map(one => one.path),
         checkoutsKept: pruned.kept,
         liveViewsSwept: liveSwept.removed.length,
         retention: retention === null ? null : { counts: retention.counts, freedBytes: retention.freed },
@@ -4352,7 +4343,7 @@ async function reconcileCommand(flags, context) {
             ...(reaped.length === 0 ? [] : [`Reaped ${reaped.length} expired lease(s).`]),
             ...adoption.adopted.map(path => `Adopted ${path} — released, unverified, somebody should look.`),
             ...adoption.forgotten.map(path => `Forgot ${path} — its directory is gone.`),
-            ...(pruned.removed.length === 0 ? [] : [`Removed ${pruned.removed.length} checkout(s) nobody has used for two days; their branches stay.`]),
+            ...(pruned.removed.length === 0 ? [] : [`Removed ${pruned.removed.length} finished task checkout(s), about ${bytesWords(pruned.freed)}; their branches stay.`]),
             ...(liveSwept.removed.length === 0 ? [] : [`Cleared ${liveSwept.removed.length} finished live view(s).`]),
             ...(retention === null || retained.length === 0 ? [] : [`Retention removed ${sweepWords(retention.counts, retention.freed)}.`]),
         ]);
@@ -7665,6 +7656,38 @@ function openBrowser(url) {
         // A browser that will not open is a URL the greeting already printed.
     }
 }
+/** Where `up` last served its console, kept beside the database so `onboard` names the same address. */
+const UP_CONSOLE_FILE = "up-console.json";
+function recordUpConsoleUrl(dir, url, now) {
+    try {
+        const file = join(dir, UP_CONSOLE_FILE), temporary = `${file}.${process.pid}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify({ url, at: now.toISOString() })}\n`, { mode: 0o600 });
+        renameSync(temporary, file);
+    }
+    catch {
+        // A display fact: a failed write only leaves onboard on the default port.
+    }
+}
+export function readUpConsoleUrl(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, UP_CONSOLE_FILE), "utf8"));
+        return typeof parsed.url === "string" && /^https?:\/\/[^\s]+$/.test(parsed.url) ? parsed.url.replace(/\/+$/, "") : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** How onboard says to sign in: the saved login file only while it still works (as `up` advertises it), else the
+ * account and its password; null only when there is no account yet. Never the password itself. */
+function onboardLogin(store, loginFile) {
+    const names = store.listApprovers().map(one => one.name);
+    const saved = readLoginFile(loginFile);
+    if (names.length === 0)
+        return saved === null ? null : { account: saved.name, file: loginFile }; // the next `up` adopts it
+    if (saved !== null && authenticateApprover(store, saved.name, saved.password).ok)
+        return { account: saved.name, file: loginFile };
+    return { account: names.length === 1 ? names[0] : null, file: null };
+}
 /**
  * `onboard`: the agent that installed Toolroll becomes its lead. The work
  * lives in agent-onboard.ts; this wires it to the installation: the same
@@ -7679,8 +7702,11 @@ async function onboardCommand(flags, context) {
     if (portGiven !== undefined && (!Number.isInteger(port) || port < 1 || port >= 65536)) {
         return fail(write, json, "onboard", "usage", "--port is a whole number under 65536", EXIT.usage);
     }
+    // The console where `up` last served, unless --port says otherwise.
+    const served = portGiven === undefined ? readUpConsoleUrl(dirname(context.databaseFile)) : null;
     const home = seams.home ?? homedir();
     const env = seams.env ?? process.env;
+    const loginFile = join(dirname(context.databaseFile), UP_LOGIN_FILE);
     const gitRun = context.gitRunner ?? ((file, args, opts) => run(file, [...args], { ...(opts?.cwd === undefined ? {} : { cwd: opts.cwd }), timeoutMs: 10_000 }));
     const registryPath = registryPathOf(context);
     const checker = createConnectionChecker({ home, env });
@@ -7690,18 +7716,31 @@ async function onboardCommand(flags, context) {
         yes: flag(flags, "yes"),
         remove: flag(flags, "remove"),
         agentFlag: text(flags, "agent"),
-        url: `http://127.0.0.1:${port}`,
-        loginFile: join(dirname(context.databaseFile), UP_LOGIN_FILE),
+        url: served ?? `http://127.0.0.1:${port}`,
+        login: onboardLogin(store, loginFile),
         home,
+        worktrees: join(dirname(context.databaseFile), "worktrees"),
         env,
         version: PACKAGE_VERSION,
         cwd: seams.cwd ?? process.cwd(),
-        interactive: seams.interactive ?? interactive(),
+        // An agent's shell may be a terminal, but nobody answers y/N there.
+        interactive: seams.interactive ?? (interactive() && !underAgent(env)),
         confirm: seams.confirm ?? (async (question) => /^y(es)?$/i.test(await ask(`${question} `))),
         findRepo: seams.findRepo ?? (async (cwd) => {
             const top = await gitRun("git", ["rev-parse", "--show-toplevel"], { cwd });
-            return top.code === 0 ? canonicalProject(top.stdout.trim()) : null;
+            const topPath = top.code === 0 ? canonicalProject(top.stdout.trim()) : null;
+            if (topPath === null)
+                return null;
+            // A linked worktree's project is its main checkout: the folder whose .git is the common one.
+            const common = await gitRun("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd });
+            const commonDir = common.code === 0 ? common.stdout.trim() : "";
+            const main = basename(commonDir) === ".git" ? canonicalProject(dirname(commonDir)) : null;
+            return { top: topPath, main: main ?? topPath };
         }),
+        enrolled: async (repo) => {
+            const registry = await loadProjectRegistry(registryPath);
+            return !("error" in registry) && registry.repos.includes(repo);
+        },
         enroll: async (repo) => {
             const before = await loadProjectRegistry(registryPath);
             const enrolled = await updateRepos(registryPath, repos => addRepos(repos, [repo]));
@@ -7839,7 +7878,10 @@ async function upCommand(flags, context) {
     if (!reserved) {
         return fail(write, json, "up", "port-busy", `port ${port} is taken — another \`up\` or \`serve\` may already be running; stop it, or pick a different --port`, EXIT.refused);
     }
-    const canPrompt = !json && process.stdin.isTTY === true && process.stdout.isTTY === true;
+    // Under a coding agent nothing is asked and no secret is printed, even in a real terminal: what is shown lands in
+    // its transcript.
+    const agentRunning = underAgent(context.upSeams?.env ?? process.env);
+    const canPrompt = !json && !agentRunning && process.stdin.isTTY === true && process.stdout.isTTY === true;
     let runnerName = "";
     let runnerToken = "";
     let approver = null;
@@ -8152,8 +8194,12 @@ async function upCommand(flags, context) {
     // 9. Readiness, then the ONE startup envelope / greeting (finding 11/20).
     const approverPlan2 = approver;
     const url = console_.url;
-    const terminal = context.upSeams?.terminal ?? process.stdout.isTTY === true;
-    const upHandoff = buildHandoff({ url, loginFile: approverPlan2.passwordFile, account: approverPlan2.passwordFile === null ? approverPlan2.approver : loginAccount(approverPlan2.passwordFile) ?? approverPlan2.approver });
+    const terminal = !agentRunning && (context.upSeams?.terminal ?? process.stdout.isTTY === true);
+    const upHandoff = buildHandoff({
+        url,
+        login: { account: approverPlan2.passwordFile === null ? approverPlan2.approver : loginAccount(approverPlan2.passwordFile) ?? approverPlan2.approver, file: approverPlan2.passwordFile },
+    });
+    recordUpConsoleUrl(dirname(context.databaseFile), url, clock());
     if (fatal === null) {
         if (json) {
             write(envelopeJson({
@@ -11268,6 +11314,97 @@ async function retentionCommand(positional, flags, context) {
     const periods = store.setRetentionPeriod(kind, days, acting.name, context.clock());
     return succeed(context.write, context.json, command, { periods }, () => [`${label(kind)}: kept ${days === null ? "forever" : `for ${periodWords(days)}`}.`]);
 }
+/** `storage`, `storage cleanup [<when>]`, `storage clean [--yes]`, `storage discard <path> --yes`: where the disk goes,
+ * and task checkouts: when a finished task's clean checkout is removed, cleaning up now, and throwing away one kept for
+ * its changes. Changing anything takes an instance operator. */
+async function storageCommand(positional, flags, context) {
+    const [action, ...rest] = positional;
+    const command = `storage ${action ?? ""}`.trim();
+    const store = context.store;
+    const changes = (action === "cleanup" && rest.length > 0) || (action === "clean" && flags.has("yes")) || action === "discard";
+    const allowed = new Set([...(changes ? ["as", "token", "token-file", "token-env"] : []), ...(action === "clean" || action === "discard" ? ["yes"] : []), "db", "json"]);
+    for (const name of flags.keys())
+        if (!allowed.has(name))
+            return fail(context.write, context.json, command, "usage", `--${name} is not a ${command} option.`, EXIT.usage);
+    const pool = new WorktreePool(store, { root: join(dirname(context.databaseFile), "worktrees"), ...(context.gitRunner === undefined ? {} : { runner: context.gitRunner }) });
+    const operator = async () => {
+        const acting = await askCredentials(flags, context);
+        const verified = acting === null ? null : authenticateApprover(store, acting.name, acting.token);
+        return acting !== null && verified !== null && verified.ok && store.isInstanceOperator(acting.name) ? acting.name : null;
+    };
+    const refused = (what) => fail(context.write, context.json, command, "refused", `An instance operator ${what}: pass --as and --token (or use the remembered login).`, EXIT.refused);
+    const summary = (plan) => [
+        `Checkouts: ${plan.count}, ${bytesWords(plan.totalBytes)}. ${plan.waitingReview} waiting for review, ${plan.withChanges} kept because they have changes.`,
+        plan.go.length === 0 ? "A clean up now would free nothing." : `A clean up now would free about ${bytesWords(plan.freeBytes)} (${plan.go.length} checkout${plan.go.length === 1 ? "" : "s"}): toolroll storage clean`,
+        `A finished task's clean checkout is removed ${cleanupWords(plan.cleanup)}; its branch stays.`,
+    ];
+    const itemLine = (one) => `  ${bytesWords(one.bytes).padStart(8)}  ${one.path}${one.why === null ? "" : `  (${whyWords(one)})`}`;
+    if (action === undefined) {
+        const plan = await checkoutPlan(store, pool, context.clock(), { manual: true });
+        const report = storageReport(store, context.databaseFile, plan.go.length === 0 ? "nothing to clean up" : `about ${bytesWords(plan.freeBytes)} to clean up`);
+        return succeed(context.write, context.json, "storage", { ...report, checkouts: checkoutSummary(plan) }, () => [
+            `${report.folder}: ${bytesWords(report.total)}`,
+            ...report.lines.map(one => `  ${one.what.padEnd(17)} ${bytesWords(one.bytes).padStart(8)}${one.count === undefined ? "" : `  (${one.count})`}${one.note === undefined ? "" : `  ${one.note}`}`),
+            ...summary(plan),
+        ]);
+    }
+    if (action === "cleanup") {
+        if (rest.length === 0) {
+            const cleanup = store.checkoutCleanup();
+            return succeed(context.write, context.json, command, { cleanup }, () => [`A finished task's clean checkout is removed ${cleanupWords(cleanup)}; its branch stays.`]);
+        }
+        const cleanup = rest.length === 1 ? parseCleanup(rest[0]) : undefined;
+        if (cleanup === undefined)
+            return fail(context.write, context.json, command, "usage", `Use storage cleanup <${CLEANUP_CHOICES.map(one => one.value).join("|")}>.`, EXIT.usage);
+        const actor = await operator();
+        if (actor === null)
+            return refused("sets checkout cleanup");
+        const saved = store.setCheckoutCleanup(cleanup, actor, context.clock());
+        return succeed(context.write, context.json, command, { cleanup: saved }, () => [`Saved. A finished task's clean checkout is removed ${cleanupWords(saved)}; its branch stays.`]);
+    }
+    if (action === "clean") {
+        if (rest.length > 0)
+            return fail(context.write, context.json, command, "usage", "Use storage clean to preview, then storage clean --yes.", EXIT.usage);
+        if (!flags.has("yes")) {
+            const plan = await checkoutPlan(store, pool, context.clock(), { manual: true });
+            return succeed(context.write, context.json, command, { preview: true, go: plan.go, stay: plan.stay, freeBytes: plan.freeBytes }, () => [
+                ...(plan.go.length === 0 ? ["Nothing to clean up."] : [`Would remove ${plan.go.length} checkout${plan.go.length === 1 ? "" : "s"}, freeing about ${bytesWords(plan.freeBytes)} (their branches stay):`, ...plan.go.map(itemLine)]),
+                ...(plan.stay.length === 0 ? [] : [`Stays (${plan.stay.length}):`, ...plan.stay.map(itemLine)]),
+                plan.go.length === 0 ? "Nothing was removed." : "Nothing was removed. Run toolroll storage clean --yes to remove them.",
+            ]);
+        }
+        const actor = await operator();
+        if (actor === null)
+            return refused("cleans up checkouts");
+        const done = await cleanCheckouts(store, pool, context.clock, { manual: true, actor });
+        return succeed(context.write, context.json, command, { removed: done.removed, kept: done.kept, freedBytes: done.freed }, () => [
+            done.removed.length === 0 ? "Nothing to clean up." : `Removed ${done.removed.length} checkout${done.removed.length === 1 ? "" : "s"}, about ${bytesWords(done.freed)}; their branches stay.`,
+            ...done.removed.map(itemLine),
+            ...done.kept.map(one => `  kept ${one.path} (${whyWords({ why: one.why })})`),
+        ]);
+    }
+    if (action === "discard") {
+        const [path, ...extra] = rest;
+        if (path === undefined || extra.length > 0)
+            return fail(context.write, context.json, command, "usage", "Use storage discard <path> --yes.", EXIT.usage);
+        const target = resolve(path);
+        if (store.getWorktree(target) === null)
+            return fail(context.write, context.json, command, "not-found", `${target} is not a task checkout. toolroll storage clean lists them.`, EXIT.refused);
+        if (!flags.has("yes"))
+            return fail(context.write, context.json, command, "usage", `This throws away ${target} and its uncommitted changes (its branch stays). Add --yes to discard it.`, EXIT.usage);
+        const actor = await operator();
+        if (actor === null)
+            return refused("discards a checkout");
+        const done = await discardCheckout(store, pool, target, context.clock(), actor);
+        if (!done.ok)
+            return fail(context.write, context.json, command, "refused", done.message, EXIT.refused);
+        return succeed(context.write, context.json, command, { discarded: target, freedBytes: done.bytes }, () => [`Discarded ${target}, about ${bytesWords(done.bytes)}; its branch stays.`]);
+    }
+    return fail(context.write, context.json, command, "usage", "Use storage, storage cleanup <when>, storage clean [--yes] or storage discard <path> --yes.", EXIT.usage);
+}
+function checkoutSummary(plan) {
+    return { count: plan.count, totalBytes: plan.totalBytes, waitingReview: plan.waitingReview, withChanges: plan.withChanges, cleanBytes: plan.freeBytes, cleanCount: plan.go.length, cleanup: plan.cleanup };
+}
 /** `policy show | set` (sprint 8): the organisation policy. Setting it takes an instance operator's credentials; each rule
  * that changed is in the ledger, before → after. A flag left out keeps its rule; "any" lifts it. */
 async function policyCommand(positional, flags, context) {

package/dist/prompt.d.ts

@@ -7,6 +7,17 @@
  */
 /** Whether asking is even possible: a human on both ends of the pipe. */
 export declare function interactive(): boolean;
+/** The program names of this process's ancestors, nearest first: each one's command and, for a script run by node
+ * or python, the script's name. Empty where `ps` cannot say. */
+export declare function ancestorPrograms(): string[];
+/**
+ * Whether a coding agent is running this command. An agent's shell can be a
+ * real terminal, yet whatever is printed lands in its transcript and nobody
+ * types at the prompt, so it is treated like no terminal at all. The agent is
+ * known by a variable it sets or, for one that sets none, by the program above
+ * this one. `programs` is read only for this process's own environment.
+ */
+export declare function underAgent(env?: Record<string, string | undefined>, programs?: () => readonly string[]): boolean;
 export declare function ask(question: string): Promise<string>;
 /** Like ask, but what is typed never echoes — passwords live here. */
 /**

package/dist/prompt.js

@@ -5,11 +5,52 @@
  * gets the same immediate usage refusal as always, because a scheduler
  * hanging on "password:" at 3am is the one bug this module must not have.
  */
+import { spawnSync } from "node:child_process";
+import { basename } from "node:path";
 import { createInterface } from "node:readline";
 /** Whether asking is even possible: a human on both ends of the pipe. */
 export function interactive() {
     return process.stdin.isTTY === true && process.stdout.isTTY === true;
 }
+/** Variables a coding agent sets for the commands it runs. Only Codex's own CODEX_ names: a person exports others
+ * (CODEX_HOME, CODEX_API_KEY, a profile) for themselves. */
+const AGENT_VARIABLES = ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "GEMINI_CLI", "CURSOR_AGENT", "OPENCODE", "GOOSE_TERMINAL", "AIDER_CHAT",
+    "CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "CODEX_THREAD_ID", "CODEX_CI", "CODEX_MANAGED_BY_NPM", "CODEX_MANAGED_BY_BUN"];
+/** Agents known by the program running this command, for those that set no variable of their own. */
+const AGENT_PROGRAMS = new Set(["claude", "codex", "gemini", "cursor-agent", "opencode", "aider", "copilot", "amp", "goose", "crush", "qwen"]);
+/** The program names of this process's ancestors, nearest first: each one's command and, for a script run by node
+ * or python, the script's name. Empty where `ps` cannot say. */
+export function ancestorPrograms() {
+    if (process.platform === "win32")
+        return [];
+    const names = [];
+    let pid = process.ppid;
+    for (let depth = 0; depth < 12 && pid > 1; depth++) {
+        const answered = spawnSync("/bin/ps", ["-o", "ppid=,args=", "-p", String(pid)], { encoding: "utf8", timeout: 2000 });
+        const found = answered.status === 0 ? /^\s*(\d+)\s+(.*)$/.exec(answered.stdout.trim()) : null;
+        if (!found)
+            break;
+        const words = found[2].split(/\s+/);
+        const program = basename(words[0] ?? "");
+        names.push(program);
+        if (/^(node|bun|deno|python[\d.]*)$/.test(program) && words[1] !== undefined && !words[1].startsWith("-"))
+            names.push(basename(words[1]));
+        pid = Number(found[1]);
+    }
+    return names;
+}
+/**
+ * Whether a coding agent is running this command. An agent's shell can be a
+ * real terminal, yet whatever is printed lands in its transcript and nobody
+ * types at the prompt, so it is treated like no terminal at all. The agent is
+ * known by a variable it sets or, for one that sets none, by the program above
+ * this one. `programs` is read only for this process's own environment.
+ */
+export function underAgent(env = process.env, programs = env === process.env ? ancestorPrograms : () => []) {
+    if (AGENT_VARIABLES.some(name => env[name] !== undefined && env[name] !== ""))
+        return true;
+    return programs().some(name => AGENT_PROGRAMS.has(name.replace(/\.(?:js|mjs|cjs|py|exe)$/, "")));
+}
 export function ask(question) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     return new Promise(resolve => rl.question(question, answer => {