byterover-cli 3.13.0 → 3.15.0

package/dist/oclif/commands/settings/reset.js

@@ -0,0 +1,81 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { SettingsEvents, } from '../../../shared/transport/events/settings-events.js';
+import { formatCount, formatDuration } from '../../../shared/utils/format-duration.js';
+import { formatConnectionError, withDaemonRetry } from '../../lib/daemon-client.js';
+import { writeJsonResponse } from '../../lib/json-response.js';
+export default class SettingsReset extends Command {
+    static args = {
+        key: Args.string({ description: 'Settings key to reset', required: true }),
+    };
+    static description = 'Restore one settings value to its default. Changes apply after `brv restart`.';
+    static examples = [
+        '<%= config.bin %> settings reset agentPool.maxSize',
+        '<%= config.bin %> settings reset agentPool.maxSize --format json',
+    ];
+    static flags = {
+        format: Flags.string({
+            default: 'text',
+            description: 'Output format (text or json)',
+            options: ['text', 'json'],
+        }),
+    };
+    async fetchDescriptor(key, options) {
+        return withDaemonRetry(async (client) => client.requestWithAck(SettingsEvents.GET, { key }), options);
+    }
+    async resetSetting(key, options) {
+        return withDaemonRetry(async (client) => client.requestWithAck(SettingsEvents.RESET, { key }), options);
+    }
+    async run() {
+        const { args, flags } = await this.parse(SettingsReset);
+        const format = flags.format;
+        try {
+            const descriptor = await this.fetchDescriptor(args.key);
+            if (!descriptor.ok) {
+                process.exitCode = 1;
+                if (format === 'json') {
+                    writeJsonResponse({ command: 'settings reset', data: { error: descriptor.error }, success: false });
+                }
+                else {
+                    this.log(descriptor.error.message);
+                }
+                return;
+            }
+            const response = await this.resetSetting(args.key);
+            if (response.ok) {
+                if (format === 'json') {
+                    writeJsonResponse({
+                        command: 'settings reset',
+                        data: { restartRequired: response.restartRequired },
+                        success: true,
+                    });
+                }
+                else {
+                    this.log(`Setting reset: ${args.key} back to default (${renderValue(descriptor, descriptor.default)}). ` +
+                        'Run `brv restart` to apply.');
+                }
+                return;
+            }
+            process.exitCode = 1;
+            if (format === 'json') {
+                writeJsonResponse({ command: 'settings reset', data: { error: response.error }, success: false });
+            }
+            else {
+                this.log(response.error.message);
+            }
+        }
+        catch (error) {
+            process.exitCode = 1;
+            if (format === 'json') {
+                writeJsonResponse({ command: 'settings reset', data: { error: formatConnectionError(error) }, success: false });
+            }
+            else {
+                this.log(formatConnectionError(error));
+            }
+        }
+    }
+}
+function renderValue(item, value) {
+    if (item.unit === 'ms')
+        return formatDuration(value);
+    return formatCount(value);
+}

package/dist/oclif/commands/settings/set.d.ts

@@ -0,0 +1,17 @@
+import { Command } from '@oclif/core';
+import { type SettingsGetResponse, type SettingsSetResponse } from '../../../shared/transport/events/settings-events.js';
+import { type DaemonClientOptions } from '../../lib/daemon-client.js';
+export default class SettingsSet extends Command {
+    static args: {
+        key: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        value: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    protected fetchDescriptor(key: string, options?: DaemonClientOptions): Promise<SettingsGetResponse>;
+    run(): Promise<void>;
+    protected writeSetting(key: string, value: unknown, options?: DaemonClientOptions): Promise<SettingsSetResponse>;
+}

package/dist/oclif/commands/settings/set.js

@@ -0,0 +1,131 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { SettingsEvents, } from '../../../shared/transport/events/settings-events.js';
+import { formatCount, formatDuration, parseDuration, } from '../../../shared/utils/format-duration.js';
+import { formatConnectionError, withDaemonRetry } from '../../lib/daemon-client.js';
+import { writeJsonResponse } from '../../lib/json-response.js';
+const DURATION_RE = /\d+\s*(?:ms|s|m|h)/i;
+export default class SettingsSet extends Command {
+    static args = {
+        key: Args.string({ description: 'Settings key to write', required: true }),
+        value: Args.string({ description: 'New value (integer for count keys, duration like 30m / 1h 30m / 1800000 for ms keys)', required: true }),
+    };
+    static description = 'Update one settings value. Changes apply after `brv restart`.';
+    static examples = [
+        '<%= config.bin %> settings set agentPool.maxSize 25',
+        '<%= config.bin %> settings set llm.iterationBudgetMs 30m',
+        '<%= config.bin %> settings set agentPool.maxSize 25 --format json',
+    ];
+    static flags = {
+        format: Flags.string({
+            default: 'text',
+            description: 'Output format (text or json)',
+            options: ['text', 'json'],
+        }),
+    };
+    async fetchDescriptor(key, options) {
+        return withDaemonRetry(async (client) => client.requestWithAck(SettingsEvents.GET, { key }), options);
+    }
+    async run() {
+        const { args, flags } = await this.parse(SettingsSet);
+        const format = flags.format;
+        try {
+            const descriptor = await this.fetchDescriptor(args.key);
+            if (!descriptor.ok) {
+                process.exitCode = 1;
+                if (format === 'json') {
+                    writeJsonResponse({ command: 'settings set', data: { error: descriptor.error }, success: false });
+                }
+                else {
+                    this.log(descriptor.error.message);
+                }
+                return;
+            }
+            const parsed = parseValue(descriptor, args.value);
+            if (parsed.kind === 'error') {
+                process.exitCode = 1;
+                if (format === 'json') {
+                    writeJsonResponse({
+                        command: 'settings set',
+                        data: { error: { code: 'invalid_value', key: args.key, message: parsed.message, value: args.value } },
+                        success: false,
+                    });
+                }
+                else {
+                    this.log(parsed.message);
+                }
+                return;
+            }
+            const response = await this.writeSetting(args.key, parsed.value);
+            if (response.ok) {
+                if (format === 'json') {
+                    writeJsonResponse({
+                        command: 'settings set',
+                        data: { restartRequired: response.restartRequired, value: parsed.value },
+                        success: true,
+                    });
+                }
+                else {
+                    this.log(`Setting saved: ${args.key} = ${parsed.display}. Run \`brv restart\` to apply.`);
+                }
+                return;
+            }
+            process.exitCode = 1;
+            if (format === 'json') {
+                writeJsonResponse({ command: 'settings set', data: { error: response.error }, success: false });
+            }
+            else {
+                this.log(response.error.message);
+            }
+        }
+        catch (error) {
+            process.exitCode = 1;
+            if (format === 'json') {
+                writeJsonResponse({ command: 'settings set', data: { error: formatConnectionError(error) }, success: false });
+            }
+            else {
+                this.log(formatConnectionError(error));
+            }
+        }
+    }
+    async writeSetting(key, value, options) {
+        return withDaemonRetry(async (client) => client.requestWithAck(SettingsEvents.SET, { key, value }), options);
+    }
+}
+function parseValue(descriptor, raw) {
+    if (descriptor.unit === 'ms')
+        return parseAsDuration(descriptor, raw);
+    return parseAsCount(descriptor, raw);
+}
+function parseAsDuration(descriptor, raw) {
+    const parsed = parseDuration(raw);
+    if (typeof parsed === 'number') {
+        return { display: formatDuration(parsed), kind: 'ok', value: parsed };
+    }
+    return { kind: 'error', message: describeParseError(descriptor.key, parsed) };
+}
+function parseAsCount(descriptor, raw) {
+    if (DURATION_RE.test(raw)) {
+        return {
+            kind: 'error',
+            message: `${descriptor.key} expects an integer count, got duration '${raw}'.`,
+        };
+    }
+    const stripped = raw.replaceAll(',', '').trim();
+    if (stripped === '' || !/^-?\d+$/.test(stripped)) {
+        return {
+            kind: 'error',
+            message: `${descriptor.key} expects an integer count, got '${raw}'.`,
+        };
+    }
+    const numeric = Number.parseInt(stripped, 10);
+    if (!Number.isFinite(numeric)) {
+        return {
+            kind: 'error',
+            message: `${descriptor.key} expects an integer count, got '${raw}'.`,
+        };
+    }
+    return { display: formatCount(numeric), kind: 'ok', value: numeric };
+}
+function describeParseError(key, error) {
+    return `${key}: ${error.hint}`;
+}

package/dist/oclif/lib/mcp-cleanup.d.ts

@@ -0,0 +1,10 @@
+export type McpCleanupDeps = {
+    readonly exit: (code: number) => void;
+};
+/**
+ * Race a stop() callback against a hard timeout, then exit(0) regardless.
+ *
+ * Guarantees: exit is called exactly once; the timeout timer is cleared if
+ * stop() resolves first; a synchronous throw from stop() does not propagate.
+ */
+export declare function runMcpCleanup(stop: () => Promise<void>, timeoutMs: number, deps: McpCleanupDeps): Promise<void>;

package/dist/oclif/lib/mcp-cleanup.js

@@ -0,0 +1,28 @@
+/**
+ * Race a stop() callback against a hard timeout, then exit(0) regardless.
+ *
+ * Guarantees: exit is called exactly once; the timeout timer is cleared if
+ * stop() resolves first; a synchronous throw from stop() does not propagate.
+ */
+export async function runMcpCleanup(stop, timeoutMs, deps) {
+    let timer;
+    try {
+        const stopPromise = (async () => stop())().catch(() => {
+            // Swallow — exit anyway. Both sync throws and async rejections land here
+            // because the IIFE wraps the call in an async boundary.
+        });
+        const timeoutPromise = new Promise((resolve) => {
+            timer = setTimeout(resolve, timeoutMs);
+        });
+        await Promise.race([stopPromise, timeoutPromise]);
+    }
+    catch {
+        // Belt-and-suspenders: nothing inside the try is expected to throw, but if
+        // it ever does (e.g., setTimeout polyfill misbehaves), still exit cleanly.
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+    deps.exit(0);
+}

package/dist/oclif/lib/mcp-crash-handler.d.ts

@@ -0,0 +1,23 @@
+export type McpCrashHandlerDeps = {
+    readonly exit: (code: number) => void;
+    readonly fileWrite: (line: string) => void;
+    readonly now: () => Date;
+    readonly stderrWrite: (chunk: string) => void;
+};
+export type McpCrashHandlers = {
+    readonly onUncaughtException: (error: unknown) => void;
+    readonly onUnhandledRejection: (reason: unknown) => void;
+};
+/**
+ * Build process-level crash handlers for `brv mcp`.
+ *
+ * Each handler logs once and then exits with code 1. Every side effect is
+ * isolated in its own try/catch so a failing logger cannot re-fire the
+ * uncaughtException event. A module-instance re-entry flag adds defense in
+ * depth: once a crash is being handled, subsequent invocations short-circuit
+ * so `exit` is only called once.
+ *
+ * MCP clients (Claude Code / Cursor / Windsurf) respawn the server on demand,
+ * so log-and-exit is the protocol-correct behavior for this child process.
+ */
+export declare function createMcpCrashHandlers(deps: McpCrashHandlerDeps): McpCrashHandlers;

package/dist/oclif/lib/mcp-crash-handler.js

@@ -0,0 +1,69 @@
+const UNPRINTABLE = '<unprintable error>';
+function safeStack(err) {
+    try {
+        if (err instanceof Error) {
+            const { stack } = err;
+            if (typeof stack === 'string')
+                return stack;
+            const { message } = err;
+            if (typeof message !== 'string')
+                return UNPRINTABLE;
+            const { name } = err;
+            if (typeof name === 'string' && name.length > 0)
+                return `${name}: ${message}`;
+            return message;
+        }
+        return String(err);
+    }
+    catch {
+        return UNPRINTABLE;
+    }
+}
+/**
+ * Build process-level crash handlers for `brv mcp`.
+ *
+ * Each handler logs once and then exits with code 1. Every side effect is
+ * isolated in its own try/catch so a failing logger cannot re-fire the
+ * uncaughtException event. A module-instance re-entry flag adds defense in
+ * depth: once a crash is being handled, subsequent invocations short-circuit
+ * so `exit` is only called once.
+ *
+ * MCP clients (Claude Code / Cursor / Windsurf) respawn the server on demand,
+ * so log-and-exit is the protocol-correct behavior for this child process.
+ */
+export function createMcpCrashHandlers(deps) {
+    let crashed = false;
+    const handle = (label, value) => {
+        if (crashed)
+            return;
+        crashed = true;
+        const message = safeStack(value);
+        const stderrLine = `[brv-mcp] ${label}: ${message}\n`;
+        try {
+            deps.stderrWrite(stderrLine);
+        }
+        catch {
+            // stderr might be closed (EPIPE) when the parent has torn down stdio
+        }
+        try {
+            deps.fileWrite(`${deps.now().toISOString()} [${label}] ${message}\n`);
+        }
+        catch {
+            // crash log is best-effort; do not block exit on filesystem errors
+        }
+        try {
+            deps.exit(1);
+        }
+        catch {
+            // process.exit should not throw, but never let it break the handler
+        }
+    };
+    return {
+        onUncaughtException(error) {
+            handle('Uncaught exception', error);
+        },
+        onUnhandledRejection(reason) {
+            handle('Unhandled rejection', reason);
+        },
+    };
+}

package/dist/oclif/lib/task-client.d.ts

@@ -28,7 +28,7 @@ export interface TaskCompletionResult {
     /** Pending review notification from the server, present when review is required after task completion. */
     pendingReview?: {
         pendingCount: number;
-        reviewUrl: string;
+        reviewUrl?: string;
     };
     result?: string;
     taskId: string;
@@ -64,14 +64,12 @@ export interface WaitForTaskOptions {
     onResponse?: (content: string, taskId: string) => void;
     /** Task ID to wait for */
     taskId: string;
-    /** Timeout in ms (default: 5 minutes) */
-    timeoutMs?: number;
 }
-/** Default timeout for task completion (seconds) — shared across curate/query commands. */
+/** Default timeout for task completion (seconds) — kept for back-compat with the deprecated `--timeout` flag. */
 export declare const DEFAULT_TIMEOUT_SECONDS = 300;
-/** Minimum --timeout value accepted from the CLI (seconds). */
+/** Minimum --timeout value accepted from the CLI (seconds). Deprecated. */
 export declare const MIN_TIMEOUT_SECONDS = 10;
-/** Maximum --timeout value accepted from the CLI (seconds). */
+/** Maximum --timeout value accepted from the CLI (seconds). Deprecated. */
 export declare const MAX_TIMEOUT_SECONDS = 3600;
 /**
  * Format tool call for CLI display (simplified version of TUI formatToolDisplay).

package/dist/oclif/lib/task-client.js

@@ -4,14 +4,21 @@ import { ReviewEvents } from '../../shared/transport/events/review-events.js';
 import { writeJsonResponse } from './json-response.js';
 /** Grace period before treating 'reconnecting' as daemon death (ms) */
 const DISCONNECT_GRACE_MS = 10_000;
-/** Default timeout for task completion (seconds) — shared across curate/query commands. */
+/** Default timeout for task completion (seconds) — kept for back-compat with the deprecated `--timeout` flag. */
 export const DEFAULT_TIMEOUT_SECONDS = 300;
-/** Minimum --timeout value accepted from the CLI (seconds). */
+/** Minimum --timeout value accepted from the CLI (seconds). Deprecated. */
 export const MIN_TIMEOUT_SECONDS = 10;
-/** Maximum --timeout value accepted from the CLI (seconds). */
+/** Maximum --timeout value accepted from the CLI (seconds). Deprecated. */
 export const MAX_TIMEOUT_SECONDS = 3600;
-/** Default timeout for task completion (ms) */
-const DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_SECONDS * 1000;
+/**
+ * Maximum time the CLI tolerates without any task-scoped event before
+ * declaring the daemon stuck. Sized at ~3x the daemon's heartbeat
+ * interval (`TASK_HEARTBEAT_INTERVAL_MS = 10_000`) so a single missed
+ * heartbeat does not trigger a false positive.
+ */
+const STALE_THRESHOLD_MS = 30_000;
+/** How often the CLI re-checks `Date.now() - lastActivityAt`. */
+const STALE_CHECK_INTERVAL_MS = 5000;
 /**
  * Format tool call for CLI display (simplified version of TUI formatToolDisplay).
  */
@@ -58,13 +65,17 @@ export function formatToolDisplay(toolName, args) {
  * allowing withDaemonRetry to handle reconnection.
  */
 export function waitForTaskCompletion(options, log) {
-    const { client, command, format, onCompleted, onError, onResponse, taskId, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+    const { client, command, format, onCompleted, onError, onResponse, taskId } = options;
     const isText = format === 'text';
     return new Promise((resolve, reject) => {
         let completed = false;
         let disconnectTimer;
         const toolCalls = [];
         let pendingReview;
+        let lastActivityAt = Date.now();
+        const markActive = () => {
+            lastActivityAt = Date.now();
+        };
         const rejectRetryable = (message) => {
             if (completed)
                 return;
@@ -72,29 +83,66 @@ export function waitForTaskCompletion(options, log) {
             cleanup();
             reject(Object.assign(new Error(message), { code: TaskErrorCode.AGENT_DISCONNECTED }));
         };
-        const timeout = setTimeout(() => {
-            if (!completed) {
+        // Heartbeat-driven liveness watcher. The daemon emits
+        // `TaskEvents.HEARTBEAT` every ~10s during quiet periods and any
+        // other task-scoped event refreshes `lastActivityAt`. A single
+        // "Task timed out after Xs" misfire while the daemon was making
+        // progress is what M6 is replacing — when nothing arrives within
+        // ~30s the daemon really is stuck.
+        const staleCheckTimer = setInterval(() => {
+            if (completed)
+                return;
+            if (Date.now() - lastActivityAt > STALE_THRESHOLD_MS) {
                 completed = true;
                 cleanup();
-                const timeoutMessage = `Task timed out after ${timeoutMs / 1000}s`;
+                const message = 'Daemon is unresponsive on this task';
                 if (isText) {
-                    reject(new Error(timeoutMessage));
+                    reject(new Error(message));
                 }
                 else {
                     writeJsonResponse({
                         command,
-                        data: { event: 'error', message: timeoutMessage, status: 'error' },
+                        data: { event: 'error', message, status: 'error' },
                         success: false,
                     });
                     resolve();
                 }
             }
-        }, timeoutMs);
+        }, STALE_CHECK_INTERVAL_MS);
         const unsubscribers = [
+            // Heartbeat — keeps the stale-check alive during quiet phases.
+            client.on(TaskEvents.HEARTBEAT, (data) => {
+                if (data.taskId !== taskId)
+                    return;
+                markActive();
+            }),
+            // Cold-start liveness signals. The daemon emits `task:created`
+            // synchronously and `task:ack` after lifecycle hooks, both BEFORE
+            // the agent forks. `task:started` follows once the agent has
+            // booted and is the trigger for heartbeat registration. Without
+            // subscribing here, a cold start that exceeds `STALE_THRESHOLD_MS`
+            // before the first heartbeat (e.g. agent fork + provider RTTs on
+            // Windows under AV) falsely rejects as "Daemon is unresponsive".
+            client.on(TaskEvents.CREATED, (data) => {
+                if (data.taskId !== taskId)
+                    return;
+                markActive();
+            }),
+            client.on(TaskEvents.ACK, (data) => {
+                if (data.taskId !== taskId)
+                    return;
+                markActive();
+            }),
+            client.on(TaskEvents.STARTED, (data) => {
+                if (data.taskId !== taskId)
+                    return;
+                markActive();
+            }),
             // Tool call started (same as TUI addToolCall)
             client.on(LlmEvents.TOOL_CALL, (data) => {
-                if (!data.taskId)
+                if (data.taskId !== taskId)
                     return;
+                markActive();
                 toolCalls.push({
                     args: data.args,
                     callId: data.callId,
@@ -111,8 +159,9 @@ export function waitForTaskCompletion(options, log) {
             }),
             // Tool call completed (same as TUI updateToolCallResult)
             client.on(LlmEvents.TOOL_RESULT, (data) => {
-                if (!data.taskId)
+                if (data.taskId !== taskId)
                     return;
+                markActive();
                 let index = -1;
                 if (data.callId) {
                     index = toolCalls.findIndex((tc) => tc.callId === data.callId);
@@ -155,8 +204,9 @@ export function waitForTaskCompletion(options, log) {
             }),
             // Thinking started (same as TUI addReasoningContent)
             client.on(LlmEvents.THINKING, (data) => {
-                if (!data.taskId)
+                if (data.taskId !== taskId)
                     return;
+                markActive();
                 if (isText) {
                     log('  Thinking...');
                 }
@@ -169,14 +219,19 @@ export function waitForTaskCompletion(options, log) {
                 }
             }),
             // Streaming chunk (same as TUI appendStreamingContent) — silent for CLI
-            client.on(LlmEvents.CHUNK, () => {
+            client.on(LlmEvents.CHUNK, (data) => {
                 // Collected by TUI for streaming display; CLI doesn't render partial chunks
+                if (data.taskId !== taskId)
+                    return;
+                markActive();
             }),
             // LLM response (final answer — used by query command)
             client.on(LlmEvents.RESPONSE, (data) => {
-                if (!data.taskId || !onResponse)
+                if (data.taskId !== taskId)
                     return;
-                onResponse(data.content, data.taskId);
+                markActive();
+                if (onResponse)
+                    onResponse(data.content, data.taskId);
             }),
             // Pending review notification — emitted by server after curate completes with review-required ops
             client.on(ReviewEvents.NOTIFY, (data) => {
@@ -193,7 +248,7 @@ export function waitForTaskCompletion(options, log) {
                 // Prefer pendingReviewCount embedded in payload (set synchronously by server before task:completed).
                 // Falls back to review:notify capture for backward compatibility.
                 const resolvedPendingReview = payload.pendingReviewCount !== undefined && payload.pendingReviewCount > 0
-                    ? { pendingCount: payload.pendingReviewCount, reviewUrl: pendingReview?.reviewUrl ?? '' }
+                    ? { pendingCount: payload.pendingReviewCount, reviewUrl: pendingReview?.reviewUrl }
                     : pendingReview;
                 onCompleted({
                     durationMs: payload.durationMs,
@@ -222,6 +277,23 @@ export function waitForTaskCompletion(options, log) {
                     resolve();
                 }
             }),
+            // Task cancelled — terminal state, mirrors the daemon-side stop list
+            // in M6 T1. Dispose without rejecting so a user-cancelled task closes
+            // cleanly and no phantom "Daemon is unresponsive" fires afterward.
+            client.on(TaskEvents.CANCELLED, (payload) => {
+                if (payload.taskId !== taskId || completed)
+                    return;
+                completed = true;
+                cleanup();
+                if (!isText) {
+                    writeJsonResponse({
+                        command,
+                        data: { event: 'cancelled', status: 'cancelled', taskId },
+                        success: true,
+                    });
+                }
+                resolve();
+            }),
             // Connection state monitoring
             client.onStateChange((state) => {
                 if (completed)
@@ -243,7 +315,7 @@ export function waitForTaskCompletion(options, log) {
                     rejectRetryable('Daemon disconnected');
                 }
             }),
-            () => clearTimeout(timeout),
+            () => clearInterval(staleCheckTimer),
             () => {
                 if (disconnectTimer)
                     clearTimeout(disconnectTimer);

package/dist/oclif/lib/timeout-deprecation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Soft-drop helpers for the legacy `--timeout` flag on `brv curate`,
+ * `brv query`, and `brv dream`. The flag is kept accepted so existing
+ * scripts and CI jobs continue to run; passing it prints a one-line
+ * deprecation warning and no longer influences the wait-for-task
+ * wall-clock (M6 T3 removes the timer entirely).
+ */
+/**
+ * Help text that replaces the old per-flag description so `--help`
+ * surfaces the deprecation without breaking flag parsing.
+ */
+export declare const TIMEOUT_DEPRECATION_HELP = "(deprecated, no effect, kept for compatibility)";
+/**
+ * One-line stderr-friendly notice printed once per invocation when the
+ * user explicitly passed `--timeout`. Wording deliberately omits any
+ * specific setting key so M6 ships independently of M1/M2/M3 and
+ * survives setting renames (per M6 T2 AC).
+ */
+export declare const TIMEOUT_DEPRECATION_MESSAGE = "--timeout is deprecated and has no effect.";
+/**
+ * Calls `log(TIMEOUT_DEPRECATION_MESSAGE)` exactly once iff the user
+ * supplied a non-default value for `--timeout`. The flag's oclif
+ * `default:` populates `userValue` even when omitted, so the cheapest
+ * way to distinguish "user-passed" from "default-filled" is value
+ * comparison against the registered default.
+ */
+export declare function warnIfTimeoutFlagUsed(options: {
+    readonly defaultValue: number;
+    readonly log: (message: string) => void;
+    readonly userValue: number | undefined;
+}): void;

package/dist/oclif/lib/timeout-deprecation.js

@@ -0,0 +1,33 @@
+/**
+ * Soft-drop helpers for the legacy `--timeout` flag on `brv curate`,
+ * `brv query`, and `brv dream`. The flag is kept accepted so existing
+ * scripts and CI jobs continue to run; passing it prints a one-line
+ * deprecation warning and no longer influences the wait-for-task
+ * wall-clock (M6 T3 removes the timer entirely).
+ */
+/**
+ * Help text that replaces the old per-flag description so `--help`
+ * surfaces the deprecation without breaking flag parsing.
+ */
+export const TIMEOUT_DEPRECATION_HELP = '(deprecated, no effect, kept for compatibility)';
+/**
+ * One-line stderr-friendly notice printed once per invocation when the
+ * user explicitly passed `--timeout`. Wording deliberately omits any
+ * specific setting key so M6 ships independently of M1/M2/M3 and
+ * survives setting renames (per M6 T2 AC).
+ */
+export const TIMEOUT_DEPRECATION_MESSAGE = '--timeout is deprecated and has no effect.';
+/**
+ * Calls `log(TIMEOUT_DEPRECATION_MESSAGE)` exactly once iff the user
+ * supplied a non-default value for `--timeout`. The flag's oclif
+ * `default:` populates `userValue` even when omitted, so the cheapest
+ * way to distinguish "user-passed" from "default-filled" is value
+ * comparison against the registered default.
+ */
+export function warnIfTimeoutFlagUsed(options) {
+    if (options.userValue === undefined)
+        return;
+    if (options.userValue === options.defaultValue)
+        return;
+    options.log(TIMEOUT_DEPRECATION_MESSAGE);
+}