@pellux/goodvibes-tui 1.16.0 → 1.17.0

package/src/input/commands/schedule-runtime.ts

@@ -10,6 +10,7 @@ import type { AutomationManager } from '@pellux/goodvibes-sdk/platform/automatio
 import type { AutomationJob } from '@pellux/goodvibes-sdk/platform/automation';
 import type { AutomationScheduleDefinition } from '@pellux/goodvibes-sdk/platform/automation';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { buildAutomationEmptyState } from '@pellux/goodvibes-sdk/platform/runtime/feature-announcements';
 import { parseNaturalLanguageSchedule } from './schedule-nl.ts';
 import type {
   AutomationExecutionPolicy,
@@ -106,13 +107,19 @@ export function registerScheduleRuntimeCommands(registry: CommandRegistry): void
       if (!sub || sub === 'list') {
         const jobs = manager.listJobs();
         if (jobs.length === 0) {
-          ctx.print(
-            'No automation jobs.\n'
-            + 'Use:\n'
-            + '  /schedule add cron "*/30 * * * *" "check build status"\n'
-            + '  /schedule add every 15m "summarize open PRs"\n'
-            + '  /schedule add at 2026-04-10T09:00:00 "send release reminder"'
-          );
+          // The SDK owns the presence + title of the how-to-create-your-first-
+          // routine empty state (shown while automation is on and idle). Its
+          // body points at a command name this registry doesn't have, so we
+          // render its title with THIS surface's real /schedule commands — a
+          // command pointer that actually exists in the registry.
+          const emptyState = buildAutomationEmptyState({ enabled: true, routineCount: jobs.length });
+          ctx.print([
+            emptyState ? emptyState.title : 'No automation jobs.',
+            'Automation is on and idle. Create your first routine with:',
+            '  /schedule add cron "*/30 * * * *" "check build status"',
+            '  /schedule add every 15m "summarize open PRs"',
+            '  /schedule add at 2026-04-10T09:00:00 "send release reminder"',
+          ].join('\n'));
           return;
         }
         const lines = ['Automation jobs:', ''];

package/src/input/commands/services-runtime.ts

@@ -16,7 +16,7 @@ export function registerServicesRuntimeCommands(registry: CommandRegistry): void
       const sub = args[0] ?? 'open';
       const shellPaths = requireShellPaths(ctx);
       if (sub === 'open' || sub === 'panel') {
-        ctx.openModal?.('services-modal'); // W6.1: services panel -> config modal
+        ctx.openModal?.('services-modal'); // services panel -> config modal
         return;
       }
       const svcRegistry = requireServiceRegistry(ctx);

package/src/input/commands/session-workflow.ts

@@ -89,7 +89,7 @@ export function reopenPanelsFromReturnContext(ctx: CommandContext, summary: Sess
   const reopened: string[] = [];
   const movedToModal: string[] = [];
   for (const panelId of summary.openPanels.slice(0, 4)) {
-    // W6.1 (the purge): a MIGRATE-TO-MODAL id has no panel to restore — a modal
+    // (the purge): a MIGRATE-TO-MODAL id has no panel to restore — a modal
     // is not part of the saved panel layout. Skip it (don't pop a modal
     // mid-resume) and note it once, rather than firing openModal + revealing an
     // empty workspace during resume.
@@ -283,7 +283,7 @@ export async function handleSessionWorkflowCommand(args: string[], ctx: CommandC
         },
       });
       // Hydrate the footer's token counters from the resumed (+ journal-replayed)
-      // history now, before ctx.renderRequest() below (W0.9).
+      // history now, before ctx.renderRequest() below.
       ctx.session.hydrateSessionUsage?.();
 
       if (meta.model) {

package/src/input/commands/settings-sync-runtime.ts

@@ -32,7 +32,7 @@ export function registerSettingsSyncRuntimeCommands(registry: CommandRegistry):
       const shellPaths = requireShellPaths(ctx);
       const controlPlaneConfigDir = ctx.platform.configManager.getControlPlaneConfigDir();
       const sub = (args[0] ?? '').toLowerCase();
-      // DEBT-5 item 3 (report-vs-modal front doors): settings-sync has a full
+      // item 3 (report-vs-modal front doors): settings-sync has a full
       // modal surface (settings-sync-modal), so the bare command now opens it
       // — the old bare/`review` transcript report moved to an explicit
       // `report` subcommand (scriptability preserved: /settings-sync report).
@@ -41,7 +41,7 @@ export function registerSettingsSyncRuntimeCommands(registry: CommandRegistry):
         return;
       }
       if (sub === 'panel' || sub === 'open') {
-        ctx.openModal?.('settings-sync-modal'); // W6.1: settings-sync panel -> config modal
+        ctx.openModal?.('settings-sync-modal'); // settings-sync panel -> config modal
         return;
       }
       if (sub === 'report' || sub === 'review') {

package/src/input/commands/share-runtime.ts

@@ -115,7 +115,7 @@ export function registerShareRuntimeCommands(registry: CommandRegistry): void {
       );
       // The exported document has no field for "this cost is a placeholder" —
       // omit `cost` entirely rather than embed a misleading 0 when the model
-      // never resolved to a real price (WO-315).
+      // never resolved to a real price.
       const costIsUnpriced = !isModelPriced(sessionModel);
       if (costIsUnpriced) {
         ctx.print(`Note: cost omitted from export — no pricing data for model "${sessionModel}".`);

package/src/input/commands/shell-core.ts

@@ -6,6 +6,7 @@ import { executeWriteQuit } from './quit-shared.ts';
 import { compactConversation, requireKeybindingsManager, requireProviderApi, requireSessionMemoryStore } from './runtime-services.ts';
 import { buildCompactionPreview, buildCompactionAfterNotice, buildPinUsageText, buildPinSuccessText } from '../../renderer/compaction-preview.ts';
 import { buildCompactionHistoryText } from '../../renderer/compaction-history-modal.ts';
+import { ensureProviderKeyThenSelect } from '../provider-key-intake.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
@@ -32,11 +33,15 @@ export function registerShellCoreCommands(registry: CommandRegistry): void {
         const modelId = args[0];
         try {
           const selected = await providerApi.selectModel(modelId);
-          ctx.session.runtime.model = selected.registryKey;
-          ctx.session.runtime.provider = selected.providerId;
-          ctx.platform.configManager.set('provider.model', selected.registryKey);
-          ctx.print(`Switched to model: ${selected.displayName} (${selected.providerId})`);
-          void providerApi.recordModelUsage(selected.registryKey).catch((err) => { logger.debug('model usage record failed', { err }); });
+          // Capture the key for an unconfigured provider inline before the
+          // selection is announced, so the switch lands ready to chat.
+          ensureProviderKeyThenSelect(ctx, selected.providerId, () => {
+            ctx.session.runtime.model = selected.registryKey;
+            ctx.session.runtime.provider = selected.providerId;
+            ctx.platform.configManager.set('provider.model', selected.registryKey);
+            ctx.print(`Switched to model: ${selected.displayName} (${selected.providerId})`);
+            void providerApi.recordModelUsage(selected.registryKey).catch((err) => { logger.debug('model usage record failed', { err }); });
+          });
         } catch (e) {
           ctx.print(`Error: ${summarizeError(e)}`);
         }
@@ -112,75 +117,48 @@ export function registerShellCoreCommands(registry: CommandRegistry): void {
   registry.register({
     name: 'help',
     aliases: ['h', '?'],
-    description: 'Show available commands and keyboard shortcuts',
-    argsHint: '[command]',
+    description: 'Browse every command with its description; picking one runs it',
     handler(_args, ctx) {
+      // Generated live from the command registry — never a hand-maintained
+      // list — so /help can never drift from the real command set. Category
+      // labels come from the same single source of truth as the generated
+      // reference and the palette (ctx.getCommandCategories; see its doc for
+      // why it is threaded through the context rather than imported here).
+      const commands = registry
+        .getAll()
+        .slice()
+        .sort((a, b) => a.name.localeCompare(b.name));
       if (ctx.openSelection) {
-        const items: SelectionItem[] = [
-          { id: '/model', label: '/model [id]', detail: 'Select LLM model', category: 'Model & Provider' },
-          { id: '/provider', label: '/provider [name]', detail: 'Switch provider', category: 'Model & Provider' },
-          { id: '/effort', label: '/effort [level]', detail: 'Reasoning effort (instant/low/medium/high)', category: 'Model & Provider' },
-          { id: '/context window', label: '/context window [<size>|clear]', detail: 'Show, set, or clear a custom context window for the current model', category: 'Model & Provider' },
-          { id: '/config', label: '/config [category|key]', detail: 'Open fullscreen configuration workspace', category: 'Config & Display' },
-          { id: '/debug', label: '/debug', detail: 'Toggle debug mode', category: 'Config & Display' },
-          { id: '/expand', label: '/expand [type]', detail: 'Expand blocks (all|thinking|tool|code)', category: 'Config & Display' },
-          { id: '/collapse', label: '/collapse [type]', detail: 'Collapse blocks', category: 'Config & Display' },
-          { id: '/bookmarks', label: '/bookmarks', detail: 'List bookmarked blocks', category: 'Config & Display' },
-          { id: '/clear', label: '/clear', detail: 'Clear display (keep context)', category: 'Conversation' },
-          { id: '/reset', label: '/reset', detail: 'Clear display + context', category: 'Conversation' },
-          { id: '/compact', label: '/compact', detail: 'Summarize to free context', category: 'Conversation' },
-          { id: '/export', label: '/export [file]', detail: 'Export as markdown', category: 'Conversation' },
-          { id: '/title', label: '/title [text]', detail: 'Show or set title', category: 'Conversation' },
-          { id: '/save', label: '/save [name]', detail: 'Save session', category: 'Conversation' },
-          { id: '/load', label: '/load <name>', detail: 'Load session', category: 'Conversation' },
-          { id: '/sessions', label: '/sessions', detail: 'List saved sessions', category: 'Conversation' },
-          { id: '/session', label: '/session', detail: 'Current session info', category: 'Conversation' },
-          { id: '/session list', label: '/session list', detail: 'List all sessions', category: 'Conversation' },
-          { id: '/session rename', label: '/session rename <name>', detail: 'Rename current session', category: 'Conversation' },
-          { id: '/resume', label: '/resume [id]', detail: 'Resume a previous session (picker when no id)', category: 'Conversation' },
-          { id: '/session resume', label: '/session resume <id>', detail: 'Load and resume a session', category: 'Conversation' },
-          { id: '/session fork', label: '/session fork [name]', detail: 'Fork current session to new ID', category: 'Conversation' },
-          { id: '/session save', label: '/session save [name]', detail: 'Force-save current session', category: 'Conversation' },
-          { id: '/session info', label: '/session info [id]', detail: 'Show session details', category: 'Conversation' },
-          { id: '/session export', label: '/session export <id> [format]', detail: 'Export session as markdown/text', category: 'Conversation' },
-          { id: '/session search', label: '/session search <query>', detail: 'Search across all sessions', category: 'Conversation' },
-          { id: '/session delete', label: '/session delete <id>', detail: 'Delete a session', category: 'Conversation' },
-          { id: '/undo', label: '/undo', detail: 'Remove last turn', category: 'Conversation' },
-          { id: '/redo', label: '/redo', detail: 'Restore undone turn', category: 'Conversation' },
-          { id: '/retry', label: '/retry [text]', detail: 'Re-send last message', category: 'Conversation' },
-          { id: '/fork', label: '/fork [name]', detail: 'Snapshot conversation as a named branch', category: 'Conversation' },
-          { id: '/branch', label: '/branch [name]', detail: 'List branches or switch to one', category: 'Conversation' },
-          { id: '/merge', label: '/merge <name>', detail: 'Append messages from a branch', category: 'Conversation' },
-          { id: '/template', label: '/template', detail: 'Browse templates', category: 'Templates' },
-          { id: '/template save', label: '/template save <name>', detail: 'Save prompt as template', category: 'Templates' },
-          { id: '/template use', label: '/template use <name>', detail: 'Execute template', category: 'Templates' },
-          { id: '/tools', label: '/tools', detail: 'List available tools', category: 'Tools & System' },
-          { id: '/search', label: '/search <query> [--limit <n>]', detail: 'Search the web and show ranked results', category: 'Tools & System' },
-          { id: '/imagine', label: '/imagine <prompt>', detail: 'Generate an image from a prompt', category: 'Tools & System' },
-          { id: '/paste', label: '/paste', detail: 'Insert clipboard text or image into the prompt', category: 'Tools & System' },
-          { id: '/shortcuts', label: '/shortcuts', detail: 'View keyboard shortcuts reference', category: 'Tools & System' },
-          { id: '/commands', label: '/commands', detail: 'Browse all commands in a scrollable list', category: 'Tools & System' },
-          { id: '/secrets', label: '/secrets set|link|get|test|list|delete', detail: 'Manage encrypted and provider-backed secrets', category: 'Tools & System' },
-          { id: '/help', label: '/help', detail: 'This help', category: 'Tools & System' },
-          { id: '/quit', label: '/quit', detail: 'Exit', category: 'Tools & System' },
-          { id: '/wq', label: '/wq', detail: 'Commit all git changes and then exit', category: 'Tools & System' },
-        ];
-        // UX-C: every item here is a command, and picking one RUNS it — label
+        const categoryByName = ctx.getCommandCategories?.() ?? new Map<string, string>();
+        const items: SelectionItem[] = commands.map((cmd) => {
+          const argsHint = cmd.argsHint ?? cmd.usage;
+          const aliases = cmd.aliases ?? [];
+          return {
+            id: cmd.name,
+            label: argsHint ? `/${cmd.name} ${argsHint}` : `/${cmd.name}`,
+            detail: aliases.length > 0 ? `${cmd.description} [aka ${aliases.map((a) => `/${a}`).join(', ')}]` : cmd.description,
+            category: categoryByName.get(cmd.name) ?? 'Other',
+          };
+        });
+        // every item here is a command, and picking one RUNS it — label
         // the verb "Run" (matching the slash-command palette) instead of the
         // generic "Select" default.
         ctx.openSelection('Help  —  Commands', items, { allowSearch: true, primaryVerbLabel: 'Run' }, (result) => {
           if (!result) return;
-          const command = result.item.id;
-          if (command.startsWith('/')) {
-            const parts = command.slice(1).trim().split(/\s+/);
-            const name = parts[0];
-            const cmdArgs = parts.slice(1);
-            void (ctx.executeCommand?.(name, cmdArgs) ?? registry.execute(name, cmdArgs, ctx));
-          }
+          const name = result.item.id;
+          void (ctx.executeCommand?.(name, []) ?? registry.execute(name, [], ctx));
         });
         return;
       }
-      ctx.print('Use /help to open the help modal. Commands: /model, /provider, /config, /template, /tools, /paste, /sessions, /bookmarks, /save, /load, /undo, /redo, /retry, /clear, /reset, /compact, /export, /title, /effort, /expand, /collapse, /debug, /quit, /wq');
+      ctx.print(
+        [
+          'Commands:',
+          ...commands.map((cmd) => {
+            const argsHint = cmd.argsHint ?? cmd.usage;
+            return `  /${cmd.name}${argsHint ? ` ${argsHint}` : ''} — ${cmd.description}`;
+          }),
+        ].join('\n'),
+      );
     },
   });
 
@@ -214,7 +192,7 @@ export function registerShellCoreCommands(registry: CommandRegistry): void {
     description: 'Summarize conversation to free context window',
     async handler(_args, ctx) {
       const messages = ctx.session.conversationManager.getMessagesForLLM();
-      // W5.4 (wo803): contextWindow IS reachable from CommandContext — the same
+      // contextWindow IS reachable from CommandContext — the same
       // call compactConversation() (runtime-services.ts) already makes to scale
       // its own behaviour by window size. Previously hardcoded to 0 here, which
       // silently suppressed buildCompactionPreview()'s capacity-% clause even
@@ -230,7 +208,7 @@ export function registerShellCoreCommands(registry: CommandRegistry): void {
       const result = await compactConversation(ctx);
       if (result) {
         // Post-compact notice: uses real CompactionEvent figures, plus an
-        // out-of-band quality-score grade line when one was computed (W5.4/B28).
+        // out-of-band quality-score grade line when one was computed ().
         ctx.print(buildCompactionAfterNotice({ event: result.event, pinnedMemoryCount, qualityScore: result.qualityScore }));
       } else {
         ctx.print('[Context] Compact complete.');
@@ -300,7 +278,7 @@ export function registerShellCoreCommands(registry: CommandRegistry): void {
       ctx.session.runtime.debugMode = !ctx.session.runtime.debugMode;
       ctx.print(`Debug mode: ${ctx.session.runtime.debugMode ? 'ON' : 'OFF'}`);
       // Honest quiet counter for direct terminal writes the guard intercepted
-      // (routed here instead of spamming the transcript). (UX-B item 1a.)
+      // (routed here instead of spamming the transcript). (item 1a.)
       const intercepted = ctx.session.runtime.terminalWritesIntercepted ?? 0;
       if (intercepted > 0) {
         ctx.print(`Terminal writes intercepted this session: ${intercepted} (details in the activity log)`);

package/src/input/commands/subscription-runtime.ts

@@ -80,7 +80,7 @@ export function registerSubscriptionRuntimeCommands(registry: CommandRegistry):
     async handler(args, ctx) {
       const shellPaths = requireShellPaths(ctx);
       if (args.length === 0 && ctx.openModal) {
-        ctx.openModal('subscription-modal'); // W6.1: subscription panel -> config modal
+        ctx.openModal('subscription-modal'); // subscription panel -> config modal
         return;
       }
       const sub = (args[0] ?? 'review').toLowerCase();

package/src/input/commands/update-runtime.ts

@@ -1,8 +1,11 @@
 /**
- * `/update` — a real self-update path for binary installs, mirroring
- * scripts/install.sh's download-verify-swap semantics (that file is the
- * tested reference for release-asset naming and checksum verification; keep
- * this in lockstep with it).
+ * `/update` — a real self-update path for binary installs. The
+ * download-verify-swap mechanics are the SDK's canonical update policy
+ * module (platform/runtime/self-update — hoisted from this file's
+ * semantics), the same mechanism the daemon's hourly loop and
+ * scripts/install.sh follow: one update mechanism everywhere. This file owns
+ * only the /update UX: install-kind gating, target selection, and the
+ * printed report.
  *
  * Subcommands:
  *   /update [check]           — resolve the latest release tag and report
@@ -12,9 +15,17 @@
  *                                app and daemon binaries, and refresh the
  *                                sqlite-vec native addon in lockstep so the
  *                                vector index never goes stale beside a new
- *                                binary. For any other install kind, prints the
- *                                exact command to run instead — it never
- *                                attempts a swap it can't do safely.
+ *                                binary. Every swap parks the outgoing file
+ *                                at `<path>.previous`, so the replaced
+ *                                version is always kept. For any other
+ *                                install kind, prints the exact command to
+ *                                run instead — it never attempts a swap it
+ *                                can't do safely.
+ *   /update rollback           — exchange each installed file with its kept
+ *                                `.previous` counterpart: one command back to
+ *                                the version that ran before the last update
+ *                                (and, being an exchange, one more command
+ *                                forward again).
  *   /update review              — install/subscription/sandbox posture,
  *                                unrelated to the update mechanics above.
  *   /update bundle export|inspect <path> — portable posture bundle, as before.
@@ -26,9 +37,16 @@
  * (scripts/release.ts) does not publish separate stable/preview channels,
  * so there is no real channel selection to wire it to.
  */
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import {
+  applyVerifiedUpdate,
+  realUpdateFileIo,
+  rollbackKeptPrevious,
+  type UpdateFileIo,
+  type UpdateTarget,
+} from '@pellux/goodvibes-sdk/platform/runtime/self-update';
 import type { CommandRegistry } from '../command-registry.ts';
 import { VERSION } from '../../version.ts';
 import { listBuiltinSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config';
@@ -37,8 +55,6 @@ import {
   parseChecksumFile,
   resolveArtifactNames,
   resolveSqliteVecAsset,
-  sha256,
-  verifyChecksum,
 } from '../../runtime/release-artifacts.ts';
 import {
   compareVersions,
@@ -66,47 +82,13 @@ async function downloadText(fetchImpl: UpdateFetchLike, url: string): Promise<st
   return await response.text();
 }
 
-async function downloadBuffer(fetchImpl: UpdateFetchLike, url: string): Promise<Buffer> {
-  const response = await fetchImpl(url);
-  if (!response.ok) {
-    throw new Error(`download failed (${response.status}) for ${url}`);
-  }
-  return Buffer.from(await response.arrayBuffer());
-}
-
 /**
- * Writes the new binary next to the target, then renames over it — an
- * atomic replace on the same filesystem, so a currently-running process
- * that already opened the old file keeps its old inode (POSIX unlink
- * semantics) instead of executing a half-written file. Same approach as
- * scripts/install.sh's `mv -f "$WORKDIR/$artifact" "$target"`.
+ * Suffix under which every swap keeps the file it replaced — re-exported
+ * from the SDK's canonical update policy module so rollback and swap share
+ * one definition everywhere.
  */
-function swapBinaryAtomically(targetPath: string, buffer: Buffer): void {
-  const tempPath = `${targetPath}.update-download`;
-  writeFileSync(tempPath, buffer);
-  if (process.platform !== 'win32') {
-    chmodSync(tempPath, 0o755);
-  }
-  renameSync(tempPath, targetPath);
-}
-
-/**
- * Writes the sqlite-vec native addon into place with the same temp-write +
- * atomic-rename discipline as the binaries, so a running process never
- * dlopen()s a half-written extension. The addon's parent directory
- * (`<execDir>/lib/sqlite-vec-<os>-<arch>/`) is created first because a fresh
- * install may not have a `lib/` tree yet. A shared library needs no execute
- * bit, so this uses 0o644 rather than the binaries' 0o755.
- */
-function writeAddonAtomically(targetPath: string, buffer: Buffer): void {
-  mkdirSync(dirname(targetPath), { recursive: true });
-  const tempPath = `${targetPath}.update-download`;
-  writeFileSync(tempPath, buffer);
-  if (process.platform !== 'win32') {
-    chmodSync(tempPath, 0o644);
-  }
-  renameSync(tempPath, targetPath);
-}
+export { PREVIOUS_FILE_SUFFIX } from '@pellux/goodvibes-sdk/platform/runtime/self-update';
+import { PREVIOUS_FILE_SUFFIX } from '@pellux/goodvibes-sdk/platform/runtime/self-update';
 
 export interface DaemonServiceRestartInfo {
   readonly managed: boolean;
@@ -169,19 +151,19 @@ export interface ApplyUpdateOptions {
   readonly print: (line: string) => void;
   readonly configManager: { get(key: string): unknown };
   readonly runCommand?: RunCommand;
-  /** Injectable so tests can observe/skip the actual filesystem swap. */
-  readonly swap?: (targetPath: string, buffer: Buffer) => void;
-  /** Injectable so tests can observe/skip writing the sqlite-vec addon. */
-  readonly writeAddon?: (targetPath: string, buffer: Buffer) => void;
-  readonly fileExists?: (path: string) => boolean;
+  /** Injectable filesystem seam (the SDK's UpdateFileIo) so tests observe swaps in memory. */
+  readonly io?: UpdateFileIo;
 }
 
 /**
- * The real self-update path. For a binary install: resolve the latest tag,
- * compare to the running version, and if newer, download + verify both
- * artifacts BEFORE swapping either one (so a checksum failure on the second
- * artifact never leaves a mismatched pair installed), then atomically swap
- * each in place. For any other install kind, never attempts a swap — it
+ * The real self-update path, delegating the download-verify-swap mechanics
+ * to the SDK's canonical update policy module (applyVerifiedUpdate — the
+ * same mechanism the daemon's hourly loop uses). For a binary install:
+ * resolve the latest tag, compare to the running version, and if newer,
+ * download + checksum-verify EVERY artifact before swapping any one (so a
+ * checksum failure never leaves a mismatched pair installed), then
+ * atomically swap each in place with the outgoing file kept at
+ * `<path>.previous`. For any other install kind, never attempts a swap — it
  * prints the exact command for that install method instead.
  */
 export async function applyUpdate(options: ApplyUpdateOptions): Promise<void> {
@@ -211,22 +193,10 @@ export async function applyUpdate(options: ApplyUpdateOptions): Promise<void> {
   options.print(`Update available: ${latestTag} (running v${normalizeVersion(options.currentVersion)}). Downloading and verifying...`);
 
   const baseUrl = releaseDownloadBaseUrl(latestTag);
-  const checksumText = await downloadText(options.fetchImpl, `${baseUrl}/${CHECKSUM_MANIFEST_NAME}`);
-  const checksums = parseChecksumFile(checksumText);
-
+  const io = options.io ?? realUpdateFileIo;
   const appBinaryPath = options.execPath;
   const daemonBinaryPath = join(dirname(appBinaryPath), 'goodvibes-daemon');
-  const fileExists = options.fileExists ?? existsSync;
-  const daemonBinaryPresent = fileExists(daemonBinaryPath);
-
-  const appBuffer = await downloadBuffer(options.fetchImpl, `${baseUrl}/${artifacts.app}`);
-  verifyChecksum(artifacts.app, sha256(appBuffer), checksums.get(artifacts.app));
-
-  let daemonBuffer: Buffer | null = null;
-  if (daemonBinaryPresent) {
-    daemonBuffer = await downloadBuffer(options.fetchImpl, `${baseUrl}/${artifacts.daemon}`);
-    verifyChecksum(artifacts.daemon, sha256(daemonBuffer), checksums.get(artifacts.daemon));
-  }
+  const daemonBinaryPresent = io.exists(daemonBinaryPath);
 
   // The sqlite-vec native addon travels with the binaries: refresh it in the
   // same download-verify-swap pass so /update never leaves a new binary beside a
@@ -237,28 +207,36 @@ export async function applyUpdate(options: ApplyUpdateOptions): Promise<void> {
   // swap), while an absent entry means the target predates the addon and is
   // skipped rather than blocking an otherwise-valid binary update. On macOS the
   // file is refreshed for consistency even though the platform blocks extension
-  // loading.
+  // loading. This inclusion decision needs one manifest pre-read; the swap
+  // itself re-verifies every included artifact inside applyVerifiedUpdate.
+  const checksumText = await downloadText(options.fetchImpl, `${baseUrl}/${CHECKSUM_MANIFEST_NAME}`);
+  const checksums = parseChecksumFile(checksumText);
   const addon = resolveSqliteVecAsset(options.platform, options.arch);
-  const addonExpected = addon ? checksums.get(addon.assetName) : undefined;
-  let addonBuffer: Buffer | null = null;
-  if (addon && addonExpected !== undefined) {
-    addonBuffer = await downloadBuffer(options.fetchImpl, `${baseUrl}/${addon.assetName}`);
-    verifyChecksum(addon.assetName, sha256(addonBuffer), addonExpected);
-  }
-
-  // All downloads verified before any write — an update must not apply partially.
-  const swap = options.swap ?? swapBinaryAtomically;
-  swap(appBinaryPath, appBuffer);
-  if (daemonBuffer) {
-    swap(daemonBinaryPath, daemonBuffer);
-  }
-  const addonTargetPath = addon && addonBuffer
+  const addonIncluded = addon !== null && checksums.get(addon.assetName) !== undefined;
+  const addonTargetPath = addon && addonIncluded
     ? join(dirname(appBinaryPath), 'lib', addon.dirName, addon.fileName)
     : null;
-  if (addonBuffer && addonTargetPath) {
-    const writeAddon = options.writeAddon ?? writeAddonAtomically;
-    writeAddon(addonTargetPath, addonBuffer);
-  }
+
+  const targets: UpdateTarget[] = [
+    { label: 'app binary', path: appBinaryPath, assetName: artifacts.app, executable: true },
+    ...(daemonBinaryPresent
+      ? [{ label: 'daemon binary', path: daemonBinaryPath, assetName: artifacts.daemon, executable: true }]
+      : []),
+    ...(addon && addonTargetPath
+      ? [{ label: 'vector addon', path: addonTargetPath, assetName: addon.assetName, executable: false }]
+      : []),
+  ];
+
+  // One mechanism everywhere: downloads + verifies ALL targets before any
+  // write, then swaps each atomically with the outgoing file kept at
+  // `<path>.previous`.
+  await applyVerifiedUpdate({
+    fetchImpl: options.fetchImpl,
+    downloadBaseUrl: baseUrl,
+    targets,
+    io,
+    platform: options.platform,
+  });
 
   const serviceInfo = detectDaemonServiceManaged(options.platform, options.configManager, options.runCommand);
 
@@ -279,6 +257,70 @@ export async function applyUpdate(options: ApplyUpdateOptions): Promise<void> {
   );
 }
 
+export interface RollbackUpdateOptions {
+  readonly execPath: string;
+  readonly platform: NodeJS.Platform;
+  readonly arch: string;
+  readonly print: (line: string) => void;
+  readonly configManager: { get(key: string): unknown };
+  readonly runCommand?: RunCommand;
+  /** Injectable filesystem seam (the SDK's UpdateFileIo) so tests observe renames in memory. */
+  readonly io?: UpdateFileIo;
+}
+
+/**
+ * One-command rollback to the version that ran before the last update,
+ * delegating the exchange mechanics to the SDK's rollbackKeptPrevious (the
+ * same module the swap uses): every installed file (app binary, daemon
+ * binary, vector addon) that has a kept `.previous` counterpart is EXCHANGED
+ * with it — the previous version becomes live, and the version being rolled
+ * back is itself kept at `.previous`, so a second `/update rollback` rolls
+ * forward again. Files without a kept counterpart are reported and left
+ * untouched; nothing is downloaded.
+ */
+export function rollbackUpdate(options: RollbackUpdateOptions): void {
+  const installKind: InstallKind = detectInstallKind(options.execPath);
+  if (installKind !== 'binary') {
+    options.print(
+      [
+        `This install is not a self-updatable binary install (detected: ${installKind === 'bun-global-package' ? 'bun/npm package install' : 'running from source'}), so there is no kept previous binary to roll back to.`,
+        `Install a specific version with your package manager instead, e.g.: ${fallbackUpdateCommand(installKind)}`,
+      ].join('\n'),
+    );
+    return;
+  }
+
+  const io = options.io ?? realUpdateFileIo;
+  const addon = resolveSqliteVecAsset(options.platform, options.arch);
+  const targets = [
+    { label: 'app binary', path: options.execPath },
+    { label: 'daemon binary', path: join(dirname(options.execPath), 'goodvibes-daemon') },
+    ...(addon ? [{ label: 'vector addon', path: join(dirname(options.execPath), 'lib', addon.dirName, addon.fileName) }] : []),
+  ];
+
+  const result = rollbackKeptPrevious(targets, io);
+  if (result.restored.length === 0) {
+    options.print(
+      `No previous version is kept beside this install (nothing at ${options.execPath}${PREVIOUS_FILE_SUFFIX}). ` +
+      'The previous version is kept from the next update onward.',
+    );
+    return;
+  }
+
+  const serviceInfo = detectDaemonServiceManaged(options.platform, options.configManager, options.runCommand);
+  options.print(
+    [
+      'Rolled back to the previously installed version.',
+      ...result.restored.map((target) => `  ${target.label}: ${target.path} (the replaced version is kept at ${target.path}${PREVIOUS_FILE_SUFFIX})`),
+      '',
+      'Restart goodvibes to run the restored version.',
+      serviceInfo.managed
+        ? `The daemon is managed by systemd — restart it with: ${serviceInfo.restartCommand}`
+        : 'The daemon restarts automatically the next time goodvibes launches.',
+    ].join('\n'),
+  );
+}
+
 interface UpdateBundle {
   readonly version: 1;
   readonly exportedAt: number;
@@ -304,8 +346,8 @@ export function registerUpdateCommand(registry: CommandRegistry): void {
   registry.register({
     name: 'update',
     aliases: ['upgrade'],
-    description: 'Check for a newer GoodVibes release and, for binary installs, download/verify/apply it',
-    usage: '[check|apply|review|bundle export <path>|bundle inspect <path>]',
+    description: 'Check for a newer GoodVibes release and, for binary installs, download/verify/apply it or roll back to the kept previous version',
+    usage: '[check|apply|rollback|review|bundle export <path>|bundle inspect <path>]',
     async handler(args, ctx) {
       const sub = args[0] ?? 'check';
 
@@ -340,6 +382,21 @@ export function registerUpdateCommand(registry: CommandRegistry): void {
         return;
       }
 
+      if (sub === 'rollback') {
+        try {
+          rollbackUpdate({
+            execPath: process.execPath,
+            platform: process.platform,
+            arch: process.arch,
+            print: ctx.print,
+            configManager: ctx.platform.configManager,
+          });
+        } catch (error) {
+          ctx.print(`Rollback failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return;
+      }
+
       if (sub === 'review') {
         const installKind = detectInstallKind(process.execPath);
         const subscriptions = requireSubscriptionManager(ctx);
@@ -358,7 +415,7 @@ export function registerUpdateCommand(registry: CommandRegistry): void {
             `  built-in subscription providers: ${builtinProviders.length}${builtinProviders.length > 0 ? ` (${builtinProviders.join(', ')})` : ''}`,
             `  active subscriptions: ${activeSubscriptions.length}${activeSubscriptions.length > 0 ? ` (${activeSubscriptions.join(', ')})` : ''}`,
             `  sandbox profile: ${sandboxProfile}`,
-            '  use /update check to look for a newer release, /update apply to install it',
+            '  use /update check to look for a newer release, /update apply to install it, /update rollback to return to the kept previous version',
           ].join('\n'),
         );
         return;
@@ -406,7 +463,7 @@ export function registerUpdateCommand(registry: CommandRegistry): void {
         }
       }
 
-      ctx.print('Usage: /update [check|apply|review|bundle export <path>|bundle inspect <path>]');
+      ctx.print('Usage: /update [check|apply|rollback|review|bundle export <path>|bundle inspect <path>]');
     },
   });
 }

package/src/input/commands/work-plan-runtime.ts

@@ -25,7 +25,7 @@ function getStore(ctx: import('../command-registry.ts').CommandContext): WorkPla
 }
 
 function openPanel(ctx: import('../command-registry.ts').CommandContext): void {
-  // W6.1: work-plan migrated to the 'work-plan' modal — open it via the seam.
+  // work-plan migrated to the 'work-plan' modal — open it via the seam.
   openModalCommand(ctx, 'work-plan-modal');
 }