@pellux/goodvibes-tui 0.23.0 → 0.24.0

package/src/core/transcript-journal.ts

@@ -0,0 +1,339 @@
+/**
+ * transcript-journal.ts — WAL-style append-only transcript journal.
+ *
+ * Purpose
+ * ───────
+ * Between full snapshots (written by persistConversation / writeRecoveryFile),
+ * a SIGKILL loses every conversation turn since the last snapshot. This module
+ * provides an append-only journal that records each durable conversation event
+ * (user message submitted, assistant turn finalised, tool results appended,
+ * compaction performed) so that a kill at any moment loses at most the
+ * in-flight append — never a full turn.
+ *
+ * File format (NDJSON)
+ * ────────────────────
+ * Line 0  — header:  { version: 1, sessionId: "...", createdAt: <epochMs> }
+ * Line 1+ — records: { type, seq, ts, messages: ConversationMessageSnapshot[] }
+ *
+ * The header carries the schemaVersion so that a reader from a future process
+ * can gate on it (readVersioned convention: unknown version → quarantine).
+ *
+ * Durability / performance tradeoff
+ * ──────────────────────────────────
+ * appendRecord() performs one appendFileSync + one fsyncSync per call.
+ * This means one fsync per durable conversation event (user message,
+ * assistant turn, tool result batch, compaction). It does NOT fsync per
+ * streaming token — the streaming path never calls appendRecord().
+ *
+ * At typical usage (a few events per user turn), this is 2–6 fsyncs/min,
+ * well within the durability/throughput envelope of any modern filesystem.
+ * The tradeoff is explicit: we accept per-event write amplification in
+ * exchange for at-most-one-record loss on SIGKILL.
+ *
+ * Recovery semantics
+ * ──────────────────
+ * 1. Read the header line. Gate on version — quarantine if unrecognised.
+ * 2. Read subsequent lines until EOF. Stop at the first line that is not
+ *    valid JSON or lacks the expected shape. Quarantine the remainder of
+ *    the file from that point onward (rename to .unrecognized). Never crash.
+ * 3. Return only records whose `ts` is strictly greater than the provided
+ *    `snapshotTimestamp` (i.e. events that occurred after the last snapshot).
+ * 4. Caller replays the returned records in `seq` order atop the snapshot
+ *    to reconstruct the conversation, then writes a fresh snapshot and
+ *    calls `journal.rotate()` to truncate the journal.
+ *
+ * Rotation
+ * ────────
+ * After a fresh snapshot is written, call journal.rotate() which deletes the
+ * journal file. The next append will recreate it with a fresh header.
+ *
+ * Journal path convention
+ * ───────────────────────
+ * <homeDirectory>/.goodvibes/tui/transcript-<sessionId>.journal
+ * This mirrors the recovery-file location (homeDirectory-scoped, not
+ * workingDir-scoped) so all per-session durability artefacts live together.
+ */
+
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+export const JOURNAL_SCHEMA_VERSION = 1;
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface JournalHeader {
+  readonly version: typeof JOURNAL_SCHEMA_VERSION;
+  readonly sessionId: string;
+  readonly createdAt: number;
+}
+
+export type JournalEventType =
+  | 'user_message'
+  | 'assistant_turn'
+  | 'tool_results'
+  | 'compaction';
+
+export interface JournalRecord {
+  /** Discriminator for the kind of durable event. */
+  readonly type: JournalEventType;
+  /** Monotonically increasing sequence number (0-based, per journal file). */
+  readonly seq: number;
+  /** Wall-clock timestamp (Date.now()) when the record was appended. */
+  readonly ts: number;
+  /** Full conversation message snapshot at the time of the event. */
+  readonly messages: ConversationMessageSnapshot[];
+}
+
+export interface ReplayResult {
+  /** Records whose ts is strictly after snapshotTimestamp, in seq order. */
+  readonly records: JournalRecord[];
+  /**
+   * True if the journal tail was corrupt (a partial write from a kill).
+   * The corrupt tail has been quarantined; replay stopped at the last
+   * good record.
+   */
+  readonly hadCorruptTail: boolean;
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+export interface TranscriptJournal {
+  /**
+   * Append one durable event record and fsync it to disk.
+   *
+   * Best-effort: if the write fails (e.g. disk full), the error is swallowed
+   * — the journal is durability-enhancing, never a hard requirement.
+   */
+  appendRecord(type: JournalEventType, messages: ConversationMessageSnapshot[]): void;
+
+  /**
+   * Delete the journal file (called after a fresh snapshot is written).
+   * The next appendRecord() will recreate the file with a fresh header.
+   * Best-effort — silently swallows errors.
+   */
+  rotate(): void;
+
+  /** Absolute path to the journal file. */
+  readonly path: string;
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Create a TranscriptJournal for the given session.
+ *
+ * The journal file is created lazily on the first appendRecord() call.
+ * Calling openTranscriptJournal() does not perform any I/O.
+ */
+export function openTranscriptJournal(
+  journalPath: string,
+  sessionId: string,
+): TranscriptJournal {
+  return new TranscriptJournalImpl(journalPath, sessionId);
+}
+
+/**
+ * Build the canonical journal path for a session.
+ *
+ * @param homeDirectory  The goodvibes home directory (e.g. ~/.goodvibes).
+ * @param sessionId      The session identifier.
+ */
+export function journalPathFor(homeDirectory: string, sessionId: string): string {
+  return join(homeDirectory, '.goodvibes', 'tui', `transcript-${sessionId}.journal`);
+}
+
+/**
+ * Replay journal records that post-date `snapshotTimestamp`.
+ *
+ * Returns an empty result if the journal file does not exist.
+ * Corrupt tail lines (partial write from a kill) are quarantined; replay
+ * stops at the first unparseable line.
+ *
+ * @param journalPath       Absolute path to the journal file.
+ * @param snapshotTimestamp The `writtenAt` / `timestamp` of the last known
+ *                          good snapshot. Only records with ts > this value
+ *                          are returned.
+ */
+export function replayJournal(
+  journalPath: string,
+  snapshotTimestamp: number,
+): ReplayResult {
+  if (!existsSync(journalPath)) {
+    return { records: [], hadCorruptTail: false };
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(journalPath, 'utf-8');
+  } catch {
+    return { records: [], hadCorruptTail: false };
+  }
+
+  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+  if (lines.length === 0) {
+    return { records: [], hadCorruptTail: false };
+  }
+
+  // ── Validate header ─────────────────────────────────────────────────────
+  let header: unknown;
+  try {
+    header = JSON.parse(lines[0]);
+  } catch {
+    quarantineJournal(journalPath);
+    return { records: [], hadCorruptTail: true };
+  }
+
+  if (
+    !isPlainObject(header) ||
+    typeof header['version'] !== 'number' ||
+    header['version'] !== JOURNAL_SCHEMA_VERSION
+  ) {
+    quarantineJournal(journalPath);
+    return { records: [], hadCorruptTail: true };
+  }
+
+  // ── Read records ────────────────────────────────────────────────────────
+  const records: JournalRecord[] = [];
+  let firstBadLine = -1;
+
+  for (let i = 1; i < lines.length; i++) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(lines[i]);
+    } catch {
+      firstBadLine = i;
+      break;
+    }
+
+    if (!isValidRecord(parsed)) {
+      firstBadLine = i;
+      break;
+    }
+
+    if (parsed.ts > snapshotTimestamp) {
+      records.push(parsed);
+    }
+  }
+
+  // ── Quarantine corrupt tail ──────────────────────────────────────────────
+  let hadCorruptTail = false;
+  if (firstBadLine !== -1) {
+    hadCorruptTail = true;
+    // Quarantine the remainder: rename the file. Caller will rotate after
+    // replay anyway, but we quarantine now so the original file is not
+    // accidentally replayed again if the process is killed during recovery.
+    quarantineJournal(journalPath);
+  }
+
+  // Sort by seq to guarantee ordering in case lines were reordered (they
+  // should not be, but be defensive).
+  records.sort((a, b) => a.seq - b.seq);
+
+  return { records, hadCorruptTail };
+}
+
+// ─── Implementation ─────────────────────────────────────────────────────────
+
+class TranscriptJournalImpl implements TranscriptJournal {
+  readonly path: string;
+  private readonly _sessionId: string;
+  private _seq = 0;
+  private _initialised = false;
+
+  constructor(journalPath: string, sessionId: string) {
+    this.path = journalPath;
+    this._sessionId = sessionId;
+  }
+
+  appendRecord(type: JournalEventType, messages: ConversationMessageSnapshot[]): void {
+    try {
+      this._ensureInitialised();
+      const record: JournalRecord = {
+        type,
+        seq: this._seq++,
+        ts: Date.now(),
+        messages,
+      };
+      const line = JSON.stringify(record) + '\n';
+      appendFileSync(this.path, line, { mode: 0o600 });
+      // fsync to flush the append to durable storage before returning.
+      const fd = openSync(this.path, 'r+');
+      try {
+        fsyncSync(fd);
+      } finally {
+        closeSync(fd);
+      }
+    } catch {
+      // Best-effort — never crash the TUI over a journal failure.
+    }
+  }
+
+  rotate(): void {
+    try {
+      if (existsSync(this.path)) {
+        unlinkSync(this.path);
+      }
+      this._initialised = false;
+      this._seq = 0;
+    } catch {
+      // Best-effort.
+    }
+  }
+
+  private _ensureInitialised(): void {
+    if (this._initialised && existsSync(this.path)) return;
+
+    mkdirSync(dirname(this.path), { recursive: true });
+    const header: JournalHeader = {
+      version: JOURNAL_SCHEMA_VERSION,
+      sessionId: this._sessionId,
+      createdAt: Date.now(),
+    };
+    // Append the header as the first line. If the file already exists (e.g.
+    // process restarted mid-session), we start appending records after
+    // whatever is already there — the replay function handles seq ordering.
+    // However, to keep things clean, if the file doesn't exist we write fresh.
+    if (!existsSync(this.path)) {
+      appendFileSync(this.path, JSON.stringify(header) + '\n', { mode: 0o600 });
+    }
+    this._initialised = true;
+  }
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isValidRecord(value: unknown): value is JournalRecord {
+  if (!isPlainObject(value)) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v['type'] === 'string' &&
+    typeof v['seq'] === 'number' &&
+    typeof v['ts'] === 'number' &&
+    Array.isArray(v['messages'])
+  );
+}
+
+function quarantineJournal(journalPath: string): void {
+  try {
+    renameSync(journalPath, `${journalPath}.unrecognized`);
+  } catch {
+    // Best-effort — if rename fails, proceed silently.
+  }
+}

package/src/core/turn-event-wiring.ts

@@ -5,6 +5,9 @@ import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import type { HookDispatcher, HookPhase, HookCategory, HookEventPath } from '@pellux/goodvibes-sdk/platform/hooks';
 import type { ConversationManager } from './conversation.ts';
+import { journalPathFor, openTranscriptJournal, type TranscriptJournal } from './transcript-journal.ts';
+import type { WebhookNotifier } from '@pellux/goodvibes-sdk/platform/integrations';
+import { maybeNotifyLongTask, readNotifyAfterSeconds, type LongTaskStatus } from './long-task-notifier.ts';
 
 /** Infer the options param of persistConversation to pick up SessionManager correctly. */
 type PersistOptions = NonNullable<Parameters<typeof persistConversation>[5]>;
@@ -47,6 +50,19 @@ export interface WireTurnEventHandlersOptions {
   readonly lastGitInfoRef: { value: unknown };
   readonly buildSessionContinuityHints: () => Record<string, unknown>;
   readonly render: () => void;
+  /**
+   * Outbound webhook notifier. When provided and URLs are configured,
+   * long-task push notifications are delivered to configured ntfy/webhook
+   * endpoints after the configured threshold. Optional — silently skipped
+   * when absent.
+   */
+  readonly webhookNotifier?: WebhookNotifier | null;
+  /**
+   * Minimal test seam: injectable clock for controlling Date.now() in tests.
+   * Defaults to the real Date.now when absent.
+   * @internal — tests only
+   */
+  readonly _clock?: () => number;
 }
 
 export interface WireTurnEventHandlersResult {
@@ -54,6 +70,8 @@ export interface WireTurnEventHandlersResult {
   readonly refreshGit: () => void;
   /** Unsubscribe functions to push into the parent unsubs array. */
   readonly unsubs: ReadonlyArray<() => void>;
+  /** The per-session transcript journal; call appendRecord() for user-submitted events. */
+  readonly transcriptJournal: TranscriptJournal;
 }
 
 /**
@@ -74,16 +92,51 @@ export function wireTurnEventHandlers(
     events, conversation, runtime, orchestrator, configManager,
     providerRegistry, systemMessageRouter, hookDispatcher,
     workingDir, homeDirectory, sessionManager, gitStatusProvider,
-    lastGitInfoRef, buildSessionContinuityHints, render,
+    lastGitInfoRef, buildSessionContinuityHints, render, webhookNotifier,
+    _clock = Date.now,
   } = options;
 
   const unsubs: Array<() => void> = [];
 
+  // Create the per-session transcript journal. Path mirrors recovery-file
+  // convention (homeDirectory-scoped). Created lazily on first append.
+  const transcriptJournal: TranscriptJournal = openTranscriptJournal(
+    journalPathFor(homeDirectory, runtime.sessionId),
+    runtime.sessionId,
+  );
+
+  // Track turn start time for long-task notification threshold.
+  let turnStartTime: number | null = null;
+
   const refreshGit = (): void => {
     gitStatusProvider.refresh().then((info) => { lastGitInfoRef.value = info; render(); }).catch(() => { /* non-fatal */ });
   };
 
-  unsubs.push(events.turns.on('TURN_COMPLETED', () => {
+  // Journal user message immediately on TURN_SUBMITTED so a SIGKILL during
+  // the subsequent stream loses at most the in-flight token chunk.
+  unsubs.push(events.turns.on('TURN_SUBMITTED', () => {
+    turnStartTime = _clock();
+    try {
+      const snap = conversation.toJSON() as { messages: Array<import('./conversation.ts').ConversationMessageSnapshot> };
+      transcriptJournal.appendRecord('user_message', snap.messages);
+    } catch { /* best-effort */ }
+  }));
+
+  unsubs.push(events.turns.on('TURN_COMPLETED', (evt) => {
+    // Long-task push notification: fires when the turn exceeded the threshold.
+    const turnElapsedMs = turnStartTime !== null ? _clock() - turnStartTime : 0;
+    turnStartTime = null;
+    const notifyThreshold = readNotifyAfterSeconds((k) => configManager.get(k as Parameters<typeof configManager.get>[0]));
+    // stopReason 'empty_response' signals a non-successful completion.
+    const taskStatus: LongTaskStatus = evt.stopReason === 'completed' ? 'ok' : 'fail';
+    maybeNotifyLongTask({
+      elapsedMs: turnElapsedMs,
+      status: taskStatus,
+      kind: 'turn',
+      sessionId: runtime.sessionId,
+      thresholdSeconds: notifyThreshold,
+      webhookNotifier: webhookNotifier ?? null,
+    });
     // Auto-save after every LLM turn so kills don't lose the session
     try {
       const snapshot = conversation.toJSON() as { messages: Array<import('./conversation.ts').ConversationMessageSnapshot>; timestamp?: number };
@@ -97,7 +150,17 @@ export function wireTurnEventHandlers(
         { workingDirectory: workingDir, homeDirectory, sessionManager },
       );
       hookDispatcher.fire({ path: 'Lifecycle:session:save' as HookEventPath, phase: 'Lifecycle' as HookPhase, category: 'session' as HookCategory, specific: 'save', sessionId: runtime.sessionId, timestamp: Date.now(), payload: { sessionId: runtime.sessionId } }).catch((err: unknown) => logger.debug('hook fire error', { error: summarizeError(err) }));
-    } catch (e) { logger.debug('auto-save on turn:complete failed', { error: summarizeError(e) }); }
+      // Snapshot succeeded — rotate the journal (gap-filler no longer needed).
+      transcriptJournal.rotate();
+    } catch (e) {
+      // Snapshot failed — append the turn to the journal so recovery can
+      // reconstruct it. Best-effort; never crash the TUI.
+      try {
+        const snap = conversation.toJSON() as { messages: Array<import('./conversation.ts').ConversationMessageSnapshot> };
+        transcriptJournal.appendRecord('assistant_turn', snap.messages);
+      } catch { /* best-effort */ }
+      logger.debug('auto-save on turn:complete failed', { error: summarizeError(e) });
+    }
     // Auto-compact: check context usage and compact if threshold exceeded
     const currentModelForCompact = providerRegistry.getCurrentModel();
     maybeAutoCompact({
@@ -120,5 +183,5 @@ export function wireTurnEventHandlers(
     refreshGit();
   }));
 
-  return { refreshGit, unsubs };
+  return { refreshGit, unsubs, transcriptJournal };
 }

package/src/input/commands/control-room-runtime.ts

@@ -10,7 +10,6 @@ export function registerControlRoomRuntimeCommands(registry: CommandRegistry): v
     name: 'cockpit',
     aliases: [],
     description: 'Open the unified operator cockpit',
-    usage: '',
     handler(_args, ctx) {
       if (ctx.openCockpitPanel) {
         ctx.openCockpitPanel();
@@ -103,7 +102,6 @@ export function registerControlRoomRuntimeCommands(registry: CommandRegistry): v
     name: 'communication',
     aliases: ['comms'],
     description: 'Inspect structured agent communication routes and recent activity',
-    usage: '',
     handler(_args, ctx) {
       if (ctx.openCommunicationPanel) {
         ctx.openCommunicationPanel();

package/src/input/commands/diff-runtime.ts

@@ -51,7 +51,7 @@ export function registerDiffRuntimeCommands(registry: CommandRegistry): void {
   registry.register({
     name: 'diff',
     aliases: ['d'],
-    description: 'Show unified diff of session file changes. Uses git diff HEAD if in a git repo.',
+    description: 'Show unified diff of session file changes. Uses git diff HEAD if in a git repo',
     usage: '[session|head|working|staged|<git-ref>]',
     argsHint: '[session|head|working|staged|<ref>]',
     async handler(args, ctx) {

package/src/input/commands/eval.ts

@@ -162,7 +162,7 @@ async function handleGate(args: string[], context: CommandContext): Promise<void
 
 export const evalCommand: SlashCommand = {
   name: 'eval',
-  description: 'Evaluation harness: run benchmark suites, compare baselines, and gate regressions.',
+  description: 'Evaluation harness: run benchmark suites, compare baselines, and gate regressions',
   usage: '<subcommand> [args]',
   argsHint: 'list|run <suite>|compare <baseline>|gate <suite>',
   handler: async (args: string[], context: CommandContext): Promise<void> => {

package/src/input/commands/health-runtime.ts

@@ -1,5 +1,6 @@
 import { ServiceRegistry } from '@pellux/goodvibes-sdk/platform/config';
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { probeTermCaps } from '../../renderer/term-caps.ts';
 import { evaluateSessionMaintenance, formatSessionMaintenanceLines } from '@/runtime/index.ts';
 import { estimateConversationTokens } from '@pellux/goodvibes-sdk/platform/core';
 import type { CommandRegistry } from '../command-registry.ts';
@@ -39,7 +40,7 @@ export function registerHealthRuntimeCommands(registry: CommandRegistry): void {
     name: 'health',
     aliases: ['doctor'],
     description: 'Health workspace for startup posture, service readiness, sandbox posture, and provider health',
-    usage: '[open|review|setup|services|sandbox|provider|accounts|auth|settings|intelligence|remote|mcp|continuity|worktrees|maintenance|repair [domain]]',
+    usage: '[open|review|setup|services|sandbox|provider|accounts|auth|settings|intelligence|remote|mcp|continuity|worktrees|maintenance|term|repair [domain]]',
     async handler(args, ctx) {
       const sub = (args[0] ?? 'review').toLowerCase();
       const readModels = requireReadModels(ctx);
@@ -127,8 +128,8 @@ export function registerHealthRuntimeCommands(registry: CommandRegistry): void {
           `  recent failures: ${settings.recentFailureCount}`,
           `  staged bundle: ${settings.hasStagedManagedBundle ? 'present' : 'none'}`,
           ...(issues.length > 0 ? issues.map((issue) => `  issue: ${issue}`) : ['  no active settings-control issues detected']),
-          '  next: /settingssync panel',
-          '  next: /settingssync show <key>',
+          '  next: /settings-sync panel',
+          '  next: /settings-sync show <key>',
           '  next: /managed staged',
         ].join('\n'));
         return;
@@ -282,6 +283,23 @@ export function registerHealthRuntimeCommands(registry: CommandRegistry): void {
         return;
       }
 
+      if (sub === 'term') {
+        const caps = probeTermCaps(process.stdout as NodeJS.WriteStream);
+        const issues: string[] = [];
+        if (caps.capability === 'none') issues.push('terminal reports no color support — UI rendering will be degraded (no ANSI colors)');
+        if (caps.capability === 'basic16') issues.push('terminal limited to 16 ANSI colors — gradient and true-color UI elements will be approximated');
+        if (!caps.syncedOutput) issues.push('DEC Synchronized Output (mode 2026) is disabled — screen-tearing may be visible on slow connections');
+        ctx.print([
+          'Health Review: Terminal Capabilities',
+          `  color capability: ${caps.capability}`,
+          `  synced output (mode 2026): ${caps.syncedOutput ? 'enabled' : 'disabled'}`,
+          `  NO_COLOR env: ${process.env['NO_COLOR'] !== undefined && process.env['NO_COLOR'] !== '' ? 'set (forces none)' : 'unset'}`,
+          `  TERM env: ${process.env['TERM'] ?? '(unset)'}`,
+          ...(issues.length > 0 ? issues.map((issue) => `  issue: ${issue}`) : ['  no terminal capability issues detected']),
+        ].join('\n'));
+        return;
+      }
+
       if (sub === 'repair') {
         const domain = (args[1] ?? 'review').toLowerCase();
         const lines = ['Health Repair'];
@@ -290,7 +308,7 @@ export function registerHealthRuntimeCommands(registry: CommandRegistry): void {
           lines.push('  domain: settings');
           lines.push(...(
             settings.conflicts.length > 0
-              ? ['  /settingssync panel', '  /settingssync show <key>', '  /managed staged']
+              ? ['  /settings-sync panel', '  /settings-sync show <key>', '  /managed staged']
               : ['  no active settings repair actions suggested']
           ));
           lines.push('  verify: /health settings');
@@ -426,6 +444,7 @@ export function registerHealthRuntimeCommands(registry: CommandRegistry): void {
         '  /health remote',
         '  /health maintenance',
         '  /health worktrees',
+        '  /health term',
         '  /health repair <domain>',
         '  /setup onboarding',
       ].join('\n'));

package/src/input/commands/knowledge.ts

@@ -132,7 +132,7 @@ function renderKnowledgeAskResult(result: KnowledgeAskResult): string {
 export const knowledgeCommand: SlashCommand = {
   name: 'knowledge',
   aliases: ['know'],
-  description: 'Structured knowledge graph: ingest URLs/bookmarks, inspect issues, and build compact prompt packets.',
+  description: 'Structured knowledge graph: ingest URLs/bookmarks, inspect issues, and build compact prompt packets',
   usage: '<subcommand> [args]',
   argsHint: 'status|ask|ingest-url|import-bookmarks|import-urls|list|search|get|queue|review-issue|candidates|reports|schedules|lint|packet|explain|reindex|consolidate',
   handler: async (args: string[], context: CommandContext): Promise<void> => {

package/src/input/commands/local-runtime.ts

@@ -53,7 +53,6 @@ export function registerLocalRuntimeCommands(registry: CommandRegistry): void {
     name: 'incident-review',
     aliases: [],
     description: 'Alias for /incident open',
-    usage: '',
     handler(_args, ctx) {
       if (ctx.openIncidentPanel) {
         ctx.openIncidentPanel();
@@ -249,7 +248,7 @@ export function registerLocalRuntimeCommands(registry: CommandRegistry): void {
     aliases: ['img'],
     description: 'Attach an image file to the next message',
     usage: '<path> [prompt text]',
-    argsHint: '<path> [prompt]',
+    argsHint: '<path> [prompt text]',
     async handler(args, ctx) {
       if (args.length === 0) {
         ctx.print('Usage: /image <path> [prompt text]\nSupported formats: PNG, JPEG, WebP, GIF');

package/src/input/commands/memory-product-runtime.ts

@@ -55,7 +55,7 @@ export function registerMemoryProductRuntimeCommands(registry: CommandRegistry):
 
   registry.register({
     name: 'session-memory',
-    description: 'Dedicated front-door for session-scoped memory capture and review. All subcommands are filtered to scope=session.',
+    description: 'Dedicated front-door for session-scoped memory capture and review. All subcommands are filtered to scope=session',
     usage: '[queue [limit] | export <path> | add <class> <summary...>]',
     async handler(args, ctx) {
       const sub = (args[0] ?? 'queue').toLowerCase();
@@ -82,7 +82,7 @@ export function registerMemoryProductRuntimeCommands(registry: CommandRegistry):
 
   registry.register({
     name: 'team-memory',
-    description: 'Dedicated front-door for team/shared memory review and exchange. The queue and export subcommands are filtered to scope=team.',
+    description: 'Dedicated front-door for team/shared memory review and exchange. The queue and export subcommands are filtered to scope=team',
     usage: '[queue [limit] | export <path> | import <path> | capture policy]',
     async handler(args, ctx) {
       const sub = (args[0] ?? 'queue').toLowerCase();

package/src/input/commands/memory.ts

@@ -25,7 +25,7 @@ import { VALID_CLASSES, VALID_REVIEW_STATES, VALID_SCOPES } from './recall-share
 export const recallCommand: SlashCommand = {
   name: 'recall',
   aliases: ['rc'],
-  description: 'Project memory: add decisions, constraints, incidents, and patterns with provenance.',
+  description: 'Project memory: add decisions, constraints, incidents, and patterns with provenance',
   usage: '<subcommand> [args]',
   argsHint: 'add|search|link|get|list|remove',
   handler: async (args: string[], context: CommandContext): Promise<void> => {

package/src/input/commands/onboarding-runtime.ts

@@ -5,7 +5,6 @@ export function registerOnboardingRuntimeCommands(registry: CommandRegistry): vo
   registry.register({
     name: 'onboarding',
     description: 'Open the onboarding wizard with current settings preloaded for review and editing',
-    usage: '',
     handler(_args, ctx) {
       openOnboardingWizard(ctx, { mode: 'edit', reset: true });
       ctx.print('Opening onboarding wizard.');

package/src/input/commands/policy.ts

@@ -4,7 +4,7 @@ import { dispatchPolicyCommand } from './policy-dispatch.ts';
 export const policyCommand: SlashCommand = {
   name: 'policy',
   aliases: ['pol'],
-  description: 'Open the policy panel or manage versioned policy bundles (load, simulate, diff, promote, rollback).',
+  description: 'Open the policy panel or manage versioned policy bundles (load, simulate, diff, promote, rollback)',
   usage: '<subcommand> [args]',
   argsHint: 'load|simulate|diff|lint|preflight|promote|rollback|status',
   handler: async (args: string[], context: CommandContext): Promise<void> => {

package/src/input/commands/profile-sync-runtime.ts

@@ -16,7 +16,8 @@ function inspectProfileSyncBundle(bundle: ProfileSyncBundle): string {
 
 export function registerProfileSyncRuntimeCommands(registry: CommandRegistry): void {
   registry.register({
-    name: 'profilesync',
+    name: 'profile-sync',
+    aliases: ['profilesync'],
     description: 'Export, import, and inspect profile sync bundles',
     usage: '[list|export <path>|inspect <path>|import <path> [prefix]]',
     handler(args, ctx) {
@@ -36,7 +37,7 @@ export function registerProfileSyncRuntimeCommands(registry: CommandRegistry): v
 
       const pathArg = args[1];
       if (!pathArg) {
-        ctx.print(`Usage: /profilesync ${sub} <path>${sub === 'import' ? ' [prefix]' : ''}`);
+        ctx.print(`Usage: /profile-sync ${sub} <path>${sub === 'import' ? ' [prefix]' : ''}`);
         return;
       }
       const targetPath = shellPaths.resolveWorkspacePath(pathArg);
@@ -93,7 +94,7 @@ export function registerProfileSyncRuntimeCommands(registry: CommandRegistry): v
       }
 
       recordSettingsSyncFailure('profiles', `unsupported subcommand: ${sub}`, controlPlaneConfigDir);
-      ctx.print('Usage: /profilesync [list|export <path>|inspect <path>|import <path> [prefix]]');
+      ctx.print('Usage: /profile-sync [list|export <path>|inspect <path>|import <path> [prefix]]');
     },
   });
 }