@proagentstore/cli 0.4.54 → 0.4.56

package/dist/browser-runner/apply-outcome.js

@@ -0,0 +1,70 @@
+/**
+ * Every outcome `/browser/complete` can be called with, and what it means locally.
+ *
+ * Only `cancelled` changed in #636. The rest are the behaviour that was already there, written
+ * down: `blocked` stays its own status because the agent stopped and needs the USER (email
+ * verification, something it cannot answer truthfully) — needs-attention, not a failure, and
+ * the console shows it as an active ticket rather than burying it.
+ *
+ * `captcha`/`stuck`/`needs_input` reach here only through the workflow's handoff TIMEOUT,
+ * which calls this endpoint with `failed` and a "… not resolved in time" detail — so their
+ * rows are a backstop for a direct call. They are `failed` because `TaskStatus` has no
+ * `escalated`, which is what the cloud's run record calls them; the honest local equivalent
+ * would be `needs_human`, but a task in that state is not finished, and every call to this
+ * method IS the finish. Left as-is deliberately rather than changed under an unrelated fix.
+ */
+export const APPLY_OUTCOME_DISPOSITION = {
+    submitted: { status: "completed", event: "task.completed", error: false },
+    ready: { status: "completed", event: "task.completed", error: false },
+    expired: { status: "completed", event: "task.completed", error: false },
+    blocked: { status: "blocked", event: "task.failed", error: true },
+    captcha: { status: "failed", event: "task.failed", error: true },
+    stuck: { status: "failed", event: "task.failed", error: true },
+    needs_input: { status: "failed", event: "task.failed", error: true },
+    failed: { status: "failed", event: "task.failed", error: true },
+    max_steps: { status: "failed", event: "task.failed", error: true },
+    cancelled: { status: "cancelled", event: "task.cancelled", error: false },
+};
+/**
+ * The disposition for an outcome off the wire.
+ *
+ * `outcome` is a string from an HTTP body: a newer cloud can send one this bundled runner has
+ * never heard of, since the runner ships inside a CLI the user upgrades on their own schedule.
+ * An unknown outcome falls back to `failed` — the same `?? "failed"` the cloud's
+ * `browserRunStopReason` uses — because "something ended and I cannot say it went well" is the
+ * only honest reading of a word this build does not know.
+ */
+export function dispositionForOutcome(outcome) {
+    return APPLY_OUTCOME_DISPOSITION[outcome] ?? APPLY_OUTCOME_DISPOSITION.failed;
+}
+/**
+ * Write a finished run's outcome onto the task, and name the event to append.
+ *
+ * Pure apart from the mutation of the task it is handed, so the whole disposition — status,
+ * error-or-not, which event — is decided in one tested place instead of inside a method that
+ * also detaches CDP sessions and closes pages.
+ */
+export function settleTaskOutcome(task, outcome, detail) {
+    const disposition = dispositionForOutcome(outcome);
+    task.status = disposition.status;
+    task.output = { outcome, detail };
+    if (disposition.error)
+        task.error = detail || outcome;
+    task.updatedAt = new Date().toISOString();
+    task.completedAt = task.updatedAt;
+    return disposition;
+}
+/**
+ * The statuses a task cannot be moved out of — what `cancelTask` refuses to overwrite.
+ *
+ * `blocked` is deliberately NOT here: a blocked task is waiting on the owner, and Stop is the
+ * owner answering. `cancelled` IS here, and was the member the old `completed || failed` pair
+ * missed (#636) — a second Stop rewrote the timestamps and appended a duplicate
+ * `task.cancelled`. `completed` and `failed` stay untouchable in the other direction: a run
+ * that genuinely finished must not be relabelled as cancelled, because it was not.
+ */
+export const TERMINAL_TASK_STATUSES = ["completed", "failed", "cancelled"];
+/** Has this task already finished, whichever way it finished? */
+export function isTerminalTaskStatus(status) {
+    return TERMINAL_TASK_STATUSES.includes(status);
+}

package/dist/browser-runner/coding/engine-env.js

@@ -0,0 +1,46 @@
+/**
+ * What environment the Engine's process actually gets.
+ *
+ * Extracted from `headless.ts` when #679 added the second decision made at this seam. There are
+ * now two, they are asked at the same three call sites (both spawns and `authResolved`), and
+ * `headless.ts` sat one line under its size pin — so the concern gets a file rather than the pin
+ * getting a raise. `engine-auth.ts` READS this env; this builds it.
+ *
+ *  1. {@link mergeEnv} — the platform's overlay over the machine's, where empty means REMOVE.
+ *  2. {@link engineSpawnEnv} — that, plus the `gh` guard ahead of the real binary on `PATH`.
+ */
+import { ghGuardEnv } from "./gh-guard.js";
+/**
+ * Merge the platform's resolved engine env over the machine's, where an EMPTY value means
+ * REMOVE rather than "set to empty".
+ *
+ * Needed because the machine env is inherited wholesale: a developer with ANTHROPIC_API_KEY in
+ * their shell handed it to every engine, and Claude Code prefers an API key over the
+ * subscription token — so choosing "subscription" injected CLAUDE_CODE_OAUTH_TOKEN and then
+ * silently lost, billing per token anyway. Without a way to express removal the setting could
+ * not mean what it said.
+ */
+export function mergeEnv(base, overlay) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(overlay ?? {})) {
+        if (v === "")
+            delete out[k];
+        else
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * The env a turn is spawned with: the merged env, with the `gh` write guard on `PATH` when the
+ * platform named a scope for this session (#679).
+ *
+ * ONE expression, called everywhere the question is asked — including `authResolved`, whose whole
+ * contract is that it reports the env the next turn is spawned with rather than the configured
+ * intent. Two expressions here is how that guarantee quietly stops being true.
+ *
+ * `ghGuardEnv` returns its input untouched whenever the guard cannot be installed, so this is safe
+ * in front of every spawn: the failure mode is the machine's own `gh`, never a missing one.
+ */
+export function engineSpawnEnv(overlay, ghScope, ghGuardRoot) {
+    return ghGuardEnv(mergeEnv(process.env, overlay), ghScope, ghGuardRoot);
+}

package/dist/browser-runner/coding/gh-guard.js

@@ -0,0 +1,272 @@
+/**
+ * Containment for the Engine's `gh` writes (#679, absorbing #676).
+ *
+ * ── The defect
+ *
+ * `headless.ts` spawns the Engine with `env: mergeEnv(process.env, this.config.env)` — twice, at
+ * the persistent stream-json spawn and again in `runOneShot`. The Engine therefore inherits the
+ * machine's ENTIRE environment, and with it whatever `git` and `gh` credentials that machine
+ * holds. `coding_diagnostics` has been saying so out loud since #676:
+ *
+ *     "A write naming a repository outside this list halts the run and is recorded. The first such
+ *      write still LANDS — the engine uses this machine's own git and gh credentials, which are
+ *      not scoped."
+ *
+ * Detection after the fact is not containment. This is the containment half.
+ *
+ * ── What this is, and what it deliberately is NOT
+ *
+ * It is an **allowlist gate on `gh`**, installed as a shim earlier on the Engine's `PATH` than the
+ * real binary. A `gh` invocation whose verb is in the closed write vocabulary AND which names a
+ * repository outside this session's registered scope is refused before it runs, with the refused
+ * repository in stderr. Everything else — every read, every write to the session's own repo — is
+ * `exec`'d straight through to the real `gh`, on the machine's own credentials, unchanged.
+ *
+ * It is **not a credential broker**, and the sketch's "route a repo-scoped installation token for
+ * the allowed case" half is deliberately rejected:
+ *
+ *  - The token that would be routed is a GitHub-App installation token minted in the cloud
+ *    (`workers/api/src/lib/git-credentials.ts`) and delivered once at session start, for the
+ *    clone. It lives about an hour; a coding session does not. Swapping the machine's working
+ *    login for it would turn a containment feature into an outage partway through long runs.
+ *  - It would BREAK the one property this ticket says must survive: a cross-repo `gh pr view
+ *    --repo <another org>/<repo>` is a different installation, so an installation token cannot
+ *    read it. The machine's own login can, and does today.
+ *  - It buys nothing. The harm is the wrong-repo write LANDING, and refusing to exec stops that
+ *    strictly earlier than handing over a credential that would have failed.
+ *
+ * It is also **not a change to the machine's git configuration.** No `insteadOf`, no
+ * `credential.helper`, no `GIT_SSH_COMMAND`. The owner drives his own work through a custom
+ * `github-personal` SSH host alias, and forcing https to gate an agent would take over
+ * configuration he uses personally.
+ *
+ * ── What remains open, and is stated rather than hidden
+ *
+ *  1. **`git push` is not gated at all.** Remotes here are SSH (`git@github-personal:…`), and
+ *     `repo.ts` says why in code: *"Only https carries a credential: git ignores userinfo on an
+ *     ssh URL"*. There is no token to withhold, so no credential decision can reach it.
+ *  2. **A `PATH` shim is bypassable.** `/opt/homebrew/bin/gh` skips it entirely, and the Engine
+ *     has been observed re-exporting its own environment (`export GH_CONFIG_DIR=…`). This raises
+ *     the cost of a wrong-repo write; it does not make one impossible.
+ *  3. **`gh api graphql` is not classified.** A mutation could travel in the query text, and
+ *     deciding that would mean pattern-matching free prose — the judgement this codebase refuses
+ *     to make in a gate, because a false positive that halts a run costs more than the finding.
+ *     Explicit `gh api --method POST|PATCH|PUT|DELETE` with a `/repos/{owner}/{repo}` path IS
+ *     classified.
+ *  4. **A write that names no repository is not gated.** `gh` then resolves the target from the
+ *     working directory's remote, which the shim cannot see without running git itself. In a
+ *     session that is the workdir the platform registered — but the Engine has a shell, so `cd`
+ *     into another checkout on this machine reaches that repository instead. Refusing every
+ *     unqualified write was rejected: it is the ordinary shape of `gh pr create` inside the repo
+ *     the session owns, so it would break the common case to narrow an uncommon one.
+ *
+ * All three are reported through {@link ghGuardReport} → `coding_diagnostics`, which is where the
+ * `enforcement: "acts-observed-halt"` value they replace used to be. A gate that overstates itself
+ * is worse than no gate.
+ */
+import { createHash } from "node:crypto";
+import { accessSync, constants, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * The closed WRITE vocabulary — `<command> <subcommand>` pairs that change something on GitHub.
+ *
+ * A denylist rather than an allowlist, which inverts `repo-write.ts`'s shape, and the inversion is
+ * the point rather than an oversight: `gh`'s read surface is enormous and open-ended (`gh api`,
+ * `gh run`, `gh release download`, `gh search`, third-party extensions), so an allowlist of reads
+ * would refuse working commands nobody enumerated and the Engine would be broken in ways that look
+ * like the platform, not like a policy. What has to be complete here is the list of verbs that
+ * WRITE, and that list is small, stable and reviewable. Adding to it is a code review.
+ *
+ * `gh gist` is absent on purpose: a gist belongs to no repository, so there is nothing to scope it
+ * against and refusing it would be theatre.
+ */
+export const GH_WRITE_VERBS = [
+    "pr create", "pr merge", "pr close", "pr reopen", "pr edit", "pr comment", "pr review", "pr ready", "pr lock", "pr unlock",
+    "issue create", "issue close", "issue reopen", "issue edit", "issue comment", "issue delete", "issue lock", "issue unlock", "issue pin", "issue unpin", "issue transfer",
+    "release create", "release delete", "release edit", "release upload",
+    "repo create", "repo delete", "repo edit", "repo rename", "repo archive", "repo unarchive", "repo sync", "repo fork", "repo deploy-key",
+    "workflow enable", "workflow disable", "workflow run",
+    "run cancel", "run rerun", "run delete",
+    "secret set", "secret delete",
+    "variable set", "variable delete",
+    "label create", "label delete", "label edit", "label clone",
+    "cache delete",
+    "ruleset check",
+];
+/** The exit status the shim refuses with — distinct from `gh`'s own 1, so a refusal is telling. */
+export const GH_REFUSED_EXIT = 3;
+/** The marker a refusal always carries, so the reason is greppable in a pane full of tool output. */
+export const GH_REFUSED_MARKER = "pags: refused";
+/** Where the generated shims live. Under the runner's existing config root, not a new location. */
+export function ghGuardRoot() {
+    return join(homedir(), ".config", "proagentstore", "gh-guard");
+}
+/** `owner/repo`, lower-cased, with any `host/` prefix or `.git` suffix removed. */
+export function normalizeRepo(raw) {
+    const parts = raw
+        .trim()
+        .replace(/^https?:\/\//i, "")
+        .replace(/\.git$/i, "")
+        .split("/")
+        .filter(Boolean);
+    return parts.slice(-2).join("/").toLowerCase();
+}
+/**
+ * The `gh` the shim delegates to: the first executable named `gh` on `path`, skipping anything
+ * under `guardRoot` — otherwise a shim installed on a previous spawn could be resolved as the
+ * "real" one and the second generation would exec the first, forever.
+ */
+export function findRealGh(path, guardRoot) {
+    for (const dir of (path ?? "").split(":")) {
+        if (!dir || (guardRoot && dir.startsWith(guardRoot)))
+            continue;
+        const candidate = join(dir, "gh");
+        try {
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            /* not here, or not executable — keep looking */
+        }
+    }
+    return null;
+}
+/**
+ * The shim itself, as text.
+ *
+ * POSIX `sh` and not a Node script, because this runs on every `gh` the Engine invokes and it must
+ * not depend on resolving a module out of a bundle whose layout differs between the monorepo
+ * (`src/*.ts` under tsx) and the published CLI (`dist/browser-runner/*.js`). The logic is small
+ * enough to be read in one screen, and its tests execute THIS text rather than a TypeScript twin
+ * of it — so what is verified is the artifact that ships.
+ *
+ * Every unclassified path ends in `exec`, so a bug here degrades to today's behaviour rather than
+ * to a broken `gh`.
+ */
+export function renderGhShim(opts) {
+    const scope = opts.scope.map(normalizeRepo).filter(Boolean).join(" ");
+    // `case` patterns, one per write verb. Generated from the constant so the shim and the
+    // reviewable list can never disagree.
+    const verbs = GH_WRITE_VERBS.map((v) => `    ${sq(v)}) write=1 ;;`).join("\n");
+    return `#!/bin/sh
+# ProAgentStore gh guard (#679) — GENERATED. Source of truth:
+# packages/browser-runner/src/coding/gh-guard.ts. Editing this file widens what the agent may
+# write to; that is a bypass, not a configuration.
+REAL=${sq(opts.realGh)}
+SCOPE=${sq(scope)}
+
+cmd=""; sub=""; repo=""; method=""; want=""
+for a in "$@"; do
+  if [ "$want" = "repo" ]; then repo="$a"; want=""; continue; fi
+  if [ "$want" = "method" ]; then method="$a"; want=""; continue; fi
+  case "$a" in
+    --repo=*) repo=\${a#--repo=} ;;
+    --method=*) method=\${a#--method=} ;;
+    -R|--repo) want="repo" ;;
+    -X|--method) want="method" ;;
+    -*) : ;;
+    *) if [ -z "$cmd" ]; then cmd="$a"; elif [ -z "$sub" ]; then sub="$a"; fi ;;
+  esac
+done
+
+write=0
+case "$cmd $sub" in
+${verbs}
+esac
+# \`gh api\` is the generic escape hatch: only an explicitly mutating method counts, and the target
+# comes out of the /repos/{owner}/{repo} path. \`gh api graphql\` is NOT classified — see the module.
+if [ "$cmd" = "api" ]; then
+  m=$(printf '%s' "$method" | tr '[:lower:]' '[:upper:]')
+  case "$m" in POST|PATCH|PUT|DELETE) write=1 ;; esac
+  if [ -z "$repo" ]; then
+    repo=$(printf '%s' "$sub" | sed -n 's|^/\\{0,1\\}repos/\\([^/]*\\)/\\([^/]*\\).*|\\1/\\2|p')
+  fi
+fi
+
+if [ "$write" = "1" ] && [ -n "$repo" ]; then
+  want_repo=$(printf '%s' "$repo" | sed 's|^https\\{0,1\\}://||; s|\\.git$||' | awk -F/ '{ if (NF>1) print $(NF-1)"/"$NF; else print $0 }' | tr '[:upper:]' '[:lower:]')
+  allowed=0
+  for r in $SCOPE; do
+    if [ "$r" = "$want_repo" ]; then allowed=1; fi
+  done
+  if [ "$allowed" = "0" ]; then
+    echo "${GH_REFUSED_MARKER}: \\\`gh $cmd $sub\\\` writes to $want_repo, which this agent session is not registered for (allowed: $SCOPE)." >&2
+    echo "Ask the owner to register that repository with the agent, or do the write in a session that owns it. Reads are not affected." >&2
+    exit ${GH_REFUSED_EXIT}
+  fi
+fi
+
+exec "$REAL" "$@"
+`;
+}
+/** Single-quote for `sh`: the only character that needs care inside `'…'` is `'` itself. */
+function sq(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** The gaps, in one place, so the runner and `coding_diagnostics` cannot drift apart. */
+export const GH_GUARD_GAPS = [
+    "`git push` is not gated — this machine's remotes are SSH, so there is no credential to withhold.",
+    "A PATH shim is bypassable: invoking `/opt/homebrew/bin/gh` by absolute path, or re-exporting PATH, skips it.",
+    "`gh api graphql` is not classified — a mutation can travel inside the query text.",
+    "A write with no `--repo` is not gated: gh resolves the target from the working directory, so a `cd` into another checkout on this machine reaches it.",
+];
+/** Report for a session with no guard installed. */
+export function ghGuardReport(scope, reason) {
+    return { installed: !reason, scope, ...(reason ? { reason } : {}), gaps: [...GH_GUARD_GAPS] };
+}
+/** Installed shims, keyed by (scope, real gh) — writing the same file per turn would be silly. */
+const installed = new Map();
+/**
+ * Install (idempotently) a shim for `scope` and return its directory, or `null` with the reason.
+ *
+ * Keyed by a hash of what the shim CONTAINS, so a scope change lands in a different directory and
+ * a stale shim can never be handed a scope it was not generated for.
+ */
+export function installGhGuard(scope, env, root = ghGuardRoot()) {
+    const repos = scope.map(normalizeRepo).filter(Boolean);
+    // No scope is not "allow nothing" — it is "the platform did not say", and a guard that refused
+    // every write on that basis would break every session an older cloud starts.
+    if (repos.length === 0)
+        return { reason: "no-scope" };
+    const realGh = findRealGh(env.PATH, root);
+    if (!realGh)
+        return { reason: "gh-not-found" };
+    const script = renderGhShim({ realGh, scope: repos });
+    const key = createHash("sha256").update(`${root}${script}`).digest("hex").slice(0, 16);
+    const cached = installed.get(key);
+    if (cached)
+        return { dir: cached };
+    const dir = join(root, key);
+    try {
+        mkdirSync(dir, { recursive: true });
+        const shim = join(dir, "gh");
+        if (!existsSync(shim))
+            writeFileSync(shim, script, { mode: 0o755 });
+        installed.set(key, dir);
+        return { dir };
+    }
+    catch {
+        // Fail OPEN and say so. A runner that cannot write to its own config dir must still be able
+        // to run the Engine; silently producing a `gh` that does not exist would be far worse.
+        return { reason: "install-failed" };
+    }
+}
+/**
+ * The Engine's spawn env, with the guard ahead of the real `gh` on `PATH`.
+ *
+ * Returns `env` untouched whenever the guard could not be installed, which is what makes this safe
+ * to put in front of every spawn: the failure mode is today's behaviour, never a broken `gh`.
+ */
+export function ghGuardEnv(env, scope, root) {
+    const out = installGhGuard(scope ?? [], env, root);
+    if (!("dir" in out))
+        return env;
+    return { ...env, PATH: `${out.dir}:${env.PATH ?? ""}` };
+}
+/** What to report for a session started with `scope`, derived from the same call the spawn made. */
+export function ghGuardStatus(scope, env, root) {
+    const repos = (scope ?? []).map(normalizeRepo).filter(Boolean);
+    const out = installGhGuard(scope ?? [], env, root);
+    return "dir" in out ? ghGuardReport(repos) : ghGuardReport(repos, out.reason);
+}

package/dist/browser-runner/coding/headless.js

@@ -2,26 +2,10 @@ import { spawn } from "node:child_process";
 import { classifyCommand, commandFromToolInput, fillTargetFromResult, toolCallOk, toolResultMark } from "./engine-acts.js";
 import { parseEngineUsage } from "./engine-usage.js";
 import { turnReportFromExit, turnReportFromResult } from "./engine-turn.js";
-/**
- * Merge the platform's resolved engine env over the machine's, where an EMPTY value means
- * REMOVE rather than "set to empty".
- *
- * Needed because the machine env is inherited wholesale: a developer with ANTHROPIC_API_KEY in
- * their shell handed it to every engine, and Claude Code prefers an API key over the
- * subscription token — so choosing "subscription" injected CLAUDE_CODE_OAUTH_TOKEN and then
- * silently lost, billing per token anyway. Without a way to express removal the setting could
- * not mean what it said.
- */
-export function mergeEnv(base, overlay) {
-    const out = { ...base };
-    for (const [k, v] of Object.entries(overlay ?? {})) {
-        if (v === "")
-            delete out[k];
-        else
-            out[k] = v;
-    }
-    return out;
-}
+import { renderToolResult, shortInput, stripAnsi } from "./transcript-lines.js";
+import { authoredTurn, authorTag } from "./turn-author.js";
+import { engineSpawnEnv, mergeEnv } from "./engine-env.js";
+import { ghGuardStatus } from "./gh-guard.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { handlerFor } from "./handlers.js";
@@ -115,6 +99,15 @@ export class HeadlessSession {
      * damages the record exactly as much as missing a real one.
      */
     awaitingResult = new Map();
+    /**
+     * `tool_use_id` → tool name, for the ONE decision the result event cannot make on its own: how
+     * much of it reaches the pane (#700, `toolResultBudget` in `transcript-lines.ts`).
+     *
+     * Separate from {@link awaitingResult}, which holds only the small minority of calls that
+     * classify as consequential acts. Entries are deleted when their result arrives and the whole
+     * map is cleared at the turn boundary, where a call that never got one is known never to.
+     */
+    toolNames = new Map();
     /** Turn counter — only used to build a fallback id when the CLI's event has no `uuid`. */
     usageSeq = 0;
     /**
@@ -163,7 +156,15 @@ export class HeadlessSession {
      * Presence only: no key or token value leaves this class.
      */
     get authResolved() {
-        return resolveEngineAuth(this.config.clientType, mergeEnv(process.env, this.config.env));
+        return resolveEngineAuth(this.config.clientType, this.spawnEnv);
+    }
+    /** The env every turn is spawned with — one expression, three call sites. See engine-env.ts. */
+    get spawnEnv() {
+        return engineSpawnEnv(this.config.env, this.config.ghScope, this.config.ghGuardRoot);
+    }
+    /** What the `gh` guard actually did on this machine (#679) — reported, never assumed. */
+    get ghGuard() {
+        return ghGuardStatus(this.config.ghScope, mergeEnv(process.env, this.config.env), this.config.ghGuardRoot);
     }
     /**
      * Did this engine launch with a conversation to continue (#408)?
@@ -334,7 +335,7 @@ export class HeadlessSession {
         const args = this.mode === "stream-json" ? buildClaudeArgs(this.cmdArgs, this.claudeSessionId) : [...this.cmdArgs];
         const proc = spawn(this.cmdBin, args, {
             cwd: this.config.workDir,
-            env: mergeEnv(process.env, this.config.env),
+            env: this.spawnEnv,
             stdio: ["pipe", "pipe", "pipe"],
         });
         this.proc = proc;
@@ -376,11 +377,13 @@ export class HeadlessSession {
             }
         });
     }
-    /** Send a user turn to the agent (it acts on it). */
-    input(text) {
+    /** Send a user turn. `author` names who wrote it, because `role` cannot — see turn-author.ts (#505). */
+    input(text, opts = {}) {
+        // The Engine reads the preamble, the pane the short marker; the instruction stays evidence.
+        const sent = authoredTurn(text, opts.author);
         if (!this.alive)
             this.start();
-        this.push(`\n❯ [${stamp()}] ${text}`); // ❯ — your turn, timestamped
+        this.push(`\n❯ [${stamp()}] ${authorTag(opts.author)}${text}`); // ❯ — your turn, timestamped
         this.run = "thinking";
         const now = Date.now();
         this.lastOutputAt = now;
@@ -388,13 +391,15 @@ export class HeadlessSession {
         this.sawOutputSinceInput = false; // arm the persistent-raw idle heuristic for THIS turn
         try {
             if (this.mode === "stream-json") {
-                const msg = JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text }] } });
+                // `role` stays "user" — the only role this protocol accepts, which is why the
+                // disambiguation rides in the text instead (#505).
+                const msg = JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text: sent }] } });
                 this.proc?.stdin?.write(`${msg}\n`);
             }
             else {
                 // Raw CLI: spawn THIS turn. See `oneShot` — there is no persistent process to
                 // write to, because a non-interactive binary would never have read it.
-                this.runOneShot(text);
+                this.runOneShot(sent);
             }
         }
         catch {
@@ -422,7 +427,7 @@ export class HeadlessSession {
         this.turnLastLine = "";
         const proc = spawn(this.cmdBin, [...this.cmdArgs, text], {
             cwd: this.config.workDir,
-            env: mergeEnv(process.env, this.config.env),
+            env: this.spawnEnv,
             stdio: ["ignore", "pipe", "pipe"],
         });
         // A turn already running is aborted before its replacement starts: `input()` accepts a turn
@@ -597,7 +602,13 @@ export class HeadlessSession {
                         this.push(`[${stamp()}] ${block.text.trim()}`); // timestamped agent reply
                     }
                     else if (block.type === "tool_use") {
-                        this.push(`⚙ ${String(block.name ?? "tool")} ${shortInput(block.input)}`); // ⚙
+                        const name = String(block.name ?? "tool");
+                        this.push(`⚙ ${name} ${shortInput(block.input)}`); // ⚙
+                        // The result arrives in a LATER event carrying only `tool_use_id`, and how much
+                        // of it reaches the pane depends on which tool it was (#700) — so the name is
+                        // remembered here and read back in `settleAct`'s sibling branch below.
+                        if (typeof block.id === "string" && block.id)
+                            this.toolNames.set(block.id, name);
                         this.noteAct(block);
                     }
                 }
@@ -605,7 +616,12 @@ export class HeadlessSession {
             case "user": // tool results come back as a synthetic user message
                 for (const block of ev.message?.content ?? []) {
                     if (block.type === "tool_result") {
-                        this.push(`  ↳${toolResultMark(block)} ${toolResult(block.content)}`); // ↳✓ / ↳✗ (#597)
+                        const id = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+                        // `""` when the call was not seen (a pane that began mid-turn, a runner restart):
+                        // an unknown tool takes the conservative budget rather than the generous one.
+                        const tool = this.toolNames.get(id) ?? "";
+                        this.toolNames.delete(id);
+                        this.push(renderToolResult(toolResultMark(block), block.content, tool)); // ↳✓ / ↳✗ (#597)
                         this.settleAct(block);
                     }
                 }
@@ -633,13 +649,16 @@ export class HeadlessSession {
                 // never saw whether it worked" is a materially different claim from silence, and
                 // silence is what a supervisor would read as "it did nothing".
                 this.flushAwaitingActs();
+                this.toolNames.clear(); // no further result is coming for anything still named here
                 this.run = "idle"; // the turn is OVER — a fact, not a guess
                 break;
             }
             default:
                 break;
         }
-        // Keep the in-memory transcript bounded.
+        // Keep the in-memory transcript bounded. Counts ENTRIES, and an entry may now be a
+        // multi-line block (a result, or a long assistant reply) rather than one line — the
+        // character bound that matters is `MAX_PANE` in runtime.ts, applied on the way out.
         if (this.transcript.length > 4000)
             this.transcript = this.transcript.slice(-3000);
     }
@@ -665,8 +684,8 @@ export class HeadlessSession {
      *
      * The result carries more than the outcome: `gh pr create --fill` states its PR number nowhere
      * but its own stdout, so an unnumbered `pr.open`/`pr.merge` takes it from here (#417). It is read
-     * from the RAW `block.content`, never from `toolResult()`'s display line — that truncates to 240
-     * characters for the transcript and would cut the URL off a verbose result.
+     * from the RAW `block.content`, never from `renderToolResult()`'s display lines — those are cut to
+     * the pane's budget (`transcript-lines.ts`) and would drop the URL off a verbose result.
      *
      * This path (and `noteAct`) is reachable ONLY from the structured stream-json handling above
      * (`assistant` → `tool_use`, `user` → `tool_result`). A Codex/Grok session is a raw spawn with no
@@ -820,36 +839,6 @@ export function buildClaudeArgs(userArgs, resumeId) {
         args.push("--resume", resumeId);
     return args;
 }
-/** Strip ANSI/VT escape sequences so a raw CLI's coloured output reads as plain text. */
-function stripAnsi(s) {
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping terminal escape/control codes from terminal output.
-    return s.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/\x1b[()][AB0-2]/g, "").replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, "");
-}
-/** Compact a tool_use input object to a single readable line. */
-function shortInput(input) {
-    if (input == null)
-        return "";
-    try {
-        const s = typeof input === "string" ? input : JSON.stringify(input);
-        return s.length > 160 ? `${s.slice(0, 160)}…` : s;
-    }
-    catch {
-        return "";
-    }
-}
-/** Render a tool_result's content (string, or array of {type:text,text}) to text. */
-function toolResult(content) {
-    let text = "";
-    if (typeof content === "string")
-        text = content;
-    else if (Array.isArray(content)) {
-        text = content
-            .map((b) => (b && typeof b === "object" && "text" in b ? String(b.text) : ""))
-            .join(" ");
-    }
-    text = text.replace(/\s+/g, " ").trim();
-    return text.length > 240 ? `${text.slice(0, 240)}…` : text;
-}
 function loadFile(path) {
     if (!path || !existsSync(path))
         return {};

package/dist/browser-runner/coding/runtime.js

@@ -5,6 +5,7 @@ import { defaultStatePath, HeadlessSession } from "./headless.js";
 import { InspectError, readGitRemoteOrigin, readRepoFile, repoSearch, repoTree, runRepoGit } from "./inspect.js";
 import { switchRepoBranch } from "./repo-write.js";
 import { checkWorkdir, ensureRepo, sanitizeSessionName } from "./repo.js";
+import { asTurnAuthor } from "./turn-author.js";
 /** Hard cap on a pane returned to the brain/console (matches the worker MAX_PANE_CHARS). */
 const MAX_PANE = 64 * 1024;
 export class CodingRuntime {
@@ -116,6 +117,7 @@ export class CodingRuntime {
                 env: input.env,
                 statePath: defaultStatePath(this.reposBaseDir),
                 resumeFrom: input.resumeFrom,
+                ghScope: input.ghScope,
                 bin: input.bin,
             });
             this.sessions.set(input.sessionId, session);
@@ -163,7 +165,9 @@ export class CodingRuntime {
         const session = this.require(sessionId);
         switch (action.kind) {
             case "message":
-                session.input(action.text);
+                // Narrowed rather than trusted: this runner is a published package any caller can
+                // POST to, and an unrecognised author must read as "unstated", not become a label.
+                session.input(action.text, { author: asTurnAuthor(action.author) });
                 break;
             case "keys": {
                 // A snapshot is no longer the whole answer (#448). `key()` records the attempt and
@@ -243,6 +247,7 @@ export class CodingRuntime {
             takeover: this.takeovers.has(sessionId),
             authResolved: s.authResolved,
             engineRuntime: s.engineRuntime,
+            ghGuard: s.ghGuard,
         }));
     }
     // ── Human takeover (the "stuck" handoff) ────────────────────────────────

package/dist/browser-runner/coding/transcript-lines.js

@@ -0,0 +1,223 @@
+/**
+ * How an engine event becomes a line in the pane — the runner's half of #700.
+ *
+ * ── The defect this file exists to remove
+ *
+ * `headless.ts` rendered every `tool_result` through a four-line helper that did two things before
+ * the pane existed: it collapsed `\s+` to a single space, and it cut the text to 240 characters.
+ * Both losses were total and neither was disclosed beyond a trailing ellipsis.
+ *
+ * The consequence is not "results are short". It is that **the shape of a result no longer depends
+ * on the command that produced it.** `cat`, `sed -n '1,50p'`, `cat -n | head -60` and "print every
+ * character" all arrive at the same size, on one line, with the indentation gone. A Pilot that
+ * cannot see a file therefore has no move: every rephrasing it can reach is the same request with
+ * the same bound. One live run spent twelve of its sixteen decisions searching that empty space and
+ * concluded — reasonably, on the evidence in front of it — that "the CLI is summarizing file
+ * contents". It was not; the evidence had been destroyed upstream.
+ *
+ * Measured across 20 sessions of one instance: **150 of 251 stored tool-result lines (59.8%) hit
+ * the 240-character cap** — 102 `Bash`, 43 `Read` — with a maximum line length of 246. The cap was
+ * the common case, and it fired hardest on `Read`, the tool whose entire job is returning file
+ * contents.
+ *
+ * ── What replaces it, and what it costs
+ *
+ * Three changes, and the reason each is separate:
+ *
+ *  1. **Line structure survives.** Newlines are kept and continuation lines carry
+ *     {@link RESULT_CONT_PREFIX}. This is the half that matters most and it costs almost nothing:
+ *     `cat -n` output is unreadable as one space-joined line at ANY length, so the collapse made
+ *     the cap worse than its size alone implies.
+ *  2. **The cap is per tool** ({@link toolResultBudget}), not one number. A `Read` result is the
+ *     case that needs room; an `Edit`'s "has been updated successfully" is a status string that was
+ *     never near 240 anyway. Raising one number for everything would buy file text by spending the
+ *     pane on results that carry none.
+ *  3. **A cut states its own size** (`…[cut: 1,500 of 18,432 chars]`), so the reader learns there
+ *     is more AND how much — which is what makes "ask for a slice that fits" a strategy rather than
+ *     a guess. Same disclosure discipline as `repo_read_file`'s window header and `repo_git`'s
+ *     TRUNCATED note on the cloud side.
+ *
+ * **The cost is real and it is the pane.** A `terminal` row stores the last 8,000 characters
+ * (`TERMINAL_SNAPSHOT_CHARS`) and one Pilot decision reads the last 6,000 (`PILOT_PANE_CHARS`), so
+ * every character bought for file text is bought by evicting history — including the `⚙`/`↳`
+ * framing `engine-tool-calls.ts` parses back out and the engine-error lines #580 exists to keep
+ * visible. {@link RESULT_CAP_CONTENT_CHARS} is therefore derived from that window rather than
+ * chosen from it — see {@link RESULT_CAP_CONTENT_CHARS} and {@link RESULT_RENDERED_MAX}, which
+ * state the content budget and what it actually costs the pane once framing is paid for.
+ *
+ * ── Old runners, and why nothing gates on a version
+ *
+ * A machine that has not upgraded keeps the 240-char single-line behaviour, so every cloud reader
+ * must go on tolerating short, structureless results — `engine-tool-calls.ts` already models that
+ * (`outputCut`) and continues to. Continuation lines are read by their PREFIX, not by a version
+ * probe: a pane is judged by what it contains, the way the `↳✓` outcome marker is.
+ */
+/**
+ * The prefix every line of a result after the first carries.
+ *
+ * It exists for two reasons and the second is the load-bearing one:
+ *
+ *  - the pane stays readable as a transcript rather than as an unindented dump, and
+ *  - a result can no longer FORGE the framing. `parseEngineToolCalls` decides what a line is from
+ *    its first characters, so a file containing a line that begins `⚙ ` or `↳` would, once
+ *    newlines survived, parse as a tool call the engine never made. Every continuation line begins
+ *    with this prefix instead, so a result's own text can never start a line that the parser reads
+ *    as anything else.
+ *
+ * `│` (U+2502), not `|`: a markdown table in an engine's reply uses the ASCII pipe, and the point
+ * of the character is that transcript prose does not use it.
+ */
+export const RESULT_CONT_PREFIX = "  │ ";
+/**
+ * How much of a CONTENT tool's result — its own characters, framing excluded — reaches the pane.
+ *
+ * Derived, not picked: the Pilot reads the last 6,000 characters of the pane
+ * (`PILOT_PANE_CHARS`, `workers/api/src/lib/coding-repetition.ts`), and no single result may take
+ * more than a QUARTER of that in content, which is ~35 lines of ordinary source — what a bounded
+ * slice request actually asks for. What that costs the pane in full is {@link RESULT_RENDERED_MAX},
+ * and it is the larger number, because framing is not free.
+ *
+ * The two constants are separate declarations in separate packages for the reason `RESULT_ARROW` is
+ * (a Worker must not import the runner's Node package); the derivation is stated here so that
+ * moving one without the other is at least a visible mistake.
+ *
+ * `used` and `total` in the cut notice are BOTH content characters, deliberately: the number is
+ * only actionable if the model can compare it against the file it is asking for.
+ */
+export const RESULT_CAP_CONTENT_CHARS = 1500;
+/**
+ * A ceiling on LINES as well as characters, because the prefix is charged per line.
+ *
+ * A result of 1,500 one-character lines would pay {@link RESULT_CONT_PREFIX} 1,500 times — 6,000
+ * characters of framing for 1,500 of content, i.e. the whole of the Pilot's window spent on
+ * indentation. 60 lines bounds that overhead at 240 characters.
+ */
+export const RESULT_CAP_CONTENT_LINES = 60;
+/** Every other tool keeps the historical 240 characters — see {@link CONTENT_TOOLS}. */
+export const RESULT_CAP_DEFAULT_CHARS = 240;
+/** …and at most six lines of it, so a status string cannot spend six prefixes to say nothing. */
+export const RESULT_CAP_DEFAULT_LINES = 6;
+/** The longest cut notice the renderer can emit — `…[cut: 999,999,999 of 999,999,999 chars]`. */
+const CUT_NOTICE_MAX = 45;
+/**
+ * What the WHOLE result block can cost the pane, framing and disclosure included.
+ *
+ * Stated because the content budget alone is not the honest figure and pretending otherwise is how
+ * a cap gets quietly exceeded: the arrow prefix, one `RESULT_CONT_PREFIX` and one newline per
+ * continuation line, and the cut notice are all pane characters too. At the current numbers that is
+ * ~1,840 — under a THIRD of the Pilot's 6,000-character window, so three consecutive content
+ * results still coexist with the narrative and the `⚙`/`↳` framing rather than evicting them.
+ *
+ * If someone widens {@link RESULT_CAP_CONTENT_CHARS}, this is the number that says what it costs.
+ */
+export const RESULT_RENDERED_MAX = "  ↳✓ ".length + RESULT_CAP_CONTENT_CHARS + (RESULT_CAP_CONTENT_LINES - 1) * (RESULT_CONT_PREFIX.length + 1) + CUT_NOTICE_MAX;
+/**
+ * The tools whose RESULT is the answer, rather than a receipt for an action.
+ *
+ * `Read`/`Bash` are the two the measurement names (43 and 102 of the 150 truncated lines).
+ * `Grep`/`Glob`/`BashOutput`/`NotebookRead` are here because their results are line-structured
+ * listings — the same content, arriving through a different tool name — and a Pilot that asked for
+ * a grep instead of a cat should not be punished for it.
+ *
+ * `Edit`, `Write`, `MultiEdit` and `TodoWrite` are deliberately absent: their results are status
+ * strings ("has been updated successfully…", 176-214 characters in the sampled sessions) that the
+ * old cap barely touched, so widening them would spend the pane and buy nothing.
+ */
+export const CONTENT_TOOLS = new Set(["Read", "Bash", "BashOutput", "Grep", "Glob", "NotebookRead"]);
+/** The budget for one tool's result. An unknown or unnamed tool gets the conservative one. */
+export function toolResultBudget(tool) {
+    return CONTENT_TOOLS.has(tool)
+        ? { chars: RESULT_CAP_CONTENT_CHARS, lines: RESULT_CAP_CONTENT_LINES }
+        : { chars: RESULT_CAP_DEFAULT_CHARS, lines: RESULT_CAP_DEFAULT_LINES };
+}
+/** Strip ANSI/VT escape sequences so a raw CLI's coloured output reads as plain text. */
+export function stripAnsi(s) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping terminal escape/control codes from terminal output.
+    return s.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/\x1b[()][AB0-2]/g, "").replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, "");
+}
+/** Compact a tool_use input object to a single readable line. */
+export function shortInput(input) {
+    if (input == null)
+        return "";
+    try {
+        const s = typeof input === "string" ? input : JSON.stringify(input);
+        return s.length > 160 ? `${s.slice(0, 160)}…` : s;
+    }
+    catch {
+        return "";
+    }
+}
+/** Render a tool_result's content (string, or array of `{type:text,text}`) to raw text. */
+export function toolResultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    // Joined with a NEWLINE, not a space: separate content blocks are separate pieces of output,
+    // and the whole point of this module is that the difference is preserved.
+    return content
+        .map((b) => (b && typeof b === "object" && "text" in b ? String(b.text) : ""))
+        .filter((t) => t !== "")
+        .join("\n");
+}
+/**
+ * Normalise a result's text to display lines: no CR, no escape codes, no trailing whitespace, and
+ * no runs of blank lines. Every one of those is pane budget spent on nothing.
+ */
+function tidyLines(text) {
+    const out = [];
+    for (const raw of stripAnsi(text.replace(/\r\n?/g, "\n")).split("\n")) {
+        const line = raw.trimEnd();
+        // Drop a leading blank, and collapse a run of blanks to one.
+        if (!line && (out.length === 0 || out[out.length - 1] === ""))
+            continue;
+        out.push(line);
+    }
+    while (out.length && out[out.length - 1] === "")
+        out.pop();
+    return out;
+}
+/**
+ * The full transcript entry for one `tool_result` — the arrow line plus any continuation lines.
+ *
+ * The head is cut rather than the tail, unchanged from the old helper: a file, a listing and a
+ * grep all answer from their beginning, and a test run's tail is recoverable from the engine's own
+ * reply text, which is never truncated. Changing that is a separate decision and is not made here.
+ */
+export function renderToolResult(mark, content, tool) {
+    const lines = tidyLines(toolResultText(content));
+    const budget = toolResultBudget(tool);
+    const total = lines.join("\n").length;
+    const kept = [];
+    let used = 0;
+    let cut = false;
+    for (const line of lines) {
+        if (kept.length >= budget.lines) {
+            cut = true;
+            break;
+        }
+        const room = budget.chars - used;
+        if (room <= 0) {
+            cut = true;
+            break;
+        }
+        if (line.length > room) {
+            kept.push(line.slice(0, room));
+            used += room;
+            cut = true;
+            break;
+        }
+        kept.push(line);
+        used += line.length;
+    }
+    if (cut && kept.length) {
+        // The figures, not just the ellipsis: "there was more" tells the reader to give up, "1,500
+        // of 18,432" tells it how narrow a slice would arrive whole. The ellipsis stays because it
+        // is what every runner ever written has used to mark a cut, and readers key on it.
+        kept[kept.length - 1] = `${kept[kept.length - 1]}…[cut: ${used.toLocaleString("en-US")} of ${total.toLocaleString("en-US")} chars]`;
+    }
+    const head = `  ↳${mark} ${kept[0] ?? ""}`.trimEnd();
+    if (kept.length < 2)
+        return head;
+    return [head, ...kept.slice(1).map((l) => `${RESULT_CONT_PREFIX}${l}`)].join("\n");
+}

package/dist/browser-runner/coding/turn-author.js

@@ -0,0 +1,86 @@
+/**
+ * Who wrote the turn the Engine is about to receive (#505, criterion 3).
+ *
+ * ── The defect
+ *
+ * `HeadlessSession.input` writes every turn to Claude Code as
+ * `{ type: "user", message: { role: "user", … } }`. That is the only shape the stream-json input
+ * protocol accepts — the role vocabulary is `user`/`assistant`, there is no third value to move
+ * to, and an Engine that stops receiving instructions is far worse than the defect — so the
+ * framing cannot be fixed by changing the role. The consequence is that the Engine calls whoever
+ * is driving it "the user", and **whoever is driving it is usually the Pilot, not a person.**
+ *
+ * On 2026-08-11 that produced a completion message telling the owner he had been warned and had
+ * "explicitly chosen" to bump the wrong `pubspec.yaml`. `instance_messages` shows he sent nothing
+ * in that window (22:31:20 and 22:47:54 bracket it); the Engine's objection was correct, and
+ * overriding it broke the deploy. Nothing had lied: the Engine said "the user", the Pilot read
+ * that back, and "the user" is the only word the protocol gave it.
+ *
+ * ── What this module does, and what it deliberately does not
+ *
+ * It **names the author** on the two surfaces the naming collision travels through:
+ *
+ *  - {@link authoredTurn} — a one-line preamble the Engine reads BEFORE the instruction, so the
+ *    Engine's own prose ("you asked me to…") is at least anchored to something that says what
+ *    "you" is. The instruction follows **verbatim**, after a blank line. #505's standing promise
+ *    is *annotate, never rewrite*: the instruction is the evidence, and truncating or rephrasing
+ *    it would destroy the only record of what was actually sent.
+ *  - {@link authorTag} — a two-word marker on the transcript line, which is what the owner reads
+ *    in the Terminal view and what the Pilot re-reads through `/coding/capture`. It is short
+ *    because that pane is a fixed character budget the Pilot pays for on every decision; a
+ *    150-character preamble repeated on every turn would evict real output from the window the
+ *    Pilot can see. The pane has never been a wire log — it already renders `❯ [12:03:04] …`,
+ *    which is not sent either — so a compact marker there is consistent with what that line is.
+ *
+ * ── Why only the Pilot is named
+ *
+ * The vocabulary is **closed at one member on purpose**, the way `repo-write.ts` closes its verb
+ * list. `POST /coding/act` is a shared door: the console's manual `/message` route, MCP's
+ * `coding_session_message`, the Overseer's delegation and the agent's own `drive_claude` tool all
+ * arrive through it, and none of them declares an author. An absent author therefore means
+ * "nobody said", which is exactly what it renders as — nothing. Adding a `"human"` member would
+ * turn silence into a claim the runner cannot support: it could only ever be set by the callers
+ * that already bothered to be explicit, so an unlabelled human turn and an unlabelled machine turn
+ * would still be indistinguishable while the labelling implied otherwise.
+ *
+ * A runner older than this change ignores the field entirely and behaves exactly as before; a
+ * cloud older than this change sends no author and the bytes are byte-identical to today. Both
+ * directions degrade to the status quo rather than to a wrong label.
+ */
+/** The authors this runner will accept over the wire. Anything else is treated as unstated. */
+const AUTHORS = ["pilot"];
+/**
+ * Narrow an untrusted wire value to a {@link TurnAuthor}.
+ *
+ * The runner is a published npm package that any caller can POST to, so the field arrives as
+ * `unknown` and an unrecognised value must read as "unstated" rather than becoming a label.
+ */
+export function asTurnAuthor(value) {
+    return typeof value === "string" && AUTHORS.includes(value) ? value : undefined;
+}
+/**
+ * The preamble the Engine reads. Kept to one sentence pair: it is prepended to EVERY Pilot turn,
+ * so its length is a per-turn token cost on every engine, on every run.
+ *
+ * It states only what the runner actually knows — the caller declared this turn's author — and
+ * makes no claim about whether a human is watching, because the console does surface the Pilot's
+ * step lines in the owner's chat and "no person has seen this" would be false there.
+ */
+const PILOT_PREAMBLE = '[pags] This turn was written by the Pilot, an automated orchestrator, not typed by a person. "The user" in this conversation means the Pilot.';
+/**
+ * The instruction as the Engine receives it: the author's preamble, a blank line, then the
+ * caller's text **unchanged**.
+ *
+ * Returns the input untouched when the author is unstated, so the only turns whose bytes change
+ * are the ones the platform can actually name.
+ */
+export function authoredTurn(text, author) {
+    return author === "pilot" ? `${PILOT_PREAMBLE}\n\n${text}` : text;
+}
+/**
+ * The transcript marker, already spaced for concatenation (`""` when the author is unstated), so
+ * a reader of the pane can tell a Pilot turn from a turn a person typed.
+ */
+export function authorTag(author) {
+    return author === "pilot" ? "(pilot) " : "";
+}

package/dist/browser-runner/handoff-status.js

@@ -0,0 +1,56 @@
+/**
+ * What a handoff-status poll can answer WITHOUT looking at the live page (#641).
+ *
+ * A handoff is the runner asking a human for something the brain cannot do: solve a
+ * challenge, perform one widget step it failed at, or supply a value it must not invent.
+ * The remote Workflow polls `browserHandoffStatus` until it is told the human acted, and
+ * `solved: true` is a licence to resume the application — so the only safe answers are the
+ * ones the runner can actually stand behind.
+ *
+ * ── The rule
+ *
+ * A handoff whose PAGE IS GONE is LOST, not resolved. It is the same category as a handoff
+ * whose SESSION is gone (the runner restarted, the takeover expired), which the caller
+ * already answers `solved: false` under a comment stating the rule outright: *a status poll
+ * must never relaunch the browser or claim a lost handoff is done.* Three lines below that
+ * comment sat `if (page.isClosed()) return { solved: true }`, ahead of all three per-reason
+ * branches, so it overrode every one of them:
+ *
+ *   - `challenge` — the brain resumed with the CAPTCHA unsolved, and the claim was acted
+ *     on rather than re-checked: the workflow records `solvedChallengeUrl`, and the apply
+ *     loop then suppresses captcha re-detection on that page for the rest of the round. A
+ *     false "solved" muted the detector that would have caught it.
+ *   - `stuck` — resumed without the human doing the single step the handoff exists for;
+ *     `humanDone` was never consulted.
+ *   - `needs_input` — resumed with `value: undefined`, so the workflow skipped the save and
+ *     the brain re-asked on the next round for a value it had been given.
+ *
+ * There is nothing to resume ONTO in any of those cases: the page the human was working in
+ * no longer exists, and the brain's next action would land on a freshly created blank tab.
+ * Staying unsolved lets the wait time out into "not resolved in time", which the cloud maps
+ * to `escalated` → the board's "Needs you" column — visible, and retryable by the owner.
+ *
+ * ── The one exception, and why it is not one
+ *
+ * `needs_input` is answered BEFORE page liveness is considered, because its answer never
+ * involved the page: the value arrives out of band through `browserSubmitInput`, which
+ * writes it onto the session. A value the owner typed is a real answer whether or not the
+ * tab survived, and discarding it would re-ask for something already in hand.
+ */
+/**
+ * The answer to a handoff-status poll, or `null` when only the live DOM can give one — a
+ * `challenge` on a page that is still open, whose token clears in the page itself.
+ */
+export function resolveHandoffStatus(facts) {
+    // Out of band, and therefore unaffected by a page that has gone.
+    if (facts.reason === "needs_input")
+        return { solved: !!facts.inputValue, challenge: null, value: facts.inputValue };
+    // Lost, not done. See the note above — this line is the fix for #641.
+    if (facts.pageClosed)
+        return { solved: false, challenge: null };
+    // A stuck handoff resumes only when the human explicitly clicks Resume — there's
+    // nothing to auto-detect.
+    if (facts.reason === "stuck")
+        return { solved: !!facts.humanDone, challenge: null };
+    return null;
+}

package/dist/browser-runner/runner.js

@@ -5,9 +5,11 @@ import { basename, dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { captureScreenshotDataUrl, challengeSolved, detectHumanChallenge } from "./challenge.js";
 import { resolveRealChromeProfileDir, seedProfileCopy } from "./browser-profile.js";
+import { isTerminalTaskStatus, settleTaskOutcome } from "./apply-outcome.js";
 import { McpRuntime } from "./mcp-runtime.js";
 import { commitLabelRe, ELEMENT_PROBE_FN, FOCUS_PROBE_FN, refuseClick, refuseKey } from "./commit-guard.js";
 import { HumanHandoffError, RunnerInputError } from "./errors.js";
+import { resolveHandoffStatus } from "./handoff-status.js";
 import { RunnerStore } from "./store.js";
 import { CodingRuntime } from "./coding/runtime.js";
 import { WORKFLOW_DRIVEN_TASKS } from "./task-types.js";
@@ -170,7 +172,11 @@ export class LocalRunner {
     }
     cancelTask(id) {
         const task = this.requireTask(id);
-        if (task.status === "completed" || task.status === "failed")
+        // Already finished, whichever way — the old `completed || failed` pair missed `cancelled`, so
+        // a second Stop rewrote the timestamps and appended a duplicate event (#636). A run that
+        // genuinely completed or failed is NOT relabelled: it ended before the Stop arrived. Off THIS
+        // return the cloud mirrored `task.cancelled` carrying `{status:"failed"}` — fixed in the cloud.
+        if (isTerminalTaskStatus(task.status))
             return task;
         task.status = "cancelled";
         task.updatedAt = new Date().toISOString();
@@ -1144,15 +1150,12 @@ export class LocalRunner {
         if (!session)
             return { solved: false, challenge: null };
         const page = session.page;
-        if (page.isClosed())
-            return { solved: true, challenge: null };
-        // A needs_input handoff resumes once the user supplies the value.
-        if (session.reason === "needs_input")
-            return { solved: !!session.inputValue, challenge: null, value: session.inputValue };
-        // A stuck handoff resumes only when the human explicitly clicks Resume —
-        // there's nothing to auto-detect.
-        if (session.reason === "stuck")
-            return { solved: !!session.humanDone, challenge: null };
+        // Every answer that needs no live DOM — including a GONE page, which used to report
+        // solved:true and resume past an unsolved challenge (#641) — comes from
+        // handoff-status.ts; null means only an open challenge's own DOM can answer.
+        const offline = resolveHandoffStatus({ reason: session.reason, pageClosed: page.isClosed(), inputValue: session.inputValue, humanDone: session.humanDone });
+        if (offline)
+            return offline;
         // A challenge resumes when the token/widget clears OR the human clicks Done —
         // custom captchas (e.g. PageUp's "not a robot") have no detectable token, so
         // the human's explicit Done is the authority; never strand them.
@@ -1197,23 +1200,17 @@ export class LocalRunner {
         }
         return { ok: true };
     }
-    /** Finalize an agent-driven application (submitted/expired → completed; else failed). */
+    /** Finalize an agent-driven application — the outcome→status table lives in apply-outcome.ts. */
     async browserComplete(taskId, outcome, detail) {
         await this.endTakeover(taskId).catch(() => undefined);
         const task = this.store.getTask(taskId);
         if (task) {
-            const success = outcome === "submitted" || outcome === "ready" || outcome === "expired";
-            // 'blocked' = the agent stopped and needs the USER (email verification, can't
-            // proceed truthfully) — it's needs-attention, not a failure, so keep it a
-            // distinct status (the console shows it as an active ticket, not buried).
-            task.status = outcome === "blocked" ? "blocked" : success ? "completed" : "failed";
-            task.output = { outcome, detail };
-            if (!success)
-                task.error = detail || outcome;
-            task.updatedAt = new Date().toISOString();
-            task.completedAt = task.updatedAt;
+            // A TOTAL table, not a chain of string comparisons: `cancelled` matched none of
+            // them and fell through to `failed`, so a run the owner stopped was filed as an
+            // error with a Retry button on it (#636). See apply-outcome.ts.
+            const { event } = settleTaskOutcome(task, outcome, detail);
             this.store.putTask(task);
-            this.addTaskEvent(task, success ? "task.completed" : "task.failed", detail || `Application ${outcome}`, { outcome, detail });
+            this.addTaskEvent(task, event, detail || `Application ${outcome}`, { outcome, detail });
         }
         await this.closeStalePages().catch(() => undefined);
         return { ok: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proagentstore/cli",
-  "version": "0.4.54",
+  "version": "0.4.56",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",