@pellux/goodvibes-agent 0.1.116 → 1.0.0

package/src/agent/routine-schedule-promotion.ts

@@ -5,6 +5,7 @@ import type { OperatorMethodInput, OperatorMethodOutput } from '@pellux/goodvibe
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { getModelIdFromProviderModel, getProviderIdFromModel } from '../config/provider-model.ts';
 import { SDK_VERSION } from '../version.ts';
+import { formatAgentRecordReviewState } from './record-labels.ts';
 import type { AgentRoutineRecord } from './routine-registry.ts';
 
 export const ROUTINE_SCHEDULE_ROUTE = '/api/automation/schedules';
@@ -16,11 +17,11 @@ type ScheduleCreateOutput = OperatorMethodOutput<'schedules.create'>;
 type ScheduleDeliveryInput = NonNullable<ScheduleCreateInput['delivery']>;
 type ScheduleDeliveryTargetInput = ScheduleDeliveryInput['targets'] extends readonly (infer T)[] ? T : never;
 
-export interface AgentDaemonConfigReader {
+export interface AgentConnectedHostConfigReader {
   get(key: string): unknown;
 }
 
-export interface AgentDaemonConnection {
+export interface AgentConnectedHostConnection {
   readonly baseUrl: string;
   readonly token: string | null;
   readonly tokenPath: string;
@@ -46,6 +47,7 @@ export type RoutineScheduleDeliverySurfaceKind =
   | 'google-chat'
   | 'signal'
   | 'whatsapp'
+  | 'telephony'
   | 'imessage'
   | 'msteams'
   | 'bluebubbles'
@@ -105,14 +107,14 @@ export interface RoutineSchedulePromotionFailure {
   readonly kind:
     | 'confirmation_required'
     | 'auth_required'
-    | 'daemon_unavailable'
+    | 'connected_host_unavailable'
     | 'version_mismatch'
-    | 'daemon_route_unavailable'
-    | 'daemon_error';
+    | 'connected_host_route_unavailable'
+    | 'connected_host_error';
   readonly error: string;
   readonly route: typeof ROUTINE_SCHEDULE_ROUTE;
   readonly baseUrl?: string;
-  readonly daemonVersion?: string;
+  readonly connectedHostVersion?: string;
   readonly expectedSdkVersion?: string;
 }
 
@@ -128,7 +130,7 @@ export interface RoutineScheduleReceipt {
   readonly route: typeof ROUTINE_SCHEDULE_ROUTE;
   readonly method: typeof ROUTINE_SCHEDULE_METHOD;
   readonly status: 'created' | 'failed';
-  readonly daemonBaseUrl: string;
+  readonly connectedHostBaseUrl: string;
   readonly scheduleId?: string;
   readonly scheduleStatus?: string;
   readonly scheduleName: string;
@@ -191,14 +193,14 @@ export interface RoutineScheduleCorrelationFailure {
   readonly ok: false;
   readonly kind:
     | 'auth_required'
-    | 'daemon_unavailable'
+    | 'connected_host_unavailable'
     | 'version_mismatch'
-    | 'daemon_route_unavailable'
-    | 'daemon_error';
+    | 'connected_host_route_unavailable'
+    | 'connected_host_error';
   readonly error: string;
   readonly route: typeof ROUTINE_SCHEDULE_ROUTE;
   readonly baseUrl?: string;
-  readonly daemonVersion?: string;
+  readonly connectedHostVersion?: string;
   readonly expectedSdkVersion?: string;
 }
 
@@ -236,17 +238,17 @@ function deliveryModeFromTargets(targets: readonly RoutineScheduleDeliveryTarget
 function toDeliveryTargetInput(target: RoutineScheduleDeliveryTargetSpec): ScheduleDeliveryTargetInput {
   return {
     kind: target.kind,
-    surfaceKind: target.surfaceKind,
+    surfaceKind: target.surfaceKind as ScheduleDeliveryTargetInput['surfaceKind'],
     address: target.address,
     routeId: target.routeId,
     label: target.label,
   };
 }
 
-export function resolveAgentDaemonConnection(
-  configManager: AgentDaemonConfigReader,
+export function resolveAgentConnectedHostConnection(
+  configManager: AgentConnectedHostConfigReader,
   homeDirectory: string,
-): AgentDaemonConnection {
+): AgentConnectedHostConnection {
   const host = String(configManager.get('controlPlane.host') ?? '127.0.0.1');
   const port = Number(configManager.get('controlPlane.port') ?? 3421);
   const tokenPath = join(homeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
@@ -265,16 +267,16 @@ export function buildRoutineSchedulePrompt(routine: AgentRoutineRecord): string
     'GoodVibes Agent scheduled routine.',
     '',
     `Routine: ${routine.name}`,
-    `Routine id: ${routine.id}`,
-    `Review state: ${routine.reviewState}`,
+    `Routine reference: ${routine.id}`,
+    `Review: ${formatAgentRecordReviewState(routine.reviewState)}`,
     `Tags: ${routine.tags.join(', ') || '(none)'}`,
     `Triggers: ${routine.triggers.join(', ') || '(manual)'}`,
     '',
     'Operator policy:',
     '- Run this as a serial GoodVibes Agent operator routine.',
-    '- Use isolated Agent Knowledge routes only; never use default Knowledge/Wiki or non-Agent knowledge spaces as fallback.',
+    '- Use isolated Agent Knowledge routes only; never use default knowledge or non-Agent knowledge spaces as fallback.',
     '- Do not perform destructive, costly, externally visible, or secret-handling actions without explicit approval.',
-    '- Do not request WRFC unless this scheduled routine explicitly delegates build/fix/review work to GoodVibes TUI.',
+    '- Do not request GoodVibes TUI delegation unless this scheduled routine explicitly delegates build/fix/review work to GoodVibes TUI.',
     '- Summarize what was checked, what changed, and what still needs user review.',
     '',
     'Routine description:',
@@ -354,7 +356,7 @@ export function buildRoutineSchedulePreview(
   };
 }
 
-async function fetchDaemonStatus(connection: AgentDaemonConnection): Promise<{
+async function fetchConnectedHostStatus(connection: AgentConnectedHostConnection): Promise<{
   readonly ok: boolean;
   readonly status: number;
   readonly body: unknown;
@@ -378,7 +380,7 @@ async function fetchDaemonStatus(connection: AgentDaemonConnection): Promise<{
 
 async function classifyScheduleError(
   error: unknown,
-  connection: AgentDaemonConnection,
+  connection: AgentConnectedHostConnection,
 ): Promise<RoutineSchedulePromotionFailure> {
   const message = summarizeError(error);
   const lower = message.toLowerCase();
@@ -386,37 +388,37 @@ async function classifyScheduleError(
     return { ok: false, kind: 'auth_required', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
   }
   if (lower.includes('404') || lower.includes('not found')) {
-    const daemon = await fetchDaemonStatus(connection);
-    const record = isRecord(daemon.body) ? daemon.body : {};
-    const daemonVersion = readString(record, 'version') ?? 'unknown';
-    if (daemon.ok && daemonVersion !== SDK_VERSION) {
+    const connectedHost = await fetchConnectedHostStatus(connection);
+    const record = isRecord(connectedHost.body) ? connectedHost.body : {};
+    const connectedHostVersion = readString(record, 'version') ?? 'unknown';
+    if (connectedHost.ok && connectedHostVersion !== SDK_VERSION) {
       return {
         ok: false,
         kind: 'version_mismatch',
-        error: `Connected GoodVibes service SDK version ${daemonVersion} does not match Agent SDK pin ${SDK_VERSION}; schedules.create is unavailable.`,
+        error: `Connected GoodVibes host SDK version ${connectedHostVersion} does not match Agent SDK pin ${SDK_VERSION}; schedules.create is unavailable.`,
         route: ROUTINE_SCHEDULE_ROUTE,
         baseUrl: connection.baseUrl,
-        daemonVersion,
+        connectedHostVersion,
         expectedSdkVersion: SDK_VERSION,
       };
     }
-    return { ok: false, kind: 'daemon_route_unavailable', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
+    return { ok: false, kind: 'connected_host_route_unavailable', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
   }
   if (lower.includes('fetch') || lower.includes('connect') || lower.includes('econnrefused')) {
-    return { ok: false, kind: 'daemon_unavailable', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
+    return { ok: false, kind: 'connected_host_unavailable', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
   }
-  return { ok: false, kind: 'daemon_error', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
+  return { ok: false, kind: 'connected_host_error', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
 }
 
-export async function promoteRoutineToDaemonSchedule(
-  connection: AgentDaemonConnection,
+export async function promoteRoutineToConnectedSchedule(
+  connection: AgentConnectedHostConnection,
   preview: RoutineSchedulePromotionPreview,
 ): Promise<RoutineSchedulePromotionResult> {
   if (!connection.token) {
     return {
       ok: false,
       kind: 'auth_required',
-      error: `No daemon operator token found at ${connection.tokenPath}`,
+      error: `No connected-host operator token found at ${connection.tokenPath}`,
       route: ROUTINE_SCHEDULE_ROUTE,
       baseUrl: connection.baseUrl,
     };

package/src/agent/routine-schedule-receipts.ts

@@ -12,7 +12,7 @@ import {
   ROUTINE_SCHEDULE_LIST_METHOD,
   ROUTINE_SCHEDULE_METHOD,
   ROUTINE_SCHEDULE_ROUTE,
-  type AgentDaemonConnection,
+  type AgentConnectedHostConnection,
   type RoutineScheduleCorrelation,
   type RoutineScheduleCorrelationFailure,
   type RoutineScheduleCorrelationResult,
@@ -82,6 +82,15 @@ function redactedDeliveryTargets(delivery: ScheduleDeliveryInput | undefined): r
   }));
 }
 
+function normalizeFailureKind(value: unknown): RoutineScheduleReceipt['failureKind'] {
+  if (value === 'confirmation_required' || value === 'auth_required' || value === 'version_mismatch') return value;
+  if (value === 'connected_host_unavailable' || value === 'connected_host_route_unavailable' || value === 'connected_host_error') return value;
+  if (value === 'daemon_unavailable') return 'connected_host_unavailable';
+  if (value === 'daemon_route_unavailable') return 'connected_host_route_unavailable';
+  if (value === 'daemon_error') return 'connected_host_error';
+  return undefined;
+}
+
 function readReceipt(value: unknown): RoutineScheduleReceipt | null {
   if (!isRecord(value)) return null;
   const id = readString(value, 'id')?.trim();
@@ -120,7 +129,7 @@ function readReceipt(value: unknown): RoutineScheduleReceipt | null {
     route: ROUTINE_SCHEDULE_ROUTE,
     method: ROUTINE_SCHEDULE_METHOD,
     status,
-    daemonBaseUrl: readString(value, 'daemonBaseUrl') ?? '',
+    connectedHostBaseUrl: readString(value, 'connectedHostBaseUrl') ?? readString(value, 'daemonBaseUrl') ?? '',
     scheduleId: readString(value, 'scheduleId') ?? undefined,
     scheduleStatus: readString(value, 'scheduleStatus') ?? undefined,
     scheduleName: readString(value, 'scheduleName') ?? routineName,
@@ -138,14 +147,7 @@ function readReceipt(value: unknown): RoutineScheduleReceipt | null {
     },
     deliveryMode: readString(value, 'deliveryMode') ?? undefined,
     deliveryTargets,
-    failureKind: value.failureKind === 'confirmation_required'
-      || value.failureKind === 'auth_required'
-      || value.failureKind === 'daemon_unavailable'
-      || value.failureKind === 'version_mismatch'
-      || value.failureKind === 'daemon_route_unavailable'
-      || value.failureKind === 'daemon_error'
-      ? value.failureKind
-      : undefined,
+    failureKind: normalizeFailureKind(value.failureKind),
     failureError: readString(value, 'failureError') ?? undefined,
   };
 }
@@ -209,7 +211,7 @@ function resultScheduleRecord(result: RoutineSchedulePromotionResult): Record<st
 
 function buildReceipt(
   existing: readonly RoutineScheduleReceipt[],
-  connection: AgentDaemonConnection,
+  connection: AgentConnectedHostConnection,
   preview: RoutineSchedulePromotionPreview,
   result: RoutineSchedulePromotionResult,
 ): RoutineScheduleReceipt {
@@ -226,7 +228,7 @@ function buildReceipt(
     route: ROUTINE_SCHEDULE_ROUTE,
     method: ROUTINE_SCHEDULE_METHOD,
     status: result.ok ? 'created' : 'failed',
-    daemonBaseUrl: connection.baseUrl,
+    connectedHostBaseUrl: connection.baseUrl,
     scheduleId,
     scheduleStatus,
     scheduleName: String(preview.payload.name ?? `Agent routine: ${preview.routineName}`),
@@ -269,7 +271,7 @@ export class RoutineScheduleReceiptStore {
     return this.snapshot().receipts.find((receipt) => receipt.id.toLowerCase() === normalized) ?? null;
   }
 
-  public append(connection: AgentDaemonConnection, preview: RoutineSchedulePromotionPreview, result: RoutineSchedulePromotionResult): RoutineScheduleReceipt {
+  public append(connection: AgentConnectedHostConnection, preview: RoutineSchedulePromotionPreview, result: RoutineSchedulePromotionResult): RoutineScheduleReceipt {
     const store = this.readStore();
     const receipt = buildReceipt(store.receipts, connection, preview, result);
     this.writeStore({ ...store, receipts: [...store.receipts, receipt] });
@@ -281,7 +283,7 @@ export class RoutineScheduleReceiptStore {
     try {
       return parseReceiptStore(readFileSync(this.storePath, 'utf-8'));
     } catch (error) {
-      throw new Error(`Could not read Agent routine schedule receipt store: ${summarizeError(error)}`);
+      throw new Error(`Could not read Agent routine schedule receipt store ${summarizeError(error)}`);
     }
   }
 
@@ -415,7 +417,7 @@ function correlateReceipts(
   });
 }
 
-async function fetchDaemonStatus(connection: AgentDaemonConnection): Promise<{
+async function fetchConnectedHostStatus(connection: AgentConnectedHostConnection): Promise<{
   readonly ok: boolean;
   readonly status: number;
   readonly body: unknown;
@@ -439,7 +441,7 @@ async function fetchDaemonStatus(connection: AgentDaemonConnection): Promise<{
 
 async function classifyScheduleListError(
   error: unknown,
-  connection: AgentDaemonConnection,
+  connection: AgentConnectedHostConnection,
 ): Promise<RoutineScheduleCorrelationFailure> {
   const message = summarizeError(error);
   const lower = message.toLowerCase();
@@ -447,37 +449,37 @@ async function classifyScheduleListError(
     return { ok: false, kind: 'auth_required', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
   }
   if (lower.includes('404') || lower.includes('not found')) {
-    const daemon = await fetchDaemonStatus(connection);
-    const record = isRecord(daemon.body) ? daemon.body : {};
-    const daemonVersion = readString(record, 'version') ?? 'unknown';
-    if (daemon.ok && daemonVersion !== SDK_VERSION) {
+    const connectedHost = await fetchConnectedHostStatus(connection);
+    const record = isRecord(connectedHost.body) ? connectedHost.body : {};
+    const connectedHostVersion = readString(record, 'version') ?? 'unknown';
+    if (connectedHost.ok && connectedHostVersion !== SDK_VERSION) {
       return {
         ok: false,
         kind: 'version_mismatch',
-        error: `Connected GoodVibes service SDK version ${daemonVersion} does not match Agent SDK pin ${SDK_VERSION}; schedules.list is unavailable.`,
+        error: `Connected GoodVibes host SDK version ${connectedHostVersion} does not match Agent SDK pin ${SDK_VERSION}; schedules.list is unavailable.`,
         route: ROUTINE_SCHEDULE_ROUTE,
         baseUrl: connection.baseUrl,
-        daemonVersion,
+        connectedHostVersion,
         expectedSdkVersion: SDK_VERSION,
       };
     }
-    return { ok: false, kind: 'daemon_route_unavailable', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
+    return { ok: false, kind: 'connected_host_route_unavailable', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
   }
   if (lower.includes('fetch') || lower.includes('connect') || lower.includes('econnrefused')) {
-    return { ok: false, kind: 'daemon_unavailable', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
+    return { ok: false, kind: 'connected_host_unavailable', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
   }
-  return { ok: false, kind: 'daemon_error', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
+  return { ok: false, kind: 'connected_host_error', error: message, route: ROUTINE_SCHEDULE_ROUTE, baseUrl: connection.baseUrl };
 }
 
 export async function reconcileRoutineScheduleReceipts(
-  connection: AgentDaemonConnection,
+  connection: AgentConnectedHostConnection,
   snapshot: RoutineScheduleReceiptSnapshot,
 ): Promise<RoutineScheduleCorrelationResult> {
   if (!connection.token) {
     return {
       ok: false,
       kind: 'auth_required',
-      error: `No daemon operator token found at ${connection.tokenPath}`,
+      error: `No connected-host operator token found at ${connection.tokenPath}`,
       route: ROUTINE_SCHEDULE_ROUTE,
       baseUrl: connection.baseUrl,
     };

package/src/agent/runtime-profile-starters.ts

@@ -44,7 +44,7 @@ export const STARTER_TEMPLATES: readonly AgentRuntimeProfileStarterTemplate[] =
       body: [
         'Operate as a calm household coordinator.',
         'Track preferences, routines, device/service notes, and recurring decisions in Agent-local memory after they are durable and non-secret.',
-        'Use read-only daemon/operator routes for status checks. Require explicit approval for purchases, messages to other people, service changes, deletions, or secret handling.',
+        'Use read-only connected-host/operator routes for status checks. Require explicit approval for purchases, messages to other people, service changes, deletions, or secret handling.',
         'Keep replies concrete: next action, owner, date, and open question when one is needed.',
       ].join('\n'),
       tags: ['household', 'home', 'coordination'],
@@ -81,7 +81,7 @@ export const STARTER_TEMPLATES: readonly AgentRuntimeProfileStarterTemplate[] =
         description: 'Review open household commitments, pending approvals, and stale home notes.',
         steps: [
           '1. List pending local routines, workplan tasks, and approvals.',
-          '2. Summarize what changed since the last review from local Agent state.',
+          '2. Summarize what changed since the last review from Agent-local state.',
           '3. Ask for confirmation before scheduling, sending messages, purchasing, or changing services.',
           '4. Record reviewed preferences and stale notes locally.',
         ].join('\n'),
@@ -200,7 +200,7 @@ export const STARTER_TEMPLATES: readonly AgentRuntimeProfileStarterTemplate[] =
         name: 'Pre-trip Readiness Review',
         description: 'Check documents, reservations, transport, packing, weather, and open decisions.',
         steps: [
-          '1. Review trip dates, locations, reservations, and open decisions from local Agent state.',
+          '1. Review trip dates, locations, reservations, and open decisions from Agent-local state.',
           '2. Refresh current weather, schedule, and rule data when needed.',
           '3. Summarize blockers and next confirmed action.',
           '4. Ask before external sends, purchases, or reservation changes.',
@@ -223,7 +223,7 @@ export const STARTER_TEMPLATES: readonly AgentRuntimeProfileStarterTemplate[] =
       description: 'Operator persona for systems, incidents, runbooks, approvals, and service posture.',
       body: [
         'Favor explicit state, logs, health, approvals, and next action.',
-        'Use read-only daemon/operator routes by default.',
+        'Use read-only connected-host/operator routes by default.',
         'Require explicit confirmation for run, pause, resume, cancel, retry, approve, deny, service changes, or writes.',
         'Delegate code/build fixes to GoodVibes TUI when explicitly requested.',
       ].join('\n'),
@@ -260,7 +260,7 @@ export const STARTER_TEMPLATES: readonly AgentRuntimeProfileStarterTemplate[] =
         name: 'Daily Operations Sweep',
         description: 'Inspect service posture, pending approvals, failed runs, and stale tasks.',
         steps: [
-          '1. Refresh daemon status, compat, approvals, workplan, automation snapshot, runs, schedules, and capacity.',
+          '1. Refresh connected-host status, compat, approvals, workplan, automation snapshot, runs, schedules, and capacity.',
           '2. Summarize degraded items and blocked work.',
           '3. Recommend exact follow-up commands with confirmation gates for side effects.',
         ].join('\n'),

package/src/agent/runtime-profile.ts

@@ -36,6 +36,12 @@ export interface AgentRuntimeProfileInfo extends AgentRuntimeProfileResolution {
   readonly starterTemplateApplication?: AgentRuntimeProfileTemplateApplication;
 }
 
+export interface AgentRuntimeProfileSelection extends AgentRuntimeProfileResolution {
+  readonly selectedAt: string | null;
+  readonly path: string;
+  readonly exists: boolean;
+}
+
 export interface AgentRuntimeProfileTemplateApplication {
   readonly id: AgentRuntimeProfileTemplateId;
   readonly name: string;
@@ -76,11 +82,14 @@ export interface AgentRuntimeProfileCommandResult {
     | 'agent.profiles.template.from_discovered'
     | 'agent.profiles.create_from_discovered'
     | 'agent.profiles.create'
+    | 'agent.profiles.default'
+    | 'agent.profiles.default.clear'
     | 'agent.profiles.delete'
     | 'agent.profiles.error';
   readonly data?: {
     readonly profiles?: readonly AgentRuntimeProfileInfo[];
     readonly profile?: AgentRuntimeProfileInfo;
+    readonly selectedProfile?: AgentRuntimeProfileSelection;
     readonly templates?: readonly AgentRuntimeProfileTemplateSummary[];
     readonly appliedTemplate?: AgentRuntimeProfileTemplateApplication;
     readonly template?: AgentRuntimeProfileTemplateSummary;
@@ -91,8 +100,13 @@ export interface AgentRuntimeProfileCommandResult {
 }
 
 const PROFILE_CREATED_FILE = 'profile.json';
+const PROFILE_SELECTION_FILE = 'profile-selection.json';
 const PROFILE_ID_PATTERN = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
 export function normalizeAgentRuntimeProfileId(value: string): string {
   return value
     .trim()
@@ -122,6 +136,10 @@ export function getAgentRuntimeProfileTemplatesRoot(baseHomeDirectory: string):
   return join(baseHomeDirectory, '.goodvibes', GOODVIBES_AGENT_SURFACE_ROOT, 'profile-starters');
 }
 
+export function getAgentRuntimeProfileSelectionPath(baseHomeDirectory: string): string {
+  return join(baseHomeDirectory, '.goodvibes', GOODVIBES_AGENT_SURFACE_ROOT, PROFILE_SELECTION_FILE);
+}
+
 export function resolveAgentRuntimeProfileHome(baseHomeDirectory: string, profileName: string): AgentRuntimeProfileResolution {
   const id = assertValidAgentRuntimeProfileId(profileName);
   return {
@@ -130,6 +148,36 @@ export function resolveAgentRuntimeProfileHome(baseHomeDirectory: string, profil
   };
 }
 
+export function readAgentRuntimeProfileSelection(baseHomeDirectory: string): AgentRuntimeProfileSelection | null {
+  const path = getAgentRuntimeProfileSelectionPath(baseHomeDirectory);
+  if (!existsSync(path)) return null;
+  try {
+    const raw: unknown = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!isRecord(raw)) return null;
+    const profileId = raw.profileId;
+    if (typeof profileId !== 'string') return null;
+    const resolution = resolveAgentRuntimeProfileHome(baseHomeDirectory, profileId);
+    const selectedAt = typeof raw.selectedAt === 'string' ? raw.selectedAt : null;
+    return {
+      ...resolution,
+      selectedAt,
+      path,
+      exists: existsSync(resolution.homeDirectory),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function resolveSelectedAgentRuntimeProfileHome(baseHomeDirectory: string): AgentRuntimeProfileResolution | null {
+  const selection = readAgentRuntimeProfileSelection(baseHomeDirectory);
+  if (!selection?.exists) return null;
+  return {
+    id: selection.id,
+    homeDirectory: selection.homeDirectory,
+  };
+}
+
 function readProfileCreatedAt(homeDirectory: string): string | null {
   const path = join(homeDirectory, PROFILE_CREATED_FILE);
   if (!existsSync(path)) return null;
@@ -147,13 +195,11 @@ function readProfileStarterTemplate(homeDirectory: string): Pick<AgentRuntimePro
   if (!existsSync(path)) return {};
   try {
     const raw: unknown = JSON.parse(readFileSync(path, 'utf-8'));
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
-    const record = raw as Record<string, unknown>;
-    const starter = record.starterTemplate;
-    if (!starter || typeof starter !== 'object' || Array.isArray(starter)) return {};
-    const starterRecord = starter as Record<string, unknown>;
-    const id = starterRecord.id;
-    const name = starterRecord.name;
+    if (!isRecord(raw)) return {};
+    const starter = raw.starterTemplate;
+    if (!isRecord(starter)) return {};
+    const id = starter.id;
+    const name = starter.name;
     if (!isAgentRuntimeProfileTemplateId(id) || typeof name !== 'string') return {};
     return {
       starterTemplateId: id,
@@ -226,7 +272,7 @@ function selectDiscoveredRecord<T extends { readonly name: string; readonly path
   if (!selector?.trim()) return records[0]!;
   const lookup = selector.trim().toLowerCase();
   const match = records.find((record) => normalizedLookupValues(record.name, record.path).includes(lookup));
-  if (!match) throw new Error(`Unknown discovered Agent ${label}: ${selector}.`);
+  if (!match) throw new Error(`Unknown discovered Agent ${label} ${selector}.`);
   return match;
 }
 
@@ -278,8 +324,8 @@ function readTemplateTextBlock(value: unknown, field: string): string {
 }
 
 function readTemplateObject(value: unknown, field: string): Record<string, unknown> {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`Starter template ${field} must be an object.`);
-  return value as Record<string, unknown>;
+  if (!isRecord(value)) throw new Error(`Starter template ${field} must be an object.`);
+  return value;
 }
 
 function parseTemplateSkill(value: unknown): AgentRuntimeProfileStarterTemplate['skills'][number] {
@@ -360,7 +406,7 @@ function resolveAgentRuntimeProfileTemplate(templateId: AgentRuntimeProfileTempl
   const local = baseHomeDirectory ? listLocalTemplates(baseHomeDirectory).find((template) => template.id === id) : undefined;
   if (local) return local;
   const suffix = baseHomeDirectory ? ' Use profiles templates to list starters.' : '';
-  throw new Error(`Unknown Agent starter profile template: ${templateId}.${suffix}`);
+  throw new Error(`Unknown Agent starter profile template ${templateId}.${suffix}`);
 }
 
 export function listAgentRuntimeProfileTemplates(baseHomeDirectory?: string): readonly AgentRuntimeProfileTemplateSummary[] {
@@ -423,7 +469,7 @@ export async function createAgentRuntimeProfileTemplateFromDiscovered(
   const selectedRoutines = selectDiscoveredRecords(routines, options.routines, 'routine');
   const target = join(getAgentRuntimeProfileTemplatesRoot(shellPaths.homeDirectory), `${id}.json`);
   if (existsSync(target) && options.replace !== true) {
-    throw new Error(`Agent starter template already exists: ${id}. Rerun with --replace to overwrite it.`);
+    throw new Error(`Agent starter template already exists ${id}. Rerun with --replace to overwrite it.`);
   }
   const persona = discoveredPersonaToTemplate(selectedPersona);
   const template: AgentRuntimeProfileStarterTemplate = {
@@ -573,9 +619,42 @@ export function createAgentRuntimeProfile(baseHomeDirectory: string, profileName
   };
 }
 
+export function setAgentRuntimeProfileSelection(baseHomeDirectory: string, profileName: string): AgentRuntimeProfileSelection {
+  const resolution = resolveAgentRuntimeProfileHome(baseHomeDirectory, profileName);
+  if (!existsSync(resolution.homeDirectory)) {
+    throw new Error(`Agent profile not found ${resolution.id}`);
+  }
+  const path = getAgentRuntimeProfileSelectionPath(baseHomeDirectory);
+  mkdirSync(dirname(path), { recursive: true });
+  const selectedAt = new Date().toISOString();
+  writeFileSync(
+    path,
+    `${JSON.stringify({
+      profileId: resolution.id,
+      selectedAt,
+    }, null, 2)}\n`,
+    'utf-8',
+  );
+  return {
+    ...resolution,
+    selectedAt,
+    path,
+    exists: true,
+  };
+}
+
+export function clearAgentRuntimeProfileSelection(baseHomeDirectory: string): boolean {
+  const path = getAgentRuntimeProfileSelectionPath(baseHomeDirectory);
+  if (!existsSync(path)) return false;
+  rmSync(path, { force: true });
+  return true;
+}
+
 export function deleteAgentRuntimeProfile(baseHomeDirectory: string, profileName: string): boolean {
   const resolution = resolveAgentRuntimeProfileHome(baseHomeDirectory, profileName);
   if (!existsSync(resolution.homeDirectory)) return false;
   rmSync(resolution.homeDirectory, { recursive: true, force: true });
+  const selection = readAgentRuntimeProfileSelection(baseHomeDirectory);
+  if (selection?.id === resolution.id) clearAgentRuntimeProfileSelection(baseHomeDirectory);
   return true;
 }