@tiens.nguyen/gu-cli 1.0.751 → 1.0.753

package/agent-stop.mjs

@@ -0,0 +1,69 @@
+/**
+ * When to stop a running agent, and how (runaway fix, 2026-09-25).
+ *
+ * WHAT HAPPENED. A turn ran `sdkmanager` for longer than 5 minutes without an update, so the API
+ * marked the job FAILED. The worker only ever stopped the agent for CANCELLED (Ctrl+C), so the
+ * agent carried on for 22 more steps nobody could see: 618 of its updates were rejected with 409,
+ * it booted an emulator four times and deleted two other emulators' data — and nothing would
+ * have stopped it before the 6-hour time budget. A job that is no longer `running` has nobody
+ * reading it; every further step is invisible work, invisible cost and invisible side effects.
+ *
+ * AND HOW. The agent used to get SIGKILL, which it cannot see, so a command it was in the middle
+ * of (its own process group, by design, so servers can outlive a turn) kept running with nothing
+ * tracking it. Now it gets SIGTERM first — the python kills the command in flight and exits —
+ * and SIGKILL only if it has not gone after a grace period, so a stop can never hang.
+ */
+
+/** Statuses after which nobody will read the job again. */
+const ENDED = new Set(["cancelled", "failed", "completed"]);
+
+/** Has the job ended on the API (so the agent must stop)? */
+export function jobEnded(status) {
+  return ENDED.has(String(status ?? "").trim().toLowerCase());
+}
+
+/** The job status named in a 409 body like {"error":"…","jobStatus":"failed"} ("" if none). */
+export function jobStatusFrom409(body) {
+  const text = String(body ?? "");
+  try {
+    const s = JSON.parse(text)?.jobStatus;
+    if (typeof s === "string") return s;
+  } catch {
+    /* a cut or non-JSON body — fall through to the pattern */
+  }
+  return /"jobStatus"\s*:\s*"([a-z]+)"/i.exec(text)?.[1] ?? "";
+}
+
+/** How long the agent gets to kill what it started before it is killed. */
+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 */
+  }
+  const t = setTimer(() => {
+    if (child.exitCode === null && child.signalCode === null) {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        /* already gone */
+      }
+    }
+  }, graceMs);
+  return () => clearTimer(t);
+}
+
+/** The worker-log line for an agent the API stopped. */
+export function agentStoppedLine(jobId, stoppedBy) {
+  if (!stoppedBy || stoppedBy === "cancelled") return `[gu-worker] agent_chat ${jobId} cancelled by user`;
+  return (
+    `[gu-worker] agent_chat ${jobId} stopped: the job is ${stoppedBy} on the API, so nobody ` +
+    "would see further steps — the agent and the command it was running were stopped"
+  );
+}

package/gonext_agent_chat.py

@@ -6578,7 +6578,62 @@ _WS_DESTRUCTIVE_RE = re.compile(
 )
 
 
-def _ws_command_risk(command, argv, denyset):
+# A DELETE OUTSIDE THE PROJECT IS THE USER'S CALL (runaway fix, 09-25). The destructive pattern
+# above only knows `rm -r` / `rm -f`, so `rm a.img b.img` sailed through: an unattended agent,
+# short of disk space, deleted two OTHER emulators' userdata-qemu.img in ~/.android/avd — files
+# outside the project nobody had mentioned. Inside a workspace (build output, its own temp
+# files) and the system temp folder deleting stays free; anywhere else it asks.
+_WS_DELETE_RUNNERS = {"rm", "rmdir", "unlink", "del", "erase", "rd", "remove-item", "trash"}
+
+
+def _ws_delete_targets(argv):
+    """The paths a delete command would remove ([] = not a delete)."""
+    if not argv:
+        return []
+    runner = os.path.basename(argv[0]).lower()
+    if runner.endswith(".exe"):
+        runner = runner[:-4]
+    if runner in _WS_DELETE_RUNNERS:
+        return [a for a in argv[1:] if a and not a.startswith("-") and a != "--"]
+    if runner == "find" and any(a in ("-delete",) for a in argv[1:]):
+        # `find <paths…> <expression>`: the paths come before the first expression token.
+        out = []
+        for a in argv[1:]:
+            if a.startswith("-") or a in ("(", "!"):
+                break
+            out.append(a)
+        return out or ["."]
+    return []
+
+
+def _ws_is_inside(path, roots):
+    return any(path == r or path.startswith(r.rstrip(os.sep) + os.sep) for r in roots)
+
+
+def _ws_delete_outside_reason(argv, wd, roots=None):
+    """Why this delete needs the user's yes, or None when every target is inside a workspace or
+    the temp folder. Paths are resolved from `wd`, with ~ expanded and symlinks followed."""
+    import tempfile
+    targets = _ws_delete_targets(argv)
+    if not targets:
+        return None
+    ws = [os.path.realpath(r["path"]) for r in (_WS_ROOTS if roots is None else roots) if r.get("path")]
+    if not ws:
+        return None  # no workspace registered (run_command needs one) — nothing to measure against
+    temp = [os.path.realpath(p) for p in {tempfile.gettempdir(), "/tmp", "/var/tmp"} if p]
+    outside = []
+    for t in targets:
+        p = os.path.expanduser(t)
+        p = os.path.realpath(p if os.path.isabs(p) else os.path.join(wd or os.getcwd(), p))
+        if not (_ws_is_inside(p, ws) or _ws_is_inside(p, temp)):
+            outside.append(t)
+    if not outside:
+        return None
+    return ("it deletes files OUTSIDE the project (" + ", ".join(outside[:3])
+            + (" …" if len(outside) > 3 else "") + ")")
+
+
+def _ws_command_risk(command, argv, denyset, wd=""):
     """Classify a command for the run policy. Returns (hard_reason, ask_reason), either
     None when N/A:
     - hard_reason: block outright when we CAN'T ask (web / non-interactive) — privilege
@@ -6595,6 +6650,11 @@ def _ws_command_risk(command, argv, denyset):
     if denyset and (runner in denyset or rbase in denyset):
         r = f"'{runner}' is on your blocked-commands list"
         return (r, r)
+    # Before the destructive pattern: `rm -rf ~/x` is both, and "outside the project" is the part
+    # the user needs to hear. Hard-blocked too when nobody can be asked (web / unattended).
+    outside = _ws_delete_outside_reason(argv, wd)
+    if outside:
+        return (outside, outside)
     if _WS_DESTRUCTIVE_RE.search(cmd):
         return (None, "a destructive command (deletes files / wipes disk / powers off)")
     return (None, None)
@@ -6722,6 +6782,33 @@ def _ws_kill_tree(pid: int, force: bool = False) -> None:
         pass
 
 
+# COMMANDS IN FLIGHT DIE WITH THE AGENT (runaway fix, agent-stop.mjs). run_command gives each
+# command its own process group so a server can outlive the turn — which also meant a command
+# the agent was in the MIDDLE of (a download, a build, an emulator boot) outlived a killed agent
+# with nothing tracking it. The worker now sends SIGTERM before SIGKILL; this handler kills
+# what is still in flight and exits. Servers/apps already left running are not in this set.
+_INFLIGHT_CMDS: set = set()
+
+
+def _on_sigterm(signum, frame):  # noqa: ARG001
+    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")
+    except Exception:  # noqa: BLE001
+        pass
+    os._exit(143)
+
+
+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
+
+
 def _ws_pgroup_pids(pgid: int) -> list:
     """Live pids in a process group (the server + everything it spawned)."""
     import subprocess
@@ -7002,6 +7089,107 @@ def _rag_s3_client(region: str, akid: str, secret: str):
     )
 
 
+# PASTED IMAGES (task #284). The REPL sends "[Image #1: <file>]" in the message text (the API
+# passes text only); the file is in ~/.gonext/images, copied there at paste time. The CURRENT
+# question's images are attached to the request for a Claude coder (the adapter turns them into
+# Anthropic image blocks); the model reads "[Image #1]". Older messages keep only the label —
+# their images are not re-sent. Files are read from ~/.gonext/images and nowhere else: the
+# marker is text, and text can be typed.
+_IMAGE_MARKER_RE = re.compile(r"\[Image #(\d+): ([^\]\n]+)\]")
+_MAX_TURN_IMAGES = 20
+
+
+def _take_image_markers(messages, images_dir=None):
+    """Rewrite the markers in `messages` (in place). → the latest user message's image files,
+    in order, as [(label, path)] — only files that exist inside the images folder."""
+    root = os.path.realpath(images_dir or os.path.join(os.path.expanduser("~"), ".gonext", "images"))
+    last_user = max((i for i, m in enumerate(messages) if isinstance(m, dict) and m.get("role") == "user"),
+                    default=-1)
+    found = []
+    for i, m in enumerate(messages):
+        if not isinstance(m, dict) or not isinstance(m.get("content"), str):
+            continue
+
+        def _sub(mt, current=(i == last_user)):
+            label = f"[Image #{mt.group(1)}]"
+            if not current:
+                return f"{label} (an earlier image — not shown again)"
+            path = os.path.realpath(os.path.expanduser(mt.group(2).strip()))
+            if not path.startswith(root + os.sep) or not os.path.isfile(path):
+                return f"{label} (the image could not be read)"
+            if len(found) >= _MAX_TURN_IMAGES:
+                return f"{label} (not attached — at most {_MAX_TURN_IMAGES} images per message)"
+            found.append((label, path))
+            return label
+        m["content"] = _IMAGE_MARKER_RE.sub(_sub, m["content"])
+    return found
+
+
+# WHAT CLAUDE WILL TAKE (task #285). smolagents re-encodes every image as PNG, base64, before
+# sending (smolagents.utils.encode_image_base64) — so a 4 MB JPEG photo can become a PNG over the
+# 5 MB per-image limit, and then Claude rejects the WHOLE request, not just the image. Claude
+# also scales anything with a long edge over 1568 px down to that (and rejects > 8000 px), so
+# shrinking first sends the same picture Claude would see, in fewer bytes.
+_IMAGE_MAX_EDGE = 1568
+_IMAGE_MAX_B64 = 5 * 1024 * 1024  # measured on the base64 string — the stricter reading
+
+
+def _png_b64_len(im) -> int:
+    import io
+    buf = io.BytesIO()
+    im.save(buf, format="PNG")
+    return (len(buf.getvalue()) + 2) // 3 * 4
+
+
+def _prepare_image(path):
+    """Open `path` and return a PIL image Claude will accept, or raise ValueError(reason)."""
+    from PIL import Image
+    try:
+        with Image.open(path) as src:
+            src.load()  # a truncated or non-image file fails here, not later in the request
+            im = src.copy()
+    except Image.DecompressionBombError:
+        raise ValueError("too many pixels to open safely") from None
+    except Exception as e:  # noqa: BLE001
+        raise ValueError(f"not a readable image ({type(e).__name__})") from None
+    # Colour modes PNG cannot hold, or holds oddly: CMYK photos, 16-bit, float, palette.
+    if im.mode == "P":
+        im = im.convert("RGBA" if "transparency" in im.info else "RGB")
+    elif im.mode not in ("RGB", "RGBA", "L", "LA"):
+        im = im.convert("RGBA" if "A" in im.mode else "RGB")
+    if max(im.size) > _IMAGE_MAX_EDGE:
+        im.thumbnail((_IMAGE_MAX_EDGE, _IMAGE_MAX_EDGE), Image.LANCZOS)
+    while _png_b64_len(im) > _IMAGE_MAX_B64:
+        if max(im.size) <= 256:
+            raise ValueError("still over 5 MB after shrinking")
+        im = im.resize((max(1, im.width * 3 // 4), max(1, im.height * 3 // 4)), Image.LANCZOS)
+    return im
+
+
+def _load_turn_images(refs):
+    """[(label, path)] → (PIL images ready for Claude, [(label, reason)] for the ones that failed)."""
+    out, failed = [], []
+    try:
+        import PIL  # noqa: F401
+    except Exception:  # noqa: BLE001
+        return out, [(label, "image support (Pillow) is not installed") for label, _ in refs]
+    for label, path in refs:
+        try:
+            out.append(_prepare_image(path))
+        except ValueError as e:
+            failed.append((label, str(e)))
+            _log(f"image {label}: not attached — {e}")
+    return out, failed
+
+
+def _label_failed_images(text, failed):
+    """Say which images did not make it, where the model reads their labels — a bare
+    "[Image #1]" with nothing attached invites the model to guess what it shows."""
+    for label, reason in failed:
+        text = text.replace(label, f"{label} (could not be opened: {reason})")
+    return text
+
+
 def run_agent_chat(cfg):
     # Task #249: what this run may log — set FIRST, before anything is logged (the history and the
     # current task are logged early, and a real turn caught them leaking when this came later).
@@ -7031,6 +7219,7 @@ def run_agent_chat(cfg):
         return
 
     messages = cfg.get("messages") or []
+    _turn_image_refs = _take_image_markers(messages)
     agent_base_url = cfg.get("agentBaseURL") or ""
     # THE PROXY, configured before any client is built (task #160). The allowlist is the three
     # model endpoints as the WORKER resolved them; the raw cfg values are used rather than the
@@ -11893,6 +12082,7 @@ def run_agent_chat(cfg):
                 workdir: directory to run in. Empty = first registered workspace.
                 timeout_seconds: give up after this many seconds if the command neither exits nor starts a server (max 600).
             """
+            proc = None  # read by the `finally` below, which runs even if Popen never did
             try:
                 import os
                 import shlex
@@ -12009,7 +12199,7 @@ def run_agent_chat(cfg):
                 # Risk gate: privilege escalation / denylisted / destructive. When the
                 # client can approve interactively (terminal), PAUSE and ask the user;
                 # otherwise (web) keep hard-blocking the privilege/denylist cases.
-                _hard_reason, _ask_reason = _ws_command_risk(command, argv, _WS_RUN_DENYLIST)
+                _hard_reason, _ask_reason = _ws_command_risk(command, argv, _WS_RUN_DENYLIST, wd)
                 # Shift+Tab may have switched it since the turn started (#47).
                 global _accept_edits
                 if _interactive_approval and _job_id:
@@ -12092,6 +12282,7 @@ def run_agent_chat(cfg):
                     stdout=log_fh, stderr=subprocess.STDOUT,
                     **_ws_spawn_kwargs(),
                 )
+                _INFLIGHT_CMDS.add(proc.pid)  # killed with the agent until it is classified
                 start = _t.time()
 
                 def _read_log() -> str:
@@ -12205,6 +12396,10 @@ def run_agent_chat(cfg):
                 _last_obs["text"] = msg
                 return msg
             finally:
+                # Exited, killed at the deadline, or left running ON PURPOSE as a server/app
+                # (tracked in the servers file for stop_server): no longer in flight either way.
+                if proc is not None:
+                    _INFLIGHT_CMDS.discard(proc.pid)
                 try:
                     log_fh.close()
                 except Exception:  # noqa: BLE001
@@ -12655,8 +12850,25 @@ def run_agent_chat(cfg):
                     _RAG_STATE["s"] = "no-index"
             except Exception:  # noqa: BLE001
                 pass
+        # The question's pasted images (task #284): a Claude coder sees them; any other coder is
+        # told they were not sent rather than left to guess from a bare "[Image #1]".
+        _turn_images = []
+        if _turn_image_refs:
+            if _is_anthropic_url(coding_base_url):
+                _turn_images, _img_failed = _load_turn_images(_turn_image_refs)
+                task_with_hint = _label_failed_images(task_with_hint, _img_failed)
+                _log(f"attached {len(_turn_images)} image(s) to the question"
+                     + (f", {len(_img_failed)} could not be opened" if _img_failed else ""))
+                if _turn_images:
+                    _emit({"type": "step", "text": f"Sending {len(_turn_images)} image(s) with the question"})
+                for _lbl, _why in _img_failed:
+                    _emit({"type": "step", "text": f"⚠ {_lbl} not sent — {_why}"})
+            else:
+                task_with_hint += ("\n\n(The user pasted " + ", ".join(l for l, _ in _turn_image_refs)
+                                   + " but this coding model is not sent images — say so if the "
+                                   "task needs them.)")
         with contextlib.redirect_stdout(sys.stderr):
-            result = agent.run(task_with_hint)
+            result = agent.run(task_with_hint, images=_turn_images or None)
             while _maxsteps_partial.get("hit"):
                 if _always_extend:
                     _log(f"max-steps reached → auto-extending to {_MAXSTEP_CEILING} "
@@ -12887,9 +13099,41 @@ def _emit(obj):
     Lock-guarded: the model-call heartbeat thread emits concurrently with the
     main loop, and interleaved writes would corrupt the NDJSON stream.
     """
+    live = isinstance(obj, dict) and obj.pop("_liveness", False)
     with _EMIT_LOCK:
         _REAL_STDOUT.write(json.dumps(obj) + "\n")
         _REAL_STDOUT.flush()
+        if live:
+            return
+        _LIVENESS["last"] = time.monotonic()
+        if obj.get("type") == "final":
+            _LIVENESS["stop"].set()
+
+
+# A TURN IS ALIVE WHILE ANYTHING RUNS, NOT ONLY THE MODEL. The API fails a job after 5 minutes
+# with no update (#209), sized on the model-call heartbeat — but only a model call had one. A
+# run_command may wait up to 10 minutes (and an MCP tool as long as it likes) in silence:
+# reported 09-25, `sdkmanager` downloading a system image was "auto-failed after 5m without
+# updates" at 28% while the download carried on. This fires only when nothing else has been
+# sent for _LIVENESS_EVERY_S, so a model call's own heartbeat still speaks for itself. Same
+# "Word… (Ns)" shape: the REPL swallows it (its ticker shows progress); the job stays fresh.
+_LIVENESS_EVERY_S = int(os.environ.get("GONEXT_LIVENESS_S") or 45)  # env: tests only
+_LIVENESS = {"last": time.monotonic(), "stop": threading.Event()}
+
+
+def _liveness_loop(every=None):
+    every = every or _LIVENESS_EVERY_S
+    while not _LIVENESS["stop"].wait(min(every, 15)):
+        quiet = time.monotonic() - _LIVENESS["last"]
+        if quiet >= every and not _LIVENESS["stop"].is_set():
+            _emit({"type": "step", "text": f"Still working… ({int(quiet)}s)", "_liveness": True})
+
+
+def _start_liveness(every=None):
+    _LIVENESS["last"] = time.monotonic()
+    t = threading.Thread(target=_liveness_loop, args=(every,), daemon=True)
+    t.start()
+    return t
 
 
 def main():
@@ -12898,6 +13142,8 @@ def main():
     except Exception as e:  # noqa: BLE001
         _emit({"type": "final", "text": f"[Invalid input: {e}]"})
         return
+    _start_liveness()
+    _install_sigterm_handler()
     run_agent_chat(cfg)
 
 

package/gu-cli.mjs

@@ -19,6 +19,7 @@ import { mkdir, mkdtemp, readFile, rm, stat, unlink, writeFile } from "node:fs/p
 import { execFile as execFileCallback, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createTaskPool, createFolderQueue } from "./job-pools.mjs";
+import { agentStoppedLine, jobEnded, jobStatusFrom409, stopGracefully } from "./agent-stop.mjs";
 import { ragJobConfig } from "./rag-job-config.mjs";
 import { codingKeyFallbackLine, isOllamaCloudUrl } from "./coding-key-prompt.mjs";
 // Pure layout helpers — safe to import here (no side effects on load, unlike gu-repl.mjs).
@@ -1697,9 +1698,17 @@ const localHealthConcurrency = 4;
 // so two turns each run slower than one would alone. The user's call: "accept it be slow" — a
 // folder that answers slowly beats a folder that cannot answer at all. Unbounded is still
 // wrong: a dozen forgotten terminals would spawn a dozen python processes against one GPU.
+//
+// 4, up from 2 (2026-09-25, the user's call: "make it 4 by default"). The 2 was sized for ONE
+// local GPU shared by coder and embedder; production now targets hosted models, where the
+// limit is this machine's RAM/CPU and the provider's rate limit, not a GPU queue. Still
+// bounded, and GONEXT_AGENT_CONCURRENCY in ~/.gonext/worker.env still overrides it (set 1-2
+// for a local Ollama/MLX coder).
+const DEFAULT_AGENT_CONCURRENCY = 4;
 const agentConcurrency = Math.max(
   1,
-  Number.parseInt(String(process.env.GONEXT_AGENT_CONCURRENCY ?? "").trim(), 10) || 2
+  Number.parseInt(String(process.env.GONEXT_AGENT_CONCURRENCY ?? "").trim(), 10) ||
+    DEFAULT_AGENT_CONCURRENCY
 );
 
 const CHUNK_PATH = "/api/worker/job-chunk";
@@ -2453,6 +2462,7 @@ function runProcessWithStreamingStdout(cmd, cmdArgs, stdinStr, timeoutMs, onLine
     let aborted = false;
     let closed = false;
     let timerLive = true;
+    let cancelHardKill = () => {};
     // On the time budget: with no onTimeout handler (probe/legacy) this is a hard cap —
     // kill immediately. With a handler (task #81, interactive terminal) ask the user
     // whether to keep waiting; the child keeps running/streaming during the ~60s prompt.
@@ -2462,7 +2472,7 @@ function runProcessWithStreamingStdout(cmd, cmdArgs, stdinStr, timeoutMs, onLine
       if (typeof onTimeout !== "function") {
         timedOut = true;
         timerLive = false;
-        child.kill("SIGKILL");
+        cancelHardKill = stopGracefully(child);
         return;
       }
       let extend = false;
@@ -2478,16 +2488,18 @@ function runProcessWithStreamingStdout(cmd, cmdArgs, stdinStr, timeoutMs, onLine
       }
       timedOut = true;
       timerLive = false;
-      child.kill("SIGKILL");
+      cancelHardKill = stopGracefully(child);
     };
     const timer = setTimeout(fireTimeout, timeoutMs);
     // User-requested cancel (gu Ctrl+C): kill the Python agent so it stops burning
     // steps/tokens. On close we resolve cleanly (not reject) — the caller checks the
     // cancel flag and leaves the job in its already-"cancelled" state.
+    // SIGTERM first (agent-stop.mjs): the agent kills the command it is in the middle of, then
+    // exits; SIGKILL follows after a short grace only if it has not.
     const onAbort = () => {
       if (aborted) return;
       aborted = true;
-      child.kill("SIGKILL");
+      cancelHardKill = stopGracefully(child);
     };
     if (abortSignal) {
       if (abortSignal.aborted) onAbort();
@@ -2521,6 +2533,7 @@ function runProcessWithStreamingStdout(cmd, cmdArgs, stdinStr, timeoutMs, onLine
       closed = true;
       timerLive = false;
       clearTimeout(timer);
+      cancelHardKill();
       if (abortSignal) abortSignal.removeEventListener?.("abort", onAbort);
       // Drain any remaining buffered line
       const remaining = lineBuffer.trim();
@@ -3556,6 +3569,9 @@ async function runAgentChatJob(job) {
   // "cancelled" status with completed/failed.
   const cancelAc = new AbortController();
   let cancelled = false;
+  // Which API status stopped the agent ("cancelled" = Ctrl+C; "failed"/"completed" = the API
+  // ended the job while it was still working — see agent-stop.mjs). "" = it was not stopped.
+  let stoppedBy = "";
   // Task #108: the user's Coding backend setting ("ollama" | "openai" | "" = Auto).
   const codingKind = ["ollama", "openai", "local"].includes(payload?.codingKind)
     ? payload.codingKind
@@ -3604,12 +3620,16 @@ async function runAgentChatJob(job) {
     });
     if (!res.ok && res.status !== 204) {
       const snippet = (await res.text().catch(() => "")).trim().slice(0, 400);
-      const cancelledNow =
-        res.status === 409 && snippet.includes('"jobStatus":"cancelled"');
-      if (cancelledNow) cancelAc.abort(); // REPL cancelled mid-run → stop the Python agent
+      const endedAs = res.status === 409 ? jobStatusFrom409(snippet) : "";
+      const cancelledNow = endedAs === "cancelled";
+      // The job is over on the API (cancelled, or failed/completed while still working): nobody
+      // will read another line, so stop the Python agent instead of letting it run on unseen.
+      if (jobEnded(endedAs) && !cancelAc.signal.aborted) {
+        stoppedBy = stoppedBy || endedAs;
+        cancelAc.abort();
+      }
       const benign409 =
-        res.status === 409 &&
-        (snippet.includes('"jobStatus":"completed"') || cancelledNow);
+        res.status === 409 && (endedAs === "completed" || cancelledNow);
       if (!benign409) {
         console.error(
           `[gu-worker] agent_chat job-chunk POST failed status=${res.status} jobId=${jobId}` +
@@ -3740,8 +3760,8 @@ async function runAgentChatJob(job) {
     // key like any other paid endpoint. A local/LAN Ollama gets no key (and ignores one).
     if (codingBackend === "openai" || (codingBackend === "ollama" && _isOllamaCloudUrl(payload?.codingBaseURL))) {
       try {
-        // NAME THE JOB (task #222 phase 2). Two turns run concurrently by default
-        // (agentConcurrency = 2), and each may have chosen a different key — so the key is
+        // NAME THE JOB (task #222 phase 2). Several turns run concurrently by default
+        // (agentConcurrency = 4), and each may have chosen a different key — so the key is
         // resolved from THIS job rather than from an account-wide "current selection", which
         // both turns would read and the later writer would decide for both. An API that does
         // not understand the parameter ignores it and returns the account key, which is
@@ -3985,16 +4005,18 @@ async function runAgentChatJob(job) {
     }
 
     // Poll our own job status during the run so a REPL Ctrl+C (which marks the job
-    // "cancelled" via the API) actually stops the Python agent within ~1.5s, instead of
-    // only being noticed on the next chunk flush (which can be 45s apart during a long
-    // model call). The job-chunk 409 path (flushChunks) is the backup signal.
+    // "cancelled" via the API) actually stops the Python agent within ~1.5s — and so does ANY
+    // end the API decides (a job expired as "failed" used to run on unseen, agent-stop.mjs),
+    // instead of only being noticed on the next chunk flush (which can be 45s apart during a
+    // long model call). The job-chunk 409 path (flushChunks) is the backup signal.
     const cancelPoll = setInterval(async () => {
       if (cancelAc.signal.aborted) return;
       try {
         const r = await workerFetch(`/api/worker/jobs/${jobId}`);
         if (r.ok) {
           const j = await r.json().catch(() => ({}));
-          if (j?.jobStatus === "cancelled") {
+          if (jobEnded(j?.jobStatus)) {
+            stoppedBy = stoppedBy || String(j.jobStatus);
             cancelled = true;
             cancelAc.abort();
           }
@@ -4212,7 +4234,7 @@ async function runAgentChatJob(job) {
     // would resurrect a finished status) and skip the final chunk flush (it'd 409).
     if (cancelled || cancelAc.signal.aborted) {
       if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
-      console.log(`[gu-worker] agent_chat ${jobId} cancelled by user`);
+      console.log(agentStoppedLine(jobId, stoppedBy));
       return;
     }
 
@@ -4268,7 +4290,7 @@ async function runAgentChatJob(job) {
     // A cancel that raced into the catch (e.g. the kill surfaced as an error before the
     // aborted-close path): the job is already "cancelled" — don't overwrite with failed.
     if (cancelled || cancelAc.signal.aborted) {
-      console.log(`[gu-worker] agent_chat ${jobId} cancelled by user`);
+      console.log(agentStoppedLine(jobId, stoppedBy));
       return;
     }
     await flushTail;

package/gu-repl.mjs

@@ -128,6 +128,7 @@ import { unapprovedProjectServers } from "./mcp-command.mjs";
 import { readHooks } from "./hooks-config.mjs";
 import { codingBannerLabel, isOllamaCloudUrl, SECRET_KEY_HINT } from "./coding-key-prompt.mjs";
 import { codingChoiceTags, coderDisplayName, coderWhere, whereOfActiveCoder } from "./coding-choice-tags.mjs";
+import { IMAGE_NEEDS_CLAUDE, clipboardImageToFile, createImageStore, imagePasteKey, imagePathFromPaste, isClaudeCoderUrl, isImagePasteKey, storeImageFile } from "./image-paste.mjs";
 import {
   isDoubleClick,
   clickRun,
@@ -1031,10 +1032,17 @@ rl._ttyWrite = (str, key) => {
   if (key?.name === "paste-end") {
     const text = pasteBuffer ?? "";
     pasteBuffer = null;
-    if (!text) return;
+    // An EMPTY paste is what some terminals send for Cmd+V with only an image on the clipboard.
+    if (!text) {
+      pasteClipboardImage();
+      return;
+    }
     // Trailing newline(s) are trimmed: a copied log almost always ends with one, and it is
     // not content the user meant to include.
     const trimmed = text.replace(/\n+$/, "");
+    // A dragged or pasted image FILE arrives as its path: show it as "[Image #N]" (task #284).
+    const imgPath = imagePathFromPaste(trimmed);
+    if (imgPath && pasteImageFile(imgPath)) return;
     const insert = shouldCollapsePaste(trimmed)
       ? makePasteToken(trimmed)
       : trimmed.replace(/\n/g, " "); // a short paste stays literal, on one line
@@ -1056,6 +1064,14 @@ rl._ttyWrite = (str, key) => {
     // paste token is short, so the input rarely moves at all.
     return;
   }
+  // Ctrl+V / Alt+V paste an IMAGE from the clipboard (task #284) — terminals paste only text, so
+  // Cmd+V with a copied screenshot sends nothing. Alt+V is the one that works on Windows:
+  // Windows Terminal keeps Ctrl+V for its own paste (Claude Code uses Alt+V there for the same
+  // reason). See image-paste.mjs.
+  if (pasteBuffer === null && isImagePasteKey(key)) {
+    pasteClipboardImage();
+    return;
+  }
   if (pasteBuffer !== null) {
     // Inside a paste: accumulate, and let NOTHING reach readline.
     if (key?.name === "enter" || key?.name === "return") pasteBuffer += "\n";
@@ -1424,6 +1440,57 @@ const stripAnsiEscapes = (s) =>
 const PASTE_MIN_CHARS = 200;
 const PASTE_MIN_LINES = 3;
 const pasteStore = new Map(); // token -> the real text
+// ---------- pasted images (task #284) ----------
+const imageStore = createImageStore();
+// Shown on the bottom row after a refused or failed image paste; clears itself.
+let imageNotice = "";
+let imageNoticeTimer = null;
+function showImageNotice(text) {
+  imageNotice = text;
+  if (imageNoticeTimer) clearTimeout(imageNoticeTimer);
+  imageNoticeTimer = setTimeout(() => {
+    imageNotice = "";
+    imageNoticeTimer = null;
+    if (barPinned()) paintBar();
+  }, 12_000);
+  imageNoticeTimer.unref?.();
+  if (barPinned()) paintBar();
+}
+/** Images go to the coding model; only a Claude coder takes them for now. */
+const coderTakesImages = () => isClaudeCoderUrl(sessionCodingUrl || defaultCodingUrl);
+function insertAtCaret(text) {
+  dropSelectedInputText();
+  const before = rl.line.slice(0, rl.cursor);
+  const after = rl.line.slice(rl.cursor);
+  rl.line = before + text + after;
+  rl.cursor = before.length + text.length;
+  rl._refreshLine();
+}
+/** A pasted image file → "[Image #N]". → false when refused (the path then goes in as text). */
+function pasteImageFile(path) {
+  if (!coderTakesImages()) {
+    showImageNotice(IMAGE_NEEDS_CLAUDE);
+    return false;
+  }
+  const r = storeImageFile(path);
+  if (r.error) {
+    showImageNotice(r.error);
+    return false;
+  }
+  insertAtCaret(imageStore.add(r.path));
+  return true;
+}
+/** Ctrl+V (or an empty paste): the clipboard's image → "[Image #N]". */
+function pasteClipboardImage() {
+  if (!coderTakesImages()) {
+    showImageNotice(IMAGE_NEEDS_CLAUDE);
+    return;
+  }
+  const r = clipboardImageToFile();
+  if (r.none) showImageNotice(`no image on the clipboard (copy a screenshot, then ${imagePasteKey()})`);
+  else if (r.error) showImageNotice(r.error);
+  else insertAtCaret(imageStore.add(r.path));
+}
 let pasteSeq = 0;
 const PASTE_TOKEN_RE = /\[Pasted text #(\d+)(?: \+\d+ lines)?\]/g;
 
@@ -1579,7 +1646,10 @@ rl.on("line", (l) => {
   // line is finalised, so every downstream consumer (the agent request, history, the session
   // file) sees the real text — a placeholder reaching the model would silently drop what the
   // user pasted.
-  const clean = expandPasteTokens(stripAnsiEscapes(submitted));
+  // 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.
+  const clean = imageStore.expand(expandPasteTokens(stripAnsiEscapes(submitted)));
+  imageStore.clear();
   const waiter = _lineWaiters.pop(); // innermost reader first — see _lineWaiters
   if (waiter) waiter(clean);
   else _lineQueue.push(clean);
@@ -1779,7 +1849,8 @@ function slashCloseSeq(line, cursor, cols) {
 let editMode = "accept"; // "accept" | "manual"
 const modeLineText = () =>
   white("✎ " + (editMode === "accept" ? "accept edits on" : "manually edit")) +
-  dim("   (shift+tab to switch)");
+  dim("   (shift+tab to switch)") +
+  (imageNotice ? "   " + orange("⚠ " + imageNotice) : "");
 // Token usage for the bar's middle row (task #104): the LAST turn's code-model input +
 // output, then the coder's lifetime output total. Unlike the old per-turn print, this row is
 // ALWAYS on screen — a turn that did no code-model work honestly reads "0", and the lifetime
@@ -3734,6 +3805,7 @@ if (process.stdin.isTTY) {
     // A deleted token means its payload is no longer referenced — drop it, so a long paste
     // the user removed isn't silently sent anyway.
     if (pasteStore.size) prunePasteStore(rl.line);
+    if (imageStore.size) imageStore.prune(rl.line);
     // ↑/↓ while the menu is up = move the highlight IN PLACE. readline drawing is
     // suppressed (slashOverlayActive) and history neutralized, so its own ↑/↓ do
     // nothing — we just move the selection and re-render the overlay (bug #109).
@@ -11195,6 +11267,7 @@ async function main() {
     rl.historyIndex = -1;
     if (_lineQueue.length > 0) _lineQueue.length = 0;
     prunePasteStore("");
+    imageStore.clear();
     if (barPinned()) paintBar();
   };
 

package/image-paste.mjs

@@ -0,0 +1,235 @@
+/**
+ * Pasting an image into the gu input (task #284).
+ *
+ * The image goes to the CODING model, the way Claude Code does it — no OCR step: the model sees
+ * the screenshot itself. For now only a Claude coder (api.anthropic.com) may receive one; with
+ * any other coder a paste is refused and the bar says to pick a Claude model.
+ *
+ * How it reaches the model. The API passes the message TEXT and nothing else, so the image rides
+ * in the text as a marker: the input shows "[Image #1]" (like "[Pasted text #1]"), and the line
+ * that is sent carries "[Image #1: /Users/…/.gonext/images/…png]". The agent reads the file,
+ * attaches it to the request, and puts "[Image #1]" back in the text it shows the model. Files
+ * are copied into ~/.gonext/images first; the agent reads images from there and nowhere else.
+ *
+ * Two ways in:
+ *   · a key that reads the clipboard's image (a copied screenshot). Terminals paste only text, so
+ *     Cmd+V with an image on the clipboard sends nothing. Ctrl+V on macOS/Linux, ALT+V on
+ *     Windows — Windows Terminal takes Ctrl+V for its own paste and the app never sees it (the
+ *     same reason Claude Code uses Alt+V there). Both keys work everywhere; the hint names one.
+ *   · a pasted or dragged image FILE path — the terminal pastes its path as text. On Windows the
+ *     most reliable way; Windows Terminal quotes a path with spaces.
+ */
+import { spawnSync } from "node:child_process";
+import { chmodSync, closeSync, copyFileSync, existsSync, mkdirSync, openSync, readSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path, { join } from "node:path";
+
+export const IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
+/**
+ * The largest file gu takes at paste time. NOT Claude's 5 MB limit: the agent shrinks every image
+ * to what Claude accepts before sending (task #285), so a 12 MB photo is fine. This only stops a
+ * file far too big to be a screenshot from being copied around.
+ */
+export const MAX_IMAGE_BYTES = 30 * 1024 * 1024;
+
+/**
+ * What the file's first bytes say it is — "png" | "jpeg" | "gif" | "webp" | "" (task #285). The
+ * EXTENSION is only a name: a renamed text file, or a screenshot still being written, has the
+ * right one and is not an image.
+ */
+export function imageKind(bytes) {
+  const b = Buffer.from(bytes ?? []);
+  if (b.length >= 8 && b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return "png";
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return "jpeg";
+  if (b.length >= 6 && /^GIF8[79]a$/.test(b.subarray(0, 6).toString("latin1"))) return "gif";
+  if (b.length >= 12 && b.subarray(0, 4).toString("latin1") === "RIFF" && b.subarray(8, 12).toString("latin1") === "WEBP") return "webp";
+  return "";
+}
+
+function fileImageKind(path) {
+  let fd;
+  try {
+    fd = openSync(path, "r");
+    const buf = Buffer.alloc(12);
+    const n = readSync(fd, buf, 0, 12, 0);
+    return imageKind(buf.subarray(0, n));
+  } catch {
+    return "";
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+const NOT_AN_IMAGE = "that file is not an image (png, jpg, gif or webp)";
+
+export const imagesDir = (home = homedir()) => join(home, ".gonext", "images");
+
+/** Is this coding server Claude's own API — the only one allowed images for now? */
+export function isClaudeCoderUrl(url) {
+  try {
+    return new URL(String(url ?? "")).hostname.toLowerCase().replace(/\.$/, "") === "api.anthropic.com";
+  } catch {
+    return false;
+  }
+}
+
+export const IMAGE_NEEDS_CLAUDE =
+  "image paste needs a Claude coding model — pick one with /model";
+
+/** The key to name in hints on this platform (both work everywhere). */
+export const imagePasteKey = (platform = process.platform) => (platform === "win32" ? "Alt+V" : "Ctrl+V");
+
+/** Is this keypress the "paste an image" key? Ctrl+V, or Alt+V (readline reports Alt as meta). */
+export function isImagePasteKey(key) {
+  if (!key || key.name !== "v") return false;
+  return Boolean(key.ctrl && !key.meta) || Boolean(key.meta && !key.ctrl);
+}
+
+/** A Windows path: a drive letter (C:\… or C:/…) or a UNC share (\\server\…). */
+const isWindowsPath = (t) => /^[A-Za-z]:[\\/]/.test(t) || /^\\\\[^\\]/.test(t);
+
+/**
+ * A pasted string → the image file it names, or "" when it is not exactly one image path.
+ * Handles what terminals actually paste for a dragged file: quotes, backslash-escaped spaces,
+ * and file:// URLs.
+ */
+export function imagePathFromPaste(text, { cwd = process.cwd(), exists = existsSync, platform = process.platform } = {}) {
+  let t = String(text ?? "").trim();
+  if (!t || t.includes("\n")) return "";
+  const win = platform === "win32";
+  if (/^(['"]).*\1$/.test(t)) t = t.slice(1, -1);
+  // A backslash is an ESCAPE only in a POSIX shell's spelling (Terminal.app drags "a\ b.png").
+  // On Windows it is the path separator — unescaping turned C:\Users\x.png into C:Usersx.png.
+  else if (!win && !isWindowsPath(t)) t = t.replace(/\\(.)/g, "$1");
+  if (t.startsWith("file://")) {
+    try {
+      t = decodeURIComponent(new URL(t).pathname);
+    } catch {
+      return "";
+    }
+  }
+  if (t.startsWith("~/") || (win && t.startsWith("~\\"))) t = join(homedir(), t.slice(2));
+  const P = win ? path.win32 : path.posix;
+  if (!IMAGE_EXTS.has(P.extname(t).toLowerCase())) return "";
+  const p = P.resolve(cwd, t);
+  return exists(p) ? p : "";
+}
+
+function newImagePath(ext, home) {
+  const dir = imagesDir(home);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..*/, "").replace("T", "-");
+  return join(dir, `${stamp}-${Math.random().toString(36).slice(2, 8)}${ext}`);
+}
+
+/** Copy an image file into ~/.gonext/images. → { path } or { error }. */
+export function storeImageFile(src, { home = homedir() } = {}) {
+  let size = 0;
+  try {
+    size = statSync(src).size;
+  } catch {
+    return { error: `cannot read ${src}` };
+  }
+  if (size > MAX_IMAGE_BYTES) return { error: tooBig(size) };
+  const kind = fileImageKind(src);
+  if (!kind) return { error: NOT_AN_IMAGE };
+  const dest = newImagePath(kind === "jpeg" ? ".jpg" : `.${kind}`, home);
+  copyFileSync(src, dest);
+  chmodSync(dest, 0o600);
+  return { path: dest };
+}
+
+const tooBig = (n) => `the image is ${(n / 1048576).toFixed(1)} MB — gu takes up to ${MAX_IMAGE_BYTES / 1048576} MB`;
+
+/** The command that writes the clipboard's image to `dest` as PNG, per platform (null = none). */
+export function clipboardImageCommand(dest, platform = process.platform) {
+  if (platform === "darwin") {
+    return {
+      cmd: "osascript",
+      args: [
+        "-e", "set png to (the clipboard as «class PNGf»)",
+        "-e", `set f to open for access POSIX file ${JSON.stringify(dest)} with write permission`,
+        "-e", "set eof f to 0",
+        "-e", "write png to f",
+        "-e", "close access f",
+      ],
+    };
+  }
+  if (platform === "win32") {
+    // Windows PowerShell 5.1 (powershell.exe) is on every Windows 11; PowerShell 7 (pwsh) is not.
+    // The clipboard API needs an STA thread. A screenshot (Win+Shift+S, PrtScn) is a bitmap; a
+    // file copied in Explorer is a file-drop list — both are handled.
+    const d = dest.replace(/'/g, "''");
+    return {
+      cmd: "powershell.exe",
+      args: ["-NoProfile", "-NonInteractive", "-STA", "-Command",
+        "Add-Type -AssemblyName System.Windows.Forms, System.Drawing; " +
+        "$c = [System.Windows.Forms.Clipboard]; $i = $c::GetImage(); " +
+        `if ($i) { $i.Save('${d}', [System.Drawing.Imaging.ImageFormat]::Png); exit 0 }; ` +
+        "foreach ($p in $c::GetFileDropList()) { if ($p -match '\\.(png|jpe?g|gif|webp)$') { " +
+        `Copy-Item -LiteralPath $p -Destination '${d}'; exit 0 } }; exit 1`],
+    };
+  }
+  return { cmd: "sh", args: ["-c", `(wl-paste --type image/png 2>/dev/null || xclip -selection clipboard -t image/png -o 2>/dev/null) > '${dest.replace(/'/g, "'\\''")}' && [ -s '${dest.replace(/'/g, "'\\''")}' ]`] };
+}
+
+/** Save the clipboard's image into ~/.gonext/images. → { path } | { error } | { none: true }. */
+export function clipboardImageToFile({ home = homedir(), platform = process.platform, run = spawnSync } = {}) {
+  const dest = newImagePath(".png", home);
+  const { cmd, args } = clipboardImageCommand(dest, platform);
+  const r = run(cmd, args, { stdio: "ignore", timeout: 10_000 });
+  let size = 0;
+  try {
+    size = statSync(dest).size;
+  } catch {
+    /* nothing written */
+  }
+  if (r?.status !== 0 || size === 0) {
+    rmSync(dest, { force: true });
+    return { none: true };
+  }
+  if (size > MAX_IMAGE_BYTES) {
+    rmSync(dest, { force: true });
+    return { error: tooBig(size) };
+  }
+  // A file copied in Explorer is copied as-is, so it can be anything with an image's name.
+  if (!fileImageKind(dest)) {
+    rmSync(dest, { force: true });
+    return { error: "the clipboard's file is not an image (png, jpg, gif or webp)" };
+  }
+  chmodSync(dest, 0o600);
+  return { path: dest };
+}
+
+/** Placeholders shown in the input, and the files behind them. */
+export function createImageStore() {
+  const store = new Map(); // token -> absolute path
+  let seq = 0;
+  const TOKEN_RE = /\[Image #(\d+)\]/g;
+  return {
+    get size() {
+      return store.size;
+    },
+    add(path) {
+      const token = `[Image #${++seq}]`;
+      store.set(token, path);
+      return token;
+    },
+    /** The line to SEND: each token carries its file, for the agent to attach. */
+    expand(line) {
+      const s = String(line ?? "");
+      if (!store.size) return s;
+      return s.replace(TOKEN_RE, (m, n) => (store.has(m) ? `[Image #${n}: ${store.get(m)}]` : m));
+    },
+    /** Forget images whose token is no longer in the line. */
+    prune(line) {
+      const present = new Set(String(line ?? "").match(TOKEN_RE) ?? []);
+      for (const t of [...store.keys()]) if (!present.has(t)) store.delete(t);
+    },
+    /** After a message is sent: the next one numbers its images from #1 again. */
+    clear() {
+      store.clear();
+      seq = 0;
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.751",
+  "version": "1.0.753",
   "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",
@@ -38,6 +38,8 @@
     "test:tokens": "python3 -m unittest discover tests -p \"test_cached_tokens.py\" -v && node --test tests/prefix-cache.test.mjs tests/agent-turn-shape.test.mjs",
     "test:selection": "node --test tests/selection-scrollback.test.mjs tests/selection-while-thinking.test.mjs tests/terminal-selection.test.mjs tests/terminal-copy.test.mjs tests/terminal-viewport.test.mjs tests/hover-repaint.test.mjs",
     "test:steps": "python3 scripts/py-tap.py tests/test_read_caps.py tests/test_trim_payback.py tests/test_explore.py tests/test_and_chains.py tests/test_edit_file_primary.py tests/test_bare_code_rescue.py tests/test_batching_rule.py tests/test_no_pdf_routing.py",
+    "check:image": "node scripts/image-paste-check.mjs",
+    "check:image-clipboard": "node scripts/image-paste-check.mjs --clipboard",
     "test:skills": "python3 scripts/py-tap.py tests/test_skills_mcp_turn.py tests/test_hooks_turn.py tests/test_mcp_client.py && node --test tests/skills.test.mjs tests/mcp-config.test.mjs tests/hooks-config.test.mjs tests/slash-menu.test.mjs tests/conversation-archive.test.mjs",
     "capture:turn": "GONEXT_OLLAMA1_LIVE=1 node scripts/capture-turn-fixture.mjs",
     "test:bearer": "node --test tests/bearer-routing.test.mjs tests/bearer-verify.test.mjs",
@@ -65,6 +67,9 @@
     "clear-state.mjs",
     "platform-tools.mjs",
     "job-pools.mjs",
+    "agent-stop.mjs",
+    "image-paste.mjs",
+    "scripts/image-paste-check.mjs",
     "rag-job-config.mjs",
     "completed-flush.mjs",
     "verbose-lines.mjs",

package/scripts/image-paste-check.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Check image paste on THIS machine, for real (task #284). Written for Windows 11, where it can
+ * only be proven on the machine itself: the clipboard belongs to the desktop session, so an ssh
+ * session cannot reach it.
+ *
+ *   node scripts/image-paste-check.mjs              # paths, storage, the agent side
+ *   node scripts/image-paste-check.mjs --clipboard  # + the real clipboard (REPLACES what is on it)
+ *
+ * Every check says what it saw. Nothing is sent to a model.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  clipboardImageToFile,
+  imagePasteKey,
+  imagePathFromPaste,
+  imagesDir,
+  storeImageFile,
+} from "../image-paste.mjs";
+import { resolvePython } from "../platform-tools.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WORKER = dirname(HERE);
+const withClipboard = process.argv.includes("--clipboard");
+const PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+  "base64",
+);
+const isPng = (p) => existsSync(p) && readFileSync(p).subarray(0, 8).equals(PNG.subarray(0, 8));
+
+let failed = 0;
+const made = []; // images this check stored — removed at the end
+
+const check = (name, ok, detail = "") => {
+  if (!ok) failed++;
+  console.log(`  ${name} … ${ok ? "ok" : "FAILED"}${detail ? `  ${detail}` : ""}`);
+};
+
+console.log(`image paste check — ${process.platform} ${process.arch}, node ${process.version}`);
+console.log(`  the image key here: ${imagePasteKey()}`);
+
+// 1. A dropped path, spelled the way this platform's terminal pastes it.
+const dir = mkdtempSync(join(tmpdir(), "gu img check "));
+const shot = join(dir, "Screen Shot 1.png");
+writeFileSync(shot, PNG);
+const spelled = process.platform === "win32" ? `"${shot}"` : shot.replace(/ /g, "\\ ");
+check("a dropped path with spaces is recognised", imagePathFromPaste(spelled) === shot, `${spelled} → ${imagePathFromPaste(spelled)}`);
+
+// 2. It is copied into ~/.gonext/images.
+const stored = storeImageFile(shot);
+if (stored.path) made.push(stored.path);
+check("copied into the images folder", Boolean(stored.path?.startsWith(imagesDir())) && isPng(stored.path), stored.path ?? stored.error);
+
+// 3. The agent reads it back from the marker, and only from the images folder.
+const py = await resolvePython();
+const snippet = [
+  "import importlib.util, json, sys",
+  "spec = importlib.util.spec_from_file_location('a', sys.argv[1]); a = importlib.util.module_from_spec(spec); spec.loader.exec_module(a)",
+  "msgs = [{'role': 'user', 'content': 'look [Image #1: ' + sys.argv[2] + '] and [Image #2: ' + sys.argv[3] + ']'}]",
+  "refs = a._take_image_markers(msgs)",
+  "imgs, failed = a._load_turn_images(refs)",
+  "print(json.dumps({'refs': refs, 'text': msgs[0]['content'], 'opened': len(imgs)}))",
+].join("\n");
+const r = spawnSync(py.cmd, [...py.args, "-c", snippet, join(WORKER, "gonext_agent_chat.py"), stored.path ?? "", shot], {
+  encoding: "utf8", timeout: 120_000, env: { ...process.env, PYTHONUTF8: "1" },
+});
+let out = null;
+try {
+  out = JSON.parse(String(r.stdout).trim().split("\n").pop());
+} catch {
+  /* reported below */
+}
+check("the agent attaches the stored image", out?.refs?.length === 1 && out?.opened === 1, out ? JSON.stringify(out.refs) : String(r.stderr).slice(-300));
+check("…and refuses a file outside the images folder", Boolean(out?.text?.includes("[Image #2] (the image could not be read)")), out?.text ?? "");
+
+// 4. The real clipboard (opt-in: it replaces what is on it).
+if (withClipboard) {
+  if (process.platform === "win32") {
+    const ps = (script) => spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-STA", "-Command", script], { encoding: "utf8" });
+    const set = ps("Add-Type -AssemblyName System.Windows.Forms, System.Drawing; " +
+      "$b = New-Object System.Drawing.Bitmap 4, 4; [System.Windows.Forms.Clipboard]::SetImage($b); 'set'");
+    check("put a bitmap on the clipboard (like Win+Shift+S)", set.status === 0, String(set.stderr).trim().slice(0, 200));
+    const got = clipboardImageToFile();
+    if (got.path) made.push(got.path);
+    check(`${imagePasteKey()} reads a screenshot`, Boolean(got.path) && isPng(got.path), got.path ?? JSON.stringify(got));
+    const drop = ps(`Set-Clipboard -LiteralPath '${shot.replace(/'/g, "''")}'; 'set'`);
+    check("put a FILE on the clipboard (like Ctrl+C in Explorer)", drop.status === 0, String(drop.stderr).trim().slice(0, 200));
+    const got2 = clipboardImageToFile();
+    if (got2.path) made.push(got2.path);
+    check(`${imagePasteKey()} reads a copied image file`, Boolean(got2.path) && isPng(got2.path), got2.path ?? JSON.stringify(got2));
+    ps("Set-Clipboard -Value ' '");
+    check("empty clipboard is 'none', not an error", clipboardImageToFile().none === true);
+  } else if (process.platform === "darwin") {
+    const set = spawnSync("osascript", ["-e", `set the clipboard to (read (POSIX file ${JSON.stringify(shot)}) as «class PNGf»)`]);
+    check("put an image on the clipboard", set.status === 0);
+    const got = clipboardImageToFile();
+    if (got.path) made.push(got.path);
+    check(`${imagePasteKey()} reads it`, Boolean(got.path) && isPng(got.path), got.path ?? JSON.stringify(got));
+  } else {
+    console.log("  (clipboard: on Linux install wl-clipboard or xclip; not checked here)");
+  }
+} else {
+  console.log("  (clipboard not checked — run with --clipboard; it replaces what is on your clipboard)");
+}
+
+rmSync(dir, { recursive: true, force: true });
+for (const p of made) rmSync(p, { force: true });
+console.log(failed ? `\n  ${failed} check(s) FAILED` : "\n  all checks passed");
+process.exit(failed ? 1 : 0);