@tiens.nguyen/gu-cli 1.0.724 → 1.0.726

package/cli-token.mjs

@@ -172,6 +172,44 @@ export async function writeState(dir, state) {
   await rename(tmp, file);
 }
 
+/** Why a pasted token was refused, in words that say what to do. */
+export function tokenRefusal(why) {
+  return why === "bad-signature" ? "it was not issued by gu (or was copied incompletely)"
+    : why === "unknown-version" ? "it is from a newer gu — update this one first"
+    : "it is not a whole token — copy it again from the Account page";
+}
+
+/**
+ * Check a pasted token OFFLINE and save it — the one way `gu token <paste>` and the terminal's own
+ * prompt both save one. lastAttemptAt null: the next gu start renews at once, which records THIS
+ * computer. Returns { ok: true, payload } or { ok: false, reason }.
+ */
+export async function saveTokenFromPaste(dir, pasted, publicKeyB64 = publicKey()) {
+  const check = verifyCliToken(String(pasted ?? "").trim(), publicKeyB64);
+  if (!check.ok) return { ok: false, reason: tokenRefusal(check.why) };
+  await writeState(dir, { token: String(pasted).trim(), lastAttemptAt: null });
+  return { ok: true, payload: check.payload };
+}
+
+/**
+ * Does a turn need a token first? Only in PRIVATE MODE (task #246): its local API fetches the
+ * agent's instructions from the gu service with this token. Hosted mode uses the worker key and
+ * never needs one. A build with no public key (tokens not configured) never asks.
+ */
+export function turnNeedsToken({ privateMode, token, publicKeyB64 = publicKey() }) {
+  if (!privateMode || !publicKeyB64) return false;
+  return !(token && verifyCliToken(token, publicKeyB64).ok);
+}
+
+/** What the terminal says when a private-mode turn needs the token — friendly, and the steps. */
+export function tokenAskLines(siteBaseUrl = siteUrl()) {
+  return [
+    "This computer needs your gu token before the agent can start — one time only.",
+    `  1. Open ${siteBaseUrl}/account and copy your gu CLI token.`,
+    "  2. Paste it below and press Enter.",
+  ];
+}
+
 // ---------------------------------------------------------------------------
 // WHEN TO RENEW, AND HOW
 // ---------------------------------------------------------------------------

package/gonext_agent_chat.py

@@ -1725,35 +1725,81 @@ def _looks_like_scratchpad(stripped: str) -> bool:
 # THE CODE-AGENT SCAFFOLD IS NOT IN THIS FILE (task #246). The fixed system prompt — the
 # Thought → Code → Observation rules that replace smolagents' stock ~9.9k-char template — is served
 # by the API (GET /api/worker/prompt-scaffold) and never shipped in the gu package. The worker
-# fetches it once per job; if it cannot, the turn stops with the reason. There is deliberately NO
-# local copy to fall back to: the point is that the text is not on the user's machine.
+# gets it once per job — from ~/.gonext/prompt-scaffolds/code-agent.txt if YOU put one there (gu
+# never writes it), else from the API — and if it cannot, the turn stops with the reason. There is
+# no bundled copy to fall back to: the point is that the text is not in what gu ships.
 #
-# What a scaffold must keep, checked again here after the API checked it: without the code-block
-# tags the model's code is never parsed, without the tool loop no signature is shown, without
-# custom_instructions the per-turn hint is dropped — each fails silently, every turn.
-_SCAFFOLD_REQUIRED = (
-    "{{code_block_opening_tag}}",
-    "{{code_block_closing_tag}}",
-    "tool.to_code_prompt()",
-    "{{authorized_imports}}",
-    "custom_instructions",
-)
+# Every scaffold passes the three checks in prompt_scaffold_check.py (size, placeholders, a trial
+# render) — without the code-block tags the model's code is never parsed, without the tool loop no
+# signature is shown, without custom_instructions the per-turn hint is dropped; each fails silently.
 
 
 # The version of the scaffold this job is running — for the log and the prompt record, never the text.
 _PROMPT_SCAFFOLD_VERSION = {"v": None}
 
 
+# THE LOCAL OVERRIDE AND THE THREE CHECKS live in prompt_scaffold_check.py — one checker, used by
+# this worker before every turn AND by `gu` at startup (so "scaffold loaded" means it passed).
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import prompt_scaffold_check as _psc  # noqa: E402
+
+_LOCAL_SCAFFOLD_PATH = _psc.LOCAL_SCAFFOLD_PATH
+_scaffold_problem = _psc.scaffold_problem
+_SCAFFOLD_REQUIRED = _psc.SCAFFOLD_REQUIRED
+
+
+def _load_prompt_scaffold(api_base: str, worker_key: str):
+    """The scaffold for this turn → (template, version, source).
+
+    YOUR LOCAL FILE FIRST (~/.gonext/prompt-scaffolds/code-agent.txt): when it exists it is used and
+    the API is not asked. Otherwise the API's version (the database's). Either way it passes the
+    three checks in _scaffold_problem, and a failure stops the turn with the reason — a broken local
+    file is NOT quietly replaced by the database version, or an edit that broke it would look like
+    it had no effect."""
+    if os.path.isfile(_LOCAL_SCAFFOLD_PATH):
+        where = "~/.gonext/prompt-scaffolds/code-agent.txt"
+        try:
+            with open(_LOCAL_SCAFFOLD_PATH, encoding="utf-8") as f:
+                text = f.read()
+        except Exception as e:  # noqa: BLE001
+            raise _AgentConfigError(
+                f"The agent couldn't start: your local scaffold {where} could not be read "
+                f"({type(e).__name__}). Fix it, or delete it to use the gu service's.") from None
+        problem = _scaffold_problem(text, f"your local scaffold {where}")
+        if problem:
+            raise _AgentConfigError(
+                f"The agent couldn't start: {problem}. Fix it, or delete it to use the gu service's.")
+        _PROMPT_SCAFFOLD_VERSION["v"] = "local"
+        return text, "local", where
+    template, version = _fetch_prompt_scaffold(api_base, worker_key)
+    problem = _scaffold_problem(template, "the scaffold from the gu service")
+    if problem:
+        _log(f"prompt scaffold v{version} unusable: {problem}")
+        raise _AgentConfigError(
+            "The agent couldn't start: gu received instructions it can't use from the server. "
+            "Please try again later.")
+    return template, version, "api"
+
+
+def _is_local_api(base: str) -> bool:
+    """Is this the private-mode API on this computer (vs the hosted gu service)?"""
+    from urllib.parse import urlparse
+    host = (urlparse(base).hostname or "").lower()
+    return host in ("127.0.0.1", "localhost", "::1") or host.startswith("127.")
+
+
 def _fetch_prompt_scaffold(api_base: str, worker_key: str, name: str = "code-agent"):
     """The agent's prompt scaffold from the API → (template, version).
 
     Raises _AgentConfigError with a message the USER reads (it becomes a TURN_FAILED line) when
     the API cannot be asked, refuses, or sends something unusable. Never returns a default. The
-    message never contains the template itself."""
+    message never contains the template. Written as what to DO, not as HTTP codes: the person
+    reading it wants the next step, and "HTTP 404 … prompt service" gave them a puzzle instead."""
     base = (api_base or "").rstrip("/")
+    local = _is_local_api(base)
     if not base or not worker_key:
         raise _AgentConfigError(
-            "The agent's prompt could not be loaded: this worker has no API address or key.")
+            "The agent couldn't start: this computer isn't signed in to gu. Please run `gu login`.")
     from urllib.parse import urlencode
     req = urllib.request.Request(
         f"{base}/api/worker/prompt-scaffold?{urlencode({'name': name})}",
@@ -1767,24 +1813,36 @@ def _fetch_prompt_scaffold(api_base: str, worker_key: str, name: str = "code-age
             detail = str(json.loads(he.read().decode("utf-8", "replace") or "{}").get("error") or "")
         except Exception:  # noqa: BLE001
             pass
-        if he.code == 404 and not detail:
-            detail = ("this API is older than the prompt service — update it "
-                      "(`gu api upgrade` on a private-mode machine)")
+        if detail:
+            # The API's own sentence already says what to do (e.g. "please run `gu token`").
+            raise _AgentConfigError(f"The agent couldn't start: {detail}") from None
+        if he.code == 404:
+            raise _AgentConfigError(
+                "The agent couldn't start: your local gu API is out of date. "
+                "Please run `gu api upgrade`, then send your message again." if local else
+                "The agent couldn't start: the gu service isn't ready for this version of gu yet. "
+                "Please try again in a few minutes.") from None
         raise _AgentConfigError(
-            f"The agent's prompt could not be loaded (HTTP {he.code})"
-            + (f": {detail}" if detail else ".")) from None
-    except Exception as e:  # noqa: BLE001
+            f"The agent couldn't start: the gu API had a problem (error {he.code}). "
+            "Please try again in a moment.") from None
+    except Exception:  # noqa: BLE001
         raise _AgentConfigError(
-            f"The agent's prompt could not be loaded — the API at {base} did not answer "
-            f"({type(e).__name__}). Check that it is running and reachable.") from None
+            "The agent couldn't start: your local gu API isn't answering. "
+            "Please check it with `gu api status` (or `gu api restart`), then try again." if local else
+            "The agent couldn't start: the gu service isn't answering. "
+            "Please check your internet connection and try again.") from None
     template = data.get("template") if isinstance(data, dict) else None
     version = data.get("version") if isinstance(data, dict) else None
     if not isinstance(template, str) or not template.strip():
-        raise _AgentConfigError("The agent's prompt could not be loaded: the API sent an empty one.")
+        raise _AgentConfigError(
+            "The agent couldn't start: gu received empty instructions from the server. "
+            "Please try again later.")
     missing = [p for p in _SCAFFOLD_REQUIRED if p not in template]
     if missing:
+        _log("prompt scaffold unusable: missing " + ", ".join(missing))
         raise _AgentConfigError(
-            "The agent's prompt could not be used: it is missing " + ", ".join(missing) + ".")
+            "The agent couldn't start: gu received instructions it can't use from the server. "
+            "Please try again later.")
     _PROMPT_SCAFFOLD_VERSION["v"] = version
     return template, version
 
@@ -2298,7 +2356,8 @@ def _render_prompt(messages, max_chars: int = 400_000) -> str:
             # the API and shown on the token-usage page — so it would hand the hidden text to
             # anyone who opens a step. Its size stays visible, the text does not.
             v = _PROMPT_SCAFFOLD_VERSION["v"]
-            text = (f"[prompt scaffold{f' v{v}' if v is not None else ''} with the tool signatures — "
+            label = " (your local file)" if v == "local" else (f" v{v}" if v is not None else "")
+            text = (f"[prompt scaffold{label} with the tool signatures — "
                     f"{len(text)} characters, not shown]")
         out.append(f"───── {role or 'message'} ─────\n{text}")
     rendered = "\n\n".join(out)
@@ -12117,7 +12176,11 @@ def run_agent_chat(cfg):
             # templates that will not load, stop the turn with the reason (_AgentConfigError →
             # TURN_FAILED) instead of quietly running on a different prompt. The version is
             # logged; the text never is.
-            _scaffold, _scaffold_version = _fetch_prompt_scaffold(worker_api_base, worker_api_key)
+            _scaffold, _scaffold_version, _scaffold_source = _load_prompt_scaffold(worker_api_base, worker_api_key)
+            if _scaffold_source != "api":
+                # SAID, every turn it applies: an old file left lying around must never quietly
+                # change the agent. One line in the thinking area, not a banner.
+                _emit({"type": "step", "text": f"using your local prompt scaffold ({_scaffold_source})"})
             try:
                 import yaml as _yaml
                 import os as _os
@@ -12126,10 +12189,11 @@ def run_agent_chat(cfg):
                     _tpl = _yaml.safe_load(_f)
             except Exception as _e:  # noqa: BLE001
                 raise _AgentConfigError(
-                    f"The agent's prompt templates could not be loaded ({type(_e).__name__}).") from None
+                    "The agent couldn't start: part of gu's install is damaged "
+                    f"({type(_e).__name__}). Please reinstall gu.") from None
             _tpl["system_prompt"] = _scaffold
             agent_kwargs["prompt_templates"] = _tpl
-            _log(f"prompt scaffold code-agent v{_scaffold_version}")
+            _log(f"prompt scaffold code-agent {'local file' if _scaffold_source != 'api' else f'v{_scaffold_version}'}")
         agent = _ToolAgent(**agent_kwargs)
         _agent_ref["a"] = agent  # let step_callback trim this agent's step memory (#63)
         # At the step budget the run ends WITHOUT final_answer (_maxsteps_partial hit). Offer

package/gu-cli.mjs

@@ -198,19 +198,14 @@ if (args[0] === "token") {
     process.exit(pasted ? 1 : 0);
   }
   if (pasted) {
-    const check = ct.verifyCliToken(pasted, pk);
-    if (!check.ok) {
-      const why =
-        check.why === "bad-signature" ? "it was not issued by gu (or was copied incompletely)"
-        : check.why === "unknown-version" ? "it is from a newer gu — update this one first"
-        : "it is not a whole token — copy it again from the Account page";
-      console.error(`That token was not saved: ${why}.`);
+    // The same check-and-save the terminal's own token prompt uses (saveTokenFromPaste).
+    const saved = await ct.saveTokenFromPaste(dir, pasted, pk);
+    if (!saved.ok) {
+      console.error(`That token was not saved: ${saved.reason}.`);
       process.exit(1);
     }
-    // lastAttemptAt null: the next gu start renews at once, which records THIS computer.
-    await ct.writeState(dir, { token: pasted, lastAttemptAt: null });
     console.log(accent("Saved.") + " It renews itself from now on.");
-    for (const l of ct.tokenSummary(check.payload)) console.log("  " + l);
+    for (const l of ct.tokenSummary(saved.payload)) console.log("  " + l);
     process.exit(0);
   }
   const state = await ct.readState(dir);

package/gu-repl.mjs

@@ -8743,6 +8743,99 @@ const wrapThought = (s, width, maxLines) => {
  * turn's accounting (see the guards below), and its caller must not adopt the answer as its
  * own conversation.
  */
+/**
+ * WHERE THIS SESSION'S SCAFFOLD COMES FROM, said at `gu` start (task #246) — "scaffold loaded" from
+ * the user's own ~/.gonext/prompt-scaffolds/code-agent.txt, or "scaffold fetched" from the gu
+ * service. Background: startup never waits on it (an offline private-mode machine would otherwise
+ * sit for 10s); the line prints when the answer arrives, or at the next prompt if a turn is running.
+ *
+ *   · A LOCAL FILE is checked with the worker's OWN checker (prompt_scaffold_check.py — size,
+ *     placeholders, a trial render), so "loaded" means it passed, not merely that it exists. The API
+ *     is not asked: turns use the file.
+ *   · Otherwise the API is asked to REFRESH — the fetch that the rest of the session then reuses
+ *     ("keep in cache until the user type gu").
+ */
+let scaffoldNotice = null;
+
+async function checkPromptScaffoldAtStart() {
+  const tl = await import("./terminal-layout.mjs");
+  let local = null;
+  let refresh = null;
+  try {
+    local = await localScaffoldState();
+    if (!local?.exists) {
+      const r = await fetch(`${apiBase}/api/worker/prompt-scaffold/refresh?name=code-agent`, {
+        method: "POST",
+        headers: { "X-Worker-Key": workerKey },
+        signal: AbortSignal.timeout(20_000),
+      });
+      const body = await r.json().catch(() => ({}));
+      refresh = { status: r.status, ...(body && typeof body === "object" ? body : {}) };
+    }
+  } catch {
+    /* refresh stays null → "couldn't ask the API" */
+  }
+  scaffoldNotice = tl.scaffoldStartupNotice({ local, refresh, private: isClientExpert() });
+  announceScaffold();
+}
+
+/** The local override's state from prompt_scaffold_check.py, or null when it could not be run. */
+async function localScaffoldState() {
+  const { resolvePython } = await import("./platform-tools.mjs");
+  const { execFile } = await import("node:child_process");
+  const py = await resolvePython();
+  return new Promise((done) => {
+    execFile(py.cmd, [...py.args, join(DIR, "prompt_scaffold_check.py")], { timeout: 15_000, windowsHide: true },
+      (err, stdout) => {
+        try {
+          const last = String(stdout ?? "").trim().split("\n").pop() ?? "";
+          done(JSON.parse(last));
+        } catch {
+          done(null);
+        }
+      });
+  });
+}
+
+/** Print the startup scaffold line — deferred while a turn owns the transcript. */
+function announceScaffold() {
+  if (!scaffoldNotice || following) return;
+  const { kind, text } = scaffoldNotice;
+  scaffoldNotice = null;
+  console.log(GUTTER + (kind === "ok" ? accent("✓ " + text) : kind === "warn" ? yellow("⚠ " + text) : red("✗ " + text)));
+  if (barPinned()) paintBar();
+}
+
+/**
+ * Private mode only: make sure this computer has a valid gu token before a turn is sent (task
+ * #246), asking for it in place. Returns true when the turn may go ahead. Hosted mode, and a gu
+ * built without token support, return true at once.
+ */
+async function ensureTokenForTurn() {
+  if (!isClientExpert()) return true;
+  const ct = await import("./cli-token.mjs");
+  const dir = join(homedir(), ".gonext");
+  const state = await ct.readState(dir);
+  if (!ct.turnNeedsToken({ privateMode: true, token: state.token })) return true;
+  console.log("");
+  for (const l of ct.tokenAskLines()) console.log(GUTTER + (l.startsWith("  ") ? dim(l) : yellow(l)));
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const pasted = String((await ask("  gu token: ")) ?? "").trim();
+    if (!pasted) {
+      console.log(GUTTER + dim("Not sent. Run `gu token <paste>` any time, then send your message again.") + "\n");
+      return false;
+    }
+    const saved = await ct.saveTokenFromPaste(dir, pasted);
+    if (saved.ok) {
+      console.log(GUTTER + accent("✓ token saved") + dim(" — it renews itself from now on.") + "\n");
+      return true;
+    }
+    console.log(GUTTER + yellow(`That token was not saved: ${saved.reason}.`));
+  }
+  console.log(GUTTER + dim("Not sent. Run `gu token <paste>` any time, then send your message again.") + "\n");
+  return false;
+}
+
 async function runAgentTurn(history, { attachJobId = "" } = {}) {
   // #238: when the licence is ENFORCED and this account is not entitled, no turn is sent. Decided at
   // startup (see licenceBlock) — never re-checked here, so a turn cannot die halfway through.
@@ -8751,6 +8844,10 @@ async function runAgentTurn(history, { attachJobId = "" } = {}) {
     return;
   }
   const attached = Boolean(attachJobId);
+  // PRIVATE MODE NEEDS THE gu TOKEN (task #246): the local API fetches the agent's instructions
+  // from the gu service with it. Asked for HERE, before anything is sent, with the steps — rather
+  // than letting the turn fail and leaving the user to decode why.
+  if (!attached && !(await ensureTokenForTurn())) return;
   inputVisible = false; // the frozen zone shows an empty prompt for the duration (#141)
   // Something on screen from the FIRST moment (task #140): Enter has just wiped the bar, and
   // the next thing to draw itself is the turn's ticker — which stays silent until the daemon
@@ -10252,6 +10349,9 @@ async function main() {
   // Show which models will answer, straight from user settings (also validates auth).
   try {
     const probe = await probeWithRecovery();
+    // A NEW gu SESSION: where does its scaffold come from? (task #246) Your file ("loaded") or the
+    // gu service ("fetched" — the refresh the session then reuses). Background: never delays startup.
+    void checkPromptScaffoldAtStart();
     const p = probe?.payload ?? {};
     // Remember the default coder id for the token footer's global-total label, and the
     // default backend's coding URL so the GLOBAL output-token total is keyed to it (task
@@ -10792,6 +10892,7 @@ async function main() {
     // what lets the frozen zone survive scrolling.
     enableClickToPosition();
     announceCliUpdate(); // deferred if a 6h refresh landed mid-turn; harmless once shown
+    announceScaffold(); // the startup scaffold line, if it arrived while a turn was running
     rl.prompt();
     paintBar();
     if (!barPinned()) probeCaretRow(); // fallback path still needs the caret's absolute row

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.724",
+  "version": "1.0.726",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -89,6 +89,7 @@
     "install-path.mjs",
     "gonext_probe_agent.py",
     "gonext_agent_chat.py",
+    "prompt_scaffold_check.py",
     "gonext_transcribe.py",
     "gonext_mlx_embed.py",
     "thinking_words.txt",

package/prompt_scaffold_check.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""THE AGENT'S PROMPT SCAFFOLD — where the local override lives, and the THREE CHECKS (task #246).
+
+One checker, used twice: gonext_agent_chat.py imports it before every agent turn, and `gu` runs it
+at startup (`python3 prompt_scaffold_check.py`) so the "scaffold loaded" line it prints means the
+file really passed — not just that a file exists. Needs only jinja2 (a smolagents dependency), so
+the startup check is quick.
+
+    python3 prompt_scaffold_check.py [path]   → one JSON line: {"exists", "path", "chars", "problem"}
+
+It never prints the scaffold text.
+"""
+import json
+import os
+import re
+import sys
+
+# A scaffold YOU put here wins over the database version, on this machine only. gu never WRITES this
+# file — the scaffold stays off users' disks unless they put it there themselves — so it is an
+# override for trying a wording before inserting it into production, not a cache.
+LOCAL_SCAFFOLD_PATH = os.path.join(os.path.expanduser("~"), ".gonext", "prompt-scaffolds", "code-agent.txt")
+LOCAL_SCAFFOLD_LABEL = "~/.gonext/prompt-scaffolds/code-agent.txt"
+
+# What a scaffold must keep — the same list the API and the deploy app use.
+SCAFFOLD_REQUIRED = (
+    "{{code_block_opening_tag}}",
+    "{{code_block_closing_tag}}",
+    "tool.to_code_prompt()",
+    "{{authorized_imports}}",
+    "custom_instructions",
+)
+
+
+class _SampleTool:
+    """Stands in for a real tool in the trial render — the attributes a template may touch."""
+    name = "sample_tool"
+    description = "A sample tool."
+    inputs = {"query": {"type": "string", "description": "a sample input"}}
+    output_type = "string"
+
+    def to_code_prompt(self):
+        return 'def sample_tool(query: string) -> string:\n    """A sample tool."""'
+
+    def to_tool_calling_prompt(self):
+        return "sample_tool: A sample tool."
+
+
+class _SampleAgent(_SampleTool):
+    name = "sample_agent"
+    description = "A sample managed agent."
+
+
+def scaffold_problem(template, source: str) -> str:
+    """"" when the scaffold is usable; else what is wrong, in words that name `source`. THREE checks:
+
+      1. not empty, at most 64,000 characters;
+      2. the five placeholders the agent loop needs;
+      3. a TRIAL RENDER exactly as smolagents renders it — jinja2 with StrictUndefined and the same
+         six variables — once bare and once with a sample tool, a sample managed agent and custom
+         instructions, so every {% if %}/{% for %} branch is exercised. Catches what 1–2 cannot: an
+         unclosed {% if %}, a stray brace, a misspelled {{ tool.nmae }}."""
+    if not isinstance(template, str) or not template.strip():
+        return f"{source} is empty"
+    if len(template) > 64_000:
+        return f"{source} is over 64,000 characters"
+    missing = [p for p in SCAFFOLD_REQUIRED if p not in template]
+    if missing:
+        return f"{source} is missing " + ", ".join(missing)
+    try:
+        from jinja2 import StrictUndefined, Template, TemplateSyntaxError
+    except Exception:  # noqa: BLE001
+        return ""  # no jinja2 here → smolagents cannot run either; the agent build will say so
+    try:
+        compiled = Template(template, undefined=StrictUndefined)
+    except TemplateSyntaxError as e:
+        return f"{source} has a template error on line {e.lineno}: {e.message}"
+    tool, agent = _SampleTool(), _SampleAgent()
+    for variables in (
+        {"tools": {}, "managed_agents": {}, "custom_instructions": ""},
+        {"tools": {tool.name: tool}, "managed_agents": {agent.name: agent},
+         "custom_instructions": "Sample instructions."},
+    ):
+        try:
+            compiled.render(authorized_imports="['json']", code_block_opening_tag="<code>",
+                            code_block_closing_tag="</code>", **variables)
+        except Exception as e:  # noqa: BLE001
+            line = getattr(e, "lineno", None)
+            # The sample objects are ours, not the reader's: name them for what they stand for.
+            why = re.sub(r"'[\w.]*_SampleAgent object'", "a managed agent", str(e))
+            why = re.sub(r"'[\w.]*_SampleTool object'", "a tool", why)
+            return (f"{source} fails to render"
+                    + (f" on line {line}" if line else "")
+                    + f": {why}")
+    return ""
+
+
+def check_file(path: str = LOCAL_SCAFFOLD_PATH, label: str = LOCAL_SCAFFOLD_LABEL) -> dict:
+    """The local override's state, for `gu` at startup. Never includes the text."""
+    if not os.path.isfile(path):
+        return {"exists": False, "path": label}
+    try:
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+    except Exception as e:  # noqa: BLE001
+        return {"exists": True, "path": label, "chars": 0,
+                "problem": f"your local scaffold {label} could not be read ({type(e).__name__})"}
+    return {"exists": True, "path": label, "chars": len(text),
+            "problem": scaffold_problem(text, f"your local scaffold {label}")}
+
+
+if __name__ == "__main__":
+    target = sys.argv[1] if len(sys.argv) > 1 else LOCAL_SCAFFOLD_PATH
+    label = LOCAL_SCAFFOLD_LABEL if len(sys.argv) <= 1 else target
+    print(json.dumps(check_file(target, label)))

package/terminal-layout.mjs

@@ -1291,6 +1291,14 @@ export function classifyTurnFailure(message) {
   ) {
     return "infra";
   }
+  // SETUP — the agent could not START: its instructions (the prompt scaffold, task #246) could not
+  // be loaded, so no model was ever called. REPORTED: a 503 from the scaffold route matched the
+  // backend patterns below and was captioned "the coding model's backend failed … /model to switch
+  // coder" — wrong on both counts, and switching coder cannot help. The message itself already
+  // says the next step. Both wordings: this gu's, and 1.0.724's ("could not be loaded (HTTP 503)").
+  if (/The agent couldn't start|The agent's prompt (could not be loaded|could not be used)|agent's prompt templates could not be loaded/i.test(t)) {
+    return "setup";
+  }
   // CONFIG — the server is up and answering; it just has no model by that name (task #213).
   // Ollama says: model 'gemma4:e4b' not found  (and "…, try pulling it first" for embeddings).
   // Checked BEFORE the backend patterns because it arrives as a 404 from a perfectly healthy
@@ -1388,6 +1396,11 @@ export function retryAdvice({ resumable = true, failures = 1, kind = "task", min
       ? `gu's own machinery has failed ${failures} times in a row — not your question, and not the coding model. Check it before retrying: gu-cli api status, and gu-cli start if the worker is not running.`
       : 'that was gu\'s own machinery stopping, not your question — "continue" runs it again';
   }
+  if (kind === "setup") {
+    // Nothing ran, so there is nothing to diagnose in the model or the question — only the step the
+    // message above names. "continue" is right AFTER that step, never before.
+    return 'nothing ran yet — not your question, and not the coding model. Do the step above, then "continue" sends your question again.';
+  }
   if (kind === "config") {
     // Not resumable by repetition, and saying "continue" here would be a lie — the same
     // question with the same model name fails identically every time. Retry count is
@@ -1755,6 +1768,39 @@ export function lazyModuleNames(text) {
     .filter((m) => m !== "gu-cli.mjs");
 }
 
+/**
+ * The one line `gu` prints at startup about the agent's prompt scaffold (task #246) — asked for so
+ * the user KNOWS where this session's scaffold came from: "scaffold is loaded" (their own file) or
+ * "scaffold is fetched" (the gu service). Pure; gu-repl gathers the facts.
+ *
+ *   local   — prompt_scaffold_check.py's answer: { exists, path, chars, problem } (null = not run)
+ *   refresh — POST /api/worker/prompt-scaffold/refresh: { status, ok, version, error, kept }
+ *   private — private mode (the local API), which decides what "update" advice means
+ * Returns { kind: "ok" | "warn" | "err", text }.
+ */
+export function scaffoldStartupNotice({ local = null, refresh = null, private: privateMode = false } = {}) {
+  const n = (x) => Number(x ?? 0).toLocaleString("en-US");
+  if (local?.exists) {
+    return local.problem
+      ? { kind: "err", text: `scaffold: ${local.problem} — fix it, or delete it to use the gu service's` }
+      : { kind: "ok", text: `scaffold loaded from ${local.path} (${n(local.chars)} chars)` };
+  }
+  if (!refresh) return { kind: "warn", text: "scaffold: couldn't ask the API — the first turn will try again" };
+  if (refresh.status === 404) {
+    return {
+      kind: "warn",
+      text: privateMode
+        ? "scaffold: your local gu API is older than this gu — run `gu api upgrade`"
+        : "scaffold: the gu service doesn't serve it yet — agent turns will fail until it does",
+    };
+  }
+  if (refresh.ok) return { kind: "ok", text: `scaffold fetched from the gu service (v${refresh.version})` };
+  const why = String(refresh.error ?? "unknown error").replace(/\.$/, "");
+  return refresh.kept !== undefined
+    ? { kind: "warn", text: `scaffold: couldn't fetch — ${why}. Still using v${refresh.kept}.` }
+    : { kind: "err", text: `scaffold: ${why}.` };
+}
+
 /** One line, bounded — a reason is for reading, and npm's can carry a whole stack frame. */
 function _clipReason(s, max = 160) {
   const one = String(s).replace(/\s+/g, " ").trim();