@pellux/goodvibes-agent 1.8.1 → 1.9.0

package/src/cli/temporal-label.ts

@@ -0,0 +1,89 @@
+/**
+ * Human temporal labels for CLI record listings.
+ *
+ * CLI output that lists sessions, routines, principals, and other timestamped
+ * records used to show a raw value (an ISO string or nothing) with no sense of
+ * how recent it is. These helpers add a plain "how long ago" (or "in ...")
+ * label ALONGSIDE the precise value — the precise value is never replaced,
+ * because the exact timestamp still matters for records, correlation, and
+ * scripting. `appendTemporalLabel` is the intended entry point: it keeps the
+ * precise string the caller already renders and appends `(2 hours ago)`.
+ *
+ * Both an epoch-milliseconds number and an ISO/parseable date string are
+ * accepted, since session summaries carry an epoch number while the local
+ * record registries (routines, personas, skills, principals, ...) carry ISO
+ * strings. Unparseable or absent input yields no label rather than a fabricated
+ * one — honesty over a plausible-looking guess.
+ */
+
+/** Parse an epoch-ms number or a date string into epoch ms, or null when it is not a real instant. */
+export function toEpochMs(value: number | string | null | undefined): number | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  const parsed = Date.parse(trimmed);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+const MONTH = 30 * DAY;
+const YEAR = 365 * DAY;
+
+function unit(count: number, singular: string): string {
+  return `${count} ${singular}${count === 1 ? '' : 's'}`;
+}
+
+/**
+ * A plain relative label for an instant, e.g. "2 hours ago", "in 3 days",
+ * "just now". Returns null when the input is not a real instant.
+ *
+ * Elapsed magnitudes are floored (not rounded) so a label never describes a
+ * moment as further in the past than it truly is — the same anti-overstatement
+ * rule the resume-relaunch age formatter follows. Future instants read "in N"
+ * with the same tiers.
+ */
+export function formatTemporalLabel(
+  value: number | string | null | undefined,
+  now: number = Date.now(),
+): string | null {
+  const at = toEpochMs(value);
+  if (at === null) return null;
+
+  const deltaMs = now - at;
+  const future = deltaMs < 0;
+  const abs = Math.abs(deltaMs);
+
+  if (abs < 10_000) return 'just now';
+
+  const magnitude = ((): string => {
+    if (abs < MINUTE) return unit(Math.floor(abs / 1000), 'second');
+    if (abs < HOUR) return unit(Math.floor(abs / MINUTE), 'minute');
+    if (abs < DAY) return unit(Math.floor(abs / HOUR), 'hour');
+    if (abs < WEEK) return unit(Math.floor(abs / DAY), 'day');
+    if (abs < MONTH) return unit(Math.floor(abs / WEEK), 'week');
+    if (abs < YEAR) return unit(Math.floor(abs / MONTH), 'month');
+    return unit(Math.floor(abs / YEAR), 'year');
+  })();
+
+  return future ? `in ${magnitude}` : `${magnitude} ago`;
+}
+
+/**
+ * Append a parenthetical temporal label to a precise value string the caller
+ * already renders. The precise value stays exactly as-is; the label is added
+ * only when the instant parses. Example:
+ *   appendTemporalLabel('2026-07-11T09:00:00.000Z', someEpochOrIso)
+ *     -> '2026-07-11T09:00:00.000Z (2 hours ago)'
+ */
+export function appendTemporalLabel(
+  precise: string,
+  value: number | string | null | undefined,
+  now: number = Date.now(),
+): string {
+  const label = formatTemporalLabel(value, now);
+  return label ? `${precise} (${label})` : precise;
+}

package/src/cli/types.ts

@@ -11,6 +11,11 @@ export type GoodVibesCliCommand =
   | 'skills'
   | 'memory'
   | 'routines'
+  | 'ci'
+  | 'principals'
+  | 'channel-profiles'
+  | 'workspaces'
+  | 'fleet'
   | 'auth'
   | 'compat'
   | 'knowledge'
@@ -21,8 +26,10 @@ export type GoodVibesCliCommand =
   | 'secrets'
   | 'sessions'
   | 'tasks'
+  | 'relay'
   | 'pair'
   | 'bundle'
+  | 'import'
   | 'completion'
   | 'help'
   | 'version'

package/src/cli/workspaces-command.ts

@@ -0,0 +1,135 @@
+import { createShellPathService } from '@/runtime/index.ts';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { WorkspaceRegistrationError } from '@pellux/goodvibes-sdk/platform/workspace';
+import {
+  createWorkspaceRegistrationStore,
+  migrateLegacyWorkspaceRegistryIfNeeded,
+  normalizeWorkspaceRoot,
+} from '../config/workspace-registration.ts';
+import type { CliCommandOutput } from './types.ts';
+import type { CliCommandRuntime } from './management.ts';
+
+/**
+ * `goodvibes-agent workspaces` — manage the shared registered-workspace store
+ * (SDK 1.6.1 platform/workspace/registration) that gates automatic checkpoints
+ * (owner ruling, 2026-07-10; see ../runtime/services.ts and
+ * ../config/workspace-registration.ts). A workspace root not covered by this
+ * store gets no automatic turn/agent-lifecycle checkpoints, and explicit
+ * `checkpoints.create` gateway calls against it are refused with this
+ * command's registration hint (see services.ts's checkpointsGatewayManager).
+ *
+ * Coverage flows down a registered root's subtree and is inherited through
+ * the git worktree→main-repo link (an orchestration worktree of a registered
+ * repo is covered without being registered itself) — the CLI UX below (the
+ * list/register/unregister subcommands, their flags, and their exit codes) is
+ * unchanged from the local-registry predecessor this now reads/writes
+ * through instead.
+ */
+
+function hasYes(args: readonly string[]): boolean {
+  return args.includes('--yes');
+}
+
+function flagValue(args: readonly string[], names: readonly string[]): string | null {
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]!;
+    for (const name of names) {
+      if (token === name) {
+        const next = args[index + 1];
+        return next && !next.startsWith('--') ? next : null;
+      }
+      if (token.startsWith(`${name}=`)) return token.slice(name.length + 1);
+    }
+  }
+  return null;
+}
+
+function commandValues(args: readonly string[]): readonly string[] {
+  const values: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]!;
+    if (!token.startsWith('--')) values.push(token);
+  }
+  return values;
+}
+
+function jsonOrText(runtime: CliCommandRuntime, value: unknown, text: string): string {
+  return runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text;
+}
+
+function usage(runtime: CliCommandRuntime, error: string): CliCommandOutput {
+  const message = `${error}\nUsage: goodvibes-agent workspaces [list|register [path] [--label <label>] --yes|unregister [path] --yes]`;
+  return { output: jsonOrText(runtime, { ok: false, error: message }, message), exitCode: 2 };
+}
+
+export async function handleWorkspacesCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  const shellPaths = createShellPathService({
+    workingDirectory: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  });
+
+  // Idempotent, receipt-gated: a no-op after the first successful migration on
+  // this machine, from any entry point. See workspace-registration.ts.
+  const migration = migrateLegacyWorkspaceRegistryIfNeeded(shellPaths);
+  if (migration) {
+    logger.info('Migrated the local workspace registry into the shared registration store', { ...migration });
+  }
+
+  const store = createWorkspaceRegistrationStore(shellPaths);
+  const [sub = 'list', ...rawRest] = runtime.cli.commandArgs;
+  const values = commandValues(rawRest);
+
+  if (sub === 'list' || sub === 'ls') {
+    const snapshot = await store.snapshot();
+    const current = normalizeWorkspaceRoot(runtime.workingDirectory);
+    const currentResolution = await store.resolve(current);
+    const currentWorkspaceRegistered = currentResolution.status === 'covered';
+    if (runtime.cli.flags.outputFormat === 'json') {
+      return {
+        output: JSON.stringify({ ok: true, ...snapshot, currentWorkspaceRegistered }, null, 2),
+        exitCode: 0,
+      };
+    }
+    const lines = snapshot.workspaces.length === 0
+      ? ['No registered workspaces', '  automatic checkpoints are off everywhere until a workspace is registered']
+      : [
+        `Registered workspaces (${snapshot.workspaces.length})`,
+        ...snapshot.workspaces.map((entry) => `  ${entry.root}${entry.label ? ` (${entry.label})` : ''} — registered ${entry.registeredAt}`),
+      ];
+    lines.push('', `current workspace ${current}`, `  registered ${currentWorkspaceRegistered ? 'yes' : 'no'}`);
+    return { output: lines.join('\n'), exitCode: 0 };
+  }
+
+  if (sub === 'register' || sub === 'add') {
+    const target = values[0] ?? runtime.workingDirectory;
+    if (!hasYes(rawRest)) {
+      return usage(runtime, `Refusing to register workspace ${normalizeWorkspaceRoot(target)} for automatic checkpoints without --yes.`);
+    }
+    const label = flagValue(rawRest, ['--label']) ?? undefined;
+    try {
+      const result = await store.add(target, label ? { label } : undefined);
+      const text = result.alreadyRegistered
+        ? `Workspace already registered: ${result.record.root}`
+        : `Workspace registered: ${result.record.root}\n  automatic checkpoints are now allowed for this workspace`;
+      return { output: jsonOrText(runtime, { ok: true, ...result }, text), exitCode: 0 };
+    } catch (error) {
+      const message = error instanceof WorkspaceRegistrationError ? error.message : summarizeError(error);
+      return { output: jsonOrText(runtime, { ok: false, error: message }, message), exitCode: 2 };
+    }
+  }
+
+  if (sub === 'unregister' || sub === 'remove' || sub === 'rm') {
+    const target = values[0] ?? runtime.workingDirectory;
+    if (!hasYes(rawRest)) {
+      return usage(runtime, `Refusing to unregister workspace ${normalizeWorkspaceRoot(target)} without --yes.`);
+    }
+    const result = await store.remove(target);
+    const text = result.removed
+      ? `Workspace unregistered: ${normalizeWorkspaceRoot(target)}\n  automatic checkpoints are now off for this workspace`
+      : `Workspace was not registered: ${normalizeWorkspaceRoot(target)}`;
+    return { output: jsonOrText(runtime, { ok: true, ...result }, text), exitCode: result.removed ? 0 : 1 };
+  }
+
+  return usage(runtime, `Unknown workspaces subcommand: ${sub}`);
+}

package/src/config/agent-settings-policy.ts

@@ -9,6 +9,14 @@ const AGENT_HIDDEN_SETTING_KEYS = new Set<string>([
 ]);
 
 const EXTERNAL_HOST_SETTING_PREFIXES = [
+  // Outbound relay reachability is a daemon lifecycle concern (dial-out,
+  // identity custody, WebAuthn step-up enforcement) owned by whichever
+  // GoodVibes host Agent is connected to. Agent's own copy of these keys is
+  // an imported/local snapshot (see README's "shared GoodVibes settings
+  // import"), not a live-shared file — toggling relay.enabled here would not
+  // actually start or stop the connected daemon's relay registration, so the
+  // whole domain is locked exactly like danger.httpListener below.
+  'relay.',
 ] as const;
 
 const EXTERNAL_HOST_SETTING_KEYS = new Set<string>([

package/src/config/checkpoint-settings.ts

@@ -0,0 +1,113 @@
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+
+/**
+ * Agent-local checkpoint guard settings (`checkpoints.*` namespace).
+ *
+ * The SDK's WorkspaceCheckpointManager exposes root/retention guard options that
+ * decide which directory it is safe to snapshot and how the first sweep and
+ * retention behave:
+ *
+ *   - `checkpoints.preferGitRoot` (boolean, SDK default true) — prefer the
+ *     enclosing git repository's top level over the raw working directory.
+ *   - `checkpoints.allowBroadRoot` (boolean, SDK default false) — opt in to
+ *     snapshotting a broad root (filesystem root, home directory, ~/.goodvibes).
+ *   - `checkpoints.allowLargeFirstSnapshot` (boolean, SDK default false) — opt
+ *     in to a first snapshot whose full sweep exceeds `maxFirstSnapshotFiles`.
+ *   - `checkpoints.maxFirstSnapshotFiles` (number, SDK default) — ceiling for
+ *     the first-ever snapshot's file sweep.
+ *   - `checkpoints.autoRetention` (boolean, SDK default true) — run a retention
+ *     sweep automatically after each successful create and once at init.
+ *
+ * A sixth key, `checkpoints.unregisteredWorkspaces`, is read separately by
+ * `readCheckpointRegistrationSetting` below (kept out of `CheckpointGuardSettings`
+ * because it is an Agent-owned enforcement switch, not an SDK manager
+ * constructor option, and must never be spread into the manager's options).
+ *
+ * The shared SDK config schema (GoodVibesConfig) has no `checkpoints` category,
+ * so these are read directly from a user-supplied `checkpoints` block in
+ * settings.json. The SDK ConfigManager deep-merges loaded settings onto the
+ * default config and preserves unknown top-level blocks, so a hand-added
+ * `checkpoints` object survives to `getRaw()`. Only these five passthrough keys
+ * are read here; each absent key falls back to the SDK manager's own default.
+ *
+ * settings.json example:
+ *
+ *   "checkpoints": {
+ *     "preferGitRoot": true,
+ *     "allowBroadRoot": false,
+ *     "allowLargeFirstSnapshot": false,
+ *     "maxFirstSnapshotFiles": 20000,
+ *     "autoRetention": true,
+ *     "unregisteredWorkspaces": "off"
+ *   }
+ */
+export interface CheckpointGuardSettings {
+  readonly preferGitRoot?: boolean;
+  readonly allowBroadRoot?: boolean;
+  readonly allowLargeFirstSnapshot?: boolean;
+  readonly maxFirstSnapshotFiles?: number;
+  readonly autoRetention?: boolean;
+}
+
+/**
+ * Read the `checkpoints.*` guard passthrough keys from the loaded config. Only
+ * keys present with the right primitive type are returned; everything else is
+ * omitted so the SDK manager applies its own default. `maxFirstSnapshotFiles`
+ * must be a finite positive number to be accepted.
+ */
+export function readCheckpointGuardSettings(
+  configManager: Pick<ConfigManager, 'getRaw'>,
+): CheckpointGuardSettings {
+  const raw = configManager.getRaw() as unknown as Record<string, unknown>;
+  const block = raw.checkpoints;
+  if (block === null || typeof block !== 'object' || Array.isArray(block)) return {};
+  const cp = block as Record<string, unknown>;
+
+  const out: {
+    preferGitRoot?: boolean;
+    allowBroadRoot?: boolean;
+    allowLargeFirstSnapshot?: boolean;
+    maxFirstSnapshotFiles?: number;
+    autoRetention?: boolean;
+  } = {};
+
+  if (typeof cp.preferGitRoot === 'boolean') out.preferGitRoot = cp.preferGitRoot;
+  if (typeof cp.allowBroadRoot === 'boolean') out.allowBroadRoot = cp.allowBroadRoot;
+  if (typeof cp.allowLargeFirstSnapshot === 'boolean') out.allowLargeFirstSnapshot = cp.allowLargeFirstSnapshot;
+  if (
+    typeof cp.maxFirstSnapshotFiles === 'number'
+    && Number.isFinite(cp.maxFirstSnapshotFiles)
+    && cp.maxFirstSnapshotFiles > 0
+  ) {
+    out.maxFirstSnapshotFiles = cp.maxFirstSnapshotFiles;
+  }
+  if (typeof cp.autoRetention === 'boolean') out.autoRetention = cp.autoRetention;
+
+  return out;
+}
+
+/**
+ * The registered-workspaces-only override (owner ruling, 2026-07-10):
+ *
+ *   - `checkpoints.unregisteredWorkspaces` (`'off' | 'guarded'`, default `'off'`)
+ *     — `'off'` is the ruling's default: automatic (turn-end/lifecycle)
+ *     checkpoints, and explicit checkpoint creation through the ws-only
+ *     `checkpoints.create` gateway verb, both refuse when the resolved
+ *     workspace root is not covered by the shared registration store
+ *     (../config/workspace-registration.ts).
+ *     `'guarded'` opts back into the pre-ruling behavior for an unregistered
+ *     workspace: automatic snapshots subscribe and explicit create proceeds,
+ *     subject only to the SDK's own root/size guards above — never a silent
+ *     re-enable, an explicit per-workspace opt-out of the registration gate.
+ *
+ * Any other value (including absence) reads as `'off'`.
+ */
+export function readCheckpointRegistrationSetting(
+  configManager: Pick<ConfigManager, 'getRaw'>,
+): 'off' | 'guarded' {
+  const raw = configManager.getRaw() as unknown as Record<string, unknown>;
+  const block = raw.checkpoints;
+  if (block === null || typeof block !== 'object' || Array.isArray(block)) return 'off';
+  const value = (block as Record<string, unknown>).unregisteredWorkspaces;
+  return value === 'guarded' ? 'guarded' : 'off';
+}

package/src/config/workspace-registration.ts

@@ -0,0 +1,299 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, parse, resolve } from 'node:path';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import {
+  WorkspaceRegistrationStore,
+  resolveWorkspaceRegistration,
+  normalizeWorkspaceRoot,
+  probeWorktreeLink,
+  type RegisteredWorkspaceRecord,
+  type DeclinedWorkspaceRecord,
+  type WorkspaceCoverageStatus,
+  type WorkspaceGitMetadata,
+  type WorkspaceResolution,
+} from '@pellux/goodvibes-sdk/platform/workspace';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from './surface.ts';
+
+export { normalizeWorkspaceRoot } from '@pellux/goodvibes-sdk/platform/workspace';
+export type {
+  DeclinedWorkspaceRecord,
+  RegisteredWorkspaceRecord,
+  WorkspaceCoverageStatus,
+  WorkspaceResolution,
+} from '@pellux/goodvibes-sdk/platform/workspace';
+
+/**
+ * Shared registered-workspace registry (SDK 1.6.1 platform/workspace/registration),
+ * the successor to this fork's local per-user JSON registry
+ * (superseded ../config/workspace-registry.ts, deleted).
+ *
+ * MIGRATION. The local registry's record shape (`{ root, registeredAt, label? }`)
+ * is field-identical to the shared store's `RegisteredWorkspaceRecord`, so a local
+ * file migrates in as a straight import — see migrateLegacyWorkspaceRegistryIfNeeded.
+ *
+ * WHY A SYNCHRONOUS RESOLVER EXISTS ALONGSIDE THE ASYNC STORE. The SDK's
+ * WorkspaceRegistrationStore is Promise-based (it persists through
+ * PersistentStore). createRuntimeServices() (../runtime/services.ts) is
+ * synchronous by design — every consumer (the CLI, the TUI bootstrap, every
+ * test file) calls it synchronously — and the automatic-checkpoint decision
+ * (whether to pass runtimeBus to WorkspaceCheckpointManager) must be made AT
+ * construction time, not after an async read resolves later. So this module
+ * also ships a synchronous snapshot read + the SDK's PURE resolver
+ * (resolveWorkspaceRegistration, no disk/git I/O) for that one call site;
+ * every other consumer (the workspaces CLI, a future interactive prompt) goes
+ * through the real async store below, the single source of truth for writes.
+ * Both read the exact same on-disk file, so there is only ever one registry.
+ */
+
+export type StoreShellPaths = Pick<ShellPathService, 'resolveUserPath' | 'homeDirectory'>;
+
+/** Path of the shared store's JSON document — the SAME path the SDK's registerGatewayVerbGroups uses internally to construct its own store instance. */
+export function sharedWorkspaceRegistrationStorePath(shellPaths: StoreShellPaths): string {
+  return shellPaths.resolveUserPath('control-plane', 'workspace-registrations.json');
+}
+
+/** Construct a store instance over the shared file — for callers that can go async (CLI commands, interactive prompts). */
+export function createWorkspaceRegistrationStore(shellPaths: StoreShellPaths): WorkspaceRegistrationStore {
+  return new WorkspaceRegistrationStore({
+    path: sharedWorkspaceRegistrationStorePath(shellPaths),
+    homeDir: shellPaths.homeDirectory,
+    daemonStateDir: shellPaths.resolveUserPath(),
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function parseRegisteredRecord(value: unknown): RegisteredWorkspaceRecord | null {
+  if (!isRecord(value)) return null;
+  const root = readString(value.root);
+  const registeredAt = readString(value.registeredAt);
+  if (!root || !registeredAt || Number.isNaN(Date.parse(registeredAt))) return null;
+  const label = readString(value.label);
+  return { root: normalizeWorkspaceRoot(root), registeredAt, ...(label ? { label } : {}) };
+}
+
+function parseDeclinedRecord(value: unknown): DeclinedWorkspaceRecord | null {
+  if (!isRecord(value)) return null;
+  const root = readString(value.root);
+  const declinedAt = readString(value.declinedAt);
+  if (!root || !declinedAt || Number.isNaN(Date.parse(declinedAt))) return null;
+  return { root: normalizeWorkspaceRoot(root), declinedAt };
+}
+
+interface SharedRegistrationSnapshot {
+  readonly workspaces: readonly RegisteredWorkspaceRecord[];
+  readonly declines: readonly DeclinedWorkspaceRecord[];
+}
+
+/**
+ * Synchronous read of the shared store's on-disk JSON, mirroring the store's
+ * own validate() logic exactly (version 1, workspaces[], declines[]). A
+ * missing or unparsable file reads as empty — never throws.
+ */
+export function readSharedWorkspaceRegistrationSnapshotSync(shellPaths: StoreShellPaths): SharedRegistrationSnapshot {
+  const path = sharedWorkspaceRegistrationStorePath(shellPaths);
+  if (!existsSync(path)) return { workspaces: [], declines: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
+    if (!isRecord(parsed) || parsed.version !== 1 || !Array.isArray(parsed.workspaces)) {
+      return { workspaces: [], declines: [] };
+    }
+    const workspaces = parsed.workspaces
+      .map(parseRegisteredRecord)
+      .filter((entry): entry is RegisteredWorkspaceRecord => entry !== null);
+    const declineList = Array.isArray(parsed.declines) ? parsed.declines : [];
+    const declines = declineList
+      .map(parseDeclinedRecord)
+      .filter((entry): entry is DeclinedWorkspaceRecord => entry !== null);
+    return { workspaces, declines };
+  } catch {
+    return { workspaces: [], declines: [] };
+  }
+}
+
+/**
+ * Resolve `path` against the shared registration store SYNCHRONOUSLY: a direct
+ * on-disk read plus the SDK's pure resolveWorkspaceRegistration. `git` defaults
+ * to a real worktree-link probe (probeWorktreeLink spawns `git`), so a linked
+ * orchestration worktree of a registered repo resolves as covered without any
+ * extra wiring — the worktree-link inheritance the shared store provides.
+ * Callers that already have git metadata (or want to avoid the spawn, e.g. in
+ * a pure unit test) can pass it explicitly.
+ */
+export function resolveWorkspaceRegistrationSync(
+  shellPaths: StoreShellPaths,
+  path: string,
+  git?: WorkspaceGitMetadata,
+): WorkspaceResolution {
+  const snapshot = readSharedWorkspaceRegistrationSnapshotSync(shellPaths);
+  const gitMeta = git ?? probeWorktreeLink(path);
+  return resolveWorkspaceRegistration({
+    path,
+    git: gitMeta,
+    registrations: snapshot.workspaces,
+    declines: snapshot.declines,
+  });
+}
+
+/**
+ * Build a cheap, repeatable live-registration checker for one fixed workspace
+ * root. `probeWorktreeLink` (a `git` subprocess spawn) runs ONCE here, since a
+ * long-running process's working directory and its git-worktree relationship
+ * do not change mid-launch; every subsequent call only re-reads the shared
+ * registration JSON file (a small synchronous fs read) — cheap enough to call
+ * on every turn/agent-lifecycle event, unlike calling
+ * `resolveWorkspaceRegistrationSync` directly (which re-probes git every time).
+ *
+ * This is what makes registering a workspace mid-launch (writing to the shared
+ * store from a separate `goodvibes-agent workspaces register` invocation) take
+ * effect on the very next automatic-checkpoint-eligible event in an
+ * already-running process, without a restart: a caller that re-runs the
+ * returned function on each event always reads current on-disk state.
+ */
+export function createWorkspaceRegistrationLiveChecker(
+  shellPaths: StoreShellPaths,
+  path: string,
+): () => WorkspaceCoverageStatus {
+  const git = probeWorktreeLink(path);
+  return () => resolveWorkspaceRegistrationSync(shellPaths, path, git).status;
+}
+
+// ---------------------------------------------------------------------------
+// One-time migration: local per-user registry -> shared store
+// ---------------------------------------------------------------------------
+
+function legacyWorkspaceRegistryPath(shellPaths: StoreShellPaths): string {
+  return shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'checkpoints', 'registered-workspaces.json');
+}
+
+function migrationReceiptPath(shellPaths: StoreShellPaths): string {
+  return shellPaths.resolveUserPath('control-plane', 'workspace-registration-migration-receipt.json');
+}
+
+function atomicWriteJson(path: string, data: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tempPath = `${path}.tmp`;
+  writeFileSync(tempPath, `${JSON.stringify(data, null, 2)}\n`, 'utf-8');
+  renameSync(tempPath, path);
+}
+
+export interface WorkspaceRegistrationMigrationResult {
+  readonly sourcePath: string;
+  readonly recordsMigrated: number;
+  readonly recordsAlreadyPresent: number;
+  readonly migratedAt: string;
+}
+
+/**
+ * Migrate the local per-user registry into the shared store, exactly once.
+ *
+ * Runs synchronously (see this module's doc comment on why). Idempotent via a
+ * receipt file: once written, later calls (any process, any startup) return
+ * null immediately without touching either file again — even if the legacy
+ * file is still present, and even if an owner later unregisters a migrated
+ * root through the new store (a migrated-then-removed root must not come back
+ * on the next start). A missing legacy file is not an error and writes no
+ * receipt (nothing happened worth remembering); an unparsable legacy file
+ * migrates zero records but still writes a receipt so it is never retried.
+ *
+ * Returns null when nothing was migrated this call (already migrated, or no
+ * legacy file); a caller logs only a real migration.
+ */
+export function migrateLegacyWorkspaceRegistryIfNeeded(
+  shellPaths: StoreShellPaths,
+): WorkspaceRegistrationMigrationResult | null {
+  const receiptPath = migrationReceiptPath(shellPaths);
+  if (existsSync(receiptPath)) return null;
+
+  const legacyPath = legacyWorkspaceRegistryPath(shellPaths);
+  if (!existsSync(legacyPath)) return null;
+
+  let legacyRecords: RegisteredWorkspaceRecord[] = [];
+  try {
+    const parsed = JSON.parse(readFileSync(legacyPath, 'utf-8')) as unknown;
+    const list = isRecord(parsed) && Array.isArray(parsed.workspaces) ? parsed.workspaces : [];
+    legacyRecords = list
+      .map(parseRegisteredRecord)
+      .filter((entry): entry is RegisteredWorkspaceRecord => entry !== null);
+  } catch {
+    legacyRecords = [];
+  }
+
+  const sharedPath = sharedWorkspaceRegistrationStorePath(shellPaths);
+  const existing = readSharedWorkspaceRegistrationSnapshotSync(shellPaths);
+  const existingRoots = new Set(existing.workspaces.map((entry) => entry.root));
+  const merged = [...existing.workspaces];
+  let migrated = 0;
+  let alreadyPresent = 0;
+  for (const record of legacyRecords) {
+    if (existingRoots.has(record.root)) {
+      alreadyPresent += 1;
+      continue;
+    }
+    existingRoots.add(record.root);
+    merged.push(record);
+    migrated += 1;
+  }
+
+  if (migrated > 0) {
+    atomicWriteJson(sharedPath, { version: 1, workspaces: merged, declines: existing.declines });
+  }
+
+  const result: WorkspaceRegistrationMigrationResult = {
+    sourcePath: legacyPath,
+    recordsMigrated: migrated,
+    recordsAlreadyPresent: alreadyPresent,
+    migratedAt: new Date().toISOString(),
+  };
+  atomicWriteJson(receiptPath, result);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// First-start registration prompt support
+// ---------------------------------------------------------------------------
+
+function canonicalPath(path: string): string {
+  try {
+    return existsSync(path) ? realpathSync(path) : resolve(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/**
+ * Would the shared store refuse to register `root` as too broad? Mirrors the
+ * SDK's broadRootReason (checkpoint/root-guard.ts — not part of the public
+ * platform/workspace export, so replicated here at the same single-purpose
+ * level as this module's other store-internal-logic mirrors) closely enough
+ * for a PRE-registration "would this be refused?" check. Used only to decide
+ * whether to OFFER registration in the first-start prompt; the store's own
+ * add() remains the authoritative guard at write time, never bypassed here.
+ */
+export function isBroadWorkspaceRoot(shellPaths: StoreShellPaths, root: string): boolean {
+  const canonicalRoot = canonicalPath(root);
+  if (parse(canonicalRoot).root === canonicalRoot) return true;
+  if (canonicalRoot === canonicalPath(shellPaths.homeDirectory)) return true;
+  if (canonicalRoot === canonicalPath(shellPaths.resolveUserPath())) return true;
+  return false;
+}
+
+/**
+ * Resolve a first-start registration prompt's answer against the shared
+ * store: fire-and-forget (the caller is a keypress handler, not an async
+ * context) but never a silent failure — a write error is logged, not lost.
+ */
+export function answerWorkspaceRegistrationPrompt(shellPaths: StoreShellPaths, root: string, accepted: boolean): void {
+  const store = createWorkspaceRegistrationStore(shellPaths);
+  const outcome = accepted ? store.add(root) : store.decline(root);
+  void outcome.catch((error: unknown) => {
+    logger.error('Failed to persist workspace registration prompt answer', { root, accepted, error: summarizeError(error) });
+  });
+}