@pellux/goodvibes-agent 1.8.0 → 1.8.2

package/docs/tools-and-commands.md

@@ -180,6 +180,12 @@ Foreground `exec` remains the default for tests, builds, and one-shot commands.
 
 Settings discovery accepts `settings action:"list"` with `category`, `prefix`, `query`, `includeHidden:true`, and `limit`. It is compact by default and each row includes a short first-class `modelRoute` that distinguishes read-only settings from set/reset-capable settings; use `includeParameters:true` or `settings action:"get"` for full descriptions/defaults. Single setting reads/writes resolve by `key`, `target`, or `query`; ambiguous matches are refused. Secret-backed setting writes through `settings action:"set"` store raw values through the secret manager and return redacted output. Shared GoodVibes settings import is `settings action:"import"`: it previews by default and applies with `confirm:true explicitUserRequest:"..."`. The preview includes source-package ownership metadata so users can see that goodvibes-tui or another published GoodVibes platform store remains source-owned and is not mutated by Agent. `import_goodvibes_settings action:"preview|apply"`, `setup action:"import_settings"`, and `workspace action:"run" actionId:"import-goodvibes-tui-settings"` remain available for compatibility or visible form parity; lower-level `agent_harness mode:"run_workspace_action"` remains a detailed compatibility route. Connected-host lifecycle/listener settings are read-only in Agent.
 
+Workspace-checkpoint root and retention guards are configured through a manual `checkpoints` block in `settings.json` (these are passed straight through to the SDK's workspace checkpoint manager and are not part of the discoverable settings catalog, so `settings action:"list"` does not surface them). The recognized keys are `checkpoints.preferGitRoot` (prefer the enclosing git repository's top level over the raw working directory; default on), `checkpoints.allowBroadRoot` (opt in to snapshotting a broad root such as the filesystem root, the home directory, or `~/.goodvibes`; default off), `checkpoints.allowLargeFirstSnapshot` (opt in to a first snapshot whose full sweep exceeds the file ceiling; default off), `checkpoints.maxFirstSnapshotFiles` (the ceiling for the first-ever snapshot's file sweep), and `checkpoints.autoRetention` (run a retention sweep automatically after each successful checkpoint and once at init; default on). Any key you omit falls back to the manager's own default. These guards are defense in depth: even a registered workspace can still be refused as too broad or too large.
+
+Automatic (turn-end/lifecycle) checkpoints are restricted to workspaces COVERED by the shared registration store (owner ruling, 2026-07-10; store migrated to the SDK's platform/workspace/registration in SDK 1.6.1). `goodvibes-agent workspaces list|register [path] [--label <label>] --yes|unregister [path] --yes` manages the registry (path defaults to the current working directory); it is user-scoped, agent-local state, not a connected-host concept. Coverage flows down a registered root's subtree and is inherited through the git worktree→main-repo link, so an orchestration-spawned sibling worktree of a registered repo checkpoints automatically without being registered itself. An unregistered/uncovered workspace gets no automatic checkpoints, and an explicit `checkpoints.create` gateway call against it is refused with a registration hint rather than silently registering the workspace on the caller's behalf. `checkpoints.unregisteredWorkspaces` (`"off"` default, or `"guarded"`) is the opt-out: `"guarded"` restores the pre-ruling behavior for that workspace (automatic checkpoints subscribe, explicit create proceeds) subject only to the root/retention guards above. `goodvibes-agent status`/`doctor` state the posture honestly — `checkpoints off: workspace not registered` when off, never silent.
+
+Best-of-N attempt groups (SDK 1.6.1 orchestration engine) are reviewed and resolved with `goodvibes-agent fleet attempts list [--workstream <workstreamId>]|pick <groupId> <winnerItemId> --yes|judge <groupId>`. This reads this Agent's own orchestration engine state directly (disk-persisted workstream snapshots), not a connected-host call — `fleet.attempts.*` is a ws-only gateway verb family with no HTTP binding, so neither this CLI command nor `agent_operator_method` can reach it over HTTP. `list` shows every held-merge group (siblings that ran in isolated worktrees and are held for a winner pick instead of auto-merging) with each candidate's diff, usage, and any prior judge proposal. `judge` runs the optional judge model and PROPOSES a winner — always rendered as a clearly labeled model proposal, never a decision — and `pick` is the confirm-gated action that actually merges the winner and cleans losing worktrees.
+
 Keybinding discovery returns fixed shortcuts plus the live resolved binding table. Fixed shortcuts and configurable bindings include direct `modelRoute` and `modelAccess` metadata so the model can distinguish supported routes from direct-user-only controls. `workspace action:"run_keybinding"` only executes actions with faithful current-shell routes. Prompt-editor-only shortcuts, terminal text selection, category cycling, and reserved shortcuts stay direct user interaction.
 
 ## Connected Host And Daemon
@@ -265,7 +271,9 @@ Routine promotion is an explicit scheduling route. Local routines stay local unt
 | `/brief` | Show a concise Agent operator briefing and next actions. |
 | `/bundle` | Export, inspect, or import redacted Agent support bundles from the TUI. |
 | `/calendar` | Manage a local calendar: list upcoming events, import or export .ics files, and add or remove events. |
+| `/channel-profiles` | List, set, or delete per-channel session profile bindings (model, provider, permission mode) on the connected host; mutations require `--yes`. |
 | `/channels` | Inspect channel readiness, delivery receipts, or send one explicitly confirmed delivery message. |
+| `/ci` | Check a repo or PR's CI with per-job conclusions and manage standing CI watches with channel delivery; mutations require `--yes`. |
 | `/clear` | Clear the conversation display while keeping LLM context. |
 | `/collapse` | Collapse rendered blocks by type. |
 | `/commands` | Browse all commands in a scrollable list. |
@@ -298,6 +306,7 @@ Routine promotion is an explicit scheduling route. Local routines stay local unt
 | `/personas` | Manage Agent-local personas. |
 | `/pin` | Pin a model to the favorites list. |
 | `/prev-error` | Jump to the previous error message in the conversation. |
+| `/principals` | Manage the connected host's cross-channel principal identity registry; unmapped senders show as "unknown principal" in session attribution. |
 | `/provider` | Switch provider or manage custom providers. |
 | `/qrcode` | Print companion pairing details and a QR code. |
 | `/quit` | Exit the application. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "private": false,
   "description": "GoodVibes personal operator assistant TUI with a proactive Agent product brain, isolated Agent Knowledge, local profiles, routines, skills, personas, and explicit build delegation.",
   "type": "module",
@@ -92,7 +92,8 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@pellux/goodvibes-sdk": "1.6.1",
+    "@pellux/goodvibes-sdk": "1.7.1",
+    "@pellux/goodvibes-terminal-shell": "1.7.1",
     "sql.js": "^1.14.1",
     "sqlite-vec": "^0.1.9",
     "zustand": "^5.0.12",

package/src/agent/capability-registry.ts

@@ -0,0 +1,300 @@
+/**
+ * Capability readiness registry — the single source of truth for how mature
+ * each advertised capability is.
+ *
+ * The agent advertises capabilities (voice, deep research, computer control,
+ * calendar, email, telephony, local models, and more) whose real maturity
+ * varies. This registry records, for every advertised capability, a declared
+ * readiness level that must be verifiable rather than aspirational.
+ *
+ * LEVELS (and nothing else):
+ *   - `certified`   A live-verification scenario exercises the capability and
+ *                   passed in the current release report. Each certified entry
+ *                   names the scenario id it maps to (see live-verifier.ts).
+ *   - `working`     Implemented and covered by unit/integration tests, but no
+ *                   live-verification scenario exercises it yet.
+ *   - `needs-setup` Implemented, but the user must configure something
+ *                   (credentials, a provider, a device) before it can run.
+ *   - `preview`     Partial implementation. The note states plainly what works.
+ *
+ * A capability that would only be "planning-only" is NOT given a level here —
+ * it is removed from advertised surfaces instead, consistent with the honesty
+ * bar. So every entry below has a real, shipped surface behind it.
+ *
+ * Onboarding copy, help text, and the tool catalogs render the level FROM this
+ * registry (see renderCapabilityReadinessLine). No surface hand-writes a
+ * duplicate maturity claim.
+ */
+
+export type CapabilityReadinessLevel = 'certified' | 'working' | 'needs-setup' | 'preview';
+
+/** The four declared levels, in maturity order. */
+export const CAPABILITY_READINESS_LEVELS: readonly CapabilityReadinessLevel[] = [
+  'certified',
+  'working',
+  'needs-setup',
+  'preview',
+];
+
+/** Plain user-facing label for each level, rendered in parentheses. */
+export const CAPABILITY_READINESS_USER_LABEL: Record<CapabilityReadinessLevel, string> = {
+  certified: 'verified live',
+  working: 'working',
+  'needs-setup': 'needs setup',
+  preview: 'preview',
+};
+
+export interface AdvertisedCapability {
+  /** Stable capability id. */
+  readonly id: string;
+  /** Plain-language title shown to users. */
+  readonly title: string;
+  /** Declared readiness level. */
+  readonly level: CapabilityReadinessLevel;
+  /**
+   * The live-verification scenario id this capability maps to. Required for
+   * `certified`, and must be absent for every other level.
+   */
+  readonly scenarioId?: string;
+  /**
+   * Surface identifiers where this capability is advertised: onboarding
+   * category ids, model-tool names, and command names. Used to attach the
+   * rendered readiness line to the right surface.
+   */
+  readonly surfaces: readonly string[];
+  /**
+   * The literal capability nouns as they appear in user-facing copy. The
+   * enforcement tests grep advertised surfaces for these and require a
+   * registry entry, so a surface can never advertise a capability that has no
+   * declared level.
+   */
+  readonly advertisedNames: readonly string[];
+  /** Plain description of what works and what does not. */
+  readonly readinessNote: string;
+}
+
+export const CAPABILITY_REGISTRY: readonly AdvertisedCapability[] = [
+  {
+    id: 'models',
+    title: 'Model routing',
+    level: 'certified',
+    scenarioId: 'openai-compatible-models',
+    surfaces: ['setup', 'models'],
+    advertisedNames: ['model routing'],
+    readinessNote:
+      'Cloud, subscription, and local model routing. A live check confirms the models route returns available models in each release report.',
+  },
+  {
+    id: 'agent-knowledge',
+    title: 'Agent Knowledge',
+    level: 'certified',
+    scenarioId: 'agent-knowledge-ask-isolated',
+    surfaces: ['onboarding-context', 'agent_knowledge'],
+    advertisedNames: ['Agent Knowledge', 'Knowledge'],
+    readinessNote:
+      'Isolated per-home knowledge with source provenance. A live check exercises the isolated ask route in each release report, and answers fail closed when provenance is missing.',
+  },
+  {
+    id: 'local-model-cookbook',
+    title: 'Local model cookbook',
+    level: 'working',
+    surfaces: ['setup', 'models'],
+    advertisedNames: ['local model'],
+    readinessNote:
+      'Hardware-scored local model recommendations scan processor, memory, and platform. Per-card memory and accelerator-model detection is not shipped.',
+  },
+  {
+    id: 'deep-research',
+    title: 'Deep research',
+    level: 'working',
+    surfaces: ['research'],
+    advertisedNames: ['research', 'deep research'],
+    readinessNote:
+      'Research runs, source review, and saved reports are implemented and unit-tested. Browser-backed runs need a connected host.',
+  },
+  {
+    id: 'documents',
+    title: 'Documents and review packets',
+    level: 'working',
+    surfaces: ['documents'],
+    advertisedNames: ['documents'],
+    readinessNote:
+      'Versioned drafts, suggestions, exports, and reviewer handoff packets are implemented and unit-tested.',
+  },
+  {
+    id: 'blind-model-comparison',
+    title: 'Model comparison',
+    level: 'working',
+    surfaces: ['documents', 'models'],
+    advertisedNames: ['model comparison'],
+    readinessNote:
+      'Blind comparison with delayed reveal, saved judgments, and confirmed route decisions are implemented and unit-tested.',
+  },
+  {
+    id: 'schedules-automation',
+    title: 'Schedules and automation',
+    level: 'working',
+    surfaces: ['automation', 'schedule'],
+    advertisedNames: ['schedules', 'routines'],
+    readinessNote:
+      'Schedules, reminders, and routines with a visible queue are implemented and unit-tested.',
+  },
+  {
+    id: 'local-context-memory',
+    title: 'Memory and personality',
+    level: 'working',
+    surfaces: ['onboarding-context', 'memory'],
+    advertisedNames: ['memory', 'personas', 'skills', 'routines'],
+    readinessNote:
+      'Local memory, personas, skills, and routines with review-first promotion are implemented and unit-tested.',
+  },
+  {
+    id: 'execution-shell',
+    title: 'Local execution',
+    level: 'working',
+    surfaces: ['execution', 'terminal', 'process'],
+    advertisedNames: ['run commands', 'shell commands'],
+    readinessNote:
+      'Local read, search, file edit, and bounded foreground commands are implemented and unit-tested.',
+  },
+  {
+    id: 'multi-agent-delegation',
+    title: 'Delegated work',
+    level: 'working',
+    surfaces: ['delegation'],
+    advertisedNames: ['delegation'],
+    readinessNote:
+      'Visible serial-by-default subagent records are implemented and unit-tested. Remote execution backends are limited to a connected host.',
+  },
+  {
+    id: 'image-input',
+    title: 'Image input',
+    level: 'working',
+    surfaces: ['onboarding-voice-media'],
+    advertisedNames: ['image input'],
+    readinessNote:
+      'Attaching an image is implemented and unit-tested. The selected model must support image understanding.',
+  },
+  {
+    id: 'messaging-channels',
+    title: 'Messaging',
+    level: 'needs-setup',
+    surfaces: ['onboarding-channels', 'channels'],
+    advertisedNames: ['messaging', 'Slack', 'Discord', 'Telegram'],
+    readinessNote:
+      'Messaging adapters are implemented; each channel must be enabled and given credentials before it can deliver.',
+  },
+  {
+    id: 'voice',
+    title: 'Voice controls',
+    level: 'needs-setup',
+    surfaces: ['onboarding-voice-media', 'device'],
+    advertisedNames: ['voice'],
+    readinessNote:
+      'Local listen-and-speak is implemented; it needs a microphone and a text-to-speech provider. Continuous talk mode and wake-word capture are not shipped.',
+  },
+  {
+    id: 'text-to-speech',
+    title: 'Spoken output',
+    level: 'needs-setup',
+    surfaces: ['onboarding-voice-media', 'device'],
+    advertisedNames: ['text-to-speech', 'TTS'],
+    readinessNote:
+      'Spoken replies work once a text-to-speech provider is configured.',
+  },
+  {
+    id: 'media-generation',
+    title: 'Media generation',
+    level: 'needs-setup',
+    surfaces: ['onboarding-voice-media'],
+    advertisedNames: ['media generation'],
+    readinessNote:
+      'Image and video generation is implemented; it needs configured media providers.',
+  },
+  {
+    id: 'telephony',
+    title: 'Telephony',
+    level: 'needs-setup',
+    surfaces: ['onboarding-voice-media', 'channels'],
+    advertisedNames: ['telephony', 'SMS'],
+    readinessNote:
+      'SMS, voice call, and bridge delivery are backed by a real delivery strategy; they need Twilio or bridge credentials.',
+  },
+  {
+    id: 'email',
+    title: 'Email',
+    level: 'needs-setup',
+    surfaces: ['email', 'personal-ops'],
+    advertisedNames: ['email'],
+    readinessNote:
+      'Direct IMAP and SMTP email is implemented; it needs account settings. Writing-style replies, auto-tagging, and spam triage are not shipped.',
+  },
+  {
+    id: 'calendar',
+    title: 'Calendar',
+    level: 'needs-setup',
+    surfaces: ['calendar', 'personal-ops'],
+    advertisedNames: ['calendar'],
+    readinessNote:
+      'Calendar import and export through .ics files is implemented. Direct CalDAV server sync is not shipped.',
+  },
+  {
+    id: 'computer-control',
+    title: 'Computer control',
+    level: 'preview',
+    surfaces: ['computer'],
+    advertisedNames: ['computer control', 'desktop control'],
+    readinessNote:
+      'Browser and desktop control is planning and readiness inspection in the agent today; actual control runs through a connected host once it certifies the route.',
+  },
+];
+
+/** Return the plain user-facing label for a level (rendered in parentheses). */
+export function capabilityReadinessUserLabel(level: CapabilityReadinessLevel): string {
+  return CAPABILITY_READINESS_USER_LABEL[level];
+}
+
+/** Look up a capability by its stable id. */
+export function getCapabilityById(id: string): AdvertisedCapability | undefined {
+  return CAPABILITY_REGISTRY.find((capability) => capability.id === id);
+}
+
+/**
+ * Look up a capability by an advertised noun (case-insensitive). Used by the
+ * enforcement tests to pin that any advertised capability name resolves to a
+ * declared readiness level.
+ */
+export function getCapabilityByAdvertisedName(name: string): AdvertisedCapability | undefined {
+  const needle = name.trim().toLowerCase();
+  return CAPABILITY_REGISTRY.find((capability) =>
+    capability.advertisedNames.some((advertised) => advertised.toLowerCase() === needle),
+  );
+}
+
+/** Every capability advertised on a given surface, in registry order. */
+export function capabilitiesForSurface(surface: string): readonly AdvertisedCapability[] {
+  return CAPABILITY_REGISTRY.filter((capability) => capability.surfaces.includes(surface));
+}
+
+/** Inline readiness suffix for a single capability, e.g. " (needs setup)". */
+export function capabilityReadinessSuffix(capability: AdvertisedCapability): string {
+  return ` (${capabilityReadinessUserLabel(capability.level)})`;
+}
+
+/**
+ * Render one plain readiness line for a surface, sourced entirely from the
+ * registry. Returns an empty string when no capability is advertised there,
+ * so a caller can append it unconditionally.
+ *
+ * Example: "Readiness: Voice controls (needs setup), Spoken output (needs
+ * setup), Image input (working), Media generation (needs setup), Telephony
+ * (needs setup)."
+ */
+export function renderCapabilityReadinessLine(surface: string): string {
+  const capabilities = capabilitiesForSurface(surface);
+  if (capabilities.length === 0) return '';
+  const parts = capabilities.map(
+    (capability) => `${capability.title}${capabilityReadinessSuffix(capability)}`,
+  );
+  return `Readiness: ${parts.join(', ')}.`;
+}

package/src/agent/email/style-reply-lane.ts

@@ -1,11 +1,20 @@
 /**
  * Personal Ops lane descriptor for the writing-style-matched draft-reply flow.
  *
+ * NOT SHIPPED / NOT WIRED (capability-honesty, 2026-07)
+ * ──────────────────────────────────────────────────────────────────────
+ * These descriptors are intentionally NOT wired into the advertised Personal
+ * Ops inbox lane (see agent-harness-personal-ops-lanes.ts). The Agent has no
+ * reader for the user's own sent-message corpus, so it cannot honestly claim a
+ * writing-style match, and competitive-feature-inventory.ts records
+ * writing-style-matched draft replies as "not yet shipped". The pure composer
+ * (style-reply.ts) and these descriptors stay as tested internal code for when
+ * the sent-corpus input and a real compose route ship together. Do not re-add
+ * buildStyleReplyLaneAdditions to buildLanes() until then.
+ *
  * This module defines the PersonalOpsWorkflow and PersonalOpsLiveRecord objects
- * that surface the style-reply capability inside the existing Personal Ops
- * 'inbox' lane.  It is integrated into buildLanes() in
- * agent-harness-personal-ops-lanes.ts by appending the exported items to the
- * inbox lane's workflows and liveRecords arrays.
+ * that would surface the style-reply capability inside the Personal Ops 'inbox'
+ * lane once the capability is genuinely shipped.
  *
  * BEFORE-SEND REVIEW BOUNDARY (enforced here and in style-reply.ts)
  * ──────────────────────────────────────────────────────────────────────

package/src/agent/memory-consolidation-receipts.ts

@@ -0,0 +1,79 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+import type { MemoryConsolidationRunReceipt } from '@pellux/goodvibes-sdk/platform/state';
+
+/**
+ * Durable, capped store of idle-consolidation run receipts. Same visible-receipt
+ * idiom as the prompt-context and per-phase consolidation receipts: an atomic
+ * JSON file under the Agent surface root, newest first, so every autonomous run
+ * leaves a record of what it merged, archived, decayed, and proposed.
+ */
+const RUN_RECEIPT_LIMIT = 50;
+
+export interface MemoryConsolidationReceiptFile {
+  readonly version: 1;
+  readonly receipts: readonly MemoryConsolidationRunReceipt[];
+}
+
+export function memoryConsolidationReceiptPath(shellPaths: ShellPathService): string {
+  return shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'learning', 'consolidation-run-receipts.json');
+}
+
+function isRunReceipt(value: unknown): value is MemoryConsolidationRunReceipt {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return typeof record.runId === 'string'
+    && typeof record.ranAt === 'string'
+    && Array.isArray(record.merged)
+    && Array.isArray(record.archived)
+    && Array.isArray(record.decayed)
+    && Array.isArray(record.proposed);
+}
+
+export class MemoryConsolidationReceiptStore {
+  public constructor(
+    private readonly shellPaths: ShellPathService,
+    private readonly limit = RUN_RECEIPT_LIMIT,
+  ) {}
+
+  public path(): string {
+    return memoryConsolidationReceiptPath(this.shellPaths);
+  }
+
+  public read(): readonly MemoryConsolidationRunReceipt[] {
+    const path = this.path();
+    if (!existsSync(path)) return [];
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(path, 'utf-8'));
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return [];
+      const receipts = (parsed as Record<string, unknown>).receipts;
+      if (!Array.isArray(receipts)) return [];
+      return receipts.filter(isRunReceipt);
+    } catch {
+      return [];
+    }
+  }
+
+  public list(limit = 20): readonly MemoryConsolidationRunReceipt[] {
+    return this.read().slice(0, Math.max(1, Math.min(this.limit, Math.trunc(limit))));
+  }
+
+  public latest(): MemoryConsolidationRunReceipt | null {
+    return this.read()[0] ?? null;
+  }
+
+  public record(receipt: MemoryConsolidationRunReceipt): MemoryConsolidationRunReceipt {
+    const path = this.path();
+    const next: MemoryConsolidationReceiptFile = {
+      version: 1,
+      receipts: [receipt, ...this.read()].slice(0, this.limit),
+    };
+    mkdirSync(dirname(path), { recursive: true });
+    const tmpPath = `${path}.tmp`;
+    writeFileSync(tmpPath, `${JSON.stringify(next, null, 2)}\n`, 'utf-8');
+    renameSync(tmpPath, path);
+    return receipt;
+  }
+}

package/src/agent/memory-prompt.ts

@@ -164,7 +164,9 @@ export interface BuildReviewedMemoryPromptOptions {
 
 export function buildReviewedMemoryPrompt(memoryRegistry: MemoryRegistry, options: BuildReviewedMemoryPromptOptions = {}): string | null {
   const limit = options.limit ?? DEFAULT_LIMIT;
-  const eligible = (options.records ?? memoryRegistry.getAll()).filter(isPromptActiveMemory);
+  // Bound to one arg — see prompt-context-receipts.ts's resolveMemoryRecords
+  // filter for why a bare `.filter(isPromptActiveMemory)` is unsafe here.
+  const eligible = (options.records ?? memoryRegistry.getAll()).filter((record) => isPromptActiveMemory(record));
   const ranking = rankMemoryForTurn(memoryRegistry, eligible, options.turnText);
   const records = ranking.records.slice(0, Math.max(0, limit));
 

package/src/agent/operator-gateway-call.ts

@@ -0,0 +1,134 @@
+/**
+ * A generic connected-host operator gateway call helper for CLI subcommands
+ * that reach ci.*, principals.*, and channels.profiles.* over the daemon's
+ * operator gateway. This mirrors the exact connection resolution and error
+ * classification pattern established in routine-schedule-promotion.ts
+ * (resolveAgentConnectedHostConnection + classifyScheduleError) so every
+ * connected-host CLI command reports failures the same way: auth_required
+ * when no token is on disk, connected_host_unavailable when the fetch itself
+ * fails, connected_host_route_unavailable / connected_host_incompatible when
+ * the method route answers 404, and connected_host_error otherwise.
+ */
+import { createBrowserGoodVibesSdk } from '@pellux/goodvibes-sdk/browser';
+import type { OperatorMethodId } from '@pellux/goodvibes-sdk/contracts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import type { AgentConnectedHostConnection } from './routine-schedule-promotion.ts';
+
+export type OperatorGatewayCallFailureKind =
+  | 'auth_required'
+  | 'connected_host_unavailable'
+  | 'connected_host_incompatible'
+  | 'connected_host_route_unavailable'
+  | 'connected_host_error';
+
+export interface OperatorGatewayCallSuccess<T> {
+  readonly ok: true;
+  readonly data: T;
+  readonly methodId: OperatorMethodId;
+  readonly route: string;
+}
+
+export interface OperatorGatewayCallFailure {
+  readonly ok: false;
+  readonly kind: OperatorGatewayCallFailureKind;
+  readonly error: string;
+  readonly methodId: OperatorMethodId;
+  readonly route: string;
+  readonly baseUrl?: string;
+}
+
+export type OperatorGatewayCallResult<T> = OperatorGatewayCallSuccess<T> | OperatorGatewayCallFailure;
+
+async function fetchConnectedHostStatus(connection: AgentConnectedHostConnection): Promise<{
+  readonly ok: boolean;
+  readonly status: number;
+  readonly body: unknown;
+}> {
+  try {
+    const response = await fetch(`${connection.baseUrl}/status`, {
+      headers: connection.token ? { authorization: `Bearer ${connection.token}` } : undefined,
+    });
+    const text = await response.text();
+    let body: unknown = text;
+    try {
+      body = text.trim() ? JSON.parse(text) as unknown : {};
+    } catch {
+      body = text;
+    }
+    return { ok: response.ok, status: response.status, body };
+  } catch (error) {
+    return { ok: false, status: 0, body: summarizeError(error) };
+  }
+}
+
+async function classifyOperatorGatewayError(
+  error: unknown,
+  connection: AgentConnectedHostConnection,
+  methodId: OperatorMethodId,
+  route: string,
+): Promise<OperatorGatewayCallFailure> {
+  const message = summarizeError(error);
+  const lower = message.toLowerCase();
+  if (lower.includes('401') || lower.includes('unauthorized') || lower.includes('auth')) {
+    return { ok: false, kind: 'auth_required', error: message, methodId, route, baseUrl: connection.baseUrl };
+  }
+  if (lower.includes('404') || lower.includes('not found')) {
+    const connectedHost = await fetchConnectedHostStatus(connection);
+    if (connectedHost.ok) {
+      return {
+        ok: false,
+        kind: 'connected_host_incompatible',
+        error: `Connected GoodVibes host compatibility does not satisfy Agent requirements; ${methodId} is unavailable.`,
+        methodId,
+        route,
+        baseUrl: connection.baseUrl,
+      };
+    }
+    return { ok: false, kind: 'connected_host_route_unavailable', error: message, methodId, route, baseUrl: connection.baseUrl };
+  }
+  if (lower.includes('fetch') || lower.includes('connect') || lower.includes('econnrefused')) {
+    return { ok: false, kind: 'connected_host_unavailable', error: message, methodId, route, baseUrl: connection.baseUrl };
+  }
+  return { ok: false, kind: 'connected_host_error', error: message, methodId, route, baseUrl: connection.baseUrl };
+}
+
+/**
+ * Invoke one operator gateway method against the connected host, returning a
+ * discriminated result instead of throwing. `route` is an informational HTTP
+ * route label used in error/preview output; the SDK's operator.invoke resolves
+ * the actual HTTP method/path from the operator contract itself.
+ */
+export async function invokeOperatorGatewayMethod<T>(
+  connection: AgentConnectedHostConnection,
+  methodId: OperatorMethodId,
+  route: string,
+  payload: unknown,
+): Promise<OperatorGatewayCallResult<T>> {
+  if (!connection.token) {
+    return {
+      ok: false,
+      kind: 'auth_required',
+      error: `No connected-host operator token found at ${connection.tokenPath}`,
+      methodId,
+      route,
+      baseUrl: connection.baseUrl,
+    };
+  }
+  try {
+    const sdk = createBrowserGoodVibesSdk({ baseUrl: connection.baseUrl, authToken: connection.token });
+    const data = await sdk.operator.invoke(methodId, payload as never) as T;
+    return { ok: true, data, methodId, route };
+  } catch (error) {
+    return classifyOperatorGatewayError(error, connection, methodId, route);
+  }
+}
+
+export function formatOperatorGatewayFailure(failure: OperatorGatewayCallFailure): string {
+  const lines = [
+    `Connected-host call failed: ${failure.methodId} (${failure.kind})`,
+    `  route ${failure.route}`,
+    failure.baseUrl ? `  connected host ${failure.baseUrl}` : '',
+    `  ${failure.error}`,
+  ];
+  return lines.filter(Boolean).join('\n');
+}