@tiens.nguyen/gu-cli 1.0.769 → 1.0.770

package/agent-stop.mjs

@@ -41,11 +41,28 @@ export const STOP_GRACE_MS = 3000;
  * Stop a child process: SIGTERM now, SIGKILL after `graceMs` unless it has exited.
  * → a function that cancels the pending SIGKILL (call it from the child's `close`).
  */
-export function stopGracefully(child, { graceMs = STOP_GRACE_MS, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
-  try {
-    child.kill("SIGTERM");
-  } catch {
-    /* already gone */
+export function stopGracefully(child, {
+  graceMs = STOP_GRACE_MS,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  platform = process.platform,
+  // WINDOWS HAS NO SIGTERM (task #302): child.kill("SIGTERM") there IS TerminateProcess, which no
+  // handler sees — so a stop could land in the middle of the agent writing a file. There, ask
+  // first (the agent watches GONEXT_STOP_FILE and stops at a safe point) and kill after the grace.
+  requestStop = null,
+} = {}) {
+  if (platform === "win32" && typeof requestStop === "function") {
+    try {
+      requestStop();
+    } catch {
+      /* could not ask — the kill after the grace still stops it */
+    }
+  } else {
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      /* already gone */
+    }
   }
   const t = setTimer(() => {
     if (child.exitCode === null && child.signalCode === null) {

package/gonext_agent_chat.py

@@ -997,6 +997,13 @@ class _AgentConfigError(RuntimeError):
     worth a plain-reply degrade — the user needs the message itself to fix Settings."""
 
 
+class _AgentOffline(_AgentConfigError):
+    """The network was gone for longer than the wait budget (task #302, part 3). Ends the turn
+    as FAILED — never as a stop — with the work so far kept and "continue" as the way on. A
+    subclass of the config error so it takes the same honest exit: no degrade to a plain reply,
+    which would need the network anyway and would answer as if the work had been done."""
+
+
 class _AgentBackendOverloaded(RuntimeError):
     """The coding backend refused every attempt with 429/rate-limit (task #114). Carries
     the user-facing explanation; like a gateway outage it must NOT degrade to a plain
@@ -3539,6 +3546,78 @@ def _retry_delay(attempt: int, overloaded: bool, gateway: bool, err=None) -> flo
     return 1.5 * attempt
 
 
+_OFFLINE_ALWAYS = (
+    # The NAME did not resolve, or there is no route at all: this machine is off the network.
+    "nodename nor servname", "name or service not known", "getaddrinfo failed",
+    "temporary failure in name resolution", "name resolution", "network is unreachable",
+    "no route to host", "network is down", "connection error",
+)
+_OFFLINE_REMOTE = (
+    # Nothing answered at the other end. For a PUBLIC host that is the network (Wi-Fi dropped, a
+    # VPN reconnecting); for a local/LAN box it is the server itself being down, which the
+    # gateway budget already handles — waiting ten minutes for a stopped Ollama would be wrong.
+    "connection refused", "connection reset", "connection aborted",
+    "failed to establish a new connection", "remote end closed connection",
+    "server disconnected", "connecterror",
+)
+_OFFLINE_TYPES = ("APIConnectionError", "ConnectError", "ConnectionError", "RemoteProtocolError",
+                  "ConnectionRefusedError", "ConnectionResetError", "ConnectionAbortedError",
+                  "gaierror", "NewConnectionError")
+
+
+def _is_offline(err, host: str = "") -> bool:
+    """Did this call fail because the NETWORK went away, rather than because a server answered?
+    (task #302, part 3). Such a failure is waited out — the same step is retried when the
+    connection is back — instead of costing the turn a few seconds after the Wi-Fi drops.
+
+    Something that answered with a status is never offline, and a timeout is its own class
+    (openai's APITimeoutError subclasses APIConnectionError, so it is excluded by name)."""
+    if err is None or _http_status_of(err) is not None or _is_request_timeout(err):
+        return False
+    local = _host_locality_is_local(host)
+    cur, depth = err, 0
+    while cur is not None and depth < 6:
+        name = type(cur).__name__
+        text = str(cur or "").lower()
+        if any(w in text for w in _OFFLINE_ALWAYS):
+            return True
+        if not local and (name in _OFFLINE_TYPES or any(w in text for w in _OFFLINE_REMOTE)):
+            return True
+        cur, depth = (getattr(cur, "__cause__", None) or getattr(cur, "__context__", None)), depth + 1
+    return False
+
+
+def _host_locality_is_local(host: str) -> bool:
+    """localhost, 127.x, 10.x, 172.16-31.x, 192.168.x, *.local, a bare name → True."""
+    import re as _re
+    h = str(host or "").strip().lower()
+    h = _re.sub(r"^https?://", "", h).split("/")[0]
+    h = _re.sub(r":\d+$", "", h) if not h.startswith("[") else h
+    if not h:
+        return False
+    if h in ("localhost", "::1", "[::1]") or h.startswith("127."):
+        return True
+    m = _re.match(r"^(\d+)\.(\d+)\.\d+\.\d+$", h)
+    if m:
+        a, b = int(m.group(1)), int(m.group(2))
+        return a == 10 or (a == 172 and 16 <= b <= 31) or (a == 192 and b == 168)
+    return "." not in h or h.endswith((".local", ".lan", ".internal", ".home"))
+
+
+def _offline_wait_budget() -> float:
+    """How long a turn waits for the network before giving up (GONEXT_OFFLINE_WAIT_S, default 10 min)."""
+    try:
+        v = float(os.environ.get("GONEXT_OFFLINE_WAIT_S", "") or 600)
+    except ValueError:
+        v = 600.0
+    return max(0.0, v)
+
+
+def _offline_delay(n: int) -> float:
+    """Seconds before offline retry #n: 2 → 5 → 10 → 15 (capped). Pure."""
+    return (2.0, 5.0, 10.0)[n - 1] if 1 <= n <= 3 else 15.0
+
+
 def _is_backend_unavailable(err) -> bool:
     s = str(err or "").lower()
     # An overload (429) is its own class — never let it fall into the gateway bucket, whose
@@ -3737,6 +3816,12 @@ def _stream_fallback_decision(err, first_token_seen: bool) -> str:
         return "raise"
     if _is_request_timeout(err) or _is_backend_unavailable(err):
         return "raise"
+    # THE NETWORK WENT (task #302, part 3). Found by the mid-turn offline test: "Connection
+    # error." matched nothing above, so a dropped Wi-Fi re-sent the step UNSTREAMED and marked the
+    # server as unable to stream for the rest of the process. A lost connection says nothing about
+    # the request's shape — raise, and the retry loop waits for the network.
+    if _is_offline(err):
+        return "raise"
     return "fallback"
 
 
@@ -6875,24 +6960,115 @@ def _ws_kill_tree(pid: int, force: bool = False) -> None:
 # what is still in flight and exits. Servers/apps already left running are not in this set.
 _INFLIGHT_CMDS: set = set()
 
+# A STOP NEVER LANDS INSIDE A FILE WRITE (task #302). The handler used to os._exit at once, and a
+# workspace write was open(path, "w") — which EMPTIES the file first — then write(): a Ctrl+C in
+# between left the user's file empty or cut off. Writes are now atomic (_ws_write_file), and a
+# stop that arrives DURING one only sets `requested`; the writer exits the moment it is done.
+# Anywhere else — a model call, which is most of a turn — the stop is immediate, as before.
+_STOP = {"writing": 0, "requested": False}
 
-def _on_sigterm(signum, frame):  # noqa: ARG001
+
+def _stop_now():
     for pid in list(_INFLIGHT_CMDS):
         _ws_kill_tree(pid, force=True)
     _INFLIGHT_CMDS.clear()
     try:
-        _log("stopped by the worker (SIGTERM) — killed the command in flight")
+        _log("stopped by the worker — killed the command in flight")
     except Exception:  # noqa: BLE001
         pass
     os._exit(143)
 
 
+def _request_stop():
+    if _STOP["writing"] > 0:
+        _STOP["requested"] = True
+        return
+    _stop_now()
+
+
+def _on_sigterm(signum, frame):  # noqa: ARG001
+    _request_stop()
+
+
+def _watch_stop_file(path: str):
+    """WINDOWS HAS NO SIGTERM: the worker's kill there is TerminateProcess, which no handler sees.
+    So the worker creates this file first and kills only after a grace period — and this thread
+    turns the file into the same safe stop the POSIX signal gets."""
+    import threading
+    import time as _t
+
+    def _loop():
+        while True:
+            try:
+                if os.path.exists(path):
+                    _request_stop()
+                    return
+            except Exception:  # noqa: BLE001
+                pass
+            _t.sleep(0.2)
+
+    threading.Thread(target=_loop, name="gu-stop-file", daemon=True).start()
+
+
 def _install_sigterm_handler():
     import signal
     try:
         signal.signal(signal.SIGTERM, _on_sigterm)
     except (ValueError, OSError):  # not the main thread, or a platform without it
         pass
+    stop_file = os.environ.get("GONEXT_STOP_FILE", "").strip()
+    if stop_file:
+        _watch_stop_file(stop_file)
+
+
+def _ws_write_file(path: str, content: str, action: str, backup) -> None:
+    """Write a workspace file SAFELY TO STOP AT ANY MOMENT (task #302).
+
+      1. The change goes on the undo list FIRST — a stop right after the write is still undoable.
+      2. The content goes to a temp file beside the target and is swapped in with os.replace, so
+         the file is always wholly the old version or wholly the new one, even under a hard kill.
+      3. A stop requested meanwhile waits for the swap (see _STOP), then happens.
+
+    A symlink is written THROUGH (its target is replaced, the link stays), as open(path, "w")
+    did. Windows can refuse the swap while another program holds the file; then it falls back to
+    the direct write rather than failing the edit.
+    """
+    import tempfile
+    _ws_record_change(action, path, backup)
+    target = os.path.realpath(path)
+    _STOP["writing"] += 1
+    try:
+        fd, tmp = tempfile.mkstemp(prefix=".gu-write-", suffix=".tmp", dir=os.path.dirname(target) or ".")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(content)
+                fh.flush()
+                os.fsync(fh.fileno())
+            if os.path.exists(target):
+                import shutil
+                shutil.copymode(target, tmp)
+            else:
+                mask = os.umask(0)
+                os.umask(mask)
+                os.chmod(tmp, 0o666 & ~mask)
+            try:
+                os.replace(tmp, target)
+            except PermissionError:
+                if not _IS_WINDOWS:
+                    raise
+                with open(target, "w", encoding="utf-8") as fh:
+                    fh.write(content)
+                os.unlink(tmp)
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+    finally:
+        _STOP["writing"] -= 1
+        if _STOP["writing"] == 0 and _STOP["requested"]:
+            _stop_now()
 
 
 def _ws_pgroup_pids(pgid: int) -> list:
@@ -10328,10 +10504,15 @@ def run_agent_chat(cfg):
                 # tries a normal error gets. The attempt count is decided per-error: we start
                 # with the generic budget and extend it the moment we see a gateway error.
                 attempt, max_attempts = 0, 3
+                # Task #302 part 3: when the network went away. None = online.
+                offline = {"since": None, "n": 0, "said": 0.0}
                 while attempt < max_attempts:
                     try:
                         msg = self._generate_once(*args, **kwargs)
                         last_err = None
+                        if offline["since"] is not None:
+                            _emit({"type": "step", "text": "Connection back — continuing"})
+                            _log(f"connection back after {time.monotonic() - offline['since']:.0f}s")
                         break
                     except Exception as e:  # noqa: BLE001
                         emsg = str(e)
@@ -10395,6 +10576,37 @@ def run_agent_chat(cfg):
                                 "names (for Ollama use the tag, e.g. qwen3:14b)."
                             ) from e
                         last_err = e
+                        # THE NETWORK WENT AWAY (task #302, part 3). Not an attempt: the same
+                        # step waits for the connection and is sent again — everything this turn
+                        # did so far is still in this process, so nothing is redone and nothing is
+                        # undone. Only a wait past the budget ends the turn, as FAILED (never as a
+                        # stop), with "continue" as the way on.
+                        if _is_offline(e, _host_of(coding_base_url)):
+                            _host = _host_of(coding_base_url)
+                            now = time.monotonic()
+                            if offline["since"] is None:
+                                offline.update(since=now, n=0, said=now)
+                                _emit({"type": "step", "text": (
+                                    f"Lost the connection to {_host} — waiting for it to come back…")})
+                            waited = now - offline["since"]
+                            budget = _offline_wait_budget()
+                            if waited < budget:
+                                offline["n"] += 1
+                                if now - offline["said"] >= 60:
+                                    offline["said"] = now
+                                    _emit({"type": "step", "text": (
+                                        f"Still waiting for the connection to {_host}… "
+                                        f"({waited / 60:.0f} min)")})
+                                delay = min(_offline_delay(offline["n"]), max(1.0, budget - waited))
+                                _log(f"offline ({_clip(emsg, 120)}) — waited {waited:.0f}s, "
+                                     f"retrying the same step in {delay:.0f}s")
+                                time.sleep(delay)
+                                continue
+                            raise _AgentOffline(
+                                f"Lost the connection to {_host} for {budget / 60:.0f} minutes, so "
+                                "the turn could not go on. The work so far is kept — nothing was "
+                                "undone. Type continue to pick up once you are back online."
+                            ) from e
                         # An OVERLOAD (429/rate limit, task #114) is its own class: the
                         # server answered and told us to slow down, so it needs a PATIENT,
                         # jittered backoff rather than the gateway policy's prompt re-send.
@@ -11997,9 +12209,7 @@ def run_agent_chat(cfg):
                     new_lines[-1] += "\n"
                 old_lines = lines[s - 1:e]
                 lines[s - 1:e] = new_lines
-                with open(rp, "w", encoding="utf-8") as fh:
-                    fh.writelines(lines)
-                _ws_record_change("edit", rp, backup)
+                _ws_write_file(rp, "".join(lines), "edit", backup)
                 _emit({"type": "step", "text": _render_edit_card(
                     "Update", rp,
                     f"Replaced lines {s}-{e} with {len(new_lines)} line(s)",
@@ -12046,9 +12256,7 @@ def run_agent_chat(cfg):
                     _last_obs["text"] = msg
                     return msg
                 backup = _ws_snapshot(rp)
-                with open(rp, "w", encoding="utf-8") as fh:
-                    fh.write(text.replace(old_string, new_string, 1))
-                _ws_record_change("edit", rp, backup)
+                _ws_write_file(rp, text.replace(old_string, new_string, 1), "edit", backup)
                 start_no = text[:text.index(old_string)].count("\n") + 1
                 old_ls = old_string.splitlines() or [""]
                 new_ls = new_string.splitlines() or [""]
@@ -12114,9 +12322,7 @@ def run_agent_chat(cfg):
                     return msg
                 backup = _ws_snapshot(rp) if existed else ""
                 os.makedirs(os.path.dirname(rp) or ".", exist_ok=True)
-                with open(rp, "w", encoding="utf-8") as fh:
-                    fh.write(content)
-                _ws_record_change("edit" if existed else "create", rp, backup or None)
+                _ws_write_file(rp, content, "edit" if existed else "create", backup or None)
                 content_ls = content.splitlines() or [""]
                 _emit({"type": "step", "text": _render_edit_card(
                     "Update" if existed else "Create", rp,

package/gu-cli.mjs

@@ -17,7 +17,8 @@ import { accent } from "./accent.mjs";
 requireSupportedNode();
 import { mkdir, mkdtemp, readFile, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { execFile as execFileCallback, spawn } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { writeFileSync, unlinkSync } from "node:fs";
 import { createTaskPool, createFolderQueue } from "./job-pools.mjs";
 import { NO_STEP, foldStepTokens, withStepTokens } from "./step-tokens.mjs";
 import { agentStoppedLine, jobEnded, jobStatusFrom409, stopGracefully } from "./agent-stop.mjs";
@@ -1743,6 +1744,39 @@ async function workerFetch(path, init = {}) {
   return fetch(url, { ...init, headers });
 }
 
+/**
+ * workerFetch that WAITS OUT A LOST NETWORK (task #302, part 3) — for the writes that must land,
+ * like a finished turn's result. A remote API unreachable is usually this machine being offline for
+ * a moment; the work is done and only its report is waiting, so it is retried with backoff for the
+ * offline budget (GONEXT_OFFLINE_WAIT_S, default 10 min) rather than lost. Only NETWORK errors are
+ * retried — an HTTP answer, even an error, is returned as it is — and a local API is not waited for
+ * (unreachable there means the API process is gone).
+ */
+async function workerFetchPatient(path, init = {}, { sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  let local = false;
+  try {
+    const h = new URL(apiBase).hostname;
+    local = h === "localhost" || h === "::1" || h.startsWith("127.");
+  } catch {
+    /* no base — the plain call will say so */
+  }
+  const budgetMs = (() => {
+    const v = Number(process.env.GONEXT_OFFLINE_WAIT_S);
+    return (Number.isFinite(v) && v >= 0 ? v : 600) * 1000;
+  })();
+  const started = Date.now();
+  for (let n = 1; ; n++) {
+    try {
+      return await workerFetch(path, init);
+    } catch (err) {
+      const network = err instanceof TypeError || /fetch failed|ECONN|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|socket hang up/i.test(String(err?.message ?? err));
+      if (local || !network || Date.now() - started >= budgetMs) throw err;
+      if (n === 1) console.log(`[gu-worker] ${path}: the API is unreachable (${String(err?.message ?? err).slice(0, 80)}) — waiting for the network`);
+      await sleep(Math.min(2000 * n, 15000));
+    }
+  }
+}
+
 async function ensureWorkerOk(res, context) {
   if (res.ok) return;
   const snippet = (await res.text().catch(() => "")).trim().slice(0, 500);
@@ -1887,29 +1921,12 @@ if (args[0] === "workspace") {
       console.error(`[gu-worker] workspace revert: no manifest for run ${runId} (${manifestPath})`);
       process.exit(1);
     }
-    let restored = 0, deleted = 0, failed = 0;
-    for (const c of manifest?.changes ?? []) {
-      try {
-        if (c.action === "edit" && c.backup && ex(c.backup)) {
-          await copyFile(c.backup, c.path);
-          restored += 1;
-          console.log(`  restored ${c.path}`);
-        } else if (c.action === "create" && ex(c.path)) {
-          await unlink(c.path);
-          deleted += 1;
-          console.log(`  deleted  ${c.path}`);
-        } else if (c.action === "create_dir" && ex(c.path)) {
-          // rmdir only removes an EMPTY dir — a revert must never destroy content
-          // the user (or a later run) put inside the created folder afterwards.
-          await rmdir(c.path);
-          deleted += 1;
-          console.log(`  removed  ${c.path}/`);
-        }
-      } catch (err) {
-        failed += 1;
-        console.error(`  FAILED   ${c.path}: ${err.message}`);
-      }
-    }
+    // One step per path from its EARLIEST entry (workspace-revert.mjs, #302): replaying the log
+    // in order deleted a file the run created and then brought it back from its "edit" backup.
+    const { planRevert, applyRevert } = await import("./workspace-revert.mjs");
+    const r = await applyRevert(planRevert(manifest?.changes ?? []), { exists: ex });
+    for (const l of r.lines) (l.startsWith("FAILED") ? console.error : console.log)(`  ${l}`);
+    const { restored, deleted, failed } = r;
     console.log(
       `[gu-worker] workspace revert ${runId}: ${restored} restored, ${deleted} created-file(s) deleted` +
         (failed ? `, ${failed} FAILED` : "") +
@@ -2452,7 +2469,11 @@ function runProcessWithStreamingStdout(cmd, cmdArgs, stdinStr, timeoutMs, onLine
     // lone surrogates and only blows up later, encoding the model request. gonext_agent_chat.py
     // also reconfigures its own streams; this covers the scripts that don't.
     const spawnOpts = { stdio: ["pipe", "pipe", "pipe"] };
-    spawnOpts.env = { ...process.env, PYTHONUTF8: "1", ...(extraEnv ?? {}) };
+    // Task #302: where to ask the agent to stop on Windows (see stopGracefully) — a file it
+    // watches, so a stop waits for a file write in progress instead of cutting it in half.
+    const stopFile = join(tmpdir(), `gu-agent-stop-${randomUUID()}`);
+    spawnOpts.env = { ...process.env, PYTHONUTF8: "1", GONEXT_STOP_FILE: stopFile, ...(extraEnv ?? {}) };
+    const requestStop = () => writeFileSync(stopFile, "stop");
     const child = spawn(cmd, cmdArgs, spawnOpts);
     let stderr = "";
     let lineBuffer = "";
@@ -2470,7 +2491,7 @@ function runProcessWithStreamingStdout(cmd, cmdArgs, stdinStr, timeoutMs, onLine
       if (typeof onTimeout !== "function") {
         timedOut = true;
         timerLive = false;
-        cancelHardKill = stopGracefully(child);
+        cancelHardKill = stopGracefully(child, { requestStop });
         return;
       }
       let extend = false;
@@ -2486,7 +2507,7 @@ function runProcessWithStreamingStdout(cmd, cmdArgs, stdinStr, timeoutMs, onLine
       }
       timedOut = true;
       timerLive = false;
-      cancelHardKill = stopGracefully(child);
+      cancelHardKill = stopGracefully(child, { requestStop });
     };
     const timer = setTimeout(fireTimeout, timeoutMs);
     // User-requested cancel (gu Ctrl+C): kill the Python agent so it stops burning
@@ -2497,7 +2518,7 @@ function runProcessWithStreamingStdout(cmd, cmdArgs, stdinStr, timeoutMs, onLine
     const onAbort = () => {
       if (aborted) return;
       aborted = true;
-      cancelHardKill = stopGracefully(child);
+      cancelHardKill = stopGracefully(child, { requestStop });
     };
     if (abortSignal) {
       if (abortSignal.aborted) onAbort();
@@ -2532,6 +2553,11 @@ function runProcessWithStreamingStdout(cmd, cmdArgs, stdinStr, timeoutMs, onLine
       timerLive = false;
       clearTimeout(timer);
       cancelHardKill();
+      try {
+        unlinkSync(stopFile);
+      } catch {
+        /* never asked to stop — no file */
+      }
       if (abortSignal) abortSignal.removeEventListener?.("abort", onAbort);
       // Drain any remaining buffered line
       const remaining = lineBuffer.trim();
@@ -4257,7 +4283,8 @@ async function runAgentChatJob(job) {
     await flushChunks();
 
     const totalTimeSeconds = (Date.now() - start) / 1000;
-    const doneRes = await workerFetch(`/api/worker/jobs/${jobId}`, {
+    // Patient (#302 part 3): the turn is DONE; a network blip now must not throw its result away.
+    const doneRes = await workerFetchPatient(`/api/worker/jobs/${jobId}`, {
       method: "PATCH",
       body: JSON.stringify({
         jobStatus: "completed",

package/gu-repl.mjs

@@ -25,6 +25,7 @@
  */
 import { readFile, mkdir, writeFile, unlink, rename } from "node:fs/promises";
 import { readStepTokens } from "./step-tokens.mjs";
+import { snapshotInput, restoreInput, replaceStoppedQuestion, stopNoteLines } from "./turn-stop.mjs";
 import { existsSync, statSync, readFileSync, writeFileSync, readdirSync, openSync, readSync, closeSync } from "node:fs";
 import { spawn } from "node:child_process";
 // FIRST, before anything that could itself fail on an old runtime: npm only WARNS about
@@ -867,6 +868,7 @@ const COMMANDS = [
   // they worked, Tab-completed to nothing, and appeared in no help. Aliases is what the registry
   // already has for exactly this — /quit, /rag-local.
   { name: "/host-mode", desc: "undo client mode — run agent turns on THIS machine again" },
+  { name: "/undo", usage: "/undo [runId]", desc: "put back the files the last stopped turn changed (from its backups) — asks first" },
   { name: "/server", desc: "pick a deployment server (host/user) for this session" },
   { name: "/proxy", usage: "/proxy [show|set|on|off|clear|test]", desc: "route MODEL calls through an HTTP proxy (local calls always go direct)" },
   { name: "/s3", usage: "/s3 [test]", desc: "set up YOUR S3 bucket (RAG index, and the PDFs/downloads gu makes) and check the AWS keys work — without it, files are saved on this computer" },
@@ -1505,6 +1507,14 @@ const stripAnsiEscapes = (s) =>
 const PASTE_MIN_CHARS = 200;
 const PASTE_MIN_LINES = 3;
 const pasteStore = new Map(); // token -> the real text
+// Task #302: the last line as TYPED — placeholders and all — taken before it is expanded for the
+// model, so a turn stopped with Ctrl+C can give the question back for editing.
+let lastSubmittedInput = null;
+// Task #302: set while the input holds a stopped turn's question; the next line sent from it
+// REPLACES that question in history when it was edited. Cleared by "never mind" (Ctrl+C).
+let prefillFor = null;
+// Task #302: the backup run of the last stopped turn — what /undo reverts by default.
+let lastStoppedRun = null;
 // ---------- pasted images (task #284) ----------
 const imageStore = createImageStore();
 // Shown on the bottom row after a refused or failed image paste; clears itself.
@@ -1619,6 +1629,23 @@ const isNetworkError = (e) =>
   /fetch failed|network|ECONN|ETIMEDOUT|EAI_AGAIN|socket hang up|und_err|terminated/i.test(
     String(e?.message ?? e)
   );
+/** Is the API on this machine? Then "unreachable" means the API process, not the network (#302). */
+const apiIsLocal = () => {
+  try {
+    const h = new URL(apiBase).hostname;
+    return h === "localhost" || h === "::1" || h === "[::1]" || h.startsWith("127.");
+  } catch {
+    return false;
+  }
+};
+/** How long a turn waits for the network (GONEXT_OFFLINE_WAIT_S, default 10 min) — the agent's own budget. */
+const offlineWaitMs = () => {
+  const v = Number(process.env.GONEXT_OFFLINE_WAIT_S);
+  return (Number.isFinite(v) && v >= 0 ? v : 600) * 1000;
+};
+// #302 part 3: a turn this terminal lost contact with (the network dropped) — its job may still be
+// running, so "continue" follows it again instead of asking the question a second time.
+let lostTurn = null;
 /**
  * Did OUR OWN deadline fire, rather than the connection failing? → boolean.
  *
@@ -1731,6 +1758,10 @@ rl.on("line", (l) => {
   // user pasted.
   // Images too (task #284): "[Image #1]" goes out as "[Image #1: <file>]" for the agent to
   // attach; the next message numbers its images from #1 again.
+  lastSubmittedInput = snapshotInput(stripAnsiEscapes(submitted), {
+    pastes: pasteStore,
+    images: new Map(imageStore.entries()),
+  });
   const clean = imageStore.expand(expandPasteTokens(stripAnsiEscapes(submitted)));
   imageStore.clear();
   const waiter = _lineWaiters.pop(); // innermost reader first — see _lineWaiters
@@ -6646,6 +6677,103 @@ async function runSavePresetCommand(line) {
  * key is saved under the preset's name and made that row's default, and the embedder is set. The
  * user reconfirms before anything changes, like /load-settings.
  */
+/**
+ * After Ctrl+C stopped THIS terminal's turn (task #302): say what it left behind, and give the
+ * question back.
+ *
+ *   · the command it was in the middle of, if any — that one cannot be made safe, only named
+ *   · the files it changed (its backup run's manifest) — kept as they are; /undo offers to put
+ *     them back, because part of the work may be wanted and nothing is reverted by itself
+ *   · the question, exactly as typed (placeholders and all), back in the input — edit it and
+ *     press Enter; Ctrl+C clears it. Never sent by itself.
+ *
+ * What the turn printed stays on screen: it is the record of what it did.
+ */
+async function afterStoppedTurn({ taskLine, submittedInput, turnStartMs, stoppedCommand = "", typed = "" }) {
+  let files = [];
+  try {
+    const ws = await import("./workspace-revert.mjs");
+    const runId = ws.runSince(turnStartMs);
+    if (runId) {
+      const changes = (await ws.readRunChanges(runId)) ?? [];
+      files = changes.filter((c) => c?.action !== "create_dir").map((c) => c.path);
+      if (files.length) lastStoppedRun = runId;
+    }
+  } catch {
+    /* no backups readable — nothing to name */
+  }
+  // A bare "continue" was the typed line: giving THAT back is no help, so only the note.
+  const canRestore = Boolean(submittedInput?.raw) && !isResumeWord(typed);
+  for (const l of stopNoteLines({ files, command: stoppedCommand, restored: canRestore })) {
+    console.log(GUTTER + dim(l));
+  }
+  console.log("");
+  if (!canRestore) return;
+  const text = restoreInput(submittedInput, { pasteStore, imageStore });
+  rl.line = text;
+  rl.cursor = text.length;
+  rl.historyIndex = -1;
+  prefillFor = { task: taskLine };
+  if (barPinned()) paintBar();
+}
+
+/**
+ * /undo — put back what a stopped turn changed (task #302): the last stopped turn's run, or the
+ * run named. Shows exactly what it will do and asks first — a file edited by hand since the turn
+ * would lose those edits, and that is said too.
+ */
+async function runUndoCommand(line) {
+  const ws = await import("./workspace-revert.mjs");
+  const named = line.trim().slice("/undo".length).trim();
+  const runId = named || lastStoppedRun;
+  console.log("");
+  if (!runId) {
+    console.log(GUTTER + dim("nothing to undo — /undo puts back what a turn you stopped with Ctrl+C changed."));
+    console.log(GUTTER + dim(`(older runs: ${ws.BACKUPS_ROOT} — /undo <run>)\n`));
+    return;
+  }
+  const changes = await ws.readRunChanges(runId);
+  if (!changes) {
+    console.log(GUTTER + red(`no backups for run ${runId}.\n`));
+    return;
+  }
+  const steps = ws.planRevert(changes);
+  if (!steps.length) {
+    console.log(GUTTER + dim("that turn changed no files.\n"));
+    return;
+  }
+  let manifestAt = 0;
+  try {
+    manifestAt = statSync(join(ws.BACKUPS_ROOT, runId, "manifest.json")).mtimeMs;
+  } catch {
+    /* unknown — no "edited since" warnings */
+  }
+  const verb = { restore: "restore", delete: "delete ", rmdir: "remove " };
+  for (const st of steps) {
+    let since = "";
+    try {
+      if (manifestAt && st.op !== "rmdir" && statSync(st.path).mtimeMs > manifestAt + 1000) {
+        since = yellow("  (changed since — those edits would be lost)");
+      }
+    } catch {
+      /* gone already */
+    }
+    console.log(GUTTER + `${verb[st.op]} ${st.path}` + since);
+  }
+  if (!(await askYesNo("Put these back?", false))) {
+    console.log(GUTTER + dim("(nothing changed)\n"));
+    return;
+  }
+  const r = await ws.applyRevert(steps);
+  for (const l of r.lines) console.log(GUTTER + dim(l));
+  console.log(
+    GUTTER + (r.failed ? yellow : dim)(
+      `${r.restored} restored, ${r.deleted} removed${r.failed ? `, ${r.failed} failed` : ""} — the backups are kept.`
+    ) + "\n"
+  );
+  if (runId === lastStoppedRun) lastStoppedRun = null;
+}
+
 async function runLoadPresetsCommand(line) {
   const pr = await import("./presets-transfer.mjs");
   const home = homedir();
@@ -9551,24 +9679,29 @@ async function ensureTokenForTurn() {
   return false;
 }
 
-async function runAgentTurn(history, { attachJobId = "" } = {}) {
+async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {}) {
   // #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.
   if (licenceBlock) {
     console.log(GUTTER + orange("Not sent.") + dim(" " + licenceBlock) + "\n");
     return;
   }
-  const attached = Boolean(attachJobId);
+  // TWO THINGS "attaching" used to mean at once (task #302, part 3): the question is NOT sent
+  // again (skipAsk), and the job is SOMEONE ELSE'S (attached — Ctrl+C only stops watching, its
+  // tokens are theirs to count). Re-attaching to this terminal's OWN turn after a lost connection
+  // is the first without the second: Ctrl+C there is a real cancel.
+  const skipAsk = Boolean(attachJobId);
+  const attached = skipAsk && !ownJob;
   // 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;
+  if (!skipAsk && !(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
   // claims the job, seconds away. This names what is actually happening meanwhile.
-  startPendingStatus(attached ? "attaching" : "sending");
-  const res = attached ? null : await fetch(`${apiBase}/api/worker/agent-ask`, {
+  startPendingStatus(skipAsk ? "attaching" : "sending");
+  const res = skipAsk ? null : await fetch(`${apiBase}/api/worker/agent-ask`, {
     method: "POST",
     headers: { "Content-Type": "application/json", "X-Worker-Key": workerKey },
     // cwd = this terminal's folder → agent puts download/unzip output here (when it's
@@ -9628,7 +9761,7 @@ async function runAgentTurn(history, { attachJobId = "" } = {}) {
     }
     throw new Error(data?.error || `agent-ask failed (HTTP ${res.status})`);
   }
-  const jobId = attached ? attachJobId : data?.jobId;
+  const jobId = skipAsk ? attachJobId : data?.jobId;
   if (!jobId) throw new Error("agent-ask returned no jobId.");
 
   // THE CODER WAS DROPPED, AND NOTHING SAID SO (task #222 phase 0). When the picked coding
@@ -9640,7 +9773,7 @@ async function runAgentTurn(history, { attachJobId = "" } = {}) {
   // Read off codingKeyMissingKnown, never off `data`: the flag lives under `payload` and this
   // response is a different shape, so reaching for it here would be undefined — falsy — and
   // warn nobody, which is the bug agent-payload-shape.test.mjs exists to catch.
-  if (!attached && codingKeyMissingKnown === true) {
+  if (!skipAsk && codingKeyMissingKnown === true) {
     console.log(
       GUTTER + orange("⚠ no API key for the coding model") +
         dim(" — coding is running on your chat model. ctrl+k to set it.\n")
@@ -9652,7 +9785,7 @@ async function runAgentTurn(history, { attachJobId = "" } = {}) {
   // hand-over to the turn's own ticker happens the moment that worker claims it. An ATTACHED
   // job is usually already running, so it says what is true of it instead — the poll below
   // corrects either of them within a second.
-  setPendingStatus(attached ? "attaching — reading its progress" : "queued — waiting for the worker");
+  setPendingStatus(skipAsk ? "attaching — reading its progress" : "queued — waiting for the worker");
   following = true;
   followingAttached = attached;
   typedDuringTurn = false;
@@ -9694,6 +9827,7 @@ async function runAgentTurn(history, { attachJobId = "" } = {}) {
   // key lookup failed." — a cold Mongo connection, NOT a bad key) must NOT kill a
   // long-running turn. Tolerate a run of them; only give up after too many in a row.
   let pollFailures = 0;
+  let pollOfflineSince = 0; // #302 part 3: when a remote API stopped answering (0 = reachable)
   const MAX_POLL_FAILURES = 6; // ~6 tries with backoff before conceding the follow
   let jobRunning = false; // only tick "thinking…" once the worker has claimed the job
   // Sticky: the agent RAN, so the coding model was called ("thinking…" was on screen). A
@@ -10534,6 +10668,7 @@ async function runAgentTurn(history, { attachJobId = "" } = {}) {
         if (jr.ok) {
           job = parsed;
           pollFailures = 0; // a clean poll resets the tolerance window
+          pollOfflineSince = 0;
         } else if (jr.status >= 400 && jr.status < 500) {
           // Client error (bad/expired key, job genuinely gone) — NOT transient, fail fast.
           throw new Error(parsed?.error || `job poll failed (HTTP ${jr.status})`);
@@ -10549,11 +10684,33 @@ async function runAgentTurn(history, { attachJobId = "" } = {}) {
         const transient = err?.transient === true || isNetworkError(err);
         if (!transient) throw err;
         pollFailures += 1;
-        if (pollFailures >= MAX_POLL_FAILURES) {
+        // THE NETWORK, NOT THE API (task #302, part 3). A REMOTE API that cannot be reached is
+        // usually this machine being offline — a Wi-Fi drop, a VPN reconnecting — while the turn
+        // itself carries on on its worker. So a network error is waited out for the same budget
+        // the agent gives its own calls, instead of giving up after ~13s. A LOCAL API unreachable
+        // is the API process itself gone (see "Agent killed its own API"), which waiting will not
+        // fix — that keeps the quick give-up.
+        const offlineWait = isNetworkError(err) && !apiIsLocal() ? offlineWaitMs() : 0;
+        if (offlineWait) {
+          if (!pollOfflineSince) pollOfflineSince = Date.now();
+          const waited = Date.now() - pollOfflineSince;
+          if (waited < offlineWait) {
+            setPendingStatus(`reconnecting to the API… (${Math.round(waited / 1000)}s)`);
+            await sleep(Math.min(1000 * pollFailures, 10000)); // backoff, capped at 10s
+            continue;
+          }
+        }
+        if (offlineWait || pollFailures >= MAX_POLL_FAILURES) {
           clearStatus();
-          throw new Error(
-            `lost contact with the API after ${pollFailures} tries (${String(err.message).slice(0, 80)}). ` +
-              "The turn may still be running on the worker — try 'continue'."
+          // The job id travels with the error: the turn may well still be running on its worker,
+          // and "continue" should FOLLOW it again rather than ask the same question twice.
+          throw Object.assign(
+            new Error(
+              `lost contact with the API after ${offlineWait ? `${Math.round(offlineWait / 60000)} min` : `${pollFailures} tries`} ` +
+                `(${String(err.message).slice(0, 80)}). The turn may still be running on the worker — ` +
+                "type continue to follow it again."
+            ),
+            { lostJobId: jobId }
           );
         }
         await sleep(Math.min(700 * pollFailures, 3000)); // linear backoff, capped at 3s
@@ -10784,7 +10941,7 @@ async function runAgentTurn(history, { attachJobId = "" } = {}) {
         // turn (main() drops it from history).
         clearStatus();
         process.stdout.write("\n" + GUTTER + dim("(cancelled — the agent was stopped)") + "\n");
-        return { text: "", shown: false, cancelled: true, started: reachedModel };
+        return { text: "", shown: false, cancelled: true, started: reachedModel, stoppedCommand: runningCmd || "" };
       }
       if (job.jobStatus === "failed") {
         clearStatus();
@@ -11637,6 +11794,7 @@ async function main() {
     rl.line = "";
     rl.cursor = 0;
     rl.historyIndex = -1;
+    prefillFor = null; // "never mind" also lets go of a restored question (#302)
     if (_lineQueue.length > 0) _lineQueue.length = 0;
     prunePasteStore("");
     imageStore.clear();
@@ -11768,6 +11926,12 @@ async function main() {
     footerActive = false; // a line arrived from the queue (no Enter keypress) → disarm
     if (lineRaw === null) break; // stdin closed
     const line = lineRaw.trim();
+    // #302: what was typed for THIS line (before expansion), and whether it was sent from a
+    // stopped turn's restored question.
+    const submittedInput = lastSubmittedInput;
+    lastSubmittedInput = null;
+    const editedFrom = prefillFor?.task ?? "";
+    prefillFor = null;
     // readline's echo is suppressed while the input line is frozen, so the submitted question
     // is printed here instead — it belongs in the scrollback like every other line. Its marker
     // is the GREY one: the cyan ">>" belongs to the live input line alone.
@@ -11902,6 +12066,10 @@ async function main() {
       await runS3Command(line);
       continue;
     }
+    if (line === "/undo" || line.startsWith("/undo ")) {
+      await runUndoCommand(line);
+      continue;
+    }
     if (line === "/save-preset" || line.startsWith("/save-preset ")) {
       await runSavePresetCommand(line);
       continue;
@@ -12154,6 +12322,10 @@ async function main() {
     // mid-retry still has something to resume next time.
     sessionUnfinishedTask = "";
     const { task: taskLine, resumed, nothingToResume } = resumeTask(line, pendingResume);
+    // #302 part 3: "continue" after a lost connection FOLLOWS the job that may still be running,
+    // rather than sending the question again. Anything else typed lets it go.
+    const reattach = lostTurn && isResumeWord(line) && lostTurn.taskLine === taskLine ? lostTurn : null;
+    lostTurn = null;
     // "continue" with nothing behind it runs NOTHING (task #201). It used to be sent to the
     // model as the literal word, which then got remembered as the unfinished task — so every
     // later "continue" retried "continue". Worse than the loop: with no task the model invents
@@ -12172,6 +12344,9 @@ async function main() {
     // "where were we?" reached the model with no history and it said nothing had been asked.
     // Only the failure NOTICE stays out of history (task #144). A resume, or the same question
     // typed again after a failure, is already the last entry and is not pushed a second time.
+    // #302: the restored question, EDITED and sent — a change of mind, so it takes the stopped
+    // one's place instead of standing beside it (then the block below sees it as pending).
+    if (editedFrom) replaceStoppedQuestion(history, editedFrom, taskLine);
     if (isPendingQuestion(history, taskLine)) {
       delete history[history.length - 1].status; // it is the current task again, not a stopped one
     } else {
@@ -12179,7 +12354,9 @@ async function main() {
     }
     await saveSession(cwd, history, { unfinishedTask: isResumeWord(taskLine) ? "" : taskLine });
     try {
-      const turn = await runAgentTurn(history);
+      const turnStartMs = Date.now();
+      if (reattach) console.log(GUTTER + dim("following the turn that was running when the connection went…\n"));
+      const turn = await runAgentTurn(history, reattach ? { attachJobId: reattach.jobId, ownJob: true } : {});
       // NOT SENT (licence block, or the token prompt declined): runAgentTurn already said so.
       // Nothing began, and "continue" can send it once the cause is fixed (task #247).
       if (!turn) {
@@ -12188,7 +12365,7 @@ async function main() {
         continue;
       }
       const { text: answer, shown, cancelled, started, detached, inputTokens, outputTokens,
-              turnOutputTokens, elapsedMs } = turn;
+              turnOutputTokens, elapsedMs, stoppedCommand } = turn;
       // Detached: the agent keeps running on the worker, so the question is neither answered
       // nor stopped — leave it untagged, and say nothing contradicting "the job keeps running".
       if (detached) continue;
@@ -12285,6 +12462,7 @@ async function main() {
           // Stopped AFTER the model was called = too slow or stuck, never a change of mind: the
           // request still stands (task #247, the user's rule). Before that, nothing had begun.
           await markInterrupted(cwd, history, taskLine, started ? "stopped" : "cancelled");
+          await afterStoppedTurn({ taskLine, submittedInput, turnStartMs, stoppedCommand, typed: line });
         } else {
           await markInterrupted(cwd, history, taskLine, "failed");
           // The turn ended cleanly but empty — no exception to summarize, so say exactly that.
@@ -12297,6 +12475,8 @@ async function main() {
       // turn that just threw auto-fire the next one.
       if (_lineQueue.length > 0) _lineQueue.length = 0;
       await rememberUnfinishedTask(cwd, taskLine); // …and "continue" can retry it (task #150)
+      // #302 part 3: the connection went, not the turn — keep its job so "continue" follows it.
+      lostTurn = err?.lostJobId ? { jobId: err.lostJobId, taskLine } : null;
       printTurnError(err?.message, {
         resumable: true,
         failures: noteTaskFailure(taskLine, classifyTurnFailure(err?.message)),

package/image-paste.mjs

@@ -248,6 +248,16 @@ export function createImageStore() {
       const present = new Set(String(line ?? "").match(TOKEN_RE) ?? []);
       for (const t of [...store.keys()]) if (!present.has(t)) store.delete(t);
     },
+    /** The live entries — snapshotted when a line is sent, so a stopped turn can give it back (#302). */
+    entries() {
+      return [...store];
+    },
+    /** Put one back exactly as it was (#302): same token, and later images number after it. */
+    restore(token, path) {
+      store.set(token, path);
+      const n = Number(/#(\d+)/.exec(String(token))?.[1]);
+      if (Number.isFinite(n) && n > seq) seq = n;
+    },
     /** After a message is sent: the next one numbers its images from #1 again. */
     clear() {
       store.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.769",
+  "version": "1.0.770",
   "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",
@@ -52,6 +52,8 @@
     "step-tokens.mjs",
     "model-setup-ui.mjs",
     "setup-prompts.mjs",
+    "turn-stop.mjs",
+    "workspace-revert.mjs",
     "terminal-hover.mjs",
     "terminal-layout.mjs",
     "terminal-viewport.mjs",

package/turn-stop.mjs

@@ -0,0 +1,78 @@
+/**
+ * AFTER Ctrl+C STOPS A TURN — the question goes back in the input, and what the turn changed is
+ * named (task #302). Pure helpers; gu-repl.mjs does the drawing.
+ *
+ * Asked for: "for a couple of seconds the thinking is still in process and the user thinks again
+ * and wants to change the question" — as Claude Code does. The screen keeps what the turn printed
+ * (the record of what it did); files are NOT reverted by themselves (part of the work may be
+ * wanted, and a command that ran cannot be undone) — /undo offers that as a choice.
+ */
+
+const PASTE_TOKEN_RE = /\[Pasted text #\d+(?: \+\d+ lines)?\]/g;
+const IMAGE_TOKEN_RE = /\[Image #\d+\]/g;
+
+/**
+ * What was TYPED, captured at the moment the line is submitted — before the pasted blocks and the
+ * images are expanded for the model and their stores are cleared. Only the entries whose
+ * placeholder is actually in the line are kept.
+ */
+export function snapshotInput(raw, { pastes = new Map(), images = new Map() } = {}) {
+  const text = String(raw ?? "");
+  const keep = (re, store) => {
+    const present = new Set(text.match(re) ?? []);
+    return [...store].filter(([token]) => present.has(token));
+  };
+  return { raw: text, pastes: keep(PASTE_TOKEN_RE, pastes), images: keep(IMAGE_TOKEN_RE, images) };
+}
+
+/**
+ * Put a snapshot back: its placeholders' payloads return to the stores, and the typed text is
+ * returned for the input line. Nothing is renumbered — the text is shown exactly as it was.
+ */
+export function restoreInput(snap, { pasteStore, imageStore } = {}) {
+  if (!snap) return "";
+  for (const [token, text] of snap.pastes ?? []) pasteStore?.set(token, text);
+  for (const [token, path] of snap.images ?? []) imageStore?.restore?.(token, path);
+  return String(snap.raw ?? "");
+}
+
+/**
+ * The restored question was EDITED and sent: that is a change of mind, so the abandoned version
+ * must not stay in history beside the new one (the model would take both as asks). Only when the
+ * last entry IS that stopped question; returns whether it replaced it.
+ *
+ * Sending it UNCHANGED is not handled here — the existing pending-question path re-runs it. And a
+ * question cleared and replaced by something else keeps its "still stands" tag (task #247).
+ */
+export function replaceStoppedQuestion(history, oldTask, newTask) {
+  const last = Array.isArray(history) ? history[history.length - 1] : null;
+  const was = String(oldTask ?? "").trim();
+  const now = String(newTask ?? "").trim();
+  if (!last || last.role !== "user" || !last.status || !was || !now || was === now) return false;
+  if (String(last.content ?? "").trim() !== was) return false;
+  last.content = now;
+  delete last.status;
+  return true;
+}
+
+/** Short relative names for the stop note: the last two path parts. */
+function shortPath(p) {
+  const parts = String(p ?? "").split(/[\\/]/).filter(Boolean);
+  return parts.slice(-2).join("/") || String(p ?? "");
+}
+
+/**
+ * The lines under a stopped turn. `files` = the paths the turn changed (from its run's manifest),
+ * `command` = the command it was in the middle of, if any.
+ */
+export function stopNoteLines({ files = [], command = "", restored = true } = {}) {
+  const out = [];
+  if (command) out.push(`stopped while running \`${command}\` — it may be incomplete; run it again if you need it`);
+  const uniq = [...new Set(files)];
+  if (uniq.length) {
+    const shown = uniq.slice(0, 3).map(shortPath).join(", ") + (uniq.length > 3 ? ` +${uniq.length - 3} more` : "");
+    out.push(`this turn changed ${uniq.length} file${uniq.length === 1 ? "" : "s"}: ${shown} — /undo puts ${uniq.length === 1 ? "it" : "them"} back`);
+  }
+  if (restored) out.push("your question is back in the input — edit it and press Enter, or Ctrl+C to clear it");
+  return out;
+}

package/workspace-revert.mjs

@@ -0,0 +1,106 @@
+/**
+ * UNDO AN AGENT RUN'S FILE CHANGES — shared by `gu-cli workspace revert` and the terminal's /undo
+ * (task #302).
+ *
+ * Every agent run keeps ~/.gonext/workspace-backups/<runId>/: a copy of each file taken before its
+ * FIRST edit in that run, and manifest.json listing every change (gonext_agent_chat.py
+ * _ws_snapshot / _ws_record_change). Undo puts the ORIGINAL state back.
+ *
+ * WHY A PLAN, NOT A REPLAY. The manifest is a log, and a file can appear in it more than once. The
+ * old revert replayed it in order — so a file the run CREATED and then edited was deleted (the
+ * "create" entry) and then brought back by the "edit" entry's backup, which is a copy of the file
+ * the run had just created. What matters is each path's EARLIEST entry: it says what the file was
+ * before the run touched it. Created → delete it; edited → restore the copy taken before the first
+ * edit; a created folder → remove it only if empty.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { copyFile, readFile, rmdir, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const BACKUPS_ROOT = join(homedir(), ".gonext", "workspace-backups");
+
+/** The manifest's changes → one step per path, from its earliest entry. Pure. */
+export function planRevert(changes) {
+  const first = new Map();
+  for (const c of Array.isArray(changes) ? changes : []) {
+    if (!c || typeof c.path !== "string" || !c.path) continue;
+    if (!first.has(c.path)) first.set(c.path, c);
+  }
+  const steps = [];
+  for (const c of first.values()) {
+    if (c.action === "edit" && c.backup) steps.push({ op: "restore", path: c.path, backup: c.backup });
+    else if (c.action === "create") steps.push({ op: "delete", path: c.path });
+    else if (c.action === "create_dir") steps.push({ op: "rmdir", path: c.path });
+  }
+  // Files before folders, deepest folders first — a created folder can only go once it is empty.
+  const rank = { restore: 0, delete: 0, rmdir: 1 };
+  return steps.sort((a, b) => rank[a.op] - rank[b.op] || (a.op === "rmdir" ? b.path.length - a.path.length : 0));
+}
+
+/** The run directories, oldest first (names are timestamps, so they sort). */
+export function listRuns(root = BACKUPS_ROOT) {
+  try {
+    return readdirSync(root).filter((d) => !d.startsWith(".")).sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The run a turn produced: the newest run whose manifest was written at or after `sinceMs`.
+ * Every run is one agent process, and every turn is one process — so a run touched after the turn
+ * began belongs to it. null when the turn changed nothing (or ran on another machine).
+ */
+export function runSince(sinceMs, root = BACKUPS_ROOT) {
+  const runs = listRuns(root).reverse();
+  for (const id of runs) {
+    try {
+      if (statSync(join(root, id, "manifest.json")).mtimeMs >= sinceMs - 1000) return id;
+    } catch {
+      /* a run with no manifest changed nothing */
+    }
+  }
+  return null;
+}
+
+/** A run's changes, or null when it has no readable manifest. */
+export async function readRunChanges(runId, root = BACKUPS_ROOT) {
+  try {
+    const m = JSON.parse(await readFile(join(root, runId, "manifest.json"), "utf8"));
+    return Array.isArray(m?.changes) ? m.changes : [];
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Carry out a plan. → { restored, deleted, failed, lines } — `lines` says what happened to each
+ * path, for the caller to print. Never throws; a step that fails is reported and the rest go on.
+ */
+export async function applyRevert(steps, { exists = existsSync } = {}) {
+  let restored = 0, deleted = 0, failed = 0;
+  const lines = [];
+  for (const s of steps) {
+    try {
+      if (s.op === "restore" && exists(s.backup)) {
+        await copyFile(s.backup, s.path);
+        restored += 1;
+        lines.push(`restored ${s.path}`);
+      } else if (s.op === "delete" && exists(s.path)) {
+        await unlink(s.path);
+        deleted += 1;
+        lines.push(`deleted  ${s.path}`);
+      } else if (s.op === "rmdir" && exists(s.path)) {
+        // rmdir removes only an EMPTY folder — undo never destroys what someone put inside later.
+        await rmdir(s.path);
+        deleted += 1;
+        lines.push(`removed  ${s.path}/`);
+      }
+    } catch (err) {
+      failed += 1;
+      lines.push(`FAILED   ${s.path}: ${err.message}`);
+    }
+  }
+  return { restored, deleted, failed, lines };
+}