mixdog 0.9.2 → 0.9.3

package/src/runtime/memory/lib/promotion-fingerprint.mjs

@@ -0,0 +1,50 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+// Plugin version + promotion code fingerprint. Extracted from index.mjs
+// (behavior-preserving). Callers pass PLUGIN_ROOT so this stays free of any
+// entry-point path resolution.
+
+export function readPluginVersion(pluginRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(pluginRoot, 'package.json'), 'utf8')).version || '0.0.1'
+  } catch { return '0.0.1' }
+}
+
+const PROMOTION_FINGERPRINT_ROOTS = ['src/memory']
+
+function collectPromotionFingerprintFiles(pluginRoot) {
+  const out = []
+  const walk = (relDir) => {
+    let entries = []
+    try { entries = fs.readdirSync(path.join(pluginRoot, relDir), { withFileTypes: true }) }
+    catch { return }
+    for (const ent of entries) {
+      const rel = `${relDir}/${ent.name}`.replace(/\\/g, '/')
+      if (ent.isDirectory()) {
+        walk(rel)
+      } else if (ent.isFile() && rel.endsWith('.mjs')) {
+        out.push(rel)
+      }
+    }
+  }
+  for (const root of PROMOTION_FINGERPRINT_ROOTS) walk(root)
+  return out.sort()
+}
+
+export function readPromotionCodeFingerprint(pluginRoot) {
+  const hash = crypto.createHash('sha256')
+  const files = collectPromotionFingerprintFiles(pluginRoot)
+  for (const rel of files) {
+    hash.update(rel)
+    hash.update('\0')
+    try {
+      hash.update(fs.readFileSync(path.join(pluginRoot, rel)))
+    } catch {
+      hash.update('missing')
+    }
+    hash.update('\0')
+  }
+  return `src/memory:${files.length}:${hash.digest('hex').slice(0, 16)}`
+}

package/src/runtime/memory/lib/recall-format.mjs

@@ -0,0 +1,183 @@
+import { cleanMemoryText } from './memory.mjs'
+
+// Recall query/format helpers extracted verbatim from index.mjs
+// (behavior-preserving). Pure string/date logic plus row rendering.
+
+export function parsePeriod(period, hasQuery) {
+  if (!period && hasQuery) period = '30d'
+  if (!period) return null
+  if (period === 'all') return null
+  if (period === 'last') return { mode: 'last' }
+  // Calendar-day windows: 'today' anchors at local midnight rather than
+  // rolling 24h. Without this, a query asking 'today' at 01:30 would silently
+  // include yesterday's last 22.5h of activity, mislabelling them as
+  // 'today's work'. 'yesterday' is the previous calendar day.
+  if (period === 'today') {
+    const start = new Date()
+    start.setHours(0, 0, 0, 0)
+    return { startMs: start.getTime(), endMs: Date.now() }
+  }
+  if (period === 'yesterday') {
+    const start = new Date()
+    start.setDate(start.getDate() - 1)
+    start.setHours(0, 0, 0, 0)
+    const end = new Date(start)
+    end.setHours(23, 59, 59, 999)
+    return { startMs: start.getTime(), endMs: end.getTime() }
+  }
+  if (period === 'this_week' || period === 'last_week') {
+    // R6 P9: calendar Mon-Sun previous/current week. Mon-start ISO
+    // convention. Replaces R5 rolling 7-14d range which was empty for
+    // sessions where "last week" decisions actually fell on Mon (4/27) of
+    // this week. Precise calendar bounds match natural-language intuition.
+    const d = new Date()
+    d.setHours(0, 0, 0, 0)
+    const dayOfWeek = d.getDay()
+    const daysSinceMon = (dayOfWeek + 6) % 7
+    const thisWeekMon = new Date(d)
+    thisWeekMon.setDate(d.getDate() - daysSinceMon)
+    if (period === 'this_week') {
+      return { startMs: thisWeekMon.getTime(), endMs: Date.now() }
+    }
+    const lastWeekMon = new Date(thisWeekMon)
+    lastWeekMon.setDate(thisWeekMon.getDate() - 7)
+    const lastWeekSunEnd = new Date(thisWeekMon.getTime() - 1)
+    return { startMs: lastWeekMon.getTime(), endMs: lastWeekSunEnd.getTime() }
+  }
+  const relMatch = period.match(/^(\d+)(m|h|d)$/)
+  if (relMatch) {
+    const n = parseInt(relMatch[1])
+    const unit = relMatch[2]
+    const now = new Date()
+    if (unit === 'm') {
+      // Minute granularity is for "resume from the previous turn / pick
+      // up where we left off" style recall — sub-hour windows where 1h
+      // is too coarse. n=0 is invalid (the regex requires \d+ which
+      // matches "0" but a zero-width window returns no rows; leave that
+      // as caller-supplied no-op).
+      const start = new Date(now.getTime() - n * 60_000)
+      return { startMs: start.getTime(), endMs: now.getTime() }
+    }
+    if (unit === 'h') {
+      const start = new Date(now.getTime() - n * 3600_000)
+      return { startMs: start.getTime(), endMs: now.getTime() }
+    }
+    const start = new Date(now)
+    start.setDate(start.getDate() - n)
+    return { startMs: start.getTime(), endMs: now.getTime() }
+  }
+  const rangeMatch = period.match(/^(\d{4}-\d{2}-\d{2})~(\d{4}-\d{2}-\d{2})$/)
+  if (rangeMatch) {
+    return {
+      startMs: Date.parse(rangeMatch[1] + 'T00:00:00'),
+      endMs:   Date.parse(rangeMatch[2] + 'T23:59:59.999'),
+    }
+  }
+  const dateMatch = period.match(/^(\d{4}-\d{2}-\d{2})$/)
+  if (dateMatch) {
+    return {
+      startMs: Date.parse(dateMatch[1] + 'T00:00:00'),
+      endMs:   Date.parse(dateMatch[1] + 'T23:59:59.999'),
+      exact: true,
+    }
+  }
+  return null
+}
+
+export function formatTs(tsMs) {
+  const n = Number(tsMs)
+  if (Number.isFinite(n) && n > 1e12) {
+    return new Date(n).toLocaleString('sv-SE').slice(0, 16)
+  }
+  return String(tsMs ?? '').slice(0, 16)
+}
+
+export const CORE_RECALL_STOPWORDS = new Set([
+  'about', 'after', 'again', 'before', 'check', 'color', 'decision', 'decided',
+  'earlier', 'memory', 'previous', 'routing', 'stored', 'tell', 'what',
+])
+
+export function coreRecallTerms(query) {
+  return [...new Set(String(query || '').toLowerCase().match(/[\p{L}\p{N}_-]{4,}/gu) || [])]
+    .filter((term) => !CORE_RECALL_STOPWORDS.has(term))
+    .slice(0, 8)
+}
+
+export function normalizeRecallProjectScope(projectScope) {
+  const raw = String(projectScope || 'common').trim()
+  if (!raw || raw.toLowerCase() === 'common') return null
+  if (raw.toLowerCase() === 'all') return '*'
+  return raw
+}
+
+export function sessionRecallTerms(query) {
+  return [...new Set(String(query || '').toLowerCase().match(/[\p{L}\p{N}_./:-]{2,}/gu) || [])]
+    .filter((term) => !CORE_RECALL_STOPWORDS.has(term))
+    .slice(0, 12)
+}
+
+export function interleaveRawRows(hybridRows, rawRows) {
+  if (!Array.isArray(rawRows) || rawRows.length === 0) return hybridRows
+  const out = []
+  const stride = Math.max(1, Math.round(hybridRows.length / (rawRows.length + 1)))
+  let rawIdx = 0
+  for (let i = 0; i < hybridRows.length; i += 1) {
+    out.push(hybridRows[i])
+    if ((i + 1) % stride === 0 && rawIdx < rawRows.length) {
+      out.push(rawRows[rawIdx])
+      rawIdx += 1
+    }
+  }
+  while (rawIdx < rawRows.length) out.push(rawRows[rawIdx++])
+  return out
+}
+
+export function renderEntryLines(rows) {
+  if (!rows || rows.length === 0) return '(no results)'
+  const lines = []
+  // Bound total emitted lines (roots x members) so a many-member recall can't
+  // inject unbounded output. Per-line content is already capped at 1000 chars;
+  // this caps the line COUNT. Narrow the query (limit/period/projectScope) for more.
+  const RECALL_LINE_CAP = 200
+  let _capped = false
+  outer:
+  for (const r of rows) {
+    const hasMembers = Array.isArray(r.members) && r.members.length > 0
+    if (hasMembers) {
+      // Chunks present: emit each member as its own line. Root row is a
+      // grouping artifact for retrieval — the caller wants the chunk
+      // content (cycle1 raw), not the cycle2-compressed summary.
+      for (const m of r.members) {
+        if (lines.length >= RECALL_LINE_CAP) { _capped = true; break outer }
+        const mTs = formatTs(m.ts)
+        const role = m.role === 'user' ? 'u' : m.role === 'assistant' ? 'a' : (m.role || '?')
+        const content = cleanMemoryText(String(m.content ?? '')).slice(0, 1000)
+        lines.push(`[${mTs}] ${role}: ${content} #${m.id}`)
+      }
+    } else {
+      if (lines.length >= RECALL_LINE_CAP) { _capped = true; break }
+      // No chunks (root not yet chunked by cycle1, or orphan leaf): emit
+      // the row itself in the same shape. element/summary fall back to
+      // raw content when both are absent.
+      const ts = formatTs(r.ts)
+      const element = r.element ?? ''
+      const summary = r.summary ?? ''
+      // Standalone leaf rows (is_root=0, no parent chunks_root resolved
+      // into a `members` list) carry their u/a role just like inline
+      // chunk members — surface it so the format stays consistent across
+      // the two emission paths.
+      const rolePrefix = r.is_root === 0 && r.role
+        ? (r.role === 'user' ? 'u: ' : r.role === 'assistant' ? 'a: ' : `${r.role}: `)
+        : ''
+      const body = element || summary
+        ? `${element}${summary ? ' — ' + summary : ''}`
+        : cleanMemoryText(String(r.content ?? '')).slice(0, 1000)
+      // Unchunked raw leaf (cycle1 hasn't classified it yet): mark it so
+      // callers can tell fresh-but-unprocessed rows from chunked memory.
+      const pendingMark = (r.is_root === 0 && r.chunk_root == null) ? ' [pending]' : ''
+      lines.push(`[${ts}] ${rolePrefix}${body.slice(0, 1000)}${pendingMark} #${r.id}`)
+    }
+  }
+  if (_capped) lines.push(`[recall truncated — showing first ${RECALL_LINE_CAP} lines; narrow the query (limit/period/projectScope) for the rest]`)
+  return lines.join('\n')
+}

package/src/runtime/memory/tool-defs.mjs

@@ -8,12 +8,12 @@ export const TOOL_DEFS = [
     name: 'memory',
     title: 'Memory Cycle',
     annotations: { title: 'Memory Cycle', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
-    description: 'Memory status/lifecycle or explicit mutation. Use recall for retrieval. Destructive jobs require exact confirm strings.',
+    description: 'Memory status/lifecycle or explicit mutation. Use recall for retrieval. When the user explicitly asks to remember something (e.g. "remember this", a stated preference, or a decision), persist it immediately with action:"core" op:"add" — do not wait for a cycle. Destructive jobs require exact confirm strings.',
     inputSchema: {
       type: 'object',
       properties: {
         action: { type: 'string', enum: ['core','manage','status','sleep','cycle1','cycle2','cycle3','flush','backfill','prune','rebuild','purge','retro_eval_active'], description: 'Operation.' },
-        op: { type: 'string', enum: ['add','edit','delete','list'], description: 'Mutation op.' },
+        op: { type: 'string', enum: ['add','edit','delete','list','candidates','promote','dismiss'], description: 'Mutation op. candidates/promote/dismiss drive core-memory proposal approval.' },
         id: { type: 'number', description: 'Exact memory id.' },
         element: { type: 'string', description: 'Memory key/title.' },
         summary: { type: 'string', description: 'Memory content.' },
@@ -38,13 +38,13 @@ export const TOOL_DEFS = [
     name: 'recall',
     title: 'Recall',
     annotations: { title: 'Recall', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    description: 'Retrieve stored memory/session history. Use for earlier work, resumes, or possibly decided items; when in doubt, recall first.',
+    description: 'Retrieve stored memory/session history. Use for earlier work, resumes, or possibly decided items; when in doubt, recall first. For "what did we just discuss": pass sessionId with no query to browse the current session (includes in-progress content); period:"last" without sessionId browses the previous completed session only.',
     inputSchema: {
       type: 'object',
       properties: {
         query: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Search text, or array for independent fan-out queries.' },
         id: { anyOf: [{ type: 'number' }, { type: 'array', items: { type: 'number' }, minItems: 1 }], description: 'Exact #id(s) from recall. Do not invent ids.' },
-        period: { type: 'string', description: 'last, 24h/7d/30d, all, date, or range.' },
+        period: { type: 'string', description: "last (previous completed session; pair with sessionId instead to include the current one), 24h/7d/30d, all, date, or range." },
         limit: { type: 'number', description: 'Max entries.' },
         offset: { type: 'number', description: 'Skip entries.' },
         sort: { type: 'string', enum: ['importance', 'date'], description: 'importance or date.' },

package/src/runtime/shared/abort-controller.mjs

@@ -1,5 +1,5 @@
 /**
- * AbortController helpers — ported from a reference agent CLI pattern.
+ * AbortController helpers.
  *
  * `createAbortController()` raises the signal's max listener cap so long-running
  * sessions with many per-iteration handlers don't trip Node's default warning.

package/src/runtime/shared/background-tasks.mjs

@@ -5,7 +5,7 @@ import {
   normalizeToolNotifyContext,
   notifyToolCompletion,
 } from './tool-execution-contract.mjs';
-import { presentErrorText } from './err-text.mjs';
+import { presentErrorText, errorLine } from './err-text.mjs';
 
 export {
   TOOL_ASYNC_EXECUTION_CONTRACT,
@@ -465,8 +465,7 @@ export function renderBackgroundTask(taskOrId, { includeResult = false } = {}) {
     if (body) {
       lines.push('', body);
     } else if (TERMINAL_STATUSES.has(task.status) && task.error) {
-      const errorText = String(task.error || '').trim();
-      lines.push('', /^error\s*:/i.test(errorText) ? errorText : `Error: ${errorText}`);
+      lines.push('', errorLine(task.error, { surface: task.surface }));
     } else if (TERMINAL_STATUSES.has(task.status) && task.status === 'completed') {
       // Terminal-completed task with no extractable body: surface a placeholder
       // instead of silently omitting the result so the owner isn't left with a

package/src/runtime/shared/buffered-appender.mjs

@@ -0,0 +1,149 @@
+/**
+ * Per-file buffered append queue.
+ *
+ * Hot paths (transcript writer, channel worker stderr log, etc.) previously
+ * called appendFileSync per entry/chunk, which blocks the event loop on
+ * every write. This module coalesces writes per path into an in-memory
+ * buffer and flushes asynchronously via fs.promises.appendFile once the
+ * buffer reaches BUFFER_FLUSH_BYTES or after DEBOUNCE_MS of inactivity.
+ * Flushes are serialized per path so ordering is preserved. On process
+ * exit, any remaining buffered bytes for every path are drained with one
+ * synchronous appendFileSync call each (best-effort, matching the
+ * agent-trace.mjs local spool exit-drain pattern).
+ */
+import { appendFileSync } from 'node:fs';
+import { appendFile } from 'node:fs/promises';
+
+const BUFFER_FLUSH_BYTES = 32 * 1024;
+const DEBOUNCE_MS = 50;
+
+// path -> { chunks: string[], bytes: number, timer, flushing, inFlight, failCount }
+const queues = new Map();
+
+function getQueue(path) {
+    let q = queues.get(path);
+    if (!q) {
+        q = { chunks: [], bytes: 0, timer: null, flushing: false, inFlight: null, failCount: 0 };
+        queues.set(path, q);
+    }
+    return q;
+}
+
+function scheduleFlush(path, q) {
+    if (q.timer) return;
+    q.timer = setTimeout(() => {
+        q.timer = null;
+        _flush(path, q);
+    }, DEBOUNCE_MS);
+    q.timer.unref?.();
+}
+
+function _flush(path, q) {
+    if (q.flushing) return;
+    if (q.chunks.length === 0) return;
+    const data = q.chunks.join('');
+    q.chunks = [];
+    q.bytes = 0;
+    // Hold the in-flight payload until the write settles so an exit-time
+    // sync drain can still recover it if it fires mid-write (fix: exit
+    // drain must not miss data that was dequeued but not yet persisted).
+    q.inFlight = data;
+    q.flushing = true;
+    appendFile(path, data, 'utf8')
+        .then(() => {
+            q.failCount = 0;
+        })
+        .catch(() => {
+            // Requeue the failed data so a later flush/exit-drain retries
+            // once, instead of silently dropping. Cap retries so a
+            // permanently broken path (e.g. deleted dir) cannot loop
+            // forever accumulating the same failing chunk.
+            q.failCount += 1;
+            if (q.failCount <= 3) {
+                q.chunks.unshift(data);
+                q.bytes += Buffer.byteLength(data, 'utf8');
+            }
+        })
+        .finally(() => {
+            q.inFlight = null;
+            q.flushing = false;
+            if (q.chunks.length > 0) {
+                if (q.bytes >= BUFFER_FLUSH_BYTES) _flush(path, q);
+                else scheduleFlush(path, q);
+            }
+        });
+}
+
+/**
+ * Queue text for buffered append to `path`. Flushes async once the buffer
+ * for that path crosses BUFFER_FLUSH_BYTES, or after DEBOUNCE_MS of
+ * inactivity, whichever comes first.
+ */
+export function appendBuffered(path, text) {
+    if (!path || !text) return;
+    const q = getQueue(path);
+    q.chunks.push(text);
+    q.bytes += Buffer.byteLength(text, 'utf8');
+    if (q.bytes >= BUFFER_FLUSH_BYTES) {
+        if (q.timer) { clearTimeout(q.timer); q.timer = null; }
+        _flush(path, q);
+    } else {
+        scheduleFlush(path, q);
+    }
+}
+
+/**
+ * Synchronously drain any remaining buffered bytes for every known path.
+ * Intended for process exit hooks only — best-effort, never throws.
+ */
+export function drainAllSync() {
+    for (const [path, q] of queues) {
+        drainPathSync(path);
+    }
+}
+
+/**
+ * Synchronously drain the queue for a single path. Writes any in-flight
+ * (already-dequeued but not yet persisted) payload FIRST, then any
+ * still-queued chunks, so nothing buffered is lost. Best-effort, never
+ * throws.
+ */
+export function drainPathSync(path) {
+    const q = queues.get(path);
+    if (!q) return;
+    if (q.timer) { clearTimeout(q.timer); q.timer = null; }
+    if (q.inFlight) {
+        try {
+            appendFileSync(path, q.inFlight, 'utf8');
+        } catch {
+            // Best-effort; nothing to recover from here.
+        }
+        q.inFlight = null;
+    }
+    if (q.chunks.length === 0) return;
+    const data = q.chunks.join('');
+    q.chunks = [];
+    q.bytes = 0;
+    try {
+        appendFileSync(path, data, 'utf8');
+    } catch {
+        // Best-effort exit drain; nothing to recover from here.
+    }
+}
+
+/**
+ * True if a path currently has an async write in flight. Callers that need
+ * to rename/rotate the underlying file (which would race a concurrent
+ * appendFile on some platforms, notably Windows) should check this and
+ * defer the rename to a later tick rather than racing it.
+ */
+export function hasInFlightWrite(path) {
+    const q = queues.get(path);
+    return Boolean(q && q.inFlight);
+}
+
+try {
+    process.on('exit', drainAllSync);
+} catch {
+    // Ignore lifecycle hook failures in embedded runtimes.
+}

package/src/runtime/shared/task-notification-envelope.mjs

@@ -0,0 +1,98 @@
+// Shared production of background-task notification envelopes.
+//
+// Producers (shell-jobs fire()/prompt-stall) and consumers (session
+// ingest/manager detection, TUI parsers reading stored sessions) must agree
+// byte-for-byte on the emitted wire format: bracket header fields, the blank
+// line body separator, and the completion instruction wording. To keep one
+// source of truth, the render helpers and the detection regexes live here.
+
+import {
+  toolCompletionInstruction,
+  isInternalRuntimeNotificationText,
+  isBracketedShellNotificationEnvelope,
+  backgroundTaskHeaderStatus,
+} from './tool-execution-contract.mjs';
+
+// Re-export the envelope *detection* predicate so producers and consumers can
+// pull render + detect from one module. Detection primitives live in
+// tool-execution-contract.mjs (shouldPersistModelVisibleToolCompletion et al.
+// depend on them there); this keeps a single import surface without forking
+// the regexes.
+export {
+  isInternalRuntimeNotificationText,
+  isBracketedShellNotificationEnvelope,
+  backgroundTaskHeaderStatus,
+};
+
+// Render the bracketed shell *completion* envelope body.
+// Byte-compatible with the historical inline assembly in shell-jobs.fire().
+export function renderShellCompletionEnvelope({
+  jobId,
+  status,
+  exitCode = null,
+  elapsedMs = null,
+  command = null,
+  summary = null,
+  stdoutPreview = null,
+  stderrPreview = null,
+  mergeStderr = false,
+} = {}) {
+  const header = [
+    `[task_id: ${jobId}]`,
+    `[status: ${status}]`,
+    `[exit: ${exitCode === null ? 'n/a' : exitCode}]`,
+    elapsedMs !== null ? `[elapsed: ${elapsedMs} ms]` : null,
+    command ? `[command: ${command}]` : null,
+  ].filter((l) => l !== null);
+  const bodySections = [
+    summary ? `Summary: ${summary}` : null,
+    stdoutPreview ? `\n[stdout preview]\n${stdoutPreview}` : null,
+    (mergeStderr !== true && stderrPreview) ? `\n[stderr preview]\n${stderrPreview}` : null,
+  ].filter((l) => l !== null);
+  // Exactly one blank line separates the bracket header block from the body
+  // when any body section exists; no trailing blank line when there is none.
+  // (Previously the '' separator was filtered out by the value filter, so a
+  // summary-only envelope glued headers straight onto `Summary:` and read as
+  // bodyless to the `\n\s*\n` body detector.)
+  const lines = bodySections.length > 0
+    ? [...header, '', ...bodySections]
+    : header;
+  return lines.join('\n');
+}
+
+// Build the shell completion instruction via the shared wording so all async
+// surfaces read identically ("The async shell task … has finished …"). The
+// exit detail is folded into the shared detail slot.
+export function shellCompletionInstruction({ jobId, status, exitCode = null } = {}) {
+  return toolCompletionInstruction({
+    surface: 'shell',
+    id: jobId,
+    status,
+    detail: `exit ${exitCode === null ? 'n/a' : exitCode}`,
+  });
+}
+
+// Render the bracketed shell *prompt-stall* progress envelope body.
+// Byte-compatible with the historical inline assembly in maybeNotifyPromptStall.
+export function renderShellPromptStallEnvelope({
+  jobId,
+  stalledMs,
+  elapsedMs = null,
+  command = null,
+  tailText = null,
+} = {}) {
+  return [
+    `[task_id: ${jobId}]`,
+    '[status: running]',
+    `[stalled: no output growth for ${stalledMs} ms]`,
+    (elapsedMs !== null && elapsedMs >= 0) ? `[elapsed: ${elapsedMs} ms]` : null,
+    command ? `[command: ${command}]` : null,
+    '',
+    'This background shell task appears to be waiting for interactive input. Background tasks cannot answer prompts automatically; cancel it or rerun with non-interactive flags/input.',
+    tailText ? `\n${tailText}` : null,
+  ].filter((line) => line !== null && line !== '').join('\n');
+}
+
+export function shellPromptStallInstruction({ jobId } = {}) {
+  return `The background shell task ${jobId} appears to be waiting for interactive input; inspect the prompt, then cancel or rerun it non-interactively.`;
+}

package/src/runtime/shared/task-notification-envelope.test.mjs

@@ -0,0 +1,107 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  renderShellCompletionEnvelope,
+  shellCompletionInstruction,
+  renderShellPromptStallEnvelope,
+  shellPromptStallInstruction,
+  isInternalRuntimeNotificationText,
+  isBracketedShellNotificationEnvelope,
+} from './task-notification-envelope.mjs';
+
+test('completion envelope matches historical assembly plus the corrected blank-line separator', () => {
+  const jobId = 'shell_job_1';
+  const status = 'completed';
+  const exitCode = 0;
+  const elapsedMs = 1234;
+  const detail = {
+    command: 'npm test',
+    summary: 'ok',
+    stdoutPreview: 'out',
+    stderrPreview: 'err',
+    mergeStderr: false,
+  };
+  const expected = [
+    `[task_id: ${jobId}]`,
+    `[status: ${status}]`,
+    `[exit: ${exitCode === null ? 'n/a' : exitCode}]`,
+    elapsedMs !== null ? `[elapsed: ${elapsedMs} ms]` : null,
+    detail.command ? `[command: ${detail.command}]` : null,
+    // The historical inline assembly filtered this '' out, gluing `Summary:`
+    // onto the header block; the corrected renderer keeps exactly one blank
+    // line between the bracket headers and the body sections.
+    '',
+    detail.summary ? `Summary: ${detail.summary}` : null,
+    detail.stdoutPreview ? `\n[stdout preview]\n${detail.stdoutPreview}` : null,
+    (detail.mergeStderr !== true && detail.stderrPreview) ? `\n[stderr preview]\n${detail.stderrPreview}` : null,
+  ].filter((l) => l !== null).join('\n');
+  const actual = renderShellCompletionEnvelope({ jobId, status, exitCode, elapsedMs, ...detail });
+  assert.equal(actual, expected);
+  assert.equal(isInternalRuntimeNotificationText(actual), true);
+  assert.equal(isBracketedShellNotificationEnvelope(actual), true);
+});
+
+test('summary-only completion envelope keeps one blank line before the body', () => {
+  const actual = renderShellCompletionEnvelope({
+    jobId: 'shell_job_1',
+    status: 'completed',
+    exitCode: 0,
+    summary: 'ok',
+  });
+  const expected = [
+    '[task_id: shell_job_1]',
+    '[status: completed]',
+    '[exit: 0]',
+    '',
+    'Summary: ok',
+  ].join('\n');
+  assert.equal(actual, expected);
+  // The blank-line separator must survive so body detectors see a body.
+  assert.match(actual, /\n\s*\n/);
+});
+
+test('bodyless completion envelope has no trailing blank line', () => {
+  const actual = renderShellCompletionEnvelope({
+    jobId: 'shell_job_1',
+    status: 'completed',
+    exitCode: 0,
+  });
+  assert.equal(actual, ['[task_id: shell_job_1]', '[status: completed]', '[exit: 0]'].join('\n'));
+  assert.doesNotMatch(actual, /\n\s*\n/);
+});
+
+test('completion instruction uses shared async wording + exit detail', () => {
+  assert.equal(
+    shellCompletionInstruction({ jobId: 'shell_job_1', status: 'completed', exitCode: 0 }),
+    'The async shell task shell_job_1 has finished (completed, exit 0) - review this result in your next step.',
+  );
+  assert.match(shellCompletionInstruction({ jobId: 'x', status: 'failed', exitCode: null }), /exit n\/a/);
+});
+
+test('prompt-stall envelope is byte-compatible with historical inline assembly', () => {
+  const jobId = 'shell_job_1';
+  const stalledMs = 5000;
+  const elapsedMs = 6000;
+  const tail = { text: 'Password:' };
+  const detail = { command: 'ssh host' };
+  const expected = [
+    `[task_id: ${jobId}]`,
+    '[status: running]',
+    `[stalled: no output growth for ${stalledMs} ms]`,
+    elapsedMs >= 0 ? `[elapsed: ${elapsedMs} ms]` : null,
+    detail.command ? `[command: ${detail.command}]` : null,
+    '',
+    'This background shell task appears to be waiting for interactive input. Background tasks cannot answer prompts automatically; cancel it or rerun with non-interactive flags/input.',
+    tail.text ? `\n${tail.text}` : null,
+  ].filter((line) => line !== null && line !== '').join('\n');
+  const actual = renderShellPromptStallEnvelope({ jobId, stalledMs, elapsedMs, command: detail.command, tailText: tail.text });
+  assert.equal(actual, expected);
+  assert.equal(isInternalRuntimeNotificationText(actual), true);
+});
+
+test('prompt-stall instruction wording unchanged', () => {
+  assert.equal(
+    shellPromptStallInstruction({ jobId: 'shell_job_1' }),
+    'The background shell task shell_job_1 appears to be waiting for interactive input; inspect the prompt, then cancel or rerun it non-interactively.',
+  );
+});

package/src/runtime/shared/tool-execution-contract.mjs

@@ -33,7 +33,7 @@ function notificationResultBody(text) {
   return match ? String(match[1] || '').trim() : '';
 }
 
-function backgroundTaskHeaderStatus(text) {
+export function backgroundTaskHeaderStatus(text) {
   const match = /^status:\s*(\S+)/mi.exec(String(text || ''));
   return clean(match?.[1]).toLowerCase();
 }
@@ -86,7 +86,7 @@ export function shouldPersistModelVisibleToolCompletion(text, meta = {}) {
 
 const BRACKETED_SHELL_STATUS_RE = /^\[status:\s*(?:running|pending|queued|completed|failed|cancelled|canceled|error|timeout|done|success)\]/im;
 
-function isBracketedShellNotificationEnvelope(text) {
+export function isBracketedShellNotificationEnvelope(text) {
   const value = String(text ?? '').trim();
   if (!value) return false;
   if (!/^\[task_id:\s*\S+\]/im.test(value)) return false;