@pellux/goodvibes-agent 0.1.101 → 0.1.103

package/src/cli/memory-command.ts

@@ -0,0 +1,646 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { createShellPathService } from '@/runtime/index.ts';
+import {
+  MemoryEmbeddingProviderRegistry,
+  MemoryRegistry,
+  MemoryStore,
+  type MemoryBundle,
+  type MemoryClass,
+  type MemoryLink,
+  type MemoryRecord,
+  type MemoryReviewState,
+  type MemoryScope,
+  type MemorySearchFilter,
+  type MemorySemanticSearchResult,
+  type ProvenanceLink,
+  type ProvenanceLinkKind,
+} from '@pellux/goodvibes-sdk/platform/state';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+import type { CliCommandOutput } from './types.ts';
+import type { CliCommandRuntime } from './management.ts';
+
+const VALID_CLASSES: readonly MemoryClass[] = ['decision', 'constraint', 'incident', 'pattern', 'fact', 'risk', 'runbook', 'architecture', 'ownership'];
+const VALID_SCOPES: readonly MemoryScope[] = ['session', 'project', 'team'];
+const VALID_REVIEW_STATES: readonly MemoryReviewState[] = ['fresh', 'reviewed', 'stale', 'contradicted'];
+const VALID_PROVENANCE_KINDS: readonly ProvenanceLinkKind[] = ['session', 'turn', 'task', 'event', 'file'];
+const VALUE_OPTIONS = new Set([
+  'by',
+  'cls',
+  'confidence',
+  'detail',
+  'file',
+  'label',
+  'limit',
+  'reason',
+  'review-state',
+  'scope',
+  'session',
+  'tags',
+  'task',
+  'turn',
+]);
+const SECRET_PATTERNS: readonly RegExp[] = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/i,
+  /\bsk-[A-Za-z0-9_-]{16,}\b/,
+  /\bgh[pousr]_[A-Za-z0-9_]{16,}\b/i,
+  /\b(?:password|passwd|api[_-]?key|token|secret)\s*[:=]\s*\S{6,}/i,
+];
+
+interface CommandSuccess<TData> {
+  readonly ok: true;
+  readonly kind: string;
+  readonly data: TData;
+}
+
+interface CommandFailure {
+  readonly ok: false;
+  readonly kind: string;
+  readonly error: string;
+}
+
+interface ParsedOptions {
+  readonly values: ReadonlyMap<string, string>;
+  readonly flags: ReadonlySet<string>;
+  readonly positionals: readonly string[];
+}
+
+interface MemoryContext {
+  readonly registry: MemoryRegistry;
+  readonly store: MemoryStore;
+  readonly path: string;
+}
+
+interface MemoryListData {
+  readonly path: string;
+  readonly records: readonly MemoryRecord[];
+  readonly filter: MemorySearchFilter;
+}
+
+interface MemorySearchData extends MemoryListData {
+  readonly semantic: boolean;
+  readonly semanticResults: readonly MemorySemanticSearchResult[];
+}
+
+function jsonOrText(runtime: CliCommandRuntime, value: unknown, text: string): string {
+  return runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text;
+}
+
+function success<TData>(runtime: CliCommandRuntime, kind: string, data: TData, text: string): CliCommandOutput {
+  const value: CommandSuccess<TData> = { ok: true, kind, data };
+  return { output: jsonOrText(runtime, value, text), exitCode: 0 };
+}
+
+function failure(runtime: CliCommandRuntime, kind: string, error: string, exitCode: number): CliCommandOutput {
+  const value: CommandFailure = { ok: false, kind, error };
+  return {
+    output: runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : error,
+    exitCode,
+  };
+}
+
+function parseOptions(args: readonly string[]): ParsedOptions {
+  const values = new Map<string, string>();
+  const flags = new Set<string>();
+  const positionals: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? '';
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+    const equalIndex = arg.indexOf('=');
+    const rawName = equalIndex >= 0 ? arg.slice(2, equalIndex) : arg.slice(2);
+    const name = rawName.trim();
+    if (!name) continue;
+    if (equalIndex >= 0) {
+      values.set(name, arg.slice(equalIndex + 1));
+      continue;
+    }
+    if (VALUE_OPTIONS.has(name)) {
+      const next = args[index + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        values.set(name, next);
+        index += 1;
+        continue;
+      }
+    }
+    flags.add(name);
+  }
+  return { values, flags, positionals };
+}
+
+function optionValue(options: ParsedOptions, name: string): string | undefined {
+  const value = options.values.get(name);
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function hasFlag(options: ParsedOptions, name: string): boolean {
+  return options.flags.has(name);
+}
+
+function csvOption(options: ParsedOptions, name: string): readonly string[] | undefined {
+  const value = optionValue(options, name);
+  if (value === undefined) return undefined;
+  return value.split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+
+function parseLimit(value: string | undefined, fallback: number): number {
+  if (value === undefined) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed < 1) throw new Error('--limit must be a positive integer.');
+  return Math.min(parsed, 200);
+}
+
+function parseConfidence(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 100) throw new Error('--confidence must be an integer from 0 to 100.');
+  return parsed;
+}
+
+function isMemoryClass(value: string): value is MemoryClass {
+  return VALID_CLASSES.includes(value as MemoryClass);
+}
+
+function isMemoryScope(value: string): value is MemoryScope {
+  return VALID_SCOPES.includes(value as MemoryScope);
+}
+
+function isReviewState(value: string): value is MemoryReviewState {
+  return VALID_REVIEW_STATES.includes(value as MemoryReviewState);
+}
+
+function isProvenanceKind(value: string): value is ProvenanceLinkKind {
+  return VALID_PROVENANCE_KINDS.includes(value as ProvenanceLinkKind);
+}
+
+function requireClass(value: string | undefined): MemoryClass {
+  if (!value || !isMemoryClass(value)) throw new Error(`Invalid memory class "${value ?? ''}". Valid: ${VALID_CLASSES.join(', ')}`);
+  return value;
+}
+
+function requireScope(value: string | undefined): MemoryScope {
+  if (!value || !isMemoryScope(value)) throw new Error(`Invalid memory scope "${value ?? ''}". Valid: ${VALID_SCOPES.join(', ')}`);
+  return value;
+}
+
+function optionalScope(value: string | undefined): MemoryScope | undefined {
+  if (value === undefined) return undefined;
+  return requireScope(value);
+}
+
+function optionalClass(value: string | undefined): MemoryClass | undefined {
+  if (value === undefined) return undefined;
+  return requireClass(value);
+}
+
+function containsSecretLikeText(text: string): boolean {
+  return SECRET_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+function assertNoSecretLikeText(fields: readonly string[]): void {
+  if (fields.some((field) => containsSecretLikeText(field))) {
+    throw new Error('Agent memory cannot store secret-looking values. Store a secret reference or remove the sensitive text.');
+  }
+}
+
+function timestamp(value: number): string {
+  return new Date(value).toISOString().slice(0, 19).replace('T', ' ');
+}
+
+function memoryDbPath(runtime: CliCommandRuntime): string {
+  return createShellPathService({
+    workingDirectory: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  }).resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'memory.sqlite');
+}
+
+async function withMemory<T>(runtime: CliCommandRuntime, fn: (context: MemoryContext) => Promise<T> | T): Promise<T> {
+  const path = memoryDbPath(runtime);
+  const embeddingRegistry = new MemoryEmbeddingProviderRegistry({ configManager: runtime.configManager });
+  const store = new MemoryStore(path, { embeddingRegistry });
+  await store.init();
+  const registry = new MemoryRegistry(store);
+  try {
+    return await fn({ registry, store, path });
+  } finally {
+    await store.save();
+    store.close();
+  }
+}
+
+function renderRecordLine(record: MemoryRecord, semanticEntry?: MemorySemanticSearchResult): string {
+  const tags = record.tags.length > 0 ? ` tags=${record.tags.join(',')}` : '';
+  const score = semanticEntry ? ` sim=${Math.round(semanticEntry.similarity * 100)}%` : '';
+  return `  ${record.id}  ${record.scope}/${record.cls}  ${record.reviewState}  ${record.confidence}%${score}${tags}  ${record.summary}`;
+}
+
+function renderRecordList(title: string, path: string, records: readonly MemoryRecord[], semanticResults: readonly MemorySemanticSearchResult[] = []): string {
+  if (records.length === 0) {
+    return [
+      title,
+      `  store: ${path}`,
+      '  No Agent memory records found.',
+      '  Add one with: goodvibes-agent memory add fact "Useful durable fact" --scope project',
+    ].join('\n');
+  }
+  return [
+    `${title} (${records.length})`,
+    `  store: ${path}`,
+    ...records.map((record) => renderRecordLine(record, semanticResults.find((entry) => entry.record.id === record.id))),
+  ].join('\n');
+}
+
+function renderRecord(record: MemoryRecord, links: readonly MemoryLink[]): string {
+  return [
+    `Memory ${record.id}`,
+    `  scope: ${record.scope}`,
+    `  class: ${record.cls}`,
+    `  review: ${record.reviewState}`,
+    `  confidence: ${record.confidence}`,
+    `  tags: ${record.tags.join(', ') || '(none)'}`,
+    `  created: ${timestamp(record.createdAt)}`,
+    `  updated: ${timestamp(record.updatedAt)}`,
+    record.reviewedAt ? `  reviewed: ${timestamp(record.reviewedAt)}${record.reviewedBy ? ` by ${record.reviewedBy}` : ''}` : '',
+    record.staleReason ? `  stale reason: ${record.staleReason}` : '',
+    '',
+    record.summary,
+    record.detail ? `\n${record.detail}` : '',
+    record.provenance.length > 0 ? '\nProvenance:' : '',
+    ...record.provenance.map((entry) => `  ${entry.kind}:${entry.ref}${entry.label ? ` (${entry.label})` : ''}`),
+    links.length > 0 ? '\nLinks:' : '',
+    ...links.map((link) => `  ${link.fromId} -> ${link.toId} [${link.relation}]`),
+  ].filter((line): line is string => Boolean(line)).join('\n');
+}
+
+function filterFromOptions(options: ParsedOptions, defaultLimit: number): MemorySearchFilter {
+  const filter: MemorySearchFilter = {
+    limit: parseLimit(optionValue(options, 'limit'), defaultLimit),
+  };
+  const scope = optionalScope(optionValue(options, 'scope'));
+  const cls = optionalClass(optionValue(options, 'cls'));
+  const tags = csvOption(options, 'tags');
+  if (scope !== undefined) filter.scope = scope;
+  if (cls !== undefined) filter.cls = cls;
+  if (tags !== undefined) filter.tags = [...tags];
+  return filter;
+}
+
+function addProvenance(provenance: ProvenanceLink[], kind: ProvenanceLinkKind, ref: string | undefined): void {
+  if (ref !== undefined && ref.trim().length > 0) provenance.push({ kind, ref: ref.trim() });
+}
+
+function provenanceFromOptions(options: ParsedOptions): readonly ProvenanceLink[] {
+  const provenance: ProvenanceLink[] = [];
+  addProvenance(provenance, 'session', optionValue(options, 'session'));
+  addProvenance(provenance, 'turn', optionValue(options, 'turn'));
+  addProvenance(provenance, 'task', optionValue(options, 'task'));
+  addProvenance(provenance, 'file', optionValue(options, 'file'));
+  if (provenance.length === 0) provenance.push({ kind: 'event', ref: 'cli' });
+  return provenance;
+}
+
+function usage(): string {
+  return [
+    'Usage: goodvibes-agent memory <subcommand>',
+    '  list [class] [--scope <session|project|team>] [--limit <n>]',
+    '  search <query> [--semantic] [--cls <class>] [--scope <scope>] [--limit <n>]',
+    '  add <class> <summary> [--scope <scope>] [--detail <text>] [--tags a,b] [--confidence <0-100>]',
+    '  show <id>',
+    '  queue [limit]',
+    '  review <id> <fresh|reviewed|stale|contradicted> [--confidence <0-100>] [--by <name>] [--reason <text>]',
+    '  stale <id> <reason>',
+    '  contradict <id> <reason>',
+    '  promote <id> <session|project|team> --yes',
+    '  link <fromId> <toId> <relation> --yes',
+    '  delete <id> --yes',
+    '  export <path> [--scope <scope>] [--cls <class>] --yes',
+    '  import <path> --yes',
+    '  handoff-inspect <path>',
+    '  vector [status|doctor|rebuild]',
+    '',
+    'Agent memory is local to GoodVibes Agent and never falls back to default Knowledge/Wiki or non-Agent knowledge segments.',
+  ].join('\n');
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+
+function isProvenanceLink(value: unknown): value is ProvenanceLink {
+  if (!isRecord(value)) return false;
+  return typeof value.ref === 'string' && typeof value.kind === 'string' && isProvenanceKind(value.kind);
+}
+
+function isMemoryRecord(value: unknown): value is MemoryRecord {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.id === 'string'
+    && typeof value.scope === 'string'
+    && isMemoryScope(value.scope)
+    && typeof value.cls === 'string'
+    && isMemoryClass(value.cls)
+    && typeof value.summary === 'string'
+    && (value.detail === undefined || typeof value.detail === 'string')
+    && isStringArray(value.tags)
+    && Array.isArray(value.provenance)
+    && value.provenance.every(isProvenanceLink)
+    && typeof value.reviewState === 'string'
+    && isReviewState(value.reviewState)
+    && typeof value.confidence === 'number'
+    && typeof value.createdAt === 'number'
+    && typeof value.updatedAt === 'number'
+  );
+}
+
+function isMemoryLink(value: unknown): value is MemoryLink {
+  if (!isRecord(value)) return false;
+  return typeof value.fromId === 'string'
+    && typeof value.toId === 'string'
+    && typeof value.relation === 'string'
+    && typeof value.createdAt === 'number';
+}
+
+function isMemoryBundle(value: unknown): value is MemoryBundle {
+  if (!isRecord(value)) return false;
+  return value.schemaVersion === 'v1'
+    && typeof value.exportedAt === 'number'
+    && (value.scope === 'all' || (typeof value.scope === 'string' && isMemoryScope(value.scope)))
+    && typeof value.recordCount === 'number'
+    && typeof value.linkCount === 'number'
+    && Array.isArray(value.records)
+    && value.records.every(isMemoryRecord)
+    && Array.isArray(value.links)
+    && value.links.every(isMemoryLink);
+}
+
+function readBundle(path: string): MemoryBundle {
+  const parsed: unknown = JSON.parse(readFileSync(path, 'utf-8'));
+  if (!isMemoryBundle(parsed)) throw new Error('Invalid Agent memory bundle.');
+  for (const record of parsed.records) {
+    assertNoSecretLikeText([
+      record.summary,
+      record.detail ?? '',
+      ...record.tags,
+      ...record.provenance.map((entry) => `${entry.kind}:${entry.ref} ${entry.label ?? ''}`),
+    ]);
+  }
+  return parsed;
+}
+
+function resolvePath(runtime: CliCommandRuntime, path: string): string {
+  return resolve(runtime.workingDirectory, path);
+}
+
+function writeBundle(path: string, bundle: MemoryBundle): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(bundle, null, 2)}\n`);
+}
+
+function renderBundleInspection(path: string, bundle: MemoryBundle): string {
+  return [
+    'Agent memory handoff bundle',
+    `  path: ${path}`,
+    `  scope: ${bundle.scope}`,
+    `  records: ${bundle.recordCount}`,
+    `  links: ${bundle.linkCount}`,
+    ...bundle.records.slice(0, 20).map((record) => `  ${record.id} ${record.scope}/${record.cls} ${record.reviewState} ${record.summary}`),
+    bundle.records.length > 20 ? `  ... ${bundle.records.length - 20} more` : '',
+  ].filter((line): line is string => Boolean(line)).join('\n');
+}
+
+function errorOutput(runtime: CliCommandRuntime, error: unknown): CliCommandOutput {
+  const message = error instanceof Error ? error.message : String(error);
+  const exitCode = message.startsWith('Usage:') || message.startsWith('Invalid ') || message.startsWith('--') ? 2 : 1;
+  return failure(runtime, 'agent.memory.error', message, exitCode);
+}
+
+async function handleList(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const options = parseOptions(args);
+  const positionalClass = options.positionals[0];
+  const filter = filterFromOptions(options, 50);
+  if (positionalClass !== undefined) filter.cls = requireClass(positionalClass);
+  const records = context.registry.search(filter);
+  const data: MemoryListData = { path: context.path, records, filter };
+  return success(runtime, 'agent.memory.list', data, renderRecordList('Agent memory', context.path, records));
+}
+
+async function handleSearch(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const options = parseOptions(args);
+  const query = options.positionals.join(' ').trim();
+  if (!query) return failure(runtime, 'invalid_memory_command', 'Usage: goodvibes-agent memory search <query> [--semantic] [--cls <class>] [--scope <scope>] [--limit <n>]', 2);
+  const filter = filterFromOptions(options, 20);
+  filter.query = query;
+  const semantic = hasFlag(options, 'semantic') || hasFlag(options, 'vector');
+  if (semantic) filter.semantic = true;
+  const semanticResults = semantic ? context.registry.searchSemantic(filter) : [];
+  const records = semantic ? semanticResults.map((entry) => entry.record) : context.registry.search(filter);
+  const data: MemorySearchData = { path: context.path, records, filter, semantic, semanticResults };
+  return success(runtime, 'agent.memory.search', data, renderRecordList(`Agent memory matching "${query}"`, context.path, records, semanticResults));
+}
+
+async function handleAdd(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const options = parseOptions(args);
+  const [classRaw, ...summaryParts] = options.positionals;
+  const cls = requireClass(classRaw);
+  const summary = summaryParts.join(' ').trim();
+  if (!summary) return failure(runtime, 'invalid_memory_command', 'Usage: goodvibes-agent memory add <class> <summary> [--scope <scope>] [--detail <text>] [--tags a,b]', 2);
+  const detail = optionValue(options, 'detail');
+  const tags = csvOption(options, 'tags');
+  assertNoSecretLikeText([summary, detail ?? '', ...(tags ?? [])]);
+  const reviewState = optionValue(options, 'review-state');
+  if (reviewState !== undefined && !isReviewState(reviewState)) {
+    return failure(runtime, 'invalid_memory_command', `Invalid review state "${reviewState}". Valid: ${VALID_REVIEW_STATES.join(', ')}`, 2);
+  }
+  const record = await context.registry.add({
+    scope: optionalScope(optionValue(options, 'scope')) ?? 'project',
+    cls,
+    summary,
+    detail,
+    tags: tags === undefined ? undefined : [...tags],
+    provenance: [...provenanceFromOptions(options)],
+    review: {
+      state: reviewState,
+      confidence: parseConfidence(optionValue(options, 'confidence')),
+      reviewedBy: optionValue(options, 'by'),
+    },
+  });
+  return success(runtime, 'agent.memory.add', record, `Agent memory added: ${record.id}`);
+}
+
+async function handleShow(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const id = args[0];
+  if (!id) return failure(runtime, 'invalid_memory_command', 'Usage: goodvibes-agent memory show <id>', 2);
+  const record = context.registry.get(id);
+  if (!record) return failure(runtime, 'memory_not_found', `Memory record not found: ${id}`, 1);
+  return success(runtime, 'agent.memory.show', { record, links: context.registry.linksFor(id) }, renderRecord(record, context.registry.linksFor(id)));
+}
+
+async function handleQueue(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const limit = parseLimit(args[0], 10);
+  const records = context.registry.reviewQueue(limit);
+  return success(runtime, 'agent.memory.queue', { path: context.path, records, limit }, renderRecordList('Agent memory review queue', context.path, records));
+}
+
+async function handleReview(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const options = parseOptions(args);
+  const [id, stateRaw] = options.positionals;
+  if (!id || !stateRaw || !isReviewState(stateRaw)) {
+    return failure(runtime, 'invalid_memory_command', `Usage: goodvibes-agent memory review <id> <${VALID_REVIEW_STATES.join('|')}> [--confidence <0-100>]`, 2);
+  }
+  const record = context.registry.review(id, {
+    state: stateRaw,
+    confidence: parseConfidence(optionValue(options, 'confidence')),
+    reviewedBy: optionValue(options, 'by') ?? 'operator',
+    staleReason: optionValue(options, 'reason'),
+  });
+  if (!record) return failure(runtime, 'memory_not_found', `Memory record not found: ${id}`, 1);
+  return success(runtime, 'agent.memory.review', record, `Agent memory reviewed: ${record.id} ${record.reviewState} ${record.confidence}%`);
+}
+
+async function handleReviewShortcut(runtime: CliCommandRuntime, context: MemoryContext, state: Extract<MemoryReviewState, 'stale' | 'contradicted'>, args: readonly string[]): Promise<CliCommandOutput> {
+  const [id, ...reasonParts] = args;
+  if (!id || reasonParts.length === 0) {
+    return failure(runtime, 'invalid_memory_command', `Usage: goodvibes-agent memory ${state === 'stale' ? 'stale' : 'contradict'} <id> <reason>`, 2);
+  }
+  const record = context.registry.review(id, {
+    state,
+    reviewedBy: 'operator',
+    staleReason: reasonParts.join(' '),
+  });
+  if (!record) return failure(runtime, 'memory_not_found', `Memory record not found: ${id}`, 1);
+  return success(runtime, `agent.memory.${state}`, record, `Agent memory marked ${state}: ${record.id}`);
+}
+
+async function handlePromote(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const options = parseOptions(args);
+  const [id, scopeRaw] = options.positionals;
+  if (!id || !scopeRaw) return failure(runtime, 'invalid_memory_command', 'Usage: goodvibes-agent memory promote <id> <session|project|team> --yes', 2);
+  if (!hasFlag(options, 'yes')) return failure(runtime, 'confirmation_required', `Refusing to promote memory record ${id} without --yes.`, 2);
+  const record = context.registry.update(id, { scope: requireScope(scopeRaw) });
+  if (!record) return failure(runtime, 'memory_not_found', `Memory record not found: ${id}`, 1);
+  return success(runtime, 'agent.memory.promote', record, `Agent memory promoted: ${record.id} -> ${record.scope}`);
+}
+
+async function handleLink(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const options = parseOptions(args);
+  const [fromId, toId, relation] = options.positionals;
+  if (!fromId || !toId || !relation) return failure(runtime, 'invalid_memory_command', 'Usage: goodvibes-agent memory link <fromId> <toId> <relation> --yes', 2);
+  if (!hasFlag(options, 'yes')) return failure(runtime, 'confirmation_required', `Refusing to link memory records ${fromId} and ${toId} without --yes.`, 2);
+  const link = await context.registry.link(fromId, toId, relation);
+  if (!link) return failure(runtime, 'memory_link_failed', 'Memory link failed; check that both records exist.', 1);
+  return success(runtime, 'agent.memory.link', link, `Agent memory linked: ${fromId} -> ${toId} [${relation}]`);
+}
+
+async function handleDelete(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const options = parseOptions(args);
+  const id = options.positionals[0];
+  if (!id) return failure(runtime, 'invalid_memory_command', 'Usage: goodvibes-agent memory delete <id> --yes', 2);
+  if (!hasFlag(options, 'yes')) return failure(runtime, 'confirmation_required', `Refusing to delete memory record ${id} without --yes.`, 2);
+  if (!context.registry.delete(id)) return failure(runtime, 'memory_not_found', `Memory record not found: ${id}`, 1);
+  return success(runtime, 'agent.memory.delete', { id }, `Agent memory deleted: ${id}`);
+}
+
+async function handleExport(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const options = parseOptions(args);
+  const pathArg = options.positionals[0];
+  if (!pathArg) return failure(runtime, 'invalid_memory_command', 'Usage: goodvibes-agent memory export <path> [--scope <scope>] [--cls <class>] --yes', 2);
+  if (!hasFlag(options, 'yes')) return failure(runtime, 'confirmation_required', `Refusing to export Agent memory bundle to ${pathArg} without --yes.`, 2);
+  const filter = filterFromOptions(options, 200);
+  const path = resolvePath(runtime, pathArg);
+  const bundle = context.registry.exportBundle(filter);
+  writeBundle(path, bundle);
+  return success(runtime, 'agent.memory.export', { path, bundle }, `Agent memory exported: ${bundle.recordCount} record(s), ${bundle.linkCount} link(s) -> ${path}`);
+}
+
+async function handleImport(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const options = parseOptions(args);
+  const pathArg = options.positionals[0];
+  if (!pathArg) return failure(runtime, 'invalid_memory_command', 'Usage: goodvibes-agent memory import <path> --yes', 2);
+  if (!hasFlag(options, 'yes')) return failure(runtime, 'confirmation_required', `Refusing to import Agent memory bundle from ${pathArg} without --yes.`, 2);
+  const path = resolvePath(runtime, pathArg);
+  const bundle = readBundle(path);
+  const result = await context.registry.importBundle(bundle);
+  return success(runtime, 'agent.memory.import', { path, result }, `Agent memory imported: ${result.importedRecords} record(s), ${result.importedLinks} link(s); skipped ${result.skippedRecords}`);
+}
+
+async function handleInspect(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const pathArg = args[0];
+  if (!pathArg) return failure(runtime, 'invalid_memory_command', 'Usage: goodvibes-agent memory handoff-inspect <path>', 2);
+  const path = resolvePath(runtime, pathArg);
+  const bundle = readBundle(path);
+  return success(runtime, 'agent.memory.handoffInspect', { path, bundle }, renderBundleInspection(path, bundle));
+}
+
+async function handleVector(runtime: CliCommandRuntime, context: MemoryContext, args: readonly string[]): Promise<CliCommandOutput> {
+  const sub = (args[0] ?? 'status').toLowerCase();
+  if (sub === 'status') {
+    const stats = context.registry.vectorStats();
+    return success(runtime, 'agent.memory.vector.status', stats, [
+      'Agent memory vector index',
+      `  backend: ${stats.backend}`,
+      `  enabled: ${stats.enabled ? 'yes' : 'no'}`,
+      `  available: ${stats.available ? 'yes' : 'no'}`,
+      `  dimensions: ${stats.dimensions}`,
+      `  indexed records: ${stats.indexedRecords}`,
+      ...(stats.path ? [`  path: ${stats.path}`] : []),
+      ...(stats.error ? [`  error: ${stats.error}`] : []),
+    ].join('\n'));
+  }
+  if (sub === 'doctor') {
+    const report = await context.registry.doctor();
+    return success(runtime, 'agent.memory.vector.doctor', report, [
+      'Agent memory vector doctor',
+      `  vector backend: ${report.vector.backend}`,
+      `  vector available: ${report.vector.available ? 'yes' : 'no'}`,
+      `  indexed records: ${report.vector.indexedRecords}`,
+      `  active embedding provider: ${report.embeddings.activeProviderId || '(none)'}`,
+      `  embedding providers: ${report.embeddings.providers.length}`,
+      ...report.embeddings.warnings.map((warning) => `  warning: ${warning}`),
+    ].join('\n'));
+  }
+  if (sub === 'rebuild') {
+    const stats = await context.registry.rebuildVectorsAsync();
+    return success(runtime, 'agent.memory.vector.rebuild', stats, [
+      'Agent memory vector rebuild complete',
+      `  backend: ${stats.backend}`,
+      `  indexed records: ${stats.indexedRecords}`,
+      ...(stats.error ? [`  error: ${stats.error}`] : []),
+    ].join('\n'));
+  }
+  return failure(runtime, 'invalid_memory_command', 'Usage: goodvibes-agent memory vector [status|doctor|rebuild]', 2);
+}
+
+export async function handleMemoryCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  try {
+    const [sub = 'list', ...rest] = runtime.cli.commandArgs;
+    const normalized = sub.toLowerCase();
+    if (normalized === 'handoff-inspect' || normalized === 'inspect') return handleInspect(runtime, rest);
+    return await withMemory(runtime, async (context) => {
+      if (normalized === 'list' || normalized === 'ls') return handleList(runtime, context, rest);
+      if (normalized === 'search' || normalized === 'find') return handleSearch(runtime, context, rest);
+      if (normalized === 'add' || normalized === 'create') return handleAdd(runtime, context, rest);
+      if (normalized === 'show' || normalized === 'get') return handleShow(runtime, context, rest);
+      if (normalized === 'queue') return handleQueue(runtime, context, rest);
+      if (normalized === 'review') return handleReview(runtime, context, rest);
+      if (normalized === 'stale') return handleReviewShortcut(runtime, context, 'stale', rest);
+      if (normalized === 'contradict' || normalized === 'contradicted') return handleReviewShortcut(runtime, context, 'contradicted', rest);
+      if (normalized === 'promote') return handlePromote(runtime, context, rest);
+      if (normalized === 'link') return handleLink(runtime, context, rest);
+      if (normalized === 'delete' || normalized === 'remove' || normalized === 'rm') return handleDelete(runtime, context, rest);
+      if (normalized === 'export' || normalized === 'handoff-export' || normalized === 'share') return handleExport(runtime, context, rest);
+      if (normalized === 'import' || normalized === 'handoff-import') return handleImport(runtime, context, rest);
+      if (normalized === 'vector' || normalized === 'vectors') return handleVector(runtime, context, rest);
+      return failure(runtime, 'invalid_memory_command', usage(), 2);
+    });
+  } catch (error) {
+    return errorOutput(runtime, error);
+  }
+}

package/src/cli/package-verification.ts

@@ -50,6 +50,15 @@ const FORBIDDEN_TARBALL_DOCS = [
   ['docs/home', 'assistant-surface.md'].join(''),
   'docs/wrfc/',
 ] as const;
+const FORBIDDEN_TARBALL_FILES = new Set([
+  'src/panels/agent-inspector-panel.ts',
+  'src/panels/agent-inspector-shared.ts',
+  'src/panels/agent-logs-panel.ts',
+  'src/panels/agent-logs-shared.ts',
+  'src/tools/wrfc-agent-guard.ts',
+  'src/renderer/agent-detail-modal.ts',
+  'src/renderer/process-summary.ts',
+]);
 const PACKAGE_FACING_TEXT_PATHS = [
   'README.md',
   'CHANGELOG.md',
@@ -216,6 +225,7 @@ export function verifyPackageCliInstall(root: string): PackageCliVerificationRep
   const requiredPathsPresent = REQUIRED_TARBALL_PATHS.filter((path) => pack.files.includes(path));
   const forbiddenPaths = pack.files.filter((path) => {
     if (FORBIDDEN_TARBALL_PREFIXES.some((prefix) => path.startsWith(prefix))) return true;
+    if (FORBIDDEN_TARBALL_FILES.has(path)) return true;
     return FORBIDDEN_TARBALL_DOCS.some((docPath) => path === docPath || path.startsWith(docPath));
   });
   const issues: string[] = [];