create-walle 0.10.1 → 0.10.2

package/template/coding-task-manager/lib/session-create/worker-continuation.js

@@ -7,6 +7,12 @@ const admissionDefault = require('../worker-admission');
 const { restoreSucceeded } = require('../resume-rung-enrich');
 const transcriptRetention = require('../transcript-retention-check');
 const transcriptSource = require('../transcript-source');
+// WP-2 (D-4/D-7): the derived-transcript-path helper and its verifier (see the preflight at the
+// transcript link below). serverConfig is the same live-read env seam production uses for the
+// Claude config dir (server.js:6743 getClaudeConfigDir).
+const serverConfig = require('../server-config');
+const { deriveClaudeTranscriptPath } = require('../resume-cwd');
+const { verifyClaudeTranscriptAt } = require('../transcript-link');
 const { isColdDeferredSession, notifyWorkerGeneration } = require('./worker-observability');
 const { budgetSentence } = require('./worker-brief');
 const { attachProgressGuard } = require('./worker-progress-guard');
@@ -533,7 +539,43 @@ function createWorkerContinuation({ getDeps, admission = admissionDefault, helpe
     catch {
       return failReceipt('worker_transcript_unavailable', 'The provider transcript link could not be read.', { retryable: true });
     }
-    const transcriptPath = String(agentRow && agentRow.jsonl_path || '').trim();
+    // WP-2 (D-4, worker-transcript-link-derived-not-discovered-2026-10-25.html §5 D-4/D-7): an
+    // empty jsonl_path is "we never recorded the link", not "the transcript is gone". Claude Code
+    // writes a session's transcript at a path derivable from (cwd, session id) alone, so derive
+    // it, VERIFY it through the one transcript reader (lib/transcript-link.js -- the file's own
+    // first line must name this session), link it, and continue. A derived path that verifies
+    // false, or a row with no cwd to derive from, refuses exactly as before -- now naming what
+    // was checked. Codex rows never enter this branch (their resume identity is the rollout
+    // thread, and a missing link there is a different failure).
+    let transcriptPath = String(agentRow && agentRow.jsonl_path || '').trim();
+    if (!transcriptPath && agentRow && recipe.agent === 'claude') {
+      const cwd = String(recipe.cwd || agentRow.project_path || agentRow.cwd || '').trim();
+      const providerSessionId = String(agentRow.agent_session_id || id);
+      let derived = '';
+      try {
+        derived = deriveClaudeTranscriptPath({
+          cwd,
+          agentSessionId: providerSessionId,
+          // The house coercion for this dep (lib/session-create/worker-mcp-servers.js:45): production's
+          // deps carries no `homedir` at all, and the test corpus injects both a getter and a string.
+          homeDir: typeof deps.homedir === 'function' ? deps.homedir() : deps.homedir,
+          claudeConfigDir: deps.claudeConfigDir || serverConfig.CLAUDE_CONFIG_DIR || '',
+        });
+      } catch { /* expected: a row with no cwd (or no agent_session_id) has nothing to derive -- fall through to the unchanged refusal */ }
+      if (derived) {
+        const verified = await verifyClaudeTranscriptAt(derived, providerSessionId, {
+          ...(typeof deps.resolveTranscriptSource === 'function' ? { resolveTranscriptSource: deps.resolveTranscriptSource } : {}),
+          ...(typeof deps.readTranscriptHead === 'function' ? { readTranscriptHead: deps.readTranscriptHead } : {}),
+        });
+        if (!verified.ok) {
+          return failReceipt('worker_transcript_missing', 'The provider transcript is not linked to this worker.', {
+            extra: { derived_path: derived, derived_state: verified.state },
+          });
+        }
+        if (typeof db.updateAgentSessionTranscriptLink === 'function') db.updateAgentSessionTranscriptLink(providerSessionId, derived);
+        transcriptPath = derived;
+      }
+    }
     if (!transcriptPath) return failReceipt('worker_transcript_missing', 'The provider transcript is not linked to this worker.');
 
     let providerId = '';

package/template/coding-task-manager/lib/session-create/worker-notices.js

@@ -1,9 +1,12 @@
 'use strict';
 
 // A lead hears that its delegated worker stopped through its next PostToolUse / UserPromptSubmit
-// hook (lib/api/ingress.js -> bin/claude-hook.js). The queue lives here; the durable truth is the
-// terminal receipt's `delivered_at_ms` in worker_sessions.runtime_json, so a CTM restart rebuilds
-// the undelivered notices once per parent. Never types into the lead's terminal.
+// hook, and -- RC-1, docs/session-stops-mid-job-2026-10-24.html D-1..D-3 -- through its Stop hook
+// too, which is answered synchronously by CTM with the drained notices plus, when the lead still
+// owns a live worker and nothing pending will wake it, a nudge naming walle_worker_wait /
+// walle_stop_worker. The queue lives here; the durable truth is the terminal receipt's
+// `delivered_at_ms` in worker_sessions.runtime_json, so a CTM restart rebuilds the undelivered
+// notices once per parent. Never types into the lead's terminal (D-5).
 
 const mainDbCensus = require('../main-db-census');
 const { nextStepFor } = require('../worker-failure-classify');
@@ -13,6 +16,88 @@ const MAX_TEXT = 400;
 
 const _queues = new Map(); // parent ctm id -> [{ receipt_id, worker_id, parent, text, at_ms }]
 
+// WP-0 (D-2/D-7): the live-worker index, maintained from the receipts CTM already publishes.
+// Memory only -- the hook path touches no DB, and a CTM restart retires every live worker, so the
+// index starts empty and needs no rebuild.
+const _live = new Map(); // parent ctm id -> Map(worker id -> { generation, at_ms })
+
+// WP-1 (D-4): one nudge per tool epoch. `nudgedAtEpoch` starts at `null` so the first Stop
+// (toolEpoch 0) nudges; a second Stop with no PostToolUse between sees toolEpoch === nudgedAtEpoch.
+const _epochs = new Map(); // parent ctm id -> { toolEpoch, nudgedAtEpoch }
+
+function _epochFor(parent) {
+  let epoch = _epochs.get(parent);
+  if (!epoch) { epoch = { toolEpoch: 0, nudgedAtEpoch: null }; _epochs.set(parent, epoch); }
+  return epoch;
+}
+
+// D-2: a `started` receipt says this worker is live for its parent until a terminal receipt for the
+// same or a newer generation arrives. No parent or no worker id -> nothing to index.
+function markWorkerLive(receipt) {
+  if (!receipt || receipt.kind !== 'started') return null;
+  const parent = String(receipt.parent_ctm_session_id || '');
+  const workerId = String(receipt.worker_id || '');
+  if (!parent || !workerId) return null;
+  const generation = Number(receipt.generation) || 1;
+  const atMs = Number(receipt.at_ms) || Date.now();
+  const map = _live.get(parent) || new Map();
+  map.set(workerId, { generation, at_ms: atMs });
+  _live.set(parent, map);
+  return { worker_id: workerId, generation, at_ms: atMs };
+}
+
+// The terminal receipt retires the worker, but an OLDER generation's terminal must never erase a
+// newer generation's `started` (AC-0c): the remove happens only while stored generation <= receipt
+// generation.
+function markWorkerGone(receipt) {
+  const parent = String(receipt?.parent_ctm_session_id || '');
+  const workerId = String(receipt?.worker_id || '');
+  if (!parent || !workerId) return false;
+  const map = _live.get(parent);
+  if (!map) return false;
+  const entry = map.get(workerId);
+  if (entry && Number(entry.generation) > (Number(receipt.generation) || 1)) return false;
+  map.delete(workerId);
+  if (!map.size) _live.delete(parent);
+  return true;
+}
+
+function liveWorkers(parentCtmSessionId) {
+  const parent = String(parentCtmSessionId || '');
+  const map = _live.get(parent);
+  if (!map || !map.size) return [];
+  return [...map.entries()]
+    .map(([worker_id, entry]) => ({ worker_id, generation: entry.generation, at_ms: entry.at_ms }))
+    .sort((a, b) => a.at_ms - b.at_ms);
+}
+
+function noteLeadToolUse(parentCtmSessionId) {
+  const parent = String(parentCtmSessionId || '');
+  if (!parent) return null;
+  const epoch = _epochFor(parent);
+  epoch.toolEpoch += 1;
+  return epoch.toolEpoch;
+}
+
+// D-3/D-4: the Stop nudge. Returns null when no worker is live, when a pending background task or
+// session cron will wake the lead anyway, when the field is absent (Claude did not send it --
+// unknown state fails open, never a nudge), or when this tool epoch was already nudged.
+function stopNudge(parentCtmSessionId, { backgroundTasks = null, sessionCrons = null } = {}) {
+  const parent = String(parentCtmSessionId || '');
+  if (!parent) return null;
+  const workers = liveWorkers(parent);
+  if (!workers.length) return null;
+  if (Array.isArray(backgroundTasks) && backgroundTasks.some((task) => task && task.status === 'running')) return null;
+  if (Array.isArray(sessionCrons) && sessionCrons.length) return null;
+  if (!Array.isArray(backgroundTasks)) return null;
+  const epoch = _epochFor(parent);
+  if (epoch.toolEpoch === epoch.nudgedAtEpoch) return null;
+  epoch.nudgedAtEpoch = epoch.toolEpoch;
+  const firstId = workers[0].worker_id;
+  const text = `Delegated worker ${firstId} is still working (${workers.length} live) and nothing pending will wake you when it finishes. Call walle_worker_wait to keep waiting, or walle_stop_worker if you no longer need it. If you are deliberately handing back to your user with the worker still running, say so and end your turn again.`;
+  return { text, workers: workers.map((worker) => worker.worker_id) };
+}
+
 // D-25: the notice ends with the failure's next_step. The evidence carries it when the
 // publisher stamped it; a receipt stored before that (or filtered by the evidence
 // whitelist) still names the code/class/reason, so the SAME table derives the identical
@@ -51,6 +136,7 @@ function noticeText(receipt) {
 function enqueueNotice(receipt) {
   const parent = String(receipt?.parent_ctm_session_id || '');
   if (!parent || receipt.kind !== 'terminal' || !receipt.receipt_id) return null;
+  markWorkerGone(receipt);
   const notice = { receipt_id: receipt.receipt_id, worker_id: String(receipt.worker_id || ''), parent, text: noticeText(receipt), at_ms: Number(receipt.at_ms) || Date.now() };
   const queue = _queues.get(parent) || [];
   if (!queue.some((n) => n.receipt_id === notice.receipt_id)) queue.push(notice);
@@ -132,6 +218,9 @@ function drainNotices(parentCtmSessionId, { now = Date.now(), dbModule = null, d
   };
 }
 
-function _resetForTest() { _queues.clear(); }
+function _resetForTest() { _queues.clear(); _live.clear(); _epochs.clear(); }
 
-module.exports = { enqueueNotice, rebuildFromDb, drainNotices, noticeText, _resetForTest };
+module.exports = {
+  enqueueNotice, rebuildFromDb, drainNotices, noticeText,
+  markWorkerLive, liveWorkers, noteLeadToolUse, stopNudge, _resetForTest,
+};

package/template/coding-task-manager/lib/session-create/worker-observability.js

@@ -4,7 +4,8 @@ const path = require('path');
 const { captureWorkerProgress } = require('./worker-progress');
 const { classifyFailure } = require('../worker-failure-classify');
 const { terminalBudgetFailure, budgetEvidence } = require('../model-proxy/request-budget');
-const { enqueueNotice } = require('./worker-notices');
+const { enqueueNotice, markWorkerLive } = require('./worker-notices');
+const { startWaitWatcher } = require('./worker-wait-watcher');
 
 const PROGRESS_CACHE_MS = 5000;
 const EVENT_RECEIPT_LIMIT = 32;
@@ -13,6 +14,10 @@ const NO_WRITE_ADVISORY_TURN_THRESHOLD = 20;
 const NO_WRITE_TERMINAL_TURN_THRESHOLD = 40;
 const EVENT_PRECEDENCE = { started: 0, progress: 1, advisory: 2, terminal: 3 };
 const WORKER_FINAL_RESULT_CAP_BYTES = 64 * 1024;
+// Lead-cost routing round 2 D-3 (§6.2): the ONE report-text byte cap, shared by the status reader
+// (delegate-worker.js counts citations from the bounded text) and the ?include_report=1 reader
+// (lib/api/sessions.js). Same 64 KiB as the final-result cap.
+const WORKER_REPORT_TEXT_CAP_BYTES = 64 * 1024;
 const FILE_PROBE_TTL_MS = 2000;
 const THROTTLED_WINDOW_MS = 60000;
 
@@ -89,10 +94,17 @@ function _removeWaiterRegistration(waiter, ctmSessionId) {
   if (!set.size) _waiters.delete(ctmSessionId);
 }
 const _liveWaiters = new Set(); // every not-yet-resolved waiter, once each (waiterCount counts waiters, not registrations)
-function _finishWaiter(waiter, why, workerId) {
+function _finishWaiter(waiter, why, workerId, detail) {
   if (waiter.done) return;
   waiter.done = true;
   clearTimeout(waiter.timer);
+  // WP-1 (D-3): a resolved waiter stops its watcher first, so a late model reply is dropped
+  // (stop() marks the watcher dead) and no interval timer outlives the wait.
+  if (waiter.watch) {
+    try { waiter.watch.stop(); }
+    catch { /* expected: a watcher stop failure never blocks the resolve */ }
+    waiter.watch = null;
+  }
   for (const id of waiter.watchedIds) _removeWaiterRegistration(waiter, id);
   _liveWaiters.delete(waiter);
   if (waiter.onHumanSubmit) {
@@ -100,9 +112,16 @@ function _finishWaiter(waiter, why, workerId) {
     humanInputEvents.removeListener('humanSubmit', waiter.onHumanSubmit);
     waiter.onHumanSubmit = null;
   }
-  waiter.resolve({ why, workerId: workerId != null ? workerId : null });
+  const result = { why, workerId: workerId != null ? workerId : null };
+  // WP-1: the watcher's own result fields exist only on a waiter that ran one -- a caller with
+  // no watcher sees exactly today's `{ why, workerId }` shape.
+  if (waiter.decisions) {
+    result.detail = detail || null;
+    result.decisions = waiter.decisions;
+  }
+  waiter.resolve(result);
 }
-function waitForWorkers({ workerIds, leadId, waitMs, generationById } = {}) {
+function waitForWorkers({ workerIds, leadId, waitMs, generationById, watchMode, callModel, getStatus, readTail, workerRoute } = {}) {
   const ids = Array.isArray(workerIds) ? workerIds.map((id) => String(id || '')).filter(Boolean) : [];
   if (!ids.length) {
     // No watched workers: the wait is still meaningful for a lead (a user_input wake with no
@@ -111,7 +130,7 @@ function waitForWorkers({ workerIds, leadId, waitMs, generationById } = {}) {
     const empty = { generationById: {} };
     return waitForWorkersWithListener([], leadId, waitMs, empty);
   }
-  return waitForWorkersWithListener(ids, leadId, waitMs, { generationById });
+  return waitForWorkersWithListener(ids, leadId, waitMs, { generationById, watchMode, callModel, getStatus, readTail, workerRoute });
 }
 function waitForWorkersWithListener(ids, leadId, waitMs, state) {
   let release = () => {};
@@ -124,7 +143,7 @@ function waitForWorkersWithListener(ids, leadId, waitMs, state) {
       done: false,
       resolve,
     };
-    const finish = (why, workerId) => _finishWaiter(waiter, why, workerId);
+    const finish = (why, workerId, detail) => _finishWaiter(waiter, why, workerId, detail);
     waiter.finish = finish;
     waiter.timer = setTimeout(() => finish('timeout'), Math.max(0, Number(waitMs) || 0));
     if (typeof waiter.timer.unref === 'function') waiter.timer.unref();
@@ -142,12 +161,64 @@ function waitForWorkersWithListener(ids, leadId, waitMs, state) {
       humanInputEvents.on('humanSubmit', waiter.onHumanSubmit);
     }
     release = () => finish('timeout');
+    // WP-1 (D-3/D-4): the watcher parks BESIDE the waiter -- one tick per watched worker, the
+    // worker's own pinned model, and a `watcher`/`watcher_unavailable` wake through the same
+    // finish gate as every code wake. It is started only when the caller wired one (a caller
+    // with no watchMode/callModel keeps today's behaviour untouched).
+    if (ids.length && state.watchMode !== 'off' && typeof state.callModel === 'function') {
+      waiter.decisions = [];
+      waiter.watch = startWaitWatcher({
+        workerIds: ids,
+        mode: state.watchMode || 'on',
+        wake: (why, detail) => finish(why, detail && detail.worker_id, detail),
+        onDecision: (d) => waiter.decisions.push(d),
+        callModel: state.callModel,
+        getStatus: state.getStatus,
+        readTail: state.readTail,
+        workerRoute: state.workerRoute,
+      }) || null;
+    }
     // F1: a waiter registered before the caller knows a worker's current generation (undefined
     // wakes on any generation notice) is narrowed per worker once the first status read lands.
     setGeneration = (workerId, value) => { if (!waiter.done) waiter.generationByCtmId.set(String(workerId), value); };
   });
   return { promise, release, setGeneration };
 }
+
+// WP-1 (D-3): the watcher's PRODUCTION model call. It rides the lane every other CTM
+// background completion uses (lib/background-llm.js -> Wall-E's background-completion
+// endpoint), so the resolved provider, the fallback chain and the circuit breakers stay the
+// routing authority's and CTM builds no provider client of its own. The pin is the caller's
+// `model` (the worker row's own route_alias + ':' + model, never a second route).
+// A failure -- transport, an unroutable pin (route_throttled / route_unavailable /
+// model_not_found), or a non-2xx decision -- answers `{ ok: false, error }`, which is exactly
+// what the watcher's D-4 consecutive-failure counter reads.
+function createWaitWatcherCallModel() {
+  return async function callWaitWatcherModel({ feature, model, system, messages, maxTokens, timeoutMs, sessionId }) {
+    let llm;
+    try {
+      llm = require('../background-llm');
+      // D-4: the watcher never takes a second route. background-llm's last-ditch Ollama hop
+      // fires on a Wall-E transport error unless the fallback setting is off, so this call
+      // carries an env copy with it off -- a transport failure is then `{ ok: false }` and the
+      // consecutive-failure counter ends the watcher with `watcher_unavailable`.
+      const env = { ...process.env, CTM_BACKGROUND_LLM_FALLBACK_PROVIDER: 'off' };
+      // WP-4a (D-9): the tick's `sessionId` is the watched worker's ctm_session_id (WP-1's
+      // per-worker tick). background-llm.js forwards it into the POST body only when it is a
+      // non-empty string, and Wall-E's ledger then keys the row by it -- so the cell's watcher
+      // spend is exactly the ledger rows of that cell's own workers.
+      const reply = await llm.callBackgroundLlm(messages, {
+        task: feature, model, system, maxTokens, timeoutMs, env,
+        ...(typeof sessionId === 'string' && sessionId ? { sessionId } : {}),
+      });
+      const text = typeof reply?.text === 'string' ? reply.text : llm.extractBackgroundLlmText(reply);
+      return { ok: true, text };
+    } catch (error) {
+      return { ok: false, error: String((error && (error.code || error.message)) || 'watch_call_failed').slice(0, 200) };
+    }
+  };
+}
+
 // D-7: a route waiter is the same record shape in the same `_waiters` registry, under the key
 // `route:<alias>`. Timer = min(waitMs, remaining hold) when the snapshot has a horizon, else waitMs.
 // The registration/wake checks read snapshot() (never admit()) so a wait is never counted as a refusal.
@@ -634,6 +705,10 @@ function createWorkerObservability({ getDeps, readWorkerRuntime, getBaseStatus }
       try { enqueueNotice(receipt); } catch { /* expected: the lead's hook notice is best-effort; walle_worker_wait and the sentinel still report */ }
       _wakeWaiters(ctmSessionId, 'terminal');
       auditScopeAtTerminal(ctmSessionId).catch((error) => reportObservationFailure(deps, ctmSessionId, error));
+    } else if (kind === 'started') {
+      // WP-0 (D-2): the live-worker index is maintained beside the notice queue from the same
+      // receipts. Memory only, so a failure here can never affect the receipt's persistence.
+      try { markWorkerLive(receipt); } catch { /* expected: the live index is best-effort; the notice queue and walle_worker_wait still report */ }
     }
     return receipt;
   }
@@ -911,8 +986,22 @@ function withIncompleteStreams(runtime, requestBudget) {
   return { ...requestBudget, incomplete_streams: count, incomplete_stream_ms: ms };
 }
 
+// D-1 (session-stops-followups-2026-10-24.html): the terminal statuses a LIVE payload can carry.
+// The DB-row readers in lib/api/sessions.js keep their own copy (_WORKER_TERMINAL_STATUSES):
+// a row's terminal_status is written only at a real exit, so it can never be provisional.
+const WORKER_TERMINAL_STATUSES = new Set(['report_ready', 'failed', 'exited']);
+
+/** D-1: a status payload is final when it is terminal AND not a report written while the process
+ *  is still alive (delegate-worker.js report_provisional). An absent field is final, so DB rows
+ *  and fixtures keep today's meaning.
+ *  @param {{status?: string, report_provisional?: boolean}|null|undefined} status
+ *  @returns {boolean} */
+function isFinalWorkerStatus(status) {
+  return !!status && WORKER_TERMINAL_STATUSES.has(status.status) && status.report_provisional !== true;
+}
+
 function pollAfterMs({ status, requestBudget } = {}) {
-  if (['report_ready', 'failed', 'exited'].includes(status?.status)
+  if (isFinalWorkerStatus(status)
     || (status?.exitCode !== null && status?.exitCode !== undefined)) return 0;
   const p50 = requestBudget?.requestDurationP50Ms;
   if (!Number.isInteger(p50) || p50 <= 0) return 30000;
@@ -921,6 +1010,8 @@ function pollAfterMs({ status, requestBudget } = {}) {
 
 module.exports = {
   waitForWorkerChange, waitForWorkerChangeHandle, waitForWorkers, notifyWorkerGeneration, notifyWorkerAdvisory, waiterCount, waitForRouteClear, _resetRouteSubscriptionsForTest,
+  createWaitWatcherCallModel,
+  isFinalWorkerStatus,
   pollAfterMs,
   withIncompleteStreams,
   createWorkerObservability,
@@ -940,6 +1031,7 @@ module.exports = {
   computeExitFailure,
   boundedWorkerText,
   isColdDeferredSession,
+  WORKER_REPORT_TEXT_CAP_BYTES,
   THROTTLED_WINDOW_MS,
   EVENT_RECEIPT_LIMIT,
   NO_WRITE_ADVISORY_TURN_THRESHOLD,

package/template/coding-task-manager/lib/session-create/worker-stop.js

@@ -65,9 +65,17 @@ async function stopWorkerSession(ctmSessionId, { mode = 'after_turn', reason = '
     return refuse('worker_not_owned', 403, id, { message: 'Only the lead that created this worker can stop it.', next_step: nextStepFor({ code: 'worker_not_owned' }) });
   }
 
-  // 4. idempotent on a terminal worker
-  if (row.terminal_at || TERMINAL_STATUSES.includes(String(row.terminal_status || ''))) {
-    return refuse('already_terminal', 200, id, { terminal_status: row.terminal_status || '', generation: Number(row.generation || 1), status: 'terminal' });
+  // WP-2 (worker-terminal-stamp-durable 2026-10-26 D-2/D-3): a dead process with an unstamped row is repaired first,
+  // so the verb below answers the truth (already_terminal), never 'stopping' on a process that no longer exists.
+  let repaired = null;
+  if (typeof helpers.repairExitedWorkerRow === 'function') {
+    try { repaired = helpers.repairExitedWorkerRow(id) || null; } catch { repaired = null; /* expected: a repair that throws leaves the row as read; the stop proceeds on the row's own truth */ }
+    if (repaired) { try { row = deps.dbModule.getWorkerSession(id) || row; } catch { /* expected: keep the row already read */ } }
+  }
+
+  // 4. idempotent on a terminal worker -- or on a repaired one whose stamp is still riding the WP-1 retry (D-3: never 'stopping' for a dead process)
+  if (repaired || row.terminal_at || TERMINAL_STATUSES.includes(String(row.terminal_status || ''))) {
+    return refuse('already_terminal', 200, id, { terminal_status: row.terminal_status || '', generation: Number(row.generation || 1), status: 'terminal', repaired });
   }
 
   // 5. the stop record: journaled by the proxy for a proxied worker, on the row for a proxyless one