@ducci/jarvis 1.0.38 → 1.0.40

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

@@ -1,271 +0,0 @@
-# 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

@@ -1,118 +0,0 @@
-# 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/findings/009-non-string-response-field.md

@@ -1,153 +0,0 @@
-# Finding 009: Non-String `response` Field Crashes Telegram Delivery
-
-**Date:** 2026-03-01
-**Severity:** High — caused "Sorry, something went wrong sending the response" with no useful information for the user
-**Status:** Fixed
-
----
-
-## Observed Session
-
-The session ran 19 agent runs, all completing successfully (`ok` or `checkpoint_reached`). The crash occurred on run 19. The user asked:
-
-> "List me all tool calls you did In this session. Tool name and args are enough to display for each entry."
-
-The model returned valid JSON but placed the list of tool calls as a JSON **array** (not a string) in the `response` field:
-
-```json
-{
-  "response": [
-    { "tool": "exec", "args": { "cmd": "find ..." } },
-    ...16 entries...
-  ],
-  "logSummary": "Enumerated every tool call made during the session..."
-}
-```
-
-The Telegram user received: **"Sorry, something went wrong sending the response. Please try again."**
-
----
-
-## Bug Chain
-
-### Step 1 — Agent parses valid JSON, stores non-string response
-
-`runAgentLoop` in `src/server/agent.js` successfully parsed the model's response JSON. The extraction logic had no type check:
-
-```js
-response = parsed.response || content;
-```
-
-`parsed.response` was an array (truthy) → `response` was set to the array. No validation. The array propagated through `finalResponse` all the way to the return value of `handleChat`.
-
-### Step 2 — Telegram handler crashes calling `.trim()` on an array
-
-In `src/channels/telegram/index.js`:
-
-```js
-const text = result.response?.trim()
-  || 'The agent encountered an error...';
-```
-
-`?.` guards against `null` and `undefined` only — not against wrong types. Arrays do not have a `.trim()` method. This threw:
-
-```
-TypeError: result.response.trim is not a function
-```
-
-### Step 3 — Delivery catch block sends the generic error
-
-The TypeError was caught by the outer delivery try/catch, which replied:
-
-```
-Sorry, something went wrong sending the response. Please try again.
-```
-
-The user had no idea what failed. The agent had completed successfully — only the delivery step crashed.
-
----
-
-## Root Causes
-
-**Primary**: `agent.js` never validates that `parsed.response` is a string after JSON parsing. The response contract ("Your message to the user, in plain text.") is documented but never enforced. Any JSON value — array, object, number, null — passes through silently.
-
-**Secondary**: `telegram/index.js` assumed `result.response` would always be a string or null/undefined, and called `.trim()` without type-guarding.
-
-The same primary bug exists in the wrap-up path (line ~315):
-```js
-response = parsedWrapUp.response || '';
-```
-This would fail identically if the wrap-up model returned a non-string `response`.
-
----
-
-## What Was Not Caught Earlier
-
-- The JSONL log stored `response: [array]` but the run status was `ok` — nothing flagged as an error on the agent side.
-- The error only surfaces in the Telegram delivery layer, which has no visibility into the JSONL log.
-- The model had valid intent (listing tool calls as a structured data type) — it just put the data in the wrong JSON field type.
-
----
-
-## Fix
-
-### 1. `src/server/agent.js` — normalize response to string at both sites
-
-**Main response path:**
-```js
-// Before:
-response = parsed.response || content;
-
-// After:
-response = typeof parsed.response === 'string'
-  ? parsed.response
-  : JSON.stringify(parsed.response, null, 2);
-```
-
-**Wrap-up path:**
-```js
-// Before:
-response = parsedWrapUp.response || '';
-
-// After:
-response = typeof parsedWrapUp.response === 'string'
-  ? parsedWrapUp.response
-  : parsedWrapUp.response != null ? JSON.stringify(parsedWrapUp.response, null, 2) : '';
-```
-
-When the model returns a non-string (array, object), it is JSON-stringified with 2-space indentation. The user gets a readable representation of the intended content rather than a crash. This preserves the model's intent while enforcing the string contract.
-
-### 2. `src/channels/telegram/index.js` — defense-in-depth type guard
-
-```js
-// Before:
-const text = result.response?.trim()
-  || 'The agent encountered an error and could not produce a response. Please try again.';
-
-// After:
-const rawResponse = typeof result.response === 'string'
-  ? result.response
-  : result.response != null ? JSON.stringify(result.response, null, 2) : '';
-const text = rawResponse.trim()
-  || 'The agent encountered an error and could not produce a response. Please try again.';
-```
-
-### 3. `docs/system-prompt.md` — explicit type constraint on `response`
-
-Added one sentence to the `## Response Format` section:
-
-```
-The `response` value must be a plain text string — never an array or object. If you need to present structured data (e.g. a list of items), format it as text within the string value.
-```
-
----
-
-## Outcome
-
-| Fix | Files changed |
-|-----|--------------|
-| Coerce `parsed.response` to string in main and wrap-up paths | `src/server/agent.js` |
-| Type guard before `.trim()` call | `src/channels/telegram/index.js` |
-| Explicit type constraint on `response` field | `docs/system-prompt.md` |
-
-**Effect on the debugging session**: instead of "Sorry, something went wrong sending the response", the user would have received the tool call list formatted as a readable JSON string.

package/docs/findings/010-checkpoint-field-type-safety.md

@@ -1,121 +0,0 @@
-# Finding 010: Non-String `checkpoint.remaining` Crashes Zero-Progress Detection
-
-**Date:** 2026-03-01
-**Severity:** High — caused "Sorry, something went wrong" in Telegram with no useful context; crashed the handoff loop mid-run
-**Status:** Fixed
-
----
-
-## Observed Session
-
-The session ran 13+ agent runs working on OWASP ZAP installation. Runs 8–13 were consecutive `checkpoint_reached` handoffs. On entry 14 (immediately after entry 13), the server logged:
-
-```
-status: error
-response: "An unexpected server error occurred: (run.checkpoint.remaining || "").trim is not a function"
-```
-
-The Telegram user received:
-
-```
-Sorry, something went wrong: (run.checkpoint.remaining || "").trim is not a function
-```
-
----
-
-## Bug Chain
-
-### Step 1 — Wrap-up call returns non-string `remaining`
-
-At iteration limit, `runAgentLoop` sends the `WRAP_UP_NOTE` and parses the model's JSON response. The model returned `checkpoint.remaining` as a non-string value (array or object) instead of a plain text string. `parsedWrapUp.checkpoint` was stored and returned with no type validation.
-
-### Step 2 — Zero-progress detection crashes on `.trim()`
-
-In `_runHandleChat`, finding 007 introduced zero-progress detection:
-
-```js
-const currentRemaining = (run.checkpoint.remaining || '').trim();
-```
-
-The `|| ''` guard only catches falsy values (null, undefined). A truthy non-string (array, object) passes through the `||` and `.trim()` is called on a non-string:
-
-```
-TypeError: (run.checkpoint.remaining || "").trim is not a function
-```
-
-### Step 3 — Outer catch logs the error and re-throws
-
-The `try/catch` at the top of the handoff loop caught the TypeError, wrote an `error` status log entry, and re-threw. The Telegram handler surfaced the raw error message.
-
----
-
-## Secondary Issues
-
-**`resumeContent` (line 520)**: `run.checkpoint.remaining || 'Continue with the task.'` — if `remaining` is a truthy non-string, it would be pushed directly into `session.messages` as the next user message content. The message API expects a string, so this would produce a malformed conversation message.
-
-**`failedApproaches` spread (lines 461–463)**: If the model returns `failedApproaches` as a non-array (string, object), `push(...value)` would spread wrong data. A string spreads individual characters; an object spreads its enumerable values.
-
----
-
-## Root Cause
-
-Same class of bug as finding 009 (non-string `response` field). Finding 009 hardened `response` and `logSummary` extraction, but the `checkpoint` sub-object fields were not included in that hardening pass. Models — especially smaller/free models under iteration-limit pressure — sometimes return structured data (arrays, objects) in fields the system prompt specifies as plain text strings.
-
----
-
-## Fix
-
-### `src/server/agent.js` — normalize checkpoint fields at source
-
-Added a normalization block immediately inside the `if (parsedWrapUp.checkpoint)` branch, before any checkpoint field is accessed downstream:
-
-```js
-const cp = parsedWrapUp.checkpoint;
-// remaining must be a string — used as the next run's resume prompt
-if (typeof cp.remaining !== 'string') {
-  cp.remaining = Array.isArray(cp.remaining)
-    ? cp.remaining.map(String).join('\n')
-    : cp.remaining != null ? JSON.stringify(cp.remaining) : '';
-}
-// failedApproaches must be an array of strings — spread into session metadata
-if (!Array.isArray(cp.failedApproaches)) {
-  cp.failedApproaches = [];
-} else {
-  cp.failedApproaches = cp.failedApproaches.map(item =>
-    typeof item === 'string' ? item : JSON.stringify(item)
-  );
-}
-```
-
-**Array coercion for `remaining`**: when the model returns an array (e.g., `["install Java", "create symlink"]`), elements are joined with newlines rather than JSON-stringified — producing a natural readable resume prompt rather than raw JSON syntax.
-
-**Centralized normalization**: fixing at source (right after parse) rather than at each use site means lines 469 and 520 need no change. Any future use of `checkpoint.remaining` or `checkpoint.failedApproaches` is automatically safe.
-
-### `src/server/agent.js` — update `WRAP_UP_NOTE`
-
-Added explicit type constraints to the `remaining` field description and a trailing instruction:
-
-```
-"remaining": "What still needs to be done — as a plain text string, never an array or object."
-...
-remaining must be a plain text string. failedApproaches must be a JSON array of strings.
-```
-
----
-
-## What Was Not Changed
-
-- `agent.js` lines 469 and 520 — no changes needed; normalization at source makes them safe
-- `src/channels/telegram/index.js` — finding 007 and 009 already added `.catch(() => {})` and type guards on delivery
-- `sessions.js`, `tools.js` — no changes needed
-
----
-
-## Outcome
-
-| Fix | Files changed |
-|-----|--------------|
-| Normalize `checkpoint.remaining` to string and `checkpoint.failedApproaches` to string array at source | `src/server/agent.js` |
-| Add explicit type constraints to WRAP_UP_NOTE | `src/server/agent.js` |
-
-**Effect**: instead of a `TypeError` crash mid-handoff-loop, the model's non-string `remaining` value is coerced to a readable string and used as the resume prompt. The session continues normally.