@pellux/goodvibes-agent 1.1.7 → 1.2.0

package/src/tools/agent-harness-setup-posture.ts

@@ -1,248 +1,124 @@
-import type { OnboardingStep1CapabilityItem, OnboardingSurfaceRecord } from '../runtime/onboarding/index.ts';
-import { collectOnboardingSnapshot, deriveStep1Capabilities, deriveStep1CapabilityFlags } from '../runtime/onboarding/index.ts';
+import { join } from 'node:path';
+import { getOrCreateCompanionToken } from '@pellux/goodvibes-sdk/platform/pairing';
+import { GOODVIBES_AGENT_PAIRING_SURFACE } from '../config/surface.ts';
 import type { CommandContext } from '../input/command-registry.ts';
-import { buildProviderAccountSnapshot } from '../panels/provider-account-snapshot.ts';
-import { requireLocalUserAuthManager, requirePlatform, requireProvider, requireSecretsManager, requireServiceRegistry, requireShellPaths, requireSubscriptionManager } from '../input/commands/runtime-services.ts';
+import { requireShellPaths } from '../input/commands/runtime-services.ts';
+import { deriveStep1Capabilities, deriveStep1CapabilityFlags } from '../runtime/onboarding/index.ts';
+import { connectedHostOperatorTokenFingerprint, connectedHostOperatorTokenPath, readConnectedHostOperatorToken } from '../runtime/connected-host-auth.ts';
+import { clearSetupWizardCheckpoint, saveSetupWizardCheckpoint } from '../agent/setup-wizard-checkpoint.ts';
+import { DEFAULT_AGENT_SETUP_WIZARD_CLEAR_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_INSPECT_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_MARK_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_REVIEW_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_RERUN_SMOKE_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_SAVE_SMOKE_ROUTE } from '../agent/setup-wizard.ts';
 import { previewHarnessText } from './agent-harness-text.ts';
+import type { AgentHarnessSetupArgs, SetupResolution } from './agent-harness-setup-posture-types.ts';
+import { buildSetupPlan } from './agent-harness-setup-plan.ts';
+import { buildSetupWizard, describeInstallSmokeCheck, installSmokeNextAction, installSmokeRunResult, installSmokeRunSummary, latestSetupSmokeEvidence, saveSetupSmokeArtifact, setupCompletionMarkerExists, setupSmokeEvidenceFields, setupSmokeEvidenceHistory } from './agent-harness-setup-smoke.ts';
+import { confirmedRepairCandidates, describeCandidate, describeHandoffCard, describeItem, describePlanItem, describeRepairCard, describeRepairDecision, describeServiceLifecycleDecision, nextSetupHandoffSummaries, planSearchText, planSummary, primarySetupRepairDecision, setupRepairTarget } from './agent-harness-setup-describe.ts';
+import { setupHandoffsForItem } from './agent-harness-setup-handoffs.ts';
+import { collectServicePosture, collectSnapshot, itemSearchText, lookupFromArgs, quoteRouteValue, readLimit, readString, safeFileMode, safeIso, summarizeLocalBehavior } from './agent-harness-setup-posture-utils.ts';
 
-export interface AgentHarnessSetupArgs {
-  readonly setupItemId?: unknown;
-  readonly target?: unknown;
-  readonly query?: unknown;
-  readonly includeParameters?: unknown;
-  readonly limit?: unknown;
-}
-
-type SetupResolution =
-  | { readonly status: 'found'; readonly item: Record<string, unknown> }
-  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
-  | { readonly status: 'missing_lookup'; readonly usage: string };
-
-type SetupLookupSource = 'setupItemId' | 'target' | 'query';
-
-interface SurfaceRegistryLike {
-  syncConfiguredSurfaces(): readonly OnboardingSurfaceRecord[];
-}
-
-function readString(value: unknown): string {
-  return typeof value === 'string' ? value.trim() : '';
-}
-
-function readLimit(value: unknown, fallback: number): number {
-  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
-  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
-  return Math.max(1, Math.min(500, Math.trunc(parsed)));
-}
-
-function safeIso(value: number | null | undefined): string | null {
-  if (typeof value !== 'number' || !Number.isFinite(value)) return null;
-  return new Date(value).toISOString();
-}
-
-function surfaceRegistry(context: CommandContext): SurfaceRegistryLike | undefined {
-  const candidate = (context.platform as { readonly surfaceRegistry?: unknown }).surfaceRegistry;
-  if (candidate && typeof candidate === 'object' && 'syncConfiguredSurfaces' in candidate) {
-    return candidate as SurfaceRegistryLike;
-  }
-  return undefined;
-}
-
-async function collectSnapshot(context: CommandContext) {
-  const registry = surfaceRegistry(context);
-  return await collectOnboardingSnapshot({
-    config: requirePlatform(context).configManager,
-    shellPaths: requireShellPaths(context),
-    acknowledgementScope: 'project',
-    subscriptions: requireSubscriptionManager(context),
-    secrets: requireSecretsManager(context),
-    auth: requireLocalUserAuthManager(context),
-    services: requireServiceRegistry(context),
-    ...(registry ? {
-      surfaces: {
-        list: () => registry.syncConfiguredSurfaces(),
-      },
-    } : {}),
-    providerAccounts: {
-      loadSnapshot: () => buildProviderAccountSnapshot({
-        providerModels: requireProvider(context).providerRegistry,
-        services: requireServiceRegistry(context),
-        subscriptions: requireSubscriptionManager(context),
-        environment: {
-          hasEnvironmentVariable: (name: string) => Boolean(process.env[name]),
-        },
-      }),
-    },
-  });
-}
-
-function lookupFromArgs(args: AgentHarnessSetupArgs): { readonly source: SetupLookupSource; readonly input: string } | null {
-  const setupItemId = readString(args.setupItemId);
-  if (setupItemId) return { source: 'setupItemId', input: setupItemId };
-  const target = readString(args.target);
-  if (target) return { source: 'target', input: target };
-  const query = readString(args.query);
-  return query ? { source: 'query', input: query } : null;
-}
-
-function itemSearchText(item: OnboardingStep1CapabilityItem): string {
-  return [
-    item.id,
-    item.label,
-    item.detail,
-    item.selected ? 'selected ready configured enabled' : 'optional attention unselected',
-  ].join('\n').toLowerCase();
-}
-
-function summarizeLocalBehavior(snapshot: Awaited<ReturnType<typeof collectSnapshot>>): Record<string, unknown> {
-  const discovery = snapshot.localBehaviorDiscovery;
-  return {
-    personas: discovery.personas,
-    skills: discovery.skills,
-    routines: discovery.routines,
-  };
-}
-
-function signalsForItem(
-  item: OnboardingStep1CapabilityItem,
-  snapshot: Awaited<ReturnType<typeof collectSnapshot>>,
-): Record<string, unknown> {
-  if (item.id === 'provider-access') {
-    return {
-      currentRoute: snapshot.providerRouting,
-      providerAccounts: {
-        providers: snapshot.providerAccounts?.providers.length ?? 0,
-        configured: snapshot.providerAccounts?.configuredCount ?? 0,
-        issues: snapshot.providerAccounts?.issueCount ?? 0,
-      },
-      subscriptions: {
-        active: snapshot.subscriptions.active.length,
-        pending: snapshot.subscriptions.pending.length,
-        activeProviderIds: snapshot.subscriptions.activeProviderIds,
-        pendingProviderIds: snapshot.subscriptions.pendingProviderIds,
-      },
-      credentialReferences: snapshot.secrets.records.length,
-    };
-  }
-  if (item.id === 'local-behavior') {
-    return summarizeLocalBehavior(snapshot);
-  }
-  if (item.id === 'communication-channels') {
-    return {
-      configuredEnabledKinds: snapshot.surfaces.configuredEnabledKinds,
-      surfaces: snapshot.surfaces.records.map((surface) => ({
-        id: surface.id,
-        kind: surface.kind,
-        label: surface.label,
-        enabled: surface.enabled,
-        state: surface.state,
-        capabilities: surface.capabilities,
-      })),
-    };
-  }
-  if (item.id === 'automation-review') {
-    return {
-      permissionsMode: snapshot.runtimeDefaults.permissionsMode,
-      helperEnabled: snapshot.providerRouting.helperEnabled,
-      toolLlmEnabled: snapshot.providerRouting.toolLlmEnabled,
-    };
-  }
-  if (item.id === 'operator-terminal') {
-    return {
-      display: snapshot.runtimeDefaults.display,
-      setupMarker: {
-        scope: snapshot.acknowledgements.scope,
-        exists: snapshot.acknowledgements.exists,
-        updatedAt: safeIso(snapshot.acknowledgements.updatedAt),
-        source: snapshot.acknowledgements.source,
-        mode: snapshot.acknowledgements.mode ?? null,
-      },
-      collectionIssues: snapshot.collectionIssues,
-    };
-  }
-  return {
-    status: item.selected ? 'covered' : 'available',
-  };
-}
-
-function describeItem(
-  item: OnboardingStep1CapabilityItem,
-  snapshot: Awaited<ReturnType<typeof collectSnapshot>>,
-  options: {
-    readonly includeParameters?: boolean;
-    readonly lookup?: Record<string, unknown>;
-  } = {},
-): Record<string, unknown> {
+export async function setupPostureCatalogStatus(context: CommandContext): Promise<Record<string, unknown>> {
+  const snapshot = await collectSnapshot(context);
+  const servicePosture = await collectServicePosture(context);
+  const plan = buildSetupPlan(context, snapshot, deriveStep1Capabilities(snapshot), servicePosture);
+  const setupSmokeEvidence = latestSetupSmokeEvidence(context);
+  const setupSmokeHistory = setupSmokeEvidenceHistory(context);
+  const setupWizard = buildSetupWizard(plan, context);
   return {
-    setupItemId: item.id,
-    label: item.label,
-    selected: item.selected,
-    modelRoute: setupItemModelRoute(),
-    ...(options.lookup ? { lookup: options.lookup } : {}),
-    ...(options.includeParameters
-      ? {
-        detail: item.detail,
-        signals: signalsForItem(item, snapshot),
-        policy: {
-          effect: 'read-only',
-          values: 'Setup posture returns onboarding readiness, counts, safe setting keys, and route metadata only; secret values and raw provider tokens are never returned.',
-          mutation: 'Setup apply, provider auth, local behavior import/create, channel delivery, and starter profile changes stay visible workspace, settings, slash-command, or first-class tool flows.',
-        },
-        modelAccess: {
-          inspectSetup: 'agent_harness mode:"setup_posture"',
-          inspectSetupItem: 'agent_harness mode:"setup_item"',
-          openOnboarding: 'agent_harness mode:"open_ui_surface" surfaceId:"onboarding" confirm:true explicitUserRequest:"..."',
-          setupWorkspace: 'agent_harness mode:"workspace_action" target:"setup"',
-          settings: 'agent_harness mode:"settings"; inspect or mutate with get_setting, set_setting, or reset_setting',
-          providerRouting: 'agent_harness mode:"model_routing"',
-          providerAccounts: 'agent_harness mode:"provider_accounts"',
-          channels: 'agent_harness mode:"channels"',
-          media: 'agent_harness mode:"media_posture"',
-          security: 'agent_harness mode:"security_posture"',
-        },
-      }
-      : {
-        summary: previewHarnessText(item.detail),
-      }),
+    modes: ['setup_posture', 'setup_item', 'setup_repair', 'setup_checkpoint', 'mark_setup_checkpoint', 'clear_setup_checkpoint', 'provision_connected_host_token', 'run_setup_smoke'],
+    capabilities: deriveStep1Capabilities(snapshot).length,
+    planItems: plan.length,
+    blockedPlanItems: plan.filter((item) => item.status === 'blocked').length,
+    autonomyBlockers: plan.filter((item) => item.blocksAutonomy && item.status !== 'ready').length,
+    nextSetupHandoffs: nextSetupHandoffSummaries(plan, 5),
+    setupWizard,
+    setupCloseout: setupWizard.closeout,
+    collectionIssues: snapshot.collectionIssues.length,
+    setupMarkerExists: setupCompletionMarkerExists(context),
+    setupSmokeEvidence,
+    setupSmokeHistory,
+    readOnly: true,
   };
 }
 
-function setupItemModelRoute(): string {
-  return 'agent_harness mode:"setup_item" or mode:"open_ui_surface"';
-}
+export async function setupRepairSummary(context: CommandContext, args: AgentHarnessSetupArgs): Promise<Record<string, unknown>> {
+  const snapshot = await collectSnapshot(context);
+  const servicePosture = await collectServicePosture(context);
+  const plan = buildSetupPlan(context, snapshot, deriveStep1Capabilities(snapshot), servicePosture);
+  const setupWizard = buildSetupWizard(plan, context);
+  const includeParameters = args.includeParameters === true;
+  const target = setupRepairTarget(plan, setupWizard, args);
+  if ('error' in target) return target.error;
 
-function describeCandidate(item: OnboardingStep1CapabilityItem): Record<string, unknown> {
+  const item = target.item;
+  const decision = primarySetupRepairDecision(item);
+  const handoffs = setupHandoffsForItem(item);
+  const alternatives = handoffs
+    .filter((handoff) => handoff.id !== decision.id)
+    .slice(0, includeParameters ? 8 : 3)
+    .map((handoff) => describeHandoffCard(handoff, includeParameters));
+  const confirmedCandidates = confirmedRepairCandidates(item);
   return {
+    mode: 'setup_repair',
+    capturedAt: new Date(snapshot.capturedAt).toISOString(),
     setupItemId: item.id,
     label: item.label,
-    selected: item.selected,
-    modelRoute: setupItemModelRoute(),
-  };
-}
-
-export async function setupPostureCatalogStatus(context: CommandContext): Promise<Record<string, unknown>> {
-  const snapshot = await collectSnapshot(context);
-  return {
-    modes: ['setup_posture', 'setup_item'],
-    capabilities: deriveStep1Capabilities(snapshot).length,
-    collectionIssues: snapshot.collectionIssues.length,
-    setupMarkerExists: snapshot.acknowledgements.exists,
-    readOnly: true,
+    status: item.status,
+    blocksAutonomy: item.blocksAutonomy,
+    lookup: target.lookup,
+    decision: describeRepairDecision(decision, includeParameters),
+    nextAction: previewHarnessText(item.nextAction, includeParameters ? 220 : 140),
+    userRoute: previewHarnessText(item.userRoute, includeParameters ? 160 : 120),
+    modelRoute: previewHarnessText(item.modelRoute, includeParameters ? 160 : 120),
+    alternatives,
+    ...(confirmedCandidates.length > 0 ? {
+      possibleConfirmedRepairs: confirmedCandidates.map((candidate) => describeRepairDecision(candidate, includeParameters)),
+    } : {}),
+    ...(item.serviceProbe ? { serviceProbe: item.serviceProbe } : {}),
+    ...(item.serviceLifecycleDecision ? { serviceLifecycleDecision: describeServiceLifecycleDecision(item.serviceLifecycleDecision) } : {}),
+    ...(includeParameters && item.repairCards ? { repairCards: item.repairCards.map(describeRepairCard) } : {}),
+    ...(includeParameters && item.bootstrapPlan ? { bootstrapPlan: item.bootstrapPlan } : {}),
+    ...(includeParameters && item.authPosture ? { authPosture: item.authPosture } : {}),
+    setupWizard: {
+      status: setupWizard.status,
+      currentStepId: setupWizard.currentStepId,
+      currentStepLabel: setupWizard.currentStepLabel,
+      closeout: setupWizard.closeout,
+    },
+    routes: {
+      inspectSetup: DEFAULT_AGENT_SETUP_WIZARD_REVIEW_ROUTE,
+      inspectItem: `setup action:"item" setupItemId:"${quoteRouteValue(item.id)}" includeParameters:true`,
+      rerunRepair: `setup action:"repair" setupItemId:"${quoteRouteValue(item.id)}" includeParameters:true`,
+    },
+    policy: {
+      effect: 'read-only-repair-decision',
+      boundary: 'This route chooses the safest next setup repair route only. It never starts, installs, restarts, writes tokens, imports settings, or opens UI by itself.',
+      confirmation: 'Any returned confirmed-effect route still requires confirm:true and explicitUserRequest tied to the user request.',
+      hostOwnership: 'GoodVibes Agent does not take ambient ownership of the GoodVibes host lifecycle; disconnected hosts use user-run bootstrap guidance, and reachable hosts use daemon receipts before lifecycle mutation.',
+    },
   };
 }
 
 export async function setupPostureSummary(context: CommandContext, args: AgentHarnessSetupArgs): Promise<Record<string, unknown>> {
   const snapshot = await collectSnapshot(context);
+  const servicePosture = await collectServicePosture(context);
   const query = readString(args.query).toLowerCase();
   const includeParameters = args.includeParameters === true;
   const all = deriveStep1Capabilities(snapshot);
+  const plan = buildSetupPlan(context, snapshot, all, servicePosture);
+  const setupSmokeEvidence = latestSetupSmokeEvidence(context);
+  const setupSmokeHistory = setupSmokeEvidenceHistory(context);
+  const setupWizard = buildSetupWizard(plan, context);
   const filtered = all
     .filter((item) => !query || itemSearchText(item).includes(query))
     .slice(0, readLimit(args.limit, 100));
+  const filteredPlan = plan
+    .filter((item) => !query || planSearchText(item).includes(query))
+    .slice(0, readLimit(args.limit, 100));
   return {
     capturedAt: new Date(snapshot.capturedAt).toISOString(),
     setupMarker: {
       scope: snapshot.acknowledgements.scope,
       exists: snapshot.acknowledgements.exists,
+      completionExists: setupCompletionMarkerExists(context),
       updatedAt: safeIso(snapshot.acknowledgements.updatedAt),
       source: snapshot.acknowledgements.source,
       mode: snapshot.acknowledgements.mode ?? null,
@@ -265,9 +141,26 @@ export async function setupPostureSummary(context: CommandContext, args: AgentHa
       enabledSurfaceKinds: snapshot.surfaces.configuredEnabledKinds.length,
       localBehavior: summarizeLocalBehavior(snapshot),
       capabilityFlags: deriveStep1CapabilityFlags(snapshot),
+      readinessPlan: planSummary(plan),
+      setupSmokeEvidence,
+      setupSmokeHistory,
+      setupWizard: {
+        status: setupWizard.status,
+        progressLabel: setupWizard.progressLabel,
+        currentStepId: setupWizard.currentStepId,
+        currentStepLabel: setupWizard.currentStepLabel,
+        repeatedBlocker: setupWizard.repeatedBlocker,
+      },
+      setupCloseout: setupWizard.closeout,
     },
+    setupSmokeEvidence,
+    setupSmokeHistory,
+    setupWizard,
+    setupCloseout: setupWizard.closeout,
     currentRoute: snapshot.providerRouting,
     issues: snapshot.collectionIssues,
+    readinessPlan: filteredPlan.map((item) => describePlanItem(item, includeParameters)),
+    nextSetupActions: nextSetupHandoffSummaries(plan, 5),
     capabilities: filtered.map((item) => describeItem(item, snapshot, { includeParameters })),
     returned: filtered.length,
     total: all.length,
@@ -275,6 +168,330 @@ export async function setupPostureSummary(context: CommandContext, args: AgentHa
   };
 }
 
+export async function setupCheckpointSummary(context: CommandContext): Promise<Record<string, unknown>> {
+  const snapshot = await collectSnapshot(context);
+  const servicePosture = await collectServicePosture(context);
+  const plan = buildSetupPlan(context, snapshot, deriveStep1Capabilities(snapshot), servicePosture);
+  const setupWizard = buildSetupWizard(plan, context);
+  return {
+    mode: 'setup_checkpoint',
+    checkpoint: setupWizard.checkpoint,
+    currentStep: setupWizard.currentStepId
+      ? setupWizard.steps.find((step) => step.id === setupWizard.currentStepId) ?? null
+      : null,
+    setupWizard: {
+      status: setupWizard.status,
+      progressLabel: setupWizard.progressLabel,
+      currentStepId: setupWizard.currentStepId,
+      currentStepLabel: setupWizard.currentStepLabel,
+      next: setupWizard.next,
+    },
+    routes: {
+      inspectSetup: DEFAULT_AGENT_SETUP_WIZARD_REVIEW_ROUTE,
+      markCurrent: DEFAULT_AGENT_SETUP_WIZARD_MARK_CHECKPOINT_ROUTE,
+      clear: DEFAULT_AGENT_SETUP_WIZARD_CLEAR_CHECKPOINT_ROUTE,
+    },
+    policy: 'Read-only checkpoint inspection. Saving or clearing the setup wizard checkpoint requires a confirmed route with explicit user request.',
+  };
+}
+
+export async function markSetupCheckpoint(context: CommandContext, args: AgentHarnessSetupArgs): Promise<Record<string, unknown>> {
+  const snapshot = await collectSnapshot(context);
+  const servicePosture = await collectServicePosture(context);
+  const plan = buildSetupPlan(context, snapshot, deriveStep1Capabilities(snapshot), servicePosture);
+  const setupWizard = buildSetupWizard(plan, context);
+  const requestedStepId = readString(args.setupItemId);
+  const step = requestedStepId
+    ? setupWizard.steps.find((candidate) => candidate.id === requestedStepId)
+    : setupWizard.currentStepId
+      ? setupWizard.steps.find((candidate) => candidate.id === setupWizard.currentStepId)
+      : null;
+  if (!step) {
+    return {
+      status: 'no_checkpoint_written',
+      mode: 'mark_setup_checkpoint',
+      reason: requestedStepId
+        ? `Unknown setup wizard step ${requestedStepId}.`
+        : 'Setup wizard has no current step to checkpoint.',
+      setupWizard: {
+        status: setupWizard.status,
+        currentStepId: setupWizard.currentStepId,
+        currentStepLabel: setupWizard.currentStepLabel,
+      },
+      routes: {
+        inspectSetup: DEFAULT_AGENT_SETUP_WIZARD_REVIEW_ROUTE,
+      },
+    };
+  }
+  if (step.sourceStatus === 'ready') {
+    return {
+      status: 'no_checkpoint_written',
+      mode: 'mark_setup_checkpoint',
+      reason: `Setup wizard step ${step.label} is already ready.`,
+      step,
+      routes: {
+        inspectSetup: DEFAULT_AGENT_SETUP_WIZARD_REVIEW_ROUTE,
+        clear: DEFAULT_AGENT_SETUP_WIZARD_CLEAR_CHECKPOINT_ROUTE,
+      },
+    };
+  }
+  const shellPaths = requireShellPaths(context);
+  const checkpoint = saveSetupWizardCheckpoint(shellPaths, {
+    currentStepId: step.id,
+    currentStepLabel: step.label,
+    source: 'harness',
+    note: 'User-confirmed setup wizard checkpoint.',
+  });
+  const updatedWizard = buildSetupWizard(plan, context);
+  return {
+    status: 'checkpoint_saved',
+    mode: 'mark_setup_checkpoint',
+    explicitUserRequest: previewHarnessText(readString(args.explicitUserRequest), 160),
+    step,
+    checkpoint,
+    setupWizard: {
+      status: updatedWizard.status,
+      progressLabel: updatedWizard.progressLabel,
+      currentStepId: updatedWizard.currentStepId,
+      currentStepLabel: updatedWizard.currentStepLabel,
+      checkpoint: updatedWizard.checkpoint,
+    },
+    routes: {
+      inspectCheckpoint: DEFAULT_AGENT_SETUP_WIZARD_INSPECT_CHECKPOINT_ROUTE,
+      inspectSetup: DEFAULT_AGENT_SETUP_WIZARD_REVIEW_ROUTE,
+      clear: DEFAULT_AGENT_SETUP_WIZARD_CLEAR_CHECKPOINT_ROUTE,
+    },
+    policy: {
+      effect: 'confirmed-setup-checkpoint-save',
+      boundary: 'Only the current setup wizard step id, label, source, timestamp, and generic note were saved in Agent-owned setup state.',
+    },
+  };
+}
+
+export function clearSetupCheckpoint(context: CommandContext, args: AgentHarnessSetupArgs): Record<string, unknown> {
+  const shellPaths = requireShellPaths(context);
+  const checkpoint = clearSetupWizardCheckpoint(shellPaths);
+  return {
+    status: 'checkpoint_cleared',
+    mode: 'clear_setup_checkpoint',
+    explicitUserRequest: previewHarnessText(readString(args.explicitUserRequest), 160),
+    checkpoint,
+    routes: {
+      inspectCheckpoint: DEFAULT_AGENT_SETUP_WIZARD_INSPECT_CHECKPOINT_ROUTE,
+      inspectSetup: DEFAULT_AGENT_SETUP_WIZARD_REVIEW_ROUTE,
+      markCurrent: DEFAULT_AGENT_SETUP_WIZARD_MARK_CHECKPOINT_ROUTE,
+    },
+    policy: {
+      effect: 'confirmed-setup-checkpoint-clear',
+      boundary: 'Removed only the Agent-owned setup wizard checkpoint file.',
+    },
+  };
+}
+
+export function provisionConnectedHostOperatorToken(context: CommandContext, args: AgentHarnessSetupArgs): Record<string, unknown> {
+  const setupItemId = readString(args.setupItemId);
+  if (setupItemId && setupItemId !== 'connected-host-auth') {
+    return {
+      status: 'unsupported_setup_item',
+      usage: 'provision_connected_host_token supports setupItemId:"connected-host-auth" only.',
+    };
+  }
+
+  const shellPaths = requireShellPaths(context);
+  const before = readConnectedHostOperatorToken(shellPaths.homeDirectory);
+  const explicitUserRequest = readString(args.explicitUserRequest);
+  const beforeFingerprint = before.token ? connectedHostOperatorTokenFingerprint(before.token) : null;
+  if (before.token && before.path.startsWith('env:')) {
+    return {
+      status: 'already_usable_env_token',
+      mode: 'provision_connected_host_token',
+      setupItemId: 'connected-host-auth',
+      explicitUserRequest: previewHarnessText(explicitUserRequest, 160),
+      token: {
+        path: before.path,
+        present: true,
+        usable: true,
+        fingerprint: beforeFingerprint,
+        rawValueReturned: false,
+      },
+      mutation: {
+        performed: false,
+        reason: 'Environment-provided connected-host token is already effective; no local token file was written.',
+      },
+      routes: {
+        inspectAuth: 'setup action:"item" setupItemId:"connected-host-auth"',
+        inspectStatus: 'host action:"status" includeParameters:true',
+        pairingPosture: 'agent_harness mode:"pairing_posture" includeParameters:true',
+      },
+      policy: {
+        effect: 'confirmed-local-token-provisioning',
+        secrets: 'Raw connected-host tokens are never returned.',
+        boundary: 'Environment-provided tokens take precedence and are not modified by this route.',
+      },
+    };
+  }
+
+  const daemonHomeDir = join(shellPaths.homeDirectory, '.goodvibes', 'daemon');
+  const canonicalPath = connectedHostOperatorTokenPath(shellPaths.homeDirectory);
+  try {
+    const record = getOrCreateCompanionToken(GOODVIBES_AGENT_PAIRING_SURFACE, { daemonHomeDir });
+    const after = readConnectedHostOperatorToken(shellPaths.homeDirectory);
+    if (!after.token) {
+      return {
+        status: 'failed',
+        mode: 'provision_connected_host_token',
+        setupItemId: 'connected-host-auth',
+        explicitUserRequest: previewHarnessText(explicitUserRequest, 160),
+        error: after.error ? previewHarnessText(after.error, 160) : 'SDK token provisioning completed but no usable connected-host token was readable.',
+        token: {
+          path: after.path,
+          present: after.present,
+          usable: false,
+          rawValueReturned: false,
+        },
+        routes: {
+          inspectAuth: 'setup action:"item" setupItemId:"connected-host-auth"',
+          inspectStatus: 'host action:"status" includeParameters:true',
+        },
+      };
+    }
+    const afterFingerprint = connectedHostOperatorTokenFingerprint(after.token);
+    const changed = beforeFingerprint !== afterFingerprint;
+    const result = before.token
+      ? changed ? 'repaired' : 'already_usable'
+      : before.present ? 'repaired' : 'created';
+    return {
+      status: result,
+      mode: 'provision_connected_host_token',
+      setupItemId: 'connected-host-auth',
+      explicitUserRequest: previewHarnessText(explicitUserRequest, 160),
+      token: {
+        path: after.path,
+        canonicalPath,
+        present: true,
+        usable: true,
+        fingerprint: afterFingerprint,
+        rawValueReturned: false,
+        fileMode: safeFileMode(canonicalPath),
+      },
+      companionRecord: {
+        surface: GOODVIBES_AGENT_PAIRING_SURFACE,
+        peerId: record.peerId,
+        createdAt: safeIso(record.createdAt),
+      },
+      mutation: {
+        performed: result === 'created' || result === 'repaired',
+        result,
+        existingTokenPreserved: result === 'already_usable',
+        source: 'getOrCreateCompanionToken',
+      },
+      routes: {
+        inspectAuth: 'setup action:"item" setupItemId:"connected-host-auth"',
+        inspectStatus: 'host action:"status" includeParameters:true',
+        pairingPosture: 'agent_harness mode:"pairing_posture" includeParameters:true',
+        runSetupSmoke: DEFAULT_AGENT_SETUP_WIZARD_RERUN_SMOKE_ROUTE,
+      },
+      policy: {
+        effect: 'confirmed-local-token-provisioning',
+        source: 'SDK platform pairing helper writes the canonical connected-host operator token file with owner-only permissions.',
+        secrets: 'Only path, fingerprint, peer id, and timestamps are returned; the raw token is not returned.',
+        rotation: 'This route preserves a valid existing token and only creates or repairs the local canonical file.',
+      },
+    };
+  } catch (error) {
+    return {
+      status: 'failed',
+      mode: 'provision_connected_host_token',
+      setupItemId: 'connected-host-auth',
+      explicitUserRequest: previewHarnessText(explicitUserRequest, 160),
+      error: previewHarnessText(error instanceof Error ? error.message : String(error), 160),
+      token: {
+        path: canonicalPath,
+        present: before.present,
+        usable: false,
+        rawValueReturned: false,
+      },
+      routes: {
+        inspectAuth: 'setup action:"item" setupItemId:"connected-host-auth"',
+        inspectStatus: 'host action:"status" includeParameters:true',
+      },
+      policy: {
+        effect: 'confirmed-local-token-provisioning',
+        secrets: 'Raw connected-host tokens are never returned.',
+      },
+    };
+  }
+}
+
+export async function runSetupInstallSmoke(context: CommandContext, args: AgentHarnessSetupArgs): Promise<Record<string, unknown>> {
+  const setupItemId = readString(args.setupItemId);
+  if (setupItemId && setupItemId !== 'install-smoke') {
+    return {
+      status: 'unsupported_setup_item',
+      usage: 'run_setup_smoke currently supports setupItemId:"install-smoke" only.',
+    };
+  }
+
+  const snapshot = await collectSnapshot(context);
+  const servicePosture = await collectServicePosture(context);
+  const plan = buildSetupPlan(context, snapshot, deriveStep1Capabilities(snapshot), servicePosture);
+  const installSmoke = plan.find((item) => item.id === 'install-smoke');
+  const smokePlan = installSmoke?.installSmokePlan;
+  if (!smokePlan) {
+    return {
+      status: 'missing_smoke_plan',
+      usage: 'Install smoke plan is not available. Inspect mode:"setup_posture" for setup readiness.',
+    };
+  }
+
+  const includeParameters = args.includeParameters === true;
+  const summary = installSmokeRunSummary(smokePlan);
+  const blockedChecks = smokePlan.checks.filter((check) => check.status === 'blocked').map((check) => check.id);
+  const userRunChecks = smokePlan.checks.filter((check) => check.status === 'user-run').map((check) => check.id);
+  const capturedAt = new Date(snapshot.capturedAt).toISOString();
+  const explicitUserRequest = readString(args.explicitUserRequest);
+  const evidenceFields = setupSmokeEvidenceFields(args.fields);
+  const artifact = await saveSetupSmokeArtifact({
+    context,
+    capturedAt,
+    explicitUserRequest,
+    smokePlan,
+    summary,
+    blockedChecks,
+    userRunChecks,
+    evidenceFields,
+  });
+  return {
+    status: 'executed',
+    mode: 'run_setup_smoke',
+    setupItemId: 'install-smoke',
+    capturedAt,
+    smokeStatus: smokePlan.status,
+    result: installSmokeRunResult(smokePlan),
+    explicitUserRequest: previewHarnessText(explicitUserRequest, 160),
+    summary,
+    blockedChecks,
+    userRunChecks,
+    checks: smokePlan.checks.map((check) => describeInstallSmokeCheck(check, includeParameters)),
+    artifact,
+    successCriteria: includeParameters ? smokePlan.successCriteria : smokePlan.successCriteria.map((entry) => previewHarnessText(entry, 120)),
+    nextAction: installSmokeNextAction(smokePlan),
+    routes: {
+      inspectSetup: DEFAULT_AGENT_SETUP_WIZARD_REVIEW_ROUTE,
+      inspectSmoke: 'setup action:"item" setupItemId:"install-smoke"',
+      rerunSmoke: DEFAULT_AGENT_SETUP_WIZARD_RERUN_SMOKE_ROUTE,
+      saveEvidence: DEFAULT_AGENT_SETUP_WIZARD_SAVE_SMOKE_ROUTE,
+    },
+    policy: {
+      effect: 'confirmed-redacted-setup-smoke',
+      shell: 'No package, host, or shell commands were executed implicitly.',
+      secrets: 'Secrets and connected-host tokens are never returned; token evidence remains presence, path, and fingerprint only.',
+      source: smokePlan.policy,
+    },
+    source: smokePlan.source,
+  };
+}
+
 export async function describeHarnessSetupItem(context: CommandContext, args: AgentHarnessSetupArgs): Promise<SetupResolution> {
   const lookup = lookupFromArgs(args);
   if (!lookup) {
@@ -284,19 +501,30 @@ export async function describeHarnessSetupItem(context: CommandContext, args: Ag
     };
   }
   const snapshot = await collectSnapshot(context);
+  const servicePosture = await collectServicePosture(context);
   const items = deriveStep1Capabilities(snapshot);
+  const plan = buildSetupPlan(context, snapshot, items, servicePosture);
   const normalized = lookup.input.toLowerCase();
   const exact = items.find((item) => item.id === lookup.input);
   if (exact) return { status: 'found', item: describeItem(exact, snapshot, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'id' } }) };
+  const exactPlan = plan.find((item) => item.id === lookup.input);
+  if (exactPlan) return { status: 'found', item: { ...describePlanItem(exactPlan, true), lookup: { ...lookup, resolvedBy: 'plan-id' } } };
   const insensitive = items.find((item) => item.id.toLowerCase() === normalized);
   if (insensitive) return { status: 'found', item: describeItem(insensitive, snapshot, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } }) };
+  const insensitivePlan = plan.find((item) => item.id.toLowerCase() === normalized);
+  if (insensitivePlan) return { status: 'found', item: { ...describePlanItem(insensitivePlan, true), lookup: { ...lookup, resolvedBy: 'case-insensitive-plan-id' } } };
   const searched = items.filter((item) => itemSearchText(item).includes(normalized));
-  if (searched.length === 1) return { status: 'found', item: describeItem(searched[0]!, snapshot, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }) };
-  if (searched.length > 1) {
+  const searchedPlan = plan.filter((item) => planSearchText(item).includes(normalized));
+  if (searched.length === 1 && searchedPlan.length === 0) return { status: 'found', item: describeItem(searched[0]!, snapshot, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }) };
+  if (searched.length === 0 && searchedPlan.length === 1) return { status: 'found', item: { ...describePlanItem(searchedPlan[0]!, true), lookup: { ...lookup, resolvedBy: 'plan-search' } } };
+  if (searched.length > 0 || searchedPlan.length > 0) {
     return {
       status: 'ambiguous',
       input: lookup.input,
-      candidates: searched.slice(0, 8).map(describeCandidate),
+      candidates: [
+        ...searched.map(describeCandidate),
+        ...searchedPlan.map((item) => describePlanItem(item, false)),
+      ].slice(0, 8),
     };
   }
   return {