@proagentstore/cli 0.4.56 → 0.4.58

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

@@ -14,7 +14,7 @@
 const HANDLERS = {
     claude: { clientType: "claude", cliCommand: "claude --dangerously-skip-permissions", envVar: "ANTHROPIC_API_KEY" },
     gemini: { clientType: "gemini", cliCommand: "gemini --approval-mode yolo --skip-trust --prompt", envVar: "GEMINI_API_KEY" },
-    codex: { clientType: "codex", cliCommand: "codex exec --sandbox danger-full-access", envVar: "OPENAI_API_KEY" },
+    codex: { clientType: "codex", cliCommand: "codex exec --json --sandbox danger-full-access", envVar: "OPENAI_API_KEY" },
     grok: { clientType: "grok", cliCommand: "grok --permission-mode bypassPermissions -p", envVar: "XAI_API_KEY" },
     generic: { clientType: "generic", cliCommand: "bash", envVar: "" },
 };

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

@@ -10,6 +10,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { handlerFor } from "./handlers.js";
 import { resolveEngineAuth } from "./engine-auth.js";
+import { engineAdapterFor, engineInvocationModeFromAdapter, engineInvocationWarning } from "./engine-adapter.js";
+export { buildClaudeArgs } from "./engine-adapter.js";
 /**
  * How many un-drained usage records a session holds (#267).
  *
@@ -60,8 +62,19 @@ export class HeadlessSession {
     run = "idle";
     /** Claude Code's own session id (from the init event) — used to --resume. */
     claudeSessionId = null;
+    /**
+     * The cloud's context brief, until the first turn spends it (ADR 0005, #693). Null once
+     * delivered, and null from the start when the engine resumed its own conversation.
+     *
+     * Consumed ONCE, by construction rather than by convention: it is cleared in the same expression
+     * that reads it. A brief re-sent on every turn would be the "unbounded brief… a token bill that
+     * grows every turn" the ADR names as the cost of owning the conversation, and it would also start
+     * contradicting the engine's own memory of the turns since.
+     */
+    pendingSeed = null;
     /** "stream-json" for Claude (structured) · "raw" for any other CLI (stdout capture). */
     mode;
+    adapter;
     cmdBin;
     cmdArgs;
     binName;
@@ -166,6 +179,14 @@ export class HeadlessSession {
     get ghGuard() {
         return ghGuardStatus(this.config.ghScope, mergeEnv(process.env, this.config.env), this.config.ghGuardRoot);
     }
+    /** Whether this process is running through structured events or plain stdout (#731). */
+    get engineMode() {
+        return engineInvocationModeFromAdapter(this.mode);
+    }
+    /** A named warning only when a structured-capable engine is actually running raw (#731). */
+    get engineModeWarning() {
+        return engineInvocationWarning(this.config.clientType, this.engineMode);
+    }
     /**
      * Did this engine launch with a conversation to continue (#408)?
      *
@@ -179,15 +200,27 @@ export class HeadlessSession {
      * flag and {@link buildClaudeArgs} is only reached in stream-json mode.
      */
     get resumedConversation() {
-        return this.mode === "stream-json" && this.claudeSessionId !== null;
+        return this.config.clientType === "claude" && this.mode === "stream-json" && this.claudeSessionId !== null;
+    }
+    /**
+     * Did this engine come up cold AND with a brief to lead its first turn (ADR 0005, #693)?
+     *
+     * Read by `/coding/start` so the sentence the user is shown is one this side CONFIRMED. It is
+     * armed-not-delivered: the brief goes out with the first `input()`, which may never arrive if
+     * the session is closed first. That is why the cloud's wording is "it was given a brief" — true
+     * the moment the engine holds one — and never "it has read your history".
+     */
+    get seededConversation() {
+        return this.pendingSeed !== null;
     }
     constructor(config) {
         this.config = config;
         this.engineLabel = `${config.clientType}:${config.id}`;
         // Our own key first, the cloud's nominated predecessor second. See `resumeFrom`.
-        this.claudeSessionId = readState(config.statePath, config.id) ?? (config.resumeFrom ? readState(config.statePath, config.resumeFrom) : null);
-        // Claude is the structured engine; everything else is a raw CLI.
-        this.mode = config.clientType === "claude" ? "stream-json" : "raw";
+        this.claudeSessionId =
+            config.clientType === "claude"
+                ? readState(config.statePath, config.id) ?? (config.resumeFrom ? readState(config.statePath, config.resumeFrom) : null)
+                : null;
         const { bin, args } = parseCommand(config.command);
         // When no explicit command is configured, fall back to THIS engine's default
         // command (codex/gemini/grok/…) — not a hard-coded "claude", which would drive a
@@ -198,6 +231,12 @@ export class HeadlessSession {
         // Use the configured command's args when a command was given (bin set), else the
         // engine default's args.
         this.cmdArgs = bin ? args : fallback.args;
+        this.adapter = engineAdapterFor(config.clientType, this.cmdArgs);
+        this.mode = this.adapter.mode;
+        // AFTER both lines above, because `resumedConversation` reads them: the brief is the fallback,
+        // so an engine that found its own conversation drops it unread rather than being handed a
+        // summary of the conversation it is already in.
+        this.pendingSeed = this.resumedConversation ? null : config.seed?.trim() || null;
         this.binName = (this.cmdBin.split("/").pop() || this.cmdBin) || "cli";
     }
     /**
@@ -262,7 +301,7 @@ export class HeadlessSession {
         // The ceiling that stops a wedged process is armed in `runOneShot` — it ENDS the turn
         // rather than relabelling a live one as idle, which is the same mistake in slower form.
         if (this.oneShot)
-            return this.procAlive ? "thinking" : "idle";
+            return this.mode === "stream-json" ? this.run : this.procAlive ? "thinking" : "idle";
         // Below: a PERSISTENT non-Claude engine — alive between turns, so exit says nothing about
         // a turn and idle must be inferred. None ships today; every raw engine is one-shot. The
         // gate is `!oneShot` rather than `mode === "raw"` because the latter now means the
@@ -314,7 +353,7 @@ export class HeadlessSession {
      * multi-turn, which is why it survived the migration untouched.
      */
     get oneShot() {
-        return this.mode === "raw";
+        return !this.adapter.persistent;
     }
     start() {
         // Starting always un-stops: `stop()` is what ends a one-shot session, so a (re)start
@@ -329,10 +368,7 @@ export class HeadlessSession {
         }
         if (this.procAlive)
             return;
-        // stream-json: we own the structural flags + --resume; merge the user's extras
-        // (e.g. --model) without letting them clobber or orphan-value our flags. raw:
-        // run exactly what the user configured and capture stdout.
-        const args = this.mode === "stream-json" ? buildClaudeArgs(this.cmdArgs, this.claudeSessionId) : [...this.cmdArgs];
+        const args = this.adapter.buildLaunchArgs(this.cmdArgs, this.claudeSessionId);
         const proc = spawn(this.cmdBin, args, {
             cwd: this.config.workDir,
             env: this.spawnEnv,
@@ -381,8 +417,17 @@ export class HeadlessSession {
     input(text, opts = {}) {
         // The Engine reads the preamble, the pane the short marker; the instruction stays evidence.
         const sent = authoredTurn(text, opts.author);
+        // The brief leads the turn and is spent in the reading (#693). It goes to the ENGINE only:
+        // the pane gets the one-line marker below, because the transcript is what the owner and the
+        // Pilot re-read through `/coding/capture` and twelve thousand characters of reconstructed
+        // history would evict the live output they are looking at — the same budget argument
+        // `turn-author.ts` makes for its two-word marker.
+        const seed = this.pendingSeed;
+        this.pendingSeed = null;
         if (!this.alive)
             this.start();
+        if (seed)
+            this.push("[pags] a context brief from ProAgentStore's record was delivered with this turn — a reconstruction, not the previous conversation");
         this.push(`\n❯ [${stamp()}] ${authorTag(opts.author)}${text}`); // ❯ — your turn, timestamped
         this.run = "thinking";
         const now = Date.now();
@@ -390,16 +435,19 @@ export class HeadlessSession {
         this.turnStartedAt = now;
         this.sawOutputSinceInput = false; // arm the persistent-raw idle heuristic for THIS turn
         try {
-            if (this.mode === "stream-json") {
+            // Brief first, instruction second, and never the other way round: it is background for
+            // the request, and an engine that reads the request last acts on the request.
+            const withSeed = seed ? `${seed}\n\n${sent}` : sent;
+            if (this.adapter.persistent) {
                 // `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 }] } });
+                const msg = JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text: withSeed }] } });
                 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(sent);
+                this.runOneShot(withSeed);
             }
         }
         catch {
@@ -425,7 +473,7 @@ export class HeadlessSession {
         // Arm the per-turn line capture BEFORE the spawn, so a report can only ever carry a line
         // this turn produced (#545).
         this.turnLastLine = "";
-        const proc = spawn(this.cmdBin, [...this.cmdArgs, text], {
+        const proc = spawn(this.cmdBin, this.adapter.buildTurnArgs(this.cmdArgs, text), {
             cwd: this.config.workDir,
             env: this.spawnEnv,
             stdio: ["ignore", "pipe", "pipe"],
@@ -582,79 +630,65 @@ export class HeadlessSession {
             this.transcript = this.transcript.slice(-3000);
     }
     handle(line) {
-        let ev;
-        try {
-            ev = JSON.parse(line);
-        }
-        catch {
-            return; // tolerate non-JSON noise
-        }
-        switch (ev.type) {
-            case "system":
-                if (ev.subtype === "init" && ev.session_id) {
-                    this.claudeSessionId = ev.session_id;
-                    writeState(this.config.statePath, this.config.id, ev.session_id);
-                }
-                break;
-            case "assistant":
-                for (const block of ev.message?.content ?? []) {
-                    if (block.type === "text" && typeof block.text === "string" && block.text.trim()) {
-                        this.push(`[${stamp()}] ${block.text.trim()}`); // timestamped agent reply
-                    }
-                    else if (block.type === "tool_use") {
-                        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);
+        for (const ev of this.adapter.parseLine(line)) {
+            switch (ev.kind) {
+                case "session":
+                    if (this.config.clientType === "claude") {
+                        this.claudeSessionId = ev.sessionId;
+                        writeState(this.config.statePath, this.config.id, ev.sessionId);
                     }
+                    break;
+                case "assistant_text":
+                    this.push(`[${stamp()}] ${ev.text}`); // timestamped agent reply
+                    break;
+                case "tool_use":
+                    this.push(`⚙ ${ev.name} ${shortInput(ev.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 (ev.id)
+                        this.toolNames.set(ev.id, ev.name);
+                    this.noteAct(ev.block);
+                    break;
+                case "tool_result": {
+                    // `""` 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(ev.toolUseId) ?? "";
+                    this.toolNames.delete(ev.toolUseId);
+                    this.push(renderToolResult(toolResultMark(ev.block), ev.content, tool)); // ↳✓ / ↳✗ (#597)
+                    this.settleAct(ev.block);
+                    break;
                 }
-                break;
-            case "user": // tool results come back as a synthetic user message
-                for (const block of ev.message?.content ?? []) {
-                    if (block.type === "tool_result") {
-                        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);
+                case "turn_end": {
+                    const failure = ev.isError ? ev.result : "";
+                    if (failure)
+                        this.push(`[error] ${failure}`);
+                    // The structured path's ANALOGUE of a non-zero exit (#545). Claude has no process
+                    // per turn, so `exitCode` is honestly null and the verdict comes from the protocol's
+                    // own `is_error` — the same claim, in the words the engine states it in. Without
+                    // this the field would exist for three engines and silently not for the flagship.
+                    this.turnReport = turnReportFromResult(ev.isError, failure);
+                    // The same event that ends the turn also reports what the turn COST (#267). It was
+                    // parsed and thrown away, which is why Engine spend was absent from the ledger.
+                    // An errored turn still burned tokens, so this is recorded regardless of is_error.
+                    const usage = parseEngineUsage(ev.raw, `${this.config.id}:${this.usageRunId}:${this.usageSeq++}`);
+                    if (usage) {
+                        this.pendingUsage.push(usage);
+                        if (this.pendingUsage.length > MAX_PENDING_USAGE)
+                            this.pendingUsage.shift();
                     }
+                    // The turn ended, so no further `tool_result` is coming for anything still waiting.
+                    // Publish it with an UNKNOWN outcome rather than dropping it: "it ran this and we
+                    // 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;
                 }
-                break;
-            case "result": {
-                const failure = ev.is_error ? String(ev.result ?? ev.subtype ?? "failed") : "";
-                if (failure)
-                    this.push(`[error] ${failure}`);
-                // The structured path's ANALOGUE of a non-zero exit (#545). Claude has no process
-                // per turn, so `exitCode` is honestly null and the verdict comes from the protocol's
-                // own `is_error` — the same claim, in the words the engine states it in. Without
-                // this the field would exist for three engines and silently not for the flagship.
-                this.turnReport = turnReportFromResult(ev.is_error === true, failure);
-                // The same event that ends the turn also reports what the turn COST (#267). It was
-                // parsed and thrown away, which is why Engine spend was absent from the ledger.
-                // An errored turn still burned tokens, so this is recorded regardless of is_error.
-                const usage = parseEngineUsage(ev, `${this.config.id}:${this.usageRunId}:${this.usageSeq++}`);
-                if (usage) {
-                    this.pendingUsage.push(usage);
-                    if (this.pendingUsage.length > MAX_PENDING_USAGE)
-                        this.pendingUsage.shift();
-                }
-                // The turn ended, so no further `tool_result` is coming for anything still waiting.
-                // Publish it with an UNKNOWN outcome rather than dropping it: "it ran this and we
-                // 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;
             }
-            default:
-                break;
         }
         // 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
@@ -687,10 +721,11 @@ export class HeadlessSession {
      * 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
-     * such framing, so its PRs stay unattributed by construction; scraping its transcript instead
-     * would be the temporal guess `pull-attribution.ts` refuses.
+     * This path (and `noteAct`) is reachable ONLY from structured adapter events. Claude emits
+     * `assistant` → `tool_use`, `user` → `tool_result`; Codex `exec --json` emits
+     * `command_execution`, which the adapter normalizes to the same shape. Raw engines have no such
+     * framing, so scraping their transcript would be the temporal guess `pull-attribution.ts`
+     * refuses.
      */
     settleAct(block) {
         const id = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
@@ -807,38 +842,6 @@ export function parseCommand(command) {
     }
     return { bin: tokens[0] ?? "", args: tokens.slice(1) };
 }
-/** Structural flags PAGS owns for the Claude stream-json engine — a user command
- *  must not override or duplicate these (and must not orphan their values). */
-const RESERVED_CLAUDE_FLAGS = new Set(["-p", "--print", "--input-format", "--output-format", "--verbose", "--resume"]);
-/**
- * Build Claude's argv: our structural stream-json flags + the user's extra args
- * (e.g. `--model`), with reserved flags (and their values) stripped so the user
- * can't clobber the protocol or leave an orphaned positional. `--resume` is added
- * last from our persisted session id, never from the user's command.
- */
-export function buildClaudeArgs(userArgs, resumeId) {
-    const args = ["-p", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose"];
-    for (let i = 0; i < userArgs.length; i++) {
-        const a = userArgs[i];
-        if (RESERVED_CLAUDE_FLAGS.has(a)) {
-            // drop the flag AND its value (when the next token isn't itself a flag)
-            if (i + 1 < userArgs.length && !userArgs[i + 1].startsWith("-"))
-                i++;
-            continue;
-        }
-        // Push every user token as-is. A previous `!args.includes(a)` dedup silently
-        // dropped a REPEATED flag token (e.g. the 2nd `--add-dir` in `--add-dir /a
-        // --add-dir /b`), which orphaned its value (`/b` became a stray positional).
-        // Our own structural flags are already protected via RESERVED_CLAUDE_FLAGS, so
-        // no dedup is needed here.
-        args.push(a);
-    }
-    if (!args.includes("--dangerously-skip-permissions"))
-        args.push("--dangerously-skip-permissions");
-    if (resumeId)
-        args.push("--resume", resumeId);
-    return args;
-}
 function loadFile(path) {
     if (!path || !existsSync(path))
         return {};

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

@@ -1,6 +1,52 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
+/**
+ * Is `dir` inside a git WORK TREE — not merely "does it contain `.git`" (#785)?
+ *
+ * Three functions in this file gated on `existsSync(resolve(workDir, ".git"))`, while
+ * `checkWorkdir` (repo.ts, #405) deliberately asks `git rev-parse --is-inside-work-tree` because
+ * `~/dev/monorepo/apps/thing` is a perfectly good workdir with no `.git` of its own. So the
+ * staleness check called a subdirectory workdir healthy and `repo_git` in the same folder answered
+ * "not a git repo". One question, one answer: this is the gate every git-running function uses.
+ *
+ * A missing directory, a missing git binary and a plain folder all read as `false` — every one
+ * of them makes the git command that follows fail, and "not a git repo" is the message
+ * `saysNotAGitRepo` (workers/api/src/lib/repo-state.ts) already matches on the cloud side.
+ */
+export function insideWorkTree(dir) {
+    try {
+        const out = execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd: dir,
+            encoding: "utf-8",
+            timeout: 10_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return out.trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+/** The one gate. The message is load-bearing: the cloud matches "not a git repo" (#548). */
+function requireWorkTree(workDir) {
+    if (!insideWorkTree(workDir))
+        throw new InspectError("not a git repo");
+}
+/**
+ * Environment for any git command that may touch the NETWORK (#785).
+ *
+ * A fetch that hits an expired credential must fail, not hang the runner's request loop on a
+ * password prompt nobody can see: `GIT_TERMINAL_PROMPT=0` for https, `BatchMode=yes` for ssh.
+ * The user's own `GIT_SSH_COMMAND` wins when set — it may carry a key or a proxy we must keep.
+ */
+function networkGitEnv() {
+    return {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND ?? "ssh -o BatchMode=yes",
+    };
+}
 /**
  * Read-only code inspection for the coding runtime — the "eyes" the Co-pilot/Chat use
  * to GROUND their answers in the real repo (read a file, `git diff`, list the tree)
@@ -34,10 +80,33 @@ export function resolveInside(root, rel, opts = {}) {
     }
     return abs;
 }
+/**
+ * A revision a caller may name (#785). One shape, checked once, used by every command that takes
+ * a `ref`.
+ *
+ * The rule that matters is the FIRST character: git reads a leading `-` as a flag, so a ref may not
+ * start with one, and then no character class below can become an option. Everything else git
+ * accepts as a revision is allowed — a sha, `HEAD~3`, `origin/main`, `v1.2`, `main..feature`,
+ * `@{u}` — because all of those are READS and the argv around them is fixed.
+ */
+const REF_PATTERN = /^[A-Za-z0-9_@][A-Za-z0-9._/^~@{}-]{0,127}$/;
+export function validateRef(ref) {
+    const r = ref.trim();
+    if (!r)
+        throw new InspectError("`ref` is empty");
+    if (!REF_PATTERN.test(r))
+        throw new InspectError(`\`ref\` is not a valid git revision: ${ref.slice(0, 64)}`);
+    return r;
+}
 /** Map a whitelisted command enum to a fixed git argv. `path` (already validated by the
- *  caller via resolveInside) is only ever appended after a literal `--` separator. */
+ *  caller via resolveInside) is only ever appended after a literal `--` separator, and `ref`
+ *  (already validated by `validateRef`) only ever lands where git expects a revision. */
 export function gitArgv(cmd, opts = {}) {
     const clampN = Math.max(1, Math.min(200, Math.floor(opts.n ?? 20)));
+    const path = opts.relPath ? ["--", opts.relPath] : [];
+    // `ref` is a REVISION and belongs before `--`; `path` is a PATHSPEC and belongs after it. That
+    // ordering is what keeps the two from being confused for each other by git, whatever they hold.
+    const rev = opts.ref ? [opts.ref] : [];
     switch (cmd) {
         case "status":
             // `--branch` adds ONE header line (`## main...origin/main [ahead 1]`). Without it a
@@ -48,7 +117,7 @@ export function gitArgv(cmd, opts = {}) {
             // `path` reaches this one too (#508). Narrowing every command rather than four of the
             // five is what lets the tool description say "it applies" with no caveat — and a
             // caveat is what a model has to reason about and can get wrong.
-            return opts.relPath ? ["status", "--short", "--branch", "--", opts.relPath] : ["status", "--short", "--branch"];
+            return ["status", "--short", "--branch", ...path];
         // `path` used to reach exactly ONE of these five (#508). It is advertised on the tool as
         // "Limit the command to one file or folder", `runRepoGit` resolves and validates it, and
         // then four of the five branches dropped it on the floor — so
@@ -60,13 +129,24 @@ export function gitArgv(cmd, opts = {}) {
         // Every one of these is git's own `--` pathspec discipline, unchanged: the validated path
         // is appended after a literal separator and can never be read as a flag or a revision.
         case "diff":
-            return opts.relPath ? ["diff", "--", opts.relPath] : ["diff"];
+            return ["diff", ...rev, ...path];
         case "diff-stat":
-            return opts.relPath ? ["diff", "--stat", "--", opts.relPath] : ["diff", "--stat"];
+            return ["diff", "--stat", ...rev, ...path];
+        // `ref` on `log` is what #785 reached for as `git log -1 <sha>` and found silently ignored:
+        // the input never existed, so the tool answered the canned 20-line list and nothing said
+        // the argument had gone nowhere. Now `{cmd:"log", ref, n:1}` is that command.
         case "log":
-            return opts.relPath ? ["log", "--oneline", "-n", String(clampN), "--", opts.relPath] : ["log", "--oneline", "-n", String(clampN)];
+            return ["log", "--oneline", "-n", String(clampN), ...rev, ...path];
         case "ls-files":
-            return opts.relPath ? ["ls-files", "--", opts.relPath] : ["ls-files"];
+            return ["ls-files", ...path];
+        // `show` is `--stat <sha>`, the other thing #785 tried: what ONE commit changed. `--stat`
+        // rather than the patch, because the patch of an arbitrary commit is unbounded and the
+        // file list is what a reader deciding whether to `diff` one file actually needs. A `show`
+        // with no ref would show HEAD, which is a guess dressed as an answer — required instead.
+        case "show":
+            if (!rev.length)
+                throw new InspectError("`show` needs a `ref` — the commit to describe");
+            return ["show", "--stat", "--format=medium", ...rev, ...path];
         default:
             throw new InspectError(`unsupported git command: ${cmd}`);
     }
@@ -96,16 +176,20 @@ export function readRepoFile(workDir, relPath, maxBytes) {
 }
 /** Run a whitelisted read-only git command in the repo. Never uses a shell. */
 export function runRepoGit(workDir, cmd, opts = {}) {
-    if (!existsSync(resolve(workDir, ".git")))
-        throw new InspectError("not a git repo");
+    requireWorkTree(workDir);
     const relPath = opts.path ? relative(workDir, resolveInside(workDir, opts.path)) : undefined;
-    const argv = gitArgv(cmd, { relPath, n: opts.n });
+    const ref = opts.ref ? validateRef(opts.ref) : undefined;
+    const argv = gitArgv(cmd, { relPath, n: opts.n, ref });
     // Did the path the caller asked for actually reach git? Reported rather than assumed, because
     // a runner is a SEPARATE release from the cloud that calls it: before #508 four of the five
     // commands ignored `path` silently, and the answer — the whole repository — was indistinguishable
     // from a correct one. An older runner omits this field entirely, which is what lets the cloud
     // say "your machine ignored the filter" instead of relaying a wrong answer as a right one.
     const pathApplied = relPath !== undefined && argv.includes(relPath);
+    // Same idiom for `ref` (#785): a runner older than this drops it, and the cloud tells the caller
+    // so — the alternative is the exact silence the issue reported, a `log -1 <sha>` answered by
+    // the newest twenty commits with nothing to say the sha went nowhere.
+    const refApplied = ref !== undefined && argv.includes(ref);
     let out = "";
     try {
         out = execFileSync("git", argv, { cwd: workDir, encoding: "utf-8", timeout: 10_000, maxBuffer: 4 * 1024 * 1024 });
@@ -119,13 +203,13 @@ export function runRepoGit(workDir, cmd, opts = {}) {
     }
     const cap = opts.maxBytes ?? 64 * 1024;
     const truncated = out.length > cap;
-    return { cmd, output: truncated ? out.slice(0, cap) : out, truncated, pathApplied };
+    return { cmd, output: truncated ? out.slice(0, cap) : out, truncated, pathApplied, refApplied };
 }
 /** Read the repo's `origin` remote URL — used to auto-associate a local checkout with its
  *  GitHub repo (so build status can query Actions). Fixed argv, no shell, no user input;
  *  returns null when it's not a git repo or has no `origin` remote. */
 export function readGitRemoteOrigin(workDir) {
-    if (!existsSync(resolve(workDir, ".git")))
+    if (!insideWorkTree(workDir))
         return null;
     try {
         const out = execFileSync("git", ["config", "--get", "remote.origin.url"], {
@@ -178,8 +262,7 @@ const SEARCH_PER_FILE = 5;
 const SEARCH_MAX_LINE = 160;
 const SEARCH_MAX_PATTERN = 200;
 export function repoSearch(workDir, opts) {
-    if (!existsSync(resolve(workDir, ".git")))
-        throw new InspectError("not a git repo");
+    requireWorkTree(workDir);
     const pattern = (opts.pattern ?? "").trim();
     if (!pattern)
         throw new InspectError("a search `pattern` is required");
@@ -306,3 +389,95 @@ export function repoTree(workDir, relPath = ".", maxDepth = 3, maxEntries = 500)
     }
     return { root: relPath, entries, truncated, truncatedByDepth, depthCap };
 }
+export const SYNC_FETCH_TTL_MS = 60_000;
+/** Per work-tree root: when the last fetch attempt was made and how it went. */
+const fetchLog = new Map();
+/** Test seam: forget every cached fetch. */
+export function resetSyncCache() {
+    fetchLog.clear();
+}
+export function repoSync(workDir, opts = {}) {
+    requireWorkTree(workDir);
+    const now = opts.now ?? Date.now;
+    const git = (args, timeout = 10_000) => execFileSync("git", args, { cwd: workDir, encoding: "utf-8", timeout, stdio: ["ignore", "pipe", "pipe"], env: networkGitEnv() }).trim();
+    const tryGit = (args, timeout) => {
+        try {
+            return git(args, timeout);
+        }
+        catch {
+            return null;
+        }
+    };
+    const root = tryGit(["rev-parse", "--show-toplevel"]) ?? resolve(workDir);
+    const abbrev = tryGit(["rev-parse", "--abbrev-ref", "HEAD"]);
+    const branch = abbrev && abbrev !== "HEAD" ? abbrev : null;
+    // The upstream git itself records for the branch, else the same-named branch on `origin` if
+    // that ref exists, else the configured branch on `origin`. Named rather than assumed: a
+    // `main` checkout whose upstream is `upstream/main` must be compared against THAT.
+    let upstream = tryGit(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+    if (!upstream) {
+        for (const candidate of [branch, opts.branch].filter((b) => Boolean(b))) {
+            if (tryGit(["rev-parse", "--verify", "--quiet", `origin/${candidate}`]) !== null) {
+                upstream = `origin/${candidate}`;
+                break;
+            }
+        }
+    }
+    const remote = upstream?.includes("/") ? upstream.slice(0, upstream.indexOf("/")) : "origin";
+    const entry = fetchLog.get(root);
+    const t = now();
+    if (opts.forceFetch || !entry || t - entry.at > SYNC_FETCH_TTL_MS) {
+        try {
+            // `--quiet` so a successful fetch prints nothing to stderr worth parsing; 20s because a
+            // fetch is a network call and the relay's read timeout is above that.
+            git(["fetch", "--quiet", remote], 20_000);
+            fetchLog.set(root, { at: t, error: null, okAt: t });
+        }
+        catch (e) {
+            const err = e;
+            // git's stderr is several lines and the diagnosis is the FIRST `fatal:`/`error:` one —
+            // the tail is boilerplate ("and the repository exists.") that names nothing.
+            const lines = String(err.stderr || err.message || "")
+                .split("\n")
+                .map((l) => l.trim())
+                .filter(Boolean);
+            const detail = lines.find((l) => /^(fatal|error):/i.test(l)) ?? lines[0] ?? "fetch failed";
+            fetchLog.set(root, { at: t, error: detail.replace(/^(fatal|error):\s*/i, "").slice(0, 200), okAt: entry?.okAt ?? null });
+        }
+    }
+    const fetchState = fetchLog.get(root) ?? { at: t, error: null, okAt: null };
+    // Upstream may only exist AFTER the first fetch of a fresh clone — look once more.
+    if (!upstream) {
+        for (const candidate of [branch, opts.branch].filter((b) => Boolean(b))) {
+            if (tryGit(["rev-parse", "--verify", "--quiet", `origin/${candidate}`]) !== null) {
+                upstream = `origin/${candidate}`;
+                break;
+            }
+        }
+    }
+    const localHead = tryGit(["rev-parse", "HEAD"]);
+    const remoteHead = upstream ? tryGit(["rev-parse", upstream]) : null;
+    let ahead = null;
+    let behind = null;
+    if (upstream && remoteHead) {
+        const counts = tryGit(["rev-list", "--left-right", "--count", `HEAD...${upstream}`]);
+        const m = counts?.match(/^(\d+)\s+(\d+)$/);
+        if (m) {
+            ahead = Number.parseInt(m[1], 10);
+            behind = Number.parseInt(m[2], 10);
+        }
+    }
+    return {
+        checked: true,
+        path: root,
+        branch,
+        upstream,
+        localHead,
+        remoteHead,
+        ahead,
+        behind,
+        fetched: fetchState.okAt !== null && t - fetchState.okAt <= SYNC_FETCH_TTL_MS,
+        fetchedAt: fetchState.okAt,
+        fetchError: fetchState.error,
+    };
+}