@proagentstore/cli 0.4.49 → 0.4.51

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

@@ -0,0 +1,55 @@
+/**
+ * How the LAST completed engine turn ended (#545).
+ *
+ * The exit code was already known on this side and spent entirely on prose: `runOneShot`'s close
+ * handler pushed `[codex exited with code 1]` into the transcript and set no field, so a production
+ * Codex session whose every turn exited 1 — three times, the reason printed each time — reported
+ * `alive: true, ready: true, runState: "idle"`, and the Pilot spent fifteen minutes and three BYOK
+ * decisions rediscovering it from the pane.
+ *
+ * OUTCOME AND LIVENESS ARE TWO FACTS, and this module owns only the first. Nothing here touches
+ * `alive`: a one-shot session has no process between turns, a failing turn does not make the
+ * session unable to take another, and conflating the two once killed every delegated goal on
+ * codex/grok/gemini at iteration 0 (see `HeadlessSession.alive`). The failure is REPORTED here;
+ * what to make of one is the cloud's judgement, in `workers/api/src/lib/coding-turn-outcome.ts`.
+ *
+ * Its own module, beside `engine-usage.ts` / `engine-acts.ts` / `engine-auth.ts`, for the reason
+ * they are: the RULE that turns a process exit into a verdict is worth testing without spawning a
+ * process, and it is the part someone will later be tempted to change.
+ */
+/** Longest engine line carried as {@link EngineTurnReport.detail}. The pane holds the rest. */
+export const MAX_TURN_DETAIL = 240;
+/**
+ * A one-shot turn's process has exited — say what that means, and nothing more.
+ *
+ * A SIGNAL outranks the code because a signalled process's code is null and the kill is ours: the
+ * 15-minute wedge ceiling and `interrupt()` both land here, and counting either as an engine
+ * failure would let three slow builds read as a broken CLI.
+ */
+export function turnReportFromExit(code, signal, lastLine = "", now = Date.now()) {
+    const detail = lastLine.trim().slice(0, MAX_TURN_DETAIL);
+    return {
+        verdict: signal !== null ? "killed" : code === 0 ? "ok" : "failed",
+        exitCode: code,
+        signal,
+        at: now,
+        ...(detail ? { detail } : {}),
+    };
+}
+/**
+ * A stream-json turn ended with a `result` event — the structured path's analogue of an exit code.
+ *
+ * Without it the field would exist for three engines and silently not for the flagship, which is
+ * the shape of gap that makes a platform-wide claim ("we notice a failed turn") false in the one
+ * case that runs most.
+ */
+export function turnReportFromResult(isError, detail = "", now = Date.now()) {
+    const text = detail.trim().slice(0, MAX_TURN_DETAIL);
+    return {
+        verdict: isError ? "failed" : "ok",
+        exitCode: null,
+        signal: null,
+        at: now,
+        ...(text ? { detail: text } : {}),
+    };
+}

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

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { classifyCommand, commandFromToolInput, fillTargetFromResult } 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".
@@ -88,6 +89,16 @@ export class HeadlessSession {
     turnStartedAt = 0;
     /** Set by stop() — the only thing that ends a one-shot session (see `alive`). */
     stopped = false;
+    /** How the last COMPLETED turn ended (#545). Null until one has. See {@link EngineTurnReport}. */
+    turnReport = null;
+    /**
+     * The engine's own last output line of the turn in flight (#545).
+     *
+     * Recorded as it is written, so the failure detail is the engine's sentence rather than
+     * something parsed back out of a rendered pane. Reset when a turn starts, so a report can never
+     * carry a previous turn's line.
+     */
+    turnLastLine = "";
     /** Measured engine spend not yet handed to the cloud (#267). Drained by {@link takeUsage}. */
     pendingUsage = [];
     /**
@@ -216,6 +227,15 @@ export class HeadlessSession {
             return !this.stopped && !this.spawnFailed;
         return this.procAlive;
     }
+    /**
+     * How the last completed turn ended (#545) — NOT whether the session can take another.
+     *
+     * Read by the snapshot and carried to the cloud. Null means no turn has completed on this
+     * session; it is never a claim that a turn went well.
+     */
+    get lastTurn() {
+        return this.turnReport;
+    }
     /** Is a process running THIS instant? The persistent engine's liveness, and the spawn guard. */
     get procAlive() {
         return this.proc !== null && this.proc.exitCode === null && this.proc.signalCode === null;
@@ -397,6 +417,9 @@ export class HeadlessSession {
      * preset decides what runs and what it costs; the platform does not need to know the engine.
      */
     runOneShot(text) {
+        // 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], {
             cwd: this.config.workDir,
             env: mergeEnv(process.env, this.config.env),
@@ -450,7 +473,7 @@ export class HeadlessSession {
             }
         }, maxTurnMs);
         ceiling.unref();
-        proc.on("close", (code) => {
+        proc.on("close", (code, signal) => {
             clearTimeout(ceiling); // cleared before the staleness guard: the timer belongs to THIS process
             // A non-zero exit is the engine's own failure (bad flags, not signed in) and the
             // operator needs to see it — silently going idle is how "stdin is not a terminal"
@@ -465,6 +488,14 @@ export class HeadlessSession {
             // kill-tmux.
             if (this.proc !== proc)
                 return;
+            // THE EXIT CODE STOPS BEING ONLY PROSE HERE (#545). Recorded after the staleness guard
+            // on purpose: a turn aborted by its successor (see the kill above) must not overwrite
+            // the report of the turn that replaced it — the loser's outcome is about a turn nobody
+            // is waiting on any more.
+            //
+            // A signal means WE ended it (the wedge ceiling, an interrupt), which is the `killed`
+            // verdict: evidence about this platform's timers, not about the engine's health.
+            this.turnReport = turnReportFromExit(code, signal, this.turnLastLine);
             this.run = "idle";
             this.proc = null;
         });
@@ -536,8 +567,12 @@ export class HeadlessSession {
     /** Raw-engine stdout: strip ANSI control codes and append to the transcript. */
     pushRaw(line) {
         const clean = stripAnsi(line);
-        if (clean.trim())
+        if (clean.trim()) {
             this.push(clean);
+            // The engine's own words, kept for the turn's report (#545) — captured on the way in,
+            // never scraped back out of the rendered pane.
+            this.turnLastLine = clean.trim();
+        }
         if (this.transcript.length > 4000)
             this.transcript = this.transcript.slice(-3000);
     }
@@ -576,8 +611,14 @@ export class HeadlessSession {
                 }
                 break;
             case "result": {
-                if (ev.is_error)
-                    this.push(`[error] ${ev.result ?? ev.subtype ?? "failed"}`);
+                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.

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

@@ -290,7 +290,16 @@ export function repoTree(workDir, relPath = ".", maxDepth = 3, maxEntries = 500)
                 try {
                     size = statSync(abs).size;
                 }
-                catch { }
+                catch {
+                    // Benign, and traced rather than assumed (#291). `size` stays `undefined`, which JSON
+                    // drops, so the entry reaches the model as `{path, type: "file"}` — the same listing a
+                    // successful stat produces, because `repo-local.ts`'s renderer prints `e.path` and has
+                    // never shown a size at all. The test is whether the fallback can be mistaken for a
+                    // real answer: `size: 0` would be a claim about an empty file; an absent field is not
+                    // a claim. The entry itself is still emitted because `readdir` saw it, and the one
+                    // case where that is already stale — deleted between the readdir and this stat —
+                    // degrades into an honest error from `repo_read_file`, not into a wrong listing.
+                }
                 entries.push({ path: rel, type: "file", size });
             }
         }

package/dist/browser-runner/coding/repo-write.js

@@ -119,10 +119,18 @@ export function switchRepoBranch(workDir, branch) {
     // CONFIRM, do not assume. The exit code says the command ran; only reading HEAD back says where
     // the checkout actually is, and that is the only thing the cloud is allowed to report as done.
     const after = currentBranch(workDir);
-    let dirtyAfter = false;
+    // And the same rule for the tree: `null` when git would not answer, never `false`. Nothing in
+    // the cloud reads this field today — `repo-policy-act.ts` acts on `refused`, `error` and its own
+    // independent read — so this is prophylactic rather than a live defect, and it is recorded that
+    // way. What makes it worth changing anyway is that the value is a CLAIM and the next reader
+    // inherits it: `dirty: false` off a failed `git status` says "clean" in the one field whose
+    // whole job is to say whether anything came across. Absent is degraded; manufactured is wrong.
+    let dirtyAfter;
     try {
         dirtyAfter = isDirty(workDir);
     }
-    catch { }
+    catch {
+        dirtyAfter = null;
+    }
     return { ok: after === to, changed: after === to, from, to, branch: after, dirty: dirtyAfter };
 }

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

@@ -151,6 +151,10 @@ export class CodingRuntime {
             // exactly the question asked about a session that just stopped.
             authResolved: session.authResolved,
             engineRuntime: session.engineRuntime,
+            // Reported on EVERY capture, including one where the session is not alive: "how did the
+            // last turn end" is exactly the question asked about a session that just stopped, and
+            // the omitted-when-null shape keeps "not measured" distinguishable from a verdict.
+            ...(session.lastTurn ? { lastTurn: session.lastTurn } : {}),
             ...(opts.drainUsage ? { usage: session.takeUsage(), acts: session.takeActs() } : {}),
         };
     }
@@ -187,6 +191,17 @@ export class CodingRuntime {
      * turn of a session very often runs after the final capture poll, and ending is where that
      * record would otherwise be lost — silently, and only for the turns at the end of every
      * session, which is a bias rather than noise.
+     *
+     * …and, since #554, WHO PAID for it. The spend was already returned here; the observation that
+     * makes it attributable was one field away on the session object in hand, so every closing turn
+     * of every session reached the ledger with `payer` NULL even when the credential was known. The
+     * bias is the same one the paragraph above describes, which is why the omission mattered: it
+     * did not lose a random sample of turns, it lost the last turn of every session.
+     *
+     * `null` is a REAL answer here, not a default. `end()` tolerates a `sessionId` it has never
+     * heard of, and the honest report for a session this runner does not have is that it cannot say
+     * what the engine authenticated with — not a guess derived from the preset (see
+     * `usage-payer.ts`, and the alternative #554 rejected).
      */
     end(sessionId) {
         const session = this.sessions.get(sessionId);
@@ -196,12 +211,16 @@ export class CodingRuntime {
         // happens after the final capture poll. Discarding the tail would systematically lose exactly
         // the acts this record exists for.
         const acts = session ? session.takeActs() : [];
+        // Read BEFORE `stop()`: `authResolved` is a live getter over the merged spawn env
+        // (`headless.ts`), so it must be taken while the session is still the object that spawned
+        // the process rather than after it has been torn down and dropped from the map.
+        const authResolved = session ? session.authResolved : null;
         if (session) {
             session.stop();
             this.sessions.delete(sessionId);
         }
         this.takeovers.delete(sessionId);
-        return { ok: true, usage, acts };
+        return { ok: true, usage, acts, authResolved };
     }
     list() {
         return [...this.sessions.entries()].map(([sessionId, s]) => ({

package/package.json

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