mixdog 0.9.147 → 0.9.148

package/src/runtime/agent/orchestrator/tools/builtin/shell-jobs.mjs

@@ -14,22 +14,21 @@ import {
 import {
     completeBackgroundTask,
     getBackgroundTask,
-    notifyBackgroundTaskProgress,
 } from '../../../../shared/background-tasks.mjs';
 import {
-    adoptNativeTaskByPid,
     cancelNativeTask,
     getNativeTask,
     listNativeTasks,
+    promoteNativeTask,
+    releaseNativeTask,
     setNativeTaskStartedAt,
-    startNativeTask,
     subscribeNativeTask,
+    trackNativeForegroundTask,
     waitNativeTask,
 } from '../lib/native-spawn-client.mjs';
 import {
     attachJobInsights,
     shellJobPublicTaskResult,
-    SHELL_JOB_OUTPUT_DISK_CAP,
 } from './lib/shell-job-insights.mjs';
 import {
     completeShellJobRecord,
@@ -42,10 +41,6 @@ import {
     renderShellCompletionEnvelope,
     shellCompletionInstruction,
 } from '../../../../shared/task-notification-envelope.mjs';
-import {
-    resolveShellMonitorIntervalMs,
-    startShellMonitor,
-} from './shell-monitor.mjs';
 
 export { shellJobPublicTaskResult } from './lib/shell-job-insights.mjs';
 
@@ -81,7 +76,7 @@ function trackShellJobRecord(task, options) {
     const settle = (detail) => {
         if (!detail || detail.status === 'running') return;
         try { unsubscribe?.(); } catch {}
-        void completeShellJobRecord(jobId, detail);
+        void completeShellJobRecord(jobId, normalizeShellJobDetail(detail));
     };
     unsubscribe = subscribeNativeTask(jobId, settle);
     settle(getNativeTask(jobId) || task);
@@ -98,12 +93,66 @@ function releaseShellJobResourceLease(jobId) {
     return true;
 }
 
-function shellJobTaskStatus(status) {
+/** Native task status → background-task status. A non-zero exit is a COMMAND
+ *  result, not a task failure: the identical run in the foreground reports
+ *  `[exit code: N]` and stays a success, so crossing the promotion threshold
+ *  must not flip it to failed. Only control-plane outcomes (spawn/server
+ *  error, timeout kill, cancellation) are terminal failures. */
+export function shellJobTaskStatus(detail) {
+    const status = typeof detail === 'string' ? detail : String(detail?.status || '');
+    if (status === 'running') return 'running';
     if (status === 'completed') return 'completed';
     if (status === 'cancelled') return 'cancelled';
+    // ONLY a real numeric non-zero exit normalizes. A signal death / null exit
+    // (SIGSEGV, SIGKILL, a lost process) is a genuine failure and must never
+    // be reported as success — `Number(null)` is 0, so an integer test on the
+    // coerced value silently turned every crash into a completed task.
+    const exitCode = (detail && typeof detail === 'object') ? detail.exitCode : null;
+    if (
+        status === 'failed'
+        && detail && typeof detail === 'object'
+        && !detail.timedOut
+        && !detail.killed
+        && !detail.error
+        && !detail.signal
+        && typeof exitCode === 'number'
+        && Number.isInteger(exitCode)
+        && exitCode !== 0
+    ) return 'completed';
     return 'failed';
 }
 
+/** Canonical shell-job detail. Every surface — wrapper task status, completion
+ *  notification, public task result, disk record, insights summary — reads
+ *  `status` from this one mapping, so a promoted non-zero command can never be
+ *  reported completed by one surface and failed by another. The raw native
+ *  value is kept as `nativeStatus` for diagnostics. */
+export function normalizeShellJobDetail(detail) {
+    if (!detail || typeof detail !== 'object') return detail;
+    const nativeStatus = String(detail.status || '');
+    const status = shellJobTaskStatus(detail);
+    // `nativeStatus` belongs to the contract even when the mapping is identity
+    // (a signal death stays `failed`): every surface must be able to read the
+    // raw value the canonical status came from.
+    if (detail.status === status && detail.nativeStatus === nativeStatus) return detail;
+    return { ...detail, status, nativeStatus: detail.nativeStatus || nativeStatus };
+}
+
+/** Cause line for a failed job. The native side fills `error` only for its own
+ *  control-plane failures, so a signal death or a status-less exit arrived with
+ *  a null cause and the completion said "failed" while explaining nothing. */
+export function shellJobFailureCause(detail) {
+    const explicit = String(detail?.error || '').trim();
+    if (explicit) return explicit;
+    const exitCode = typeof detail?.exitCode === 'number' ? detail.exitCode : null;
+    const exitDetail = exitCode == null ? '' : ` (exit ${exitCode})`;
+    if (detail?.timedOut) return `timed out before completing${exitDetail}`;
+    if (detail?.signal) return `terminated by signal ${detail.signal}${exitDetail}`;
+    if (detail?.killed) return `terminated before completing${exitDetail}`;
+    if (exitCode == null) return 'ended without an exit status';
+    return `exited with code ${exitCode}`;
+}
+
 export function buildShellCompletion(jobId, detail) {
     const startedAtMs = Date.parse(detail?.startedAt || '');
     const finishedAtMs = Date.parse(detail?.finishedAt || '') || Date.now();
@@ -112,59 +161,34 @@ export function buildShellCompletion(jobId, detail) {
         : null;
     const exitCode = typeof detail?.exitCode === 'number' ? detail.exitCode : null;
     const status = detail?.status || 'unknown';
+    const taskStatus = shellJobTaskStatus(detail);
+    // A failure always carries its cause — including a signal death, where the
+    // native task has no `error` of its own.
+    const failureCause = taskStatus === 'failed' ? shellJobFailureCause(detail) : null;
+    const reported = (failureCause && !detail?.error) ? { ...detail, error: failureCause } : detail;
     const body = renderShellCompletionEnvelope({
         jobId,
         status,
         exitCode,
         elapsedMs,
         command: detail?.command,
-        summary: detail?.summary,
+        summary: detail?.summary || failureCause || null,
         stdoutPreview: detail?.stdoutPreview,
         stderrPreview: detail?.stderrPreview,
         mergeStderr: detail?.mergeStderr,
     });
-    const taskStatus = shellJobTaskStatus(status);
     return {
         taskStatus,
         body,
         instruction: shellCompletionInstruction({ jobId, status, exitCode }),
-        result: shellJobPublicTaskResult(detail),
-        error: taskStatus === 'failed' ? (detail?.error || null) : null,
+        result: shellJobPublicTaskResult(reported),
+        error: failureCause,
     };
 }
 
-function shellMonitorState(detail) {
-    return {
-        stdoutBytes: Math.max(0, Number(detail?.stdoutBytes) || 0),
-        stderrBytes: Math.max(0, Number(detail?.stderrBytes) || 0),
-        summary: String(detail?.summary || '').trim(),
-    };
-}
-
-function renderShellMonitorProgress(jobId, detail, previous) {
-    const current = shellMonitorState(detail);
-    const startedAtMs = Date.parse(detail?.startedAt || '');
-    const elapsedMs = Number.isFinite(startedAtMs) ? Math.max(0, Date.now() - startedAtMs) : null;
-    const stdoutDelta = Math.max(0, current.stdoutBytes - previous.stdoutBytes);
-    const stderrDelta = Math.max(0, current.stderrBytes - previous.stderrBytes);
-    const latestChanged = current.summary && current.summary !== previous.summary;
-    const lines = [
-        'shell task progress',
-        `task_id: ${jobId}`,
-        'status: running',
-        elapsedMs == null ? null : `elapsed_ms: ${elapsedMs}`,
-        `stdout_bytes: ${current.stdoutBytes}`,
-        `stderr_bytes: ${current.stderrBytes}`,
-        stdoutDelta || stderrDelta ? `new_output_bytes: ${stdoutDelta + stderrDelta}` : null,
-        latestChanged ? '' : null,
-        latestChanged ? `latest: ${current.summary}` : null,
-    ];
-    return { text: lines.filter((line) => line !== null).join('\n'), state: current };
-}
-
-export async function waitForShellJob(jobId, { timeoutMs = 30_000 } = {}) {
+export async function waitForShellJob(jobId, { timeoutMs = 30_000, signal = null } = {}) {
     const started = Date.now();
-    const detail = await waitNativeTask(jobId, timeoutMs);
+    const detail = normalizeShellJobDetail(await waitNativeTask(jobId, timeoutMs, signal));
     const withInsights = attachJobInsights(detail);
     if (!withInsights) return null;
     withInsights.waitedMs = Date.now() - started;
@@ -173,52 +197,53 @@ export async function waitForShellJob(jobId, { timeoutMs = 30_000 } = {}) {
 }
 
 export function peekShellJob(jobId) {
-    return attachJobInsights(getNativeTask(jobId));
+    return attachJobInsights(normalizeShellJobDetail(getNativeTask(jobId)));
+}
+
+/** True while the job's process is still alive in this daemon. Owners of
+ *  in-use artifacts consult it before a fallback cleanup fires. */
+export function isShellJobRunning(jobId) {
+    return getNativeTask(String(jobId || ''))?.status === 'running';
+}
+
+/** Run `onSettled` once the job leaves 'running' (immediately when it already
+ *  has). Owners of per-command artifacts (hoisted script files, tee captures,
+ *  cache invalidation) use this instead of a fixed timer, which either fired
+ *  under a still-running command or never at all. Returns an unsubscribe, or
+ *  null when the job is unknown here — the caller then keeps its own fallback. */
+export function subscribeShellJobSettled(jobId, onSettled) {
+    const key = String(jobId || '').trim();
+    if (!key || typeof onSettled !== 'function') return null;
+    const current = getNativeTask(key);
+    if (!current) return null;
+    if (current.status !== 'running') {
+        queueMicrotask(() => { try { onSettled(current); } catch {} });
+        return () => {};
+    }
+    let done = false;
+    let unsubscribe = () => {};
+    const fire = (task) => {
+        if (done || !task || task.status === 'running') return;
+        done = true;
+        try { unsubscribe(); } catch {}
+        try { onSettled(task); } catch {}
+    };
+    unsubscribe = subscribeNativeTask(key, fire);
+    return () => {
+        done = true;
+        try { unsubscribe(); } catch {}
+    };
 }
 
 export function refreshShellJob(jobId) {
-    return getNativeTask(jobId);
+    return normalizeShellJobDetail(getNativeTask(jobId));
 }
 
 export function killShellJob(jobId) {
     const detail = cancelNativeTask(jobId);
     if (!detail) return null;
-    return { ...attachJobInsights(detail), killed: detail.status === 'running' };
-}
-
-export async function startBackgroundShellJob(options = {}) {
-    const {
-        command,
-        timeoutMs,
-        workDir,
-        mergeStderr,
-        spawnEnv,
-        shell,
-        shellArg,
-        shellArgs,
-        shellType,
-        clientHostPid,
-        ownerSessionId,
-    } = options;
-    const argv = [
-        ...(Array.isArray(shellArgs) && shellArgs.length > 0 ? shellArgs : [shellArg]),
-        command,
-    ].filter((value) => value != null && String(value).length > 0);
-    const task = await startNativeTask({
-        program: shell,
-        argv,
-        cwd: workDir,
-        env: spawnEnv,
-        timeoutMs,
-        mergeStderr,
-        command,
-        shellType,
-        clientHostPid,
-        ownerSessionId,
-        outputLimit: SHELL_JOB_OUTPUT_DISK_CAP,
-    });
-    trackShellJobRecord(task, { ownerSessionId, clientHostPid });
-    return task;
+    const wasRunning = detail.status === 'running';
+    return { ...attachJobInsights(normalizeShellJobDetail(detail)), killed: wasRunning };
 }
 
 export function attachShellJobResourceLease(jobId, lease) {
@@ -262,13 +287,7 @@ export function cancelBackgroundShellJobWatch(jobId) {
     return entry.notifyCtx || null;
 }
 
-export function configureBackgroundShellJobMonitor(jobId, intervalMs) {
-    const entry = backgroundShellJobWatchers.get(jobId);
-    if (!entry || typeof entry.setMonitor !== 'function') return null;
-    return entry.setMonitor(intervalMs);
-}
-
-export function watchBackgroundShellJob(jobId, notifyCtx, { monitorIntervalMs } = {}) {
+export function watchBackgroundShellJob(jobId, notifyCtx) {
     const ctx = notifyCtx && typeof notifyCtx.notifyFn === 'function'
         ? normalizeToolNotifyContext(notifyCtx)
         : jobNotifyCtxByJobId.get(jobId);
@@ -276,53 +295,20 @@ export function watchBackgroundShellJob(jobId, notifyCtx, { monitorIntervalMs }
     if (ctx) jobNotifyCtxByJobId.set(jobId, ctx);
     let settled = false;
     let unsubscribe = () => {};
-    let stopMonitor = () => false;
-    let previousMonitorState = shellMonitorState(attachJobInsights(getNativeTask(jobId)));
-    const setMonitor = (value) => {
-        stopMonitor();
-        const nextIntervalMs = resolveShellMonitorIntervalMs(value);
-        previousMonitorState = shellMonitorState(attachJobInsights(getNativeTask(jobId)));
-        const task = getBackgroundTask(jobId);
-        if (task) {
-            task.meta = {
-                ...(task.meta && typeof task.meta === 'object' ? task.meta : {}),
-                monitor_interval_ms: nextIntervalMs,
-            };
-        }
-        stopMonitor = startShellMonitor({
-            intervalMs: nextIntervalMs,
-            onTick: () => {
-                const detail = attachJobInsights(getNativeTask(jobId));
-                if (!detail || detail.status !== 'running') return false;
-                const progress = renderShellMonitorProgress(jobId, detail, previousMonitorState);
-                const sent = notifyBackgroundTaskProgress(jobId, {
-                    text: progress.text,
-                    resultType: 'shell_task_progress',
-                    status: 'running',
-                    once: false,
-                });
-                if (sent) previousMonitorState = progress.state;
-                return true;
-            },
-        });
-        return nextIntervalMs;
-    };
     const cancel = () => {
         if (settled) return;
         settled = true;
-        stopMonitor();
         unsubscribe();
         backgroundShellJobWatchers.delete(jobId);
     };
     const finish = (detail) => {
         if (settled || !detail || detail.status === 'running') return;
         settled = true;
-        stopMonitor();
         unsubscribe();
         backgroundShellJobWatchers.delete(jobId);
         jobNotifyCtxByJobId.delete(jobId);
         releaseShellJobResourceLease(jobId);
-        const enriched = attachJobInsights(detail);
+        const enriched = attachJobInsights(normalizeShellJobDetail(detail));
         const completion = buildShellCompletion(jobId, enriched);
         const completedTask = completeBackgroundTask(jobId, {
             status: completion.taskStatus,
@@ -357,7 +343,9 @@ export function watchBackgroundShellJob(jobId, notifyCtx, { monitorIntervalMs }
                         visible = modelVisibleToolCompletionMessage(`${message}\n\n(no output)`, meta);
                     }
                     if (!visible) return false;
-                    return enqueuePendingMessage(sessionId, markCompletionEntry(visible)) > 0;
+                    return enqueuePendingMessage(sessionId, markCompletionEntry(visible, {
+                        executionId: meta?.execution_id,
+                    })) > 0;
                 },
                 logPrefix: 'shell-jobs',
             });
@@ -365,23 +353,41 @@ export function watchBackgroundShellJob(jobId, notifyCtx, { monitorIntervalMs }
     };
     unsubscribe = subscribeNativeTask(jobId, finish);
     if (!settled) {
-        setMonitor(monitorIntervalMs);
-        backgroundShellJobWatchers.set(jobId, { cancel, notifyCtx: ctx, setMonitor });
+        backgroundShellJobWatchers.set(jobId, { cancel, notifyCtx: ctx });
     }
     queueMicrotask(() => finish(getNativeTask(jobId)));
 }
 
-export async function adoptForegroundShellJob({
+export async function trackForegroundShellJob({
+    command,
+    cwd,
+    child,
+    jobId,
+    clientHostPid,
+    ownerSessionId,
+}) {
+    return trackNativeForegroundTask({
+        child,
+        jobId,
+        command,
+        cwd,
+        ownerSessionId,
+        clientHostPid,
+    });
+}
+
+export async function promoteForegroundShellJob({
     command,
     cwd,
     pid,
+    jobId,
     timeoutMs,
     clientHostPid,
     ownerSessionId,
     startedAtMs = 0,
 }) {
-    const native = await adoptNativeTaskByPid({
-        pid,
+    const native = await promoteNativeTask({
+        jobId,
         command,
         cwd,
         timeoutMs,
@@ -390,8 +396,8 @@ export async function adoptForegroundShellJob({
     });
     if (!native) return null;
     demoteBackgroundShellPriority(pid);
-    // Adoption stamps the task at adoption time, and a promoted standby shell
-    // carries its process-creation time. Neither is when this command started,
+    // Promotion refreshes the task at transition time, and a promoted standby
+    // shell carries its process-creation time. Neither is when this command started,
     // so the runner's own start moment is registered before anything reads the
     // task — the record, the completion elapsed and the live readouts then all
     // measure the command itself.
@@ -476,7 +482,9 @@ export async function reconcileRecoveredShellJobCompletions() {
                 enqueueFallback: (sessionId, message, meta) => {
                     const visible = modelVisibleToolCompletionMessage(message, meta);
                     if (!visible) return false;
-                    return enqueuePendingMessage(sessionId, markCompletionEntry(visible)) > 0;
+                    return enqueuePendingMessage(sessionId, markCompletionEntry(visible, {
+                        executionId: meta?.execution_id,
+                    })) > 0;
                 },
                 logPrefix: 'shell-jobs-recovery',
             });
@@ -507,6 +515,17 @@ export async function shutdownShellJobs(_reason = 'runtime-close', { scope = nul
         jobs.map((task) => waitNativeTask(task.jobId, 1_200).catch(() => null)),
     );
     for (const task of jobs) releaseShellJobResourceLease(task.jobId);
+    if (scoped) {
+        // The owning session is gone: nothing can query its tasks again, so
+        // drop ALL of its retained state — not only the ones that happened to
+        // be running when shutdown began. releaseNativeTask refuses a task
+        // that is still alive, and disk records still serve a post-restart
+        // recovery read.
+        for (const task of listNativeTasks()) {
+            if (String(task.ownerSessionId || '') !== ownerSessionId) continue;
+            try { releaseNativeTask(task.jobId); } catch {}
+        }
+    }
     if (!scoped) {
         for (const jobId of [...shellJobResourceLeases.keys()]) {
             releaseShellJobResourceLease(jobId);

package/src/runtime/agent/orchestrator/tools/builtin/task-tool.mjs

@@ -4,22 +4,31 @@ import {
     peekShellJob,
     killShellJob,
     cancelBackgroundShellJobWatch,
-    configureBackgroundShellJobMonitor,
     clearShellJobNotifyCtx,
     shellJobPublicTaskResult,
+    shellJobTaskStatus,
+    waitForShellJob,
 } from './shell-jobs.mjs';
+
+// Ceiling for confirming that a cancelled task's process really exited. The
+// wait returns the moment the native task settles, so this only bounds a
+// process that ignores the kill.
+const TASK_CANCEL_CONFIRM_MS = 5_000;
 import {
-    isValidShellMonitorIntervalMs,
-    SHELL_MONITOR_INTERVAL_MAX_MS,
-    SHELL_MONITOR_INTERVAL_MIN_MS,
-} from './shell-monitor.mjs';
+    TASK_WAIT_TIMEOUT_DEFAULT_MS,
+    TASK_WAIT_TIMEOUT_MAX_MS,
+    TASK_WAIT_TIMEOUT_MIN_MS,
+} from './builtin-tools.mjs';
+import { getAbortSignalForSession } from '../../session/abort-lookup.mjs';
 import {
+    acknowledgeBackgroundTaskCompletion,
     cancelBackgroundTask,
     completeBackgroundTask,
     getBackgroundTask,
     renderBackgroundTask,
     renderBackgroundTaskList,
 } from '../../../../shared/background-tasks.mjs';
+import { recordDeliveredCompletion } from '../../session/manager/delivered-completions.mjs';
 import {
     listShellJobRecords,
     readShellJobRecord,
@@ -37,7 +46,15 @@ function recoveredTaskMatches(record, options = {}) {
     const clientHostPid = Number(context?.clientHostPid) || null;
     if (sessionIds.size === 0 && !clientHostPid) return true;
     if (!record?.ownerSessionId && !record?.ownerHostPid) return true;
-    if (record.ownerSessionId && sessionIds.has(String(record.ownerSessionId))) return true;
+    // A caller WITH session identity is authorized by session identity ONLY.
+    // In a pooled host every pane shares one claude.exe pid, so the host pid
+    // can neither widen a session mismatch nor stand in for a record that
+    // never recorded an owner session — both kept other panes' commands and
+    // results visible. The pid path remains for callers that have no session
+    // identity at all, where it is the only identity available.
+    if (sessionIds.size > 0) {
+        return Boolean(record.ownerSessionId) && sessionIds.has(String(record.ownerSessionId));
+    }
     return Boolean(clientHostPid && Number(record.ownerHostPid) === clientHostPid);
 }
 
@@ -53,20 +70,15 @@ function renderRecoveredShellTask(record) {
     ].join('\n');
 }
 
-function shellJobToTaskStatus(status) {
-    if (status === 'completed') return 'completed';
-    if (status === 'cancelled') return 'cancelled';
-    if (status === 'running') return 'running';
-    return 'failed';
-}
-
 function refreshShellTask(taskId, { includeRunning = false } = {}) {
     const job = peekShellJob(taskId);
     if (!job) return null;
     const publicResult = shellJobPublicTaskResult(job);
     if (job.status !== 'running') {
         completeBackgroundTask(taskId, {
-            status: shellJobToTaskStatus(job.status),
+            // Same mapping as the completion notification, so a non-zero exit
+            // reads as a completed task in both surfaces.
+            status: shellJobTaskStatus(job),
             result: publicResult,
             resultText: JSON.stringify(publicResult, null, 2),
             notify: false,
@@ -91,6 +103,14 @@ function renderTaskCancelSuccess(taskId, task) {
     ].join('\n');
 }
 
+// Clamp lives next to the caller; the bounds themselves are published by the
+// tool schema, so an out-of-range request is corrected rather than rejected.
+function resolveTaskWaitTimeoutMs(value) {
+    const raw = Number(value);
+    if (!Number.isFinite(raw) || raw <= 0) return TASK_WAIT_TIMEOUT_DEFAULT_MS;
+    return Math.min(TASK_WAIT_TIMEOUT_MAX_MS, Math.max(TASK_WAIT_TIMEOUT_MIN_MS, Math.floor(raw)));
+}
+
 export async function executeTaskTool(args, options = {}) {
     const action = typeof args.action === 'string' ? args.action.toLowerCase() : '';
     if (!action) return 'Error: task action is required';
@@ -114,8 +134,8 @@ export async function executeTaskTool(args, options = {}) {
     if (/^sess_/.test(taskId)) {
         return `Error: "${taskId}" is an agent/session id, not a background task_id. Agent tasks deliver completion notifications; use agent list/read only for manual recovery.`;
     }
-    if (action !== 'read' && action !== 'monitor' && action !== 'cancel') {
-        return `Error: task action must be one of list|read|monitor|cancel (got ${JSON.stringify(args.action)})`;
+    if (action !== 'read' && action !== 'wait' && action !== 'cancel') {
+        return `Error: task action must be one of list|read|wait|cancel (got ${JSON.stringify(args.action)})`;
     }
 
     const task = getBackgroundTask(taskId, { context: options });
@@ -124,56 +144,108 @@ export async function executeTaskTool(args, options = {}) {
         if (!recovered || !recoveredTaskMatches(recovered, options)) {
             return `Error: task not found: ${taskId}`;
         }
-        if (action === 'read') {
-            return recovered.terminal
-                ? renderRecoveredShellTask(recovered)
-                : `Error: task state is unavailable after restart: ${taskId}`;
+        if (action === 'read' || action === 'wait') {
+            // Nothing to wait ON after a restart: the process is gone, so wait
+            // degrades to the recovered snapshot rather than blocking.
+            if (!recovered.terminal) return `Error: task state is unavailable after restart: ${taskId}`;
+            recordDeliveredCompletion({ executionId: taskId });
+            return renderRecoveredShellTask(recovered);
         }
         if (action === 'cancel') {
             return recovered.terminal
                 ? `Error: task already ${recovered.status}: ${taskId}`
                 : `Error: task process control is unavailable after restart: ${taskId}`;
         }
-        if (action === 'monitor') {
-            return `Error: task monitoring is unavailable after restart: ${taskId}`;
-        }
     }
     const isShellTask = task.surface === 'shell';
 
-    if (action === 'read') {
+    if (action === 'read' || action === 'wait') {
+        if (action === 'wait') {
+            if (!isShellTask) return `Error: task wait is only available for shell tasks: ${taskId}`;
+            // The turn's abort signal must cut the wait short; a cancelled turn
+            // cannot sit out the remaining ceiling.
+            let waitSignal = null;
+            try { waitSignal = (await getAbortSignalForSession(options?.sessionId)) || null; }
+            catch { waitSignal = null; }
+            const waitTimeoutMs = resolveTaskWaitTimeoutMs(args.timeout_ms);
+            // A shell task whose descendants outlived the shell process has no
+            // native job to subscribe to — the process it belonged to is gone.
+            // Its registry promise (resolved by the descendant observer) is the
+            // completion event in that case.
+            if (!peekShellJob(taskId) && task.status === 'running' && task.promise) {
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, waitTimeoutMs);
+                    timer.unref?.();
+                    const done = () => { clearTimeout(timer); resolve(); };
+                    task.promise.then(done, done);
+                    if (waitSignal) {
+                        if (waitSignal.aborted) done();
+                        else waitSignal.addEventListener('abort', done, { once: true });
+                    }
+                });
+            } else {
+                await waitForShellJob(taskId, {
+                    timeoutMs: waitTimeoutMs,
+                    signal: waitSignal,
+                });
+            }
+        }
         if (isShellTask) refreshShellTask(taskId, { includeRunning: true });
         const latest = getBackgroundTask(taskId, { context: options }) || task;
         const rendered = renderBackgroundTask(latest, { includeResult: true });
-        return rendered;
-    }
-
-    if (action === 'monitor') {
-        const intervalMs = args.monitor_interval_ms;
-        if (!isValidShellMonitorIntervalMs(intervalMs)) {
-            return `Error: task monitor_interval_ms must be 0 or an integer from ${SHELL_MONITOR_INTERVAL_MIN_MS} to ${SHELL_MONITOR_INTERVAL_MAX_MS} ms`;
+        if (acknowledgeBackgroundTaskCompletion(taskId, { context: options })) {
+            recordDeliveredCompletion({ executionId: taskId });
         }
-        if (!isShellTask) return `Error: task monitoring is only available for shell tasks: ${taskId}`;
-        const configured = configureBackgroundShellJobMonitor(taskId, intervalMs);
-        if (configured == null) return `Error: shell task is not running: ${taskId}`;
-        return [
-            'status: running',
-            `task_id: ${taskId}`,
-            `monitoring: ${configured === 0 ? 'off' : 'on'}`,
-            `monitor_interval_ms: ${configured}`,
-        ].join('\n');
+        return rendered;
     }
 
     if (action === 'cancel') {
         if (isShellTask) {
+            // A tracked task with no native job is still cancellable: the
+            // registry's own cancel hook owns it (descendants that outlived
+            // their shell). Remember that it WAS live so the outcome is
+            // reported as a cancellation rather than "task not found".
+            const wasRunning = task.status === 'running';
             const job = killShellJob(taskId);
+            if (job) {
+                // Confirm the process actually terminated before reporting a
+                // terminal status. Removing the watcher on the strength of a
+                // delivered signal left a live, unmonitored process behind a
+                // false 'cancelled'.
+                const confirmed = await waitForShellJob(taskId, { timeoutMs: TASK_CANCEL_CONFIRM_MS });
+                if (confirmed && confirmed.status === 'running') {
+                    // Watcher and notify context stay armed: the eventual exit
+                    // must still reach the owner.
+                    return [
+                        'status: cancel-unconfirmed',
+                        `task_id: ${taskId}`,
+                        'the cancellation was delivered but the process has not exited yet. It stays tracked and its completion is still delivered; re-run task cancel or task read to check again.',
+                    ].join('\n');
+                }
+                if (!confirmed) {
+                    // No terminal event and no observable task: absence of
+                    // state is not proof of termination. Stop tracking it so it
+                    // cannot hang as 'running' forever, but never claim it died.
+                    cancelBackgroundShellJobWatch(taskId);
+                    clearShellJobNotifyCtx(taskId);
+                    cancelBackgroundTask(taskId, 'cancelled by task control; termination unconfirmed');
+                    return [
+                        'status: cancel-unconfirmed',
+                        `task_id: ${taskId}`,
+                        'the cancellation was delivered but this task is no longer observable, so its termination could not be confirmed. Verify the process directly if it must be gone.',
+                    ].join('\n');
+                }
+            }
             cancelBackgroundShellJobWatch(taskId);
             clearShellJobNotifyCtx(taskId);
             cancelBackgroundTask(taskId, 'cancelled by task control');
-            return job ? renderTaskCancelSuccess(taskId, getBackgroundTask(taskId, { context: options }) || task) : buildJobNotFoundMessage(taskId);
+            return (job || wasRunning)
+                ? renderTaskCancelSuccess(taskId, getBackgroundTask(taskId, { context: options }) || task)
+                : buildJobNotFoundMessage(taskId);
         }
         cancelBackgroundTask(taskId, 'cancelled by task control');
         return renderTaskCancelSuccess(taskId, getBackgroundTask(taskId, { context: options }) || task);
     }
 
-    return `Error: task action must be one of list|read|monitor|cancel (got ${JSON.stringify(args.action)})`;
+    return `Error: task action must be one of list|read|wait|cancel (got ${JSON.stringify(args.action)})`;
 }