@iseoane/agent-depot 0.6.13 → 0.6.15

package/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.15] - 2026-11-12
+
+### Changed
+
+- Sources marks a refreshed Source as `✓ refreshed` without the elapsed time;
+  `… refreshing Ns` keeps its counter (#123).
+- Progress lines share one format; a one-item batch no longer shows `(1/1)` (#123).
+- Update previews say "No updates can be applied" when nothing applies, empty
+  previews no longer show "Review 1 of 0", and commit-only Package versions read
+  `commit xxxxxxx` everywhere (#124).
+- Wrapped preview rows keep their indent and step guide; long titles are shortened
+  so the confirmation question always stays on screen (#125).
+
+### Fixed
+
+- Installations marks a tracked App whose recipe changed as needing approval and
+  Enter opens the recipe review; an invalid recipe shows its reason (#127).
+- A Source cache lock left by a process that died is recovered safely, and a busy
+  lock names its holder (#120, #122).
+- Escapes typed in text can no longer be cut so they look like real ones, uppercase
+  `\X`/`\U` are handled, and quoted paths mark invisible characters (#128).
+- State files are flushed to disk before and after replacing them, so a power cut
+  does not leave them empty (#129).
+
+### Changed (development)
+
+- The TUI start refresh is an injected option; confirmation and file-picker tests no
+  longer depend on terminal size, and review coverage gaps are closed (#119, #121, #126).
+
+## [0.6.14] - 2026-11-12
+
+### Added
+
+- The TUI names the item being installed or updated, with its position in the
+  batch (for example `Updating Skill tdd (2/5)…`); the elapsed time keeps running
+  across items and manual App steps (#104).
+- The Sources view marks each Source as not refreshed, refreshing, refreshed or
+  failed. On start the TUI refreshes registered Git Sources in the background
+  (no prompts, 60 s limit), and previews reuse a successful refresh from the last
+  hour; `r` always refreshes again (#105).
+- Exporting a Profile to an existing file offers to overwrite it after an explicit
+  confirmation; the CLI needs `profile export --out <file> --overwrite` (#107).
+
+### Changed
+
+- Every TUI confirmation uses a shared footer that shows reading progress and what
+  `y` will do; `y` is ignored until the preview has been read to the end
+  (#106, #111, #112, #113, #114).
+- The update batch preview starts with a summary and the collected warnings, then
+  groups Skills, Apps and Packages with version arrows and `$ command` lines (#108).
+- App recipe reviews and App confirmations show a header and one block per step
+  (#109, #110).
+
+### Security
+
+- A `y` that arrives together with other keys (pasted text, held arrows or Page
+  Down) never confirms; it must be pressed on its own (#115).
+- The TUI escapes control and format characters from recipes, Sources, Packages and
+  Host output in every view, so a remote `SKILL.md` or recipe can no longer send
+  terminal escape sequences or disguise a command (#116, #117).
+
 ## [0.6.13] - 2026-11-11
 
 ### Fixed

package/README.md

@@ -971,7 +971,9 @@ independently. Unknown selections and combining a block's inclusion filter with
 `--no-*` flag are errors.
 
 Stdout contains JSON only; stderr shows the preview and exclusion reasons.
-`--out` requires a new file (existing files and symlinks are not replaced).
+`--out` requires a new file unless `--overwrite` is given, which atomically replaces an
+existing regular file; directories and symlinks are never replaced. Overwriting creates a
+new file, so it does not keep the original's permissions, owner or hard links.
 Profiles contain canonical Git URLs with discovery inclusion, individual Skill
 selections with recorded version policies, Hosts and user methods, complete App
 recipes (including recipes for other platforms), and Package selections as

package/dist/src/app-flow.js

@@ -156,7 +156,14 @@ export function createAppOperations(environment = {}) {
         if (!entry.applicable)
             return { status: "not applicable here" };
         if (cached?.installedVersion) {
-            return { status: "installed", installedVersion: cached.installedVersion, evidence: "recorded" };
+            const approval = await approvalStatus(entry);
+            if (approval.status === "invalid") {
+                return { status: "invalid", installedVersion: cached.installedVersion, evidence: "recorded", reason: approval.reason };
+            }
+            return {
+                status: "installed", installedVersion: cached.installedVersion, evidence: "recorded",
+                ...(approval.status === "needs approval" ? { needsApproval: true } : {}),
+            };
         }
         const approval = await approvalProblem(entry);
         if (approval)

package/dist/src/atomic-file.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
-import { rename, unlink, writeFile } from "node:fs/promises";
+import { open, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 export const WINDOWS_RENAME_ATTEMPTS = 20;
 const WINDOWS_RENAME_RETRY_MS = 5;
@@ -23,11 +24,35 @@ export async function renameWithWindowsRetry(from, to, deps = { rename, platform
         }
     }
 }
-/** Write a unique temporary sibling, then publish it with rename. */
+/** Persist a directory entry change; Windows cannot open a directory for fsync. */
+async function syncDirectory(directory) {
+    if (process.platform === "win32")
+        return;
+    const handle = await open(directory, "r");
+    try {
+        await handle.sync();
+    }
+    catch (error) {
+        // Some filesystems do not implement fsync on directories.
+        if (!["EINVAL", "ENOTSUP"].includes(error.code ?? ""))
+            throw error;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Write a unique temporary sibling, fsync it, publish it with rename, then fsync the directory. */
 export async function writeFileAtomically(file, contents, options = {}) {
     const temporaryPath = `${file}.${process.pid}.${randomUUID()}.tmp`;
     try {
-        await writeFile(temporaryPath, contents, { encoding: "utf8", flag: "wx", mode: options.mode });
+        const handle = await open(temporaryPath, "wx", options.mode);
+        try {
+            await handle.writeFile(contents, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
         try {
             await renameWithWindowsRetry(temporaryPath, file);
         }
@@ -39,6 +64,7 @@ export async function writeFileAtomically(file, contents, options = {}) {
             // Source state holds its read-modify-write lock while using this Windows fallback.
             await writeFile(file, contents, "utf8");
         }
+        await syncDirectory(path.dirname(file));
     }
     finally {
         await unlink(temporaryPath).catch((error) => {

package/dist/src/cli.js

@@ -155,6 +155,8 @@ const COMMANDS = new Map([
             // Loaded lazily so non-interactive commands never import Ink/React.
             const renderTui = dependencies.renderTui ?? (await import("./tui/render.js")).renderTui;
             await renderTui(operations, {
+                // The one place the opt-out is read: E2E tests start the real binary and cannot inject options.
+                refreshOnStart: process.env.AGENT_DEPOT_NO_BACKGROUND_REFRESH !== "1",
                 homeDirectory: dependencies.homeDirectory,
                 projectRoot,
                 sourceAccess: dependencies.sourceAccess,

package/dist/src/flow-progress.js

@@ -0,0 +1,9 @@
+const KIND_LABEL = { skill: "Skill", app: "App", package: "Package" };
+/** `Removing demo (2/5)…`: the shared busy label of a batch; a batch of one has no position, and the `…` marks work in progress. */
+export function formatStepLabel(text, position, total) {
+    return `${text}${total > 1 ? ` (${position}/${total})` : ""}…`;
+}
+/** `Updating Skill tdd (2/5)…`. */
+export function formatProgressLabel(event) {
+    return formatStepLabel(`${event.verb} ${KIND_LABEL[event.kind]} ${event.name}`, event.position, event.total);
+}

package/dist/src/git-source.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
-import { lstat, mkdir, rename, rm, rmdir } from "node:fs/promises";
-import { homedir } from "node:os";
+import { link, lstat, mkdir, readFile, rename, rm, rmdir, unlink, writeFile } from "node:fs/promises";
+import { homedir, hostname } from "node:os";
 import path from "node:path";
 import { isLockContention } from "./atomic-file.js";
 import { assertNoSymlinkPath } from "./path-safety.js";
@@ -50,7 +50,14 @@ function gitFailureDetail(result) {
 }
 class NodeGitCommandRunner {
     async run(command, args, options = {}) {
-        const result = await runProcess(command, args, options.cwd === undefined ? {} : { cwd: options.cwd });
+        const result = await runProcess(command, args, {
+            ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            ...(options.env === undefined ? {} : { env: options.env }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        });
+        if (result.timedOut) {
+            throw new Error(`git command timed out after ${Math.round((options.timeoutMs ?? 0) / 1000)} s`);
+        }
         if (result.code !== 0) {
             throw new Error(`git command failed: ${gitFailureDetail(result)}`);
         }
@@ -78,7 +85,21 @@ class NodeGitSnapshotCommandRunner {
     }
 }
 const SOURCE_LOCK_TIMEOUT_MS = 30_000;
+/** D2 (I0031): nobody is watching a background refresh, so it must neither prompt nor hang. */
+const BACKGROUND_REFRESH_OPTIONS = Object.freeze({
+    env: Object.freeze({ GIT_TERMINAL_PROMPT: "0" }),
+    timeoutMs: 60_000,
+});
 const SOURCE_LOCK_RETRY_MS = 10;
+const SOURCE_LOCK_OWNER_FILE = "owner.json";
+const SOURCE_LOCK_OWNER_MAX_BYTES = 4096;
+const SOURCE_RECOVERY_MUTEX_ID_FILE = "id";
+const LOCK_REMOVAL_ATTEMPTS = 5;
+const LOCK_REMOVAL_RETRY_MS = 50;
+/** A recovery takes milliseconds, so a mutex this old was left by a process that died mid-recovery. */
+const SOURCE_RECOVERY_MUTEX_MAX_AGE_MS = 60_000;
+/** Covers locks from versions without an owner record and an acquisition interrupted before writing it. */
+const SOURCE_LOCK_OWNERLESS_MAX_AGE_MS = 10 * 60_000;
 /**
  * Clones each Source into a local mirror and refreshes it from the registered
  * URL. Mirrors are intentionally not checked out: discovery owns later reads.
@@ -86,11 +107,13 @@ const SOURCE_LOCK_RETRY_MS = 10;
 export class GitSourceAccessAdapter {
     cachePath;
     runner;
+    lockHooks;
     constructor(options = {}) {
+        this.lockHooks = options.lockHooks ?? {};
         this.cachePath = options.cachePath ?? defaultGitSourceCachePath();
         this.runner = options.runner ?? new NodeGitCommandRunner();
     }
-    async refresh(source) {
+    async refresh(source, options = {}) {
         const expectedId = sourceIdForUrl(source.url);
         if (source.kind !== "git" || source.id !== expectedId) {
             throw new GitSourceAccessError(source, "the Source identity does not match its registered URL");
@@ -100,12 +123,14 @@ export class GitSourceAccessAdapter {
             await assertNoSymlinkPath(this.cachePath, "cache path");
             await mkdir(this.cachePath, { recursive: true });
             await assertNoSymlinkPath(this.cachePath, "cache path");
-            const release = await acquireSourceLock(`${destination}.lock`);
+            const lock = await acquireSourceLock(`${destination}.lock`, this.lockHooks);
             try {
-                await this.refreshLocked(source, destination);
+                await this.lockHooks.afterLockAcquired?.();
+                await lock.assertHeld();
+                await this.refreshLocked(source, destination, options.background ? BACKGROUND_REFRESH_OPTIONS : undefined);
             }
             finally {
-                await release();
+                await lock.release();
             }
         }
         catch (error) {
@@ -116,7 +141,7 @@ export class GitSourceAccessAdapter {
             throw new GitSourceAccessError(source, reason);
         }
     }
-    async refreshLocked(source, destination) {
+    async refreshLocked(source, destination, runOptions) {
         const existing = await pathType(destination);
         if (existing === "symlink") {
             throw new Error("the Source cache path is a symbolic link");
@@ -136,12 +161,12 @@ export class GitSourceAccessAdapter {
                 "--force",
                 gitSourceLocation(source.url).repositoryUrl,
                 "+refs/*:refs/*",
-            ]);
+            ], runOptions);
             return;
         }
         const temporaryDestination = `${destination}.${process.pid}.${randomUUID()}.tmp`;
         try {
-            await this.runner.run("git", ["clone", "--mirror", gitSourceLocation(source.url).repositoryUrl, temporaryDestination]);
+            await this.runner.run("git", ["clone", "--mirror", gitSourceLocation(source.url).repositoryUrl, temporaryDestination], runOptions);
             await assertNoSymlinkPath(temporaryDestination, "cache path");
             if ((await pathType(temporaryDestination)) !== "directory") {
                 throw new Error("Git clone did not create a directory mirror");
@@ -429,14 +454,60 @@ async function pathType(candidate) {
         throw error;
     }
 }
-async function acquireSourceLock(lockPath) {
+const LOCK_TAKEN_OVER_MESSAGE = "the Source cache lock was taken over by another process; this refresh stopped without touching the cache";
+/** Identifies a directory across its lifetime; a recreated path gets a new inode or birth time. */
+async function directoryIdentity(directory) {
+    try {
+        const { dev, ino, birthtimeNs } = await lstat(directory, { bigint: true });
+        return `${dev}:${ino}:${birthtimeNs}`;
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * Removes `directory` if `stillOurs` holds, then retries a failed removal only on that same directory.
+ * `rm` deletes the owner record before the directory, so after a partial failure ownership can no longer
+ * be re-read; identity stands in for it, and a successor's directory recreated at the path never matches.
+ * `rm`'s own retry option would repeat the removal on the path blindly instead. Windows reports EBUSY,
+ * EPERM or ENOTEMPTY while another process still holds a handle on something inside, so only those are retried.
+ * Residual limit: the checks and the removal are separate calls (the filesystem has no atomic conditional
+ * remove), so a successor that takes the path inside that window, microseconds wide, is still removed;
+ * two reclaimers of an aged-out recovery mutex can race the same way.
+ */
+async function removeWhileOurs(directory, stillOurs, hooks) {
+    if (!(await stillOurs())) {
+        return;
+    }
+    const identity = await directoryIdentity(directory);
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            // rm unlinks links instead of following them, so nothing outside the directory is touched.
+            await (hooks.removeDirectory ?? ((target) => rm(target, { recursive: true, force: true })))(directory);
+            return;
+        }
+        catch (error) {
+            const transient = ["EBUSY", "EPERM", "ENOTEMPTY"].includes(error.code ?? "");
+            if (!transient || attempt >= LOCK_REMOVAL_ATTEMPTS) {
+                throw error;
+            }
+            await new Promise((resolve) => setTimeout(resolve, LOCK_REMOVAL_RETRY_MS));
+            if (identity === undefined || (await directoryIdentity(directory)) !== identity) {
+                return;
+            }
+        }
+    }
+}
+async function acquireSourceLock(lockPath, hooks) {
     const deadline = Date.now() + SOURCE_LOCK_TIMEOUT_MS;
     while (true) {
         try {
             await mkdir(lockPath);
-            return async () => {
-                await rmdir(lockPath);
-            };
+            await hooks.afterLockCreated?.();
+            return await publishLockOwner(lockPath, hooks);
         }
         catch (error) {
             if (!isLockContention(error)) {
@@ -445,13 +516,184 @@ async function acquireSourceLock(lockPath) {
             if ((await pathType(lockPath)) === "symlink") {
                 throw new Error("the Source cache lock is a symbolic link");
             }
+            if (await recoverOrphanedLock(lockPath, hooks)) {
+                continue;
+            }
             if (Date.now() >= deadline) {
-                throw new Error(`the Source cache lock directory is busy: ${lockPath}; another refresh might be active. Wait for it to finish before retrying`);
+                const record = await readLockOwner(lockPath);
+                const holder = record.kind === "owner"
+                    ? ` (held by process ${record.owner.pid} on host ${record.owner.hostname})`
+                    : record.kind === "none"
+                        ? ` (held by an unknown process: it has no owner record and will be recovered once it is ${SOURCE_LOCK_OWNERLESS_MAX_AGE_MS / 60_000} minutes old)`
+                        : "";
+                throw new Error(`the Source cache lock directory is busy: ${lockPath}${holder}; another refresh might be active. Wait for it to finish before retrying`);
             }
             await new Promise((resolve) => setTimeout(resolve, SOURCE_LOCK_RETRY_MS));
         }
     }
 }
+/**
+ * Publishes the owner record without ever replacing one: a holder that stalled and lost its lock
+ * would otherwise overwrite its successor's record and let both believe they hold it.
+ * A hard link fails with EEXIST when the record exists. Where links are unsupported, an exclusive
+ * create gives the same no-overwrite guarantee, but a reader can briefly see a partial record,
+ * which it treats as unreadable and so never as a reason to remove the lock.
+ */
+async function publishLockOwner(lockPath, hooks) {
+    const owner = { pid: process.pid, hostname: hostname(), startedAt: new Date().toISOString(), id: randomUUID() };
+    const ownerPath = path.join(lockPath, SOURCE_LOCK_OWNER_FILE);
+    const temporaryPath = `${ownerPath}.${owner.id}.tmp`;
+    const contents = JSON.stringify(owner);
+    try {
+        await writeFile(temporaryPath, contents, { encoding: "utf8", flag: "wx" });
+        try {
+            await link(temporaryPath, ownerPath);
+        }
+        catch (error) {
+            if (!["ENOSYS", "ENOTSUP", "EOPNOTSUPP", "EPERM"].includes(error.code ?? "")) {
+                throw error;
+            }
+            await writeFile(ownerPath, contents, { encoding: "utf8", flag: "wx" });
+        }
+    }
+    catch (error) {
+        await unlink(temporaryPath).catch(() => undefined);
+        if (error.code === "EEXIST") {
+            throw new Error(LOCK_TAKEN_OVER_MESSAGE);
+        }
+        if (error.code === "ENOENT") {
+            // The directory this call created is gone: the lock was recovered, and a successor may already hold a new one.
+            throw new Error(LOCK_TAKEN_OVER_MESSAGE);
+        }
+        // rmdir only removes an empty directory: ours, or a successor's before it published, whose own write then
+        // reports the takeover. A successor with an owner record is never empty.
+        await rmdir(lockPath).catch(() => undefined);
+        throw new Error(`could not record the Source cache lock owner: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    await unlink(temporaryPath).catch(() => undefined);
+    return {
+        async assertHeld() {
+            const record = await readLockOwner(lockPath);
+            if (record.kind !== "owner" || record.owner.id !== owner.id) {
+                throw new Error(LOCK_TAKEN_OVER_MESSAGE);
+            }
+        },
+        async release() {
+            await removeWhileOurs(lockPath, async () => {
+                const record = await readLockOwner(lockPath);
+                return record.kind === "owner" && record.owner.id === owner.id;
+            }, hooks);
+        },
+    };
+}
+/** Reads the owner record without following links. */
+async function readLockOwner(lockPath) {
+    const ownerPath = path.join(lockPath, SOURCE_LOCK_OWNER_FILE);
+    try {
+        const information = await lstat(ownerPath);
+        if (!information.isFile() || information.size > SOURCE_LOCK_OWNER_MAX_BYTES) {
+            return { kind: "unreadable" };
+        }
+        const parsed = JSON.parse(await readFile(ownerPath, "utf8"));
+        if (typeof parsed !== "object" || parsed === null) {
+            return { kind: "unreadable" };
+        }
+        const { pid, hostname: host, startedAt, id } = parsed;
+        return Number.isInteger(pid) && pid > 0 && typeof host === "string" && typeof startedAt === "string" && typeof id === "string"
+            ? { kind: "owner", owner: { pid: pid, hostname: host, startedAt, id } }
+            : { kind: "unreadable" };
+    }
+    catch (error) {
+        return isMissing(error) ? { kind: "none" } : { kind: "unreadable" };
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but belongs to someone else.
+        return error.code !== "ESRCH";
+    }
+}
+async function isOldLock(lockPath, maxAgeMs) {
+    try {
+        return Date.now() - (await lstat(lockPath)).mtimeMs > maxAgeMs;
+    }
+    catch {
+        return false;
+    }
+}
+/** The orphan a recoverer judged: a dead owner on this host (by id) or an old lock with no owner record. */
+async function judgeOrphan(lockPath) {
+    const record = await readLockOwner(lockPath);
+    if (record.kind === "owner") {
+        return record.owner.hostname === hostname() && !isProcessAlive(record.owner.pid) ? record : undefined;
+    }
+    return record.kind === "none" && await isOldLock(lockPath, SOURCE_LOCK_OWNERLESS_MAX_AGE_MS) ? record : undefined;
+}
+/**
+ * Removes a lock whose holder is provably gone. Recoverers serialize on a short-lived `.recovering`
+ * mutex and re-judge the lock in place while holding it, so a judgment made before another process
+ * recovered and re-took the lock can never remove (or move) that live lock: nothing but a recoverer
+ * removes a lock whose owner is dead, and acquirers cannot replace a lock that still exists.
+ * Returns true when the caller should retry the acquisition at once.
+ */
+async function recoverOrphanedLock(lockPath, hooks) {
+    const judged = await judgeOrphan(lockPath);
+    if (judged === undefined) {
+        return false;
+    }
+    await hooks.afterJudging?.();
+    const mutexPath = `${lockPath}.recovering`;
+    try {
+        await mkdir(mutexPath);
+    }
+    catch (error) {
+        if (!isLockContention(error)) {
+            throw error;
+        }
+        // A recoverer that died holding the mutex would otherwise block recovery for good.
+        if (await isOldLock(mutexPath, SOURCE_RECOVERY_MUTEX_MAX_AGE_MS)) {
+            await removeWhileOurs(mutexPath, () => isOldLock(mutexPath, SOURCE_RECOVERY_MUTEX_MAX_AGE_MS), hooks);
+            return true;
+        }
+        return false;
+    }
+    const mutexId = randomUUID();
+    const mutexIdPath = path.join(mutexPath, SOURCE_RECOVERY_MUTEX_ID_FILE);
+    const ownsMutex = async () => (await readFile(mutexIdPath, "utf8").catch(() => undefined)) === mutexId;
+    try {
+        await writeFile(mutexIdPath, mutexId, { encoding: "utf8", flag: "wx" });
+    }
+    catch (error) {
+        // The mutex was reclaimed before it was identified; give up this recovery attempt.
+        if (!["EEXIST", "ENOENT"].includes(error.code ?? "")) {
+            await rmdir(mutexPath).catch(() => undefined);
+            throw error;
+        }
+        return false;
+    }
+    try {
+        const isJudgedOrphan = async () => {
+            const current = await judgeOrphan(lockPath);
+            return current !== undefined && (current.kind === "owner"
+                ? judged.kind === "owner" && judged.owner.id === current.owner.id
+                : judged.kind === "none");
+        };
+        if (await isJudgedOrphan()) {
+            await hooks.beforeOrphanRemoval?.();
+            // A recoverer paused past the mutex's age limit may have had the mutex reclaimed and the lock re-taken,
+            // so the mutex and the orphan are re-checked before every removal attempt.
+            await removeWhileOurs(lockPath, async () => await ownsMutex() && await isJudgedOrphan(), hooks);
+        }
+        return true;
+    }
+    finally {
+        await removeWhileOurs(mutexPath, ownsMutex, hooks);
+    }
+}
 export function validateGitRef(candidate) {
     if (typeof candidate !== "string" || candidate.length === 0 || candidate.trim() !== candidate ||
         Array.from(candidate).some((character) => (character.codePointAt(0) ?? 0) <= 0x20) ||

package/dist/src/preview-model.js

@@ -0,0 +1,37 @@
+// Anything outside this set could be read differently by a shell, so the argument is shown quoted.
+const PLAIN_ARGUMENT = /^[\w@%+=:,./-]+$/u;
+// What the TUI does not escape itself: spaces other than U+0020, default-ignorable code points that are not control or format, and
+// the zero-width joiner (kept in ordinary text for emoji).
+const NOT_ESCAPED_BY_TUI = /(?! )(?![\p{Cc}\p{Cf}])[\p{Zs}\p{Default_Ignorable_Code_Point}]|\u200D/gu;
+// JSON.stringify leaves these raw; shown as is, a right-to-left override, zero-width space or no-break space can make one argument
+// look like another. A plain space stays: inside the quotes it is what it looks like.
+const INVISIBLE = /(?! )[\p{Cc}\p{Cf}\p{Zs}\p{Default_Ignorable_Code_Point}\u2028\u2029]/gu;
+function quoted(argument, terminal) {
+    // The TUI escapes control and format characters once, when it draws; escaping them here too would show a real RLO as typed text.
+    if (terminal)
+        return quoteText(argument);
+    return JSON.stringify(argument).replace(INVISIBLE, escapeCharacter);
+}
+function escapeCharacter(character) {
+    const code = character.codePointAt(0).toString(16);
+    return code.length > 4 ? `\\u{${code}}` : `\\u${code.padStart(4, "0")}`;
+}
+/**
+ * `text` in double quotes with quotes and backslashes escaped. Control and format characters stay as they are for the TUI to escape;
+ * spaces other than U+0020 and ignorable characters are written out, as in `commandLine`.
+ */
+export function quoteText(text) {
+    return `"${text.replace(/[\\"]/gu, "\\$&").replace(NOT_ESCAPED_BY_TUI, escapeCharacter)}"`;
+}
+/**
+ * The argv as one shell-like line: arguments with spaces, quotes, shell metacharacters or invisible characters are JSON-quoted.
+ * With `terminal`, control and format characters are left for the TUI's own escaping.
+ */
+export function commandLine(argv, options = {}) {
+    const terminal = options.terminal === true;
+    return argv.map((argument) => PLAIN_ARGUMENT.test(argument) ? argument : quoted(argument, terminal)).join(" ");
+}
+/** Every warning row of the item, in order. */
+export function itemWarnings(item) {
+    return item.rows.flatMap((row) => row.kind === "warning" ? [row.text] : []);
+}

package/dist/src/process-runner.js

@@ -159,6 +159,7 @@ export function runProcess(command, args, options = {}) {
         const sink = childOutputSinks.getStore();
         const child = spawn(invocation.command, [...invocation.args], {
             ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            ...(options.env === undefined ? {} : { env: { ...process.env, ...options.env } }),
             shell: false,
             windowsVerbatimArguments: invocation.windowsVerbatimArguments,
             // Without a capture, stdout is piped only for a sink, and then discarded after it is shown.

package/dist/src/profile-cli.js

@@ -4,10 +4,10 @@ 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 EXPORT_USAGE = "agent-depot export [--out <file> [--overwrite]] [--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, progress = NO_PROGRESS) {
-    const { filters, out } = parseProfileOptions(values, false);
+    const { filters, out, overwrite } = parseProfileOptions(values, false);
     const plan = await progress.run("Building Profile export", () => buildProfileExport(operations, apps, {
         ...filters,
         homeDirectory,
@@ -20,7 +20,7 @@ export async function runProfileExport(values, operations, apps, output, diagnos
     if (out === undefined)
         output(content.trimEnd());
     else {
-        await writeProfileExport(out, plan.profile);
+        await writeProfileExport(out, plan.profile, { overwrite });
         diagnostic(`Exported profile to ${out}`);
     }
     return 0;
@@ -30,6 +30,7 @@ function parseProfileOptions(values, importing) {
     const filters = { sources, skills, apps: appNames, packages: packageNames };
     let out;
     let confirmed = false;
+    let overwrite = false;
     for (let index = 0; index < values.length; index++) {
         const option = values[index];
         if (option === "--yes" && importing) {
@@ -37,6 +38,11 @@ function parseProfileOptions(values, importing) {
                 throw new CliUsageError("Duplicate --yes");
             confirmed = true;
         }
+        else if (option === "--overwrite" && !importing) {
+            if (overwrite)
+                throw new CliUsageError("Duplicate --overwrite");
+            overwrite = true;
+        }
         else if (option === "--no-sources")
             filters.noSources = true;
         else if (option === "--no-skills")
@@ -66,7 +72,9 @@ function parseProfileOptions(values, importing) {
         else
             throw new CliUsageError(`Usage: ${importing ? IMPORT_USAGE : EXPORT_USAGE}`);
     }
-    return { filters, out, confirmed };
+    if (overwrite && out === undefined)
+        throw new CliUsageError("--overwrite requires --out");
+    return { filters, out, confirmed, overwrite };
 }
 export async function runProfileImport(values, operations, apps, output, environment = {}, progress = NO_PROGRESS) {
     const file = values[0];

package/dist/src/profile-export.js

@@ -1,8 +1,9 @@
-import { writeFile } from "node:fs/promises";
+import { lstat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { loadAppOwnedSkillFilter } from "./app-owned-skills.js";
 import { sourceIdForUrl } from "./git-source.js";
 import { bundleRoot, describeBundleInSource, describeCoordinates } from "./package-model.js";
+import { writeFileAtomically } from "./atomic-file.js";
 import { AGENT_DEPOT_PACKAGE_VERSION } from "./project-manifest.js";
 import { parseProfile, PROFILE_FORMAT, PROFILE_FORMAT_V2, serializeProfile } from "./profile.js";
 import { formatVersionPolicy } from "./skill-install.js";
@@ -219,9 +220,28 @@ export function requireProfileExportSelection(profile) {
         throw new Error("Nothing selected; nothing written.");
     }
 }
-/** Exclusively create an export artifact; never replace a file or follow a symlink. */
-export async function writeProfileExport(file, profile) {
+/** Rejects an existing destination that is not a regular file, such as a directory or symlink. */
+export async function requireOverwritableProfileExport(file) {
+    try {
+        if (!(await lstat(file)).isFile())
+            throw new Error(`${file} is not a regular file; choose another path`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+/**
+ * Exclusively create an export artifact unless `overwrite` explicitly allows atomically replacing a
+ * regular file. Neither path follows a symlink: `wx` refuses it and the atomic rename replaces the entry.
+ */
+export async function writeProfileExport(file, profile, options = {}) {
     requireProfileExportSelection(profile);
+    if (options.overwrite) {
+        await requireOverwritableProfileExport(file);
+        await writeFileAtomically(file, serializeProfile(profile));
+        return;
+    }
     try {
         await writeFile(file, serializeProfile(profile), { encoding: "utf8", flag: "wx" });
     }