kritya 0.8.29-beta → 0.8.31-beta

package/dist/agent/loop.js

@@ -28,6 +28,19 @@ export class Agent {
     contextWindow = 120_000;
     /** Max model round-trips per request before stopping to ask the user. */
     maxSteps = DEFAULT_MAX_STEPS;
+    /**
+     * 1-based index of the step the loop is currently on, 0 before the first
+     * model call. Read by the subagent runner to report "step 4/15" as it works.
+     */
+    stepIndex = 0;
+    /**
+     * True when the last run stopped because it reached `maxSteps` rather than
+     * finishing. That is the "wants to keep going" case, and it is the only
+     * signal that distinguishes it — the loop just ends either way, and the
+     * message it appends afterwards is indistinguishable from model output to
+     * anything that doesn't parse it.
+     */
+    hitStepLimit = false;
     /**
      * How long one tool call may run before it's abandoned (config
      * `toolTimeoutSeconds`). A tool with its own deadline opts out via
@@ -446,7 +459,13 @@ export class Agent {
         }
     }
     async runLoop(systemMsg, handlers, signal) {
+        // Reset per run, not per Agent: the main agent serves many turns in one
+        // process, so a previous turn that hit the cap must not leave the flag set
+        // for the next one.
+        this.stepIndex = 0;
+        this.hitStepLimit = false;
         for (let i = 0; i < this.maxSteps; i++) {
+            this.stepIndex = i + 1;
             // Checked ahead of the generic abort so a kill mid-turn is reported as
             // a kill rather than an ordinary cancellation.
             this.kill.assertLive();
@@ -519,6 +538,7 @@ export class Agent {
                 await this.tryCompact("Auto-compacted context", handlers, signal);
             }
         }
+        this.hitStepLimit = true;
         handlers.onAssistantText(`[Stopped after ${this.maxSteps} steps — the safety limit for one request. ` +
             `Send "continue" to keep going, or raise "maxSteps" in ~/.kritya/config.json.]`);
     }

package/dist/agent/subagents.js

@@ -0,0 +1,354 @@
+import { Agent } from "./loop.js";
+import { commitWorktree, createWorktree, isGitRepo, removeWorktree, worktreeDiffStat, } from "./worktree.js";
+import { PermissionManager } from "../permissions/permissions.js";
+import { SessionStore } from "../session/store.js";
+/**
+ * Batches are capped at six tasks by spawn_agent's own schema and at four by
+ * spawn_write_agent's, so allowing more concurrency than the larger of the two
+ * buys nothing — the extra slots can never be filled.
+ */
+export const MAX_SUBAGENT_CONCURRENCY = 6;
+export const DEFAULT_SUBAGENT_CONCURRENCY = 3;
+export const DEFAULT_SUBAGENT_TIMEOUT_MS = 10 * 60 * 1000;
+/** Read-only agents get half the budget of write agents: they search, they don't build. */
+export const DEFAULT_READ_SUBAGENT_STEPS = 15;
+export const DEFAULT_WRITE_SUBAGENT_STEPS = 30;
+/** Longest headline kept for the one-line progress report. */
+const HEADLINE_MAX = 72;
+/** A finite value floors to itself, bounded to 1..MAX_SUBAGENT_CONCURRENCY; anything else takes the default. */
+export function clampConcurrency(value) {
+    const wanted = typeof value === "number" && Number.isFinite(value)
+        ? Math.floor(value)
+        : DEFAULT_SUBAGENT_CONCURRENCY;
+    return Math.min(Math.max(wanted, 1), MAX_SUBAGENT_CONCURRENCY);
+}
+/**
+ * Why an aborted subagent stopped, or undefined if it wasn't aborted.
+ *
+ * The raw abort message is identical for both cases ("this operation was
+ * aborted"), so without this a ten-minute wall-clock cap reads exactly like the
+ * user pressing Ctrl-C.
+ */
+export function abortOutcome(opts) {
+    if (opts.timedOut)
+        return { error: "timed out before finishing", stoppedEarly: "timeout" };
+    if (opts.cancelled)
+        return { error: "cancelled", stoppedEarly: "cancelled" };
+    return undefined;
+}
+/** Joins the non-empty reasons a subagent's work could not be used, or undefined if there are none. */
+export function mergeErrors(...messages) {
+    const kept = messages.filter((m) => typeof m === "string" && m.trim() !== "");
+    return kept.length > 0 ? kept.join(" ") : undefined;
+}
+/** One collapsed line from a finished result, for the progress line. */
+export function headline(result) {
+    const text = (result.error ?? result.summary).replace(/\s+/g, " ").trim();
+    if (text === "")
+        return "no findings";
+    return text.length > HEADLINE_MAX ? `${text.slice(0, HEADLINE_MAX - 1)}…` : text;
+}
+/**
+ * The bracketed note the spawn_* tools append to a result, or undefined for a
+ * clean run.
+ *
+ * Shared by both tools so a failure reads the same either way, and so the
+ * single-task path can't lose it: that path returns the summary bare, which
+ * used to mean a lone failing subagent came back as an empty string with the
+ * reason nowhere in sight.
+ */
+export function subagentStatusNote(result) {
+    const notes = [];
+    if (result.error)
+        notes.push(`[error: ${result.error}]`);
+    if (result.stoppedEarly === "max-steps") {
+        notes.push("[stopped early: it hit its step limit, so the findings above are incomplete — " +
+            "re-dispatch a narrower task, or raise subagentMaxSteps]");
+    }
+    else if (result.stoppedEarly) {
+        notes.push(`[stopped early: ${result.stoppedEarly}]`);
+    }
+    return notes.length > 0 ? notes.join("\n") : undefined;
+}
+/**
+ * Handlers for a subagent's own agent loop: no streaming to a UI, but two
+ * things this file has to get right.
+ *
+ * Assistant text is accumulated rather than replaced. The loop emits one
+ * message per step, so the old `onAssistantText: (t) => (finalText = t)` kept
+ * only the last one — a subagent that reported findings and then carried on
+ * working silently lost them, and the summary came back as whatever it said
+ * last.
+ *
+ * And progress is reported from onToolStart rather than onTextDelta: deltas
+ * arrive per token, which would churn the parent's status line for no gain,
+ * while tool starts are the natural "here's what it's doing now" beat.
+ */
+export function createSubagentHandlers(opts) {
+    const parts = [];
+    return {
+        onTextDelta: () => { },
+        onReasoningDelta: () => { },
+        onAssistantText: (text) => {
+            const trimmed = text.trim();
+            if (trimmed === "")
+                return;
+            parts.push(trimmed);
+            opts.onFinalText(parts.join("\n\n"));
+        },
+        onToolStart: (_id, name, summary) => {
+            if (!opts.onStep)
+                return;
+            const label = summary.trim() || name;
+            const info = opts.stepInfo?.();
+            opts.onStep(info && info.max > 0 ? `step ${info.step}/${info.max} · ${label}` : label);
+        },
+        onToolEnd: () => { },
+        requestPermission: opts.requestPermission,
+        onUsage: () => { },
+    };
+}
+/**
+ * Builds the `spawnAgents` implementation the spawn_agent / spawn_write_agent
+ * tools call through `ToolContext`.
+ *
+ * Lives here rather than inline in the CLI entry point so the headless and
+ * Electron entry points can wire the same runner instead of going without
+ * subagents entirely, and so the logic is reachable from tests — `dist/index.js`
+ * is excluded from coverage, which is how the swallowed-failure and
+ * timeout-looks-like-cancel bugs survived in it.
+ */
+export function createSubagentRunner(deps) {
+    const concurrency = clampConcurrency(deps.concurrency);
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_SUBAGENT_TIMEOUT_MS;
+    const readMaxSteps = deps.readMaxSteps ?? DEFAULT_READ_SUBAGENT_STEPS;
+    const writeMaxSteps = deps.writeMaxSteps ?? DEFAULT_WRITE_SUBAGENT_STEPS;
+    /** Fields every subagent Agent shares, so the two runners can't drift apart. */
+    function baseAgent(tools, maxSteps, task, spanAttributes) {
+        const sub = new Agent(deps.client, deps.model, tools, {
+            workspace: deps.workspace,
+            sandboxMode: deps.sandboxMode,
+            trustWorkspace: deps.trustWorkspace,
+        }, new PermissionManager([], deps.workspace), new SessionStore(deps.workspace, true), []);
+        sub.maxSteps = maxSteps;
+        sub.audit = deps.audit;
+        // Both have non-optional NOOP defaults, so only overwrite when supplied.
+        if (deps.tracer)
+            sub.tracer = deps.tracer;
+        if (deps.meter)
+            sub.meter = deps.meter;
+        sub.kill = deps.kill();
+        sub.spanParent = deps.spanParent?.();
+        sub.spanAttributes = { ...spanAttributes, "kritya.subagent_task": task.slice(0, 120) };
+        return sub;
+    }
+    async function runReadOnlyAgent(task, signal, onProgress) {
+        const sub = baseAgent(deps.readOnlyTools, readMaxSteps, task, { "kritya.subagent": true });
+        let finalText = "";
+        await sub.runTurn(task, createSubagentHandlers({
+            onFinalText: (t) => (finalText = t),
+            // read-only tools never require permission, so this is never invoked
+            requestPermission: async () => "no",
+            onStep: onProgress,
+            stepInfo: () => ({ step: sub.stepIndex, max: sub.maxSteps }),
+        }), signal);
+        return {
+            task,
+            write: false,
+            summary: finalText.trim() || "(subagent returned no findings)",
+            // Hitting the cap is the "wants to keep going" case: the findings are
+            // real but incomplete, unlike a timeout, which is infrastructure.
+            ...(sub.hitStepLimit ? { stoppedEarly: "max-steps" } : {}),
+        };
+    }
+    async function runWriteAgent(task, signal, onProgress) {
+        if (!isGitRepo(deps.workspace)) {
+            return {
+                task,
+                write: true,
+                summary: "",
+                error: "the workspace is not a git repository, so an isolated worktree could not be created",
+            };
+        }
+        const wt = createWorktree(deps.workspace);
+        if (!wt) {
+            deps.audit?.logTool({
+                tool: "subagent_worktree",
+                summary: `worktree creation failed for task: ${task.slice(0, 72)}`,
+                outcome: "error",
+            });
+            return { task, write: true, summary: "", error: "failed to create an isolated git worktree" };
+        }
+        deps.audit?.logTool({
+            tool: "subagent_worktree",
+            summary: `created branch "${wt.branch}" for task: ${task.slice(0, 72)}`,
+            outcome: "ok",
+        });
+        let finalText = "";
+        // A subagent that died mid-run must not come back looking like a success:
+        // the tool renders `[error: …]` only when this is set, so without it a
+        // crash was reported as an ordinary summary that merely happened to begin
+        // with "(subagent stopped: …)" — and its partial edits were still committed.
+        let runError;
+        let stoppedEarly;
+        try {
+            // Auto-allow ordinary writes/edits/shell (no human is watching this run),
+            // but a destructive command still forces `warning` via classifyDanger in
+            // the agent loop regardless of the allowlist — fail-safe deny it there,
+            // since there's no one to confirm it and letting it run unattended would
+            // be unsafe even inside an isolated worktree (it still has real shell/
+            // network access).
+            const sub = new Agent(deps.client, deps.model, deps.writeTools, {
+                workspace: wt.dir,
+                sandboxMode: deps.sandboxMode,
+                trustWorkspace: deps.trustWorkspace,
+            }, new PermissionManager({ allow: ["write_file", "edit_file", "shell(*)"], deny: [] }, wt.dir), new SessionStore(wt.dir, true), []);
+            sub.maxSteps = writeMaxSteps;
+            // No human is watching this run (see the auto-allow comment above) —
+            // the forced unsandboxed-fallback warning must resolve on its own via
+            // the handler below rather than be raised at all.
+            sub.interactive = false;
+            sub.audit = deps.audit;
+            if (deps.tracer)
+                sub.tracer = deps.tracer;
+            if (deps.meter)
+                sub.meter = deps.meter;
+            sub.kill = deps.kill(); // see runReadOnlyAgent
+            sub.spanParent = deps.spanParent?.();
+            sub.spanAttributes = {
+                "kritya.subagent": true,
+                "kritya.subagent_write": true,
+                "kritya.subagent_task": task.slice(0, 120),
+                "kritya.subagent_branch": wt.branch,
+            };
+            await sub.runTurn(task, createSubagentHandlers({
+                onFinalText: (t) => (finalText = t),
+                requestPermission: async (_name, _summary, _diff, warning) => (warning ? "no" : "yes"),
+                onStep: onProgress,
+                stepInfo: () => ({ step: sub.stepIndex, max: sub.maxSteps }),
+            }), signal);
+            if (sub.hitStepLimit)
+                stoppedEarly = "max-steps";
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            runError = `the subagent stopped before finishing: ${message}`;
+            if (!finalText)
+                finalText = `(subagent stopped: ${message})`;
+        }
+        const commitState = commitWorktree(wt, `kritya subagent: ${task.slice(0, 72)}`);
+        deps.audit?.logTool({
+            tool: "subagent_worktree",
+            summary: `branch "${wt.branch}": commit ${commitState}`,
+            outcome: commitState === "failed" ? "error" : "ok",
+        });
+        if (commitState === "clean") {
+            const cleaned = removeWorktree(deps.workspace, wt, true);
+            const summary = finalText.trim() || "(no changes made)";
+            // Surface this rather than silently leave an empty orphaned branch: a
+            // failed `git branch -D` (e.g. a transient ref lock) shouldn't look
+            // identical to a subagent that genuinely made no changes.
+            return {
+                task,
+                write: true,
+                summary,
+                error: mergeErrors(runError, cleaned
+                    ? undefined
+                    : `made no changes, but its empty scratch branch "${wt.branch}" could not be ` +
+                        `auto-deleted (a transient git lock) — safe to remove manually with ` +
+                        `\`git branch -D ${wt.branch}\``),
+                ...(stoppedEarly ? { stoppedEarly } : {}),
+            };
+        }
+        if (commitState === "failed") {
+            // Don't discard the worktree: the subagent's edits are real work, even
+            // if a commit hook rejected them. Leave it on disk for manual recovery.
+            return {
+                task,
+                write: true,
+                summary: finalText.trim(),
+                error: mergeErrors(runError, "changes could not be committed (a commit hook may have rejected them) — " +
+                    `left uncommitted at ${wt.dir}`),
+                ...(stoppedEarly ? { stoppedEarly } : {}),
+            };
+        }
+        const diffstat = worktreeDiffStat(deps.workspace, wt);
+        removeWorktree(deps.workspace, wt, false);
+        return {
+            task,
+            write: true,
+            branch: wt.branch,
+            summary: `${finalText.trim() || "(no summary)"}${diffstat ? `\n\n${diffstat}` : ""}`,
+            error: runError,
+            ...(stoppedEarly ? { stoppedEarly } : {}),
+        };
+    }
+    async function runOneAgent(spec, parentSignal, onProgress) {
+        const controller = new AbortController();
+        const onParentAbort = () => controller.abort();
+        parentSignal?.addEventListener("abort", onParentAbort);
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        try {
+            const result = spec.write
+                ? await runWriteAgent(spec.task, controller.signal, onProgress)
+                : await runReadOnlyAgent(spec.task, controller.signal, onProgress);
+            if (result.error === undefined && result.stoppedEarly === undefined)
+                return result;
+            const aborted = abortOutcome({ timedOut, cancelled: parentSignal?.aborted === true });
+            // A step-cap stop is the agent asking for more room, not an abort, so
+            // only overwrite when this run was actually cut short.
+            if (aborted && (timedOut || parentSignal?.aborted === true))
+                return { ...result, ...aborted };
+            return result;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const aborted = abortOutcome({ timedOut, cancelled: parentSignal?.aborted === true });
+            return {
+                task: spec.task,
+                write: Boolean(spec.write),
+                summary: "",
+                error: aborted?.error ?? message,
+                ...(aborted ? { stoppedEarly: aborted.stoppedEarly } : {}),
+            };
+        }
+        finally {
+            clearTimeout(timer);
+            parentSignal?.removeEventListener("abort", onParentAbort);
+        }
+    }
+    return {
+        // Runs subagents concurrently, capped at `concurrency` at a time, so a
+        // burst of parallel tasks can't exhaust API rate limits or system resources.
+        async spawnAgents(specs, signal, onProgress) {
+            // Don't stand up worktrees and API calls for work that the shared kill
+            // switch would abort on its first step anyway.
+            if (deps.kill().active) {
+                return specs.map((s) => ({
+                    task: s.task,
+                    write: Boolean(s.write),
+                    summary: "",
+                    error: "not started — the kill switch is active",
+                }));
+            }
+            const results = new Array(specs.length);
+            let next = 0;
+            const workers = Array.from({ length: Math.min(concurrency, specs.length) }, async () => {
+                while (next < specs.length) {
+                    const i = next++;
+                    results[i] = await runOneAgent(specs[i], signal, (text) => onProgress?.(i, text));
+                    // Reported the moment it lands rather than only once the slowest
+                    // sibling finishes: a six-way batch is otherwise invisible for as
+                    // long as its slowest member takes.
+                    onProgress?.(i, `done — ${headline(results[i])}`);
+                }
+            });
+            await Promise.all(workers);
+            return results;
+        },
+    };
+}

package/dist/index.js

@@ -40,7 +40,7 @@ import { isBannerSeen, markBannerSeen } from "./trust/bannerSeen.js";
 import { partitionByTrust, serverFingerprint, trustServer } from "./trust/mcpTrust.js";
 import { runHeadless } from "./headless.js";
 import { installCrashHandlers } from "./crash.js";
-import { createWorktree, commitWorktree, worktreeDiffStat, removeWorktree, isGitRepo, } from "./agent/worktree.js";
+import { createSubagentRunner } from "./agent/subagents.js";
 import { VERSION } from "./version.js";
 import { updateNoticeForUser } from "./update/check.js";
 const USAGE = `kritya — a lean, provider-agnostic terminal coding agent
@@ -316,6 +316,8 @@ async function promptApiKeySetup(providerName, envVarName) {
 async function main() {
     const config = loadConfig();
     const privacyMode = args.privacy || privacyModeFor(config);
+    // The ASCII banner renders on every launch regardless — this only decides
+    // whether to also show the first-run "Try asking:" hints.
     const firstLaunch = !isBannerSeen(workspace);
     if (!isAiDisclosureShown(workspace)) {
         await showAiDisclosureNotice();
@@ -546,182 +548,31 @@ async function main() {
         ...nonRecursive(ALL_TOOLS),
         ...mcpTools.filter((t) => !t.requiresPermission),
     ];
-    // Hard caps so a runaway or hung subagent can't stall the session or burn
-    // unbounded API/compute: a wall-clock timeout per subagent, and a bound on
-    // how many run at once.
-    const SUBAGENT_TIMEOUT_MS = 10 * 60 * 1000;
-    const SUBAGENT_CONCURRENCY = 3;
-    function silentHandlers(onFinalText, requestPermission) {
-        return {
-            onTextDelta: () => { },
-            onReasoningDelta: () => { },
-            onAssistantText: onFinalText,
-            onToolStart: () => { },
-            onToolEnd: () => { },
-            requestPermission,
-            onUsage: () => { },
-        };
-    }
-    async function runReadOnlyAgent(task, signal) {
-        const sub = new Agent(client, () => modelRef.current, readOnlySubTools, { workspace, sandboxMode, trustWorkspace }, new PermissionManager([], workspace), new SessionStore(workspace, true), []);
-        sub.maxSteps = 15;
-        sub.audit = sessionAudit;
-        sub.tracer = sessionTracer;
-        sub.meter = sessionMeter;
-        // Share the parent's kill switch: a subagent with its own would keep
-        // running after the user stopped the session.
-        sub.kill = agent.kill;
-        sub.spanParent = agent.turnSpan;
-        sub.spanAttributes = { "kritya.subagent": true, "kritya.subagent_task": task.slice(0, 120) };
-        let finalText = "";
-        await sub.runTurn(task, 
-        // read-only tools never require permission, so this is never invoked
-        silentHandlers((t) => (finalText = t), async () => "no"), signal);
-        return { task, write: false, summary: finalText.trim() || "(subagent returned no findings)" };
-    }
-    async function runWriteAgent(task, signal) {
-        if (!isGitRepo(workspace)) {
-            return {
-                task,
-                write: true,
-                summary: "",
-                error: "the workspace is not a git repository, so an isolated worktree could not be created",
-            };
-        }
-        const wt = createWorktree(workspace);
-        if (!wt) {
-            sessionAudit?.logTool({
-                tool: "subagent_worktree",
-                summary: `worktree creation failed for task: ${task.slice(0, 72)}`,
-                outcome: "error",
-            });
-            return { task, write: true, summary: "", error: "failed to create an isolated git worktree" };
-        }
-        sessionAudit?.logTool({
-            tool: "subagent_worktree",
-            summary: `created branch "${wt.branch}" for task: ${task.slice(0, 72)}`,
-            outcome: "ok",
-        });
-        let finalText = "";
-        try {
-            // Auto-allow ordinary writes/edits/shell (no human is watching this run),
-            // but a destructive command still forces `warning` via classifyDanger in
-            // the agent loop regardless of the allowlist — fail-safe deny it there,
-            // since there's no one to confirm it and letting it run unattended would
-            // be unsafe even inside an isolated worktree (it still has real shell/
-            // network access).
-            const sub = new Agent(client, () => modelRef.current, writeSubTools, { workspace: wt.dir, sandboxMode, trustWorkspace }, new PermissionManager({ allow: ["write_file", "edit_file", "shell(*)"], deny: [] }, wt.dir), new SessionStore(wt.dir, true), []);
-            sub.maxSteps = 30;
-            // No human is watching this run (see the auto-allow comment above) —
-            // the forced unsandboxed-fallback warning must resolve on its own via
-            // the handler below rather than be raised at all.
-            sub.interactive = false;
-            sub.audit = sessionAudit;
-            sub.tracer = sessionTracer;
-            sub.meter = sessionMeter;
-            sub.kill = agent.kill; // see runReadOnlyAgent
-            sub.spanParent = agent.turnSpan;
-            sub.spanAttributes = {
-                "kritya.subagent": true,
-                "kritya.subagent_write": true,
-                "kritya.subagent_task": task.slice(0, 120),
-                "kritya.subagent_branch": wt.branch,
-            };
-            await sub.runTurn(task, silentHandlers((t) => (finalText = t), async (_name, _summary, _diff, warning) => (warning ? "no" : "yes")), signal);
-        }
-        catch (err) {
-            if (!finalText)
-                finalText = `(subagent stopped: ${err instanceof Error ? err.message : String(err)})`;
-        }
-        const commitState = commitWorktree(wt, `kritya subagent: ${task.slice(0, 72)}`);
-        sessionAudit?.logTool({
-            tool: "subagent_worktree",
-            summary: `branch "${wt.branch}": commit ${commitState}`,
-            outcome: commitState === "failed" ? "error" : "ok",
-        });
-        if (commitState === "clean") {
-            const cleaned = removeWorktree(workspace, wt, true);
-            const summary = finalText.trim() || "(no changes made)";
-            // Surface this rather than silently leave an empty orphaned branch: a
-            // failed `git branch -D` (e.g. a transient ref lock) shouldn't look
-            // identical to a subagent that genuinely made no changes.
-            return cleaned
-                ? { task, write: true, summary }
-                : {
-                    task,
-                    write: true,
-                    summary,
-                    error: `made no changes, but its empty scratch branch "${wt.branch}" could not be ` +
-                        `auto-deleted (a transient git lock) — safe to remove manually with ` +
-                        `\`git branch -D ${wt.branch}\``,
-                };
-        }
-        if (commitState === "failed") {
-            // Don't discard the worktree: the subagent's edits are real work, even
-            // if a commit hook rejected them. Leave it on disk for manual recovery.
-            return {
-                task,
-                write: true,
-                summary: finalText.trim(),
-                error: `changes could not be committed (a commit hook may have rejected them) — left uncommitted at ${wt.dir}`,
-            };
-        }
-        const diffstat = worktreeDiffStat(workspace, wt);
-        removeWorktree(workspace, wt, false);
-        return {
-            task,
-            write: true,
-            branch: wt.branch,
-            summary: `${finalText.trim() || "(no summary)"}${diffstat ? `\n\n${diffstat}` : ""}`,
-        };
-    }
-    async function runOneAgent(spec, parentSignal) {
-        const controller = new AbortController();
-        const onParentAbort = () => controller.abort();
-        parentSignal?.addEventListener("abort", onParentAbort);
-        const timer = setTimeout(() => controller.abort(), SUBAGENT_TIMEOUT_MS);
-        try {
-            return spec.write
-                ? await runWriteAgent(spec.task, controller.signal)
-                : await runReadOnlyAgent(spec.task, controller.signal);
-        }
-        catch (err) {
-            return {
-                task: spec.task,
-                write: Boolean(spec.write),
-                summary: "",
-                error: err instanceof Error ? err.message : String(err),
-            };
-        }
-        finally {
-            clearTimeout(timer);
-            parentSignal?.removeEventListener("abort", onParentAbort);
-        }
-    }
-    // Runs subagents concurrently, capped at SUBAGENT_CONCURRENCY at a time, so
-    // a burst of parallel tasks can't exhaust API rate limits or system resources.
-    const spawnAgents = async (specs, signal) => {
-        // Don't stand up worktrees and API calls for work that the shared kill
-        // switch would abort on its first step anyway.
-        if (agent.kill.active) {
-            return specs.map((s) => ({
-                task: s.task,
-                write: Boolean(s.write),
-                summary: "",
-                error: "not started — the kill switch is active",
-            }));
-        }
-        const results = new Array(specs.length);
-        let next = 0;
-        const workers = Array.from({ length: Math.min(SUBAGENT_CONCURRENCY, specs.length) }, async () => {
-            while (next < specs.length) {
-                const i = next++;
-                results[i] = await runOneAgent(specs[i], signal);
-            }
-        });
-        await Promise.all(workers);
-        return results;
-    };
+    // The runner itself lives in agent/subagents.ts. It used to be inline here,
+    // which put it out of reach of both the headless and Electron entry points
+    // (neither of which wires subagents at all as a result) and out of reach of
+    // the test suite, since dist/index.js is excluded from coverage.
+    const { spawnAgents } = createSubagentRunner({
+        client,
+        model: () => modelRef.current,
+        readOnlyTools: readOnlySubTools,
+        writeTools: writeSubTools,
+        workspace,
+        sandboxMode,
+        trustWorkspace,
+        audit: sessionAudit,
+        tracer: sessionTracer,
+        meter: sessionMeter,
+        // Read lazily: this runner is constructed before `agent` exists below.
+        kill: () => agent.kill,
+        spanParent: () => agent.turnSpan,
+        concurrency: config.subagentConcurrency,
+        timeoutMs: config.subagentTimeoutSeconds === undefined
+            ? undefined
+            : config.subagentTimeoutSeconds * 1000,
+        readMaxSteps: config.subagentMaxSteps,
+        writeMaxSteps: config.subagentWriteMaxSteps,
+    });
     const agent = new Agent(client, () => modelRef.current, tools, {
         workspace,
         sandboxMode,

package/dist/tools/subagent.js

@@ -1,3 +1,4 @@
+import { subagentStatusNote } from "../agent/subagents.js";
 const MAX_AGENTS = 6;
 /**
  * Dispatches one or more focused, read-only subtasks to fresh agents that each
@@ -31,7 +32,7 @@ export const spawnAgentTool = {
     // Self-managed: each subagent has its own wall-clock cap and the batch runs
     // several in sequence, so the total legitimately exceeds any per-tool limit.
     timeoutMs: 0,
-    async execute(args, ctx, signal) {
+    async execute(args, ctx, signal, onProgress) {
         const tasks = Array.isArray(args.tasks)
             ? args.tasks.map((t) => String(t).trim()).filter(Boolean)
             : [];
@@ -41,11 +42,20 @@ export const spawnAgentTool = {
             return `Error: at most ${MAX_AGENTS} tasks per call.`;
         if (!ctx.spawnAgents)
             return "Error: subagents are not available in this session.";
-        const results = await ctx.spawnAgents(tasks.map((task) => ({ task, write: false })), signal);
-        if (results.length === 1)
-            return results[0].summary;
+        const results = await ctx.spawnAgents(tasks.map((task) => ({ task, write: false })), signal, 
+        // The runner reports per-subagent status; the batch is what knows how
+        // many there are, so the "2/6" framing is added here.
+        (index, text) => onProgress?.(`subagent ${index + 1}/${tasks.length} · ${text}`));
+        if (results.length === 1) {
+            const note = subagentStatusNote(results[0]);
+            return note ? `${results[0].summary}\n\n${note}` : results[0].summary;
+        }
         return results
-            .map((r, i) => `--- Subagent ${i + 1}: ${r.task.slice(0, 60)} ---\n${r.summary}`)
+            .map((r, i) => {
+            const note = subagentStatusNote(r);
+            const header = `--- Subagent ${i + 1}: ${r.task.slice(0, 60)} ---`;
+            return note ? `${header}\n${r.summary}\n${note}` : `${header}\n${r.summary}`;
+        })
             .join("\n\n");
     },
     summarize: (args) => {

package/dist/tools/writeAgent.js

@@ -1,3 +1,4 @@
+import { subagentStatusNote } from "../agent/subagents.js";
 const MAX_AGENTS = 4;
 /**
  * Dispatches one or more subagents that can write files, edit files, and run
@@ -45,7 +46,7 @@ export const spawnWriteAgentTool = {
             tasks.map((t, i) => `  ${i + 1}. ${String(t).slice(0, 100)}`).join("\n") +
             `\n\nNone of this touches your working tree directly — review each branch's diff before merging.`);
     },
-    async execute(args, ctx, signal) {
+    async execute(args, ctx, signal, onProgress) {
         const tasks = Array.isArray(args.tasks)
             ? args.tasks.map((t) => String(t).trim()).filter(Boolean)
             : [];
@@ -55,17 +56,23 @@ export const spawnWriteAgentTool = {
             return `Error: at most ${MAX_AGENTS} tasks per call.`;
         if (!ctx.spawnAgents)
             return "Error: subagents are not available in this session.";
-        const results = await ctx.spawnAgents(tasks.map((task) => ({ task, write: true })), signal);
+        const results = await ctx.spawnAgents(tasks.map((task) => ({ task, write: true })), signal, 
+        // See subagent.ts — the batch owns the "2/4" framing, the runner reports status.
+        (index, text) => onProgress?.(`subagent ${index + 1}/${tasks.length} · ${text}`));
         return results
             .map((r, i) => {
             const header = `--- Write subagent ${i + 1}: ${r.task.slice(0, 60)} ---`;
-            if (r.error)
-                return `${header}\n${r.summary}\n[error: ${r.error}]`;
-            const branchNote = r.branch
-                ? `\n\nChanges committed to branch "${r.branch}". Review with ` +
-                    `\`git diff main...${r.branch}\` (or your base branch), merge with \`git merge ${r.branch}\`.`
-                : "\n\n(no file changes were made)";
-            return `${header}\n${r.summary}${branchNote}`;
+            const note = subagentStatusNote(r);
+            // A problem replaces the branch note rather than sitting next to it:
+            // telling someone to review a branch is wrong advice when the commit
+            // failed, or when the subagent never finished what it was doing.
+            const tail = note
+                ? `\n${note}`
+                : r.branch
+                    ? `\n\nChanges committed to branch "${r.branch}". Review with ` +
+                        `\`git diff main...${r.branch}\` (or your base branch), merge with \`git merge ${r.branch}\`.`
+                    : "\n\n(no file changes were made)";
+            return `${header}\n${r.summary}${tail}`;
         })
             .join("\n\n");
     },

package/dist/trust/bannerSeen.js

@@ -4,9 +4,13 @@ import { CONFIG_DIR } from "../config/config.js";
 import { hardenWindowsDir } from "../config/winAcl.js";
 import { debugLog } from "../config/debug.js";
 /**
- * Tracks which workspaces have already shown the full ASCII banner once, so
- * repeat launches (which cost real vertical space in a terminal) can fall
- * back to a compact one-line header instead. Same shape and persistence
+ * Tracks which workspaces have already been opened once.
+ *
+ * The full ASCII banner itself no longer consults this — it renders on every
+ * launch, because the compact one-line fallback it used to select made repeat
+ * launches look broken. What remains gated on it is the first-run
+ * "Try asking:" hint block in App.tsx, which is genuine onboarding text and
+ * would be noise on every subsequent launch. Same shape and persistence
  * pattern as aiDisclosure.ts's ai-disclosure.json.
  */
 const BANNER_FILE = path.join(CONFIG_DIR, "banner-seen.json");
@@ -22,11 +26,11 @@ function loadStore(storeFile) {
         return {};
     }
 }
-/** Whether the full ASCII banner has already been shown for this workspace. */
+/** Whether this workspace has been opened before (drives the first-run hints). */
 export function isBannerSeen(workspace, storeFile = BANNER_FILE) {
     return typeof loadStore(storeFile)[path.resolve(workspace)] === "string";
 }
-/** Record that the full ASCII banner has been shown for this workspace, now. */
+/** Record that this workspace has been opened, now. */
 export function markBannerSeen(workspace, storeFile = BANNER_FILE) {
     const store = loadStore(storeFile);
     store[path.resolve(workspace)] = new Date().toISOString();

package/dist/ui/App.js

@@ -123,7 +123,6 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
         resumeSessions,
         refreshFileList,
         onSwitchClient,
-        firstLaunch,
     });
     useEffect(() => {
         onRequestPermissionReady?.(requestPermission);

package/dist/ui/Banner.js

@@ -41,27 +41,37 @@ function letterOffsets(text, pixelLen) {
 function letterWidth(ch, pixelLen) {
     return (GLYPHS[ch] ?? GLYPHS["-"])[0].length * pixelLen;
 }
-// Vertical gradient: cyan at the top fading into NVIDIA green.
+// The banner's palette: cyan at the top of the glyphs fading into NVIDIA green.
 const TOP_RGB = [0x00, 0xd9, 0xff];
 const BOTTOM_RGB = [0x76, 0xb9, 0x00];
-function rowColor(row) {
-    const t = row / (ROWS - 1);
+/** One step of the cyan→green ramp, where t=0 is the cyan end and t=1 the green end. */
+function ramp(t) {
     const [r, g, b] = TOP_RGB.map((c, i) => Math.round(c + (BOTTOM_RGB[i] - c) * t));
     return `#${[r, g, b].map((c) => c.toString(16).padStart(2, "0")).join("")}`;
 }
+function rowColor(row) {
+    return ramp(row / (ROWS - 1));
+}
+/**
+ * The tagline walks the glyphs' own cyan→green ramp, but left-to-right instead
+ * of top-to-bottom, so it reads as the bottom edge of the same object rather
+ * than an unrelated third colour. Ink has no text gradient, so this is applied
+ * one character at a time.
+ */
+export function sweepColor(index, length) {
+    return ramp(length <= 1 ? 0 : index / (length - 1));
+}
 const BETA_LABEL = "beta";
 /** Product tagline shown under the banner on launch. */
 export const TAGLINE = "Superintelligence at your command line";
-export function Banner({ tagline, subtitle, compact, }) {
-    if (compact) {
-        return (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { dimColor: true, children: subtitle }) }));
-    }
+export function Banner({ tagline, subtitle }) {
     const columns = terminalColumns(process.stdout);
     const wide = bannerLines("KRITYA", "░░");
     const narrow = bannerLines("KRITYA", "░");
     const pixelLen = wide[0].length <= columns ? 2 : narrow[0].length <= columns ? 1 : 0;
     const lines = pixelLen === 2 ? wide : pixelLen === 1 ? narrow : null;
-    const center = (text) => " ".repeat(Math.max(0, Math.floor((columns - text.length) / 2))) + text;
+    const pad = (text) => " ".repeat(Math.max(0, Math.floor((columns - text.length) / 2)));
+    const center = (text) => pad(text) + text;
     // Right-align "beta" under the final "A" of KRITYA, one line below the glyph.
     const betaLine = (() => {
         if (!lines)
@@ -72,5 +82,5 @@ export function Banner({ tagline, subtitle, compact, }) {
         const indent = leftPad + aStart + Math.max(0, aWidth - BETA_LABEL.length);
         return " ".repeat(indent) + BETA_LABEL;
     })();
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 2, marginBottom: 1, children: [lines ? (lines.map((line, i) => (_jsx(Text, { color: rowColor(i), children: center(line) }, i)))) : (_jsx(Text, { bold: true, color: "cyan", children: center("KRITYA") })), betaLine ? _jsx(Text, { dimColor: true, children: betaLine }) : null, tagline ? _jsx(Text, { children: center(tagline) }) : null, _jsx(Box, { marginTop: 2, children: subtitle ? _jsx(Text, { dimColor: true, children: center(subtitle) }) : null }), _jsx(Text, { dimColor: true, children: center("AI can make mistakes. Verify important output.") })] }));
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 2, marginBottom: 1, children: [lines ? (lines.map((line, i) => (_jsx(Text, { color: rowColor(i), children: center(line) }, i)))) : (_jsx(Text, { bold: true, color: "cyan", children: center("KRITYA") })), betaLine ? _jsx(Text, { dimColor: true, children: betaLine }) : null, tagline ? (_jsxs(Text, { children: [pad(tagline), [...tagline].map((ch, i) => (_jsx(Text, { color: sweepColor(i, tagline.length), children: ch }, i)))] })) : null, _jsx(Box, { marginTop: 2, children: subtitle ? _jsx(Text, { dimColor: true, children: center(subtitle) }) : null }), _jsx(Text, { dimColor: true, children: center("AI can make mistakes. Verify important output.") })] }));
 }

package/dist/ui/TranscriptItem.js

@@ -10,5 +10,5 @@ export function TranscriptItem({ item, verbose, contentWidth }) {
     return (_jsxs(Box, { marginBottom: item.kind === "tool" ? 0 : 1, flexDirection: "column", children: [item.kind === "user" && (_jsxs(Text, { children: [_jsxs(Text, { bold: true, color: "green", children: ["\u276F", " "] }), item.text] })), item.kind === "assistant" && _jsx(Markdown, { text: item.text, width: contentWidth }), item.kind === "tool" && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { dimColor: true, children: [item.error ? _jsx(Text, { color: "red", children: "\u2717" }) : _jsx(Text, { color: "green", children: "\u2713" }), " ", item.summary, item.resultSummary && !verbose ? ` — ${item.resultSummary}` : ""] }), item.output && item.output.trim() && (item.resultSummary === undefined || verbose) && (_jsx(Text, { dimColor: true, children: toolOutputPreview(item.output, verbose, Math.max(20, contentWidth - TOOL_INDENT), item.error)
                             .split("\n")
                             .map((l) => `    ${l}`)
-                            .join("\n") }))] })), item.kind === "info" && _jsx(Text, { dimColor: true, children: item.text }), item.kind === "banner" && (_jsx(Banner, { tagline: item.tagline, subtitle: item.subtitle, compact: item.compact })), item.kind === "summary" && (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "green", paddingX: 1, children: [_jsx(Text, { bold: true, color: "green", children: "\u2713 Completed" }), item.files.length > 0 ? (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Changed:" }), item.files.map((f) => (_jsxs(Text, { children: [" ", f] }, f)))] })) : (_jsx(Text, { dimColor: true, children: "No files changed." })), _jsxs(Text, { dimColor: true, children: ["Next: ", item.nextStep] })] }))] }));
+                            .join("\n") }))] })), item.kind === "info" && _jsx(Text, { dimColor: true, children: item.text }), item.kind === "banner" && _jsx(Banner, { tagline: item.tagline, subtitle: item.subtitle }), item.kind === "summary" && (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "green", paddingX: 1, children: [_jsx(Text, { bold: true, color: "green", children: "\u2713 Completed" }), item.files.length > 0 ? (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Changed:" }), item.files.map((f) => (_jsxs(Text, { children: [" ", f] }, f)))] })) : (_jsx(Text, { dimColor: true, children: "No files changed." })), _jsxs(Text, { dimColor: true, children: ["Next: ", item.nextStep] })] }))] }));
 }

package/dist/ui/useAgent.js

@@ -45,7 +45,7 @@ function initialToolStatus(name) {
  * permission state, usage/cost tracking, and session resume. Input handling
  * (text box, slash-command suggestions, @mention autocomplete) stays in App.
  */
-export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBridge, resumedCount, initialTasks, resumeSessions, refreshFileList, onSwitchClient, firstLaunch, }) {
+export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBridge, resumedCount, initialTasks, resumeSessions, refreshFileList, onSwitchClient, }) {
     const nextId = useRef(0);
     const [items, setItems] = useState(() => {
         const initial = [
@@ -54,7 +54,6 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
                 kind: "banner",
                 tagline: TAGLINE,
                 subtitle: `${path.basename(workspace)} · ${modelRef.current} · type a request, or /help for commands`,
-                compact: !firstLaunch,
             },
         ];
         if (resumedCount > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kritya",
-  "version": "0.8.29-beta",
+  "version": "0.8.31-beta",
   "description": "Kritya — Superintelligence at your command line",
   "type": "module",
   "publishConfig": {