@pellux/goodvibes-daemon 1.28.0

package/src/runtime/trigger-services.ts

@@ -0,0 +1,62 @@
+import { TriggerManager } from '@pellux/goodvibes-sdk/platform/triggers';
+import { createBunStreamHost, createProcessManagerTriggerHost, createTriggerActionExecutor } from '@pellux/goodvibes-sdk/platform/triggers';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { AgentManager, ProcessManager } from '@pellux/goodvibes-sdk/platform/tools';
+import type { SharedSessionBroker } from '@pellux/goodvibes-sdk/platform/control-plane';
+import type { ShellPathService } from '@/runtime/index.ts';
+
+/**
+ * The trigger family: stream watchers, on-exit process triggers, and condition
+ * checks, supervised as one.
+ *
+ * This daemon composes the full family and feeds the manager to the fleet as
+ * its trigger supervisor, so a trigger defined against the daemon fires
+ * reliably. The daemon is the right process to own it — it is the one that
+ * stays running.
+ *
+ * Two things about the shape are load-bearing:
+ *  - `config` is a CLOSURE over the config manager rather than a snapshot, so
+ *    toggling `watchers.triggers.*` takes effect on the next read instead of at
+ *    the next restart.
+ *  - the process host is ProcessManager-backed, so a supervised on-exit child
+ *    inherits the same credential-environment scrub, live output collection and
+ *    SIGTERM/SIGKILL watchdog as any other background command the daemon runs.
+ */
+export function createTriggerServices(deps: {
+  readonly configManager: ConfigManager;
+  readonly shellPaths: ShellPathService;
+  readonly surfaceRoot: string;
+  readonly agentManager: AgentManager;
+  readonly processManager: ProcessManager;
+  readonly sessionBroker: Pick<SharedSessionBroker, 'getSession'>;
+}): TriggerManager {
+  const { configManager } = deps;
+  return new TriggerManager({
+    storePath: deps.shellPaths.resolveProjectPath(deps.surfaceRoot, 'triggers.json'),
+    config: () => ({
+      enabled: configManager.get('watchers.triggers.enabled'),
+      backoffLadderMs: configManager.get('watchers.triggers.backoffLadderMs'),
+      breakerStrikes: configManager.get('watchers.triggers.breakerStrikes'),
+      defaultCheckIntervalMs: configManager.get('watchers.triggers.defaultCheckIntervalMs'),
+      probeTimeoutMs: configManager.get('watchers.triggers.probeTimeoutMs'),
+      maxConcurrentChecks: configManager.get('watchers.triggers.maxConcurrentChecks'),
+      observationRingSize: configManager.get('watchers.triggers.observationRingSize'),
+      runHistoryLimit: configManager.get('watchers.triggers.runHistoryLimit'),
+      runHistoryTtlHours: configManager.get('watchers.triggers.runHistoryTtlHours'),
+      eventLogLimit: configManager.get('watchers.triggers.eventLogLimit'),
+      eventLogTtlHours: configManager.get('watchers.triggers.eventLogTtlHours'),
+      sweepIntervalMs: configManager.get('watchers.triggers.sweepIntervalMs'),
+      supervisionTickMs: configManager.get('watchers.triggers.supervisionTickMs'),
+      streamQueueLimit: configManager.get('watchers.triggers.streamQueueLimit'),
+      streamBatchLines: configManager.get('watchers.triggers.streamBatchLines'),
+      streamBatchIntervalMs: configManager.get('watchers.triggers.streamBatchIntervalMs'),
+      onExitMaxDurationMs: configManager.get('watchers.triggers.onExitMaxDurationMs'),
+      onExitStdin: configManager.get('watchers.triggers.onExitStdin'),
+      outputTailBytes: configManager.get('watchers.triggers.outputTailBytes'),
+    }),
+    actions: createTriggerActionExecutor({ agents: deps.agentManager, processManager: deps.processManager }),
+    processHost: createProcessManagerTriggerHost(deps.processManager),
+    streamHost: createBunStreamHost(),
+    sessionIsLive: (sessionId: string) => deps.sessionBroker.getSession(sessionId) !== null,
+  });
+}

package/src/runtime/trust/checkpoint-eligibility.ts

@@ -0,0 +1,138 @@
+import { existsSync, readFileSync } from 'node:fs';
+import type { ShellPathService } from '@/runtime/index.ts';
+import {
+  normalizeWorkspaceRoot,
+  probeWorktreeLink,
+  resolveWorkspaceRegistration,
+  type DeclinedWorkspaceRecord,
+  type RegisteredWorkspaceRecord,
+  type WorkspaceCoverageStatus,
+  type WorkspaceGitMetadata,
+  type WorkspaceResolution,
+} from '@pellux/goodvibes-sdk/platform/workspace';
+
+/**
+ * Checkpoint eligibility, read live off the shared workspace-registration store.
+ *
+ * The daemon takes automatic checkpoints on turn and agent-run lifecycle events.
+ * Which workspaces that is allowed to happen in is the owner's registered-
+ * workspaces-only ruling: only a workspace that was EXPLICITLY registered for
+ * checkpoints (`checkpointEligible`) qualifies, and a directory somebody merely
+ * opened in a surface never silently becomes checkpoint-eligible.
+ *
+ * This read is synchronous by design. The decision is made per lifecycle event,
+ * inside a subscription callback that cannot await, and it has to reflect the
+ * store as it is on disk RIGHT NOW — registering a workspace while the daemon is
+ * running has to take effect on the next eligible event, not on the next
+ * restart. The SDK's resolver is pure, so the only I/O is one small JSON read
+ * plus a single git worktree probe amortized at construction.
+ */
+
+export type StoreShellPaths = Pick<ShellPathService, 'resolveUserPath' | 'homeDirectory'>;
+
+/** Path of the shared store's JSON document — the same path the SDK's gateway verb group constructs its own store over. */
+export function sharedWorkspaceRegistrationStorePath(shellPaths: StoreShellPaths): string {
+  return shellPaths.resolveUserPath('control-plane', 'workspace-registrations.json');
+}
+
+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);
+  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 {
+  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
+ * validation 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 ONLY the checkpoint-eligible registrations — the
+ * boundary the automatic and explicit checkpoint gates consume. Worktree-link
+ * inheritance still applies: a linked worktree of a checkpoint-eligible main
+ * repository resolves as 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, which is cheap enough to call on every
+ * turn/agent-lifecycle event.
+ */
+export function createWorkspaceRegistrationLiveChecker(
+  shellPaths: StoreShellPaths,
+  path: string,
+): () => WorkspaceCoverageStatus {
+  const git = probeWorktreeLink(path);
+  return () => resolveCheckpointEligibilitySync(shellPaths, path, git).status;
+}

package/src/runtime/trust/trust-gated-approvals.ts

@@ -0,0 +1,169 @@
+/**
+ * trust-gated-approvals.ts — how a headless daemon asks the workspace trust
+ * question, and how the answer reaches the runs it hosts.
+ *
+ * The terminal app composes the trust gate at the permission machinery's final
+ * ask layer and raises the question as a modal on its own screen. The daemon
+ * has the same gate — `trustGatedAsk` next door, reading the same
+ * `<cwd>/.goodvibes/<surface>/trust.json` the terminal app writes — and no
+ * screen to raise anything on. Before this module it therefore
+ * did neither: the gate was constructed, never loaded, never consulted, and no
+ * hosted run passed through it.
+ *
+ * Two pieces close that:
+ *
+ *  1. `createWorkspaceTrustDecisionAsk` raises the trust question as an
+ *     ordinary approval record. That is the whole point of the approval-raise
+ *     path: a process with no screen states the question, publishes it on
+ *     `approval-update`, and whichever surface is attached answers it. Approved
+ *     means "trusted", denied means "restricted" — a real decision either way,
+ *     persisted by the gate, and never asked again for this workspace.
+ *
+ *  2. `trustGatedApprovalRaiser` puts the gate in front of the raiser the
+ *     permission manager asks through, and loads the persisted decision before
+ *     consulting it. The load is here rather than in the composition root
+ *     because `createRuntimeServices` is synchronous: a fire-and-forget load
+ *     started at composition time can lose the race with the first hosted run,
+ *     and losing it means re-asking a question the user already answered.
+ *     `WorkspaceTrustManager.load()` is idempotent, so paying for it on every
+ *     ask costs one already-resolved promise after the first.
+ *
+ * What the daemon does NOT do here is decide by default. An untrusted
+ * workspace's hosted run neither runs as if trusted nor fails as if refused: it
+ * asks. If the ask cannot be answered — nothing attached, or the broker itself
+ * failed — the workspace stays undecided and this run is refused, with the
+ * reason in the log rather than in a silence. A refusal that records nothing is
+ * the failure mode this whole seam exists to remove.
+ */
+import { randomUUID } from 'node:crypto';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type { PermissionPromptDecision, PermissionPromptRequest } from '@pellux/goodvibes-sdk/platform/permissions';
+import { operations } from '@pellux/goodvibes-sdk/platform/runtime';
+const { trustGatedAsk } = operations;
+type WorkspaceTrustLevel = operations.WorkspaceTrustLevel;
+type WorkspaceTrustManager = operations.WorkspaceTrustManager;
+
+/**
+ * The extra fields a raise carries beside the request itself — the attribution
+ * routing/metadata a background-agent ask is stamped with before it reaches the
+ * broker. The gate only reads `request.category`, so these ride around it.
+ */
+export interface ApprovalRaiseExtras {
+  readonly routeId?: string | undefined;
+  readonly metadata?: Record<string, unknown> | undefined;
+  /** Expiry for a raised ask; the trust question sets one, tool asks do not. */
+  readonly timeoutMs?: number | undefined;
+}
+
+/** Raise an ask and wait for the answer. Matches the SDK's ApprovalRaiser seam. */
+export type ApprovalRaise = (
+  input: { readonly request: PermissionPromptRequest } & ApprovalRaiseExtras,
+) => Promise<PermissionPromptDecision>;
+
+/**
+ * How long a raised trust question stays open before it expires.
+ *
+ * A hosted run blocked on a question nobody is there to answer is a run that
+ * never finishes, and an unattended daemon is the normal case, not the edge
+ * one. Ten minutes is long enough for someone who is at a surface to see the
+ * ask and answer it, and short enough that an unattended run fails with a
+ * reason instead of hanging until the process restarts.
+ */
+export const WORKSPACE_TRUST_ASK_TIMEOUT_MS = 10 * 60 * 1000;
+
+export interface WorkspaceTrustDecisionAskDeps {
+  readonly requestApproval: ApprovalRaise;
+  /** The workspace the question is about — it names the directory being trusted. */
+  readonly workingDirectory: string;
+  readonly timeoutMs?: number | undefined;
+}
+
+/**
+ * Build the `requestTrustDecision` callback `trustGatedAsk` calls when a
+ * workspace has no decision yet.
+ *
+ * The question is raised as a `read`-category request on purpose: it is the
+ * trust question itself, raised BY the gate, and routing it back through the
+ * gate would ask the gate to decide whether it may ask.
+ */
+export function createWorkspaceTrustDecisionAsk(
+  deps: WorkspaceTrustDecisionAskDeps,
+): () => Promise<WorkspaceTrustLevel> {
+  return async () => {
+    const request: PermissionPromptRequest = {
+      callId: `workspace-trust-${randomUUID().slice(0, 8)}`,
+      tool: 'workspace-trust',
+      args: { workspace: deps.workingDirectory },
+      category: 'read',
+      analysis: {
+        classification: 'workspace-trust',
+        riskLevel: 'high',
+        summary: `Trust the workspace ${deps.workingDirectory}?`,
+        reasons: [
+          `A run hosted by this daemon wants to write, execute, or delegate in "${deps.workingDirectory}", which has no trust decision recorded.`,
+          'Approving marks the workspace trusted and stops this question being asked for it again.',
+          'Denying marks it restricted: reads keep working, and writes, commands and delegation are refused there.',
+        ],
+        target: deps.workingDirectory,
+        targetKind: 'path',
+        blastRadius: 'local',
+      },
+    };
+    try {
+      const decision = await deps.requestApproval({
+        request,
+        timeoutMs: deps.timeoutMs ?? WORKSPACE_TRUST_ASK_TIMEOUT_MS,
+        metadata: { source: 'workspace-trust', workspace: deps.workingDirectory },
+      });
+      return decision.approved ? 'trusted' : 'restricted';
+    } catch (error) {
+      // Nothing attached, or the broker failed. Say so and leave the workspace
+      // undecided — the next run asks again rather than inheriting a decision
+      // nobody made.
+      logger.warn('Workspace trust question could not be answered; this run is refused and the workspace stays undecided', {
+        workspace: deps.workingDirectory,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  };
+}
+
+/** The slice of the trust manager this seam uses. */
+export type TrustGateManager =
+  & Pick<WorkspaceTrustManager, 'isCategoryAllowed' | 'isDecided' | 'setLevel'>
+  & { load(): Promise<void> };
+
+/**
+ * Wrap an approval raiser with the workspace trust gate.
+ *
+ * Layering matches the terminal app's: the gate is the outer ask, the broker
+ * raise is the inner one, and the permission manager's own layers (mode,
+ * policy, session cache, durable rules) still run before either. A trusted
+ * workspace is exactly as permissive as it was; a restricted one refuses
+ * non-read categories without asking, because that is what the user chose.
+ *
+ * `routeId`/`metadata` reach the inner raise unchanged. The gate's own
+ * signature carries only the request, so the extras are held against the
+ * request object for the duration of the call rather than in a shared slot a
+ * concurrent ask could overwrite.
+ */
+export function trustGatedApprovalRaiser(
+  manager: TrustGateManager,
+  raise: ApprovalRaise,
+  requestTrustDecision: () => Promise<WorkspaceTrustLevel>,
+): ApprovalRaise {
+  const extrasByRequest = new WeakMap<PermissionPromptRequest, ApprovalRaiseExtras>();
+  const gated = trustGatedAsk(
+    manager,
+    (request) => raise({ request, ...(extrasByRequest.get(request) ?? {}) }),
+    requestTrustDecision,
+  );
+  return async (input) => {
+    extrasByRequest.set(input.request, { routeId: input.routeId, metadata: input.metadata });
+    // Idempotent, and awaited on every ask rather than once at composition:
+    // see the module header for why the composition root cannot await it.
+    await manager.load();
+    return gated(input.request);
+  };
+}

package/src/runtime/update-check.ts

@@ -0,0 +1,61 @@
+/**
+ * Pure logic for `/update`: version comparison, the latest-release-tag
+ * redirect lookup, and honest install-kind detection.
+ *
+ * Version comparison and the release-tag lookup are re-exported from the
+ * SDK's canonical update policy module (platform/runtime/self-update), which
+ * was hoisted from this file's semantics — one mechanism everywhere.
+ * Install-kind detection stays local: it encodes how THIS package is
+ * installed (compiled binary vs bun/npm package vs source run) and what
+ * command replaces a swap for each kind.
+ *
+ * The self-update download/verify/swap orchestration that USES these lives
+ * in this daemon's own hourly loop (`src/daemon/lifecycle.ts`); this module
+ * only decides "is there a newer version" and "can this install be swapped
+ * in place". The terminal app's own manual `/update` command solves the same
+ * problem for its own users, independently.
+ */
+export {
+  compareVersions,
+  normalizeVersion,
+  parseReleaseTagFromLocation,
+  resolveLatestReleaseTag,
+  type UpdateFetchLike,
+} from '@pellux/goodvibes-sdk/platform/runtime/self-update';
+
+/**
+ * How this running process was installed, detected honestly from
+ * process.execPath rather than assumed:
+ *   - "binary": a standalone `bun build --compile` executable with no
+ *     package-manager ancestry — the scripts/install.sh install path.
+ *     Swappable in place.
+ *   - "bun-global-package": running the vendored binary shipped inside an
+ *     npm/bun-managed package install (execPath contains a "node_modules"
+ *     path segment — true for both `bun add -g` and a local project
+ *     dependency). Managed by the package manager; swapping the vendored
+ *     file in place would fight the next `bun add -g` upgrade, so this is
+ *     never swapped — the user re-runs their package manager instead.
+ *   - "source": running directly via the `bun` interpreter (`bun run
+ *     src/main.ts`), not a compiled binary at all.
+ */
+export type InstallKind = 'binary' | 'bun-global-package' | 'source';
+
+export function detectInstallKind(execPath: string): InstallKind {
+  const segments = execPath.split(/[\\/]/);
+  const execName = (segments[segments.length - 1] ?? '').toLowerCase();
+  if (execName === 'bun' || execName === 'bun.exe') {
+    return 'source';
+  }
+  if (segments.includes('node_modules')) {
+    return 'bun-global-package';
+  }
+  return 'binary';
+}
+
+/** The exact command to tell the user to run instead of a swap, for each non-binary install kind. */
+export function fallbackUpdateCommand(kind: Exclude<InstallKind, 'binary'>): string {
+  if (kind === 'bun-global-package') {
+    return 'bun add -g goodvibes-daemon';
+  }
+  return 'curl -fsSL https://goodvibes.sh/install.sh | sh';
+}

package/src/runtime/workspace-checkpointing.ts

@@ -0,0 +1,116 @@
+import { WorkspaceCheckpointManager } from '@pellux/goodvibes-sdk/platform/workspace';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { RuntimeEventBus, SessionSurface } from '@/runtime/index.ts';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { readCheckpointGuardSettings, readCheckpointRegistrationSetting } from '../config/checkpoint-settings.ts';
+import { createWorkspaceRegistrationLiveChecker, type StoreShellPaths } from './trust/checkpoint-eligibility.ts';
+
+/**
+ * The workspace checkpoint manager, gated on live registration.
+ *
+ * This daemon's checkpoint manager scopes the checkpoint git store to the
+ * surface's own directory AND gates every automatic snapshot on the owner's
+ * registered-workspaces-only ruling.
+ *
+ * The gate is a LIVE re-check rather than a construction-time decision. The
+ * manager only subscribes to turn/agent-lifecycle events when it is built with a
+ * runtime bus, so building it without one for an unregistered workspace would
+ * mean registering that workspace mid-run had no effect until a restart. It is
+ * always built WITH the bus and each individual automatic snapshot attempt is
+ * refused instead — by overriding this one instance's own `create`, since the
+ * manager has no predicate hook and `create` is the single seam both the
+ * automatic subscription and every explicit caller pass through.
+ */
+
+export interface WorkspaceCheckpointing {
+  /** The manager itself — automatic snapshots gated, explicit creates unrestricted. */
+  readonly manager: WorkspaceCheckpointManager;
+  /**
+   * The narrower surface handed to the `checkpoints.*` gateway verbs: identical
+   * except that an explicit create refuses, with an actionable message, when the
+   * workspace is not checkpoint-eligible. Reads (list/diff/sessionChanges) and
+   * restore stay unrestricted — they operate over checkpoints that may already
+   * exist, including from a since-unregistered workspace.
+   */
+  readonly gatewayManager: Pick<WorkspaceCheckpointManager, 'list' | 'create' | 'diff' | 'restore' | 'sessionChanges' | 'workspaceRoot'>;
+  /** Whether checkpoints are currently permitted for this workspace. Re-reads the store on every call. */
+  readonly currentlyAllowed: () => boolean;
+}
+
+export function createWorkspaceCheckpointing(opts: {
+  readonly workspaceRoot: string;
+  /**
+   * The declare-once storage handle. Passing it resolves the checkpoint git
+   * store to `surface.checkpointsDir` instead of the unscoped
+   * `<workspaceRoot>/.goodvibes/checkpoints` every product using this SDK would
+   * otherwise share. The SDK migrates an existing legacy store into the scoped
+   * location on first use.
+   */
+  readonly surface: SessionSurface;
+  readonly runtimeBus: RuntimeEventBus;
+  readonly configManager: ConfigManager;
+  readonly shellPaths: StoreShellPaths;
+  /** Stamps automatic snapshots with the live session id, so a checkpoint made this launch is found by the session-scoped restore lookup. */
+  readonly resolveSessionId?: (ctx: { readonly turnId?: string | undefined; readonly agentId?: string | undefined }) => string | undefined;
+}): WorkspaceCheckpointing {
+  const registrationStatus = createWorkspaceRegistrationLiveChecker(opts.shellPaths, opts.workspaceRoot);
+  const currentlyAllowed = (): boolean =>
+    registrationStatus() === 'covered' || readCheckpointRegistrationSetting(opts.configManager) === 'guarded';
+
+  const manager = new WorkspaceCheckpointManager({
+    workspaceRoot: opts.workspaceRoot,
+    // Root and retention guards from the owner's `checkpoints.*` settings. These
+    // are defense in depth UNDER the registration rule, not a replacement for
+    // it: even a registered root can still be refused as too broad or too large.
+    ...readCheckpointGuardSettings(opts.configManager),
+    surface: opts.surface,
+    runtimeBus: opts.runtimeBus,
+    ...(opts.resolveSessionId ? { resolveSessionId: opts.resolveSessionId } : {}),
+  });
+
+  // Automatic snapshots ('turn' | 'agent-run', fired by the manager's own bus
+  // subscription) resolve to null quietly when the workspace is not eligible —
+  // there is no caller to throw to, and the manager already documents a null
+  // return as the cheap no-op for an unchanged tree. Explicit ('manual') creates
+  // are NOT re-gated here: they go through the gateway surface below, which
+  // throws something actionable before ever reaching this method.
+  const originalCreate = manager.create.bind(manager);
+  manager.create = ((createOpts) => {
+    if (createOpts.kind !== 'manual' && !currentlyAllowed()) return Promise.resolve(null);
+    return originalCreate(createOpts);
+  }) as typeof manager.create;
+
+  // Eagerly initialize so the automatic-snapshot subscription is live before the
+  // first turn completes. If init() rejects, the manager caches that rejection
+  // forever and every later call re-throws it — the catch here only prevents an
+  // unhandled rejection at startup; the checkpoint verbs report the failure to
+  // whoever calls them.
+  void manager.init().catch((error: unknown) => {
+    logger.warn('WorkspaceCheckpointManager.init failed', { error: error instanceof Error ? error.message : String(error) });
+  });
+
+  const gatewayManager: WorkspaceCheckpointing['gatewayManager'] = {
+    workspaceRoot: manager.workspaceRoot,
+    list: manager.list.bind(manager),
+    diff: manager.diff.bind(manager),
+    restore: manager.restore.bind(manager),
+    sessionChanges: manager.sessionChanges.bind(manager),
+    create: (createOpts) => {
+      if (!currentlyAllowed()) {
+        throw new Error(
+          `Checkpoints are off for this workspace: ${opts.workspaceRoot} is not registered. `
+          + 'Register it first, then retry (or set checkpoints.unregisteredWorkspaces to "guarded" '
+          + 'to opt this workspace out of the registration gate).',
+        );
+      }
+      // Default the session stamp from the live resolver when the caller omits
+      // it — the resolveSessionId hook only auto-stamps automatic snapshots, so
+      // without this an explicit checkpoint made this launch would be written
+      // unstamped and excluded by the session-scoped restore lookup.
+      const sessionId = createOpts.sessionId ?? opts.resolveSessionId?.({});
+      return manager.create(sessionId ? { ...createOpts, sessionId } : createOpts);
+    },
+  };
+
+  return { manager, gatewayManager, currentlyAllowed };
+}