@iseoane/agent-depot 0.6.3 → 0.6.5

package/dist/src/package-host-state.js

@@ -1,4 +1,4 @@
-import { lstat, readFile } from "node:fs/promises";
+import { lstat, readFile, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 import { canonicalizeGitSourceUrl } from "./git-source.js";
@@ -246,8 +246,10 @@ async function readPiCheckoutEvidence(checkoutPath, sourceIdentity) {
             runPiGit(checkoutPath, ["status", "--porcelain", "--untracked-files=all"]),
             runPiGit(checkoutPath, ["show", "HEAD:package.json"]),
         ]);
-        const expectedRoot = path.resolve(checkoutPath);
-        if (path.resolve(topLevel) !== expectedRoot)
+        // Git prints a forward-slash, long-name path on Windows (C:/Users/runneradmin/...) while the
+        // checkout path may use backslashes or an 8.3 short name (C:\Users\RUNNER~1\...); realpath makes both canonical.
+        const [canonicalTopLevel, canonicalCheckout] = await Promise.all([realpath(topLevel), realpath(checkoutPath)]);
+        if (canonicalTopLevel !== canonicalCheckout)
             return unavailable("the package path is not the root of its Git checkout");
         if (normalizeRepository(piSourceIdentityFromUrl(origin)) !== normalizeRepository(sourceIdentity)) {
             return unavailable("the Git checkout origin does not match the selected Pi package Source");
@@ -303,7 +305,7 @@ async function isMatchingRootOnlyNpmLock(checkoutPath, manifest) {
             if (manifest[key] !== undefined && (!isRecord(manifest[key]) || Object.keys(manifest[key]).length !== 0))
                 return false;
         }
-        const allowed = ["name", "version", "license", "peerDependencies", "peerDependenciesMeta"];
+        const allowed = ["name", "version", "license", "peerDependencies", "peerDependenciesMeta", "bin"];
         const equalJson = (left, right) => {
             if (left === right)
                 return true;
@@ -313,13 +315,49 @@ async function isMatchingRootOnlyNpmLock(checkoutPath, manifest) {
             return keys.length === Object.keys(right).length
                 && keys.every((key) => Object.hasOwn(right, key) && equalJson(left[key], right[key]));
         };
-        return Object.keys(root).every((key) => allowed.includes(key) && equalJson(root[key], manifest[key]))
-            && ["peerDependencies", "peerDependenciesMeta"].every((key) => equalJson(root[key], manifest[key]));
+        // npm records `bin` in its normalized form, so compare against that, not the raw manifest value.
+        const expectedBin = normalizeNpmBin(manifest);
+        return Object.keys(root).every((key) => allowed.includes(key)
+            && equalJson(root[key], key === "bin" ? expectedBin : manifest[key]))
+            && ["peerDependencies", "peerDependenciesMeta"].every((key) => equalJson(root[key], manifest[key]))
+            && equalJson(root.bin, expectedBin);
     }
     catch {
         return false;
     }
 }
+/**
+ * npm's `bin` normalization for the string and object forms (npm-normalize-package-bin): a string
+ * becomes `{ [unscoped name]: path }` and every target loses a leading `./`. Verified against
+ * `npm install --package-lock-only` (npm 12). Array and malformed forms yield `undefined`, so a
+ * lock that carries `bin` for them is rejected instead of guessed.
+ */
+function normalizeNpmBin(manifest) {
+    const raw = manifest.bin;
+    let entries;
+    if (typeof raw === "string") {
+        if (typeof manifest.name !== "string")
+            return undefined;
+        entries = { [manifest.name.replace(/^@[^/]+\//u, "")]: raw };
+    }
+    else if (isRecord(raw)) {
+        entries = raw;
+    }
+    else {
+        return undefined;
+    }
+    const clean = {};
+    for (const [key, target] of Object.entries(entries)) {
+        const name = path.posix.basename(key.replace(/[\\:]/gu, "/"));
+        if (typeof target !== "string" || name === "" || name === "." || name === "..")
+            return undefined;
+        const normalizedTarget = path.posix.join("/", target.replace(/\\/gu, "/")).slice(1);
+        if (normalizedTarget === "")
+            return undefined;
+        clean[name] = normalizedTarget;
+    }
+    return Object.keys(clean).length === 0 ? undefined : clean;
+}
 async function runPiGit(checkoutPath, args) {
     const result = await runProcess("git", ["-C", checkoutPath, ...args], {
         captureStdout: true,

package/dist/src/package-state.js

@@ -2,7 +2,7 @@ import { chmod, mkdir, readFile, rmdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { setTimeout as delay } from "node:timers/promises";
 import path from "node:path";
-import { writeFileAtomically } from "./atomic-file.js";
+import { isLockContention, writeFileAtomically } from "./atomic-file.js";
 import { PACKAGE_HOSTS, selectionKey, } from "./package-model.js";
 import { PROJECT_MANIFEST_VERSION, ProjectManifestError, parseProjectManifest } from "./project-manifest.js";
 import { defaultSourceStatePath } from "./source-state.js";
@@ -385,7 +385,7 @@ export class PackageStateStore {
                 };
             }
             catch (error) {
-                if (!isAlreadyExists(error)) {
+                if (!isLockContention(error)) {
                     throw error;
                 }
                 if (Date.now() >= deadline) {
@@ -399,6 +399,3 @@ export class PackageStateStore {
 function isMissingFile(error) {
     return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
-function isAlreadyExists(error) {
-    return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
-}

package/dist/src/process-runner.js

@@ -1,11 +1,164 @@
 import { spawn } from "node:child_process";
-/** Runs a command with an argument vector and no shell; rejects only when spawning fails. */
+import { AsyncLocalStorage } from "node:async_hooks";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+const childOutputSinks = new AsyncLocalStorage();
+/**
+ * Runs `work` so that every child started by `runProcess` inside it (however deep, whichever runner
+ * a caller injected) also reports its output to `sink`. This is a read-only tap: capture, caps,
+ * timeouts and results behave exactly as without a sink.
+ */
+export function withChildOutput(sink, work) {
+    return childOutputSinks.run(sink, work);
+}
+/** cmd.exe metacharacters, escaped with `^` (same set as cross-spawn). */
+const CMD_META_CHARACTERS = /([()\][%!^"`<>&|;, *?])/gu;
+/**
+ * Characters that could chain commands or split the line if an npm cmd-shim's
+ * `%*` re-parse flips quote parity; rejecting them prevents injection, though an
+ * argument with `"` can still reach the program altered.
+ */
+const CMD_UNSAFE_ARGUMENT = /[\r\n&|<>]/u;
+/** Quotes one argument for the MSVCRT parser: backslashes double only before a quote or the closing quote. */
+function quoteMsvcrtArgument(argument) {
+    let encoded = "";
+    let backslashes = 0;
+    for (const character of argument) {
+        if (character === "\\") {
+            backslashes += 1;
+            continue;
+        }
+        encoded += character === '"'
+            ? `${"\\".repeat(backslashes * 2 + 1)}"`
+            : `${"\\".repeat(backslashes)}${character}`;
+        backslashes = 0;
+    }
+    return `"${encoded}${"\\".repeat(backslashes * 2)}"`;
+}
+function escapeCmdArgument(argument, index) {
+    if (CMD_UNSAFE_ARGUMENT.test(argument)) {
+        throw Object.assign(new Error(`Argument ${index} cannot be passed safely to a Windows batch file (line break or & | < > character)`), { code: "EINVAL" });
+    }
+    return quoteMsvcrtArgument(argument).replace(CMD_META_CHARACTERS, "^$1");
+}
+/**
+ * Windows cannot spawn a `.cmd`/`.bat` file without a shell (Node rejects it
+ * since CVE-2024-27980), so it runs through `cmd.exe /d /s /c` with every
+ * argument quoted and escaped; any other command is spawned directly. An
+ * argument cmd.exe could misparse is rejected with `EINVAL`.
+ */
+export function spawnInvocation(command, args, platform = process.platform) {
+    if (platform !== "win32" || !/\.(?:cmd|bat)$/iu.test(command)) {
+        return { command, args, windowsVerbatimArguments: false };
+    }
+    const line = [path.win32.normalize(command).replace(CMD_META_CHARACTERS, "^$1"), ...args.map(escapeCmdArgument)].join(" ");
+    return { command: process.env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], windowsVerbatimArguments: true };
+}
+/**
+ * How long `runProcess` waits after asking a process (tree) to stop before it escalates (POSIX: SIGKILL)
+ * or, once nothing more can be done, gives up on the stdio pipes a surviving descendant holds open.
+ */
+const KILL_GRACE_MS = 2_000;
+/** Upper bound for the `ps` snapshot of the process tree. */
+const PROCESS_LIST_TIMEOUT_MS = 1_000;
+/**
+ * Terminates a Windows child and everything it started. `child.kill()` ends
+ * only the direct child, so for a batch file it would stop cmd.exe and leave
+ * the real program running with the stdio pipes open; a program that starts
+ * helpers has the same problem. Falls back to
+ * `child.kill()` when taskkill cannot be started or fails (for example because
+ * the child already exited). Never throws and does not wait for taskkill.
+ */
+function killWindowsProcessTree(child) {
+    const { pid } = child;
+    if (pid === undefined) {
+        child.kill();
+        return;
+    }
+    const taskkill = path.win32.join(process.env.SystemRoot || process.env.windir || "C:\\Windows", "System32", "taskkill.exe");
+    try {
+        spawn(taskkill, ["/pid", String(pid), "/T", "/F"], { shell: false, stdio: "ignore", windowsHide: true })
+            .on("error", () => { child.kill(); })
+            .on("close", (code) => { if (code !== 0)
+            child.kill(); });
+    }
+    catch {
+        child.kill();
+    }
+}
+/**
+ * The pids of `rootPid` and every process descended from it, from a single `ps` snapshot. The child
+ * stays in agent-depot's own process group and session (a detached group has no controlling terminal,
+ * so a git or ssh prompt would fail, and a terminal Ctrl-C would no longer reach it), so a group kill
+ * is not available. Never rejects: falls back to `rootPid` alone when `ps` cannot be run or read.
+ */
+function listProcessTree(rootPid) {
+    return new Promise((resolve) => {
+        const tree = [rootPid];
+        let ps;
+        try {
+            ps = spawn("ps", ["-A", "-o", "pid=,ppid="], { stdio: ["ignore", "pipe", "ignore"], timeout: PROCESS_LIST_TIMEOUT_MS });
+        }
+        catch {
+            resolve(tree);
+            return;
+        }
+        let output = "";
+        ps.stdout?.setEncoding("utf8");
+        ps.stdout?.on("data", (chunk) => { output += chunk; });
+        // A missing `ps` is followed by `close` with no output, which leaves just the root.
+        ps.on("error", () => { });
+        ps.on("close", () => {
+            const children = new Map();
+            for (const line of output.split("\n")) {
+                const [pid, parent] = line.trim().split(/\s+/u).map(Number);
+                if (pid === undefined || parent === undefined || !Number.isInteger(pid) || !Number.isInteger(parent))
+                    continue;
+                children.set(parent, [...(children.get(parent) ?? []), pid]);
+            }
+            for (const pid of tree) {
+                for (const child of children.get(pid) ?? [])
+                    if (!tree.includes(child))
+                        tree.push(child);
+            }
+            resolve(tree);
+        });
+    });
+}
+function signalProcesses(pids, signal) {
+    for (const pid of pids) {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+/**
+ * Runs a command with an argument vector and no shell (except cmd.exe for
+ * Windows batch files); rejects only when spawning fails. For every command, a timeout or output overflow kills the whole process tree and reports
+ * it as terminated by `SIGTERM`, and the result is returned within a bounded
+ * time even if a descendant survives and holds the stdio pipes open. On POSIX the
+ * tree is the child and its descendants at the moment of the kill (from a `ps`
+ * snapshot, because the child shares agent-depot's process group): they get
+ * `SIGTERM`, and if the command has still not closed its output after a grace
+ * period, the members of that snapshot still running get `SIGKILL`.
+ * A process that left the tree beforehand (daemonized, or orphaned by an exited
+ * child) is not killed. On Windows, an argument to a `.cmd`/`.bat` file containing a line
+ * break or `& | < >` is rejected with `EINVAL` because cmd.exe cannot carry it
+ * safely.
+ */
 export function runProcess(command, args, options = {}) {
     return new Promise((resolve, reject) => {
-        const child = spawn(command, [...args], {
+        const invocation = spawnInvocation(command, args);
+        const sink = childOutputSinks.getStore();
+        const child = spawn(invocation.command, [...invocation.args], {
             ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
             shell: false,
-            stdio: ["ignore", options.captureStdout ? "pipe" : "ignore", "pipe"],
+            windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+            // Without a capture, stdout is piped only for a sink, and then discarded after it is shown.
+            stdio: ["ignore", options.captureStdout || sink !== undefined ? "pipe" : "ignore", "pipe"],
         });
         const stdout = [];
         let stdoutBytes = 0;
@@ -13,22 +166,91 @@ export function runProcess(command, args, options = {}) {
         let stderrBytes = 0;
         let outputTooLarge = false;
         let timedOut = false;
+        let settled = false;
+        let terminating = false;
+        let killedByRunner = false;
+        let graceTimer;
+        let posixTree = [];
+        const isRunning = () => child.exitCode === null && child.signalCode === null;
+        const settle = (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            // taskkill ends the process with exit code 1 and no signal, and an escalated kill ends with SIGKILL; report both like child.kill() does, so callers see a terminated process.
+            if (killedByRunner && (signal === null || signal === "SIGKILL")) {
+                code = null;
+                signal = "SIGTERM";
+            }
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            if (graceTimer !== undefined)
+                clearTimeout(graceTimer);
+            resolve({ code, signal, stdout: Buffer.concat(stdout), stderr, outputTooLarge, ...(timedOut ? { timedOut: true } : {}) });
+        };
+        // A surviving descendant keeps the pipes open, so `close` may never come: give up on them.
+        const giveUp = () => {
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            settle(child.exitCode, child.signalCode);
+        };
+        const terminate = () => {
+            if (terminating)
+                return;
+            terminating = true;
+            // A child that already exited must not be killed: its pid may have been reused.
+            const running = isRunning();
+            if (running)
+                killedByRunner = true;
+            if (process.platform === "win32") {
+                if (running)
+                    killWindowsProcessTree(child);
+                graceTimer = setTimeout(giveUp, KILL_GRACE_MS);
+                return;
+            }
+            if (child.pid === undefined)
+                return; // never spawned: `error` has already rejected
+            if (!running) {
+                graceTimer = setTimeout(giveUp, KILL_GRACE_MS);
+                return;
+            }
+            posixTree = [child.pid];
+            // The child's own pid is left alone once it has exited, as it may have been reused.
+            const alive = (pids) => pids.filter((pid) => pid !== child.pid || isRunning());
+            // Snapshot before signalling: once the child dies its descendants are reparented and can no longer be found.
+            listProcessTree(child.pid).then((tree) => {
+                posixTree = tree;
+                signalProcesses(alive(tree), "SIGTERM");
+            }, () => {
+                signalProcesses(alive(posixTree), "SIGTERM");
+            });
+            graceTimer = setTimeout(() => {
+                signalProcesses(alive(posixTree), "SIGKILL");
+                graceTimer = setTimeout(giveUp, KILL_GRACE_MS);
+            }, KILL_GRACE_MS);
+        };
         const timeout = options.timeoutMs === undefined ? undefined : setTimeout(() => {
             timedOut = true;
-            child.kill();
+            terminate();
         }, options.timeoutMs);
         timeout?.unref();
+        const stdoutDecoder = new StringDecoder("utf8");
+        const showStdout = sink !== undefined && (!options.captureStdout || options.streamStdout === true);
         child.stdout?.on("data", (chunk) => {
-            stdoutBytes += chunk.length;
-            if (options.maxOutputBytes !== undefined && stdoutBytes > options.maxOutputBytes) {
-                outputTooLarge = true;
-                child.kill();
-                return;
+            if (options.captureStdout) {
+                stdoutBytes += chunk.length;
+                if (options.maxOutputBytes !== undefined && stdoutBytes > options.maxOutputBytes) {
+                    outputTooLarge = true;
+                    terminate();
+                    return;
+                }
+                stdout.push(chunk);
             }
-            stdout.push(chunk);
+            if (showStdout)
+                sink(stdoutDecoder.write(chunk), "stdout");
         });
         child.stderr?.setEncoding("utf8");
         child.stderr?.on("data", (chunk) => {
+            sink?.(chunk, "stderr");
             const bytes = Buffer.from(chunk);
             const remaining = options.maxStderrBytes === undefined
                 ? bytes.length : Math.max(0, options.maxStderrBytes - stderrBytes);
@@ -36,14 +258,10 @@ export function runProcess(command, args, options = {}) {
             stderr += bytes.subarray(0, remaining).toString("utf8");
             if (options.maxStderrBytes !== undefined && stderrBytes > options.maxStderrBytes) {
                 outputTooLarge = true;
-                child.kill();
+                terminate();
             }
         });
         child.on("error", reject);
-        child.on("close", (code, signal) => {
-            if (timeout !== undefined)
-                clearTimeout(timeout);
-            resolve({ code, signal, stdout: Buffer.concat(stdout), stderr, outputTooLarge, ...(timedOut ? { timedOut: true } : {}) });
-        });
+        child.on("close", settle);
     });
 }

package/dist/src/profile-cli.js

@@ -2,16 +2,17 @@ import { readFile } from "node:fs/promises";
 import { buildProfileExport, requireProfileExportSelection, writeProfileExport } from "./profile-export.js";
 import { applyProfileImport, buildProfileImport } from "./profile-import.js";
 import { serializeProfile } from "./profile.js";
+import { NO_PROGRESS } from "./progress.js";
 import { CliUsageError } from "./usage-error.js";
 export const EXPORT_USAGE = "agent-depot export [--out <file>] [--no-sources] [--no-skills] [--no-apps] [--no-packages] [--source <id|url>...] [--skill <path|name>...] [--app <name>...] [--package <selection>...]";
 export const IMPORT_USAGE = "agent-depot import <file> [--yes] [--no-sources] [--no-skills] [--no-apps] [--no-packages] [--source <id|url>...] [--skill <path|name>...] [--app <name>...] [--package <selection>...]";
-export async function runProfileExport(values, operations, apps, output, diagnostic, homeDirectory, packageOperations) {
+export async function runProfileExport(values, operations, apps, output, diagnostic, homeDirectory, packageOperations, progress = NO_PROGRESS) {
     const { filters, out } = parseProfileOptions(values, false);
-    const plan = await buildProfileExport(operations, apps, {
+    const plan = await progress.run("Building Profile export", () => buildProfileExport(operations, apps, {
         ...filters,
         homeDirectory,
         ...(packageOperations === undefined ? {} : { packageOperations }),
-    });
+    }));
     for (const line of plan.preview)
         diagnostic(line);
     requireProfileExportSelection(plan.profile);
@@ -67,7 +68,7 @@ function parseProfileOptions(values, importing) {
     }
     return { filters, out, confirmed };
 }
-export async function runProfileImport(values, operations, apps, output, environment = {}) {
+export async function runProfileImport(values, operations, apps, output, environment = {}, progress = NO_PROGRESS) {
     const file = values[0];
     if (!file || file.startsWith("--"))
         throw new CliUsageError(`Usage: ${IMPORT_USAGE}`);
@@ -80,14 +81,15 @@ export async function runProfileImport(values, operations, apps, output, environ
     catch (error) {
         throw new Error(`${file}: invalid JSON (${error instanceof Error ? error.message : String(error)})`);
     }
-    const plan = await buildProfileImport(input, operations, apps, filters, environment.packageOperations);
+    const plan = await progress.run("Building import preview", () => buildProfileImport(input, operations, apps, filters, environment.packageOperations));
     for (const line of plan.preview)
         output(line);
     if (!confirmed) {
         output("Import not confirmed; rerun with --yes. Nothing was written.");
         return 0;
     }
-    const results = await applyProfileImport(plan, operations, apps, confirmed, output, environment);
+    // Skill and Package items refresh their Git Sources, and git may ask for credentials on the terminal.
+    const results = await progress.run("Applying import", () => applyProfileImport(plan, operations, apps, confirmed, output, environment), { mayPrompt: true });
     for (const result of results)
         output(`${result.status}: ${result.item.label}${result.detail ? `; ${result.detail}` : ""}`);
     return results.some(result => result.status === "failed") ? 1 : 0;

package/dist/src/progress.js

@@ -0,0 +1,157 @@
+import stringWidth from "string-width";
+import { animationEnabled, formatElapsed, SPINNER_FRAMES, SPINNER_TICK_MS, STATIC_GLYPH } from "./tui/working-model.js";
+/** Progress that shows nothing, for embedders and tests that capture output themselves. */
+export const NO_PROGRESS = { run: (_label, work) => work(), clear: () => undefined };
+const ERASE_LINE = "\r\u001b[2K";
+/** Cuts `text` to under `width` terminal columns so a redraw never wraps and cursor movement stays exact. */
+function fit(text, width) {
+    if (width === undefined || width < 2 || stringWidth(text) < width)
+        return text;
+    let kept = "";
+    let used = 0;
+    for (const character of text) {
+        const columns = stringWidth(character);
+        if (used + columns > width - 2)
+            break;
+        kept += character;
+        used += columns;
+    }
+    return `${kept}…`;
+}
+/** How many child output lines the spinner shows under its own line. */
+const TAIL_LINES = 3;
+/** A child line longer than this without a line break is shown as it is, so a runaway line cannot grow memory. */
+const MAX_PENDING_LINE = 4096;
+// eslint-disable-next-line no-control-regex
+const TERMINAL_ESCAPES = /\u001b(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001b]*(?:\u0007|\u001b\\)|[@-Z\\-_])/gu;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu;
+/**
+ * Child output is untrusted terminal input: an escape sequence would move the cursor and break the
+ * redraw, and a `\r` progress bar (npm, git) should show only its latest state.
+ */
+function displayLine(raw) {
+    const afterReturn = raw.replace(/\r$/u, "").split("\r").at(-1) ?? "";
+    return afterReturn.replace(TERMINAL_ESCAPES, "").replaceAll("\t", " ").replace(CONTROL_CHARACTERS, "").trimEnd();
+}
+/** Turns chunks of each output stream into complete display lines; `flush` emits what is left unterminated. */
+function lineSplitter(onLine) {
+    const pending = { stdout: "", stderr: "" };
+    const emit = (raw) => {
+        const line = displayLine(raw);
+        if (line !== "")
+            onLine(line);
+    };
+    return {
+        write(text, stream) {
+            const parts = (pending[stream] + text).split("\n");
+            pending[stream] = parts.pop() ?? "";
+            for (const part of parts)
+                emit(part);
+            if (pending[stream].length > MAX_PENDING_LINE) {
+                emit(pending[stream]);
+                pending[stream] = "";
+            }
+        },
+        flush() {
+            for (const stream of ["stdout", "stderr"]) {
+                emit(pending[stream]);
+                pending[stream] = "";
+            }
+        },
+    };
+}
+/** Moves to the first row of a frame of `rows` rows and erases it, so a frame with a tail leaves nothing behind. */
+function eraseFrame(rows) {
+    return rows <= 1 ? ERASE_LINE : `\u001b[${rows - 1}A\r\u001b[J`;
+}
+function withEllipsis(label) {
+    return label.endsWith("…") ? label : `${label}…`;
+}
+/** Creates the progress reporter for one CLI run. */
+export function createProgress(options = {}) {
+    const stream = options.stream ?? process.stderr;
+    const env = options.env ?? process.env;
+    const now = options.now ?? Date.now;
+    const timers = options.timers ?? {
+        setInterval: (callback, ms) => setInterval(callback, ms),
+        clearInterval: (timer) => clearInterval(timer),
+    };
+    const tap = options.tapChildOutput;
+    const verbose = options.verbose === true;
+    let active = false;
+    let drawnRows = 0;
+    function clear() {
+        if (drawnRows === 0)
+            return;
+        const rows = drawnRows;
+        drawnRows = 0;
+        stream.write(eraseFrame(rows));
+    }
+    /** Runs `work` while its child output goes to `splitter`; the tap goes silent as soon as the step ends. */
+    async function showChildOutput(work, splitter) {
+        if (tap === undefined)
+            return work();
+        let live = true;
+        try {
+            return await tap((text, source) => { if (live)
+                splitter.write(text, source); }, work);
+        }
+        finally {
+            live = false;
+            splitter.flush();
+        }
+    }
+    async function run(label, work, runOptions = {}) {
+        if (active)
+            return work();
+        const text = withEllipsis(label);
+        if (verbose || stream.isTTY !== true || !animationEnabled(env) || runOptions.mayPrompt === true) {
+            // Not animated: one persistent line, so logs and pipes stay readable and nothing needs erasing.
+            stream.write(`${stream.isTTY === true ? `${STATIC_GLYPH} ` : ""}${text}\n`);
+            active = true;
+            try {
+                // Verbose output is plain lines, so it is also safe next to a prompt; otherwise child output stays hidden.
+                return verbose ? await showChildOutput(work, lineSplitter((line) => stream.write(`${line}\n`))) : await work();
+            }
+            finally {
+                active = false;
+            }
+        }
+        const startedAt = now();
+        let tick = 0;
+        const tail = [];
+        // A terminal too short for the tail keeps the single-line spinner rather than scrolling.
+        const room = stream.rows === undefined || stream.rows >= TAIL_LINES + 2;
+        const splitter = lineSplitter((line) => {
+            if (!room)
+                return;
+            tail.push(line);
+            if (tail.length > TAIL_LINES)
+                tail.shift();
+        });
+        const draw = () => {
+            const elapsed = formatElapsed(now() - startedAt);
+            const line = `${SPINNER_FRAMES[tick % SPINNER_FRAMES.length]} ${text}${elapsed === "" ? "" : ` ${elapsed}`}`;
+            tick += 1;
+            const frame = [line, ...tail.map((child) => `  ${child}`)].map((row) => fit(row, stream.columns));
+            const previousRows = drawnRows;
+            drawnRows = frame.length;
+            stream.write(`${eraseFrame(previousRows)}${frame.join("\n")}`);
+        };
+        active = true;
+        draw();
+        const timer = timers.setInterval(draw, SPINNER_TICK_MS);
+        // A redraw timer alone must never keep the process alive.
+        timer.unref();
+        try {
+            return await showChildOutput(work, splitter);
+        }
+        finally {
+            timers.clearInterval(timer);
+            active = false;
+            clear();
+        }
+    }
+    return { run, clear };
+}

package/dist/src/source-state.js

@@ -2,7 +2,7 @@ import { mkdir, readFile, rmdir, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { setTimeout as delay } from "node:timers/promises";
 import path from "node:path";
-import { writeFileAtomically } from "./atomic-file.js";
+import { isLockContention, writeFileAtomically } from "./atomic-file.js";
 import { canonicalizeGitSourceUrl, sourceIdForUrl } from "./git-source.js";
 import { parseProjectManifest } from "./project-manifest.js";
 const EMPTY_STATE = Object.freeze({
@@ -218,7 +218,7 @@ export class SourceStateStore {
                 };
             }
             catch (error) {
-                if (!isAlreadyExists(error)) {
+                if (!isLockContention(error)) {
                     throw error;
                 }
                 if (Date.now() >= deadline) {
@@ -235,6 +235,3 @@ function errorCode(error) {
 function isMissingFile(error) {
     return errorCode(error) === "ENOENT";
 }
-function isAlreadyExists(error) {
-    return errorCode(error) === "EEXIST";
-}

package/dist/src/tui/adoption-actions.js

@@ -3,6 +3,7 @@ import { runInstall } from "./catalog-installs.js";
 import { errorText } from "./batch.js";
 import { defaultAdoptionHosts, findAdoptionCandidates, prepareAdoption } from "./installations.js";
 import { answerYesNo, applyChecklistOutcome, hostChecklistKey, moveCursor, versionInputKey } from "./mode-keys.js";
+import { busy } from "./working-model.js";
 function cancel(context) {
     context.setMessage({ kind: "ok", text: "Adoption cancelled" });
     context.browse();
@@ -22,7 +23,7 @@ export async function startAdoption(context, group) {
         return;
     }
     context.setMessage(undefined);
-    context.setMode({ kind: "busy", label: `Looking for a Source Skill named ${entry.name}...` });
+    context.setMode(busy(`Looking for a Source Skill named ${entry.name}…`));
     try {
         const candidates = await findAdoptionCandidates(context.operations, entry);
         if (!context.isMounted())
@@ -43,7 +44,7 @@ export async function startAdoption(context, group) {
     }
 }
 async function prepare(context, mode, version) {
-    context.setMode({ kind: "busy", label: `Refreshing source and checking that ${mode.entry.name} matches...` });
+    context.setMode(busy(`Refreshing source and checking that ${mode.entry.name} matches…`));
     try {
         const adoption = await prepareAdoption(context.operations, context.env, mode.entry, mode.skill, { hosts: mode.hosts, version });
         if (!context.isMounted())
@@ -55,7 +56,7 @@ async function prepare(context, mode, version) {
     }
 }
 async function confirm(context, mode, exposure) {
-    context.setMode({ kind: "busy", label: `Adopting ${mode.entry.name}...` });
+    context.setMode(busy(`Adopting ${mode.entry.name}…`));
     let result;
     try {
         result = { kind: "ok", text: (await runInstall(mode.adoption.prepared, context.operations, exposure)).join(" ") };