@bike4mind/cli 0.14.0 → 0.15.0

package/dist/index.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-import { $ as OAuthClient, A as substituteArguments, B as DEFAULT_THOROUGHNESS, C as WebSocketToolExecutor, D as ServerLlmBackend, E as WebSocketLlmBackend, F as generateCliTools, G as buildSystemPrompt, H as registerFeatureModuleTools, I as ALWAYS_DENIED_FOR_AGENTS, J as ReActAgent, K as buildSkillsPromptSection, L as DEFAULT_AGENT_MODEL, M as extractCompactInstructions, N as loadContextFiles, O as isTransientNetworkError, P as PermissionManager, Q as SessionStore, R as DEFAULT_MAX_ITERATIONS, S as ApiClient, T as FallbackLlmBackend, U as setWebSocketToolExecutor, V as clearFeatureModuleTools, W as getPlanModeFilePath, X as CheckpointStore, Y as CustomCommandStore, Z as CommandHistoryStore, _ as createAgentDelegateTool, a as createBlockerTools, at as searchFiles, b as createSkillTool, c as createDecisionStore, d as createFindDefinitionTool, et as hasFileReferences, f as createTodoStore, g as BackgroundAgentManager, h as createBackgroundAgentTools, i as createBlockerStore, it as formatFileSize, j as formatStep, k as McpManager, l as formatDecisionsOutput, m as createCoordinateTaskTool, n as createReviewGateTool, nt as searchCommands, o as formatBlockersOutput, ot as warmFileCache, p as createWriteTodosTool, q as isReadOnlyTool, r as formatReviewGatesOutput, rt as mergeCommands, s as createDecisionLogTool, t as createReviewGateStore, tt as processFileReferences, u as createGetFileStructureTool, v as AgentStore, w as WebSocketConnectionManager, x as parseAgentConfig, y as SubagentOrchestrator, z as DEFAULT_RETRY_CONFIG } from "./tools-BTPUXUNS.mjs";
+import { $ as OAuthClient, A as substituteArguments, B as DEFAULT_THOROUGHNESS, C as WebSocketToolExecutor, D as ServerLlmBackend, E as WebSocketLlmBackend, F as generateCliTools, G as buildSystemPrompt, H as registerFeatureModuleTools, I as ALWAYS_DENIED_FOR_AGENTS, J as ReActAgent, K as buildSkillsPromptSection, L as DEFAULT_AGENT_MODEL, M as extractCompactInstructions, N as loadContextFiles, O as isTransientNetworkError, P as PermissionManager, Q as SessionStore, R as DEFAULT_MAX_ITERATIONS, S as ApiClient, T as FallbackLlmBackend, U as setWebSocketToolExecutor, V as clearFeatureModuleTools, W as getPlanModeFilePath, X as CheckpointStore, Y as CustomCommandStore, Z as CommandHistoryStore, _ as createAgentDelegateTool, a as createBlockerTools, at as searchFiles, b as createSkillTool, c as createDecisionStore, d as createFindDefinitionTool, et as hasFileReferences, f as createTodoStore, g as BackgroundAgentManager, h as createBackgroundAgentTools, i as createBlockerStore, it as formatFileSize, j as formatStep, k as McpManager, l as formatDecisionsOutput, m as createCoordinateTaskTool, n as createReviewGateTool, nt as searchCommands, o as formatBlockersOutput, ot as warmFileCache, p as createWriteTodosTool, q as isReadOnlyTool, r as formatReviewGatesOutput, rt as mergeCommands, s as createDecisionLogTool, t as createReviewGateStore, tt as processFileReferences, u as createGetFileStructureTool, v as AgentStore, w as WebSocketConnectionManager, x as parseAgentConfig, y as SubagentOrchestrator, z as DEFAULT_RETRY_CONFIG } from "./tools-ChYlNt33.mjs";
 import { n as useCliStore, t as selectActiveBackgroundAgents } from "./store-DV5s-qni.mjs";
-import { Ut as validateJupyterKernelName, Wt as validateNotebookPath$1, g as CREDIT_DEDUCT_TRANSACTION_TYPES, i as getEnvironmentName, n as logger, r as getApiUrl, t as ConfigStore, v as ChatModels } from "./ConfigStore-B9I7UHuG.mjs";
-import { t as version } from "./package-uvIC6spW.mjs";
+import { Gt as validateNotebookPath$1, Wt as validateJupyterKernelName, g as CREDIT_DEDUCT_TRANSACTION_TYPES, i as getEnvironmentName, n as logger, r as getApiUrl, t as ConfigStore, v as ChatModels } from "./ConfigStore-HRgwfPBk.mjs";
+import { t as version } from "./package-CaPvuP1F.mjs";
 import { r as checkForUpdate } from "./updateChecker-C8xsNY2L.mjs";
 import React, { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
 import { Box, Static, Text, render, useApp, useInput, usePaste, useStdout } from "ink";
-import { execSync } from "child_process";
+import { execSync, spawn } from "child_process";
 import { randomBytes, randomUUID } from "crypto";
 import { existsSync, promises, readFileSync, statSync } from "fs";
 import { homedir } from "os";
@@ -2839,6 +2839,190 @@ function injectHandoffMessage(messages, handoff) {
 		timestamp: (/* @__PURE__ */ new Date()).toISOString()
 	}, ...messages.filter((m) => !isInjectedHandoff(m))];
 }
+const LOCAL_HANDOFF_MESSAGE_CHARS = 1500;
+/**
+* Build a SessionHandoff purely from local session state, without any LLM
+* call. The fields are populated directly from workflow state — no synthesis,
+* no narrative summary. This is the structural fallback when the LLM is
+* unreachable (rate-limit, network, auth, upstream outage).
+*
+* The shape matches the LLM-generated handoff so callers can persist it in
+* `session.metadata.workflow.handoff` interchangeably.
+*
+* `workflowOverride` lets callers pass the authoritative decision/blocker
+* arrays (typically from in-memory ref stores) when `session.metadata.workflow`
+* may not yet have been synced from those refs. Without it, the handoff would
+* reflect a stale snapshot while `applyHandoffToWorkflow` writes the fresh
+* refs — leaving the handoff and the surrounding workflow object out of sync.
+*/
+function buildLocalHandoff(session, workflowOverride) {
+	const workflow = session.metadata.workflow;
+	const decisions = workflowOverride?.decisions ?? workflow?.decisions ?? [];
+	const openBlockers = (workflowOverride?.blockers ?? workflow?.blockers ?? []).filter((b) => b.status === "open");
+	return {
+		summary: `Local handoff for session "${session.name}" (${session.messages.length} messages, model ${session.model}). Generated from session state without an LLM call — no narrative synthesis.`,
+		keyFindings: [],
+		nextSteps: [],
+		pendingDecisions: decisions.map((d) => `${d.summary} (rationale: ${d.rationale})`),
+		blockers: openBlockers.map((b) => b.description),
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+/**
+* Render a full Markdown handoff document from session state. Includes
+* session metadata, all decisions and open blockers verbatim, the last
+* `LOCAL_HANDOFF_MESSAGE_TAIL` messages role-labeled and lightly truncated,
+* and a pointer to the on-disk session JSON for deeper context.
+*
+* If `session.metadata.workflow.handoff` is set (either from an LLM-generated
+* synthesis or from `buildLocalHandoff`), its narrative sections are rendered
+* at the top — so both code paths produce a single uniform artifact.
+*
+* Used as the durable artifact for `/handoff` (both LLM-backed and
+* `--local`) and for the auto-fallback when the LLM is unreachable.
+*/
+function renderLocalHandoffMarkdown(session, sessionJsonPath) {
+	const workflow = session.metadata.workflow;
+	const decisions = workflow?.decisions ?? [];
+	const openBlockers = (workflow?.blockers ?? []).filter((b) => b.status === "open");
+	const resolvedBlockers = (workflow?.blockers ?? []).filter((b) => b.status === "resolved");
+	const tail = session.messages.filter((m) => !isInjectedHandoff(m)).slice(-20);
+	const handoff = workflow?.handoff;
+	const lines = [];
+	lines.push(`# Session handoff: ${session.name}`);
+	lines.push("");
+	lines.push("Durable artifact for resuming this session elsewhere. Captures any synthesized handoff plus decisions, open blockers, and the tail of the conversation verbatim.");
+	lines.push("");
+	if (handoff) {
+		lines.push("## Synthesized handoff");
+		lines.push("");
+		lines.push(handoff.summary);
+		lines.push("");
+		appendMarkdownSection(lines, "Key findings", handoff.keyFindings);
+		appendMarkdownSection(lines, "Next steps", handoff.nextSteps);
+		appendMarkdownSection(lines, "Pending decisions", handoff.pendingDecisions);
+		appendMarkdownSection(lines, "Blockers", handoff.blockers);
+		lines.push(`_Generated at ${handoff.generatedAt}._`);
+		lines.push("");
+	}
+	lines.push("## Session metadata");
+	lines.push("");
+	lines.push(`- **Session ID:** \`${session.id}\``);
+	lines.push(`- **Model:** ${session.model}`);
+	lines.push(`- **Created:** ${session.createdAt}`);
+	lines.push(`- **Updated:** ${session.updatedAt}`);
+	lines.push(`- **Messages:** ${session.messages.length}`);
+	lines.push(`- **Tool calls:** ${session.metadata.toolCallCount}`);
+	lines.push(`- **Total cost:** $${session.metadata.totalCost.toFixed(4)}`);
+	lines.push(`- **Generated:** ${(/* @__PURE__ */ new Date()).toISOString()}`);
+	if (sessionJsonPath) lines.push(`- **Full session JSON:** \`${sessionJsonPath}\``);
+	lines.push("");
+	lines.push(`## Decisions (${decisions.length})`);
+	lines.push("");
+	if (decisions.length === 0) lines.push("_No decisions logged._");
+	else for (const d of decisions) {
+		lines.push(`### ${d.summary}`);
+		lines.push("");
+		lines.push(`- **Rationale:** ${d.rationale}`);
+		if (d.alternatives && d.alternatives.length > 0) lines.push(`- **Alternatives considered:** ${d.alternatives.join("; ")}`);
+		if (d.context) lines.push(`- **Context:** ${d.context}`);
+		lines.push(`- **Logged at:** ${d.timestamp}`);
+		lines.push("");
+	}
+	lines.push(`## Open blockers (${openBlockers.length})`);
+	lines.push("");
+	if (openBlockers.length === 0) lines.push("_No open blockers._");
+	else for (const b of openBlockers) lines.push(`- ${b.description} _(opened ${b.createdAt})_`);
+	lines.push("");
+	if (resolvedBlockers.length > 0) {
+		lines.push(`## Resolved blockers (${resolvedBlockers.length})`);
+		lines.push("");
+		for (const b of resolvedBlockers) {
+			const resolution = b.resolution ? ` → ${b.resolution}` : "";
+			lines.push(`- ${b.description}${resolution}`);
+		}
+		lines.push("");
+	}
+	lines.push(`## Last ${tail.length} messages`);
+	lines.push("");
+	if (tail.length === 0) lines.push("_No conversation messages._");
+	else for (const msg of tail) {
+		const role = ROLE_LABELS[msg.role] || "System";
+		const content = msg.content.length > LOCAL_HANDOFF_MESSAGE_CHARS ? msg.content.slice(0, LOCAL_HANDOFF_MESSAGE_CHARS) + "\n\n_...[truncated]_" : msg.content;
+		lines.push(`### ${role} — ${msg.timestamp}`);
+		lines.push("");
+		lines.push(content);
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+function appendMarkdownSection(lines, heading, items) {
+	if (items.length === 0) return;
+	lines.push(`**${heading}:**`);
+	lines.push("");
+	for (const item of items) lines.push(`- ${item}`);
+	lines.push("");
+}
+function defaultLocalHandoffDir() {
+	return path.join(homedir(), ".bike4mind", "handoffs");
+}
+function buildLocalHandoffFileName(session, now) {
+	const stamp = now.toISOString().replace(/[:.]/g, "-");
+	return `${session.id}-${stamp}.md`;
+}
+/**
+* Write a local handoff Markdown file to `~/.bike4mind/handoffs/` and return
+* the absolute path. Creates the directory if missing. The session JSON path
+* is embedded in the markdown so the user (or another agent) can locate the
+* full session for deeper context.
+*
+* `dir` is overridable for tests.
+*/
+async function writeLocalHandoffFile(session, options = {}) {
+	const dir = options.dir ?? defaultLocalHandoffDir();
+	const now = options.now ?? /* @__PURE__ */ new Date();
+	const sessionJsonPath = options.sessionJsonPath ?? path.join(homedir(), ".bike4mind", "sessions", `${session.id}.json`);
+	await promises.mkdir(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const filePath = path.join(dir, buildLocalHandoffFileName(session, now));
+	const markdown = renderLocalHandoffMarkdown(session, sessionJsonPath);
+	await promises.writeFile(filePath, markdown, {
+		encoding: "utf-8",
+		mode: 384
+	});
+	return filePath;
+}
+/**
+* True if an error from the LLM completion path indicates the network call
+* itself could not complete — rate limit, network drop, auth failure, or
+* upstream outage. Used to decide when to auto-fall back to the local
+* (LLM-free) handoff path.
+*
+* Conservative on purpose: a malformed-response or parse error from a server
+* that *did* answer is NOT an LLM-unavailable condition — the user can retry,
+* and falling back would mask a real bug.
+*
+* Keep the substring matches below in sync with the error strings thrown by
+* `apps/cli/src/llm/ServerLlmBackend.ts` (see its catch block around the
+* `Request failed with status` / `Authentication ...` / `Cannot connect ...`
+* / `Failed to complete LLM request` throws). Renames there will silently
+* break the auto-fallback — a typed error hierarchy would be a more robust
+* long-term fix.
+*
+* Note on 403: ServerLlmBackend throws `403 Forbidden: <details>` for
+* WAF/server-blocked requests. We deliberately do NOT classify these as
+* unavailable — a 403 typically means the user needs to take action
+* (re-auth, contact support, fix WAF rule) and silently degrading would
+* mask that. Real auth failures already surface via the `Authentication ...`
+* messages above. Add 403 here only if a concrete use case warrants it.
+*/
+function isLlmUnavailableError(error) {
+	if (!(error instanceof Error)) return false;
+	const message = error.message;
+	return message.includes("Rate limit exceeded") || message.includes("Authentication expired") || message.includes("Authentication failed") || message.includes("Cannot connect to Bike4Mind server") || message.includes("ECONNREFUSED") || message.includes("ETIMEDOUT") || message.includes("ENOTFOUND") || message.includes("ECONNRESET") || message.includes("Failed to complete LLM request") || /Request failed with status 5\d\d/.test(message) || /^5\d\d\b/.test(message);
+}
 //#endregion
 //#region src/utils/compaction.ts
 /**
@@ -3622,6 +3806,106 @@ var MultiLlmBackend = class {
 	}
 };
 //#endregion
+//#region src/utils/peonNotifier.ts
+/**
+* peon-ping notifier — native b4m adapter for peon-ping (https://peonping.com).
+*
+* peon-ping plays game-character voice lines + on-screen banners when an AI
+* coding agent finishes a turn or needs attention. It consumes a small JSON
+* event on stdin (the "CESP" hook contract shared by Claude Code and every
+* peon-ping adapter):
+*
+*   { hook_event_name, notification_type, cwd, session_id, permission_mode }
+*
+* This module is the b4m CLI's equivalent of the shell adapters peon-ping
+* ships for other IDEs (see `adapters/openclaw.sh`), except it runs in-process
+* and is wired directly to the CLI's lifecycle via a store subscription.
+*
+* Behaviour is auto-detect: if a `peon.sh` is found on disk it is enabled,
+* otherwise every call is a silent no-op. Set `B4M_PEON_PING=0` to force it
+* off even when installed.
+*/
+/**
+* Resolve the path to `peon.sh`, checking the same locations peon-ping's own
+* adapters use. Returns null when peon-ping is not installed. Resolved once and
+* cached: `null` means "looked and found nothing".
+*/
+let resolvedScript;
+function findPeonScript() {
+	if (resolvedScript !== void 0) return resolvedScript;
+	const claudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(homedir(), ".claude");
+	resolvedScript = [
+		process.env.CLAUDE_PEON_DIR ? path.join(process.env.CLAUDE_PEON_DIR, "peon.sh") : null,
+		path.join(claudeDir, "hooks", "peon-ping", "peon.sh"),
+		path.join(homedir(), ".openpeon", "peon.sh")
+	].filter((p) => p !== null).find((p) => existsSync(p)) ?? null;
+	return resolvedScript;
+}
+/** Explicit off-switch via env, even when peon-ping is installed. */
+function isDisabledByEnv() {
+	const v = process.env.B4M_PEON_PING?.toLowerCase();
+	return v === "0" || v === "false" || v === "off";
+}
+/** True when peon-ping is installed and not disabled. */
+function isPeonAvailable() {
+	return !isDisabledByEnv() && findPeonScript() !== null;
+}
+/**
+* Fire a single peon-ping event. Fire-and-forget and fail-safe: the child is
+* detached and unref'd, all output is discarded, and any spawn error is logged
+* to the debug log but never surfaced — the CLI must never break because of a
+* missing or misbehaving peon install.
+*/
+function notifyPeon(event, options = {}) {
+	if (isDisabledByEnv()) return;
+	const script = findPeonScript();
+	if (!script) return;
+	const payload = JSON.stringify({
+		hook_event_name: event,
+		notification_type: options.notificationType ?? "",
+		cwd: process.cwd(),
+		session_id: useCliStore.getState().session?.id ?? `b4m-${process.pid}`,
+		permission_mode: ""
+	});
+	try {
+		const child = spawn("bash", [script], {
+			stdio: [
+				"pipe",
+				"ignore",
+				"ignore"
+			],
+			detached: true
+		});
+		child.on("error", (err) => logger.debug(`peon-ping spawn failed: ${err.message}`));
+		child.stdin?.on("error", () => {});
+		child.stdin?.end(payload);
+		child.unref();
+	} catch (err) {
+		logger.debug(`peon-ping notify error: ${err.message}`);
+	}
+}
+/**
+* Subscribe to CLI lifecycle and emit peon-ping events:
+* - `Stop` when the agent finishes a turn (isThinking true → false)
+* - `Notification` (permission_prompt) when a permission / user-question /
+*   review-gate prompt first appears and the user needs to act
+*
+* Fires `SessionStart` immediately. Returns an unsubscribe function; call it
+* (and pass `emitSessionEnd`) on exit to emit `SessionEnd`.
+*/
+function startPeonNotifier() {
+	if (!isPeonAvailable()) return () => {};
+	notifyPeon("SessionStart");
+	return useCliStore.subscribe((state, prev) => {
+		if (prev.isThinking && !state.isThinking) notifyPeon("Stop");
+		if (!prev.permissionPrompt && !!state.permissionPrompt || !prev.userQuestionPrompt && !!state.userQuestionPrompt || !prev.reviewGatePrompt && !!state.reviewGatePrompt) notifyPeon("Notification", { notificationType: "permission_prompt" });
+	});
+}
+/** Emit `SessionEnd`. Call on CLI exit. */
+function emitPeonSessionEnd() {
+	notifyPeon("SessionEnd");
+}
+//#endregion
 //#region src/agents/dynamicAgentTool.ts
 /**
 * Create the create_dynamic_agent tool
@@ -6484,6 +6768,13 @@ function CliApp() {
 	useEffect(() => {
 		init();
 	}, [init]);
+	useEffect(() => {
+		const unsubscribe = startPeonNotifier();
+		return () => {
+			unsubscribe();
+			emitPeonSessionEnd();
+		};
+	}, []);
 	const handleMessageRef = useRef(null);
 	const abortControllerRef = useRef(state.abortController);
 	abortControllerRef.current = state.abortController;
@@ -7179,12 +7470,71 @@ function CliApp() {
 		}
 	};
 	/**
+	* Apply `handoff` to the session's workflow state, pulling the latest
+	* decisions/blockers/review-gates from their stores. Centralizes the
+	* workflow assembly so the LLM-backed path and the local fallback path
+	* cannot drift apart on which fields land on `session.metadata.workflow`.
+	*/
+	const applyHandoffToWorkflow = (session, handoff) => {
+		session.metadata.workflow = {
+			decisions: decisionStoreRef.current.decisions,
+			blockers: blockerStoreRef.current.blockers,
+			handoff,
+			reviewGates: reviewGateStoreRef.current.reviewGates
+		};
+	};
+	/**
+	* Best-effort write of the Markdown handoff artifact to
+	* `~/.bike4mind/handoffs/`. Returns the file path on success, null on
+	* filesystem failure — callers should not block on this.
+	*
+	* Reads `session.metadata.workflow.handoff` to include the narrative
+	* synthesis section (if any), so this works uniformly for both the
+	* LLM-backed path and the local fallback path — see issue #8806.
+	*/
+	const writeHandoffMarkdown = async (session) => {
+		try {
+			return await writeLocalHandoffFile(session);
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			logger.debug(`Handoff markdown write failed: ${reason}`);
+			return null;
+		}
+	};
+	/**
+	* Build a handoff purely from local session state — no LLM call. Mutates
+	* the session's workflow state with the local handoff and writes a Markdown
+	* file to `~/.bike4mind/handoffs/`.
+	*
+	* Used both as the explicit `--local` path and as the auto-fallback when
+	* the LLM is unreachable (rate limit, network, auth) — see issue #8806.
+	*/
+	const writeLocalFallbackHandoff = async (session) => {
+		const handoff = buildLocalHandoff(session, {
+			decisions: decisionStoreRef.current.decisions,
+			blockers: blockerStoreRef.current.blockers
+		});
+		applyHandoffToWorkflow(session, handoff);
+		const filePath = await writeHandoffMarkdown(session);
+		if (!filePath) return null;
+		return {
+			handoff,
+			filePath
+		};
+	};
+	/**
 	* Generate a structured session handoff via a single LLM call and persist it
 	* onto the session's workflow state. Returns the handoff on success, or null
-	* if generation was skipped (short session) or failed (parse / agent error).
+	* if generation was skipped (short session) or failed unrecoverably.
+	*
+	* If the LLM is unavailable (rate-limit, network, auth, upstream outage),
+	* automatically falls back to a local handoff written to disk so the user
+	* always has a usable artifact — see issue #8806. Falling back is silent at
+	* the data layer; the caller surfaces the path to the user.
 	*
-	* Failures are best-effort and surfaced as a warning rather than thrown —
-	* the surrounding /save flow must not block on handoff generation.
+	* Other failures (parse errors, short sessions) are best-effort and surfaced
+	* as warnings rather than thrown — the surrounding /save flow must not block
+	* on handoff generation.
 	*
 	* Callers are responsible for saving the session afterwards.
 	*/
@@ -7202,17 +7552,27 @@ function CliApp() {
 				logger.debug(`Handoff response: ${result.finalAnswer.slice(0, 500)}`);
 				return null;
 			}
-			session.metadata.workflow = {
-				decisions: decisionStoreRef.current.decisions,
-				blockers: blockerStoreRef.current.blockers,
+			applyHandoffToWorkflow(session, handoff);
+			return {
 				handoff,
-				reviewGates: reviewGateStoreRef.current.reviewGates
+				filePath: await writeHandoffMarkdown(session),
+				source: "llm"
 			};
-			return handoff;
 		} catch (err) {
 			const reason = err instanceof Error ? err.message : String(err);
-			console.warn(`⚠️  Handoff generation failed: ${reason}`);
 			logger.debug(`Handoff generation error: ${reason}`);
+			if (isLlmUnavailableError(err)) {
+				console.warn(`⚠️  LLM unavailable for handoff generation: ${reason}`);
+				const local = await writeLocalFallbackHandoff(session);
+				if (local) return {
+					handoff: local.handoff,
+					filePath: local.filePath,
+					source: "local-fallback"
+				};
+				console.warn("⚠️  Local handoff fallback also failed; no handoff produced.");
+				return null;
+			}
+			console.warn(`⚠️  Handoff generation failed: ${reason}`);
 			return null;
 		} finally {
 			useCliStore.getState().setIsThinking(false);
@@ -7258,9 +7618,12 @@ function CliApp() {
 			}, EXIT_HANDOFF_PROMPT_TIMEOUT_MS);
 		})) return;
 		try {
-			if (await generateHandoff(session)) {
+			const result = await generateHandoff(session);
+			if (result) {
 				await state.sessionStore.save(session);
-				console.log("🤝 Handoff generated.");
+				const label = result.source === "local-fallback" ? "Local handoff written (LLM unavailable)" : "Handoff generated";
+				if (result.filePath) console.log(`🤝 ${label}. File: ${result.filePath}`);
+				else console.log(`🤝 ${label}.`);
 			}
 		} catch (err) {
 			const reason = err instanceof Error ? err.message : String(err);
@@ -7297,19 +7660,39 @@ function CliApp() {
 	};
 	/**
 	* Show the existing handoff or generate a fresh one. Shared by `/handoff` and
-	* `/workflow handoff`. Pass `['generate']` (or `['regen']`) to force regeneration.
+	* `/workflow handoff`. Subcommands:
+	*   - `generate` / `regen` — force regeneration via the LLM (auto-falls back
+	*     to a local handoff if the LLM is unreachable; see issue #8806).
+	*   - `--local` flag — skip the LLM entirely and write a local handoff file
+	*     from session state. The recovery path for when the user is
+	*     rate-limited or offline.
 	*/
 	const runHandoffCommand = async (args) => {
 		if (!state.session) {
 			console.log("No active session");
 			return;
 		}
+		const wantsLocal = args.includes("--local");
+		const filteredArgs = args.filter((a) => a !== "--local");
 		const existing = state.session.metadata.workflow?.handoff;
-		const wantsRegen = args[0] === "generate" || args[0] === "regen";
+		const wantsRegen = filteredArgs[0] === "generate" || filteredArgs[0] === "regen" || wantsLocal;
 		if (existing && !wantsRegen) {
 			console.log("\n🤝 Session handoff\n");
 			console.log(formatHandoffOutput(existing));
-			console.log("Run /handoff generate to refresh.\n");
+			console.log("Run /handoff generate to refresh, or /handoff --local for an LLM-free snapshot.\n");
+			return;
+		}
+		if (wantsLocal) {
+			const local = await writeLocalFallbackHandoff(state.session);
+			if (!local) {
+				console.log("❌ Failed to write local handoff");
+				return;
+			}
+			await state.sessionStore.save(state.session);
+			console.log("\n🤝 Local session handoff (no LLM call)\n");
+			console.log(formatHandoffOutput(local.handoff));
+			console.log(`\n📄 Local handoff written to ${local.filePath}`);
+			console.log("✅ Session saved with local handoff");
 			return;
 		}
 		if (state.session.messages.length < 4) {
@@ -7320,15 +7703,17 @@ function CliApp() {
 			console.log("Cannot generate handoff: no active agent");
 			return;
 		}
-		const handoff = await generateHandoff(state.session);
-		if (!handoff) {
-			console.log("❌ Failed to generate handoff");
+		const result = await generateHandoff(state.session);
+		if (!result) {
+			console.log("❌ Failed to generate handoff. Try /handoff --local for an LLM-free snapshot.");
 			return;
 		}
 		await state.sessionStore.save(state.session);
-		console.log("\n🤝 Session handoff\n");
-		console.log(formatHandoffOutput(handoff));
-		console.log("\n✅ Session saved with refreshed handoff");
+		const fellBack = result.source === "local-fallback";
+		console.log(fellBack ? "\n🤝 Local session handoff (LLM unavailable)\n" : "\n🤝 Session handoff\n");
+		console.log(formatHandoffOutput(result.handoff));
+		if (result.filePath) console.log(`\n📄 Handoff written to ${result.filePath}`);
+		console.log(fellBack ? "✅ Session saved with local fallback handoff" : "✅ Session saved with refreshed handoff");
 	};
 	const handleCommand = async (command, args) => {
 		const customCommand = state.customCommandStore.getCommand(command);
@@ -7472,10 +7857,14 @@ Multi-line Input:
 					handoff: state.session.metadata.workflow?.handoff,
 					reviewGates: reviewGateStoreRef.current.reviewGates
 				};
-				const handoff = await generateHandoff(state.session);
+				const handoffResult = await generateHandoff(state.session);
 				await state.sessionStore.save(state.session);
 				console.log(`✅ Session saved as "${sessionName}"`);
-				if (handoff) console.log("🤝 Session handoff generated");
+				if (handoffResult) {
+					const label = handoffResult.source === "local-fallback" ? "Local handoff written (LLM unavailable)" : "Session handoff generated";
+					if (handoffResult.filePath) console.log(`🤝 ${label}. File: ${handoffResult.filePath}`);
+					else console.log(`🤝 ${label}`);
+				}
 				break;
 			}
 			case "resume":

package/dist/{package-uvIC6spW.mjs → package-CaPvuP1F.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 //#region package.json
-var version = "0.14.0";
+var version = "0.15.0";
 //#endregion
 export { version as t };