@tiens.nguyen/gu-cli 1.0.723 → 1.0.725

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/client-expert-api.mjs

@@ -20,6 +20,7 @@
 import { createRequire } from "node:module";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { spawnSurviving, pidOnPort } from "./platform-tools.mjs";
+import { DEFAULT_API_BASE as HOSTED_API_BASE } from "./device-login.mjs";
 import { spawn } from "node:child_process";
 import { writeFile, mkdir, readFile, access } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -64,6 +65,8 @@ export function apiEnv({
   mongoUri = LOCAL_MONGO_URI,
   dbName = LOCAL_DB_NAME,
   base = {},
+  hostedBase = hostedApiBase(),
+  home = homedir(),
 } = {}) {
   return {
     ...base,
@@ -71,9 +74,20 @@ export function apiEnv({
     DATA_BACKEND: "mongo",
     MONGODB_URI: mongoUri,
     MONGODB_DB: dbName,
+    // THE AGENT'S PROMPT SCAFFOLD IS NOT ON THIS MACHINE (task #246). The local API forwards the
+    // worker's request to the hosted API, signed with this machine's gu CLI token, and keeps the
+    // answer in memory only — so private mode needs internet for a turn, and says so when it has
+    // none. No local copy exists to fall back to, by design.
+    PROMPT_SCAFFOLD_UPSTREAM: hostedBase,
+    GU_CLI_TOKEN_FILE: join(home, ".gonext", "cli-token.json"),
   };
 }
 
+/** The hosted gu API — where a Client Expert machine's token is renewed and its scaffold fetched. */
+export function hostedApiBase(env = process.env) {
+  return String(env.GU_TOKEN_API_BASE ?? "").trim() || HOSTED_API_BASE;
+}
+
 /**
  * Is this health body a usable API?
  *

package/gonext_agent_chat.py

@@ -1308,7 +1308,7 @@ def _render_numbered_tool_list(tools) -> str:
     when RAG or a workspace is enabled/disabled) and the numbering is always exactly
     correct, unlike the old manually-incremented counter it replaces. Kept intentionally
     terse — first docstring line only, bare arg names — since the system prompt's own
-    `tool.to_code_prompt()` rendering (see _COMPACT_CODE_SYSTEM_PROMPT) already shows the
+    `tool.to_code_prompt()` rendering (in the API-served prompt scaffold) already shows the
     full typed signature on every model call; this is just a quick-reference index."""
     lines = []
     for i, t in enumerate(tools, 1):
@@ -1722,79 +1722,129 @@ def _looks_like_scratchpad(stripped: str) -> bool:
     return len(_DELIBERATION_RE.findall(stripped)) >= 3
 
 
-# Compact replacement for smolagents' default CodeAgent system prompt. The stock template
-# is ~9.9k chars, dominated by ~6k chars of GENERIC few-shot examples (image captions,
-# Wikipedia, etc.) that are irrelevant to our HTTP/file tools and cost real prompt-eval
-# time every step on a slow coding model. This keeps everything FUNCTIONALLY required —
-# the Thought→Code→Observation loop, the code-blob format + closing tag, the {{tools}}
-# rendering (so exact signatures survive), authorized imports, custom_instructions — plus
-# ONE short worked example, and trims the rest. Jinja vars must match the stock template.
-_COMPACT_CODE_SYSTEM_PROMPT = (
-    "You are an expert assistant who solves the task by writing Python code that calls "
-    "tools. You work in a loop of Thought → Code → Observation.\n\n"
-    "At EACH step:\n"
-    "- Write one 'Thought:' line: what you'll do and which tool.\n"
-    "- Then a code block that OPENS with {{code_block_opening_tag}} and CLOSES with "
-    "{{code_block_closing_tag}}, containing simple Python that calls the tools you need "
-    "and print()s what you want to see.\n"
-    "- BATCH INDEPENDENT CALLS INTO ONE BLOCK. If you already know the arguments for "
-    "several lookups, do them in ONE step and print each under a header — up to about 8 at "
-    "a time, then continue in the next step. Split into separate steps only when an "
-    "argument DEPENDS on a previous Observation.\n"
-    "- Batch LOOKUPS, not changes. If a line raises, the lines after it never run — so "
-    "keep edits, file writes and commands to one per block.\n"
-    "- You then receive the 'Observation:'. Use it to decide the next step. When you have "
-    "the answer, call final_answer(answer) inside a code block.\n\n"
-    "Example — arguments already known, so ONE step does all of it:\n"
-    "Thought: I need these three files before I can change anything.\n"
-    "{{code_block_opening_tag}}\n"
-    'for p in ["src/main.js", "src/api.js", "test/main.test.js"]:\n'
-    '    print("=====", p)\n'
-    "    print(read_file_lines(path=p))\n"
-    "{{code_block_closing_tag}}\n"
-    "Observation: \"===== src/main.js … ===== src/api.js … \"\n\n"
-    "Example — the next call DEPENDS on this result, so it is a separate step:\n"
-    "Thought: I'll read the page the user gave.\n"
-    "{{code_block_opening_tag}}\n"
-    'text = fetch_url("https://example.com")\n'
-    "print(text)\n"
-    "{{code_block_closing_tag}}\n"
-    "Observation: \"Example Domain … \"\n"
-    "Thought: I have the content, so I'll answer.\n"
-    "{{code_block_opening_tag}}\n"
-    'final_answer("The page is Example Domain, a placeholder site.")\n'
-    "{{code_block_closing_tag}}\n\n"
-    "You have access to these tools — call them as plain Python functions with the exact "
-    "signatures shown:\n"
-    "{{code_block_opening_tag}}\n"
-    "{%- for tool in tools.values() %}\n"
-    "{{ tool.to_code_prompt() }}\n"
-    "{% endfor %}\n"
-    "{{code_block_closing_tag}}\n"
-    "{%- if managed_agents and managed_agents.values() | list %}\n"
-    "You can also delegate to team members by calling them like a tool with a 'task' "
-    "string argument:\n"
-    "{{code_block_opening_tag}}\n"
-    "{%- for agent in managed_agents.values() %}\n"
-    "def {{ agent.name }}(task: str) -> str:\n"
-    '    """{{ agent.description }}"""\n'
-    "{% endfor %}\n"
-    "{{code_block_closing_tag}}\n"
-    "{%- endif %}\n\n"
-    "Rules:\n"
-    "1. ALWAYS write a 'Thought:' line, then a code block opening with "
-    "{{code_block_opening_tag}} and closing with {{code_block_closing_tag}} — or you fail.\n"
-    "2. Pass tool arguments directly: calculate(expression=\"2+2\"), NOT as a dict.\n"
-    "3. Use only variables you have defined; state persists between steps.\n"
-    "4. Never re-run a tool call with the exact same parameters.\n"
-    "5. Don't name a variable after a tool (e.g. 'final_answer').\n"
-    "6. Imports are allowed ONLY from: {{authorized_imports}}\n"
-    "7. Don't give up — you are in charge of solving the task.\n"
-    "{%- if custom_instructions %}\n"
-    "{{custom_instructions}}\n"
-    "{%- endif %}\n\n"
-    "Now Begin!"
-)
+# 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
+# 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.
+#
+# 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. 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 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})}",
+        headers={"X-Worker-Key": worker_key}, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=15, context=_ssl_context()) as resp:
+            data = json.loads(resp.read().decode("utf-8", "replace") or "{}")
+    except urllib.error.HTTPError as he:
+        detail = ""
+        try:
+            detail = str(json.loads(he.read().decode("utf-8", "replace") or "{}").get("error") or "")
+        except Exception:  # noqa: BLE001
+            pass
+        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 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(
+            "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 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 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
 
 
 def _usage_field(obj, name):
@@ -2300,6 +2350,15 @@ def _render_prompt(messages, max_chars: int = 400_000) -> str:
     out = []
     for m in messages or []:
         role, text = _message_role_text(m)
+        if role == "system":
+            # THE SCAFFOLD IS NEVER RECORDED (task #246). The system message IS the API-served
+            # prompt scaffold (rendered with the tool signatures), and this record is stored by
+            # 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"]
+            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)
     if len(rendered) > max_chars:
@@ -12111,21 +12170,30 @@ def run_agent_chat(cfg):
             agent_kwargs["additional_authorized_imports"] = [
                 "json", "base64", "urllib", "urllib.request", "urllib.error"
             ]
-            # Trim smolagents' ~6k-char generic few-shot examples from the system prompt
-            # (they dominate prompt-eval on a slow coding model) while keeping the tool
-            # rendering + format rules intact. Load the stock templates and swap only the
-            # system_prompt; fall back to the default on any error.
+            # THE SYSTEM PROMPT IS THE API'S SCAFFOLD (task #246): the stock templates are loaded
+            # for everything else (planning, final-answer, managed agents) and ONLY system_prompt
+            # is swapped. No fallback in either direction — a missing scaffold, or stock
+            # 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, _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
                 import smolagents as _sm
-                _tpl = _yaml.safe_load(open(_os.path.join(
-                    _os.path.dirname(_sm.__file__), "prompts", "code_agent.yaml")))
-                _tpl["system_prompt"] = _COMPACT_CODE_SYSTEM_PROMPT
-                agent_kwargs["prompt_templates"] = _tpl
-                _log("using compact CodeAgent system prompt (trimmed few-shot examples)")
+                with open(_os.path.join(_os.path.dirname(_sm.__file__), "prompts", "code_agent.yaml")) as _f:
+                    _tpl = _yaml.safe_load(_f)
             except Exception as _e:  # noqa: BLE001
-                _log(f"compact system prompt unavailable ({_e}); using smolagents default")
+                raise _AgentConfigError(
+                    "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 {'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.723",
+  "version": "1.0.725",
   "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();