@pellux/goodvibes-agent 0.1.116 → 1.0.0

package/src/agent/skill-registry.ts

@@ -1,11 +1,32 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
 import type { ShellPathService } from '@/runtime/index.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
 import { assertNoSecretLikeText } from './persona-registry.ts';
+import { formatAgentRecordReviewState } from './record-labels.ts';
 
 export type AgentSkillSource = 'user' | 'agent' | 'imported' | 'system';
 export type AgentSkillReviewState = 'fresh' | 'reviewed' | 'stale';
+export type AgentSkillRequirementKind = 'env' | 'command';
+
+export interface AgentSkillRequirement {
+  readonly kind: AgentSkillRequirementKind;
+  readonly name: string;
+  readonly description?: string;
+}
+
+export interface AgentSkillReadiness {
+  readonly ready: boolean;
+  readonly met: readonly AgentSkillRequirement[];
+  readonly missing: readonly AgentSkillRequirement[];
+}
+
+export interface AgentSkillBundleReadiness {
+  readonly ready: boolean;
+  readonly includedSkills: readonly AgentSkillRecord[];
+  readonly missingSkillIds: readonly string[];
+  readonly missingRequirements: readonly AgentSkillRequirement[];
+}
 
 export interface AgentSkillRecord {
   readonly id: string;
@@ -14,6 +35,7 @@ export interface AgentSkillRecord {
   readonly procedure: string;
   readonly triggers: readonly string[];
   readonly tags: readonly string[];
+  readonly requirements: readonly AgentSkillRequirement[];
   readonly enabled: boolean;
   readonly source: AgentSkillSource;
   readonly provenance: string;
@@ -45,6 +67,7 @@ export interface AgentSkillCreateInput {
   readonly procedure: string;
   readonly triggers?: readonly string[];
   readonly tags?: readonly string[];
+  readonly requirements?: readonly AgentSkillRequirement[];
   readonly enabled?: boolean;
   readonly source?: AgentSkillSource;
   readonly provenance?: string;
@@ -65,6 +88,7 @@ export interface AgentSkillUpdateInput {
   readonly procedure?: string;
   readonly triggers?: readonly string[];
   readonly tags?: readonly string[];
+  readonly requirements?: readonly AgentSkillRequirement[];
   readonly provenance?: string;
 }
 
@@ -105,6 +129,11 @@ function readStringArray(value: unknown): string[] {
   return value.filter((entry): entry is string => typeof entry === 'string').map((entry) => entry.trim()).filter(Boolean);
 }
 
+function readRequirementKind(value: unknown): AgentSkillRequirementKind | null {
+  if (value === 'env' || value === 'command') return value;
+  return null;
+}
+
 function normalizeName(name: string): string {
   return name.trim().replace(/\s+/g, ' ');
 }
@@ -123,6 +152,48 @@ function normalizeList(values: readonly string[] | undefined): string[] {
   return result;
 }
 
+function validateRequirementName(requirement: AgentSkillRequirement): void {
+  if (requirement.kind === 'env' && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(requirement.name)) {
+    throw new Error(`Invalid skill env requirement ${requirement.name}`);
+  }
+  if (requirement.kind === 'command' && !/^[A-Za-z0-9._+-]+$/.test(requirement.name)) {
+    throw new Error(`Invalid skill command requirement ${requirement.name}`);
+  }
+}
+
+function normalizeRequirements(values: readonly AgentSkillRequirement[] | undefined): AgentSkillRequirement[] {
+  const seen = new Set<string>();
+  const result: AgentSkillRequirement[] = [];
+  for (const value of values ?? []) {
+    const kind = readRequirementKind(value.kind);
+    const name = typeof value.name === 'string' ? value.name.trim() : '';
+    if (!kind || !name) continue;
+    const description = typeof value.description === 'string' ? value.description.trim() : '';
+    const requirement: AgentSkillRequirement = {
+      kind,
+      name,
+      ...(description ? { description } : {}),
+    };
+    validateRequirementName(requirement);
+    const key = `${requirement.kind}:${requirement.name.toLowerCase()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(requirement);
+  }
+  return result;
+}
+
+function parseRequirements(value: unknown): AgentSkillRequirement[] {
+  if (!Array.isArray(value)) return [];
+  return normalizeRequirements(value
+    .filter(isRecord)
+    .map((entry) => ({
+      kind: readRequirementKind(entry.kind) ?? 'env',
+      name: readString(entry.name).trim(),
+      description: readString(entry.description).trim(),
+    })));
+}
+
 function slugify(value: string): string {
   const slug = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
   return slug || 'skill';
@@ -132,6 +203,23 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
+function canExecute(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function commandExists(command: string, pathValue: string | undefined): boolean {
+  if (!pathValue) return false;
+  return pathValue
+    .split(delimiter)
+    .filter(Boolean)
+    .some((pathEntry) => canExecute(join(pathEntry, command)));
+}
+
 function parseSkill(value: unknown): AgentSkillRecord | null {
   if (!isRecord(value)) return null;
   const id = readString(value.id).trim();
@@ -150,6 +238,7 @@ function parseSkill(value: unknown): AgentSkillRecord | null {
     procedure,
     triggers: readStringArray(value.triggers),
     tags: readStringArray(value.tags),
+    requirements: parseRequirements(value.requirements),
     enabled: value.enabled === true,
     source,
     provenance: readString(value.provenance, source).trim() || source,
@@ -206,14 +295,16 @@ function formatStore(store: SkillStoreFile): string {
   return `${JSON.stringify(store, null, 2)}\n`;
 }
 
-export function skillStorePath(shellPaths: ShellPathService): string {
+type AgentLocalStorePaths = Pick<ShellPathService, 'resolveUserPath'>;
+
+export function skillStorePath(shellPaths: AgentLocalStorePaths): string {
   return shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'skills', 'skills.json');
 }
 
 export class AgentSkillRegistry {
   public constructor(private readonly storePath: string) {}
 
-  public static fromShellPaths(shellPaths: ShellPathService): AgentSkillRegistry {
+  public static fromShellPaths(shellPaths: AgentLocalStorePaths): AgentSkillRegistry {
     return new AgentSkillRegistry(skillStorePath(shellPaths));
   }
 
@@ -284,9 +375,10 @@ export class AgentSkillRegistry {
     const description = input.description.trim();
     const procedure = input.procedure.trim();
     this.validateRequired(name, description, procedure);
-    assertNoSecretLikeText([name, description, procedure, ...(input.tags ?? []), ...(input.triggers ?? [])]);
+    const requirements = normalizeRequirements(input.requirements);
+    assertNoSecretLikeText([name, description, procedure, ...(input.tags ?? []), ...(input.triggers ?? []), ...requirements.flatMap((requirement) => [requirement.name, requirement.description ?? ''])], 'Skills');
     const duplicate = store.skills.find((skill) => skill.name.toLowerCase() === name.toLowerCase());
-    if (duplicate) throw new Error(`Skill already exists: ${duplicate.id}`);
+    if (duplicate) throw new Error(`Skill already exists ${duplicate.id}`);
     const timestamp = nowIso();
     const skill: AgentSkillRecord = {
       id: this.nextId(name, store.skills),
@@ -295,6 +387,7 @@ export class AgentSkillRegistry {
       procedure,
       triggers: normalizeList(input.triggers),
       tags: normalizeList(input.tags),
+      requirements,
       enabled: input.enabled === true,
       source: input.source ?? 'user',
       provenance: input.provenance?.trim() || input.source || 'user',
@@ -312,9 +405,9 @@ export class AgentSkillRegistry {
     const description = input.description.trim();
     const skillIds = this.normalizeExistingSkillIds(store, input.skillIds);
     this.validateBundleRequired(name, description, skillIds);
-    assertNoSecretLikeText([name, description, ...skillIds]);
+    assertNoSecretLikeText([name, description, ...skillIds], 'Skill bundles');
     const duplicate = store.bundles.find((bundle) => bundle.name.toLowerCase() === name.toLowerCase());
-    if (duplicate) throw new Error(`Skill bundle already exists: ${duplicate.id}`);
+    if (duplicate) throw new Error(`Skill bundle already exists ${duplicate.id}`);
     const timestamp = nowIso();
     const bundle: AgentSkillBundleRecord = {
       id: this.nextBundleId(name, store.bundles),
@@ -335,14 +428,15 @@ export class AgentSkillRegistry {
   public update(idOrName: string, input: AgentSkillUpdateInput): AgentSkillRecord {
     const store = this.readStore();
     const existing = this.findInStore(store, idOrName);
-    if (!existing) throw new Error(`Unknown skill: ${idOrName}`);
+    if (!existing) throw new Error(`Unknown skill ${idOrName}`);
     const name = input.name === undefined ? existing.name : normalizeName(input.name);
     const description = input.description === undefined ? existing.description : input.description.trim();
     const procedure = input.procedure === undefined ? existing.procedure : input.procedure.trim();
     this.validateRequired(name, description, procedure);
-    assertNoSecretLikeText([name, description, procedure, ...(input.tags ?? []), ...(input.triggers ?? [])]);
+    const requirements = input.requirements === undefined ? existing.requirements : normalizeRequirements(input.requirements);
+    assertNoSecretLikeText([name, description, procedure, ...(input.tags ?? []), ...(input.triggers ?? []), ...requirements.flatMap((requirement) => [requirement.name, requirement.description ?? ''])], 'Skills');
     const duplicate = store.skills.find((skill) => skill.id !== existing.id && skill.name.toLowerCase() === name.toLowerCase());
-    if (duplicate) throw new Error(`Skill already exists: ${duplicate.id}`);
+    if (duplicate) throw new Error(`Skill already exists ${duplicate.id}`);
     const updated: AgentSkillRecord = {
       ...existing,
       name,
@@ -350,6 +444,7 @@ export class AgentSkillRegistry {
       procedure,
       triggers: input.triggers === undefined ? existing.triggers : normalizeList(input.triggers),
       tags: input.tags === undefined ? existing.tags : normalizeList(input.tags),
+      requirements,
       provenance: input.provenance === undefined ? existing.provenance : input.provenance.trim() || existing.provenance,
       reviewState: 'fresh',
       staleReason: undefined,
@@ -366,14 +461,14 @@ export class AgentSkillRegistry {
   public updateBundle(idOrName: string, input: AgentSkillBundleUpdateInput): AgentSkillBundleRecord {
     const store = this.readStore();
     const existing = this.findBundleInStore(store, idOrName);
-    if (!existing) throw new Error(`Unknown skill bundle: ${idOrName}`);
+    if (!existing) throw new Error(`Unknown skill bundle ${idOrName}`);
     const name = input.name === undefined ? existing.name : normalizeName(input.name);
     const description = input.description === undefined ? existing.description : input.description.trim();
     const skillIds = input.skillIds === undefined ? existing.skillIds : this.normalizeExistingSkillIds(store, input.skillIds);
     this.validateBundleRequired(name, description, skillIds);
-    assertNoSecretLikeText([name, description, ...skillIds]);
+    assertNoSecretLikeText([name, description, ...skillIds], 'Skill bundles');
     const duplicate = store.bundles.find((bundle) => bundle.id !== existing.id && bundle.name.toLowerCase() === name.toLowerCase());
-    if (duplicate) throw new Error(`Skill bundle already exists: ${duplicate.id}`);
+    if (duplicate) throw new Error(`Skill bundle already exists ${duplicate.id}`);
     const updated: AgentSkillBundleRecord = {
       ...existing,
       name,
@@ -395,7 +490,7 @@ export class AgentSkillRegistry {
   public setEnabled(idOrName: string, enabled: boolean): AgentSkillRecord {
     const store = this.readStore();
     const existing = this.findInStore(store, idOrName);
-    if (!existing) throw new Error(`Unknown skill: ${idOrName}`);
+    if (!existing) throw new Error(`Unknown skill ${idOrName}`);
     const updated: AgentSkillRecord = { ...existing, enabled, updatedAt: nowIso() };
     this.writeStore({
       ...store,
@@ -407,7 +502,7 @@ export class AgentSkillRegistry {
   public setBundleEnabled(idOrName: string, enabled: boolean): AgentSkillBundleRecord {
     const store = this.readStore();
     const existing = this.findBundleInStore(store, idOrName);
-    if (!existing) throw new Error(`Unknown skill bundle: ${idOrName}`);
+    if (!existing) throw new Error(`Unknown skill bundle ${idOrName}`);
     const updated: AgentSkillBundleRecord = { ...existing, enabled, updatedAt: nowIso() };
     this.writeStore({
       ...store,
@@ -419,7 +514,7 @@ export class AgentSkillRegistry {
   public markReviewed(idOrName: string): AgentSkillRecord {
     const store = this.readStore();
     const existing = this.findInStore(store, idOrName);
-    if (!existing) throw new Error(`Unknown skill: ${idOrName}`);
+    if (!existing) throw new Error(`Unknown skill ${idOrName}`);
     const updated: AgentSkillRecord = {
       ...existing,
       reviewState: 'reviewed',
@@ -437,7 +532,7 @@ export class AgentSkillRegistry {
   public markBundleReviewed(idOrName: string): AgentSkillBundleRecord {
     const store = this.readStore();
     const existing = this.findBundleInStore(store, idOrName);
-    if (!existing) throw new Error(`Unknown skill bundle: ${idOrName}`);
+    if (!existing) throw new Error(`Unknown skill bundle ${idOrName}`);
     const updated: AgentSkillBundleRecord = {
       ...existing,
       reviewState: 'reviewed',
@@ -455,7 +550,7 @@ export class AgentSkillRegistry {
   public markStale(idOrName: string, reason: string): AgentSkillRecord {
     const store = this.readStore();
     const existing = this.findInStore(store, idOrName);
-    if (!existing) throw new Error(`Unknown skill: ${idOrName}`);
+    if (!existing) throw new Error(`Unknown skill ${idOrName}`);
     const updated: AgentSkillRecord = {
       ...existing,
       reviewState: 'stale',
@@ -472,7 +567,7 @@ export class AgentSkillRegistry {
   public markBundleStale(idOrName: string, reason: string): AgentSkillBundleRecord {
     const store = this.readStore();
     const existing = this.findBundleInStore(store, idOrName);
-    if (!existing) throw new Error(`Unknown skill bundle: ${idOrName}`);
+    if (!existing) throw new Error(`Unknown skill bundle ${idOrName}`);
     const updated: AgentSkillBundleRecord = {
       ...existing,
       reviewState: 'stale',
@@ -489,7 +584,7 @@ export class AgentSkillRegistry {
   public deleteSkill(idOrName: string): AgentSkillRecord {
     const store = this.readStore();
     const existing = this.findInStore(store, idOrName);
-    if (!existing) throw new Error(`Unknown skill: ${idOrName}`);
+    if (!existing) throw new Error(`Unknown skill ${idOrName}`);
     this.writeStore({
       ...store,
       skills: store.skills.filter((skill) => skill.id !== existing.id),
@@ -503,7 +598,7 @@ export class AgentSkillRegistry {
   public deleteBundle(idOrName: string): AgentSkillBundleRecord {
     const store = this.readStore();
     const existing = this.findBundleInStore(store, idOrName);
-    if (!existing) throw new Error(`Unknown skill bundle: ${idOrName}`);
+    if (!existing) throw new Error(`Unknown skill bundle ${idOrName}`);
     this.writeStore({
       ...store,
       bundles: store.bundles.filter((bundle) => bundle.id !== existing.id),
@@ -561,7 +656,7 @@ export class AgentSkillRegistry {
     const normalized = normalizeList(skillIds).map(slugify);
     const known = new Set(store.skills.map((skill) => skill.id));
     for (const skillId of normalized) {
-      if (!known.has(skillId)) throw new Error(`Unknown skill for bundle: ${skillId}`);
+      if (!known.has(skillId)) throw new Error(`Unknown skill for bundle ${skillId}`);
     }
     return normalized;
   }
@@ -571,7 +666,7 @@ export class AgentSkillRegistry {
     try {
       return parseStore(readFileSync(this.storePath, 'utf-8'));
     } catch (error) {
-      throw new Error(`Could not read Agent skill store: ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(`Could not read Agent skill store ${error instanceof Error ? error.message : String(error)}`);
     }
   }
 
@@ -583,6 +678,80 @@ export class AgentSkillRegistry {
   }
 }
 
+export function buildAgentSkillRequirements(input: {
+  readonly env?: readonly string[];
+  readonly commands?: readonly string[];
+}): readonly AgentSkillRequirement[] {
+  return normalizeRequirements([
+    ...(input.env ?? []).map((name) => ({ kind: 'env' as const, name })),
+    ...(input.commands ?? []).map((name) => ({ kind: 'command' as const, name })),
+  ]);
+}
+
+export function normalizeAgentSkillRequirements(values: readonly AgentSkillRequirement[] | undefined): readonly AgentSkillRequirement[] {
+  return normalizeRequirements(values);
+}
+
+export function formatAgentSkillRequirement(requirement: AgentSkillRequirement): string {
+  return `${requirement.kind}:${requirement.name}`;
+}
+
+export function evaluateAgentSkillReadiness(
+  skill: Pick<AgentSkillRecord, 'requirements'>,
+  options: {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly pathValue?: string;
+  } = {},
+): AgentSkillReadiness {
+  const env = options.env ?? process.env;
+  const pathValue = options.pathValue ?? env.PATH;
+  const met: AgentSkillRequirement[] = [];
+  const missing: AgentSkillRequirement[] = [];
+  for (const requirement of skill.requirements) {
+    const present = requirement.kind === 'env'
+      ? typeof env[requirement.name] === 'string' && (env[requirement.name] ?? '').length > 0
+      : commandExists(requirement.name, pathValue);
+    if (present) met.push(requirement);
+    else missing.push(requirement);
+  }
+  return { ready: missing.length === 0, met, missing };
+}
+
+export function evaluateAgentSkillBundleReadiness(
+  bundle: Pick<AgentSkillBundleRecord, 'skillIds'>,
+  skills: readonly AgentSkillRecord[],
+  options: {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly pathValue?: string;
+  } = {},
+): AgentSkillBundleReadiness {
+  const skillById = new Map(skills.map((skill) => [skill.id, skill]));
+  const includedSkills: AgentSkillRecord[] = [];
+  const missingSkillIds: string[] = [];
+  const missingRequirements: AgentSkillRequirement[] = [];
+  const seenRequirements = new Set<string>();
+  for (const skillId of bundle.skillIds) {
+    const skill = skillById.get(skillId);
+    if (!skill) {
+      missingSkillIds.push(skillId);
+      continue;
+    }
+    includedSkills.push(skill);
+    for (const requirement of evaluateAgentSkillReadiness(skill, options).missing) {
+      const key = `${requirement.kind}:${requirement.name.toLowerCase()}`;
+      if (seenRequirements.has(key)) continue;
+      seenRequirements.add(key);
+      missingRequirements.push(requirement);
+    }
+  }
+  return {
+    ready: missingSkillIds.length === 0 && missingRequirements.length === 0,
+    includedSkills,
+    missingSkillIds,
+    missingRequirements,
+  };
+}
+
 export function buildEnabledSkillsPrompt(shellPaths: ShellPathService): string | null {
   const snapshot = AgentSkillRegistry.fromShellPaths(shellPaths).snapshot();
   const active = snapshot.activeSkills;
@@ -591,18 +760,27 @@ export function buildEnabledSkillsPrompt(shellPaths: ShellPathService): string |
     '## Enabled GoodVibes Agent Skills',
     'Use these local reusable procedures inside the same serial assistant conversation when they fit the user request.',
     '',
-    ...snapshot.enabledBundles.slice(0, 4).flatMap((bundle) => [
-      `### Skill Bundle: ${bundle.name}`,
-      `Description: ${bundle.description}`,
-      `Review state: ${bundle.reviewState}`,
-      `Included skills: ${bundle.skillIds.join(', ')}`,
-      '',
-    ]),
+    ...snapshot.enabledBundles.slice(0, 4).flatMap((bundle) => {
+      const readiness = evaluateAgentSkillBundleReadiness(bundle, snapshot.skills);
+      const missing = [
+        ...readiness.missingRequirements.map(formatAgentSkillRequirement),
+        ...readiness.missingSkillIds.map((skillId) => `skill:${skillId}`),
+      ];
+      return [
+        `### Skill Bundle: ${bundle.name}`,
+        `Description: ${bundle.description}`,
+        `Review: ${formatAgentRecordReviewState(bundle.reviewState)}`,
+        `Readiness: ${readiness.ready ? 'ready' : `missing ${missing.join(', ')}`}`,
+        `Included skills: ${bundle.skillIds.join(', ')}`,
+        '',
+      ];
+    }),
     ...active.slice(0, 8).flatMap((skill) => [
       `### ${skill.name}`,
       `Description: ${skill.description}`,
-      `Review state: ${skill.reviewState}`,
+      `Review: ${formatAgentRecordReviewState(skill.reviewState)}`,
       `Triggers: ${skill.triggers.join(', ') || '(manual)'}`,
+      `Readiness: ${evaluateAgentSkillReadiness(skill).ready ? 'ready' : `missing ${evaluateAgentSkillReadiness(skill).missing.map(formatAgentSkillRequirement).join(', ')}`}`,
       skill.procedure,
       '',
     ]),

package/src/cli/agent-knowledge-args.ts

@@ -14,7 +14,7 @@ export function commandValues(args: readonly string[]): string[] {
 export function delegationTaskValues(args: readonly string[]): string[] {
   const values: string[] = [];
   for (const token of args) {
-    if (token === '--wrfc') continue;
+    if (token === '--review' || token === '--wrfc') continue;
     if (!token.startsWith('--')) values.push(token);
   }
   return values;
@@ -79,6 +79,10 @@ export function hasFlag(args: readonly string[], flag: string): boolean {
   return args.includes(flag);
 }
 
+export function hasAnyFlag(args: readonly string[], flags: readonly string[]): boolean {
+  return flags.some((flag) => args.includes(flag));
+}
+
 export function stripCommandFlag(args: readonly string[], flag: string): { readonly rest: readonly string[]; readonly present: boolean } {
   const rest: string[] = [];
   let present = false;

package/src/cli/agent-knowledge-command.ts

@@ -3,6 +3,7 @@ import type { CliCommandRuntime } from './management.ts';
 import {
   commandValues,
   delegationTaskValues,
+  hasAnyFlag,
   hasFlag,
   parseConnectorInput,
   readFirstStringList,
@@ -14,6 +15,7 @@ import {
 } from './agent-knowledge-args.ts';
 import {
   formatAsk,
+  formatAgentKnowledgeFailureKind,
   formatBatchIngest,
   formatConnector,
   formatConnectorDoctor,
@@ -30,7 +32,7 @@ import {
 import { AGENT_KNOWLEDGE_METHODS, DELEGATION_METHOD } from './agent-knowledge-methods.ts';
 import {
   createAgentSdk,
-  fetchDaemonStatus,
+  fetchConnectedHostStatus,
   findDisallowedKnowledgeScopeFlag,
   formatScopeFlagRejection,
   getAgentKnowledgeJson,
@@ -38,7 +40,7 @@ import {
   postAgentKnowledgeJson,
   readPackageMetadata,
   readString,
-  resolveDaemonConnection,
+  resolveConnectedHostConnection,
   runKnowledgeCall,
 } from './agent-knowledge-runtime.ts';
 import { formatJsonOrText, yesNo } from './management.ts';
@@ -47,23 +49,23 @@ interface DelegationResult {
   readonly sessionId: string;
   readonly message: unknown;
   readonly task: string;
-  readonly wrfcRequested: boolean;
+  readonly reviewRequested: boolean;
 }
 
-function buildDelegationBody(task: string, wrfcRequested: boolean): string {
+function buildDelegationBody(task: string, reviewRequested: boolean): string {
   return [
     'GoodVibes Agent explicit build delegation.',
     '',
-    'Original user ask:',
+    'Original user ask',
     task,
     '',
-    'Agent policy:',
+    'Agent policy',
     '- GoodVibes Agent is not the coding TUI.',
     '- Preserve the full original ask.',
-    '- GoodVibes TUI owns file edits, git/worktree flows, execution isolation UX, and any WRFC owner chain.',
-    wrfcRequested
-      ? '- WRFC was explicitly requested by the Agent user for this build/fix/review delegation.'
-      : '- WRFC was not explicitly requested; do not turn this into WRFC solely because it came from Agent.',
+    '- GoodVibes TUI owns file edits, git/worktree flows, execution isolation UX, and any delegated review owner chain.',
+    reviewRequested
+      ? '- Delegated review was explicitly requested by the Agent user for this build/fix/review handoff.'
+      : '- Delegated review was not explicitly requested; do not add review solely because this came from Agent.',
   ].join('\n');
 }
 
@@ -479,12 +481,12 @@ export async function handleAgentKnowledgeShortcutCommand(
 }
 
 export async function handleCompatCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
-  const connection = resolveDaemonConnection(runtime);
+  const connection = resolveConnectedHostConnection(runtime);
   const metadata = readPackageMetadata();
-  const daemon = await fetchDaemonStatus(connection);
-  const daemonRecord = isRecord(daemon.body) ? daemon.body : {};
-  const daemonVersion = readString(daemonRecord, 'version') ?? 'unknown';
-  const versionCompatible = daemon.ok && daemonVersion === metadata.sdkVersion;
+  const connectedHost = await fetchConnectedHostStatus(connection);
+  const connectedHostRecord = isRecord(connectedHost.body) ? connectedHost.body : {};
+  const connectedHostVersion = readString(connectedHostRecord, 'version') ?? 'unknown';
+  const versionCompatible = connectedHost.ok && connectedHostVersion === metadata.sdkVersion;
   const knowledgeRoute = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.status, async (routeConnection) => (
     await createAgentSdk(routeConnection).knowledge.status()
   ));
@@ -493,11 +495,11 @@ export async function handleCompatCommand(runtime: CliCommandRuntime): Promise<C
     ok: versionCompatible && knowledgeRouteReady,
     packageVersion: metadata.version,
     sdkPin: metadata.sdkVersion,
-    daemon: {
+    connectedHost: {
       baseUrl: connection.baseUrl,
-      status: daemon.status,
-      version: daemonVersion,
-      reachable: daemon.ok,
+      status: connectedHost.status,
+      version: connectedHostVersion,
+      reachable: connectedHost.ok,
       compatible: versionCompatible,
     },
     auth: {
@@ -512,13 +514,13 @@ export async function handleCompatCommand(runtime: CliCommandRuntime): Promise<C
   };
   const text = [
     'GoodVibes Agent compatibility',
-    `  package: ${metadata.version}`,
-    `  SDK pin: ${metadata.sdkVersion}`,
-    `  runtime: ${daemonVersion} at ${connection.baseUrl} (${daemon.ok ? 'reachable' : 'unreachable'})`,
-    `  version compatible: ${yesNo(versionCompatible)}`,
-    `  operator token: ${connection.token ? 'present' : 'missing'} (${connection.tokenPath})`,
-    `  Agent knowledge route: ${knowledgeRouteReady ? 'ready' : `not ready (${knowledgeRoute.ok ? 'unknown' : knowledgeRoute.kind})`}`,
-    ...(versionCompatible ? [] : ['  next: update connected GoodVibes services so /status matches the Agent SDK pin.']),
+    `  package ${metadata.version}`,
+    `  SDK pin ${metadata.sdkVersion}`,
+    `  connected host ${connectedHostVersion} at ${connection.baseUrl} (${connectedHost.ok ? 'reachable' : 'unreachable'})`,
+    `  version compatible ${yesNo(versionCompatible)}`,
+    `  operator token ${connection.token ? 'present' : 'missing'} (${connection.tokenPath})`,
+    `  Agent Knowledge route ${knowledgeRouteReady ? 'ready' : `not ready (${knowledgeRoute.ok ? 'unknown' : formatAgentKnowledgeFailureKind(knowledgeRoute.kind)})`}`,
+    ...(versionCompatible ? [] : ['  next update the connected GoodVibes host so /status matches the Agent SDK pin.']),
   ].join('\n');
   return {
     output: runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text,
@@ -527,11 +529,11 @@ export async function handleCompatCommand(runtime: CliCommandRuntime): Promise<C
 }
 
 export async function handleDelegateCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
-  const wrfcRequested = hasFlag(runtime.cli.commandArgs, '--wrfc');
+  const reviewRequested = hasAnyFlag(runtime.cli.commandArgs, ['--review', '--wrfc']);
   const task = delegationTaskValues(runtime.cli.commandArgs).join(' ').trim();
   if (!task) {
     return {
-      output: 'Usage: goodvibes-agent delegate [--wrfc] <build/fix/review task>',
+      output: 'Usage: goodvibes-agent delegate [--review] <build/fix/review task>',
       exitCode: 2,
     };
   }
@@ -548,10 +550,14 @@ export async function handleDelegateCommand(runtime: CliCommandRuntime): Promise
     if (!sessionId) throw new Error('sessions.create returned no session id.');
     const message = await sdk.operator.invoke('sessions.messages.create', {
       sessionId,
-      body: buildDelegationBody(task, wrfcRequested),
+      body: buildDelegationBody(task, reviewRequested),
       surfaceKind: 'goodvibes-agent',
       surfaceId: 'goodvibes-agent-cli',
       kind: 'task',
+      metadata: {
+        reviewRequested,
+        wrfcRequested: reviewRequested,
+      },
       routing: {
         executionIntent: {
           riskClass: 'elevated',
@@ -561,15 +567,15 @@ export async function handleDelegateCommand(runtime: CliCommandRuntime): Promise
         },
       },
     });
-    return { sessionId, message, task, wrfcRequested };
+    return { sessionId, message, task, reviewRequested };
   });
   if (!result.ok) return { output: formatFailure(result, runtime.cli.flags.outputFormat === 'json'), exitCode: 1 };
   const text = [
     'Delegation submitted to GoodVibes TUI/shared-session routes.',
-    `  session: ${result.data.sessionId}`,
-    `  mode: ${result.data.wrfcRequested ? 'WRFC requested' : 'direct build delegation'}`,
-    `  task: ${result.data.task}`,
-    '  next: check GoodVibes TUI shared-session/task status for the result.',
+    `  session ${result.data.sessionId}`,
+    `  mode ${result.data.reviewRequested ? 'delegated review requested' : 'direct build delegation'}`,
+    `  task ${result.data.task}`,
+    '  next check GoodVibes TUI shared-session/task status for the result.',
   ].join('\n');
   return {
     output: formatJsonOrText(runtime.cli)(result, text),