@pellux/goodvibes-agent 1.9.1 → 1.10.0

package/src/runtime/bootstrap-external-services.ts

@@ -2,18 +2,28 @@
  * Connected-host (daemon + HTTP listener) discovery for GoodVibes Agent.
  *
  * Split out of bootstrap.ts (which is near the 800-line architecture cap) to
- * keep this concern — and its "GoodVibes Agent never owns the daemon
- * lifecycle" framing — in one small, readable place.
+ * keep this concern — and the Agent's daemon-lifecycle boundary — in one
+ * small, readable place.
  *
- * GoodVibes Agent never starts or restarts the connected daemon: every call
- * routes through the SDK-shared adopt-or-spawn policy
+ * Discovery routes through the SDK-shared adopt-or-spawn policy
  * (decideDaemonAdoption/classifyDaemonProbe) with `adoptOnly: true`, so a
  * reachable, version-compatible daemon is adopted and anything else (absent,
- * blocked, or on an incompatible wire version) is reported honestly. This
- * replaces a local stub that hard-declared every daemon 'external' without
- * probing or version-checking it.
+ * blocked, or on an incompatible wire version) is reported honestly. The
+ * Agent never spawns or embeds a daemon of its own and never restarts a
+ * running one. One bounded exception at boot: when discovery finds nothing
+ * on the configured port but the host's service entry IS installed on this
+ * machine, the Agent issues a single start through the platform service
+ * manager, waits a bounded time for the daemon to answer, re-probes, and
+ * reports what it did (see connected-host-autostart.ts). A machine with the
+ * host installed but stopped must not hand the user homework.
  */
 import { startExternalServices } from '@/runtime/index.ts';
+import {
+  autostartInstalledConnectedHost,
+  createConnectedHostServiceControl,
+  type ConnectedHostServiceControl,
+} from './connected-host-autostart.ts';
+import type { SpineReachability } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
 import type {
   DeferredStartupCoordinator,
   ExternalServicesHandle,
@@ -65,9 +75,25 @@ const hostServiceIsBlocked = (status: HostServiceStatus): boolean => status.mode
 export interface AgentExternalServicesController {
   /** The most recently resolved (or pending) connected-host status. */
   getStatus(): ExternalServicesHandle;
+  /**
+   * Resolves once the deferred boot discovery (including any boot-time start
+   * of an installed-but-stopped host) has settled. Later probes that reuse
+   * the daemon's reachability (session/memory spine adoption) await this so
+   * they see the post-discovery daemon state instead of racing it.
+   */
+  whenDiscovered(): Promise<void>;
   stop(): Promise<void>;
 }
 
+/** Test seams for the boot-time start of an installed-but-stopped host. */
+export interface ConnectedHostAutostartSeams {
+  readonly control?: ConnectedHostServiceControl;
+  readonly probeReachability?: () => Promise<SpineReachability>;
+  readonly waitTimeoutMs?: number;
+  readonly pollIntervalMs?: number;
+  readonly sleep?: (ms: number) => Promise<void>;
+}
+
 export function wireAgentExternalServices(options: {
   readonly configManager: HostServicesConfig;
   readonly runtimeBus: RuntimeEventBus;
@@ -77,8 +103,23 @@ export function wireAgentExternalServices(options: {
   readonly deferredStartup: DeferredStartupCoordinator;
   readonly systemMessageRouter: SystemMessageRouter;
   readonly requestRender: () => void;
+  /** Injectable discovery implementation (tests); defaults to the SDK-shared policy. */
+  readonly startServices?: typeof startExternalServices;
+  readonly connectedHostAutostart?: ConnectedHostAutostartSeams;
 }): AgentExternalServicesController {
   const { configManager, runtimeBus, hookDispatcher, services, uiServices, deferredStartup, systemMessageRouter, requestRender } = options;
+  const startServices = options.startServices ?? startExternalServices;
+
+  // Connected-host honesty receipts ("updated from X to Y", "restarted after
+  // a crash at HH:MM", settings migrations) captured off the once-per-attach
+  // ?receipts=consume /status read (bootstrap.ts's memory-spine onAttach):
+  // delivery at the daemon is destructive (served once, to the consuming
+  // reader), so every captured receipt renders here — buffered ones from before
+  // this sink attaches flush immediately.
+  services.daemonReceiptFeed.attach((receipt) => {
+    systemMessageRouter.high(`[Connected host] ${receipt.text}`);
+    requestRender();
+  });
 
   const inspectAgentDependencies = () => {
     const daemonStatus = externalServices.daemonStatus;
@@ -103,8 +144,60 @@ export function wireAgentExternalServices(options: {
   };
   let externalServicesPromise: Promise<ExternalServicesHandle> | null = null;
 
+  // Deliberately NOT passing the daemon facade's `updateArtifact` identity
+  // ({version, execPath}): with adoptOnly the agent never constructs or embeds
+  // a DaemonServer, so there is no daemon-side hourly update loop here to feed
+  // — absent means host-managed, which is exactly the agent's stance toward
+  // whichever host it adopts. The agent's OWN binary updates at launch through
+  // its launch auto-update path instead (src/cli/launch-auto-update.ts).
   const startAgentExternalServices = (): Promise<ExternalServicesHandle> =>
-    startExternalServices(configManager, runtimeBus, hookDispatcher, services, { adoptOnly: true });
+    startServices(configManager, runtimeBus, hookDispatcher, services, { adoptOnly: true });
+
+  // Boot-time start of an installed-but-stopped host: when discovery found
+  // nothing on the configured port, check the platform service manager for an
+  // installed host entry, start it once, wait a bounded time, and re-probe.
+  // Every skip/failure path is honest; errors here never break discovery.
+  const maybeStartInstalledConnectedHost = async (): Promise<void> => {
+    const seams = options.connectedHostAutostart ?? {};
+    try {
+      const outcome = await autostartInstalledConnectedHost({
+        daemonStatus: externalServices.daemonStatus,
+        control: seams.control ?? createConnectedHostServiceControl({
+          configManager: services.configManager,
+          workingDirectory: services.workingDirectory,
+          homeDirectory: services.homeDirectory,
+        }),
+        probeReachability: seams.probeReachability ?? (() => services.sessionSpineClient.probeReachability()),
+        waitTimeoutMs: seams.waitTimeoutMs,
+        pollIntervalMs: seams.pollIntervalMs,
+        sleep: seams.sleep,
+      });
+      switch (outcome.action) {
+        case 'started':
+        case 'came-online': {
+          externalServicesPromise = startAgentExternalServices();
+          externalServices = await externalServicesPromise;
+          const adopted = externalServices.daemonStatus.mode === 'external';
+          const suffix = adopted
+            ? ''
+            : ` — but adopting it still failed: ${externalServices.daemonStatus.reason ?? externalServices.daemonStatus.mode}`;
+          systemMessageRouter.low(outcome.action === 'started'
+            ? `[Startup] Connected host was installed but stopped; started it (service "${outcome.serviceName}")${suffix}.`
+            : `[Startup] Connected host service "${outcome.serviceName}" was already starting; connected once it answered${suffix}.`);
+          break;
+        }
+        case 'start-failed': {
+          systemMessageRouter.high(`[Startup] Connected host is installed but not answering, and starting it did not succeed: ${outcome.reason}. Start it manually with: goodvibes service start`);
+          break;
+        }
+        case 'not-installed':
+        case 'none':
+          break;
+      }
+    } catch (error) {
+      logger.debug('Boot-time connected-host start check failed', { error: summarizeError(error) });
+    }
+  };
 
   const platformExternalServices = uiServices.platform as typeof uiServices.platform & {
     externalServices: NonNullable<typeof uiServices.platform.externalServices>;
@@ -122,7 +215,7 @@ export function wireAgentExternalServices(options: {
       await externalServices.stop();
       externalServicesPromise = startAgentExternalServices();
       externalServices = await externalServicesPromise;
-      systemMessageRouter.high('[Startup] GoodVibes Agent does not start or restart the connected GoodVibes host — it adopted the current status from a fresh probe.');
+      systemMessageRouter.high('[Startup] GoodVibes Agent re-probed the connected GoodVibes host and adopted its current status; this route never starts or restarts the host itself.');
       requestRender();
       return inspectAgentDependencies();
     },
@@ -131,12 +224,14 @@ export function wireAgentExternalServices(options: {
   // Connected-host discovery OFF the interactive path: probe the configured
   // host/port through the shared adopt-or-spawn policy (adoptOnly — Agent
   // never spawns or embeds) and replace the pending status with an honest
-  // one (adopted, incompatible, blocked, or unavailable).
-  deferredStartup.schedule({
+  // one (adopted, incompatible, blocked, or unavailable). An unavailable
+  // daemon then gets the one bounded installed-but-stopped start check.
+  const discoveryComplete = deferredStartup.schedule({
     label: 'external-services',
     run: async () => {
       externalServicesPromise = startAgentExternalServices();
       externalServices = await externalServicesPromise;
+      await maybeStartInstalledConnectedHost();
       requestRender();
     },
     onError: (error) => {
@@ -149,6 +244,7 @@ export function wireAgentExternalServices(options: {
 
   return {
     getStatus: () => externalServices,
+    whenDiscovered: () => discoveryComplete,
     stop: async () => {
       await externalServices.stop();
     },

package/src/runtime/bootstrap-hook-bridge.ts

@@ -28,7 +28,7 @@ export interface ResumeSessionOptions {
   readonly hookDispatcher: HookDispatcher;
   readonly sessionManager: SessionManager;
   readonly configManager: Pick<ConfigManager, 'get' | 'getCategory'>;
-  readonly providerRegistry: Pick<ProviderRegistry, 'get' | 'getCurrentModel' | 'getForModel' | 'require'>;
+  readonly providerRegistry: Pick<ProviderRegistry, 'get' | 'getCurrentModel' | 'getForModel' | 'require' | 'resolveModelPricing'>;
 }
 
 export function createResumeSessionHandler(options: ResumeSessionOptions): (sessionId: string) => void {
@@ -54,7 +54,7 @@ export function createResumeSessionHandler(options: ResumeSessionOptions): (sess
       if (meta?.provider) options.runtime.provider = meta.provider;
       options.writeLastSessionPointer(sessionId);
       void options.sharedSessionBroker.reopenSession(sessionId).catch((err) => { logger.debug('session broker reopen session failed', { err }); });
-      // W2A: mirror the reopen into the daemon spine — reopen:true is sent ONLY on
+      // Mirror the reopen into the daemon spine — reopen:true is sent ONLY on
       // this explicit user resume verb (fire-and-forget; never blocks the resume).
       options.sessionSpineClient.reopen({ sessionId, project: options.projectRoot });
       options.conversation.log(`Resumed session: ${sessionId}`, { fg: '135' });

package/src/runtime/bootstrap-shell.ts

@@ -8,7 +8,6 @@ import type { RuntimeStore } from './store/index.ts';
 import type { RuntimeServices } from './services.ts';
 import type { CommandContext } from '../input/command-registry.ts';
 import type { AgentPromptContextReceiptStore } from '../agent/prompt-context-receipts.ts';
-import type { OpsControlPlane } from '@/runtime/index.ts';
 import { CommandRegistry } from '../input/command-registry.ts';
 import { registerBuiltinCommands } from '../input/commands.ts';
 import { InputHistory } from '../input/input-history.ts';
@@ -58,7 +57,6 @@ export interface BootstrapShellOptions {
   readonly policyRuntimeState: PolicyRuntimeState;
   readonly uiServices: UiRuntimeServices;
   readonly taskManager: TaskManager;
-  readonly opsControlPlane?: OpsControlPlane;
   readonly completeModelSelectionSideEffect?: () => void;
 }
 
@@ -119,7 +117,6 @@ export function createBootstrapShell(options: BootstrapShellOptions): BootstrapS
     policyRuntimeState,
     uiServices,
     taskManager,
-    opsControlPlane,
     completeModelSelectionSideEffect,
   } = options;
 
@@ -156,11 +153,14 @@ export function createBootstrapShell(options: BootstrapShellOptions): BootstrapS
 
   const commandRegistry = new CommandRegistry();
   registerBuiltinCommands(commandRegistry);
+  // No opsControlPlane: the Agent's product boundary keeps connected-host
+  // tasks read-only (see /tasks: every mutation subcommand is blocked and
+  // routed to /workplan or /delegate), so the opsApi intervention verbs
+  // honestly report the control plane as unavailable.
   const foundationClients = createRuntimeFoundationClients({
     runtimeServices: services,
     tasksReadModel: uiServices.readModels.tasks,
     taskManager,
-    opsControlPlane,
   });
   const {
     directTransport,

package/src/runtime/bootstrap.ts

@@ -11,6 +11,7 @@
  */
 import { Orchestrator, type OrchestratorUserInputOptions } from '../core/orchestrator.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { collectStartupAnnouncements } from '@pellux/goodvibes-sdk/platform/runtime/feature-announcements';
 import type { PermissionRequestHandler } from '@pellux/goodvibes-sdk/platform/permissions';
 import type { CommandContext } from '../input/command-registry.ts';
 import type { InputHistory } from '../input/input-history.ts';
@@ -20,7 +21,6 @@ import type { Compositor } from '../renderer/compositor.ts';
 import type { RuntimeContext, BootstrapOptions } from './context.ts';
 import { shutdownRuntime, fireSessionStart, saveSession } from '@/runtime/index.ts';
 import { createTaskManager } from '@/runtime/index.ts';
-import { OpsControlPlane } from '@/runtime/index.ts';
 import type { SystemMessageRouter } from '../core/system-message-router.ts';
 import { emitSessionReady, emitSessionStarted } from '@/runtime/index.ts';
 import {
@@ -77,7 +77,7 @@ const GOODVIBES_AGENT_OPERATOR_POLICY = [
   '## GoodVibes Agent Operator Policy',
   '- Act as one user-facing autonomous assistant. Prefer the lowest-friction safe path that completes the user outcome; do not expose internal package or host ownership unless it is needed for diagnosis, setup, or safety.',
   '- Work serially in the main conversation by default for ordinary chat, research, planning, setup, local context, and short tool work. Use visible schedules, work plans, operator actions, or delegated/remote routes for durable or long-running autonomy.',
-  '- Connected-host lifecycle is not ambient. If the host is unavailable, explain the shortest user action to make the assistant reachable; do not pretend a missing host route worked.',
+  '- Connected-host lifecycle is not ambient beyond one bounded boot behavior: at startup the runtime starts an installed-but-stopped host through the platform service manager and reports it. If the host is unavailable after that, explain the shortest user action to make the assistant reachable; do not pretend a missing host route worked.',
   '- Read tools: `route action:"plan|status"`, `schedule action:"list"`, `setup action:"status|item|repair|checkpoint"`, `settings action:"list|get"`, `vibe action:"status|show"`, `context action:"status|files|file|prompt|receipts|receipt"`, `memory action:"status|provider|curator|candidate|list|search|get"`, `channels action:"status|channel|setup|triage|deliveries"`, `models action:"status|route|local|providers|provider"`, `personal_ops action:"briefing|status|queue|intake|lane"`, `autonomy action:"intake|queue|item|status"`, `delegation action:"status|routes|route"`, `execution action:"status|route|history|record|processes|process_capabilities|process|recovery"`, `security action:"status|finding|explain"`, `support action:"status|bundle"`, `sessions action:"list|get"`, `audit action:"readiness|item|evidence|artifact"`, `computer action:"status|plan|control|browser|setup|mcp"`, `research action:"plan|search|runner|runs|run|sources|source|bundle|reports|report_artifact"`, `device action:"status|capability|browser|control|voice|provider"`, `workspace action:"status|actions|action|surfaces|surface|shortcuts|keybindings|keybinding|commands|command|cli_commands|cli_command"`, `host action:"status|capabilities|capability|services|service|methods|method"`, `import_goodvibes_settings action:"preview"`, and `agent_operator_briefing` for connected work/approvals/automation/schedules, `agent_knowledge` for isolated Agent Knowledge, and `agent_harness` for harness catalogs/status/capability discovery. Use `agent_artifacts` for saved artifact list/preview/export/package/archive; write modes are confirmation-gated.',
   '- Harness access: use `settings action:"set|reset|import"` and `workspace action:"run|run_command|open|run_keybinding|set_keybinding|reset_keybinding"` to use the same surfaces the user can use; lower-level `agent_harness` modes remain for detail inspection and compatibility.',
   '- State tools: `agent_work_plan` for visible local work items; `agent_local_registry` for Agent-local notes, memory, personas, skills, bundles, and routines; `agent_learning_consolidation` for confirmed duplicate cleanup phases; `agent_documents` for versioned Agent document drafts. Keep records non-secret, sourced, and reviewable.',
@@ -395,9 +395,6 @@ export async function bootstrapRuntime(
   }));
 
   const opsTaskManager = createTaskManager(store, runtimeBus, userSessionId);
-  const opsControlPlane = services.featureFlags.isEnabled('operator-control-plane')
-    ? new OpsControlPlane(opsTaskManager, runtimeBus, store, userSessionId)
-    : undefined;
 
   const shell = createBootstrapShell({
     configManager,
@@ -420,13 +417,23 @@ export async function bootstrapRuntime(
     policyRuntimeState: services.policyRuntimeState,
     uiServices,
     taskManager: opsTaskManager,
-    opsControlPlane,
     completeModelSelectionSideEffect: () => {
       compositor.resetDiff();
     },
   });
   const systemMessageRouter = shell.systemMessageRouter;
   systemMessageRouterRef.value = systemMessageRouter;
+  // Announce-once receipts due at boot (e.g. the web surface URL when
+  // web.enabled). The store is shared per install, so whichever process of
+  // this install boots first (daemon, TUI, or this Agent) announces; every
+  // other process stays silent. Mirrors the SDK daemon boot's collection.
+  for (const announcement of collectStartupAnnouncements({
+    configManager,
+    store: services.featureAnnouncementStore,
+  })) {
+    logger.info(announcement.text, { announcement: announcement.id });
+    systemMessageRouter.low(`[Startup] ${announcement.text}`);
+  }
   const commandRegistry = shell.commandRegistry;
   const commandContext = shell.commandContext;
   const inputHistory = shell.inputHistory;
@@ -478,9 +485,11 @@ export async function bootstrapRuntime(
 
   const deferredStartup = createDeferredStartupCoordinator();
 
-  // GoodVibes Agent never owns the connected daemon's (or HTTP listener's)
+  // GoodVibes Agent does not own the connected daemon's (or HTTP listener's)
   // lifecycle — see bootstrap-external-services.ts for the adopt-only wiring
-  // and the deferred discovery probe it schedules.
+  // and the deferred discovery probe it schedules. One bounded exception at
+  // boot: a host that is INSTALLED on this machine but stopped is started
+  // once through the platform service manager, with an honest receipt.
   const agentExternalServices = wireAgentExternalServices({
     configManager,
     runtimeBus,
@@ -519,13 +528,15 @@ export async function bootstrapRuntime(
       requestRender();
     },
   });
-  // W2A: probe the daemon spine OFF the interactive path. On a reachable daemon,
+  // Probe the daemon spine OFF the interactive path. On a reachable daemon,
   // fold the agent's own per-cwd legacy session store into it (once; marked
-  // migrated). Never starts the daemon; a down/absent daemon leaves the agent
-  // local-only with an honest offline status.
+  // migrated). Waits for connected-host discovery (which may have just started
+  // an installed-but-stopped daemon) so this probe sees the settled state; a
+  // down/absent daemon leaves the agent local-only with an honest offline status.
   deferredStartup.schedule({
     label: 'session-spine',
     run: async () => {
+      await agentExternalServices.whenDiscovered();
       const reachability = await services.sessionSpineClient.probeReachability();
       if (reachability !== 'online') return;
       foldLegacySpineStore(services.sessionSpineClient, {
@@ -558,10 +569,21 @@ export async function bootstrapRuntime(
     memorySpineClient: services.memorySpineClient,
     transport: services.memorySpineTransport,
     probeReachability: () => services.sessionSpineClient.probeReachability(),
+    // One consuming /status read per attach: a current daemon delivers its
+    // one-shot honesty receipts ("restarted after a crash at HH:MM", "updated
+    // from X to Y") only to a ?receipts=consume read, and this adoption edge is
+    // exactly where the agent (re)attaches to a daemon. The plain liveness probe
+    // stays receipt-neutral.
+    onAttach: () => services.consumeDaemonReceipts(),
   });
   deferredStartup.schedule({
     label: 'memory-spine',
     run: async () => {
+      // Wait for connected-host discovery (which may have just started an
+      // installed-but-stopped daemon) so the first adoption decision sees the
+      // settled daemon state instead of racing it; the heartbeat below keeps
+      // reconciling for the rest of the process lifetime either way.
+      await agentExternalServices.whenDiscovered();
       await reconcileMemorySpine();
       // Prime the recall snapshot (SDK 1.2.0 sync-recall seam) so the FIRST
       // system prompt built after boot already has a real snapshot to read
@@ -721,7 +743,7 @@ export async function bootstrapRuntime(
     commandRegistry,
     systemMessageRouter,
     shutdown: async (sessionData) => {
-      // W2A: best-effort spine close (short timeout, fire-and-forget) then stop
+      // Best-effort spine close (short timeout, fire-and-forget) then stop
       // the heartbeat timer. Tolerates a racing daemon stop; never blocks teardown.
       services.sessionSpineClient.close(runtime.sessionId);
       services.sessionSpineClient.dispose();

package/src/runtime/connected-host-autostart.ts

@@ -0,0 +1,269 @@
+/**
+ * Boot-time start of an installed-but-stopped connected GoodVibes host.
+ *
+ * When boot discovery finds nothing on the configured daemon host/port, a
+ * machine that actually HAS the host installed should not hand the user
+ * homework. This module checks whether the host's service entry is present
+ * for the platform service manager and, when it is installed but stopped,
+ * issues one start through that service manager, then waits a bounded time
+ * for the daemon to answer before the session proceeds.
+ *
+ * Boundaries that stay exactly as strict as before:
+ *   - A reachable daemon (adopted or embedded) is never restarted.
+ *   - A held port ('blocked' by an unverified process, or 'incompatible'
+ *     wire version) is respected and left alone — the closest states the
+ *     probe has to "another owner is mid-update or mid-restart".
+ *   - A service unit that the service manager already reports active gets a
+ *     bounded wait only, never a second start command underneath it.
+ *   - The Agent still never spawns or embeds a daemon of its own, and a host
+ *     that is genuinely not installed keeps the existing honest guidance.
+ *
+ * Detection reuses the platform's one existing installed-daemon detector,
+ * the SDK's PlatformServiceManager (`status().installed` = service entry
+ * present, `status().running` = live service-manager query). It is checked
+ * for the connected host's managed service name and for the older unit name
+ * earlier installs used; a `service.serviceName` config value overrides both,
+ * through the manager's own name resolution.
+ */
+import { PlatformServiceManager, type ManagedServiceStatus } from '@pellux/goodvibes-sdk/platform/daemon';
+import type { SpineReachability } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
+import type { ConfigManager } from '../config/index.ts';
+
+/** The connected host's managed service name (the goodvibes CLI's default). */
+export const MANAGED_CONNECTED_HOST_SERVICE_NAME = 'goodvibes';
+/** The unit name older connected-host installs registered. */
+export const LEGACY_CONNECTED_HOST_SERVICE_NAME = 'goodvibes-daemon';
+
+/** Structural mirror of the SDK service manager's action-runner result. */
+export interface ConnectedHostServiceActionResult {
+  readonly status: number | null;
+  readonly stdout?: string | undefined;
+  readonly stderr?: string | undefined;
+}
+
+/** One candidate service entry, as the platform service manager sees it. */
+export interface ConnectedHostServiceSnapshot {
+  readonly serviceName: string;
+  readonly platform: ManagedServiceStatus['platform'];
+  readonly unitPath: string;
+  readonly installed: boolean;
+  readonly running: boolean;
+  /**
+   * False on the 'manual' platform: there the SDK manager would spawn its own
+   * locally-resolved command, which the Agent cannot honestly resolve for a
+   * host it does not own — those stay on the guidance path.
+   */
+  readonly startSupported: boolean;
+}
+
+export interface ConnectedHostServiceStartResult {
+  readonly ok: boolean;
+  readonly error?: string | undefined;
+}
+
+/** Narrow detector/starter seam over the SDK's PlatformServiceManager. */
+export interface ConnectedHostServiceControl {
+  snapshot(): readonly ConnectedHostServiceSnapshot[];
+  start(serviceName: string): ConnectedHostServiceStartResult;
+}
+
+export interface ConnectedHostServiceControlOptions {
+  readonly configManager: ConfigManager;
+  readonly workingDirectory: string;
+  readonly homeDirectory: string;
+  /** Injectable systemctl/launchctl/schtasks runner so tests never touch the host. */
+  readonly actionRunner?: ((command: string, args: readonly string[]) => ConnectedHostServiceActionResult) | undefined;
+}
+
+function summarizeThrown(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Build the detector/starter over the SDK's PlatformServiceManager.
+ *
+ * When `service.serviceName` is configured, the manager's own resolution
+ * collapses every candidate to that one name, so a single manager is built;
+ * otherwise the managed and legacy default names are each checked.
+ */
+export function createConnectedHostServiceControl(
+  options: ConnectedHostServiceControlOptions,
+): ConnectedHostServiceControl {
+  // The config schema ships `service.serviceName` with the managed default, so
+  // get() never returns undefined here. A value that IS the managed default
+  // (configured or defaulted — indistinguishable, and equivalent) also gets the
+  // older unit name checked; any other value is an explicit operator choice and
+  // is trusted exclusively.
+  const primaryName = String(options.configManager.get('service.serviceName') ?? '').trim()
+    || MANAGED_CONNECTED_HOST_SERVICE_NAME;
+  const candidateNames = primaryName === MANAGED_CONNECTED_HOST_SERVICE_NAME
+    ? [MANAGED_CONNECTED_HOST_SERVICE_NAME, LEGACY_CONNECTED_HOST_SERVICE_NAME]
+    : [primaryName];
+  // Pin each manager's view of `service.serviceName` to its candidate so the
+  // SDK's own name resolution yields exactly that unit (the schema default
+  // would otherwise shadow every `defaultServiceName`). Only `get` is consulted
+  // by the manager, so the narrow delegate below is honest.
+  const pinnedConfigView = (serviceName: string): ConfigManager => ({
+    get: (key: string) => key === 'service.serviceName' ? serviceName : options.configManager.get(key as Parameters<ConfigManager['get']>[0]),
+  }) as unknown as ConfigManager;
+  const managers = candidateNames.map((resolvedName) => ({
+    resolvedName,
+    manager: new PlatformServiceManager(pinnedConfigView(resolvedName), {
+      workingDirectory: options.workingDirectory,
+      homeDirectory: options.homeDirectory,
+      // Match the connected host's own service scope (log/pid file layout on the
+      // manual platform); systemd/launchd/windows entries are home-scoped anyway.
+      surfaceRoot: 'daemon',
+      defaultServiceName: resolvedName,
+      ...(options.actionRunner ? { actionRunner: options.actionRunner } : {}),
+    }),
+  }));
+
+  const toSnapshot = (status: ManagedServiceStatus): ConnectedHostServiceSnapshot => ({
+    serviceName: status.serviceName,
+    platform: status.platform,
+    unitPath: status.path,
+    installed: status.installed,
+    running: status.running,
+    startSupported: status.platform !== 'manual',
+  });
+
+  return {
+    snapshot(): readonly ConnectedHostServiceSnapshot[] {
+      const seen = new Set<string>();
+      const snapshots: ConnectedHostServiceSnapshot[] = [];
+      for (const { resolvedName, manager } of managers) {
+        if (seen.has(resolvedName)) continue;
+        seen.add(resolvedName);
+        snapshots.push(toSnapshot(manager.status()));
+      }
+      return snapshots;
+    },
+    start(serviceName: string): ConnectedHostServiceStartResult {
+      const candidate = managers.find((entry) => entry.resolvedName === serviceName);
+      if (!candidate) {
+        return { ok: false, error: `no service entry named "${serviceName}" is tracked on this host` };
+      }
+      try {
+        const result = candidate.manager.start();
+        return result.actionError === undefined
+          ? { ok: true }
+          : { ok: false, error: result.actionError };
+      } catch (error) {
+        return { ok: false, error: summarizeThrown(error) };
+      }
+    },
+  };
+}
+
+/** Subset of the discovery status the autostart decision needs. */
+export interface ConnectedHostDaemonStatusView {
+  readonly mode: 'disabled' | 'embedded' | 'external' | 'blocked' | 'incompatible' | 'unavailable';
+}
+
+export type ConnectedHostAutostartOutcome =
+  /** Nothing to do: the daemon answers, the port is held, or the daemon is disabled by config. */
+  | { readonly action: 'none'; readonly reason: 'daemon-active' | 'port-held' | 'daemon-disabled' }
+  /** No service entry is installed on this host — the existing guidance path is unchanged. */
+  | { readonly action: 'not-installed' }
+  /** The Agent issued a start through the service manager and the daemon answered. */
+  | { readonly action: 'started'; readonly serviceName: string }
+  /** The service unit was already active (starting or restarting); the daemon answered within the bounded wait, with no start issued. */
+  | { readonly action: 'came-online'; readonly serviceName: string }
+  /** A start was attempted (or was impossible) and the daemon still does not answer; guidance applies, with this reason. */
+  | { readonly action: 'start-failed'; readonly serviceName: string; readonly reason: string };
+
+export interface ConnectedHostAutostartOptions {
+  readonly daemonStatus: ConnectedHostDaemonStatusView;
+  readonly control: ConnectedHostServiceControl;
+  readonly probeReachability: () => Promise<SpineReachability>;
+  /** Total bounded wait for the daemon to answer after a start (default 8000ms). */
+  readonly waitTimeoutMs?: number | undefined;
+  /** Poll interval within the bounded wait (default 400ms). */
+  readonly pollIntervalMs?: number | undefined;
+  /** Injectable so tests drive the wait loop deterministically. */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+
+const DEFAULT_WAIT_TIMEOUT_MS = 8_000;
+const DEFAULT_POLL_INTERVAL_MS = 400;
+
+/**
+ * Decide and (when safe) perform the boot-time start of an installed-but-
+ * stopped connected host. Pure over its seams: every effect goes through
+ * `control` and `probeReachability`.
+ */
+export async function autostartInstalledConnectedHost(
+  options: ConnectedHostAutostartOptions,
+): Promise<ConnectedHostAutostartOutcome> {
+  const waitTimeoutMs = options.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+  const pollIntervalMs = Math.max(1, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  }));
+  // Attempt-counted (not wall-clock) so an injected no-op sleep still terminates.
+  const attempts = Math.max(1, Math.ceil(waitTimeoutMs / pollIntervalMs));
+
+  const waitForAnswer = async (): Promise<boolean> => {
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      if (attempt > 0) await sleep(pollIntervalMs);
+      if ((await options.probeReachability()) === 'online') return true;
+    }
+    return false;
+  };
+
+  switch (options.daemonStatus.mode) {
+    case 'embedded':
+    case 'external':
+      // A running daemon is never restarted.
+      return { action: 'none', reason: 'daemon-active' };
+    case 'blocked':
+    case 'incompatible':
+      // The port is held — by an unverified process or a daemon this build
+      // refuses to adopt. Either way another owner may be mid-update or
+      // mid-restart; never fight it.
+      return { action: 'none', reason: 'port-held' };
+    case 'disabled':
+      return { action: 'none', reason: 'daemon-disabled' };
+    case 'unavailable':
+      break;
+  }
+
+  const installed = options.control.snapshot().find((snapshot) => snapshot.installed);
+  if (!installed) return { action: 'not-installed' };
+
+  if (installed.running) {
+    // The service manager already reports the unit active — it may be mid-start
+    // or mid-restart. Wait for it, but never issue another start underneath it.
+    if (await waitForAnswer()) return { action: 'came-online', serviceName: installed.serviceName };
+    return {
+      action: 'start-failed',
+      serviceName: installed.serviceName,
+      reason: `service "${installed.serviceName}" is active per the service manager but the daemon did not answer within ${waitTimeoutMs}ms — check its logs`,
+    };
+  }
+
+  if (!installed.startSupported) {
+    return {
+      action: 'start-failed',
+      serviceName: installed.serviceName,
+      reason: `service "${installed.serviceName}" is installed without a service-manager entry this Agent can start`,
+    };
+  }
+
+  const startResult = options.control.start(installed.serviceName);
+  if (!startResult.ok) {
+    return {
+      action: 'start-failed',
+      serviceName: installed.serviceName,
+      reason: startResult.error ?? 'the service start command failed',
+    };
+  }
+  if (await waitForAnswer()) return { action: 'started', serviceName: installed.serviceName };
+  return {
+    action: 'start-failed',
+    serviceName: installed.serviceName,
+    reason: `the service start command was accepted but the daemon did not answer within ${waitTimeoutMs}ms`,
+  };
+}