@iseoane/agent-depot 0.6.14 → 0.6.16

package/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.16] - 2026-11-13
+
+### Changed
+
+- `app install` names the Hosts whose setup the recipe declares and the `app setup` command to run, since install never runs Host setup and wiring is not tracked (#131).
+- The built-in `agent-depot-apprecipe` Skill (1.3) checks Host wiring in its preflight (unattended setup per Host, conflicting MCP entries, plugins and packages), prefers `argv` setup when possible, rechecks manual setup on repair and hands off the pending `app setup` command per Host (#131).
+
+## [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

package/README.md

@@ -972,7 +972,8 @@ independently. Unknown selections and combining a block's inclusion filter with
 
 Stdout contains JSON only; stderr shows the preview and exclusion reasons.
 `--out` requires a new file unless `--overwrite` is given, which atomically replaces an
-existing regular file; directories and symlinks are never replaced.
+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-cli.js

@@ -1,6 +1,6 @@
 import { PROJECT_HOSTS } from "./project-manifest.js";
 import { APP_RECIPE_SCHEMA } from "./app-schema.js";
-import { checkAppUpdates } from "./app-flow.js";
+import { checkAppUpdates, declaredSetupHosts } from "./app-flow.js";
 import { NO_PROGRESS } from "./progress.js";
 import { CliUsageError } from "./usage-error.js";
 const ACTION_PROGRESS = {
@@ -158,15 +158,27 @@ async function runLifecycle(action, args, apps, output, usage, progress) {
             output(`Manual (never executed): ${result.manual}`);
             output(describeManualCompletion(plan));
         }
+        if (action === "install" && result.status === "installed")
+            showSetupHosts(plan);
         return result.status === "installed" || result.status === "untracked" || result.status === "completed" ? 0 : 1;
     }
+    function showSetupHosts(plan) {
+        const hosts = declaredSetupHosts(plan.entry.recipe);
+        if (!hosts.length)
+            return;
+        output(`Host setup is separate and not tracked; this recipe declares it for: ${hosts.join(", ")}.`);
+        output(`Run app setup ${quoteAppName(name)} --host <host> --yes for each Host you use.`);
+    }
+}
+function quoteAppName(name) {
+    return process.platform === "win32"
+        ? "'" + name.replaceAll("'", "''") + "'"
+        : "'" + name.replaceAll("'", "'\\''") + "'";
 }
 /** Copyable completion command for the platform's documented shell. */
 export function describeManualCompletion(plan) {
     const name = plan.entry.recipe.name;
-    const quotedName = process.platform === "win32"
-        ? "'" + name.replaceAll("'", "''") + "'"
-        : "'" + name.replaceAll("'", "'\\''") + "'";
+    const quotedName = quoteAppName(name);
     const shell = process.platform === "win32" ? "PowerShell" : "POSIX shell";
     return `After completing it, run app ${plan.action} ${quotedName}${plan.host ? ` --host ${plan.host}` : ""} --manual-done --yes to check version (${shell}).`;
 }

package/dist/src/app-flow.js

@@ -7,6 +7,7 @@ import { fetchAppLatest } from "./app-latest.js";
 import { writeFileAtomically } from "./atomic-file.js";
 import { parseAppRecipe } from "./app-recipes.js";
 import { createPortableExecutableResolver } from "./executable-resolution.js";
+import { PROJECT_HOSTS } from "./project-manifest.js";
 import { runProcess } from "./process-runner.js";
 import { defaultSourceStatePath } from "./source-state.js";
 const APP_OUTPUT_LIMIT = 1024 * 1024;
@@ -156,7 +157,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)
@@ -482,6 +490,10 @@ export function createAppOperations(environment = {}) {
     }
     return { directory, approvalStatus, checkUpdate, load, preview, approve, inspect, inspectForExport, planLifecycle, executeLifecycle, completeManual, cancelManual, trackedApps, previewForget, forgetApp };
 }
+/** Hosts whose user-global setup the recipe declares; install never runs them and wiring is not tracked. */
+export function declaredSetupHosts(recipe) {
+    return PROJECT_HOSTS.filter(host => recipe.setup?.[host] !== undefined);
+}
 /** Concurrent independent checks; one broken App must not hide the rest of a batch. */
 export async function checkAppUpdates(apps) {
     const entries = (await apps.load()).filter(entry => entry.applicable || entry.error);

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

@@ -1,6 +1,9 @@
 const KIND_LABEL = { skill: "Skill", app: "App", package: "Package" };
-/** `Updating Skill tdd (2/5)…`; a batch of one has no position. */
+/** `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) {
-    const position = event.total > 1 ? ` (${event.position}/${event.total})` : "";
-    return `${event.verb} ${KIND_LABEL[event.kind]} ${event.name}${position}…`;
+    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";
@@ -91,6 +91,15 @@ const BACKGROUND_REFRESH_OPTIONS = Object.freeze({
     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.
@@ -98,7 +107,9 @@ 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();
     }
@@ -112,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.lockHooks.afterLockAcquired?.();
+                await lock.assertHeld();
                 await this.refreshLocked(source, destination, options.background ? BACKGROUND_REFRESH_OPTIONS : undefined);
             }
             finally {
-                await release();
+                await lock.release();
             }
         }
         catch (error) {
@@ -441,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)) {
@@ -457,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

@@ -9,16 +9,19 @@ const INVISIBLE = /(?! )[\p{Cc}\p{Cf}\p{Zs}\p{Default_Ignorable_Code_Point}\u202
 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).replace(NOT_ESCAPED_BY_TUI, escapeCharacter);
+        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 characters stay as they are for the TUI to escape. */
+/**
+ * `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, "\\$&")}"`;
+    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.

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

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text } from "./safe-text.js";
+import { formatStepLabel } from "../flow-progress.js";
 import { commandLine } from "../preview-model.js";
 import { PROJECT_HOSTS } from "../project-manifest.js";
 import { errorText, runBatch } from "./batch.js";
@@ -76,9 +77,9 @@ function appPreviewLines(mode) {
 function appBusy(label, previous, done) {
     return { kind: "app-busy", label, startedAt: operationStart(previous), ...(done?.length ? { done } : {}) };
 }
-/** `Running App step: name (2/5)…`; the position is left out for a batch of one. */
+/** `Running App step: name (2/5)…`; `finished` counts the steps already done. */
 function stepLabel(verb, entry, finished, total) {
-    return `${verb} App step: ${appName(entry)}${total > 1 ? ` (${finished + 1}/${total})` : ""}…`;
+    return formatStepLabel(`${verb} App step: ${appName(entry)}`, finished + 1, total);
 }
 async function prepareNext(context, requests, results = [], failures = 0, previous) {
     const { manage, apps } = context;
@@ -229,5 +230,5 @@ export function AppPanel({ mode }) {
     const styled = appPreviewLines(mode);
     const lines = styled.map(lineText);
     const chrome = appPreviewChrome(mode);
-    return _jsx(PagedPreview, { chrome: chrome, lines: lines, styled: styled, viewport: geometry(lines, mode.cursor, chrome) });
+    return _jsx(PagedPreview, { lines: lines, styled: styled, viewport: geometry(lines, mode.cursor, chrome) });
 }

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

@@ -1,5 +1,6 @@
 import { PROJECT_HOSTS } from "../project-manifest.js";
 import { assertManagedInstallationRecordsUnchanged } from "../skill-removal.js";
+import { formatStepLabel } from "../flow-progress.js";
 import { errorText, runBatch } from "./batch.js";
 import { missingHosts, prepareHostAddition, prepareUninstall, runHostAddition, runUninstall, UNINSTALL_REFUSALS, } from "./catalog-installs.js";
 import { answerPaged, answerYesNo, applyChecklistOutcome, hostChecklistKey } from "./mode-keys.js";
@@ -80,12 +81,12 @@ function resultOf(outcomes, skipped) {
         applied: outcomes.filter((outcome) => outcome.ok).map((outcome) => outcome.item.id),
     };
 }
-/** `Removing name (2/5)…` for each item as it starts. */
+/** `Removing name (2/5)…` (no position for one item) for each item as it starts. */
 function startOf(verb, progress) {
     if (!progress)
         return undefined;
     return (item, position, total, finished) => {
-        progress(`${verb} ${item.label} (${position}/${total})…`, finished.map(outcome => outcome.line));
+        progress(formatStepLabel(`${verb} ${item.label}`, position, total), finished.map(outcome => outcome.line));
     };
 }
 /** Execute step: each item is rechecked and applied on its own against the records the previous items were expected to leave. */

package/dist/src/tui/catalog-panel.js

@@ -33,7 +33,7 @@ export function CatalogSelectionHelp({ row, height }) {
 /** The install confirmation with the shared footer; the view shows it alone so no tree rows count against its height. */
 export function InstallConfirmPanel({ mode }) {
     const { lines, chrome } = installPreview(mode.items);
-    return _jsx(PagedPreview, { chrome: chrome, lines: lines, viewport: usePreviewGeometry()(lines, mode.cursor, chrome) });
+    return _jsx(PagedPreview, { lines: lines, viewport: usePreviewGeometry()(lines, mode.cursor, chrome) });
 }
 /** The prompt of the install flow; browsing shows nothing. */
 export function ActionPanel({ mode }) {

package/dist/src/tui/installations-browse.js

@@ -107,7 +107,7 @@ function actOnRow(context, snapshot, row, input, key) {
     else if (item.kind === "app") {
         if (input === "A")
             context.setMessage({ kind: "error", text: "Adoption applies to unmanaged Skills, not Apps" });
-        else if (key.return && item.row.inspection.status !== "needs approval") {
+        else if (key.return && item.row.inspection.status !== "needs approval" && !item.row.inspection.needsApproval) {
             const { entry, inspection } = item.row;
             const approved = inspection.status === "installed" || inspection.status === "not installed";
             context.setMessage({

package/dist/src/tui/installations-panel.js

@@ -10,7 +10,7 @@ import { theme } from "./theme.js";
 /** An adoptable preview with the shared footer; the view shows it alone so no tree rows count against its height. */
 export function AdoptionConfirmPanel({ mode }) {
     const { lines, chrome } = adoptionPreview(mode);
-    return _jsx(PagedPreview, { chrome: chrome, lines: lines, viewport: usePreviewGeometry()(lines, mode.cursor, chrome) });
+    return _jsx(PagedPreview, { lines: lines, viewport: usePreviewGeometry()(lines, mode.cursor, chrome) });
 }
 /** The prompt of the adoption and manage modes; browsing shows nothing. */
 export function ModePanel({ mode }) {

package/dist/src/tui/installations-rows.js

@@ -6,7 +6,7 @@ function AppDetails({ row }) {
     const version = row.inspection.installedVersion;
     const statusColor = row.inspection.status === "invalid" ? theme.error : theme.warning;
     const invalid = row.inspection.status === "invalid" ? ` · invalid recipe: ${row.inspection.reason ?? "unknown error"}` : "";
-    return (_jsxs(Text, { children: [_jsx(Text, { color: theme.legend, children: "  " }), _jsx(Text, { color: version === undefined ? statusColor : theme.version, children: version ?? row.inspection.status }), row.inspection.evidence === "recorded" ? _jsx(Text, { color: theme.value, children: " (recorded)" }) : null, invalid === "" ? null : _jsx(Text, { color: theme.error, children: invalid })] }));
+    return (_jsxs(Text, { children: [_jsx(Text, { color: theme.legend, children: "  " }), _jsx(Text, { color: version === undefined ? statusColor : theme.version, children: version ?? row.inspection.status }), row.inspection.evidence === "recorded" ? _jsx(Text, { color: theme.value, children: " (recorded)" }) : null, row.inspection.needsApproval ? _jsx(Text, { color: theme.warning, children: " \u00B7 needs approval" }) : null, invalid === "" ? null : _jsx(Text, { color: theme.error, children: invalid })] }));
 }
 function PackageDetails({ row }) {
     const version = row.installedVersion;

package/dist/src/tui/installations-tree.js

@@ -79,7 +79,7 @@ export function describeNode(row) {
             return `${name}  invalid recipe: ${inspection.reason}`;
         const version = inspection.installedVersion ?? inspection.status;
         const invalid = inspection.status === "invalid" ? ` · invalid recipe: ${inspection.reason}` : "";
-        return `${name}  ${version}${inspection.evidence === "recorded" ? " (recorded)" : ""}${invalid}`;
+        return `${name}  ${version}${inspection.evidence === "recorded" ? " (recorded)" : ""}${inspection.needsApproval ? " · needs approval" : ""}${invalid}`;
     }
     return `${data.group.name} [${data.group.hosts.join(", ")}]`;
 }

package/dist/src/tui/keys.js

@@ -26,18 +26,26 @@ function grouped(key) {
     groupedKeys.add(copy);
     return copy;
 }
+/**
+ * The most events any hook has read this turn. A hook that mounts mid-read starts its own count at 0, but the hooks that were already
+ * listening have counted the keys it missed, so this tells it that it is not at the start of the turn.
+ */
+let eventsInTurn = 0;
 /**
  * `useInput` that treats several plain characters delivered in one write (fast
  * typing, a paste) as the separate key presses they are, in order. Ink also hands
  * the escape sequences of one read over as separate events within one turn; every key
- * after the first of a turn counts as grouped, as do all characters of a split block.
+ * after the first of a turn counts as grouped, in any hook, as do all characters of a split block.
  */
 export function useKeys(handler) {
     const eventsThisTurn = useRef(0);
     useInput((input, key) => {
+        if (eventsInTurn === 0)
+            queueMicrotask(() => { eventsInTurn = 0; });
         if (eventsThisTurn.current++ === 0)
             queueMicrotask(() => { eventsThisTurn.current = 0; });
-        const later = eventsThisTurn.current > 1;
+        eventsInTurn = Math.max(eventsInTurn, eventsThisTurn.current);
+        const later = eventsThisTurn.current > 1 || eventsInTurn > 1;
         if (ESCAPE_REMNANT.test(input)) {
             if (!PASTE_MARKERS.has(input))
                 handler(input, later ? grouped(key) : key);

package/dist/src/tui/manage-panel.js

@@ -14,7 +14,7 @@ function SkippedLines({ skipped }) {
 /** A Skill confirmation with the shared footer; the view shows it alone so no tree rows count against its height. */
 export function PagedConfirmPanel({ mode }) {
     const { lines, styled, chrome } = pagedConfirmPreview(mode);
-    return _jsx(PagedPreview, { chrome: chrome, lines: lines, styled: styled, viewport: usePreviewGeometry()(lines, mode.cursor, chrome) });
+    return _jsx(PagedPreview, { lines: lines, styled: styled, viewport: usePreviewGeometry()(lines, mode.cursor, chrome) });
 }
 /** Renders the prompt of a manage mode: host lists, previews and confirmations. */
 export function ManagePanel({ mode }) {

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

@@ -200,5 +200,5 @@ export function handlePackageKey(context, mode, input, key) {
 export function PackagePanel({ mode }) {
     const { lines, chrome } = packagePreview(mode);
     const viewport = usePreviewGeometry()(lines, mode.cursor, chrome);
-    return _jsx(PagedPreview, { chrome: chrome, lines: lines, viewport: viewport });
+    return _jsx(PagedPreview, { lines: lines, viewport: viewport });
 }

package/dist/src/tui/package-rows.js

@@ -5,7 +5,7 @@ import { displayPackageCoordinates, displayPackageSelection, } from "../package-
 export function packageVersionLabel(evidence, commit) {
     if (evidence === undefined)
         return "unknown";
-    return evidence.kind === "manifest-version" ? versionWithCommit(evidence.version, commit) : evidence.commit.slice(0, 7);
+    return evidence.kind === "manifest-version" ? versionWithCommit(evidence.version, commit) : `commit ${evidence.commit.slice(0, 7)}`;
 }
 function versionWithCommit(version, commit) {
     return `${version}${commit === undefined ? "" : ` (${commit.slice(0, 7)})`}`;
@@ -47,9 +47,13 @@ export function recordedVersionLabel(record) {
     if (record.verified !== undefined)
         return packageVersionLabel(record.verified);
     if (record.lastDelegatedCommit !== undefined)
-        return record.lastDelegatedCommit.slice(0, 7);
+        return `commit ${record.lastDelegatedCommit.slice(0, 7)}`;
     return "unknown";
 }
+/** The version the host reports when it states one, else what the selection record remembers. */
+export function installedVersionLabel({ installed, observed }) {
+    return observed?.kind === "installed" && observed.version !== undefined ? observed.version : recordedVersionLabel(installed);
+}
 export function packageRow(record, inspection) {
     return {
         selection: record.selection,
@@ -58,7 +62,7 @@ export function packageRow(record, inspection) {
         ...(inspection.installed.kind === "installed" && inspection.installed.version !== undefined
             ? { installedVersion: versionWithCommit(inspection.installed.version, inspection.installed.commit) }
             : inspection.installed.kind === "installed" && inspection.installed.commit !== undefined
-                ? { installedVersion: inspection.installed.commit.slice(0, 7) }
+                ? { installedVersion: `commit ${inspection.installed.commit.slice(0, 7)}` }
                 : {}),
         available: packageVersionLabel(inspection.available, inspection.availableCommit),
         status: packageRowStatus(record.selection, inspection),

package/dist/src/tui/panel-parts.js

@@ -7,7 +7,9 @@ import { escapeControlText, sliceSpans } from "./preview-window.js";
 import { animationEnabled, formatElapsed, SPINNER_FRAMES, SPINNER_TICK_MS, STATIC_GLYPH } from "./working-model.js";
 /** A titled, color-independent boundary for a focused interaction or result. */
 export function BorderPanel({ title, children }) {
-    return (_jsxs(Box, { borderStyle: "round", borderColor: theme.border, paddingX: 1, flexDirection: "column", children: [_jsx(Text, { color: theme.title, bold: true, children: title }), children] }));
+    return (_jsxs(Box, { borderStyle: "round", borderColor: theme.border, paddingX: 1, flexDirection: "column", children: [typeof title === "string"
+                ? _jsx(Text, { color: theme.title, bold: true, children: title })
+                : title.map((row, position) => _jsx(PreEscapedText, { color: theme.title, bold: true, wrap: "truncate", children: row }, position)), children] }));
 }
 export function FieldLine({ label, value }) {
     return _jsxs(Text, { children: [_jsx(Text, { color: theme.field, children: label }), _jsxs(Text, { color: theme.value, children: [" ", value] })] });
@@ -113,16 +115,22 @@ function noticeColor(line) {
         return theme.warning;
     return text.startsWith("Cannot install ") ? theme.error : undefined;
 }
-function PreviewLine({ line, position, logicalLine, offset = 0 }) {
+/** The hanging prefix of a continuation row, drawn in the gutter colour, then the part of the line's spans the row shows. */
+function rowSpans(spans, prefix, offset, length) {
+    return [...(prefix === "" ? [] : [previewSpan(prefix, theme.field)]), ...sliceSpans(spans, offset, length)];
+}
+function PreviewLine({ line, position, logicalLine, offset = 0, prefixLength = 0 }) {
+    const prefix = line.slice(0, prefixLength);
+    const textLength = line.length - prefixLength;
     const profileSpans = logicalLine === undefined ? profilePreviewSpans(line) : profilePreviewSpans(logicalLine);
     if (profileSpans) {
-        const spans = logicalLine === undefined ? profileSpans : sliceSpans(profileSpans, offset, line.length);
+        const spans = logicalLine === undefined ? profileSpans : rowSpans(profileSpans, prefix, offset, textLength);
         return _jsx(PreEscapedText, { children: spans.map((span, index) => _jsx(PreEscapedText, { color: span.color, bold: span.bold, children: span.text }, index)) }, position);
     }
     const field = previewField(logicalLine ?? line);
     if (field) {
         const fieldSpans = [previewSpan(field.label, theme.field), previewSpan(field.value, theme.value)];
-        const spans = logicalLine === undefined ? fieldSpans : sliceSpans(fieldSpans, offset, line.length);
+        const spans = logicalLine === undefined ? fieldSpans : rowSpans(fieldSpans, prefix, offset, textLength);
         return _jsx(PreEscapedText, { children: spans.map((span, index) => _jsx(PreEscapedText, { color: span.color, children: span.text }, index)) }, position);
     }
     return _jsx(PreEscapedText, { color: noticeColor(logicalLine ?? line) ?? theme.value, children: line }, position);
@@ -150,16 +158,16 @@ function footerColor(role, reachedEnd) {
  * A paged preview with the shared two-row footer: reading progress, then what `y` does. `[y]` stays
  * dimmed until `viewport` reaches the end; callers ignore `y` until then using the same viewport.
  */
-export function PagedPreview({ chrome, lines: rawLines, styled: rawStyled, viewport }) {
+export function PagedPreview({ lines: rawLines, styled: rawStyled, viewport }) {
     // The same escape `previewViewport` applied, so rows, offsets and spans describe the same text. The rows themselves are already
     // escaped, hence `PreEscapedText`; only the title goes through `BorderPanel`.
     const lines = rawLines.map(escapeControlText);
     const styled = rawStyled?.map((line) => line?.map((span) => ({ ...span, text: escapeControlText(span.text) })));
-    return (_jsxs(BorderPanel, { title: chrome.title, children: [viewport.rows.map((line, position) => {
+    return (_jsxs(BorderPanel, { title: viewport.titleRows, children: [viewport.rows.map((line, position) => {
                 const logical = viewport.sourceLines[position];
                 const custom = styled?.[logical];
                 return custom === undefined
-                    ? _jsx(PreviewLine, { line: line, position: position, logicalLine: lines[logical], offset: viewport.sourceOffsets[position] }, position)
-                    : _jsx(PreEscapedText, { children: sliceSpans(custom, viewport.sourceOffsets[position], line.length).map((span, index) => _jsx(PreEscapedText, { color: span.color, bold: span.bold, children: span.text }, index)) }, position);
+                    ? _jsx(PreviewLine, { line: line, position: position, logicalLine: lines[logical], offset: viewport.sourceOffsets[position], prefixLength: viewport.prefixLengths[position] }, position)
+                    : _jsx(PreEscapedText, { children: rowSpans(custom, line.slice(0, viewport.prefixLengths[position]), viewport.sourceOffsets[position], line.length - viewport.prefixLengths[position]).map((span, index) => _jsx(PreEscapedText, { color: span.color, bold: span.bold, children: span.text }, index)) }, position);
             }), viewport.footer.map((spans, row) => _jsx(PreEscapedText, { children: spans.map((span, index) => _jsx(PreEscapedText, { ...footerColor(span.role, viewport.reachedEnd), children: span.text }, index)) }, `footer-${row}`))] }));
 }

package/dist/src/tui/preview-window.js

@@ -1,20 +1,13 @@
 import { useWindowSize } from "ink";
 import stringWidth from "string-width";
 import { headerTabRowCount } from "./header-layout.js";
+import { ESCAPE_TEXT, namesEscapedCharacter, textUnits, UNSAFE_PATTERN } from "./text-wrap.js";
 const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 // Text shown in the TUI comes from recipes, Sources, Skills and Hosts. Raw, an ESC or carriage return redraws the terminal over the
 // lines under review and a bidi override reorders them; both also change the width the `y` gate was computed for. The zero-width joiner
 // stays because emoji sequences such as a person at a laptop are made with it.
-const UNSAFE_PATTERN = "(?!\\u200D)[\\p{Cc}\\p{Cf}\\u2028\\u2029]";
-const UNSAFE_CHARACTER = new RegExp(UNSAFE_PATTERN, "u");
 // A backslash run before text shaped like an escape we print (`\x1b`, `\u202e`, `\u{1f600}`), or before a character we escape.
-const ESCAPE_TEXT = "x[0-9a-f]{2}|u[0-9a-f]{4}|u\\{[0-9a-f]{1,6}\\}";
 const ESCAPABLE = new RegExp(`(\\\\+)(?:(${ESCAPE_TEXT})|(?=${UNSAFE_PATTERN}))|${UNSAFE_PATTERN}`, "giu");
-/** Whether `escape` (`x1b`, `u202e`, `u{1f600}`) names a character this module would print as an escape. */
-function namesEscapedCharacter(escape) {
-    const code = Number.parseInt(escape.replace(/^[xu]\{?|\}$/gu, ""), 16);
-    return code <= 0x10ffff && UNSAFE_CHARACTER.test(String.fromCodePoint(code));
-}
 /**
  * `text` with control, format and line-separator characters replaced by visible escapes (`\x1b`, `\u202e`). A backslash run right
  * before text that looks like one of those escapes is doubled, so a typed `\x1b` cannot pass for a real ESC; other backslashes,
@@ -41,26 +34,44 @@ function escapeChrome(chrome) {
         ...(chrome.cancel === undefined ? {} : { cancel: escapeControlText(chrome.cancel) }),
     };
 }
-function wrapLine(line, width) {
-    const segments = [...graphemes.segment(line)];
+const TREE_GUTTER = /^( *)([│┌├└])?( *)/u;
+/**
+ * What continuation rows of a wrapped line start with: its indent and, in a step tree, the gutter that
+ * keeps running below its branch (`│` under `┌` and `├`, nothing under `└`). Empty when the prefix would
+ * leave less than half the width for text.
+ */
+function hangingPrefix(line, width) {
+    const [, before = "", glyph = "", after = ""] = TREE_GUTTER.exec(line) ?? [];
+    const continued = glyph === "" ? "" : glyph === "└" ? " " : "│";
+    const prefix = `${before}${continued}${after}`;
+    return stringWidth(prefix) * 2 <= width ? prefix : "";
+}
+function wrapLine(line, width, hang = false) {
+    const segments = textUnits(line, width);
     if (segments.length === 0)
-        return [{ row: "", offset: 0 }];
+        return [{ row: "", offset: 0, prefixLength: 0 }];
+    const prefix = hang ? hangingPrefix(line, width) : "";
     const wrapped = [];
     let row = "";
     let rowWidth = 0;
     let rowOffset = 0;
+    let prefixLength = 0;
+    let hasText = false;
     for (const { segment, index } of segments) {
         const segmentWidth = stringWidth(segment);
-        if (row !== "" && rowWidth + segmentWidth > width) {
-            wrapped.push({ row, offset: rowOffset });
-            row = "";
-            rowWidth = 0;
+        if (hasText && rowWidth + segmentWidth > width) {
+            wrapped.push({ row, offset: rowOffset, prefixLength });
+            row = prefix;
+            rowWidth = stringWidth(prefix);
+            prefixLength = prefix.length;
+            hasText = false;
             rowOffset = index;
         }
         row += segment;
         rowWidth += segmentWidth;
+        hasText = true;
     }
-    wrapped.push({ row, offset: rowOffset });
+    wrapped.push({ row, offset: rowOffset, prefixLength });
     return wrapped;
 }
 const MAX_BAR_WIDTH = 12;
@@ -90,7 +101,8 @@ function footerSpans(state, chrome, width) {
     const progress = state.reachedEnd
         ? [{ text: "read ✓", role: "read" }]
         : [{ text: `read ${bar}${Math.floor(read * 100)}%`, role: "reading" }];
-    progress.push({ text: ` · ${position(state.cursor + 1, state.start + 1, state.end)}`, role: "position" });
+    if (state.total > 0)
+        progress.push({ text: ` · ${position(state.cursor + 1, state.start + 1, state.end)}`, role: "position" });
     if (!state.reachedEnd)
         progress.push({ text: " · arrows/Pg page", role: "position" });
     else if (chrome.consequence !== undefined)
@@ -142,17 +154,37 @@ function reservedFooterRows(total, windowed, chrome, width, maxRows) {
     const widest = { cursor: Math.max(total - 1, 0), start: Math.max(total - 1, 0), end: total, total, windowed };
     return Math.max(layoutFooter(footerSpans({ ...widest, reachedEnd: false }, chrome, width), width, maxRows).length, layoutFooter(footerSpans({ ...widest, reachedEnd: true }, chrome, width), width, maxRows).length);
 }
+/** `title` cut, with an ellipsis, to the longest start that wraps to at most `maxRows` once escaped. */
+function clipTitle(title, width, maxRows) {
+    const fits = (text) => wrapLine(escapeControlText(text), width).length <= maxRows;
+    if (fits(title))
+        return title;
+    const parts = [...graphemes.segment(title)].map(({ segment }) => segment);
+    let low = 0;
+    let high = parts.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (fits(`${parts.slice(0, middle).join("")}…`))
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return `${parts.slice(0, low).join("")}…`;
+}
 export function previewViewport(rawLines, cursor, terminalRows, terminalColumns, rawChrome) {
     const lines = rawLines.map(escapeControlText);
     const chrome = escapeChrome(rawChrome);
     const contentWidth = Math.max(terminalColumns - 8, 1);
-    const wrapped = lines.flatMap((line, sourceLine) => wrapLine(line, contentWidth).map(({ row, offset }) => ({ row, sourceLine, offset })));
+    const wrapped = lines.flatMap((line, sourceLine) => wrapLine(line, contentWidth, true).map((wrappedRow) => ({ ...wrappedRow, sourceLine })));
     const previewRows = wrapped.map(({ row }) => row);
     const total = previewRows.length;
     const headerRows = headerTabRowCount(contentWidth) + 3;
-    const titleRows = wrapLine(chrome.title, contentWidth).length;
     const reservedRows = chrome.reservedRows !== undefined && chrome.reservedRows > 0 ? Math.ceil(chrome.reservedRows) : 0;
-    const fixedRows = headerRows + 1 + 2 + titleRows + reservedRows;
+    // The footer, with its question and its action, is reserved first; the title takes what remains after a row of content.
+    const footerRows = Math.max(reservedFooterRows(total, false, chrome, contentWidth, Infinity), reservedFooterRows(total, true, chrome, contentWidth, Infinity));
+    const titleBudget = Math.max(terminalRows - headerRows - 1 - 2 - reservedRows - 1 - footerRows, 1);
+    const titleRows = wrapLine(escapeControlText(clipTitle(rawChrome.title, contentWidth, titleBudget)), contentWidth).map(({ row }) => row);
+    const fixedRows = headerRows + 1 + 2 + titleRows.length + reservedRows;
     // At least one preview row stays visible; the footer is cut to what remains.
     const maxFooterRows = Math.max(terminalRows - fixedRows - 1, 2);
     const rowsWithFooter = (windowed) => Math.max(terminalRows - fixedRows - reservedFooterRows(total, windowed, chrome, contentWidth, maxFooterRows), 1);
@@ -163,9 +195,11 @@ export function previewViewport(rawLines, cursor, terminalRows, terminalColumns,
     const end = Math.min(start + height, total);
     const reachedEnd = end === total;
     return {
+        titleRows,
         rows: previewRows.slice(start, end),
         sourceLines: wrapped.slice(start, end).map(({ sourceLine }) => sourceLine),
         sourceOffsets: wrapped.slice(start, end).map(({ offset }) => offset),
+        prefixLengths: wrapped.slice(start, end).map(({ prefixLength }) => prefixLength),
         start,
         end,
         total,

package/dist/src/tui/profile-view.js

@@ -17,7 +17,7 @@ import { isYes, useKeys } from "./keys.js";
 import { escapeControlText, usePreviewGeometry } from "./preview-window.js";
 import { answerYesNo, moveCursor, movePreviewCursor, toggleChoice } from "./mode-keys.js";
 import { BorderPanel, PagedPreview, PreviewLines, Working } from "./panel-parts.js";
-import { clipText, elideMiddle, fitLines, wrapText } from "./text-wrap.js";
+import { clipText, elideMiddle, fitLines, textUnits, wrapText } from "./text-wrap.js";
 import { theme } from "./theme.js";
 import { useMirrored, useMounted } from "./view-state.js";
 import { computeWindow, useListHeight } from "./window.js";
@@ -145,7 +145,7 @@ const NOTE_CHROME = { title: "Export note", cancel: "[Esc] close" };
  * what matter, so with fewer than three rows the field keeps its label and its tail behind a `…`; with
  * three or more a path keeps its first row too, around a count of the rows left out.
  */
-function NameField({ label, value, rows, width, tail = false }) {
+export function NameField({ label, value, rows, width, tail = false }) {
     // Measured and drawn as escaped, so a hostile path or name takes the rows it is shown on.
     const escapedValue = escapeControlText(value);
     const wrapped = wrapText(`${label}${escapedValue}`, width);
@@ -155,9 +155,10 @@ function NameField({ label, value, rows, width, tail = false }) {
     if (keepsMiddleCount)
         shown = elideMiddle(wrapped, rows, width);
     else if (cut) {
-        const characters = Array.from(escapedValue);
-        for (let dropped = 1; dropped <= characters.length; dropped += 1) {
-            shown = wrapText(`${label}…${characters.slice(dropped).join("")}`, width);
+        // Dropped by units, so the cut cannot leave half of a doubled backslash that would read as a real escape.
+        const units = textUnits(escapedValue).map(({ segment }) => segment);
+        for (let dropped = 1; dropped <= units.length; dropped += 1) {
+            shown = wrapText(`${label}…${units.slice(dropped).join("")}`, width);
             if (shown.length <= rows)
                 break;
         }
@@ -640,5 +641,5 @@ export function ProfileView({ operations, environment = {}, onCapturingChange, l
     return _jsxs(Box, { flexDirection: "column", children: [mode === "export-folder" ? _jsx(FilePicker, { purpose: "directory", listHeight: listHeight, startDirectory: exportDirectory ?? startDirectory, onCancel: () => setMode("export-list"), onChoose: selection => { if (selection.kind === "directory")
                     chooseExportDirectory(selection.directory); } }) : null, mode === "import-browse" ? _jsx(FilePicker, { purpose: "file", listHeight: listHeight, startDirectory: importDirectory ?? startDirectory, notice: importNotice, onCancel: () => setMode("browse"), onChoose: chooseImportFile }) : null, listing ? _jsxs(BorderPanel, { title: mode === "export-list" ? "Export Profile" : "Import Profile", children: [listContent, _jsx(Text, { color: theme.legend, children: hintText }), window.indicator ? _jsx(Text, { color: theme.muted, children: window.indicator }) : null] }) : null, mode === "browse" ? _jsx(BorderPanel, { title: "Portable Profile", children: _jsx(Text, { color: theme.legend, children: "e export \u00B7 i import" }) }) : null, mode === "busy" && working ? _jsx(Working, { label: working.label, since: working.startedAt }) : null, mode === "export-name" ? _jsxs(BorderPanel, { title: "Export file name", children: [_jsx(NameField, { label: "Folder: ", value: exportDirectory ?? startDirectory, rows: folderRows, width: panelWidth }), _jsx(NameField, { label: "Name: ", value: `${text}_`, rows: nameRows, width: panelWidth, tail: true }), liveDestination === undefined ? null : _jsx(NameField, { label: "Destination: ", value: liveDestination, rows: destinationRows, width: panelWidth }), nameNote === undefined ? null : _jsx(PreEscapedText, { color: theme.warning, children: escapeControlText(nameNote) }), extensionNote === undefined ? null : _jsx(PreEscapedText, { color: theme.muted, children: escapeControlText(extensionNote) }), nameError === undefined ? null : nameErrorLines.length <= NAME_ERROR_ROWS
                         ? _jsx(PreEscapedText, { color: theme.error, children: escapeControlText(nameError) })
-                        : elideMiddle(nameErrorLines, NAME_ERROR_ROWS, panelWidth).map((line, index) => _jsx(PreEscapedText, { color: theme.error, children: line }, index)), nameChecking === undefined ? null : _jsx(Working, { label: "Checking name\u2026", since: nameChecking }), _jsx(Text, { color: theme.legend, children: NAME_HINT })] }) : null, mode === "confirm" ? _jsx(PagedPreview, { chrome: confirmChrome(), lines: lines, viewport: previewGeometry(lines, cursor, confirmChrome()) }) : null, mode === "detail" ? _jsx(PagedPreview, { chrome: NOTE_CHROME, lines: lines, viewport: previewGeometry(lines, cursor, NOTE_CHROME) }) : null, mode === "results" ? _jsxs(_Fragment, { children: [_jsx(PreviewLines, { lines: lines.slice(window.start, window.end) }), _jsx(Text, { children: "j/k scroll" })] }) : null, window.indicator && mode === "results" ? _jsx(Text, { children: window.indicator }) : null] });
+                        : elideMiddle(nameErrorLines, NAME_ERROR_ROWS, panelWidth).map((line, index) => _jsx(PreEscapedText, { color: theme.error, children: line }, index)), nameChecking === undefined ? null : _jsx(Working, { label: "Checking name\u2026", since: nameChecking }), _jsx(Text, { color: theme.legend, children: NAME_HINT })] }) : null, mode === "confirm" ? _jsx(PagedPreview, { lines: lines, viewport: previewGeometry(lines, cursor, confirmChrome()) }) : null, mode === "detail" ? _jsx(PagedPreview, { lines: lines, viewport: previewGeometry(lines, cursor, NOTE_CHROME) }) : null, mode === "results" ? _jsxs(_Fragment, { children: [_jsx(PreviewLines, { lines: lines.slice(window.start, window.end) }), _jsx(Text, { children: "j/k scroll" })] }) : null, window.indicator && mode === "results" ? _jsx(Text, { children: window.indicator }) : null] });
 }

package/dist/src/tui/render.js

@@ -5,14 +5,16 @@ import { App } from "./app.js";
 /** Renders the TUI and resolves once the user exits it. */
 export async function renderTui(operations, environment) {
     const refreshSession = createSourceRefreshSession(operations);
-    const instance = render(_jsx(App, { operations: operations, environment: environment, refreshSession: refreshSession, 
-        // Test-only opt-out (tests/isolated-env.ts); manual and preview refreshes are unaffected.
-        refreshOnStart: process.env.AGENT_DEPOT_NO_BACKGROUND_REFRESH !== "1" }), { alternateScreen: true });
+    const instance = render(_jsx(App, { operations: operations, environment: environment, refreshSession: refreshSession, refreshOnStart: environment?.refreshOnStart ?? true }), { alternateScreen: true });
     await instance.waitUntilExit();
+    await finishRunningRefreshes(refreshSession, (message) => process.stderr.write(message));
+}
+/** Drops the queued refreshes and waits for the running ones, telling the user only when it has to wait. */
+export async function finishRunningRefreshes(refreshSession, write) {
     refreshSession.stop();
     // Killing a refresh would leave its Source cache lock behind, so wait for the running ones instead.
     if ([...refreshSession.snapshot().values()].some((state) => state.status === "refreshing")) {
-        process.stderr.write("Waiting for the Source refreshes still running to finish…\n");
+        write("Waiting for the Source refreshes still running to finish…\n");
         await refreshSession.settled();
     }
 }

package/dist/src/tui/sources-recipes.js

@@ -364,16 +364,16 @@ export function useSourcesRecipes({ operations, environment, onCapturingChange,
     const panel = (_jsxs(Box, { flexDirection: "column", children: [loadError && !pagedPreview ? _jsxs(Text, { color: theme.error, children: ["Error loading App recipes: ", loadError] }) : null, error && !pagedPreview ? _jsx(Text, { color: theme.error, children: error }) : null, notice && !pagedPreview ? _jsx(Text, { color: theme.success, children: notice }) : null, mode.kind === "guide" ? (_jsxs(BorderPanel, { title: "Add an App recipe", children: [_jsx(Text, { children: "1 With the AI skill \u00B7 install if missing, then copy the prompt" }), _jsx(Text, { children: "2 Manual \u00B7 write a recipe using the schema" }), _jsx(Text, { children: "n or Esc closes" })] })) : null, mode.kind === "manual" ? (_jsxs(BorderPanel, { title: "Write an App recipe", children: [_jsxs(Text, { children: ["Write a JSON recipe in ", apps.directory] }), _jsx(Text, { children: "Schema: agent-depot app schema \u00B7 n or Esc closes" })] })) : null, mode.kind === "prompt" ? (_jsxs(BorderPanel, { title: "App recipe authoring prompt", children: [_jsx(Text, { children: "Use the agent-depot-apprecipe skill to create the recipe for <app>" }), _jsxs(Text, { children: ["Recipes: ", apps.directory, " \u00B7 n or Esc closes"] })] })) : null, mode.kind === "install" ? _jsx(ActionPanel, { mode: mode.action }) : null, mode.kind === "busy" ? _jsx(BorderPanel, { title: "App recipe workflow", children: _jsx(Working, { label: mode.label, since: mode.startedAt }) }) : null, mode.kind === "approve" ? (() => {
                 const chrome = recipeApprovalChrome(mode.entry);
                 const lines = mode.lines.map(lineText);
-                return _jsx(PagedPreview, { chrome: chrome, lines: lines, styled: mode.lines, viewport: previewGeometry(lines, mode.cursor, chrome) });
+                return _jsx(PagedPreview, { lines: lines, styled: mode.lines, viewport: previewGeometry(lines, mode.cursor, chrome) });
             })() : null, mode.kind === "pick" ? (_jsxs(BorderPanel, { title: "Remove which recipe?", children: [mode.members.map((row, index) => _jsxs(Text, { children: [index + 1, " ", recipeMemberLine(row)] }, row.entry.file)), _jsx(Text, { color: theme.legend, children: "Press a number to review that one file for removal \u00B7 n or Esc cancels" })] })) : null, mode.kind === "uninstall-question" ? (_jsxs(BorderPanel, { title: "Uninstall before recipe removal", children: [_jsxs(Text, { children: ["App ", appName(mode.removal.entry), " is installed or tracked", mode.removal.installedVersion ? ` (${mode.removal.installedVersion})` : "", "."] }), _jsxs(Text, { children: [_jsx(DecisionPrompt, { children: "Uninstall it before removing the recipe?" }), _jsx(Text, { color: theme.legend, children: "(n cancels removal)" })] })] })) : null, mode.kind === "uninstall-confirm" || mode.kind === "uninstall-manual" ? (() => {
                 const chrome = uninstallChrome(mode);
                 const styled = appPlanLines(mode.plan);
                 const lines = styled.map(lineText);
-                return _jsx(PagedPreview, { chrome: chrome, lines: lines, styled: styled, viewport: previewGeometry(lines, mode.cursor, chrome) });
+                return _jsx(PagedPreview, { lines: lines, styled: styled, viewport: previewGeometry(lines, mode.cursor, chrome) });
             })() : null, mode.kind === "remove" ? (() => {
                 const chrome = removeChrome(mode.removal);
                 const lines = removeLines(mode.removal);
-                return _jsx(PagedPreview, { chrome: chrome, lines: lines, viewport: previewGeometry(lines, mode.cursor, chrome) });
+                return _jsx(PagedPreview, { lines: lines, viewport: previewGeometry(lines, mode.cursor, chrome) });
             })() : null] }));
     return { rows, loadingSince, handleKey, startAdd, reload, clearMessage: () => { setError(undefined); setNotice(undefined); }, panel, directory: apps.directory, capturing: mode.kind !== "browse" };
 }

package/dist/src/tui/sources-view.js

@@ -11,7 +11,6 @@ import { groupRecipeRows, useSourcesRecipes } from "./sources-recipes.js";
 import { BorderPanel, PagedPreview, Working } from "./panel-parts.js";
 import { usePreviewGeometry } from "./preview-window.js";
 import { movePreviewCursor } from "./mode-keys.js";
-import { formatAgo } from "./updates.js";
 import { animationEnabled, formatElapsed } from "./working-model.js";
 /** Footer keys for the selected row; App seeds the footer before the view reports a selection. */
 export function sourceRowHints(row) {
@@ -69,7 +68,7 @@ function RefreshMark({ state, now }) {
         case "refreshing":
             return _jsxs(Text, { color: theme.warning, children: ["\u2026 refreshing ", formatElapsed(now - (state.startedAt ?? now))] });
         case "refreshed":
-            return _jsxs(Text, { color: theme.success, children: ["\u2713 refreshed ", formatAgo(now - (state.finishedAt ?? now))] });
+            return _jsx(Text, { color: theme.success, children: "\u2713 refreshed" });
         case "failed":
             return _jsx(Text, { color: theme.error, children: "\u2717 refresh failed" });
     }
@@ -408,7 +407,7 @@ function Prompt({ mode, previewGeometry }) {
         return _jsx(BorderPanel, { title: "Sources", children: _jsx(Working, { label: mode.label, since: mode.startedAt }) });
     if (mode.kind === "confirm" && previewGeometry !== undefined) {
         const { lines, chrome } = confirmPreview(mode);
-        return _jsx(PagedPreview, { chrome: chrome, lines: lines, viewport: previewGeometry(lines, mode.cursor, chrome) });
+        return _jsx(PagedPreview, { lines: lines, viewport: previewGeometry(lines, mode.cursor, chrome) });
     }
     return null;
 }

package/dist/src/tui/text-wrap.js

@@ -1,11 +1,55 @@
 import stringWidth from "string-width";
 const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+// Control, format and line-separator characters the TUI prints as escapes; the zero-width joiner stays for emoji sequences.
+export const UNSAFE_PATTERN = "(?!\\u200D)[\\p{Cc}\\p{Cf}\\u2028\\u2029]";
+const UNSAFE_CHARACTER = new RegExp(UNSAFE_PATTERN, "u");
+/** Text shaped like an escape the TUI prints (`x1b`, `u202e`, `u{1f600}`), ignoring case. */
+export const ESCAPE_TEXT = "x[0-9a-f]{2}|u[0-9a-f]{4}|u\\{[0-9a-f]{1,6}\\}";
+const ESCAPE_UNIT = new RegExp(`(\\\\+)(${ESCAPE_TEXT})`, "giu");
+/** Whether `escape` (`x1b`, `u202e`, `u{1f600}`) names a character the TUI would print as an escape. */
+export function namesEscapedCharacter(escape) {
+    const code = Number.parseInt(escape.replace(/^[xu]\{?|\}$/giu, ""), 16);
+    return code <= 0x10ffff && UNSAFE_CHARACTER.test(String.fromCodePoint(code));
+}
+/**
+ * The units text is cut at: graphemes, except around an escape written as text that names a character the TUI escapes. Cut inside,
+ * its doubled backslash would leave a `\x1b` that reads as a real ESC. The backslash run splits into pairs from the left, so a cut
+ * between pairs keeps its parity, and the last one or two backslashes stay with the escape text: a unit is at most 12 columns. A unit
+ * wider than `maxWidth` falls back to graphemes. `index` is the UTF-16 offset of the unit.
+ */
+export function textUnits(value, maxWidth = Infinity) {
+    const units = [];
+    let from = 0;
+    const addGraphemes = (text, offset) => {
+        for (const { segment, index } of graphemes.segment(text))
+            units.push({ segment, index: offset + index });
+    };
+    for (const match of value.matchAll(ESCAPE_UNIT)) {
+        const [whole, backslashes = "", escape = ""] = match;
+        if (!namesEscapedCharacter(escape))
+            continue;
+        const tail = backslashes.length % 2 === 1 ? 1 : 2;
+        const pairs = backslashes.length - tail;
+        const unit = backslashes.slice(pairs) + escape;
+        addGraphemes(value.slice(from, match.index), from);
+        if (stringWidth(unit) > maxWidth)
+            addGraphemes(whole, match.index);
+        else {
+            for (let offset = 0; offset < pairs; offset += 2)
+                units.push({ segment: "\\\\", index: match.index + offset });
+            units.push({ segment: unit, index: match.index + pairs });
+        }
+        from = match.index + whole.length;
+    }
+    addGraphemes(value.slice(from), from);
+    return units;
+}
 /** Split text on grapheme boundaries so wide and combining characters wrap at `width` columns. */
 export function wrapText(value, width) {
     const lines = [];
     let line = "";
     let lineWidth = 0;
-    for (const { segment } of graphemes.segment(value)) {
+    for (const { segment } of textUnits(value, width)) {
         const segmentWidth = stringWidth(segment);
         if (line && lineWidth + segmentWidth > width) {
             lines.push(line);
@@ -26,7 +70,7 @@ export function fitLines(lines, maxRows, width) {
     const visible = lines.slice(0, maxRows);
     let last = "";
     let used = 0;
-    for (const { segment } of graphemes.segment(visible[maxRows - 1])) {
+    for (const { segment } of textUnits(visible[maxRows - 1])) {
         const segmentWidth = stringWidth(segment);
         if (used + segmentWidth > width - 1)
             break;
@@ -55,7 +99,7 @@ export function clipText(value, width) {
         return value;
     let last = "";
     let used = 0;
-    for (const { segment } of graphemes.segment(value)) {
+    for (const { segment } of textUnits(value)) {
         const segmentWidth = stringWidth(segment);
         if (used + segmentWidth > Math.max(width - 1, 0))
             break;

package/dist/src/tui/updates-panel.js

@@ -59,7 +59,7 @@ function CapturedUpdatePreview({ mode }) {
     const styled = updateModePreviewLines(mode);
     const lines = styled.map(lineText);
     const chrome = updateModePreviewChrome(mode);
-    return _jsx(PagedPreview, { chrome: chrome, lines: lines, styled: styled, viewport: usePreviewGeometry()(lines, mode.cursor, chrome) });
+    return _jsx(PagedPreview, { lines: lines, styled: styled, viewport: usePreviewGeometry()(lines, mode.cursor, chrome) });
 }
 export function ModePanel({ mode }) {
     switch (mode.kind) {

package/dist/src/tui/updates-view.js

@@ -16,6 +16,12 @@ import { lineText } from "./preview-render.js";
 import { updateModePreviewChrome, updateModePreviewLines } from "./updates-preview.js";
 import { useKeys } from "./keys.js";
 import { BorderPanel, Working } from "./panel-parts.js";
+/** Whether the working panel is drawn. A preview owns the screen: its height was computed without the panel, so the two never share it. */
+export function showsWorkingPanel(state, mode) {
+    if (mode.kind === "preview" || mode.kind === "manual" || mode.kind === "confirm-paths")
+        return false;
+    return state.status === "loading" || mode.kind === "busy";
+}
 const NO_ENVIRONMENT = {};
 /** How often the age of the check is redrawn. */
 const CLOCK_TICK_MS = 10_000;
@@ -116,6 +122,6 @@ export function UpdatesView({ operations, environment, onCapturingChange, listHe
     const hasErrors = data?.appError !== undefined || (data?.results ?? []).some((result) => result.error !== undefined);
     const showingBrowse = mode.kind === "browse";
     // One indicator for the whole operation: a check's own phase label, else the busy mode's.
-    const working = state.status === "loading" ? state : mode.kind === "busy" ? mode : undefined;
+    const working = !showsWorkingPanel(state, mode) ? undefined : state.status === "loading" ? state : mode.kind === "busy" ? mode : undefined;
     return (_jsxs(Box, { flexDirection: "column", children: [showingBrowse ? _jsxs(Text, { color: theme.title, bold: true, children: ["Updates (scope: ", scope, ")  t all \u00B7 p project \u00B7 g user-global \u00B7 u update"] }) : null, working ? _jsx(BorderPanel, { title: state.status === "loading" ? "Update check" : "Updates", children: _jsx(Working, { label: working.label, since: working.startedAt, now: clock }) }) : null, showingBrowse && data ? _jsx(CheckStatus, { data: data, now: clock() }) : null, showingBrowse && data && !hasErrors && shown.length === 0 ? _jsx(Text, { children: "No installations" }) : null, showingBrowse ? entries.slice(window.start, window.end).map((entry, offset) => (_jsx(EntryLine, { entry: entry, selected: window.start + offset === index, checked: checked, view: view, showUnknown: showUnknown }, entryId(entry)))) : null, showingBrowse ? _jsx(UpdatesFooter, { indicator: window.indicator, upToDate: upToDate, updatableCount: updatable.length, checkedCount: checked.length, message: message }) : null, _jsx(ModePanel, { mode: mode })] }));
 }

package/dist/src/tui/updates.js

@@ -5,7 +5,7 @@ import { sourceIdForUrl } from "../git-source.js";
 import { applyConfirmedUpdates, loadUpdates, previewUpdateCandidates, readScopeInstallations, skillUpdatePreviewItem, } from "../update-flow.js";
 import { packageOperationsOf } from "./environment.js";
 import { formatVersionEvidence } from "./installations.js";
-import { describePackageComponent, installedEvidenceLabel, packageStatusLabel, packageVersionLabel, recordedVersionLabel } from "./package-rows.js";
+import { describePackageComponent, installedEvidenceLabel, packageStatusLabel, packageVersionLabel, installedVersionLabel, recordedVersionLabel } from "./package-rows.js";
 import { quoteText } from "../preview-model.js";
 /** Every scope the view can assess, in display order. */
 export const UPDATE_SCOPES = ["project", "user-global"];
@@ -213,7 +213,7 @@ function packagePreviewItem(row, { plan, approval }) {
     return {
         title: descriptor.name,
         detail: selection.host,
-        version: { from: recordedVersionLabel(row.check.installed), to: packageVersionLabel(descriptor.version) },
+        version: { from: installedVersionLabel(row.check), to: packageVersionLabel(descriptor.version) },
         rows,
     };
 }
@@ -291,7 +291,7 @@ export async function prepareUpdates(data, selected) {
         groups, apps: data.apps, appPlans, appFailures,
         packages: data.packages, packagePlans, packageFailures,
         document: {
-            action: `Apply ${counted(applicable.length, "update")}`,
+            action: applicable.length === 0 ? "No updates can be applied" : `Apply ${counted(applicable.length, "update")}`,
             summary: sections.map(({ items, noun }) => counted(items.length, noun)).join(" · "),
             context: [...context, ...[...environments].map((environment) => `Environment: ${environment}`)],
             warnings,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iseoane/agent-depot",
-  "version": "0.6.14",
+  "version": "0.6.16",
   "description": "A cross-platform catalog for reusable coding-agent skills.",
   "license": "MIT",
   "author": "iseoane",

package/skills/agent-depot-apprecipe/SKILL.md

@@ -4,7 +4,7 @@ description: "Trigger: App recipe creation or repair. Research an App's actual i
 license: MIT
 metadata:
   author: "iseoane"
-  version: "1.2"
+  version: "1.3"
 ---
 
 ## Activation Contract
@@ -43,6 +43,7 @@ Check installation **and** update, uninstall, version/latest and each Host setup
 - **Runtime/build and hook requirements:** verify documented engine ranges, compiler/toolchain minimums, architecture/libc support and utilities such as `git`, `curl`, `jq` or extraction tools. Check write access to the actual global prefix and required elevation; never assume sudo or request credentials in chat. Inspect prerequisites for Host plugins separately from the App binary.
 - **Unattended behavior:** use installed manager `--help`/documented help and upstream installer source to establish confirmation defaults and supported flags. Verify explicit formula/cask or package disambiguation where necessary. Do not invent `--yes` flags or rely on stdin EOF to count as consent. Run dry-run/read-only probes only after checking they do not install, register, authenticate or rewrite configuration; never test a lifecycle command just to see whether it prompts.
 - **Version and update signals:** verify a release-meaningful version (not an unchanged `dev`) and a latest signal for the chosen channel. A GitHub release can be ahead of a package-manager formula. Use channel metadata when available and disclose freshness limits; do not run `brew update` or another mutating refresh as a read-only latest probe.
+- **Host wiring:** for each Host the user uses, read the installed App's setup help (for example `<app> setup --help`) and establish, per Host, whether setup runs unattended and which flags it accepts; a flag valid for one Host can be rejected for another. Inspect existing wiring that setup may conflict with or duplicate: user MCP entries (for Claude, `mcpServers` in `~/.claude.json`), Host plugins (`claude plugin list`), Host packages (`pi list`) and permissions entries. Setup that refuses to overwrite a conflicting entry needs a documented removal step first. Flags that grant permissions or bypass prompts are the user's choice: present them, never select them silently.
 - **Preserved state:** identify existing binary copies, data directories and Host wiring without reading private memory content. Explain migrations, backups and teardown scope outside executable argv where appropriate; never delete user data or remove a shared tap/marketplace implicitly.
 
 ### Homebrew checklist
@@ -59,10 +60,10 @@ Read the current schema; do not assume it has dependency or multi-command fields
 
 1. Record upstream evidence and platform support. Inspect all PATH matches (`which -a`/`whence -a`, or Windows `Get-Command -All`), resolved paths, and channel inventories such as `brew list`, `npm ls -g` or `pipx list`. List Windows shims seen from WSL separately: `/mnt/<drive>/` executables cannot serve a Linux recipe. Finish only when the actual channel is established or the user has chosen one.
 2. Complete the Installer Preflight and resolve the prerequisite decision gate before writing required `name`, `install`, `update`, `uninstall`, and `version`. Each lifecycle step uses `argv`, `manual`, or both; manual fallback applies only to spawn failure, never non-zero exit. `version` needs read-only argv and a JavaScript regex with exactly one capture group. Choose optional `latest` as `github: owner/repo`, `npm: package`, or read-only `argv` plus `pattern`; omit it when unknown. Consult [the illustrative example](assets/example.md), not as upstream command evidence.
-3. Put user-global Host wiring in optional `setup`/`teardown` maps keyed by `pi`, `claude`, `codex`, or `opencode`. Keep install separate; uninstall never implicitly runs teardown. Delegate wiring to App commands or manual user instructions, not direct agent edits of Host configuration. Exclude project initialization.
+3. Ask which Hosts the user uses when it is not already established. Put user-global Host wiring in optional `setup`/`teardown` maps keyed by `pi`, `claude`, `codex`, or `opencode`. Keep install separate; uninstall never implicitly runs teardown. Agent Depot never executes `manual` text and does not track wiring, so a manual setup stays undone unless the user runs it: use `argv` whenever the Host Wiring preflight shows an unattended route, and keep `manual` only for steps that need a terminal or a user decision. When repairing a recipe or after an App update, recheck every `manual` setup step against the installed version's help; a new non-interactive flag can make it automatable. Delegate wiring to App commands or manual user instructions, not direct agent edits of Host configuration. Exclude project initialization.
 4. Declare optional `skills` only for documented App-owned directory/link names. Match whole names case-sensitively; only `*` is special, while `?` and brackets are literal. Reject empty/whitespace-only, path separators, NUL and star-only patterns. These declarations filter unmanaged adoption/removal even before approval/install; they verify no artifacts or provenance.
 5. Run `agent-depot app validate <file>...` for current-platform recipes. Fix structural errors; report unapproved recipes as needs approval, not runtime-verified. Distinguish structural validity, recipe approval, prerequisite readiness, installed version and Host wiring; none proves the others. A known missing prerequisite remains a blocker even when validation succeeds. Version commands run only for approved applicable content. Mark other platforms unverified. After user approval, the user can inspect `app list` and separately preview `app install|update|uninstall <name>` or `app setup|teardown <name> --host <host>`.
 
 ## Output Contract
 
-Return file paths, platform/channel evidence, a concise prerequisite status (satisfied/missing/unverified) with preparation commands and whether the recipe is ready or blocked, validation results and runtime-verification limits; unsupported platforms; omitted optional fields and why; license, telemetry/update-check behavior (or unknown); and conflicting duplicate install routes, including plugin-marketplace versus setup routes. Explain that version alone determines installed state, updates require a changed version, and unknown latest is not an available update. End with the user's approval command, without running it.
+Return file paths, platform/channel evidence, a per-Host wiring status for each Host the user uses (wired, pending, manual or conflicting, with the evidence inspected) and the exact `agent-depot app setup <name> --host <host>` command for each pending Host, a concise prerequisite status (satisfied/missing/unverified) with preparation commands and whether the recipe is ready or blocked, validation results and runtime-verification limits; unsupported platforms; omitted optional fields and why; license, telemetry/update-check behavior (or unknown); and conflicting duplicate install routes, including plugin-marketplace versus setup routes. Explain that version alone determines installed state, updates require a changed version, and unknown latest is not an available update. End with the user's approval command, without running it.