@pellux/goodvibes-sdk 0.37.1 → 0.38.0

package/dist/platform/tools/exec/runtime.js

@@ -107,6 +107,40 @@ function applyExpectations(result, expect, exitCode) {
 function buildTimedOutResult(cmdStr, cwd, durationMs, progressFile) {
     return { cmd: cmdStr, exit_code: null, stdout: '', stderr: '', success: false, timed_out: true, duration_ms: durationMs, cwd, ...(progressFile ? { progress_file: progressFile } : {}) };
 }
+/** Wave-4 cooperative cancellation (wo701): mirrors buildTimedOutResult's shape for the AbortSignal path. */
+function buildCancelledResult(cmdStr, cwd, durationMs) {
+    return { cmd: cmdStr, exit_code: null, stdout: '', stderr: '', success: false, cancelled: true, duration_ms: durationMs, cwd };
+}
+/**
+ * Grace window for draining a killed child's stdout/stderr after a
+ * timeout/abort stop before returning regardless. Kept well under the
+ * cancellation-latency budget the cooperative-cancellation tests assert
+ * (< 5s).
+ */
+const POST_STOP_DRAIN_GRACE_MS = 500;
+/**
+ * Wave-4 cooperative cancellation (wo701): after a timeout/abort kill the
+ * child has already been SIGKILL'd, but a grandchild that inherited the
+ * stdout/stderr pipe can hold it open, so reading those streams to EOF may
+ * never settle. Awaiting the full IO promise unbounded here could therefore
+ * block until the grandchild's own duration elapses (observed as a hang under
+ * loaded CI). A cancelled/timed-out result never depends on fully-drained
+ * content, so bound the wait to a short grace window and return regardless.
+ * The still-pending IO promise is defused so it can never surface as an
+ * unhandled rejection; the grace timer is unref'd so it cannot keep the event
+ * loop (or a test runner) alive.
+ */
+async function drainAfterStop(io, graceMs) {
+    const settled = io.then(() => undefined, () => undefined);
+    let timer;
+    const grace = new Promise((resolve) => {
+        timer = setTimeout(resolve, graceMs);
+        timer.unref?.();
+    });
+    await Promise.race([settled, grace]);
+    if (timer)
+        clearTimeout(timer);
+}
 function getProgressDirectory(workingDirectory) {
     return join(workingDirectory, ...OVERFLOW_SUBDIR);
 }
@@ -144,7 +178,7 @@ async function spawnBackground(processManager, cmd, cwd, env) {
 function handleBgSpecialCommand(processManager, cmd) {
     return processManager.handleCommand(cmd);
 }
-async function runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout) {
+async function runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal) {
     const guardResult = await guardExecCommand(cmdStr, DEFAULT_ALLOWED_CLASSES, featureFlags);
     if (!guardResult.allowed) {
         const denial = formatDenialResponse(guardResult, cmdStr);
@@ -163,18 +197,25 @@ async function runCommand(processManager, overflowHandler, featureFlags, cmdStr,
     const timeoutMs = cmdInput.timeout_ms ?? globalTimeout;
     const mergedEnv = { ...buildCleanEnv(), ...cmdInput.env };
     const startTime = Date.now();
+    // Wave-4 cooperative cancellation (wo701) is wired for the foreground and
+    // progress-streamed paths (the common cases — progress auto-engages once
+    // timeout_ms exceeds PROGRESS_AUTO_THRESHOLD_MS, which the 120s default
+    // timeout always does). `until`-pattern commands are explicitly deferred
+    // (see the WO report) — the timeout kill-timer they already have still
+    // applies, just not an external AbortSignal.
     if (cmdInput.until) {
         return runUntil(processManager, overflowHandler, cmdStr, cmdInput, cwd, mergedEnv, timeoutMs, startTime);
     }
     const useProgress = cmdInput.progress === true || timeoutMs > PROGRESS_AUTO_THRESHOLD_MS;
     if (useProgress) {
-        return runCommandWithProgress(processManager, overflowHandler, cmdStr, cmdInput, workingDirectory, cwd, mergedEnv, timeoutMs, startTime);
+        return runCommandWithProgress(processManager, overflowHandler, cmdStr, cmdInput, workingDirectory, cwd, mergedEnv, timeoutMs, startTime, signal);
     }
     const proc = Bun.spawn(['/bin/sh', '-c', cmdStr], { ...(cwd !== undefined ? { cwd } : {}), env: mergedEnv, stdout: 'pipe', stderr: 'pipe' });
     let timedOut = false;
+    let cancelled = false;
     let killTimer;
-    let timeoutResolve;
-    const timeoutSentinel = new Promise((res) => { timeoutResolve = res; });
+    let stopResolve;
+    const stopSentinel = new Promise((res) => { stopResolve = res; });
     killTimer = setTimeout(async () => {
         timedOut = true;
         try {
@@ -186,9 +227,31 @@ async function runCommand(processManager, overflowHandler, featureFlags, cmdStr,
             // The process may have already exited before kill.
             logger.debug('[ExecRuntime] kill on timeout failed (process may have exited)', { error: String(err) });
         }
-        timeoutResolve();
+        stopResolve();
     }, timeoutMs);
     killTimer.unref?.();
+    const onAbort = () => {
+        if (timedOut || cancelled)
+            return;
+        cancelled = true;
+        void (async () => {
+            try {
+                proc.kill('SIGTERM');
+                await sleep(200);
+                proc.kill('SIGKILL');
+            }
+            catch (err) {
+                logger.debug('[ExecRuntime] kill on cancellation failed (process may have exited)', { error: String(err) });
+            }
+            stopResolve();
+        })();
+    };
+    if (signal) {
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+    }
     try {
         const procPromise = Promise.all([
             new Response(proc.stdout).text(),
@@ -198,20 +261,18 @@ async function runCommand(processManager, overflowHandler, featureFlags, cmdStr,
         let procResult;
         await Promise.race([
             procPromise.then((r) => { procResult = r; }),
-            timeoutSentinel,
+            stopSentinel,
         ]);
         clearTimeout(killTimer);
-        if (timedOut) {
-            try {
-                await procPromise;
-            }
-            catch (error) {
-                logger.debug('exec foreground command collection failed after timeout', {
-                    command: cmdStr,
-                    error: summarizeError(error),
-                });
-            }
-            return buildTimedOutResult(cmdStr, cwd, Date.now() - startTime);
+        if (signal)
+            signal.removeEventListener('abort', onAbort);
+        if (timedOut || cancelled) {
+            // Bounded drain: the child is already killed; never block past a short
+            // grace window on streams an orphaned grandchild may keep open.
+            await drainAfterStop(procPromise, POST_STOP_DRAIN_GRACE_MS);
+            return timedOut
+                ? buildTimedOutResult(cmdStr, cwd, Date.now() - startTime)
+                : buildCancelledResult(cmdStr, cwd, Date.now() - startTime);
         }
         const [stdoutRaw, stderrRaw, exitCode] = procResult;
         const stdoutResult = truncate(overflowHandler, stdoutRaw, 'stdout');
@@ -233,16 +294,19 @@ async function runCommand(processManager, overflowHandler, featureFlags, cmdStr,
     }
     catch (err) {
         clearTimeout(killTimer);
+        if (signal)
+            signal.removeEventListener('abort', onAbort);
         throw err;
     }
 }
-async function runCommandWithProgress(_processManager, overflowHandler, cmdStr, cmdInput, workingDirectory, cwd, mergedEnv, timeoutMs, startTime) {
+async function runCommandWithProgress(_processManager, overflowHandler, cmdStr, cmdInput, workingDirectory, cwd, mergedEnv, timeoutMs, startTime, signal) {
     const progressFile = initProgressFile(cmdStr, workingDirectory);
     const proc = Bun.spawn(['/bin/sh', '-c', cmdStr], { ...(cwd !== undefined ? { cwd } : {}), env: mergedEnv, stdout: 'pipe', stderr: 'pipe' });
     let timedOut = false;
+    let cancelled = false;
     let killTimer;
-    let timeoutResolve;
-    const timeoutSentinel = new Promise((res) => { timeoutResolve = res; });
+    let stopResolve;
+    const stopSentinel = new Promise((res) => { stopResolve = res; });
     killTimer = setTimeout(async () => {
         timedOut = true;
         try {
@@ -254,9 +318,32 @@ async function runCommandWithProgress(_processManager, overflowHandler, cmdStr,
             logger.debug('[ExecRuntime] kill on streamed timeout failed (process may have exited)', { error: String(err) });
         }
         progressFile.append('# Timed out\n');
-        timeoutResolve();
+        stopResolve();
     }, timeoutMs);
     killTimer.unref?.();
+    const onAbort = () => {
+        if (timedOut || cancelled)
+            return;
+        cancelled = true;
+        void (async () => {
+            try {
+                proc.kill('SIGTERM');
+                await sleep(200);
+                proc.kill('SIGKILL');
+            }
+            catch (err) {
+                logger.debug('[ExecRuntime] kill on cancellation failed (process may have exited)', { error: String(err) });
+            }
+            progressFile.append('# Cancelled\n');
+            stopResolve();
+        })();
+    };
+    if (signal) {
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+    }
     let stdoutBuf = '';
     let stderrBuf = '';
     const warnings = [];
@@ -304,19 +391,18 @@ async function runCommandWithProgress(_processManager, overflowHandler, cmdStr,
         }
     };
     const ioPromise = Promise.all([readStdout(), readStderr(), proc.exited]);
-    await Promise.race([ioPromise, timeoutSentinel]);
+    await Promise.race([ioPromise, stopSentinel]);
     clearTimeout(killTimer);
-    if (timedOut) {
-        try {
-            await ioPromise;
-        }
-        catch (error) {
-            logger.debug('exec progress command IO collection failed after timeout', {
-                command: cmdStr,
-                error: summarizeError(error),
-            });
-        }
-        return { ...buildTimedOutResult(cmdStr, cwd, Date.now() - startTime, progressFile.path), stdout: stdoutBuf, stderr: stderrBuf };
+    if (signal)
+        signal.removeEventListener('abort', onAbort);
+    if (timedOut || cancelled) {
+        // Bounded drain: the child is already killed; never block past a short
+        // grace window on streams an orphaned grandchild may keep open. stdoutBuf/
+        // stderrBuf already hold whatever the background readers captured so far.
+        await drainAfterStop(ioPromise, POST_STOP_DRAIN_GRACE_MS);
+        return timedOut
+            ? { ...buildTimedOutResult(cmdStr, cwd, Date.now() - startTime, progressFile.path), stdout: stdoutBuf, stderr: stderrBuf }
+            : { ...buildCancelledResult(cmdStr, cwd, Date.now() - startTime), stdout: stdoutBuf, stderr: stderrBuf, progress_file: progressFile.path };
     }
     const ioResult = await ioPromise.catch((error) => {
         logger.warn('exec progress command IO collection failed', {
@@ -440,6 +526,10 @@ export function isRetryableExecResult(result, allowed) {
     // Timed-out commands are never auto-retried — callers must decide
     if (result.timed_out)
         return false;
+    // Cancelled commands (Wave 4, wo701) must never be retried — retrying
+    // after an operator/engine kill would defeat the cancellation entirely.
+    if (result.cancelled)
+        return false;
     const combined = `${result.stdout}\n${result.stderr}`;
     // Terminal errors — always skip retry
     const TERMINAL_PATTERNS = [
@@ -476,9 +566,9 @@ export function isRetryableExecResult(result, allowed) {
     }
     return false;
 }
-async function runWithRetry(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout) {
+async function runWithRetry(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal) {
     if (!cmdInput.retry) {
-        return runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout);
+        return runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal);
     }
     const maxRetries = Math.min(cmdInput.retry.max ?? 3, 10);
     const delayMs = cmdInput.retry.delay_ms ?? 1000;
@@ -487,7 +577,7 @@ async function runWithRetry(processManager, overflowHandler, featureFlags, cmdSt
     const retryOn = cmdInput.retry.on;
     let lastResult;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        lastResult = await runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout);
+        lastResult = await runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal);
         if (lastResult.success) {
             return { ...lastResult, retries: attempt };
         }
@@ -504,18 +594,21 @@ async function runWithRetry(processManager, overflowHandler, featureFlags, cmdSt
     }
     return { ...lastResult, retries: maxRetries };
 }
-async function executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout) {
+async function executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal) {
     const bgSpecial = handleBgSpecialCommand(processManager, cmdStr);
     if (bgSpecial)
         return bgSpecial;
     if (cmdInput.background) {
+        // Background processes intentionally outlive this tool call — cancelling
+        // the caller's item/agent must not kill a process the user asked to
+        // detach, so `signal` is deliberately not threaded here.
         return spawnBackground(processManager, cmdStr, resolveCwd(cmdInput.cwd, workingDirectory), cmdInput.env);
     }
-    return runWithRetry(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout);
+    return runWithRetry(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal);
 }
-async function executeResolvedCommands(processManager, overflowHandler, featureFlags, resolvedCmds, parallel, workingDirectory, globalTimeout, failFast) {
+async function executeResolvedCommands(processManager, overflowHandler, featureFlags, resolvedCmds, parallel, workingDirectory, globalTimeout, failFast, signal) {
     if (parallel) {
-        return mapWithConcurrency(resolvedCmds, MAX_PARALLEL_EXEC_COMMANDS, ({ cmdStr, cmdInput }) => executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout));
+        return mapWithConcurrency(resolvedCmds, MAX_PARALLEL_EXEC_COMMANDS, ({ cmdStr, cmdInput }) => executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal));
     }
     const results = [];
     let stopped = false;
@@ -524,7 +617,7 @@ async function executeResolvedCommands(processManager, overflowHandler, featureF
             results.push({ cmd: cmdStr, exit_code: null, stdout: '', stderr: '', success: false, skipped: true });
             continue;
         }
-        const result = await executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout);
+        const result = await executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal);
         results.push(result);
         if (failFast && !result.success) {
             stopped = true;
@@ -550,6 +643,7 @@ function formatResult(result, verbosity) {
                 stderr: firstStderr,
                 ...(result.expectation_error && { expectation_error: result.expectation_error }),
                 ...(result.timed_out && { timed_out: true }),
+                ...(result.cancelled && { cancelled: true }),
                 ...(result.process_id && { process_id: result.process_id, pid: result.pid }),
                 ...(result.progress_file && { progress_file: result.progress_file }),
                 ...(result.warnings && { warnings: result.warnings }),
@@ -567,6 +661,7 @@ function formatResult(result, verbosity) {
                 stderr: result.stderr,
                 ...(result.expectation_error && { expectation_error: result.expectation_error }),
                 ...(result.timed_out && { timed_out: true }),
+                ...(result.cancelled && { cancelled: true }),
                 ...(result.process_id && { process_id: result.process_id, pid: result.pid }),
                 ...(result.stdout_truncated && { stdout_truncated: true }),
                 ...(result.stderr_truncated && { stderr_truncated: true }),
@@ -593,7 +688,7 @@ export function createExecTool(processManager, options = {}) {
             supportsProgress: true,
             supportsStreamingOutput: true,
         },
-        async execute(args) {
+        async execute(args, opts) {
             try {
                 if (!Array.isArray(args['commands']) || args['commands'].length === 0) {
                     return { success: false, error: 'commands must be a non-empty array' };
@@ -627,7 +722,7 @@ export function createExecTool(processManager, options = {}) {
                     }
                     resolvedCmds.push({ cmdStr, cmdInput });
                 }
-                const results = await executeResolvedCommands(processManager, overflowHandler, featureFlags, resolvedCmds, input.parallel === true, workingDirectory, globalTimeout, failFast);
+                const results = await executeResolvedCommands(processManager, overflowHandler, featureFlags, resolvedCmds, input.parallel === true, workingDirectory, globalTimeout, failFast, opts?.signal);
                 const formatted = results.map((r) => formatResult(r, verbosity));
                 const allSuccess = results.every((r) => r.success);
                 const responseData = formatted.length === 1 ? { ...formatted[0] } : { commands: formatted, total: formatted.length };
@@ -641,7 +736,7 @@ export function createExecTool(processManager, options = {}) {
                 const failed = results.filter((r) => !r.success);
                 const errorSummary = failed.length > 0
                     ? `${failed.length} of ${results.length} command(s) failed: `
-                        + failed.map((r) => `'${r.cmd}'${r.skipped ? ' (skipped)' : ` exit ${r.exit_code}${r.timed_out ? ' (timed out)' : ''}`}`).join('; ')
+                        + failed.map((r) => `'${r.cmd}'${r.skipped ? ' (skipped)' : ` exit ${r.exit_code}${r.timed_out ? ' (timed out)' : r.cancelled ? ' (cancelled)' : ''}`}`).join('; ')
                     : undefined;
                 return {
                     success: allSuccess,

package/dist/platform/tools/exec/schema.d.ts

@@ -269,6 +269,8 @@ export interface ExecCommandResult {
     expectation_error?: string | undefined;
     /** Set when command exceeded timeout. */
     timed_out?: boolean | undefined;
+    /** Set when an external AbortSignal cancelled the command (Wave 4, wo701 — orchestration engine cancellation). Never combined with timed_out. */
+    cancelled?: boolean | undefined;
     /** Set when command ran in background. */
     process_id?: string | undefined;
     pid?: number | undefined;

package/dist/platform/tools/exec/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/exec/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/exec/schema.ts"],"names":[],"mappings":"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"}

package/dist/platform/tools/fetch/runtime.d.ts

@@ -6,6 +6,13 @@ import type { FeatureFlagManager } from '../../runtime/feature-flags/index.js';
 export interface FetchRuntimeDeps {
     readonly serviceRegistry?: Pick<ServiceRegistry, 'resolveAuth'> | null | undefined;
     readonly featureFlags?: Pick<FeatureFlagManager, 'isEnabled'> | null | undefined;
+    /**
+     * Wave-4 cooperative cancellation (wo701): an externally-supplied signal,
+     * combined with each request's own per-URL timeout signal via
+     * `AbortSignal.any`. Optional and additive — omitted, behavior is
+     * unchanged from before this field existed.
+     */
+    readonly signal?: AbortSignal | undefined;
 }
 interface CacheEntry {
     data: FetchUrlResult;

package/dist/platform/tools/fetch/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/fetch/runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAsF,MAAM,aAAa,CAAC;AAClI,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAM/E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACnF,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;CAClF;AAED,UAAU,UAAU;IAClB,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AASD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiC;IAC/D,OAAO,CAAC,eAAe,CAAK;IAE5B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAOtE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAiBxC,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;CAkFpF;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,CAE5G;AAseD,wBAAgB,eAAe,CAC7B,IAAI,GAAE,gBAAqB,EAC3B,OAAO,sBAA4B,GAClC,IAAI,CAiCN"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/fetch/runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAsF,MAAM,aAAa,CAAC;AAClI,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAM/E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACnF,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACjF;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED,UAAU,UAAU;IAClB,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AASD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiC;IAC/D,OAAO,CAAC,eAAe,CAAK;IAE5B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAOtE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAiBxC,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;CAkFpF;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,CAE5G;AA0eD,wBAAgB,eAAe,CAC7B,IAAI,GAAE,gBAAqB,EAC3B,OAAO,sBAA4B,GAClC,IAAI,CAqCN"}

package/dist/platform/tools/fetch/runtime.js

@@ -165,8 +165,9 @@ function encodeFormBodyData(bodyData) {
     }
     return params.toString();
 }
-async function fetchOneRaw(urlInput, headers, method, body, effectiveUrl, trustTierConfig, sanitizationEnabled) {
-    const { signal, dispose } = createTimeoutController(urlInput.timeout_ms ?? DEFAULT_TIMEOUT_MS);
+async function fetchOneRaw(urlInput, headers, method, body, effectiveUrl, trustTierConfig, sanitizationEnabled, externalSignal) {
+    const { signal: timeoutSignal, dispose } = createTimeoutController(urlInput.timeout_ms ?? DEFAULT_TIMEOUT_MS);
+    const signal = externalSignal ? AbortSignal.any([timeoutSignal, externalSignal]) : timeoutSignal;
     try {
         return sanitizationEnabled
             ? await fetchWithValidatedRedirects({
@@ -353,14 +354,14 @@ async function fetchOne(urlInput, opts, runtime) {
     const { headers, body: requestBody } = await prepareFetchRequest(urlInput, deps);
     const startTime = performance.now();
     try {
-        let response = await fetchOneRaw(urlInput, headers, method, requestBody, effectiveUrl, trustTierConfig, sanitizationEnabled);
+        let response = await fetchOneRaw(urlInput, headers, method, requestBody, effectiveUrl, trustTierConfig, sanitizationEnabled, deps.signal);
         const retryOnAuth = urlInput.retry_on_auth ?? (urlInput.service !== undefined);
         if (response.status === 401 && retryOnAuth && urlInput.service && !(requestBody instanceof FormData)) {
             const refreshedHeaders = await deps.serviceRegistry?.resolveAuth(urlInput.service);
             if (refreshedHeaders) {
                 const retryHeaders = { ...headers };
                 Object.assign(retryHeaders, refreshedHeaders);
-                response = await fetchOneRaw(urlInput, retryHeaders, method, requestBody, effectiveUrl, trustTierConfig, sanitizationEnabled);
+                response = await fetchOneRaw(urlInput, retryHeaders, method, requestBody, effectiveUrl, trustTierConfig, sanitizationEnabled, deps.signal);
             }
         }
         const durationMs = Math.round(performance.now() - startTime);
@@ -503,13 +504,14 @@ export function createFetchTool(deps = {}, runtime = new FetchRuntimeService())
             supportsProgress: true,
             supportsStreamingOutput: true,
         },
-        async execute(args) {
+        async execute(args, opts) {
             if (!Array.isArray(args.urls) || args.urls.length === 0) {
                 return { success: false, error: 'Missing or empty "urls" array' };
             }
             try {
                 const input = { ...args, urls: args.urls };
-                const output = await runtime.execute(input, deps);
+                const effectiveDeps = opts?.signal ? { ...deps, signal: opts.signal } : deps;
+                const output = await runtime.execute(input, effectiveDeps);
                 return { success: true, output: JSON.stringify(output) };
             }
             catch (err) {

package/dist/platform/tools/registry.d.ts

@@ -1,4 +1,4 @@
-import type { Tool, ToolDefinition, ToolResult } from '../types/tools.js';
+import type { Tool, ToolDefinition, ToolExecuteOptions, ToolResult } from '../types/tools.js';
 import type { ContractVerificationResult, ContractVerifierOptions } from '../runtime/tools/contract-verifier.js';
 /**
  * ToolRegistry - Central registry for all tools available to the LLM.
@@ -41,8 +41,14 @@ export declare class ToolRegistry {
     verifyAllContracts(opts?: ContractVerifierOptions): Map<string, ContractVerificationResult>;
     /** Returns the ToolDefinition array formatted for LLM function calling. */
     getToolDefinitions(): ToolDefinition[];
-    /** Execute a named tool with the given arguments. Wraps errors in ToolResult. */
-    execute(callId: string, name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * Execute a named tool with the given arguments. Wraps errors in ToolResult.
+     *
+     * `opts.signal` (Wave 4, wo701) is an additive pass-through to
+     * `tool.execute` — only tools that opt in (exec, fetch) read it. Callers
+     * that don't have a cancellation signal (the common case) omit `opts`.
+     */
+    execute(callId: string, name: string, args: Record<string, unknown>, opts?: ToolExecuteOptions): Promise<ToolResult>;
     /** Returns true if a tool with the given name is registered. */
     has(name: string): boolean;
     /** Returns all registered tools. */

package/dist/platform/tools/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/platform/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI1E,OAAO,KAAK,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAGjH;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA2B;IAExC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAO1B;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAClB,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,uBAAuB,GAC7B,0BAA0B;IAiB7B;;;;;;OAMG;IACH,cAAc,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,uBAAuB,GAC7B,0BAA0B,GAAG,SAAS;IAOzC;;;;;OAKG;IACH,kBAAkB,CAChB,IAAI,CAAC,EAAE,uBAAuB,GAC7B,GAAG,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAK1C,2EAA2E;IAC3E,kBAAkB,IAAI,cAAc,EAAE;IAItC,iFAAiF;IAC3E,OAAO,CACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC;IA0CtB,gEAAgE;IAChE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,oCAAoC;IACpC,IAAI,IAAI,IAAI,EAAE;CAGf"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/platform/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI9F,OAAO,KAAK,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAGjH;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA2B;IAExC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAO1B;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAClB,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,uBAAuB,GAC7B,0BAA0B;IAiB7B;;;;;;OAMG;IACH,cAAc,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,uBAAuB,GAC7B,0BAA0B,GAAG,SAAS;IAOzC;;;;;OAKG;IACH,kBAAkB,CAChB,IAAI,CAAC,EAAE,uBAAuB,GAC7B,GAAG,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAK1C,2EAA2E;IAC3E,kBAAkB,IAAI,cAAc,EAAE;IAItC;;;;;;OAMG;IACG,OAAO,CACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,UAAU,CAAC;IA0CtB,gEAAgE;IAChE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,oCAAoC;IACpC,IAAI,IAAI,IAAI,EAAE;CAGf"}

package/dist/platform/tools/registry.js

@@ -70,8 +70,14 @@ export class ToolRegistry {
     getToolDefinitions() {
         return Array.from(this.tools.values()).map((t) => t.definition);
     }
-    /** Execute a named tool with the given arguments. Wraps errors in ToolResult. */
-    async execute(callId, name, args) {
+    /**
+     * Execute a named tool with the given arguments. Wraps errors in ToolResult.
+     *
+     * `opts.signal` (Wave 4, wo701) is an additive pass-through to
+     * `tool.execute` — only tools that opt in (exec, fetch) read it. Callers
+     * that don't have a cancellation signal (the common case) omit `opts`.
+     */
+    async execute(callId, name, args, opts) {
         const tool = this.tools.get(name);
         if (!tool) {
             return {
@@ -85,7 +91,7 @@ export class ToolRegistry {
             // Premium models that send correct calls pass through unchanged.
             const repairResult = repairToolCall(name, args, tool.definition);
             const effectiveArgs = repairResult.repaired ? repairResult.fixed : args;
-            const result = await tool.execute(effectiveArgs);
+            const result = await tool.execute(effectiveArgs, opts);
             // Tool.execute returns ToolResult without callId — inject it here
             const toolResult = { ...result, callId };
             if (repairResult.warnings && repairResult.warnings.length > 0) {

package/dist/platform/types/tools.d.ts

@@ -30,10 +30,23 @@ export interface ToolResult {
     /** Non-failing issues the caller should surface with the result. */
     warnings?: readonly string[] | undefined;
 }
+/**
+ * Optional per-call execution options.
+ *
+ * `signal` (Wave 4, wo701) is ADDITIVE: it was not present before, and every
+ * existing tool implementation that declares `execute(args)` with a single
+ * parameter remains a valid implementation of this interface (structural
+ * typing — an unused trailing optional parameter is simply never read). Only
+ * tools that opt in (exec, fetch) read it to propagate cooperative
+ * cancellation into a spawned child process or an in-flight request.
+ */
+export interface ToolExecuteOptions {
+    readonly signal?: AbortSignal | undefined;
+}
 /** A registered tool with its definition and executor. */
 export interface Tool {
     definition: ToolDefinition;
     /** Tools return a result without callId — the registry injects callId when wrapping. */
-    execute(args: Record<string, unknown>): Promise<Omit<ToolResult, 'callId'>>;
+    execute(args: Record<string, unknown>, opts?: ToolExecuteOptions): Promise<Omit<ToolResult, 'callId'>>;
 }
 //# sourceMappingURL=tools.d.ts.map

package/dist/platform/types/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/platform/types/tools.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,UAAU,GACV,SAAS,GACT,MAAM,GACN,OAAO,GACP,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AAEtE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,oEAAoE;IACpE,WAAW,CAAC,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,CAAC;IACpD,yDAAyD;IACzD,WAAW,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC9C,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,kEAAkE;IAClE,uBAAuB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/C;AAED,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC1C;AAED,0DAA0D;AAC1D,MAAM,WAAW,IAAI;IACnB,UAAU,EAAE,cAAc,CAAC;IAC3B,wFAAwF;IACxF,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;CAC7E"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/platform/types/tools.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,UAAU,GACV,SAAS,GACT,MAAM,GACN,OAAO,GACP,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AAEtE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,oEAAoE;IACpE,WAAW,CAAC,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,CAAC;IACpD,yDAAyD;IACzD,WAAW,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC9C,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,kEAAkE;IAClE,uBAAuB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/C;AAED,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED,0DAA0D;AAC1D,MAAM,WAAW,IAAI;IACnB,UAAU,EAAE,cAAc,CAAC;IAC3B,wFAAwF;IACxF,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;CACxG"}

package/dist/platform/version.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-let version = '0.37.1';
+let version = '0.38.0';
 try {
     const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf-8'));
     version = pkg.version ?? version;

package/dist/platform/workspace/checkpoint/side-git.d.ts

@@ -72,14 +72,26 @@ export declare class SideGitRunner {
      * Stage changes into the side index.
      *
      * @param paths When provided (non-empty), stage only these pathspecs
-     * (scoped snapshot). Otherwise sweep the whole work tree, always excluding
-     * `.goodvibes` (our own storage) via pathspec magic — the same
-     * `:(exclude)` pattern AgentWorktree already uses for the same reason.
-     * Beyond that exclusion, git's normal `.gitignore` handling already applies
-     * here: `.gitignore` matching is a work-tree-relative feature of git and
-     * works identically regardless of where GIT_DIR points, so the workspace's
-     * own `.gitignore` (node_modules, build output, etc.) is honored with no
-     * extra configuration.
+     * (scoped snapshot). Otherwise sweep the whole work tree with a plain `.`
+     * pathspec. `.goodvibes` (our own storage) is kept out of that sweep by
+     * `.goodvibes/.gitignore`'s own `*` self-ignore line, written by `init()`
+     * (via `ensureGoodvibesIgnored()`) before this method can ever run — NOT by
+     * naming `.goodvibes` explicitly here. An earlier version of this method
+     * did pass an explicit `:(exclude).goodvibes` / `:(exclude).goodvibes/**`
+     * pathspec (mirroring the pattern AgentWorktree uses for the same reason),
+     * but that breaks the moment the WORKSPACE's own top-level `.gitignore`
+     * also happens to contain a `.goodvibes/` rule (exactly what this project's
+     * own TUI writes at startup): git aborts the entire `add -A` with "The
+     * following paths are ignored by one of your .gitignore files: .goodvibes
+     * ... Use -f if you really want to add them," because naming an
+     * already-ignored path in ANY pathspec — exclude magic or not — triggers
+     * that check. A path git discovers and skips implicitly while walking a
+     * wildcard `.` sweep never hits that check. Beyond `.goodvibes`, git's
+     * normal `.gitignore` handling already applies here: `.gitignore` matching
+     * is a work-tree-relative feature of git and works identically regardless
+     * of where GIT_DIR points, so the workspace's own `.gitignore`
+     * (node_modules, build output, etc.) is honored with no extra
+     * configuration.
      */
     stageAll(paths?: string[]): Promise<void>;
     /** Write the currently-staged index out as a tree object, without committing. Returns the tree hash. */

package/dist/platform/workspace/checkpoint/side-git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"side-git.d.ts","sourceRoot":"","sources":["../../../../src/platform/workspace/checkpoint/side-git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,0EAA0E;AAC1E,eAAO,MAAM,eAAe,6CAA6C,CAAC;AAE1E,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,gCAAgC,CAAC;AA8CnE,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;gBAEpB,IAAI,EAAE,oBAAoB;IAUtC,gFAAgF;IAC1E,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1C;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C,wGAAwG;IAClG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAIlC,6DAA6D;IACvD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7C;;;;;;;;;;;;;;;;;OAiBG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,sEAAsE;IAChE,kBAAkB,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAmBrE,+DAA+D;IACzD,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAK/D,+FAA+F;IACzF,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,wGAAwG;IAClG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC,iGAAiG;IAC3F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAItD,wGAAwG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1D,6GAA6G;IACvG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKhE,6CAA6C;IACvC,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;CAG1B"}
+{"version":3,"file":"side-git.d.ts","sourceRoot":"","sources":["../../../../src/platform/workspace/checkpoint/side-git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,0EAA0E;AAC1E,eAAO,MAAM,eAAe,6CAA6C,CAAC;AAE1E,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,gCAAgC,CAAC;AA8CnE,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;gBAEpB,IAAI,EAAE,oBAAoB;IAUtC,gFAAgF;IAC1E,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1C;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/C,wGAAwG;IAClG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAIlC,6DAA6D;IACvD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7C;;;;;;;;;;;;;;;;;OAiBG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,sEAAsE;IAChE,kBAAkB,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAmBrE,+DAA+D;IACzD,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAK/D,+FAA+F;IACzF,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,wGAAwG;IAClG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC,iGAAiG;IAC3F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAItD,wGAAwG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1D,6GAA6G;IACvG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKhE,6CAA6C;IACvC,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;CAG1B"}

package/dist/platform/workspace/checkpoint/side-git.js

@@ -161,19 +161,29 @@ export class SideGitRunner {
      * Stage changes into the side index.
      *
      * @param paths When provided (non-empty), stage only these pathspecs
-     * (scoped snapshot). Otherwise sweep the whole work tree, always excluding
-     * `.goodvibes` (our own storage) via pathspec magic — the same
-     * `:(exclude)` pattern AgentWorktree already uses for the same reason.
-     * Beyond that exclusion, git's normal `.gitignore` handling already applies
-     * here: `.gitignore` matching is a work-tree-relative feature of git and
-     * works identically regardless of where GIT_DIR points, so the workspace's
-     * own `.gitignore` (node_modules, build output, etc.) is honored with no
-     * extra configuration.
+     * (scoped snapshot). Otherwise sweep the whole work tree with a plain `.`
+     * pathspec. `.goodvibes` (our own storage) is kept out of that sweep by
+     * `.goodvibes/.gitignore`'s own `*` self-ignore line, written by `init()`
+     * (via `ensureGoodvibesIgnored()`) before this method can ever run — NOT by
+     * naming `.goodvibes` explicitly here. An earlier version of this method
+     * did pass an explicit `:(exclude).goodvibes` / `:(exclude).goodvibes/**`
+     * pathspec (mirroring the pattern AgentWorktree uses for the same reason),
+     * but that breaks the moment the WORKSPACE's own top-level `.gitignore`
+     * also happens to contain a `.goodvibes/` rule (exactly what this project's
+     * own TUI writes at startup): git aborts the entire `add -A` with "The
+     * following paths are ignored by one of your .gitignore files: .goodvibes
+     * ... Use -f if you really want to add them," because naming an
+     * already-ignored path in ANY pathspec — exclude magic or not — triggers
+     * that check. A path git discovers and skips implicitly while walking a
+     * wildcard `.` sweep never hits that check. Beyond `.goodvibes`, git's
+     * normal `.gitignore` handling already applies here: `.gitignore` matching
+     * is a work-tree-relative feature of git and works identically regardless
+     * of where GIT_DIR points, so the workspace's own `.gitignore`
+     * (node_modules, build output, etc.) is honored with no extra
+     * configuration.
      */
     async stageAll(paths) {
-        const pathspecs = paths && paths.length > 0
-            ? paths
-            : ['.', ':(exclude).goodvibes', ':(exclude).goodvibes/**'];
+        const pathspecs = paths && paths.length > 0 ? paths : ['.'];
         await this.git.raw(['add', '-A', '--', ...pathspecs]);
     }
     /** Write the currently-staged index out as a tree object, without committing. Returns the tree hash. */