@pellux/goodvibes-tui 0.22.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/channel-runtime.ts

@@ -0,0 +1,139 @@
+import type { CommandRegistry } from '../command-registry.ts';
+import { requireIntegrationHelpers } from './runtime-services.ts';
+
+export function registerChannelRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'channel',
+    aliases: [],
+    description: 'Inspect channel routes, delivery strategies, and ingress policies',
+    usage: '[status|routes|delivery|policy] [--json]',
+    argsHint: 'status | routes | delivery | policy',
+    handler(args, ctx) {
+      const sub = args[0];
+      const asJson = args.includes('--json');
+
+      if (!sub || sub === 'open' || sub === 'panel') {
+        if (ctx.showPanel) ctx.showPanel('routes');
+        return;
+      }
+
+      const helpers = requireIntegrationHelpers(ctx);
+
+      if (sub === 'status') {
+        const review = helpers.buildReview();
+        if (asJson) {
+          ctx.print(JSON.stringify(review, null, 2));
+          return;
+        }
+        const lines: string[] = [
+          'Channel Status',
+          `  routes:            ${review.routes.length}`,
+          `  api families:      ${review.apiFamilies.join(', ') || '(none)'}`,
+          `  sessions:          ${review.sessions}`,
+          `  tasks:             ${review.tasks}`,
+          `  pending approvals: ${review.pendingApprovals}`,
+          `  remote contracts:  ${review.remoteContracts}`,
+          '',
+          `Active route families: ${review.routes.join(', ') || '(none)'}`,
+          '',
+          'Use /channel routes for delivery binding details.',
+          'Use /channel delivery for outbound delivery snapshot.',
+          'Use /channel policy for ingress policy snapshot.',
+        ];
+        ctx.print(lines.join('\n'));
+        return;
+      }
+
+      if (sub === 'routes') {
+        const snapshot = helpers.getRouteSnapshot();
+        if (asJson) {
+          ctx.print(JSON.stringify(snapshot, null, 2));
+          return;
+        }
+        const entries = Object.entries(snapshot);
+        if (entries.length === 0) {
+          ctx.print('No route bindings active.\n\nRoutes become active when channel surfaces (slack, discord, ntfy, webhook, etc.) are configured and the daemon is running.');
+          return;
+        }
+        const lines: string[] = ['Channel Routes'];
+        for (const [key, value] of entries) {
+          lines.push(`  ${String(key).padEnd(28)} ${JSON.stringify(value)}`);
+        }
+        lines.push('');
+        lines.push('Route bindings reflect active daemon surface registrations.');
+        ctx.print(lines.join('\n'));
+        return;
+      }
+
+      if (sub === 'delivery') {
+        const snapshot = helpers.getDeliverySnapshot();
+        if (asJson) {
+          ctx.print(JSON.stringify(snapshot, null, 2));
+          return;
+        }
+        const entries = Object.entries(snapshot);
+        if (entries.length === 0) {
+          ctx.print('No delivery snapshot available.\n\nDelivery state is populated when the daemon handles outbound channel messages.');
+          return;
+        }
+        const lines: string[] = ['Channel Delivery Snapshot'];
+        for (const [key, value] of entries) {
+          lines.push(`  ${String(key).padEnd(28)} ${JSON.stringify(value)}`);
+        }
+        ctx.print(lines.join('\n'));
+        return;
+      }
+
+      if (sub === 'policy') {
+        const configManager = ctx.platform.configManager;
+        // Channel policy is persisted by ChannelPolicyManager in
+        // .goodvibes/tui/channels/policies.json — surface via configManager
+        // category (runtime-accessible without a daemon round-trip).
+        const surfaces = [
+          'slack', 'discord', 'ntfy', 'webhook', 'homeassistant',
+          'telegram', 'google-chat', 'signal', 'whatsapp',
+          'imessage', 'msteams', 'bluebubbles', 'mattermost', 'matrix',
+        ];
+        const lines: string[] = ['Channel Ingress Policies'];
+        let found = false;
+        for (const surface of surfaces) {
+          const key = `surfaces.${surface}.enabled` as Parameters<typeof configManager.get>[0];
+          const enabled = configManager.get(key);
+          if (enabled !== undefined && enabled !== null) {
+            found = true;
+            lines.push(`  ${surface.padEnd(20)} enabled=${String(enabled)}`);
+          }
+        }
+        if (!found) {
+          lines.push('  No channel surfaces configured.');
+          lines.push('');
+          lines.push('  Configure surfaces via /onboarding or Settings > Surfaces.');
+          lines.push('  Fine-grained ingress policies (allowedCommands, requireMention, groupPolicies)');
+          lines.push('  are managed by ChannelPolicyManager in .goodvibes/tui/channels/policies.json.');
+        } else {
+          lines.push('');
+          lines.push('  Fine-grained ingress policies (allowedCommands, requireMention, groupPolicies)');
+          lines.push('  are managed by ChannelPolicyManager in .goodvibes/tui/channels/policies.json.');
+        }
+        if (asJson) {
+          ctx.print(JSON.stringify({ surfaces: Object.fromEntries(surfaces.map((s) => [s, configManager.get(`surfaces.${s}.enabled` as Parameters<typeof configManager.get>[0])])) }, null, 2));
+          return;
+        }
+        ctx.print(lines.join('\n'));
+        return;
+      }
+
+      ctx.print(
+        'Usage: /channel <subcommand>\n'
+        + '  (no args)  — open the Routes panel\n'
+        + '  status     — channel overview: routes, sessions, tasks, pending approvals\n'
+        + '  routes     — active route binding snapshot\n'
+        + '  delivery   — outbound delivery snapshot\n'
+        + '  policy     — configured channel surfaces and ingress policy location\n'
+        + '\n'
+        + 'Options:\n'
+        + '  --json  Output raw JSON for scripting'
+      );
+    },
+  });
+}

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> => {