@proagentstore/cli 0.4.55 → 0.4.56

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

@@ -3,26 +3,9 @@ import { classifyCommand, commandFromToolInput, fillTargetFromResult, toolCallOk
 import { parseEngineUsage } from "./engine-usage.js";
 import { turnReportFromExit, turnReportFromResult } from "./engine-turn.js";
 import { renderToolResult, shortInput, stripAnsi } from "./transcript-lines.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 { 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";
@@ -173,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)?
@@ -344,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;
@@ -386,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;
@@ -398,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 {
@@ -432,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

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/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/package.json

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