@aion0/forge 0.10.53 → 0.10.56

package/lib/chat/tool-dispatcher.ts

@@ -37,6 +37,85 @@ export interface ToolResult {
 
 export type BuiltinHandler = (input: unknown) => Promise<string>;
 
+// ─── Data-dir file helpers ────────────────────────────────
+// resolveTmpPath: scoped to <dataDir>/tmp/ — where save_tmp_file drops
+// its files. Kept separate from scratch/ (the synthetic "scratch
+// project" task workspace) so the cache janitor can wipe tmp/ without
+// disturbing in-progress task workdirs.
+async function resolveTmpPath(rel: string): Promise<string> {
+  const { getDataDir } = await import('../dirs');
+  const { join, resolve } = await import('node:path');
+  const clean = rel.replace(/^\/+/, '');
+  if (!clean || clean.includes('..') || clean.includes('\0')) throw new Error('invalid tmp path');
+  const tmpRoot = join(getDataDir(), 'tmp');
+  const target = resolve(tmpRoot, clean);
+  if (!target.startsWith(tmpRoot + '/') && target !== tmpRoot) {
+    throw new Error('resolved path escapes tmp dir');
+  }
+  return target;
+}
+
+// resolveDataPath: scoped to <dataDir>/ — the read/list tools' broader
+// surface. Blocks known sensitive files (encrypt key, enterprise keys,
+// sqlite DBs, server log, anything starting with a dot at the dataDir
+// root). Subpaths under known-safe subdirs (scratch/, flows/, prompts/,
+// connectors/, etc.) are accepted as-is. The agent can use this to
+// inspect its OWN config — but secrets stay invisible.
+function isSensitiveDataPath(target: string, dataRoot: string): string | null {
+  if (target === dataRoot) return null;
+  const rel = target.slice(dataRoot.length + 1); // drop "<root>/"
+  const top = rel.split('/')[0] || '';
+  // Top-level dotfiles (.encrypt-key, .enterprise-keys.json, …) — secrets.
+  if (top.startsWith('.')) return `top-level dotfile "${top}" is sensitive (encryption keys, session state)`;
+  // SQLite databases are binary, large, and contain raw chat / task history.
+  if (/\.(db|db-wal|db-shm)$/i.test(top)) return `sqlite database "${top}" — read via Forge APIs instead`;
+  // forge.log / forge.log.old — large + may contain tokens that leaked into errors.
+  if (/^forge\.log/i.test(top)) return 'forge.log is server diagnostics — ask the user to grep it directly';
+  // Token caches at root.
+  if (/-tokens\.json$/i.test(top)) return `"${top}" stores auth tokens — sensitive`;
+  return null;
+}
+async function resolveDataPath(rel: string): Promise<string> {
+  const { getDataDir } = await import('../dirs');
+  const { resolve } = await import('node:path');
+  const clean = String(rel || '').replace(/^\/+/, '');
+  if (clean.includes('..') || clean.includes('\0')) throw new Error('invalid path');
+  const dataRoot = getDataDir();
+  const target = resolve(dataRoot, clean);
+  if (!target.startsWith(dataRoot + '/') && target !== dataRoot) {
+    throw new Error('resolved path escapes data dir');
+  }
+  const blocked = isSensitiveDataPath(target, dataRoot);
+  if (blocked) throw new Error(`refused: ${blocked}`);
+  return target;
+}
+
+// A connector arg whose WHOLE value is one of these forms is a reference
+// to a Forge-managed file. Path inside the prefix is dataDir-relative —
+// e.g. "scratch://tmp/foo.md", "scratch://flows/x.yaml". The "scratch:"
+// prefix is historical (originally only pointed at <dataDir>/scratch/);
+// kept for compatibility.
+const SCRATCH_REF_RE = /^(?:scratch:\/\/|scratch:|\/api\/scratch\/)(.+)$/;
+
+// Replace any `scratch://<file>` arg with the file's base64 content,
+// server-side. This is the whole point: the LLM can hand a connector a
+// saved file (e.g. onedrive.upload_file content_base64) without ever
+// hand-encoding it — hand-encoding large/non-ASCII content is unreliable
+// and is exactly what wedged the OneDrive upload in an endless retry loop.
+async function resolveScratchRefsInArgs(args: Record<string, unknown>): Promise<void> {
+  const { readFile } = await import('node:fs/promises');
+  for (const [k, v] of Object.entries(args)) {
+    if (typeof v !== 'string') continue;
+    const m = v.match(SCRATCH_REF_RE);
+    if (!m) continue;
+    // Path inside the ref is dataDir-relative. Goes through the same
+    // sensitive-file guard as read_forge_file (no leaking encrypt keys
+    // / DBs into a connector upload).
+    const buf = await readFile(await resolveDataPath(m[1])); // ENOENT → tool error
+    args[k] = buf.toString('base64');
+  }
+}
+
 const BUILTINS: Record<string, BuiltinHandler> = {
   get_current_time: async () => new Date().toISOString(),
 
@@ -310,31 +389,144 @@ const BUILTINS: Record<string, BuiltinHandler> = {
   // gets a download link in the response. Prefer this over dispatch_task for
   // "save / create / export a file" asks — the LLM already has the content
   // in context, no need to spawn a CLI task that may write elsewhere.
-  save_scratch_file: async (input) => {
+  save_tmp_file: async (input) => {
     const params = (input as { filename?: string; content?: string } | undefined) || {};
     const filename = (params.filename || '').trim();
     const content = params.content == null ? '' : String(params.content);
     if (!filename) return JSON.stringify({ ok: false, error: 'filename is required' });
-    if (filename.includes('..') || filename.startsWith('/') || filename.includes('\0')) {
-      return JSON.stringify({ ok: false, error: 'filename must be a bare relative name (no .. / leading /)' });
+    // Bare filename only — no slashes anywhere. The cache janitor
+    // (lib/scratch-cleanup.ts) only sweeps top-level files in tmp/;
+    // allowing nested writes would create files that never expire.
+    // Also keeps the path returned in `path: "tmp/<filename>"` simple.
+    if (filename.includes('..') || filename.includes('/') || filename.includes('\\') || filename.includes('\0')) {
+      return JSON.stringify({ ok: false, error: 'filename must be a bare relative name (no slashes, no ".." — use date-stamped flat names like "report-2026-06-09.md")' });
     }
-    const { getDataDir } = await import('../dirs');
-    const { join, resolve } = await import('node:path');
+    // Land under <dataDir>/tmp/ — cache-managed location the user can
+    // sweep via "forge clean cache" / the user-menu Cache panel. Keeps
+    // <dataDir>/scratch/ for the synthetic "scratch project" workspace
+    // (where dispatched tasks live + edit their own files).
+    let target: string;
+    try { target = await resolveTmpPath(filename); }
+    catch (e) { return JSON.stringify({ ok: false, error: (e as Error).message }); }
     const { mkdir, writeFile } = await import('node:fs/promises');
-    const scratchRoot = join(getDataDir(), 'scratch');
-    const target = resolve(scratchRoot, filename);
-    if (!target.startsWith(scratchRoot + '/') && target !== scratchRoot) {
-      return JSON.stringify({ ok: false, error: 'resolved path escapes scratch dir' });
-    }
     const { dirname } = await import('node:path');
+    // Bare filename → dirname is always <dataDir>/tmp/. mkdir -p idempotent.
     await mkdir(dirname(target), { recursive: true });
     await writeFile(target, content, 'utf8');
+    const sizeBytes = Buffer.byteLength(content, 'utf8');
+    const fileUrl = `file://${target}`;
+    // Pre-format the user-facing message. Tell agent to OUTPUT this
+    // verbatim — agents follow "echo this string" instructions far
+    // more reliably than abstract "include the URL" hints. Past
+    // attempts with hint-only kept producing prose that lost the
+    // file:// URL or wrapped it in markdown the chat UI couldn't
+    // render. This sidesteps the entire link-pattern question.
+    const userMessage = `✓ Saved (${sizeBytes} bytes) — ${fileUrl}`;
+    return JSON.stringify({
+      ok: true,
+      path: `tmp/${filename}`,
+      local_path: target,
+      file_url: fileUrl,
+      bytes: sizeBytes,
+      user_message: userMessage,
+      hint: 'OUTPUT THE `user_message` FIELD VERBATIM as your reply to the user — copy the exact characters, no markdown wrapping, no rephrasing, no shortening, no extra prose. That string contains the file:// URL Chrome can open directly on localhost (and that the user can paste into Finder/Explorer). For follow-up asks like "give me the link" / "where is it" / "提供链接" / "再给我一次" → output the same file:// URL again (' + fileUrl + '). To UPLOAD this file to a connector (e.g. onedrive.upload_file), pass "scratch://tmp/' + filename + '" as the content_base64 arg — Forge base64-encodes server-side; do NOT hand-encode. To read it back later, use read_forge_file with filename:"tmp/' + filename + '". tmp/ is auto-swept by the cache janitor.',
+    });
+  },
+
+  // Read any Forge-managed file under <dataDir>/ — tmp/, scratch/,
+  // flows/, prompts/, connectors/, etc. Sensitive files (encrypt key,
+  // sqlite DBs, log, *-tokens.json) are refused. Text returns decoded
+  // text (capped 256KB); pass as_base64:true for binary. To upload a
+  // file to a connector, prefer passing "scratch://<dataDir-rel>" as
+  // the arg — base64-encoded server-side; no bytes through the model.
+  read_forge_file: async (input) => {
+    const params = (input as { filename?: string; as_base64?: boolean } | undefined) || {};
+    // Normalize: strip the scratch:// / /api/scratch/ prefixes the
+    // agent might have copied from save_tmp_file's response. The
+    // remaining string is a dataDir-relative path (e.g. "tmp/foo.md",
+    // "flows/x.yaml", "prompts/y.yaml").
+    const filename = (params.filename || '').trim().replace(/^(?:scratch:\/\/|scratch:|\/api\/scratch\/)/, '');
+    if (!filename) return JSON.stringify({ ok: false, error: 'filename is required' });
+    let target: string;
+    try { target = await resolveDataPath(filename); }
+    catch (e) { return JSON.stringify({ ok: false, error: (e as Error).message }); }
+    const { readFile } = await import('node:fs/promises');
+    let buf: Buffer;
+    try { buf = await readFile(target); }
+    catch { return JSON.stringify({ ok: false, error: `Forge file not found: ${filename}` }); }
+    if (params.as_base64) {
+      return JSON.stringify({
+        ok: true, path: filename,
+        local_path: target, file_url: `file://${target}`,
+        encoding: 'base64', size_bytes: buf.length, content: buf.toString('base64'),
+        // "scratch://" is the connector-ref protocol name (historical —
+        // not the scratch/ dir). Path after it is dataDir-relative.
+        note: `To upload to a connector, prefer passing "scratch://${filename}" directly as the connector arg — Forge resolves + base64-encodes it server-side, no need to round-trip these bytes through the model.`,
+      });
+    }
+    const MAX = 256 * 1024;
+    const truncated = buf.length > MAX;
+    return JSON.stringify({
+      ok: true, path: filename,
+      local_path: target, file_url: `file://${target}`,
+      encoding: 'utf-8', size_bytes: buf.length, truncated,
+      content: buf.subarray(0, MAX).toString('utf8'),
+      ...(truncated ? { note: `content truncated to ${MAX} bytes — use as_base64 for the full file` } : {}),
+    });
+  },
+
+  // List files anywhere under <dataDir>/ (Forge's own data dir).
+  // Replaces the "dispatch a task just to `ls`" workaround. The `dir`
+  // param is dataDir-relative — pass "tmp" / "scratch" / "flows" /
+  // "connectors" / "prompts" / etc. No dir → lists dataDir root.
+  // Sensitive items (encrypt key, sqlite DBs, log, *-tokens.json at
+  // root) are skipped — see resolveDataPath.
+  list_forge_files: async (input) => {
+    const params = (input as { dir?: string; ext?: string; limit?: number } | undefined) || {};
+    const sub = String(params.dir || '').trim().replace(/^\/+|\/+$/g, '');
+    const ext = String(params.ext || '').trim().toLowerCase();
+    const limit = Math.max(1, Math.min(500, Number(params.limit) || 200));
+    const { getDataDir } = await import('../dirs');
+    const { join, relative } = await import('node:path');
+    const { readdir, stat } = await import('node:fs/promises');
+    const dataRoot = getDataDir();
+    let target: string;
+    try { target = sub ? await resolveDataPath(sub) : dataRoot; }
+    catch (e) { return JSON.stringify({ ok: false, error: (e as Error).message }); }
+    let dirents;
+    try { dirents = await readdir(target, { withFileTypes: true }); }
+    catch (e) { return JSON.stringify({ ok: false, error: `cannot list ${sub || 'data/'}: ${(e as Error).message}` }); }
+    const entries: Array<{ path: string; kind: 'file' | 'dir'; size?: number; mtime?: string; file_url?: string }> = [];
+    for (const d of dirents) {
+      const full = join(target, d.name);
+      // Apply the same sensitive-file filter to entries we list — so the
+      // agent doesn't even see .encrypt-key / *.db etc.
+      if (isSensitiveDataPath(full, dataRoot)) continue;
+      if (ext && d.isFile() && !d.name.toLowerCase().endsWith(ext)) continue;
+      let size: number | undefined;
+      let mtime: string | undefined;
+      if (d.isFile()) {
+        try { const s = await stat(full); size = s.size; mtime = s.mtime.toISOString(); } catch {}
+      }
+      entries.push({
+        path: relative(dataRoot, full),
+        kind: d.isDirectory() ? 'dir' : 'file',
+        ...(size !== undefined ? { size } : {}),
+        ...(mtime ? { mtime } : {}),
+        // file:// URL the user can paste into Chrome (works on localhost).
+        // Provide on dirs too — opening a dir in Chrome shows the listing.
+        file_url: `file://${full}`,
+      });
+      if (entries.length >= limit) break;
+    }
+    entries.sort((a, b) => (b.mtime || '').localeCompare(a.mtime || '') || a.path.localeCompare(b.path));
     return JSON.stringify({
       ok: true,
-      path: `scratch/${filename}`,
-      url: `/api/scratch/${filename}`,
-      bytes: Buffer.byteLength(content, 'utf8'),
-      hint: 'Tell the user the file is ready and reference it inline as `scratch/' + filename + '` — chat will render a download link automatically.',
+      root: relative(dataRoot, target) || '.',
+      local_root: target,
+      count: entries.length,
+      entries,
+      hint: 'When the user asks to show / list files, surface each entry\'s `path` (dataDir-relative, e.g. "tmp/foo.md") and `file_url` (file://… — opens in Chrome on localhost). Use read_forge_file with the same `path` to inspect content. PREFER this over dispatch_task with `ls`.',
     });
   },
 
@@ -365,6 +557,23 @@ const BUILTINS: Record<string, BuiltinHandler> = {
     });
   },
 
+  // Stop a still-running dispatched task. Use when the user says "停止
+  // / cancel / kill the task" — much better than telling them to open
+  // the Tasks UI. No-op (returns terminal:true) if the task already
+  // finished, so it's safe to call without checking status first.
+  cancel_task: async (input) => {
+    const params = (input as { task_id?: string } | undefined) || {};
+    if (!params.task_id) return JSON.stringify({ ok: false, error: 'task_id is required' });
+    const { getTask, cancelTask } = await import('../task-manager');
+    const task = getTask(params.task_id);
+    if (!task) return JSON.stringify({ ok: false, error: `Task "${params.task_id}" not found` });
+    if (task.status !== 'running' && task.status !== 'queued') {
+      return JSON.stringify({ ok: true, task_id: task.id, status: task.status, terminal: true, note: 'already terminal — no cancel needed' });
+    }
+    const cancelled = cancelTask(params.task_id);
+    return JSON.stringify({ ok: cancelled, task_id: task.id, status: cancelled ? 'cancelled' : task.status, terminal: cancelled });
+  },
+
   // Companion to dispatch_task — read a task's status + result. Returns JSON
   // so start_watch can poll via done_path="terminal" or done_match
   // {path:"status", equals:"done"}.
@@ -630,7 +839,7 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
   },
   {
     name: 'dispatch_task',
-    description: 'Dispatch a one-shot background Claude task in a Forge project. Use for longer-running asks the user wants to fire-and-forget ("analyze X codebase and write findings to a file", "run the test suite and summarize failures"). Returns JSON: {ok, task_id, project, status, hint}. The task runs in the background; if the user wants to be notified on completion, follow the hint — call start_watch on get_task_status and STOP polling in this conversation.',
+    description: 'Dispatch a one-shot background Claude CLI task in a Forge project. EXPENSIVE — spawns a fresh Claude subprocess that reads/edits code in the target project. Use ONLY for genuine codebase work: "analyze X repo and write findings", "run the test suite and summarize", "fix bug in <project>", "refactor module Y". \n\nDO NOT use for: \n  • Saving a file with content YOU already have → use save_tmp_file. \n  • Reading a Forge-owned file (tmp/scratch/flows/prompts/...) → use read_forge_file. \n  • Listing files in <dataDir>/ → use list_forge_files. \n  • Running a pipeline → use trigger_pipeline. \n  • Inspecting a saved task → use get_task_status. \n\nFor "create / write / save a file with this content" the right tool is ALWAYS save_tmp_file — the LLM has the content, no CLI subprocess needed. \n\nIf the user\'s ask is ambiguous (might be a quick save vs a real codebase task), STOP and ask before dispatching — a user reporting "I just wanted a file" after seeing a task spawn is a clear signal you misclassified. \n\nReturns JSON: {ok, task_id, project, status, hint}. The task runs in the background; if the user wants completion notification, follow the hint — call start_watch on get_task_status and STOP polling in this conversation.',
     input_schema: {
       type: 'object',
       properties: {
@@ -651,8 +860,8 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
     },
   },
   {
-    name: 'save_scratch_file',
-    description: 'Save text content to a file under <dataDir>/scratch/ and return a clickable download URL. USE THIS — not dispatch_task — when the user says "save this to a file", "create a file with X", "export the results", "give me a downloadable copy". The LLM provides the content directly (you already have it in context); no CLI task needed. Chat will auto-link any `scratch/<filename>` mention in your reply as a download link, so just mention the returned path in prose. Scratch is EPHEMERAL — files are auto-deleted after settings.scratchRetentionDays (default 7 days); tell the user this when handing over the link. Filename must be a bare relative name (no .. or /). Allowed extensions for the auto-link: .md .txt .json .yaml .yml .csv .log .html .pdf .png .jpg .jpeg .gif .svg.',
+    name: 'save_tmp_file',
+    description: 'Save text content to <dataDir>/tmp/<filename>. USE THIS — never dispatch_task — when the user says "save this to a file", "create a file with X", "export the results", "give me a downloadable copy". The LLM already has the content; no CLI task needed. Returns `file_url` (file://… that opens directly in Chrome on localhost) plus `path` ("tmp/<filename>") + `local_path`. tmp/ is cache-managed and gets swept by the cache janitor / "forge clean cache" — tell the user it\'s ephemeral. To UPLOAD this file to a connector (e.g. onedrive.upload_file content_base64), pass "scratch://tmp/<filename>" as the arg — Forge base64-encodes server-side; do NOT hand-encode. To read it back: read_forge_file with filename:"tmp/<filename>". Filename must be a bare relative name (no .. or /).',
     input_schema: {
       type: 'object',
       properties: {
@@ -668,6 +877,41 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
       required: ['filename', 'content'],
     },
   },
+  {
+    name: 'read_forge_file',
+    description: 'Read any file Forge manages under <dataDir>/ — tmp/ (chat-saved), scratch/ (task workspaces), flows/, prompts/, connectors/, etc. PREFER THIS over dispatch_task when the user wants to inspect a Forge-owned file. filename is a dataDir-relative path: "tmp/report.md", "flows/x.yaml", "connectors/onedrive/manifest.yaml". Sensitive files (encrypt key, sqlite DBs, server log, *-tokens.json at root) are refused. Text returns decoded UTF-8 (capped 256KB); pass as_base64:true for binary (pdf, images, zip). To UPLOAD to a connector, prefer "scratch://<dataDir-rel>" arg — bytes never traverse the model.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        filename: { type: 'string', description: 'dataDir-relative path, e.g. "tmp/report.md", "flows/mantis-bug-fix.yaml", "connectors/mantis/manifest.yaml".' },
+        as_base64: { type: 'boolean', description: 'Return raw bytes base64-encoded instead of decoded UTF-8 text. Use for binary files.' },
+      },
+      required: ['filename'],
+    },
+  },
+  {
+    name: 'list_forge_files',
+    description: 'List files / subdirs anywhere under <dataDir>/ (Forge\'s own data dir). PREFER THIS over `dispatch_task` with `ls` — it\'s sync, in-process, no LLM detour. `dir` is dataDir-relative: pass "tmp" for chat-saved temp files, "scratch" for task workspaces, "flows" / "prompts" / "connectors" for configs. Omit `dir` to see the dataDir root. Each entry has `path` (dataDir-relative), `kind` (file/dir), and `file_url` (file://… opens in Chrome on localhost). Sensitive items (encrypt key, sqlite DBs, server log, *-tokens.json) are filtered out automatically.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        dir: { type: 'string', description: 'dataDir-relative directory. Examples: "tmp", "scratch", "flows", "prompts", "connectors/mantis". Omit to list dataDir root.' },
+        ext: { type: 'string', description: 'Optional file-extension filter (e.g. ".md", ".yaml"). Lowercase match on suffix.' },
+        limit: { type: 'number', description: 'Max entries (default 200, capped at 500).' },
+      },
+    },
+  },
+  {
+    name: 'cancel_task',
+    description: 'Cancel a still-running dispatched task by id. Use when the user says "停止 / cancel / kill the task" — much cleaner than telling them to open the Tasks UI. Safe to call on an already-terminal task (returns ok with note). task_id comes from dispatch_task\'s response.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task id from dispatch_task.' },
+      },
+      required: ['task_id'],
+    },
+  },
   {
     name: 'get_task_status',
     description: "Check a dispatched Forge task's status + result by id. Pass task_id (returned by dispatch_task). Returns JSON: {id, status: 'queued'|'running'|'done'|'failed'|'cancelled', terminal: bool, project, result_summary?, error?, completed_at?}. For start_watch, use done_path=\"terminal\" (fires on done/failed/cancelled) or done_match={path:\"status\",equals:\"done\"}.",
@@ -1090,6 +1334,15 @@ export async function dispatchTool(
   const cfgGap = preflightConnectorSettings(def, effectiveSettings);
   if (cfgGap) return { content: cfgGap, is_error: true };
 
+  // Resolve any `scratch://<file>` arg into the file's base64 content,
+  // server-side — so the LLM can hand a saved file to a connector
+  // (e.g. onedrive.upload_file content_base64) without hand-encoding it.
+  try {
+    await resolveScratchRefsInArgs(argInput);
+  } catch (e) {
+    return { content: `scratch reference failed: ${(e as Error).message}`, is_error: true };
+  }
+
   try {
     let result: ToolResult;
     switch (protocol) {

package/lib/chat/turn-control.ts

@@ -0,0 +1,109 @@
+/**
+ * Per-session control channel for an in-flight agent turn.
+ *
+ * A tool-call loop (agent-loop.ts) can otherwise run unattended for up to
+ * MAX_ITERATIONS with no way for the user to intervene — which is exactly
+ * how a doomed task melts an instance. This gives two levers, both scoped
+ * to a CURRENTLY RUNNING turn:
+ *   • abort — break the loop cleanly at the next iteration boundary
+ *   • notes — supplementary text the agent picks up on its next iteration
+ *
+ * State is in-process (chat-standalone owns the loop) and ephemeral: it is
+ * reset when the turn begins and cleared when it ends. Both levers no-op
+ * when no turn is running, so the caller can tell the user to just send a
+ * normal message instead.
+ */
+
+interface TurnControl {
+  running: boolean;
+  aborted: boolean;
+  notes: string[];
+}
+
+const controls = new Map<string, TurnControl>();
+
+function get(sessionId: string): TurnControl {
+  let c = controls.get(sessionId);
+  if (!c) {
+    c = { running: false, aborted: false, notes: [] };
+    controls.set(sessionId, c);
+  }
+  return c;
+}
+
+/** Mark a turn as live. Called by agent-loop at the top of runTurn.
+ *  Sets running:true + aborted:false. Does NOT clear notes — endTurn
+ *  is the one that clears them at completion. Important: if a turn was
+ *  claimed via tryBeginTurn in enqueueChatInput and a note arrived in
+ *  the async window before runTurn reached this point, the note must
+ *  survive to be picked up at the first iteration boundary. Wiping
+ *  here would silently drop user input. */
+export function beginTurn(sessionId: string): void {
+  const c = get(sessionId);
+  c.running = true;
+  c.aborted = false;
+  // notes intentionally preserved — see comment above.
+}
+
+/** Atomic claim — if no turn is running, mark running and return true.
+ *  If a turn is already running, return false (caller should merge as note).
+ *  Synchronous — closes the race window between "check isTurnRunning" and
+ *  runTurn actually entering its loop and calling beginTurn. Without this,
+ *  two enqueueChatInput calls arriving while runTurn is still in its async
+ *  setup phase BOTH see isTurnRunning=false and BOTH fork a turn — exactly
+ *  the duplicate-turn bug observed on 2026-06-10 (watch fired, user typed
+ *  immediately after, both got separate runTurns and produced doubled
+ *  tool calls). */
+export function tryBeginTurn(sessionId: string): boolean {
+  const c = get(sessionId);
+  if (c.running) return false;
+  c.running = true;
+  c.aborted = false;
+  // notes intentionally NOT cleared here — any addNote that landed in
+  // the race window before claim is valid input for THIS new turn.
+  // beginTurn (called by agent-loop on entry) will set notes=[] only if
+  // this is the very first turn; otherwise the prior endTurn already
+  // cleared them.
+  return true;
+}
+
+/** Turn finished (normally or via abort) — clear all transient state. */
+export function endTurn(sessionId: string): void {
+  const c = get(sessionId);
+  c.running = false;
+  c.aborted = false;
+  c.notes = [];
+}
+
+/** User asked to stop. Returns false if no turn is running (nothing to abort). */
+export function requestAbort(sessionId: string): boolean {
+  const c = get(sessionId);
+  if (!c.running) return false;
+  c.aborted = true;
+  return true;
+}
+
+export function isAborted(sessionId: string): boolean {
+  return get(sessionId).aborted;
+}
+
+export function isTurnRunning(sessionId: string): boolean {
+  return get(sessionId).running;
+}
+
+/** Queue supplementary info for the running turn. Returns false if idle. */
+export function addNote(sessionId: string, text: string): boolean {
+  const c = get(sessionId);
+  if (!c.running) return false;
+  c.notes.push(text);
+  return true;
+}
+
+/** Take + clear the queued notes (called by the loop each iteration). */
+export function consumeNotes(sessionId: string): string[] {
+  const c = get(sessionId);
+  if (c.notes.length === 0) return [];
+  const out = c.notes;
+  c.notes = [];
+  return out;
+}

package/lib/chat-standalone.ts

@@ -33,9 +33,11 @@
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
 import {
   createSession, getSession, listSessions, updateSession, deleteSession, listMessages,
-  clearSessionMessages, ensureMainSession, forkSession, appendMessage,
+  clearSessionMessages, ensureMainSession, forkSession,
 } from './chat/session-store';
-import { runTurn, type AgentEvent } from './chat/agent-loop';
+import { type AgentEvent } from './chat/agent-loop';
+import { requestAbort, addNote, isTurnRunning } from './chat/turn-control';
+import { enqueueChatInput } from './chat/input-queue';
 import { bridgePush } from './chat/bridge-client';
 import { startWatchRunner } from './watch/watch-runner';
 
@@ -173,20 +175,21 @@ async function handleMessagePost(req: IncomingMessage, res: ServerResponse, id:
   const text = String(body?.text || '').trim();
   if (!text) return sendJson(res, 400, { error: 'text is required' });
 
-  const startedAt = Date.now();
-  void runTurn({
+  // Route through the single input queue — handles isTurnRunning merge
+  // (so extension + webchat sending on same session collapse into one
+  // turn) without this handler caring how. See lib/chat/input-queue.ts.
+  const r = enqueueChatInput({
     sessionId: id,
-    userText: text,
-    callbacks: { onEvent: (e: AgentEvent) => fanoutEvent(id, e) },
-  }).then((r) => {
-    if (!r.ok) fanoutEvent(id, { type: 'error', data: { error: r.error || 'unknown' } });
-    console.log(`[chat] turn ${id.slice(0, 8)} done in ${Date.now() - startedAt}ms ok=${r.ok}`);
-  }).catch((err) => {
-    fanoutEvent(id, { type: 'error', data: { error: (err as Error).message } });
-    console.error('[chat] turn error', err);
+    text,
+    mode: 'turn',
+    source: 'user',
+    onEvent: (e) => fanoutEvent(id, e),
+  });
+  sendJson(res, 202, {
+    accepted: true,
+    merged: r.status === 'merged',
+    topic: `chat:${id}`,
   });
-
-  sendJson(res, 202, { accepted: true, topic: `chat:${id}` });
 }
 
 /**
@@ -204,11 +207,46 @@ async function handleInjectMessage(req: IncomingMessage, res: ServerResponse, id
   const role: 'user' | 'assistant' = body?.role === 'user' ? 'user' : 'assistant';
   const blocks = Array.isArray(body?.blocks) ? body.blocks : null;
   if (!blocks || blocks.length === 0) return sendJson(res, 400, { error: 'blocks[] required' });
-  const saved = appendMessage({ session_id: id, role, blocks });
-  // Payload shape must match what agent-loop emits — extension's
-  // messageFromServer(event.data) reads .id/.role/.blocks/.ts directly.
-  fanoutEvent(id, { type: 'message_saved', message_id: saved.id, data: saved });
-  sendJson(res, 200, { ok: true, message_id: saved.id });
+  // Announce mode — persist + SSE push, no agent invocation. Goes
+  // through the same input-queue for consistency (one entry point).
+  const r = enqueueChatInput({
+    sessionId: id,
+    blocks,
+    role,
+    mode: 'announce',
+    source: 'schedule',
+    onEvent: (e) => fanoutEvent(id, e),
+  });
+  if (!r.ok) return sendJson(res, 400, { error: r.reason || 'enqueue failed' });
+  sendJson(res, 200, { ok: true, message_id: r.messageId });
+}
+
+// Abort the in-flight tool-call loop for a session. The loop breaks at its
+// next iteration boundary and persists a "⏹ Stopped" sentinel. No-op (409)
+// when no turn is running.
+async function handleAbortPost(req: IncomingMessage, res: ServerResponse, id: string): Promise<void> {
+  const session = getSession(id);
+  if (!session) return sendJson(res, 404, { error: 'session not found' });
+  // Loud log: every abort goes through here. If "Stop" fires without a
+  // visible UI click, this print pins the culprit (user-agent / referer).
+  const accepted = requestAbort(id);
+  if (!accepted) return sendJson(res, 409, { ok: false, running: false, error: 'no active turn to stop' });
+  return sendJson(res, 200, { ok: true, running: true });
+}
+
+// Queue supplementary info for the running turn — the loop splices it in as
+// a user message the agent sees on its next iteration. 409 when idle (the
+// client should just send a normal message instead). The note appears in
+// the transcript when the loop consumes it (single source of truth).
+async function handleNotePost(req: IncomingMessage, res: ServerResponse, id: string): Promise<void> {
+  const session = getSession(id);
+  if (!session) return sendJson(res, 404, { error: 'session not found' });
+  const body = await readJson(req);
+  const text = String(body?.text || '').trim();
+  if (!text) return sendJson(res, 400, { error: 'text is required' });
+  const queued = addNote(id, text);
+  if (!queued) return sendJson(res, 409, { ok: false, running: false, error: 'no active turn — send it as a normal message instead' });
+  return sendJson(res, 200, { ok: true, running: true });
 }
 
 function handleEventsSse(_req: IncomingMessage, res: ServerResponse, id: string): void {
@@ -276,6 +314,12 @@ async function route(req: IncomingMessage, res: ServerResponse): Promise<void> {
   const inject = /^\/api\/sessions\/([^/]+)\/inject$/.exec(url.pathname);
   if (inject && m === 'POST') return handleInjectMessage(req, res, inject[1]!);
 
+  const abort = /^\/api\/sessions\/([^/]+)\/abort$/.exec(url.pathname);
+  if (abort && m === 'POST') return handleAbortPost(req, res, abort[1]!);
+
+  const note = /^\/api\/sessions\/([^/]+)\/note$/.exec(url.pathname);
+  if (note && m === 'POST') return handleNotePost(req, res, note[1]!);
+
   const fork = /^\/api\/sessions\/([^/]+)\/fork$/.exec(url.pathname);
   if (fork && m === 'POST') return handleSessionFork(req, res, fork[1]!);
 
@@ -310,8 +354,18 @@ httpServer.listen(PORT, '127.0.0.1', () => {
   startWatchRunner({
     onProgress: (sessionId, payload) => fanoutEvent(sessionId, { type: 'watch_status', data: payload }),
     runChat: (sessionId, text) => {
-      void runTurn({ sessionId, userText: text, callbacks: { onEvent: (e) => fanoutEvent(sessionId, e) } })
-        .catch((err) => console.error('[watch] runChat failed', (err as Error).message));
+      // Watch-triggered chat input. Routes through the single input
+      // queue — automatically merges into a running turn (as a note)
+      // or starts a fresh one. Without going through enqueueChatInput
+      // a watch firing mid-turn would spawn a concurrent runTurn and
+      // produce duplicate tool calls (regression seen on 2026-06-09).
+      enqueueChatInput({
+        sessionId,
+        text,
+        mode: 'turn',
+        source: 'watch',
+        onEvent: (e) => fanoutEvent(sessionId, e),
+      });
     },
   });
 });

package/lib/help-docs/10-troubleshooting.md

@@ -88,6 +88,22 @@ rm -rf $(npm root -g)/@aion0/forge $(npm root -g)/@aion0/.forge-*
 npm install -g @aion0/forge
 ```
 
+### Chat keeps looping / "thinking…" never finishes
+The agent got stuck retrying a tool that can't succeed (e.g. a truncated
+result it keeps re-fetching). While a turn is running the `/chat` composer
+stays usable:
+- **■ Stop** — aborts the tool-call loop at the next step and posts a
+  "⏹ Stopped by user" message. Use this to break a runaway turn.
+- **Send** — type a correction/extra instruction and send it; while a turn
+  is running it's spliced into THAT turn (the agent reads it on its next
+  step), so you can redirect without cancelling. A normal `POST /messages`
+  is deliberately NOT used here — it would spawn a second concurrent loop on
+  the same session.
+
+These hit `POST /api/sessions/:id/abort` and `/note` on the chat backend, so
+any client (web `/chat`, extension) can drive them. `/note` no-ops (409) when
+no turn is running — the page then sends it as a normal new message instead.
+
 ## Logs
 
 - Background server: `~/.forge/data/forge.log`

package/lib/help-docs/17-connectors.md

@@ -165,6 +165,25 @@ tools:
 - `{base_url}` / `{settings.<name>}` → expanded server-side from saved settings
 - `{args.<name>}` → expanded by the runtime from the LLM's tool input
 
+**Forge-file args (`scratch://` connector-ref protocol)**: any tool arg
+whose whole value is a `scratch://<path>` reference is read from
+`<dataDir>/<path>` and replaced with the file's **base64** content,
+server-side, before the tool runs. The `scratch://` prefix is the
+ref protocol name (historical — not tied to the `scratch/` subdir); the
+path after it is **dataDir-relative**, so `scratch://tmp/foo.md`,
+`scratch://scratch/report.md`, `scratch://flows/x.yaml` all work.
+Sensitive items (encryption keys, sqlite DBs, server log, `*-tokens.json`
+at root) are refused. Bare-form references (`scratch/<file>` and
+`/api/scratch/<file>`) are accepted for back-compat — same dataDir-rooted
+resolution. This lets the chat agent hand a saved file straight to a
+connector (e.g. `onedrive.upload_file` `content_base64:
+"scratch://tmp/report.md"`) without hand-encoding it — hand-encoding
+large or non-ASCII content is unreliable. A missing file fails the call
+with a clear error (no retry). The companion builtin `read_forge_file`
+pulls Forge-managed file content back into chat context (same dataDir-
+relative paths, same sensitive blacklist). For *uploading*, prefer the
+`scratch://` ref so the bytes never round-trip through the model.
+
 **`script` contract**:
 - Receives `args` (the LLM's parameters)
 - Returns a JSON-serializable value (no DOM nodes, no functions)