@ducci/jarvis 1.0.23 → 1.0.25

package/docs/agent.md

@@ -503,6 +503,23 @@ Schema:
 - No additional per-run tool-call cap beyond iterations.
 - No token limit enforcement in v1.
 
+### Two-Level Tool Timeout Architecture
+
+Every tool execution is governed by two independent timeout layers:
+
+**Layer 1 — Outer wrapper** (`executeTool` in `src/server/tools.js`):
+```js
+const timeoutMs = tool.timeout || TOOL_TIMEOUT_MS;  // TOOL_TIMEOUT_MS = 60_000
+return await Promise.race([fn(toolArgs, ...), timeout]);
+```
+This is the hard cap. `tool.timeout` is a top-level property on the tool registry entry (not inside `definition` or `code`). `exec` has `timeout: 300_000` (5 minutes); `system_install` also has 5 minutes; all other tools default to 60s.
+
+**Layer 2 — Inner timeout** (inside the tool's `code`): e.g. `execAsync(cmd, { timeout: 270000 })`. Should be slightly shorter than Layer 1 to ensure a clean error from the inner call rather than a hard kill from the outer wrapper.
+
+**Declaring a custom timeout on a tool** (via `save_tool`): pass the optional `timeout` parameter (in ms, capped at 600,000). This writes the top-level `timeout` property to the tool entry in `tools.json`.
+
+**Important**: Modifying a seed tool's code via `save_tool` does NOT change its outer timeout — seed tools are restored to their original definition on server restart via `seedTools()`.
+
 ## User Info
 
 User info is stored as a small JSON file in the Jarvis data directory: `~/.jarvis/data/user-info.json`. `save_user_info` appends to the collection, and `read_user_info` returns the full set.

package/docs/findings/007-telegram-errors-and-handoff-stalling.md

@@ -0,0 +1,271 @@
+# Finding 007: Telegram Error Opacity, Empty Responses, and Handoff Stalling
+
+**Date:** 2026-02-28
+**Severity:** High — caused "Sorry, something went wrong" with no context, silent empty responses, and 40+ wasted iterations on a stuck task
+**Status:** Fixed
+
+---
+
+## Observed Session
+
+The session (`fdb3fb46`) ran on a Linux server using `nvidia/nemotron-3-nano-30b-a3b:free`. The user asked Jarvis to implement a cybersecurity scanning project and run a scan against `https://dviet.de`. The session produced 10 agent runs over approximately 2 hours, including 4 consecutive handoff runs that made no real progress, two "Sorry, something went wrong" errors in Telegram, and one completely silent (empty) Telegram message.
+
+---
+
+## What Happened — Full Run Sequence
+
+| Run | Trigger | Status | Telegram received |
+|-----|---------|--------|-------------------|
+| 1 | "Hi" | ok | "Hello Duc! 👋" |
+| 2 | "Weißt du wo das cybersecurity Projekt liegt?" | ok (9 iterations) | Location found |
+| 3 | "Kannst du das readme lesen..." | ok | README analysis |
+| 4 | "Yes implement the missing pieces..." | **format_error** | **Empty message (silent)** |
+| 5 | "What exactly went wrong?" (handoff 1) | checkpoint_reached | — (internal handoff loop) |
+| 6 | handoff 2 | checkpoint_reached | — (internal) |
+| 7 | handoff 3 | checkpoint_reached | — (internal) |
+| 8 | handoff 4 | **model_error** | **"Sorry, something went wrong: ..."** |
+| 9 | "What is your session id" | ok | Session ID |
+| 10 | "Do exec ls" | **model_error** | **"Sorry, something went wrong: ..."** |
+
+---
+
+## Issue 1: Generic "Sorry, something went wrong" with no context
+
+### What happened
+
+Runs 8 and 10 failed with `model_error: Empty choices array` — the nvidia free model returned a response with `choices: []`, producing no content at all. When `handleChat` threw an error, the Telegram channel's catch block sent:
+
+```
+Sorry, something went wrong. Please try again.
+```
+
+This is maximally unhelpful. The user has no idea whether the model failed, whether a tool crashed, whether the session is broken, or whether retrying will help.
+
+### Root cause
+
+The catch block in `src/channels/telegram/index.js` used a hardcoded string regardless of the actual error:
+
+```js
+} catch (e) {
+  console.error(`[telegram] agent error chat_id=${chatId}: ${e.message}`);
+  await ctx.reply('Sorry, something went wrong. Please try again.');
+  clearInterval(typingInterval);
+  return;
+}
+```
+
+The error message was logged to `console.error` (only visible in server logs, not to the user) and discarded.
+
+### Fix (`src/channels/telegram/index.js`)
+
+Pass `e.message` to the user reply:
+
+```js
+const errText = e.message
+  ? `Sorry, something went wrong: ${e.message}`
+  : 'Sorry, something went wrong. Please try again.';
+await ctx.reply(errText).catch(() => {});
+```
+
+The `.catch(() => {})` guards against a second failure when the Telegram API itself is unreachable — without it, a failed `ctx.reply` inside the catch block would throw an unhandled rejection.
+
+---
+
+## Issue 2: Empty Telegram message on `format_error`
+
+### What happened
+
+Run 4 ended with `format_error` — the model produced a non-JSON final response and all three recovery attempts (fallback model, nudge retry) also failed. The agent returned with `response: ""` (empty string). The Telegram handler then called:
+
+```js
+const text = result.response;  // ""
+await ctx.reply(text);          // ctx.reply("") — Telegram silently rejects empty messages
+```
+
+The user saw nothing. No error, no confirmation, no indication that anything had happened. From their perspective the message was sent and never received a reply.
+
+### Root cause
+
+The delivery block in `src/channels/telegram/index.js` used `result.response` directly without guarding against empty or null values. When `format_error` returns an empty string, `ctx.reply("")` is called and Telegram's API rejects it silently (HTTP 400 from Telegram, swallowed by grammy).
+
+Additionally, the error log in the delivery catch block used `result.response.length`, which would throw a `TypeError` if `result.response` was `null` rather than `""`.
+
+### Fix (`src/channels/telegram/index.js`)
+
+Guard with `?.trim()` and a fallback message:
+
+```js
+const text = result.response?.trim()
+  || 'The agent encountered an error and could not produce a response. Please try again.';
+```
+
+Also updated the delivery catch block to not reference `result.response.length` (which crashes on null).
+
+---
+
+## Issue 3: `failedApproaches` memory lost across handoff runs
+
+### What happened
+
+Runs 5, 6, 7, and 8 were all consecutive handoff runs triggered by a single user message ("What exactly went wrong?"). Each run correctly produced a `failedApproaches` array in its checkpoint — for example, "nuclei scan command timed out". However, the resume message for the next run was built using only the **current run's** `failedApproaches`:
+
+```js
+if (run.checkpoint.failedApproaches && run.checkpoint.failedApproaches.length > 0) {
+  resumeContent += `\n\n[System: The following approaches were tried and failed in the previous run — ...]`
+  // ↑ only the last run's failures, not all previous runs
+}
+```
+
+Run 6 started knowing about run 5's failures. Run 7 started knowing about run 6's failures — but had forgotten run 5's. Run 8 started knowing about run 7's failures — but had forgotten runs 5 and 6. The model could only see one run of history at a time and kept rediscovering and re-attempting strategies it had already tried.
+
+The session JSONL log shows runs 5, 6, 7, and 8 all executing nearly identical tool call sequences:
+
+- `nuclei -update-templates`
+- `nuclei -h`
+- `mkdir -p results/dviet.de`
+- `which node`
+- `ls -al /usr/local/share/nuclei` → error (directory doesn't exist)
+- `echo -e '#!/bin/bash...'` → broken scan.sh
+- `nuclei -silent ... -u https://dviet.de` → **60s timeout**
+- `nmap -sV -p 80,443 dviet.de` → host down
+- `nuclei -silent -t http-title ...` → **60s timeout**
+
+32 tool calls in run 8 alone, across only 3 model iterations — the model was dumping the same 10-call batch per iteration, learning nothing.
+
+### Fix (`src/server/agent.js`, `src/server/sessions.js`)
+
+**1.** Added `failedApproaches: []` to `session.metadata` in `createSession()`. This gives old sessions a graceful upgrade path (the field will be initialized to `[]` on the first new user message that resets handoff state).
+
+**2.** On every new user message, `failedApproaches` is reset alongside `handoffCount`:
+
+```js
+session.metadata.handoffCount = 0;
+session.metadata.failedApproaches = [];
+```
+
+**3.** After each `checkpoint_reached` run, the current run's failures are pushed onto the session-level accumulator:
+
+```js
+if (run.checkpoint.failedApproaches && run.checkpoint.failedApproaches.length > 0) {
+  if (!session.metadata.failedApproaches) session.metadata.failedApproaches = [];
+  session.metadata.failedApproaches.push(...run.checkpoint.failedApproaches);
+}
+```
+
+**4.** The resume message uses the full accumulated list instead of just the last run's:
+
+```js
+const allFailedApproaches = session.metadata.failedApproaches || [];
+if (allFailedApproaches.length > 0) {
+  resumeContent += `\n\n[System: The following approaches were tried and failed in previous runs — do not repeat them:\n${allFailedApproaches.map((a, i) => `${i + 1}. ${a}`).join('\n')}]`;
+}
+```
+
+The message changed from "in the **previous run**" to "in **previous runs**" to accurately reflect the scope.
+
+---
+
+## Issue 4: Zero-progress handoffs not detected
+
+### What happened
+
+Runs 5, 6, and 7 all hit `checkpoint_reached` with nearly identical `remaining` fields. Each run used 10 full iterations yet made no real progress — the `remaining` list after run 7 was essentially the same as after run 5. The handoff loop continued spawning new runs until `maxHandoffs` was hit, burning 30 more iterations and about 90 minutes of wall time.
+
+The existing `maxHandoffs` limit (default 5) is the only backstop, but it doesn't distinguish between runs that make real progress and runs that achieve nothing. It allows up to 5 useless handoffs before stopping.
+
+### Root cause
+
+No comparison was made between consecutive `checkpoint.remaining` values. The handoff loop always continued as long as `handoffCount <= maxHandoffs`, with no check that the agent had actually made forward progress.
+
+### Fix (`src/server/agent.js`)
+
+Introduced a `previousRemaining` variable in the handoff loop. Before each handoff continuation, the current `checkpoint.remaining` (trimmed) is compared against the previous run's value. If they are identical, the session is stopped immediately with `intervention_required`:
+
+```js
+let previousRemaining = null;
+
+// ... inside handoff loop, after checkpoint_reached:
+const currentRemaining = (run.checkpoint.remaining || '').trim();
+if (previousRemaining !== null && currentRemaining === previousRemaining) {
+  finalStatus = 'intervention_required';
+  finalLogSummary = 'Zero progress detected: task state unchanged after a full run. Human intervention required.';
+  // log, strip, break
+}
+previousRemaining = currentRemaining;
+```
+
+This fires on the **second** handoff with identical remaining — one repeat is allowed because the model may be working on the same items in a different order. Identical remaining on two consecutive runs means it is genuinely stuck.
+
+**Effect on the debugging session**: instead of running 4 useless handoffs (runs 5–8), the agent would have stopped at run 6 with `intervention_required`, saving 20 iterations and about 60 minutes.
+
+---
+
+## Issue 5: `echo -e` creates broken shell scripts on Ubuntu
+
+### What happened
+
+The model attempted to create `scan.sh` using:
+
+```sh
+echo -e '#!/bin/bash\n# Simple wrapper...\n...'
+```
+
+On Ubuntu, the default shell for non-interactive commands is `/bin/dash`, not `/bin/bash`. `dash` does not support `echo -e` — it treats `-e` as a literal argument, so the file started with:
+
+```
+-e #!/bin/bash
+# Simple wrapper...
+```
+
+Every attempt to run `scan.sh` failed with:
+
+```
+/root/.jarvis/projects/cybersecurity/scan.sh: 1: -e: not found
+```
+
+The model detected the error on the first try, but each subsequent handoff run repeated the exact same broken creation command, presumably because the `echo -e` pattern was deep in the model's training distribution for "create a shell script".
+
+### Root cause
+
+The system prompt's `## exec Safety` section gave guidance about filesystem scans and `cat` vs `grep`, but said nothing about portable file creation. The `echo -e` pattern works on bash but not on sh/dash, and this distinction is invisible to a model working through `exec`.
+
+### Fix (`docs/system-prompt.md`)
+
+Added a bullet to `## exec Safety`:
+
+```
+- **Writing multi-line files**: use `printf '...'` or a heredoc (`cat <<'EOF' > file`) instead of
+  `echo -e`. The `-e` flag is not portable — on Ubuntu `/bin/sh` it is treated as literal text,
+  corrupting the file.
+```
+
+---
+
+## What Was Not Changed
+
+- The `model_error: Empty choices array` path in `runAgentLoop` — this is a provider-side failure, no server-side fix can prevent the model from returning nothing. The fix is at the Telegram delivery layer (surfacing the error to the user), not at the agent layer.
+- The `maxHandoffs` limit — it remains as a hard cap. Zero-progress detection fires before `maxHandoffs` in the case of a truly stuck task, so the two mechanisms are complementary.
+- The `consecutiveFailures` detector and exact-match loop tracker — unchanged; they work alongside the new zero-progress check.
+- No per-session Perplexity call counter was added server-side.
+
+---
+
+## Secondary Observation: nuclei templates were present but never found
+
+Nuclei was installed at `/usr/local/bin/nuclei`. Its templates were at `/root/nuclei-templates` (visible in the `list_dir /root` output from run 2). However, the model never connected these two facts — it searched `/usr/local/share/nuclei`, `/root/.nuclei`, and various `/usr` subdirectories, missing the templates that were right there in `/root`.
+
+Running `nuclei -u https://dviet.de -t /root/nuclei-templates/...` (or just `nuclei -u https://dviet.de` with the templates auto-discovered from `~/nuclei-templates`) would likely have worked. The scan also failed because `nmap` reported "host seems down" for `dviet.de` — the host was either rate-limiting ICMP or the port scan was blocked. Using `nmap -Pn` to skip host discovery would have bypassed this.
+
+Neither of these is a Jarvis bug — they are model reasoning failures specific to this session and this free model. A more capable model would have spotted the template path and the nmap flag.
+
+---
+
+## Outcome
+
+| Fix | Files changed |
+|-----|--------------|
+| Better error text in Telegram catch block | `src/channels/telegram/index.js` |
+| Guard against empty response before `ctx.reply()` | `src/channels/telegram/index.js` |
+| Accumulate `failedApproaches` across all handoffs in `session.metadata` | `src/server/agent.js`, `src/server/sessions.js` |
+| Zero-progress handoff detection via `previousRemaining` comparison | `src/server/agent.js` |
+| Shell script writing guidance (`printf`/heredoc over `echo -e`) | `docs/system-prompt.md` |

package/docs/findings/008-exec-timeout-architecture.md

@@ -0,0 +1,118 @@
+# Finding 008: exec Timeout Architecture — Agent Cannot Increase Its Own Timeout
+
+**Date:** 2026-02-28
+**Severity:** Medium — caused 5 wasted user interactions and agent confusion; no crashes or data loss
+**Status:** Fixed
+
+---
+
+## What Happened
+
+A user asked Jarvis to run a cybersecurity scan script (`nuclei` + `nmap`) against `https://dviet.de`. The script ran via the `exec` tool and timed out after 60 seconds. The user then asked the agent to "increase the timeout to 5 minutes."
+
+The agent attempted this in two ways:
+
+1. **Run 11**: Used `exec` to run `sed -i 's/"timeout": 60000/"timeout": 300000/g' tools.json` — changing the `timeout` value inside the exec tool's `code` string from 60s to 300s.
+2. **Run 13**: Called `save_tool` to recreate the exec tool with a "5-minute timeout" description and modified code.
+
+Both attempts failed. The scan timed out at 60s in every subsequent run. The agent and user concluded "the platform enforces a 60-second cap" — true, but neither understood why the agent's changes had no effect.
+
+---
+
+## Root Cause
+
+### The Two-Level Timeout Architecture
+
+Every tool execution is governed by two independent timeouts:
+
+**Layer 1 — Outer wrapper** (`executeTool` in `src/server/tools.js`):
+
+```js
+const timeoutMs = tool.timeout || TOOL_TIMEOUT_MS;  // TOOL_TIMEOUT_MS = 60_000
+const timeout = new Promise((_, reject) =>
+  setTimeout(() => reject(new Error(`Tool '${name}' timed out after ${timeoutMs / 1000}s`)), timeoutMs)
+);
+return await Promise.race([fn(toolArgs, ...), timeout]);
+```
+
+`tool.timeout` is a **top-level property on the tool registry entry** — not inside `definition` or `code`. Only `system_install` had this property set (to 300,000ms). The exec tool had no top-level `timeout`, so it always used the 60s default.
+
+**Layer 2 — Inner timeout** (inside the tool's `code`):
+
+The exec seed tool's code contains `execAsync(args.cmd, { timeout: 60000 })`. This is just a string stored in tools.json. Changing this number (via sed or save_tool) only affects the inner `execAsync` behavior — the outer Promise.race at 60s fires first anyway.
+
+### Why the Agent's Fixes Had No Effect
+
+1. **sed on the code string**: Changed the inner `execAsync` timeout from 60s to 300s. But the outer wrapper uses `tool.timeout || 60_000`, and `exec` has no `tool.timeout` property. The outer race still fires at 60s and wins.
+
+2. **`save_tool` recreation**: `save_tool` writes `{ definition, code }` to tools.json — it had no `timeout` parameter. The exec entry still had no top-level `timeout` after `save_tool`. Same result.
+
+### Why seedTools() Makes This Permanent
+
+Even if a manual edit to tools.json successfully added `exec.timeout = 300000`, the next server restart would run `seedTools()`, compare against `SEED_TOOLS.exec` (which has no timeout), and restore it — losing the change.
+
+---
+
+## What Changed
+
+### 1. `exec` seed tool now has a 5-minute timeout (`src/server/tools.js`)
+
+Added `timeout: 300_000` as a top-level property on the exec seed tool — the simplest fix:
+
+```js
+exec: {
+  timeout: 300_000, // 5 minutes — Layer 1 outer wrapper reads this
+  definition: { ... },
+  code: `... execAsync(args.cmd, { timeout: 270000 }) ...` // 4.5 min inner, leaves headroom
+}
+```
+
+The inner `execAsync` timeout was also updated from 60s to 270s (4.5 min) so it fires cleanly before the outer wrapper, giving a proper error message rather than a hard kill.
+
+### 2. `save_tool` now accepts a `timeout` parameter (`src/server/tools.js`)
+
+The `save_tool` tool now accepts an optional `timeout` field (in milliseconds, max 600,000 = 10 minutes). When provided, it is written as a top-level property on the tool entry:
+
+```js
+const entry = { definition: { ... }, code: args.code };
+if (args.timeout !== undefined) {
+  const t = Number(args.timeout);
+  entry.timeout = Math.min(t, 600_000);
+}
+tools[args.name] = entry;
+```
+
+This allows the agent to create custom tools with explicit timeout declarations when wrapping slow operations.
+
+### 3. System prompt updated (`docs/system-prompt.md`)
+
+Added a `## Execution Timeouts` section documenting:
+- `exec` = 5-minute cap (covers scans, builds, and most long-running commands)
+- `system_install` = 5-minute cap, use for package installation
+- Custom tools via `save_tool` = 60s default, pass `timeout` param to extend
+- Background execution pattern for processes > 5 minutes
+
+### 4. `agent.md` updated (`docs/agent.md`)
+
+Added a `### Two-Level Tool Timeout Architecture` subsection under `## Limits and Timeouts` explaining:
+- The outer wrapper and how `tool.timeout` is read
+- The inner timeout in tool code and its relationship to the outer
+- How to declare a custom timeout via `save_tool`
+- Why seed tool modifications via `save_tool` don't change the outer timeout (seedTools() restores on restart)
+
+---
+
+## What Was Not Changed
+
+- `TOOL_TIMEOUT_MS` constant — remains at 60,000ms (the default for tools without an explicit timeout)
+- `system_install` — unchanged
+- The handoff system, checkpoint memory, loop detection — all unchanged
+- `seedTools()` update detection logic — unchanged
+
+---
+
+## Outcome
+
+- `exec` now has a 5-minute timeout — long-running scans, builds, and downloads work without any workaround
+- The agent can set custom timeouts on tools it creates via `save_tool`
+- The system prompt and docs explain the architecture so the agent doesn't waste iterations on an unsolvable problem

package/docs/system-prompt.md

@@ -52,6 +52,22 @@ The `exec` tool runs real shell commands on the server. Use it responsibly:
 - **Use known paths.** Prefer `process.cwd()`, `$HOME`, or paths you already know over broad searches. Use `which <binary>` to locate executables.
 - **Prefer targeted reads.** Use `grep`, `head`, or `tail` instead of `cat` on files you haven't seen before. Large file output is truncated anyway — a targeted command gives you better signal.
 - **Avoid commands with unbounded runtime.** If a command could run indefinitely or scan an unknown-size tree, scope it first.
+- **Writing multi-line files**: use `printf '...'` or a heredoc (`cat <<'EOF' > file`) instead of `echo -e`. The `-e` flag is not portable — on Ubuntu `/bin/sh` it is treated as literal text, corrupting the file.
+
+## Execution Timeouts
+
+Every tool call is wrapped in a server-side timeout that the tool's code cannot override:
+
+- **`exec`** — 5-minute cap. Sufficient for scans, builds, and most long-running commands.
+- **`system_install`** — 5-minute cap. Use for installing system binaries via a package manager.
+- **Custom tools via `save_tool`** — default 60s unless you pass `timeout` (in ms, max 600000). If a custom tool wraps a slow operation, set `timeout` explicitly.
+
+**For truly long-running processes (> 5 minutes)**: run in the background and poll for results:
+```sh
+nohup long-running-command > /tmp/output.log 2>&1 & echo $!
+# Check progress later
+cat /tmp/output.log
+```
 
 ## Failure Recovery
 
@@ -70,6 +86,7 @@ When building a custom tool with `save_tool`:
 - **Installing an npm package**: use the `npm_install` tool — it handles the correct install directory automatically. Then create the tool with `save_tool`. The tool code can `require('<package-name>')` directly.
 - **Installing a system binary** (e.g. nuclei, jq, ffmpeg, git): use the `system_install` tool — never use exec for this. It auto-detects the available package manager (brew/apt-get/snap) and has a 5-minute timeout sized for real downloads.
 - **Available bindings in tool code**: `args`, `fs`, `path`, `process`, `require`, `__jarvisDir` (absolute path to the jarvis server directory).
+- **Long-running custom tools**: if your tool wraps an operation that takes more than 60 seconds (e.g. a network call, a slow computation), pass `timeout` in milliseconds to `save_tool` (max 600000 = 10 minutes). Example: `save_tool({ name: "run_scan", timeout: 300000, ... })`.
 
 ## logSummary Guidelines
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ducci/jarvis",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "A fully automated agent system that lives on a server.",
   "main": "./src/index.js",
   "type": "module",

package/src/channels/telegram/index.js

@@ -50,7 +50,10 @@ export async function startTelegramChannel(config) {
       result = await handleChat(config, sessionId, ctx.message.text);
     } catch (e) {
       console.error(`[telegram] agent error chat_id=${chatId}: ${e.message}`);
-      await ctx.reply('Sorry, something went wrong. Please try again.');
+      const errText = e.message
+        ? `Sorry, something went wrong: ${e.message}`
+        : 'Sorry, something went wrong. Please try again.';
+      await ctx.reply(errText).catch(() => {});
       clearInterval(typingInterval);
       return;
     }
@@ -64,7 +67,9 @@ export async function startTelegramChannel(config) {
 
     try {
       const MAX_TG = 4096;
-      const text = result.response;
+      // Guard against empty response (e.g. format_error returns empty string)
+      const text = result.response?.trim()
+        || 'The agent encountered an error and could not produce a response. Please try again.';
       if (text.length <= MAX_TG) {
         await ctx.reply(text);
       } else {
@@ -74,8 +79,8 @@ export async function startTelegramChannel(config) {
       }
       console.log(`[telegram] response sent chat_id=${chatId} length=${text.length}`);
     } catch (e) {
-      console.error(`[telegram] delivery error chat_id=${chatId} length=${result.response.length}: ${e.message}`);
-      await ctx.reply('Sorry, something went wrong. Please try again.');
+      console.error(`[telegram] delivery error chat_id=${chatId}: ${e.message}`);
+      await ctx.reply('Sorry, something went wrong sending the response. Please try again.').catch(() => {});
     } finally {
       clearInterval(typingInterval);
     }

package/src/server/agent.js

@@ -381,9 +381,10 @@ async function _runHandleChat(config, sessionId, userMessage) {
     session = createSession(systemPromptTemplate);
   }
 
-  // Append user message and reset handoff counter
+  // Append user message and reset handoff state
   session.messages.push({ role: 'user', content: userMessage });
   session.metadata.handoffCount = 0;
+  session.metadata.failedApproaches = [];
 
   // Resolves {{user_info}} in system prompt at runtime (never persisted)
   function prepareMessages(messages) {
@@ -399,6 +400,8 @@ async function _runHandleChat(config, sessionId, userMessage) {
   let finalResponse = '';
   let finalLogSummary = '';
   let finalStatus = 'ok';
+  // Tracks checkpoint.remaining from the previous handoff run to detect zero progress
+  let previousRemaining = null;
 
   try {
     // Handoff loop
@@ -449,6 +452,36 @@ async function _runHandleChat(config, sessionId, userMessage) {
         status: 'checkpoint_reached',
       });
 
+      // Accumulate failedApproaches from this run into session metadata so the
+      // full history of failed strategies is available across all handoff runs.
+      if (run.checkpoint.failedApproaches && run.checkpoint.failedApproaches.length > 0) {
+        if (!session.metadata.failedApproaches) session.metadata.failedApproaches = [];
+        session.metadata.failedApproaches.push(...run.checkpoint.failedApproaches);
+      }
+
+      // Zero-progress detection: if checkpoint.remaining is identical to the previous
+      // handoff's remaining, the agent completed a full run without making any progress.
+      // Stop immediately rather than burning more iterations on a stuck task.
+      const currentRemaining = (run.checkpoint.remaining || '').trim();
+      if (previousRemaining !== null && currentRemaining === previousRemaining) {
+        finalResponse = run.response;
+        finalLogSummary = 'Zero progress detected: task state unchanged after a full run. Human intervention required.';
+        finalStatus = 'intervention_required';
+
+        await appendLog(sessionId, {
+          iteration: 0,
+          model: config.selectedModel,
+          userInput: userMessage,
+          toolCalls: [],
+          response: finalResponse,
+          logSummary: finalLogSummary,
+          status: 'intervention_required',
+        });
+        session.messages.splice(runStartIndex, session.messages.length - runStartIndex - 1);
+        break;
+      }
+      previousRemaining = currentRemaining;
+
       // Check handoff limit
       session.metadata.handoffCount++;
       if (session.metadata.handoffCount > config.maxHandoffs) {
@@ -478,10 +511,12 @@ async function _runHandleChat(config, sessionId, userMessage) {
 
       // Resume with checkpoint.remaining as new prompt.
       // Guard against null/undefined in case the model omitted the field.
-      // Prepend any failed approaches so the next run doesn't repeat them.
+      // Use the full accumulated failedApproaches list across ALL handoff runs so the
+      // agent has complete memory of what has already been tried and failed.
       let resumeContent = run.checkpoint.remaining || 'Continue with the task.';
-      if (run.checkpoint.failedApproaches && run.checkpoint.failedApproaches.length > 0) {
-        resumeContent += `\n\n[System: The following approaches were tried and failed in the previous run — do not repeat them:\n${run.checkpoint.failedApproaches.map((a, i) => `${i + 1}. ${a}`).join('\n')}]`;
+      const allFailedApproaches = session.metadata.failedApproaches || [];
+      if (allFailedApproaches.length > 0) {
+        resumeContent += `\n\n[System: The following approaches were tried and failed in previous runs — do not repeat them:\n${allFailedApproaches.map((a, i) => `${i + 1}. ${a}`).join('\n')}]`;
       }
       session.messages.push({ role: 'user', content: resumeContent });
     }

package/src/server/sessions.js

@@ -22,6 +22,7 @@ export function createSession(systemPromptTemplate) {
   return {
     metadata: {
       handoffCount: 0,
+      failedApproaches: [],
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
     },

package/src/server/tools.js

@@ -43,6 +43,7 @@ const SEED_TOOLS = {
     `,
   },
   exec: {
+    timeout: 300_000, // 5 minutes — scans, builds, and long commands need more than 60s
     definition: {
       type: 'function',
       function: {
@@ -67,7 +68,7 @@ const SEED_TOOLS = {
       try {
         const { stdout, stderr } = await execAsync(args.cmd, {
           encoding: "utf8",
-          timeout: 60000,
+          timeout: 270000, // 4.5 min — leaves headroom before the outer 5-min tool timeout
           maxBuffer: 2 * 1024 * 1024,
         });
         return { status: "ok", exitCode: 0, stdout, stderr };
@@ -144,12 +145,16 @@ const SEED_TOOLS = {
               type: 'string',
               description: 'The body of an async function. Must end with a return statement — the returned value becomes the tool result. Available bindings: args (your tool parameters), fs (node:fs), path (node:path), process, require, __jarvisDir (absolute path to the jarvis server directory — use path.resolve(__jarvisDir, "../..") to get the project root for npm installs). Do NOT wrap in a function declaration. Example: const raw = await fs.promises.readFile(args.filePath, "utf8"); const data = JSON.parse(raw); return { count: data.length, first: data[0] };',
             },
+            timeout: {
+              type: 'number',
+              description: 'Optional execution timeout in milliseconds for this tool (max 600000 = 10 minutes). Use this when the tool wraps a slow operation (e.g. a network request or long computation) that exceeds the default 60-second limit. If omitted, the default 60-second timeout applies.',
+            },
           },
           required: ['name', 'description', 'parameters', 'code'],
         },
       },
     },
-    code: `const toolsFile = path.join(process.env.HOME, '.jarvis/data/tools/tools.json'); const raw = await fs.promises.readFile(toolsFile, 'utf8').catch(() => '{}'); const tools = JSON.parse(raw); let parameters = args.parameters; if (typeof parameters === 'string') { try { parameters = JSON.parse(parameters); } catch { return { status: 'error', error: 'parameters must be a JSON Schema object, not a string. Pass the object directly, not as a JSON-serialized string.' }; } } if (typeof parameters !== 'object' || parameters === null || Array.isArray(parameters)) { return { status: 'error', error: 'parameters must be a JSON Schema object (e.g. { type: "object", properties: {...} }).' }; } tools[args.name] = { definition: { type: 'function', function: { name: args.name, description: args.description, parameters } }, code: args.code }; await fs.promises.writeFile(toolsFile, JSON.stringify(tools, null, 2), 'utf8'); return { status: 'ok', saved: args.name };`,
+    code: `const toolsFile = path.join(process.env.HOME, '.jarvis/data/tools/tools.json'); const raw = await fs.promises.readFile(toolsFile, 'utf8').catch(() => '{}'); const tools = JSON.parse(raw); let parameters = args.parameters; if (typeof parameters === 'string') { try { parameters = JSON.parse(parameters); } catch { return { status: 'error', error: 'parameters must be a JSON Schema object, not a string. Pass the object directly, not as a JSON-serialized string.' }; } } if (typeof parameters !== 'object' || parameters === null || Array.isArray(parameters)) { return { status: 'error', error: 'parameters must be a JSON Schema object (e.g. { type: "object", properties: {...} }).' }; } const entry = { definition: { type: 'function', function: { name: args.name, description: args.description, parameters } }, code: args.code }; if (args.timeout !== undefined) { const t = Number(args.timeout); if (!Number.isFinite(t) || t <= 0) return { status: 'error', error: 'timeout must be a positive number in milliseconds.' }; entry.timeout = Math.min(t, 600_000); } tools[args.name] = entry; await fs.promises.writeFile(toolsFile, JSON.stringify(tools, null, 2), 'utf8'); return { status: 'ok', saved: args.name, timeout: entry.timeout || 60000 };`,
   },
   get_tool: {
     definition: {