@pellux/goodvibes-agent 1.8.0 → 1.8.2

package/src/runtime/services.ts

@@ -1,8 +1,11 @@
 import { join } from 'node:path';
+import { StepUpService } from '@pellux/goodvibes-sdk/daemon';
 import { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import { shell as runtimeShell } from '@pellux/goodvibes-sdk/platform/runtime';
 import type { shell as RuntimeShell } from '@pellux/goodvibes-sdk/platform/runtime';
 import { SecretsManager } from '../config/secrets.ts';
+import { readCheckpointGuardSettings, readCheckpointRegistrationSetting } from '../config/checkpoint-settings.ts';
+import { createWorkspaceRegistrationLiveChecker, migrateLegacyWorkspaceRegistryIfNeeded } from '../config/workspace-registration.ts';
 import { FocusTracker } from '../core/focus-tracker.ts';
 import { ServiceRegistry } from '@pellux/goodvibes-sdk/platform/config';
 import { SubscriptionManager } from '@pellux/goodvibes-sdk/platform/config';
@@ -10,6 +13,13 @@ import { AutomationDeliveryManager, AutomationManager, AutomationRouteStore } fr
 import { ChannelPluginRegistry, ChannelPolicyManager, RouteBindingManager, SurfaceRegistry } from '@pellux/goodvibes-sdk/platform/channels';
 import { ChannelDeliveryRouter } from '@pellux/goodvibes-sdk/platform/channels';
 import { ApprovalBroker, GatewayMethodCatalog, SharedSessionBroker } from '@pellux/goodvibes-sdk/platform/control-plane';
+import { attachWsOnlyGatewayVerbHandlers, createArchivableFleetRegistry } from '@pellux/goodvibes-terminal-shell';
+import { createSessionConversationRewindPort } from './conversation-rewind-port.ts';
+// Not re-exported by @pellux/goodvibes-terminal-shell (only the gateway-verb
+// composition and the registry factory are) — reached directly per the SDK
+// adoption convention of going straight to the platform package for whatever
+// terminal-shell does not already wrap, rather than hand-rolling the bridge.
+import { attachFleetEmitBridge } from '@pellux/goodvibes-sdk/platform/runtime/fleet';
 import type { SharedSessionRoutingIntent } from '@pellux/goodvibes-sdk/platform/control-plane';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import { AGENT_SPINE_PARTICIPANT, SessionSpineClient } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
@@ -45,9 +55,17 @@ import { AgentOrchestrator } from '@pellux/goodvibes-sdk/platform/agents';
 import { ArchetypeLoader } from '@pellux/goodvibes-sdk/platform/agents';
 import { CodeIndexStore } from '@pellux/goodvibes-sdk/platform/state';
 import { CodeIndexReindexScheduler } from '@pellux/goodvibes-sdk/platform/state';
-import { createProcessRegistry, withFleetArchive } from '@pellux/goodvibes-sdk/platform/runtime/fleet';
 import { createOrchestrationEngine } from '@pellux/goodvibes-sdk/platform/orchestration';
 import { WorkspaceCheckpointManager } from '@pellux/goodvibes-sdk/platform/workspace';
+
+/**
+ * Structural mirror of the SDK's CheckpointSessionResolver (checkpoint/manager):
+ * maps a triggering turn/agent lifecycle event to its owning session id. Declared
+ * locally because the type is re-exported only from the deep checkpoint subpath,
+ * not the `platform/workspace` barrel this module already imports; the shape is
+ * exact, so a resolver typed against it is assignable to the constructor option.
+ */
+type CheckpointSessionResolver = (ctx: { readonly turnId?: string | undefined; readonly agentId?: string | undefined }) => string | undefined;
 import { ProcessManager } from '@pellux/goodvibes-sdk/platform/tools';
 import { ModeManager } from '@pellux/goodvibes-sdk/platform/state';
 import { FileUndoManager } from '@pellux/goodvibes-sdk/platform/state';
@@ -95,6 +113,7 @@ import { FileStateCache } from '@pellux/goodvibes-sdk/platform/state';
 import { ProjectIndex } from '@pellux/goodvibes-sdk/platform/state';
 import { IdempotencyStore } from '@/runtime/index.ts';
 import { OverflowHandler } from '@pellux/goodvibes-sdk/platform/tools';
+import { ContextAccountingHolder } from '@pellux/goodvibes-sdk/platform/tools';
 import { ToolLLM } from '@pellux/goodvibes-sdk/platform/config';
 import { ComponentHealthMonitor } from '@/runtime/index.ts';
 import { SandboxSessionRegistry } from '@/runtime/index.ts';
@@ -397,6 +416,16 @@ export interface RuntimeServicesOptions {
   readonly localUserAuthManager?: UserAuthManager;
   readonly featureFlags?: FeatureFlagManager;
   readonly getConversationTitle?: () => string | undefined;
+  /**
+   * Maps a triggering turn/agent lifecycle event to the owning session id so the
+   * WorkspaceCheckpointManager can stamp automatic (and defaulted explicit)
+   * checkpoints with it. Without this, same-launch checkpoints are written with
+   * an undefined session id and the session-scoped restore/rewind lookup filters
+   * them out — so a checkpoint made this launch could not be activated until a
+   * restart. Consulted live at each event, so a resolver reading a mutable
+   * session-id ref reflects the current session without re-wiring.
+   */
+  readonly resolveSessionId?: CheckpointSessionResolver;
   readonly workingDir: string;
   readonly homeDirectory: string;
 }
@@ -549,6 +578,15 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     secretsManager,
     subscriptionManager,
   });
+  // Settable holder for the context_accounting tool's session source (SDK
+  // 1.6.1). Constructed here (unbound) so it exists for the whole runtime
+  // services lifetime and every consumer of `services.contextAccountingHolder`
+  // sees the SAME instance the tool roster is registered against — bootstrap.ts
+  // binds an Orchestrator-backed ContextAccountingSource onto it once the
+  // interactive Orchestrator exists (see bindOrchestratorContextAccounting in
+  // context-accounting-source.ts). Left unbound here: the tool honestly
+  // reports "no live session context bound" until that bind call runs.
+  const contextAccountingHolder = new ContextAccountingHolder();
   const providerCapabilityRegistry = new ProviderCapabilityRegistry();
   const cacheHitTracker = new CacheHitTracker();
   const favoritesStore = new FavoritesStore({ dir: shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT) });
@@ -913,9 +951,14 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   //                            never fires for the Agent.
   //   • processRegistry      — fleet observability over the managers the Agent
   //                            already owns (agents, wrfc, processes, watchers).
-  //   • workspaceCheckpointManager — constructed without a runtimeBus so it
-  //                            never auto-subscribes to turn events / snapshots
-  //                            the workspace; inert unless explicitly invoked.
+  //   • workspaceCheckpointManager — a runtimeBus (hence automatic turn/agent-
+  //                            lifecycle snapshots) is only passed when
+  //                            `workingDirectory` is a registered workspace (or
+  //                            the unregistered-workspaces override is
+  //                            "guarded"); otherwise it stays inert unless
+  //                            explicitly invoked. See the construction site
+  //                            below for the full registered-workspaces-only
+  //                            rule (owner ruling, 2026-07-10).
   const orchestrationEngine = createOrchestrationEngine({
     agentManager,
     configManager,
@@ -934,7 +977,10 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   });
   // Archive-aware: finished agent/swarm subtrees can be moved out of the
   // live fleet view into a session-scoped archive (SDK fleet/archive.ts).
-  const processRegistry = withFleetArchive(createProcessRegistry({
+  // createArchivableFleetRegistry is the shared terminal-shell wrapper over the
+  // SDK's withFleetArchive(createProcessRegistry(...)) — one named seam both
+  // daemon front-ends build the registry through so it cannot drift.
+  const processRegistry = createArchivableFleetRegistry({
     agentManager,
     wrfcController,
     orchestrationEngine,
@@ -947,17 +993,222 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     messageBus: agentMessageBus,
     automationManager,
     runtimeBus: options.runtimeBus,
-  }));
+  });
+  // Root/retention guard options come from the user's `checkpoints.*` settings
+  // (see config/checkpoint-settings.ts); any key the user did not set is omitted
+  // so the SDK manager applies its own default. These guards are defense in
+  // depth UNDER the registered-workspaces-only rule below, not replaced by it:
+  // even a registered root can still be refused as too broad or too large.
+  //
+  // Registered-workspaces-only (owner ruling, 2026-07-10; live-gating extended
+  // 2026-07-11 so registering mid-launch takes effect without a restart — the
+  // same stale-until-restart defect class fixed for permission-mode metadata).
+  // The SDK's WorkspaceCheckpointManager only takes automatic turn/agent-
+  // lifecycle snapshots when constructed WITH a runtimeBus (see the SDK's own
+  // platform/runtime/services.ts, which always passes one). This composition
+  // root ALWAYS passes runtimeBus now (so the automatic-snapshot subscription
+  // is live from process start regardless of boot-time registration state),
+  // and instead gates each individual automatic snapshot attempt through a
+  // LIVE re-check via `checkpointsCurrentlyAllowed` below — patched onto this
+  // one manager instance's own `create` method, since the SDK has no built-in
+  // predicate hook for this. `checkpointsCurrentlyAllowed` is cheap to call on
+  // every event: `createWorkspaceRegistrationLiveChecker` probes the git
+  // worktree link ONCE (a `git` subprocess spawn) and every call after that
+  // only re-reads the shared registration JSON file. "Allowed" means
+  // `workingDirectory` resolves as COVERED by the shared registration store
+  // (SDK 1.6.1 platform/workspace/registration, via
+  // config/workspace-registration.ts — the successor to this fork's local
+  // per-user registry, migrated in once below), or the owner has explicitly
+  // opted an unregistered workspace back in via
+  // `checkpoints.unregisteredWorkspaces: "guarded"` (config/checkpoint-settings.ts;
+  // default "off"). Coverage flows down a registered root's subtree AND
+  // through the git worktree→main-repo link, so an orchestration-spawned
+  // worktree of a registered repo checkpoints automatically without being
+  // registered itself. A workspace SWAP at runtime is still not tracked here
+  // (WorkspaceSwapManager's rerootStores does not re-root this manager; a swap
+  // needs a restart to pick up a new root's registration) — only the
+  // registration STATE of this fixed workingDirectory is now live.
+  const registrationMigration = migrateLegacyWorkspaceRegistryIfNeeded(shellPaths);
+  if (registrationMigration) {
+    logger.info('Migrated the local workspace registry into the shared registration store', { ...registrationMigration });
+  }
+  const checkpointsRegistrationStatus = createWorkspaceRegistrationLiveChecker(shellPaths, workingDirectory);
+  const checkpointsCurrentlyAllowed = (): boolean =>
+    checkpointsRegistrationStatus() === 'covered' || readCheckpointRegistrationSetting(configManager) === 'guarded';
   const workspaceCheckpointManager = new WorkspaceCheckpointManager({
     workspaceRoot: workingDirectory,
+    ...readCheckpointGuardSettings(configManager),
+    runtimeBus: options.runtimeBus,
+    // Stamp automatic snapshots with the live session id so a checkpoint created
+    // during this launch is found by the session-scoped restore/rewind lookup —
+    // the fix that makes same-launch activation work without a restart. The
+    // resolver is consulted at each lifecycle event, so it tracks the current
+    // session even though the id is finalized after this manager is built.
+    ...(options.resolveSessionId ? { resolveSessionId: options.resolveSessionId } : {}),
   });
+  // Gate AUTOMATIC snapshots (kind 'turn' | 'agent-run', fired internally by
+  // the manager's own bus subscription via `this.create(...)`) on the live
+  // registration check, by overriding this instance's own `create` method —
+  // the manager has no predicate-hook option, and this is the one seam that
+  // every automatic-snapshot call and every explicit caller both go through.
+  // 'manual' (explicit, gateway-invoked) creates are NOT re-gated here: they
+  // already go through checkpointsGatewayManager.create's own live check
+  // below, which throws an actionable message BEFORE ever reaching this
+  // method — this override would just be a silent, redundant pass for that
+  // path. For an automatic snapshot there is no caller to throw to (the
+  // manager's own subscription callbacks only `.catch()`-log a rejection), so
+  // an automatic attempt against an unregistered/un-guarded workspace resolves
+  // to `null` quietly — the same "cheap no-op" contract `create()` already
+  // documents for an unchanged tree, not a new error path.
+  const originalCreateCheckpoint = workspaceCheckpointManager.create.bind(workspaceCheckpointManager);
+  workspaceCheckpointManager.create = ((opts) => {
+    if (opts.kind !== 'manual' && !checkpointsCurrentlyAllowed()) return Promise.resolve(null);
+    return originalCreateCheckpoint(opts);
+  }) as typeof workspaceCheckpointManager.create;
+  // Eagerly initialize so the automatic snapshot subscription is wired up
+  // immediately (mirrors the SDK's own default runtime services) rather than
+  // only on first explicit checkpoints.* call — otherwise the very first
+  // TURN_COMPLETED could arrive before anything has touched the manager. Now
+  // unconditional (previously skipped for an unregistered-at-boot workspace):
+  // the subscription itself is inert-by-gate rather than inert-by-absence, so
+  // a workspace registered mid-launch starts producing automatic snapshots on
+  // the very next eligible event, with no restart needed to (re)wire the bus.
+  void workspaceCheckpointManager.init().catch((err) => {
+    logger.warn('WorkspaceCheckpointManager.init failed', { error: err instanceof Error ? err.message : String(err) });
+  });
+  // Explicit user-invoked checkpoint creation (the ws-only `checkpoints.create`
+  // gateway verb) is gated the SAME way: refuse with an actionable hint rather
+  // than silently registering the workspace on the caller's behalf. This is
+  // the chosen policy for the pending owner ruling (the alternative —
+  // register-and-proceed — was NOT chosen, to keep "create a checkpoint" from
+  // having a side effect the caller did not ask for). list/diff/restore/
+  // sessionChanges are read/restore operations over checkpoints that may
+  // already exist (e.g. from a since-unregistered workspace) and are left
+  // unrestricted here.
+  const checkpointsGatewayManager: Pick<WorkspaceCheckpointManager, 'list' | 'create' | 'diff' | 'restore' | 'sessionChanges' | 'workspaceRoot'> = {
+    workspaceRoot: workspaceCheckpointManager.workspaceRoot,
+    list: workspaceCheckpointManager.list.bind(workspaceCheckpointManager),
+    diff: workspaceCheckpointManager.diff.bind(workspaceCheckpointManager),
+    restore: workspaceCheckpointManager.restore.bind(workspaceCheckpointManager),
+    sessionChanges: workspaceCheckpointManager.sessionChanges.bind(workspaceCheckpointManager),
+    create: (opts) => {
+      // Re-reads the registry and setting live via the same cheap checker the
+      // automatic-snapshot gate above uses, so registering the workspace via
+      // `goodvibes-agent workspaces register` takes effect for the NEXT
+      // explicit create call (same as it always has) — and, as of the live
+      // gate above, for automatic snapshots too, without a restart either way.
+      if (!checkpointsCurrentlyAllowed()) {
+        throw new Error(
+          `Checkpoints are off for this workspace: ${workingDirectory} is not registered. `
+          + 'Register it first, then retry: goodvibes-agent workspaces register --yes '
+          + '(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, not
+      // explicit create calls). Without this, an explicit checkpoint made this
+      // launch would be written unstamped and excluded by the session-scoped
+      // restore lookup — the same same-launch activation gap the resolver closes
+      // for automatic snapshots. An explicitly supplied sessionId always wins.
+      const sessionId = opts.sessionId ?? options.resolveSessionId?.({});
+      return workspaceCheckpointManager.create(sessionId ? { ...opts, sessionId } : opts);
+    },
+  };
+
+  // Attach handlers for every ws-only gateway verb group (fleet.* including
+  // the archive verbs, checkpoints.*, sessions.search, push.*, principals.*,
+  // channels.profiles.*, ci.*, and — when the deps below are all present —
+  // checkin.*). Without this call the catalog carries descriptors but no
+  // handlers, and every one of those verbs answers 501 "Gateway method is not
+  // invokable" — the same gap the companion app found on the TUI-vendored
+  // daemon. Mirrors the SDK runtime's composition root (goodvibes-sdk
+  // platform/runtime/services.ts). attachWsOnlyGatewayVerbHandlers is the
+  // shared terminal-shell wrapper over the SDK's registerGatewayVerbGroups —
+  // the single named call site both front-ends bind these handlers through,
+  // gated by the package's conformance check.
+  //
+  // configManager and runtimeStore are required (SDK 1.6.1): they back
+  // sessions.permissionMode.get/set and sessions.contextUsage.get. The four
+  // check-in deps (channelDeliveryRouter, providerRegistry, automationManager,
+  // sessionLister) are each optional individually, but the check-in verb
+  // group (checkin.config.get/set, checkin.run, checkin.receipts.list) is
+  // registered ONLY when all four are present — every one of them is already
+  // constructed above in this composition root, so the Agent wires all four:
+  // the proactive check-in loop runs for real here, not as a facade. Off by
+  // default via checkin.enabled (see config/schema-domain-runtime.ts).
+  attachWsOnlyGatewayVerbHandlers(gatewayMethods, {
+    processRegistry,
+    workspaceCheckpointManager: checkpointsGatewayManager,
+    sessionBroker,
+    secretsManager,
+    approvalBroker,
+    shellPaths,
+    configManager,
+    runtimeStore: options.runtimeStore,
+    channelDeliveryRouter,
+    providerRegistry,
+    automationManager,
+    sessionLister: sessionBroker,
+    // The best-of-N surface (fleet.attempts.list/pick/judge): the
+    // orchestration engine already implements FleetAttemptsController
+    // (listHeldMergeGroups/pickAttemptWinner/proposeAttemptWinner) — wiring
+    // it here is what turns those verbs from cataloged-but-unhandled into
+    // real handlers (see src/test/daemon/gateway-ws-only-invokable.test.ts).
+    attemptsController: orchestrationEngine,
+    // worktrees.setup.run (SDK 1.6.1): the rerun affordance for worktree
+    // cold-start setup, registered over a WorktreeRegistry rooted at this
+    // daemon's own working directory (matching worktrees.snapshot's reader)
+    // only when workingDirectory is present. It already is here — this was a
+    // real cataloged-but-unhandled gap (found by the gateway parity pin
+    // sweep, see src/test/daemon/gateway-parity-verb-families.test.ts) with
+    // no reason to leave unfixed: the daemon's own working directory was
+    // already in scope in this composition root (see
+    // checkpointsGatewayManager above).
+    workingDirectory,
+    // Conversation half of the unified rewind (rewind.plan/apply with scope
+    // 'conversation' or 'both'): this Agent's own ConversationManager (see
+    // src/core/conversation.ts) IS a genuine in-process mutable conversation
+    // store — the exact shape RewindConversationPort assumes ("a daemon-hosted
+    // mutable conversation store") — so it is wired here rather than left
+    // null, ported from goodvibes-tui's identical seam
+    // (conversation-rewind-port.ts, registerSessionConversation at bootstrap;
+    // see bootstrap-core.ts). createSessionConversationRewindPort() reads the
+    // live per-session registry lazily (no conversation reference needed at
+    // construction time), so it can be called here even though bootstrap
+    // wires the actual session registration separately. See
+    // src/test/daemon/gateway-rewind-conversation-scope.test.ts for the live
+    // proof this resolves a real conversation, not a stub.
+    conversationRewindPort: createSessionConversationRewindPort(),
+  });
+  // Turn the fleet registry's coalesced snapshot tick into poll-free
+  // spawn/progress/attention/completion events on the runtime event bus's
+  // 'fleet' domain (SDK 1.6.1, runtime/fleet/emit-bridge.ts) — the SDK's own
+  // doc note on this bridge: "The control-plane gateway already fans every
+  // runtime-bus domain out to subscribed SSE/WebSocket clients, so no
+  // gateway/channel change is needed once the fleet domain exists." Without
+  // this call the fleet.* gateway verbs above still answer pull queries
+  // (fleet.snapshot/fleet.list), but nothing pushes live deltas — a webui
+  // FleetView watching this agent's orchestrator-spawned sub-agents would see
+  // them only on manual refresh, never their attention state flipping to
+  // needs-input in real time. No unsubscribe is kept: the bridge is meant to
+  // live for the registry's lifetime (same non-disposed pattern as the
+  // fleet/push verb registrations just above; see the SDK's own doc comment
+  // on attachFleetEmitBridge).
+  attachFleetEmitBridge({ registry: processRegistry, bus: options.runtimeBus });
+
+  // The relay step-up ceremony service the SDK's RuntimeServices requires (and
+  // the daemon facade dereferences at start). Constructed exactly as the SDK
+  // composition root does, from the public @pellux/goodvibes-sdk/daemon export.
+  const stepUpService = new StepUpService({ secrets: secretsManager });
 
   return {
+    stepUpService,
     workingDirectory,
     homeDirectory,
     shellPaths,
     configManager,
     featureFlags,
+    contextAccountingHolder,
     orchestrationEngine,
     codeIndexStore,
     codeIndexReindexScheduler,

package/src/runtime/tool-permission-safety.ts

@@ -1,5 +1,6 @@
 import type { PermissionCategory, PermissionCheckResult } from '@pellux/goodvibes-sdk/platform/permissions';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { HARNESS_MODE_DESCRIPTORS } from '../tools/agent-harness-mode-catalog.ts';
 
 type PermissionManagerLike = {
   check(toolName: string, args: Record<string, unknown>): Promise<boolean>;
@@ -18,6 +19,7 @@ const READ_TOOL_NAMES = new Set([
   'state',
   'registry',
   'route',
+  'repo_map',
   'goodvibes_context',
   'autonomy',
   'channels',
@@ -36,7 +38,6 @@ const READ_TOOL_NAMES = new Set([
   'settings',
   'vibe',
   'workspace',
-  'agent_harness',
   'agent_knowledge',
   'agent_operator_briefing',
 ]);
@@ -76,6 +77,18 @@ const READ_ONLY_AUTONOMY_ACTIONS = new Set(['', 'intake', 'request', 'route', 'p
 const READ_ONLY_DELEGATION_ACTIONS = new Set(['', 'status', 'summary', 'overview', 'policy', 'decision', 'decisions', 'delegation_posture', 'routes', 'list', 'catalog', 'posture', 'route', 'item', 'card', 'show', 'inspect', 'delegation_route']);
 const READ_ONLY_EXECUTION_ACTIONS = new Set(['', 'status', 'summary', 'overview', 'routes', 'posture', 'execution_posture', 'route', 'show_route', 'inspect_route', 'execution_route', 'history', 'activity', 'records', 'execution_history', 'record', 'item', 'show', 'inspect', 'execution_history_item', 'processes', 'background', 'backgrounds', 'background_processes', 'capabilities', 'process_capabilities', 'process', 'background_process', 'recovery', 'file_recovery', 'undo_redo']);
 
+// The agent_harness tool takes a `mode`. Every mode whose catalog kind is not
+// 'effect' only inspects, lists, or aliases read-only state, so it classifies as
+// 'read'. Every 'effect' mode changes settings, memory, skills, personas,
+// routines, keybindings, drafts, or runs a promotion/consolidation/command pass,
+// so it classifies as a write. A mode string that is absent from the catalog
+// (unknown or misspelled) is deliberately treated as a write, never a read.
+const READ_ONLY_HARNESS_MODES: ReadonlySet<string> = new Set(
+  HARNESS_MODE_DESCRIPTORS
+    .filter((descriptor) => descriptor.kind !== 'effect')
+    .map((descriptor) => descriptor.id),
+);
+
 type MarkedPermissionManager = PermissionManagerLike & { [SAFETY_MARKER]?: true };
 
 export function installPermissionManagerSafetyGuard(manager: PermissionManagerLike): void {
@@ -275,6 +288,10 @@ export function fallbackPermissionCategoryForArgs(toolName: string, args: Record
         : '';
     return READ_ONLY_EXECUTION_ACTIONS.has(action) ? 'read' : 'write';
   }
+  if (toolName === 'agent_harness') {
+    const mode = typeof args.mode === 'string' ? args.mode.trim() : '';
+    return READ_ONLY_HARNESS_MODES.has(mode) ? 'read' : 'write';
+  }
   if (toolName === 'agent_artifacts') {
     const mode = typeof args.mode === 'string' ? args.mode.trim() : '';
     return mode === 'list' || mode === 'show' ? 'read' : 'write';

package/src/shell/blocking-input.ts

@@ -3,15 +3,28 @@ import type { PermissionRequest } from '@pellux/goodvibes-sdk/platform/permissio
 import type { SessionSnapshot } from '@/runtime/index.ts';
 import type { SystemMessageRouter } from '../core/system-message-router.ts';
 import { readConversationMessageSnapshots } from '../core/conversation-message-snapshot.ts';
+import { answerWorkspaceRegistrationPrompt, type StoreShellPaths } from '../config/workspace-registration.ts';
 
 export type PendingPermissionState = PermissionRequest & {
   resolve: (approved: boolean, remember?: boolean) => void;
 };
 
+/**
+ * First-start registration prompt (owner-approved design): the root that was
+ * offered, and the shellPaths needed to answer it (register or decline)
+ * against the shared registration store without threading a separate
+ * callback through every caller — see answerWorkspaceRegistrationPrompt.
+ */
+export type PendingWorkspaceRegistrationState = {
+  readonly root: string;
+  readonly shellPaths: StoreShellPaths;
+};
+
 export type BlockingInputHandlerOptions = {
   data: string;
   pendingPermission: PendingPermissionState | null;
   recoveryPending: boolean;
+  pendingWorkspaceRegistration: PendingWorkspaceRegistrationState | null;
   abortTurn: () => void;
   conversation: ConversationManager;
   systemMessageRouter: SystemMessageRouter;
@@ -24,6 +37,7 @@ export type BlockingInputHandlerResult = {
   handled: boolean;
   pendingPermission: PendingPermissionState | null;
   recoveryPending: boolean;
+  pendingWorkspaceRegistration: PendingWorkspaceRegistrationState | null;
 };
 
 export function handleBlockingShellInput(
@@ -33,6 +47,7 @@ export function handleBlockingShellInput(
     data,
     pendingPermission,
     recoveryPending,
+    pendingWorkspaceRegistration,
     abortTurn,
     conversation,
     systemMessageRouter,
@@ -48,24 +63,24 @@ export function handleBlockingShellInput(
     if (key === 'y') {
       req.resolve(true, false);
       render();
-      return { handled: true, pendingPermission: null, recoveryPending };
+      return { handled: true, pendingPermission: null, recoveryPending, pendingWorkspaceRegistration };
     }
 
     if (key === 'a') {
       req.resolve(true, true);
       render();
-      return { handled: true, pendingPermission: null, recoveryPending };
+      return { handled: true, pendingPermission: null, recoveryPending, pendingWorkspaceRegistration };
     }
 
     if (key === 'n' || data === '\x1b' || data === '\x03') {
       req.resolve(false, false);
       abortTurn();
       render();
-      return { handled: true, pendingPermission: null, recoveryPending };
+      return { handled: true, pendingPermission: null, recoveryPending, pendingWorkspaceRegistration };
     }
 
     render();
-    return { handled: true, pendingPermission, recoveryPending };
+    return { handled: true, pendingPermission, recoveryPending, pendingWorkspaceRegistration };
   }
 
   if (recoveryPending) {
@@ -79,21 +94,36 @@ export function handleBlockingShellInput(
       }
       deleteRecoveryFile();
       render();
-      return { handled: true, pendingPermission: null, recoveryPending: false };
+      return { handled: true, pendingPermission: null, recoveryPending: false, pendingWorkspaceRegistration };
     }
 
     if (data === '\x1b' || data === '\x03') {
       systemMessageRouter.high('[Recovery] Discarded recovery data.');
       deleteRecoveryFile();
       render();
-      return { handled: true, pendingPermission: null, recoveryPending: false };
+      return { handled: true, pendingPermission: null, recoveryPending: false, pendingWorkspaceRegistration };
     }
 
     systemMessageRouter.high('[Recovery] Ignored saved session; starting a new prompt.');
     deleteRecoveryFile();
     render();
-    return { handled: false, pendingPermission: null, recoveryPending: false };
+    return { handled: false, pendingPermission: null, recoveryPending: false, pendingWorkspaceRegistration };
+  }
+
+  // First-start registration prompt: 'y' registers, EVERY other key (Escape,
+  // Enter-through, Ctrl+C, any stray key) declines — default no, matching the
+  // owner-approved design. Subtree-scoped: never asks again at this root
+  // either way, since both add() and decline() are recorded against it.
+  if (pendingWorkspaceRegistration) {
+    const { root, shellPaths } = pendingWorkspaceRegistration;
+    const accepted = data.toLowerCase().trim() === 'y';
+    answerWorkspaceRegistrationPrompt(shellPaths, root, accepted);
+    systemMessageRouter.high(accepted
+      ? `[Workspace] Registered ${root} — automatic checkpoints are now allowed here.`
+      : `[Workspace] Not registered — automatic checkpoints stay off here (won't ask again for this location).`);
+    render();
+    return { handled: true, pendingPermission: null, recoveryPending, pendingWorkspaceRegistration: null };
   }
 
-  return { handled: false, pendingPermission, recoveryPending };
+  return { handled: false, pendingPermission, recoveryPending, pendingWorkspaceRegistration };
 }

package/src/shell/startup-wiring.ts

@@ -3,6 +3,7 @@ import type { HookDispatcher, HookEventPath, HookPhase, HookCategory } from '@pe
 import type { SessionManager } from '@pellux/goodvibes-sdk/platform/sessions';
 import {
   checkRecoveryFile,
+  createShellPathService,
   formatReturnContextForDisplay,
   persistConversation,
   writeRecoveryFile,
@@ -14,6 +15,8 @@ import {
 } from '../runtime/onboarding/index.ts';
 import { deriveOnboardingState } from '../runtime/onboarding/onboarding-state.ts';
 import { buildSetupIncompleteHint } from '../core/setup-incomplete-hint.ts';
+import { isBroadWorkspaceRoot, normalizeWorkspaceRoot, resolveWorkspaceRegistrationSync } from '../config/workspace-registration.ts';
+import type { PendingWorkspaceRegistrationState } from './blocking-input.ts';
 
 export interface SessionPersistenceAndRecoveryDeps {
   readonly buildCurrentSessionSnapshot: () => SessionSnapshot;
@@ -41,6 +44,8 @@ export interface SessionPersistenceAndRecoveryResult {
   recoveryInterval: ReturnType<typeof setInterval>;
   /** True if an unsaved recovery session was found and the user prompt was shown. */
   recoveryPending: boolean;
+  /** Set when the first-start registration prompt was shown this launch (see below). */
+  pendingWorkspaceRegistration: PendingWorkspaceRegistrationState | null;
 }
 
 /**
@@ -69,6 +74,7 @@ export function wireSessionPersistenceAndRecovery(
     sessionManager,
     onStreamSpeedUpdate,
   } = deps;
+  const shellPaths = createShellPathService({ workingDirectory: workingDir, homeDirectory });
 
   // --- Streaming speed + tool preview wiring ---
   let streamStartTime = 0;
@@ -125,7 +131,26 @@ export function wireSessionPersistenceAndRecovery(
     );
   }, 60_000);
 
-  return { recoveryInterval, recoveryPending };
+  // First-start registration prompt (owner-approved design): only when this
+  // directory resolves to unknown (not covered, not declined) AND it isn't a
+  // broad root the store would refuse anyway (see isBroadWorkspaceRoot's own
+  // doc comment on why an "offer" check is safe to keep separate from the
+  // store's authoritative write-time guard). Skipped when a recovery prompt
+  // already claimed this launch's ambient attention, and while onboarding is
+  // still incomplete — the full-screen onboarding wizard would otherwise
+  // compete with this prompt for the very next keypress the owner types.
+  let pendingWorkspaceRegistration: PendingWorkspaceRegistrationState | null = null;
+  const onboardingDone = Boolean(readOnboardingCompletionMarker(shellPaths, 'user').payload);
+  if (!recoveryPending && onboardingDone) {
+    const resolution = resolveWorkspaceRegistrationSync(shellPaths, workingDir);
+    if (resolution.status === 'unknown' && !isBroadWorkspaceRoot(shellPaths, workingDir)) {
+      systemMessageRouter.high(`[Workspace] "${workingDir}" is not a registered workspace, so automatic (turn-end) checkpoints are off here. Register it? Press "y" to register, any other key to decline (won't ask again for this location).`);
+      render();
+      pendingWorkspaceRegistration = { root: normalizeWorkspaceRoot(workingDir), shellPaths };
+    }
+  }
+
+  return { recoveryInterval, recoveryPending, pendingWorkspaceRegistration };
 }
 
 /**

package/src/tools/agent-context-policy.ts

@@ -147,7 +147,7 @@ function buildAgentCapabilitiesContract(registry?: ToolRegistry): Record<string,
       {
         area: 'Project and computer work',
         can: 'Read, search, analyze, edit, and write workspace files; run bounded shell commands; inspect diffs and project structure; recover recent file edit/write snapshots.',
-        tools: ['read', 'find', 'analyze', 'inspect', 'edit', 'write', 'exec', optionalTool('execution'), optionalTool('delegation')].filter(has),
+        tools: ['read', 'find', 'analyze', 'inspect', 'edit', 'write', 'exec', optionalTool('repo_map'), optionalTool('execution'), optionalTool('delegation')].filter(has),
         inspect: 'execution action:"status"; delegation action:"status"',
       },
       {

package/src/tools/agent-harness-cli-command-policy.ts

@@ -68,12 +68,30 @@ export function describeCliCommandPolicy(commandName: string): CommandExecutionP
       boundary: 'Diagnostics and posture commands are readable from Agent-owned settings, provider, model, and connected-host capability surfaces without taking connected-host lifecycle ownership.',
     };
   }
-  if (root === 'profiles' || root === 'personas' || root === 'skills' || root === 'memory' || root === 'routines' || root === 'sessions' || root === 'bundle') {
+  if (root === 'profiles' || root === 'personas' || root === 'skills' || root === 'memory' || root === 'routines' || root === 'sessions' || root === 'bundle' || root === 'import' || root === 'workspaces' || root === 'fleet') {
     return {
       effect: 'local-state',
       confirmation,
-      preferredModelTool: root === 'profiles' ? agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action') : 'agent_local_registry',
-      boundary: 'Local library/profile/session/bundle CLI commands operate on Agent-local data. Mutations require explicit user intent and should use first-class Agent-local tools where available.',
+      preferredModelTool: root === 'profiles' || root === 'workspaces' || root === 'fleet' ? agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action') : 'agent_local_registry',
+      boundary: root === 'workspaces'
+        ? 'The registered-workspace list that gates automatic checkpoints (owner ruling, 2026-07-10) is Agent-local, user-scoped state. There is no dedicated model tool yet; registration/unregistration is a mutating action and requires explicit user intent (the CLI itself requires --yes).'
+        : root === 'fleet'
+          ? 'Best-of-N held-merge attempt groups (SDK 1.6.1) are this Agent\'s own orchestration engine state, not a connected-host call — fleet.attempts.* is ws-only with no HTTP binding, so agent_operator_method cannot reach it either. There is no dedicated model tool yet; picking a winner is a mutating, worktree-cleaning action and requires explicit user intent (the CLI itself requires --yes).'
+          : 'Local library/profile/session/bundle/import CLI commands operate on Agent-local data. Mutations require explicit user intent and should use first-class Agent-local tools where available.',
+    };
+  }
+  if (root === 'ci' || root === 'principals' || root === 'channel-profiles') {
+    return {
+      effect: 'connected-host-state',
+      confirmation,
+      // agent_operator_method, NOT agent_operator_action: the action tool's
+      // allowlist covers only approvals.* and automation.* and cannot invoke
+      // ci.*/principals.*/channels.profiles.* — pointing the model there would
+      // dead-end in "unknown action". The generic operator-method tool routes
+      // these directly (read-only methods run without confirmation; writes
+      // require confirm + explicitUserRequest).
+      preferredModelTool: 'agent_operator_method (methodId "ci.status", "ci.watches.*", "principals.*", "channels.profiles.*")',
+      boundary: 'CI status/watches, principal identity mappings, and per-channel profile defaults live on the connected host. Reads run through agent_operator_method without confirmation; writes require confirm + explicitUserRequest there, and mutating CLI subcommands require --yes.',
     };
   }
   if (root === 'knowledge' || root === 'ask' || root === 'search') {
@@ -92,6 +110,14 @@ export function describeCliCommandPolicy(commandName: string): CommandExecutionP
       boundary: 'Delegation is explicit user-directed work only; no hidden background review or separate Agent job should be created implicitly.',
     };
   }
+  if (root === 'relay') {
+    return {
+      effect: 'read-only',
+      confirmation,
+      preferredModelTool: `${settingsActions('list', 'get')} (category "relay") or ${agentHarnessModes('tools')}`,
+      boundary: 'relay status reports the connected host\'s imported relay.* configuration and the relay-connect feature flag only — it is not a live check (Agent hosts no daemon and the SDK has no remote relay-status route). relay pair always honestly refuses: minting a pairing payload needs the relay identity private key, which only the daemon actually holding the relay identity has.',
+    };
+  }
   if (root === 'subscription' || root === 'secrets' || root === 'pair') {
     return {
       effect: root === 'pair' ? 'external-network' : 'mixed',