@pellux/goodvibes-agent 1.9.1 → 1.10.0

package/src/cli/launch-auto-update.ts

@@ -0,0 +1,218 @@
+/**
+ * Launch-time self-update — the agent lands on the newest release at startup
+ * so an installed binary never drifts behind. At interactive launch (before
+ * any runtime bootstrap or terminal mode change) this runs a quick version
+ * check and, when a newer release exists, installs it through the SAME
+ * checksum-verified download/verify/swap path `/update apply` uses
+ * (src/input/commands/update-runtime.ts — there is deliberately no second
+ * updater), then asks the caller to restart onto the new binary.
+ *
+ * Honesty rules, in both directions:
+ *   - the check gets a short timeout; when it cannot complete (offline, slow
+ *     network) the CURRENT version starts with exactly one line saying the
+ *     check was skipped — launch is never held hostage by the network.
+ *   - a successful update restarts into the new binary and the restarted
+ *     process prints a receipt naming both versions, so the swap is never
+ *     silent.
+ *   - every swap keeps the outgoing file at `<path>.previous`; rollback is
+ *     one command (`/update rollback`).
+ *
+ * The feature is a real configurable setting (`update.autoUpdateAtLaunch` in
+ * settings.json, read via readUpdateSettings): default ON, off with an
+ * explicit false. Only binary installs self-update — a package-managed
+ * install or a from-source dev checkout skips with one honest line naming
+ * why (a swap there would fight the package manager, or there is no compiled
+ * file to swap; see detectInstallKind).
+ *
+ * Everything effectful is injectable; tests drive the decision logic with a
+ * stubbed fetch, a stubbed apply, and pinned fixture versions — never the
+ * live build VERSION and never the real network.
+ */
+import { spawnSync } from 'node:child_process';
+import { detectInstallKind, normalizeVersion, type UpdateFetchLike } from '../runtime/update-check.ts';
+import { applyUpdate, checkForUpdate, type ApplyUpdateOptions } from '../input/commands/update-runtime.ts';
+import { readUpdateSettings, type UpdateSettings } from '../config/update-settings.ts';
+import type { ConfigManager } from '../config/index.ts';
+import { VERSION } from '../version.ts';
+
+/**
+ * Set on the restarted process by restartOntoUpdatedBinary, carrying the
+ * version that performed the update. Its presence means "an update already
+ * happened this launch": the restarted process prints the receipt and skips
+ * its own check, which also makes an update-that-didn't-change-the-version
+ * structurally unable to restart-loop.
+ */
+export const LAUNCH_UPDATED_FROM_ENV = 'GOODVIBES_AGENT_LAUNCH_UPDATED_FROM';
+
+/** Default budget for the launch-time version check; user-tunable via update.launchCheckTimeoutMs. */
+export const LAUNCH_UPDATE_CHECK_TIMEOUT_MS = 2500;
+
+export type LaunchAutoUpdateOutcome =
+  | {
+      readonly action: 'continue';
+      readonly reason: 'just-updated' | 'disabled' | 'not-swappable-install' | 'already-current' | 'check-skipped' | 'update-failed';
+    }
+  | { readonly action: 'restart'; readonly latestTag: string };
+
+export interface RunLaunchAutoUpdateOptions {
+  readonly fetchImpl: UpdateFetchLike;
+  readonly execPath: string;
+  readonly platform: NodeJS.Platform;
+  readonly arch: string;
+  readonly currentVersion: string;
+  readonly settings: UpdateSettings;
+  readonly env: NodeJS.ProcessEnv;
+  readonly print: (line: string) => void;
+  /** Injectable so tests observe the install step instead of swapping real files. */
+  readonly apply?: (options: ApplyUpdateOptions) => Promise<void>;
+  readonly timeoutMs?: number;
+}
+
+/** Resolves to 'timeout' when `promise` does not settle within `ms`; the timer never keeps the process alive. */
+async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T | 'timeout'> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<'timeout'>((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), ms);
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The launch-time decision: receipt-and-continue (restarted process), skip
+ * (disabled / unswappable / current / unreachable), install-and-restart, or
+ * fail-and-continue on the current version. Never throws.
+ */
+export async function runLaunchAutoUpdate(options: RunLaunchAutoUpdateOptions): Promise<LaunchAutoUpdateOutcome> {
+  const updatedFrom = options.env[LAUNCH_UPDATED_FROM_ENV];
+  if (typeof updatedFrom === 'string' && updatedFrom.length > 0) {
+    // Consumed here so sessions spawned from inside this one never inherit it.
+    delete options.env[LAUNCH_UPDATED_FROM_ENV];
+    options.print(`auto-update: updated from v${normalizeVersion(updatedFrom)} to v${normalizeVersion(options.currentVersion)} at launch`);
+    return { action: 'continue', reason: 'just-updated' };
+  }
+
+  if (!(options.settings.autoUpdateAtLaunch ?? true)) {
+    return { action: 'continue', reason: 'disabled' };
+  }
+
+  const installKind = detectInstallKind(options.execPath);
+  if (installKind !== 'binary') {
+    // Honest, single-line skip: only a compiled release binary can be swapped
+    // in place, and the skip should never look like an update happened.
+    options.print(installKind === 'source'
+      ? 'auto-update skipped: running from source (dev checkout)'
+      : 'auto-update skipped: package-managed install — update with: bun add -g @pellux/goodvibes-agent');
+    return { action: 'continue', reason: 'not-swappable-install' };
+  }
+
+  const timeoutMs = options.timeoutMs ?? options.settings.launchCheckTimeoutMs ?? LAUNCH_UPDATE_CHECK_TIMEOUT_MS;
+  let check: Awaited<ReturnType<typeof checkForUpdate>> | 'timeout';
+  try {
+    check = await withTimeout(checkForUpdate(options.fetchImpl, options.currentVersion), timeoutMs);
+  } catch {
+    check = 'timeout';
+  }
+  if (check === 'timeout') {
+    options.print('update check skipped: offline');
+    return { action: 'continue', reason: 'check-skipped' };
+  }
+  if (check.isCurrent) {
+    return { action: 'continue', reason: 'already-current' };
+  }
+
+  try {
+    const apply = options.apply ?? applyUpdate;
+    await apply({
+      fetchImpl: options.fetchImpl,
+      execPath: options.execPath,
+      platform: options.platform,
+      arch: options.arch,
+      currentVersion: options.currentVersion,
+      print: options.print,
+    });
+    options.print(`auto-update: ${check.latestTag} installed — restarting onto the new version`);
+    return { action: 'restart', latestTag: check.latestTag };
+  } catch (error) {
+    options.print(
+      `auto-update failed: ${error instanceof Error ? error.message : String(error)} — starting the current version v${normalizeVersion(options.currentVersion)}`,
+    );
+    return { action: 'continue', reason: 'update-failed' };
+  }
+}
+
+export interface SelfUpdateAtLaunchParams {
+  readonly configManager: Pick<ConfigManager, 'getRaw'>;
+  readonly stdout: { write(chunk: string): unknown };
+}
+
+/**
+ * The complete launch wiring for main(), with real host inputs: run the
+ * decision above; when an update was installed, restart onto the swapped
+ * binary and EXIT THIS PROCESS with the new instance's exit code (this call
+ * never returns in that case); otherwise return the honest lines that were
+ * printed (receipt / skipped check / failed update) so the caller can
+ * re-surface them through the system message router once it exists — the
+ * stdout copies written here are wiped by the agent's alternate screen.
+ */
+export async function selfUpdateAtLaunch(params: SelfUpdateAtLaunchParams): Promise<readonly string[]> {
+  const lines: string[] = [];
+  const outcome = await runLaunchAutoUpdate({
+    fetchImpl: fetch as UpdateFetchLike,
+    execPath: process.execPath,
+    platform: process.platform,
+    arch: process.arch,
+    currentVersion: VERSION,
+    settings: readUpdateSettings(params.configManager),
+    env: process.env,
+    print: (line) => {
+      lines.push(line);
+      params.stdout.write(`${line}\n`);
+    },
+  });
+  if (outcome.action === 'restart') {
+    process.exit(
+      restartOntoUpdatedBinary({
+        execPath: process.execPath,
+        argv: process.argv.slice(2),
+        env: process.env,
+        fromVersion: VERSION,
+      }),
+    );
+  }
+  return lines;
+}
+
+export interface RestartOntoUpdatedBinaryOptions {
+  readonly execPath: string;
+  readonly argv: readonly string[];
+  readonly env: NodeJS.ProcessEnv;
+  /** The version that performed the update — the restarted process prints it in its receipt line. */
+  readonly fromVersion: string;
+  /** Injectable so tests observe the restart instead of spawning a process. */
+  readonly spawn?: (execPath: string, argv: readonly string[], env: NodeJS.ProcessEnv) => number | null;
+}
+
+/**
+ * Runs the (just-swapped) binary at execPath with the original CLI arguments
+ * and an inherited terminal, blocking until it exits, and returns its exit
+ * code for the caller to process.exit with. The receipt marker travels in the
+ * child's environment, never on the command line.
+ */
+export function restartOntoUpdatedBinary(options: RestartOntoUpdatedBinaryOptions): number {
+  const spawn =
+    options.spawn ??
+    ((execPath: string, argv: readonly string[], env: NodeJS.ProcessEnv) =>
+      spawnSync(execPath, [...argv], { stdio: 'inherit', env }).status);
+  const status = spawn(options.execPath, options.argv, {
+    ...options.env,
+    [LAUNCH_UPDATED_FROM_ENV]: options.fromVersion,
+  });
+  return status ?? 0;
+}

package/src/cli/relay-command.ts

@@ -1,4 +1,4 @@
-import { FEATURE_FLAG_MAP } from '@pellux/goodvibes-sdk/platform/runtime/state';
+import { FEATURE_SETTINGS } from '@pellux/goodvibes-sdk/platform/runtime/state';
 import type { CliCommandOutput } from './types.ts';
 import type { CliCommandRuntime } from './management.ts';
 
@@ -35,11 +35,11 @@ function jsonOrText(runtime: CliCommandRuntime, value: unknown, text: string): s
 }
 
 function relayConnectFlagSummary(): { readonly id: string; readonly name: string; readonly defaultState: string } {
-  const flag = FEATURE_FLAG_MAP.get('relay-connect');
+  const feature = FEATURE_SETTINGS.find((entry) => entry.id === 'relay-connect');
   return {
     id: 'relay-connect',
-    name: flag?.name ?? 'Outbound Zero-Knowledge Relay',
-    defaultState: flag?.defaultState ?? 'disabled',
+    name: feature?.name ?? 'Outbound Zero-Knowledge Relay',
+    defaultState: feature === undefined ? 'disabled' : feature.defaultEnabled ? 'enabled' : 'disabled',
   };
 }
 

package/src/cli/service-posture.ts

@@ -226,9 +226,9 @@ export function formatCliServicePosture(posture: CliServicePosture, json = false
   return [
     'GoodVibes Agent connected-host diagnostics',
     '  lifecycle owner: outside goodvibes-agent',
-    '  Agent starts connected host: no',
+    '  Agent starts connected host: only at boot, when it is installed but stopped',
     `  external host config present: ${yesNo(posture.config.enabled)}`,
-    '  external host lifecycle config: ignored by Agent',
+    '  external host lifecycle config: only the service name is read, for the boot start check',
     `  daemon considered enabled: ${yesNo(posture.config.daemonEnabled)}`,
     `  log: ${posture.log.path ?? 'n/a'} (${posture.log.exists ? 'present' : 'missing'})`,
     ...(posture.log.readError ? [`  log read error: ${posture.log.readError}`] : []),

package/src/cli/tui-startup.ts

@@ -45,6 +45,37 @@ export function formatFatalStartupErrorForLog(error: unknown): string {
   return fatalStartupStack(error);
 }
 
+/**
+ * The one fatal-startup exit path for main(): log the full detail, print the
+ * user-facing explanation to stderr, and exit 1. Lives beside the two
+ * formatters it composes so main.ts carries no error-formatting plumbing of
+ * its own. Both writes are individually best-effort — a failing logger or a
+ * torn-down stderr must never hide the original launch failure.
+ */
+export function reportFatalStartupError(
+  err: unknown,
+  options: FatalStartupFormatOptions,
+  sinks: {
+    readonly logError: (message: string, context: Record<string, unknown>) => void;
+    readonly writeStderr: (chunk: string) => void;
+    readonly exit: (code: number) => void;
+  },
+): void {
+  const detail = formatFatalStartupErrorForLog(err);
+  try {
+    sinks.logError('Fatal error', { error: detail });
+  } catch {
+    // Startup diagnostics must never hide the original launch failure.
+  }
+  const userDetail = formatFatalStartupErrorForUser(err, options);
+  try {
+    sinks.writeStderr(`${options.binary} failed to launch:\n${userDetail}\n`);
+  } catch {
+    // Ignore secondary stderr failures during process teardown.
+  }
+  sinks.exit(1);
+}
+
 export function formatFatalStartupErrorForUser(error: unknown, options: FatalStartupFormatOptions): string {
   if (options.debug === true) return fatalStartupStack(error);
 

package/src/cli/workspaces-command.ts

@@ -6,6 +6,7 @@ import {
   createWorkspaceRegistrationStore,
   migrateLegacyWorkspaceRegistryIfNeeded,
   normalizeWorkspaceRoot,
+  registerWorkspaceForCheckpoints,
 } from '../config/workspace-registration.ts';
 import type { CliCommandOutput } from './types.ts';
 import type { CliCommandRuntime } from './management.ts';
@@ -108,7 +109,10 @@ export async function handleWorkspacesCommand(runtime: CliCommandRuntime): Promi
     }
     const label = flagValue(rawRest, ['--label']) ?? undefined;
     try {
-      const result = await store.add(target, label ? { label } : undefined);
+      // Explicit registration: registers AND stamps checkpoint-eligibility, so
+      // this workspace becomes an owner-opted checkpoint boundary (a plain
+      // store.add would register without enabling automatic checkpoints).
+      const result = await registerWorkspaceForCheckpoints(shellPaths, 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`;

package/src/cli-flags.ts

@@ -5,7 +5,7 @@ export {
   applyRuntimeConfigValue,
   applyRuntimeCommandEndpointFlagOverrides,
   applyRuntimeEndpointFlagOverrides,
-  applyRuntimeFeatureFlagOverrides,
+  applyRuntimeFeatureOverrides,
   applyRuntimeUrlOverride,
   handleGoodVibesCliCommand,
   parseGoodVibesCli,

package/src/config/index.ts

@@ -8,7 +8,7 @@
 
 export { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 export type { DeepReadonly } from '@pellux/goodvibes-sdk/platform/config';
-export type { GoodVibesConfig, ConfigKey, ConfigValue, ConfigSetting, PermissionMode, PermissionAction, PermissionsToolConfig, NotificationsConfig, PersistedFlagState } from '@pellux/goodvibes-sdk/platform/config';
+export type { GoodVibesConfig, ConfigKey, ConfigValue, ConfigSetting, PermissionMode, PermissionAction, PermissionsToolConfig, NotificationsConfig } from '@pellux/goodvibes-sdk/platform/config';
 export { DEFAULT_CONFIG, CONFIG_SCHEMA } from '@pellux/goodvibes-sdk/platform/config';
 export { ConfigError } from '@pellux/goodvibes-sdk/platform/types';
 

package/src/config/update-settings.ts

@@ -0,0 +1,45 @@
+/**
+ * `update.*` — launch-time self-update behavior.
+ *
+ * The SDK owns settings.json's typed schema, but its loader deep-merges user
+ * JSON over the defaults and keeps unknown top-level namespaces through
+ * `getRaw()` (the same passthrough contract checkpoint-settings.ts documents),
+ * so the agent keeps its own `update` namespace in the same file and reads it
+ * back here.
+ *
+ * The reader hand-validates each field and returns a PARTIAL object holding
+ * only the keys the user actually set to a well-typed value — a missing or
+ * malformed block degrades to "use the built-in defaults", never a crash. The
+ * defaults themselves live in the consumer (src/cli/launch-auto-update.ts):
+ * the feature defaults ON for binary installs, per the recorded owner
+ * directive that clients update on start, and `update.autoUpdateAtLaunch:
+ * false` is the explicit, persisted off switch.
+ */
+import type { ConfigManager } from './index.ts';
+
+type RawRecord = Record<string, unknown>;
+
+export interface UpdateSettings {
+  /** Check for a newer release at launch and install it before starting. Default: true. */
+  readonly autoUpdateAtLaunch?: boolean;
+  /** How long the launch-time version check may take before it is skipped. Defaults to 2500; clamped to [250, 30000]. */
+  readonly launchCheckTimeoutMs?: number;
+}
+
+const LAUNCH_CHECK_MIN_TIMEOUT_MS = 250;
+const LAUNCH_CHECK_MAX_TIMEOUT_MS = 30_000;
+
+/** Read `update.*` from settings.json, validating and clamping the timeout. */
+export function readUpdateSettings(configManager: Pick<ConfigManager, 'getRaw'>): UpdateSettings {
+  const raw = configManager.getRaw() as unknown as RawRecord;
+  const block = raw['update'];
+  if (!block || typeof block !== 'object' || Array.isArray(block)) return {};
+  const src = block as RawRecord;
+  const out: { autoUpdateAtLaunch?: boolean; launchCheckTimeoutMs?: number } = {};
+  if (typeof src['autoUpdateAtLaunch'] === 'boolean') out.autoUpdateAtLaunch = src['autoUpdateAtLaunch'];
+  const timeout = src['launchCheckTimeoutMs'];
+  if (typeof timeout === 'number' && Number.isFinite(timeout) && timeout > 0) {
+    out.launchCheckTimeoutMs = Math.min(LAUNCH_CHECK_MAX_TIMEOUT_MS, Math.max(LAUNCH_CHECK_MIN_TIMEOUT_MS, Math.floor(timeout)));
+  }
+  return out;
+}

package/src/config/workspace-registration.ts

@@ -4,6 +4,7 @@ import type { ShellPathService } from '@/runtime/index.ts';
 import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import {
   WorkspaceRegistrationStore,
+  type RegisterWorkspaceResult,
   resolveWorkspaceRegistration,
   normalizeWorkspaceRoot,
   probeWorktreeLink,
@@ -23,6 +24,27 @@ export type {
   WorkspaceResolution,
 } from '@pellux/goodvibes-sdk/platform/workspace';
 
+/**
+ * CHECKPOINT-ELIGIBILITY BOUNDARY (owner ruling: the checkpoint boundary stays
+ * EXPLICIT, never silently widened).
+ *
+ * The shared registration store is ONE file the whole platform reads and writes
+ * (~/.goodvibes/control-plane/workspace-registrations.json). The TUI's first-open
+ * self-recording writes a plain {@link RegisteredWorkspaceRecord} to it for any
+ * directory a user merely opens — so "registered in the store" can no longer mean
+ * "the owner opted this workspace into automatic checkpoints". The agent's
+ * checkpoint boundary must therefore consume ONLY records the owner EXPLICITLY
+ * registered for checkpoints, marked by `checkpointEligible === true`.
+ *
+ * The SDK record schema natively carries both fields (typed on
+ * {@link RegisteredWorkspaceRecord}): `origin` — which flow wrote/stamped the
+ * record, provenance only — and `checkpointEligible`, where ABSENT MEANS FALSE.
+ * The store's `add` stamps/upgrades them typed, and absent options never strip
+ * an existing stamp, so one surface's plain self-recording cannot demote
+ * another consumer's eligibility.
+ */
+export const AGENT_EXPLICIT_REGISTRATION_ORIGIN = 'agent-explicit-registration';
+
 /**
  * Shared registered-workspace registry (SDK 1.6.1 platform/workspace/registration),
  * the successor to this fork's local per-user JSON registry
@@ -76,7 +98,15 @@ function parseRegisteredRecord(value: unknown): RegisteredWorkspaceRecord | null
   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 } : {}) };
+  const origin = readString(value.origin);
+  return {
+    root: normalizeWorkspaceRoot(root),
+    registeredAt,
+    ...(label ? { label } : {}),
+    ...(origin ? { origin } : {}),
+    // Strictly `true` only; any other value (including absent) is not eligible.
+    ...(value.checkpointEligible === true ? { checkpointEligible: true } : {}),
+  };
 }
 
 function parseDeclinedRecord(value: unknown): DeclinedWorkspaceRecord | null {
@@ -143,26 +173,54 @@ export function resolveWorkspaceRegistrationSync(
 }
 
 /**
- * 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).
+ * Resolve `path` against ONLY the checkpoint-eligible registrations — the
+ * boundary the automatic/explicit checkpoint gate consumes. Identical to
+ * {@link resolveWorkspaceRegistrationSync} except the registrations are filtered
+ * to `checkpointEligible === true` first, so a plain TUI self-record (registered
+ * in the shared store, but never explicitly opted into checkpoints) resolves as
+ * NOT covered here even though the general resolver reports it registered.
+ * Worktree-link inheritance still applies: a linked worktree of a checkpoint-
+ * eligible main repo resolves covered.
+ */
+export function resolveCheckpointEligibilitySync(
+  shellPaths: StoreShellPaths,
+  path: string,
+  git?: WorkspaceGitMetadata,
+): WorkspaceResolution {
+  const snapshot = readSharedWorkspaceRegistrationSnapshotSync(shellPaths);
+  const eligible = snapshot.workspaces.filter((entry) => entry.checkpointEligible === true);
+  const gitMeta = git ?? probeWorktreeLink(path);
+  return resolveWorkspaceRegistration({
+    path,
+    git: gitMeta,
+    registrations: eligible,
+    declines: snapshot.declines,
+  });
+}
+
+/**
+ * Build a cheap, repeatable live checkpoint-eligibility 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
+ * `resolveCheckpointEligibilitySync` 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
+ * This is what makes registering a workspace mid-launch (an explicit
+ * `goodvibes-agent workspaces register` that stamps `checkpointEligible`) 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.
+ * already-running process, without a restart: a caller that re-runs the returned
+ * function on each event always reads current on-disk state. It consumes ONLY
+ * checkpoint-eligible records, so a directory a TUI user merely opened never
+ * silently becomes checkpoint-eligible to the agent.
  */
 export function createWorkspaceRegistrationLiveChecker(
   shellPaths: StoreShellPaths,
   path: string,
 ): () => WorkspaceCoverageStatus {
   const git = probeWorktreeLink(path);
-  return () => resolveWorkspaceRegistrationSync(shellPaths, path, git).status;
+  return () => resolveCheckpointEligibilitySync(shellPaths, path, git).status;
 }
 
 // ---------------------------------------------------------------------------
@@ -184,6 +242,142 @@ function atomicWriteJson(path: string, data: unknown): void {
   renameSync(tempPath, path);
 }
 
+interface RawSharedStoreDoc {
+  readonly version: 1;
+  readonly workspaces: unknown[];
+  readonly declines: unknown[];
+}
+
+/**
+ * Raw read of the shared store document that preserves EVERY field on EVERY
+ * record verbatim — unlike {@link readSharedWorkspaceRegistrationSnapshotSync},
+ * which strips each record to the known shape. Used by the synchronous
+ * eligibility backfill below so it never drops another surface's fields (or a
+ * future one) when it rewrites the file. A missing/unparsable file reads as an
+ * empty document.
+ */
+function readSharedStoreRawDoc(path: string): RawSharedStoreDoc {
+  if (!existsSync(path)) return { version: 1, workspaces: [], declines: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
+    if (!isRecord(parsed) || parsed.version !== 1 || !Array.isArray(parsed.workspaces)) {
+      return { version: 1, workspaces: [], declines: [] };
+    }
+    return {
+      version: 1,
+      workspaces: parsed.workspaces,
+      declines: Array.isArray(parsed.declines) ? parsed.declines : [],
+    };
+  } catch {
+    return { version: 1, workspaces: [], declines: [] };
+  }
+}
+
+/**
+ * The agent's EXPLICIT checkpoint-registration path: one typed store `add` that
+ * registers `root` (the SDK's own root-guarded write) AND stamps it
+ * `checkpointEligible: true` with the agent-explicit origin — the store's `add`
+ * carries both fields natively, upgrading an already-present record's stamp in
+ * the same call. This is the ONLY way a record becomes checkpoint-eligible at
+ * write time — a plain SDK `add` (the TUI's first-open self-recording) never
+ * sets the flag, so opening a directory in the TUI cannot widen the agent's
+ * checkpoint boundary. Returns the SDK's register result unchanged so callers
+ * keep their existing messaging.
+ */
+export async function registerWorkspaceForCheckpoints(
+  shellPaths: StoreShellPaths,
+  root: string,
+  opts?: { readonly label?: string },
+): Promise<RegisterWorkspaceResult> {
+  const store = createWorkspaceRegistrationStore(shellPaths);
+  return await store.add(root, {
+    ...(opts?.label ? { label: opts.label } : {}),
+    origin: AGENT_EXPLICIT_REGISTRATION_ORIGIN,
+    checkpointEligible: true,
+  });
+}
+
+function checkpointEligibilityBackfillReceiptPath(shellPaths: StoreShellPaths): string {
+  return shellPaths.resolveUserPath('control-plane', 'workspace-checkpoint-eligibility-backfill-receipt.json');
+}
+
+export interface CheckpointEligibilityBackfillResult {
+  readonly sourcePath: string;
+  readonly recordsStamped: number;
+  readonly backfilledAt: string;
+}
+
+/**
+ * One-time boot backfill that stamps `checkpointEligible: true` on the shared-
+ * store records that came from the agent's OWN explicit registrations, so the
+ * new eligibility boundary does not retroactively drop workspaces the owner had
+ * already opted into checkpoints before this flag existed. This is exactly the
+ * "the consumer that owns checkpointing re-stamps its own roots on boot" the
+ * SDK's record schema documents for pre-provenance records; it writes the raw
+ * document directly (field-preserving, see readSharedStoreRawDoc) because it
+ * runs inside the synchronous createRuntimeServices path where the async typed
+ * store cannot be awaited.
+ *
+ * The honest source of "which records were the agent's explicit list" is the
+ * legacy per-user registry file (`<surface>/checkpoints/registered-workspaces.json`)
+ * — written only by `workspaces register`, and never deleted by the migration
+ * that imported it into the shared store. Every root in it is an explicit owner
+ * opt-in, so the matching shared-store record is stamped eligible. This covers
+ * both a fresh import (records just migrated in without the flag) and a machine
+ * where the import already ran (the earlier commit that migrated the explicit
+ * list into the shared store predates this flag).
+ *
+ * Receipt-gated so it runs once. A missing legacy file writes no receipt
+ * (there is no explicit-list source to derive from, and nothing worth
+ * remembering); records registered afresh through
+ * {@link registerWorkspaceForCheckpoints} are already stamped at write time.
+ * Returns null when nothing was backfilled this call.
+ */
+export function backfillCheckpointEligibilityIfNeeded(
+  shellPaths: StoreShellPaths,
+): CheckpointEligibilityBackfillResult | null {
+  const receiptPath = checkpointEligibilityBackfillReceiptPath(shellPaths);
+  if (existsSync(receiptPath)) return null;
+
+  const legacyPath = legacyWorkspaceRegistryPath(shellPaths);
+  if (!existsSync(legacyPath)) return null;
+
+  const legacyRoots = new Set<string>();
+  try {
+    const parsed = JSON.parse(readFileSync(legacyPath, 'utf-8')) as unknown;
+    const list = isRecord(parsed) && Array.isArray(parsed.workspaces) ? parsed.workspaces : [];
+    for (const entry of list) {
+      if (!isRecord(entry)) continue;
+      const root = readString(entry.root);
+      if (root) legacyRoots.add(normalizeWorkspaceRoot(root));
+    }
+  } catch {
+    // An unparsable legacy file yields no roots but still writes a receipt below
+    // so this is never retried.
+  }
+
+  const sharedPath = sharedWorkspaceRegistrationStorePath(shellPaths);
+  const doc = readSharedStoreRawDoc(sharedPath);
+  let stamped = 0;
+  const workspaces = doc.workspaces.map((entry) => {
+    if (!isRecord(entry)) return entry;
+    const root = normalizeWorkspaceRoot(readString(entry.root));
+    if (!legacyRoots.has(root) || entry.checkpointEligible === true) return entry;
+    stamped += 1;
+    const existingOrigin = readString(entry.origin);
+    return { ...entry, checkpointEligible: true, origin: existingOrigin || AGENT_EXPLICIT_REGISTRATION_ORIGIN };
+  });
+  if (stamped > 0) atomicWriteJson(sharedPath, { version: 1, workspaces, declines: doc.declines });
+
+  const result: CheckpointEligibilityBackfillResult = {
+    sourcePath: legacyPath,
+    recordsStamped: stamped,
+    backfilledAt: new Date().toISOString(),
+  };
+  atomicWriteJson(receiptPath, result);
+  return result;
+}
+
 export interface WorkspaceRegistrationMigrationResult {
   readonly sourcePath: string;
   readonly recordsMigrated: number;
@@ -291,8 +485,13 @@ export function isBroadWorkspaceRoot(shellPaths: StoreShellPaths, root: string):
  * 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);
+  // Accepting the first-start prompt is an EXPLICIT owner opt-in, so it goes
+  // through registerWorkspaceForCheckpoints (registers AND stamps eligibility) —
+  // not a plain store.add, which would register without making the workspace
+  // checkpoint-eligible. Declining stays a plain decline.
+  const outcome = accepted
+    ? registerWorkspaceForCheckpoints(shellPaths, root)
+    : createWorkspaceRegistrationStore(shellPaths).decline(root);
   void outcome.catch((error: unknown) => {
     logger.error('Failed to persist workspace registration prompt answer', { root, accepted, error: summarizeError(error) });
   });