@pellux/goodvibes-tui 0.20.3 → 0.21.0

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

@@ -0,0 +1,144 @@
+import type { UiRuntimeEvents } from '@/runtime/index.ts';
+import { createStreamStallWatchdog } from './stream-stall-watchdog.ts';
+import { formatUserFacingErrorLine } from './format-user-error.ts';
+
+/**
+ * Live stream and tool-execution metrics maintained by wireStreamEventMetrics.
+ * The object is mutated in place by event handlers; callers declare it before
+ * render() and pass it in, so render() can read the fields without copying.
+ */
+export interface StreamMetrics {
+  /** Epoch ms when the most recent STREAM_START fired; 0 when idle. */
+  startTime: number;
+  /** Number of STREAM_DELTA events received since the last STREAM_START. */
+  deltaCount: number;
+  /** Computed tokens-per-second at the last STREAM_DELTA; 0 when idle. */
+  tokenSpeed: number;
+  /** Elapsed ms from STREAM_START to first STREAM_DELTA (time-to-first-token). */
+  ttftMs: number | undefined;
+  /** Whether TTFT has been recorded for the current turn. */
+  ttftRecorded: boolean;
+  /** Epoch ms when the most recent TOOL_EXECUTING event fired; undefined when idle. */
+  activeToolStartedAtMs: number | undefined;
+  /** Name of the currently executing tool; cleared when execution completes. */
+  activeToolName: string | undefined;
+}
+
+/** Minimal orchestrator surface required for stream token-speed calculation. */
+interface StreamOrchestrator {
+  readonly streamingOutputTokens: number;
+}
+
+/** Minimal provider surface required for the stream stall watchdog. */
+interface StreamProviderRegistry {
+  getCurrentModel(): { readonly provider: string };
+}
+
+/** Minimal system-message surface required for user-visible notifications. */
+interface StreamSystemMessageRouter {
+  high(message: string): void;
+  low(message: string): void;
+}
+
+export interface WireStreamEventMetricsOptions {
+  /** The UI runtime event bus (turns + tools sub-buses). */
+  readonly events: UiRuntimeEvents;
+  /** Orchestrator reference used to read real output token counts. */
+  readonly orchestrator: StreamOrchestrator;
+  /** Provider registry used by the stall watchdog to name the current provider. */
+  readonly providerRegistry: StreamProviderRegistry;
+  /** System message router for turn-error and stall notifications. */
+  readonly systemMessageRouter: StreamSystemMessageRouter;
+  /** Trigger a UI repaint after a state mutation. */
+  readonly render: () => void;
+  /**
+   * Caller-owned metrics object to mutate in place.  Declared before render()
+   * so the render closure can read it without a forward-reference issue.
+   */
+  readonly metrics: StreamMetrics;
+}
+
+/**
+ * Wire STREAM_* and TOOL_* runtime events to the provided StreamMetrics object
+ * and install the stream-stall watchdog.  The caller owns the metrics object
+ * and declares it before render() so both the render closure and the returned
+ * event handlers share the same reference.
+ *
+ * Returns an array of unsubscribe functions; push them into the parent unsubs
+ * array so they are cleaned up on exit.
+ *
+ * Responsibilities:
+ *   - Track stream start time, delta count, token speed, and TTFT
+ *   - Track the currently executing tool name and start time
+ *   - Display TURN_ERROR messages via systemMessageRouter
+ *   - Emit a stall hint when STREAM_START has no delta within the watchdog threshold
+ */
+export function wireStreamEventMetrics(
+  options: WireStreamEventMetricsOptions,
+): ReadonlyArray<() => void> {
+  const { events, metrics, orchestrator, providerRegistry, systemMessageRouter, render } = options;
+
+  const unsubs: Array<() => void> = [];
+
+  unsubs.push(events.turns.on('STREAM_START', () => {
+    metrics.startTime = Date.now();
+    metrics.deltaCount = 0;
+    metrics.tokenSpeed = 0;
+    metrics.ttftMs = undefined;
+    metrics.ttftRecorded = false;
+  }));
+
+  unsubs.push(events.turns.on('STREAM_DELTA', () => {
+    metrics.deltaCount++;
+    const elapsed = (Date.now() - metrics.startTime) / 1000;
+    // Record TTFT on the first delta of each turn.
+    if (!metrics.ttftRecorded) {
+      metrics.ttftMs = Date.now() - metrics.startTime;
+      metrics.ttftRecorded = true;
+    }
+    // Use real output token count for accurate tok/s; fall back to delta count.
+    const tokenCount = orchestrator.streamingOutputTokens > 0
+      ? orchestrator.streamingOutputTokens
+      : metrics.deltaCount;
+    metrics.tokenSpeed = elapsed > 0 ? tokenCount / elapsed : 0;
+  }));
+
+  unsubs.push(events.turns.on('TURN_ERROR', (event) => {
+    const errVal: string = event.error;
+    const formatted = formatUserFacingErrorLine(errVal);
+    systemMessageRouter.high(`[Error] ${formatted}`);
+    render();
+  }));
+
+  // --- Stream stall watchdog: emit one low hint if STREAM_START has no delta within 30s ---
+  const stallWatchdog = createStreamStallWatchdog({
+    events: events.turns,
+    onStall: (providerName) => {
+      systemMessageRouter.low(`Still waiting on ${providerName}… Ctrl+C to cancel`);
+      render();
+    },
+    getProviderName: () => providerRegistry.getCurrentModel().provider,
+    // thresholdMs uses the default 30 000
+  });
+  unsubs.push(() => stallWatchdog.dispose());
+
+  unsubs.push(events.tools.on('TOOL_EXECUTING', (ev) => {
+    metrics.activeToolStartedAtMs = ev.startedAt;
+    metrics.activeToolName = ev.tool;
+    render();
+  }));
+  unsubs.push(events.tools.on('TOOL_SUCCEEDED', () => {
+    metrics.activeToolStartedAtMs = undefined;
+    metrics.activeToolName = undefined;
+  }));
+  unsubs.push(events.tools.on('TOOL_FAILED', () => {
+    metrics.activeToolStartedAtMs = undefined;
+    metrics.activeToolName = undefined;
+  }));
+  unsubs.push(events.tools.on('TOOL_CANCELLED', () => {
+    metrics.activeToolStartedAtMs = undefined;
+    metrics.activeToolName = undefined;
+  }));
+
+  return unsubs;
+}

package/src/core/stream-stall-watchdog.ts

@@ -0,0 +1,103 @@
+/**
+ * StreamStallWatchdog — detects STREAM_START events where no STREAM_DELTA
+ * arrives within a configurable threshold, and emits a single low-priority
+ * hint to the user.
+ *
+ * Design:
+ *   - Arm on STREAM_START: set a timeout for STALL_THRESHOLD_MS.
+ *   - Disarm on STREAM_DELTA: clear the pending timeout (stream is alive).
+ *   - Disarm on STREAM_END / TURN_COMPLETED / TURN_ERROR / TURN_CANCEL:
+ *     clear the timeout (turn finished normally or with error).
+ *   - If the timeout fires: emit ONE hint, do NOT repeat until the next turn.
+ *   - Re-arm only on the next STREAM_START (next turn).
+ *   - dispose(): clears all subscriptions and any pending timeout.
+ *
+ * @module
+ */
+
+/** Milliseconds of silence after STREAM_START before emitting the hint. */
+export const STALL_THRESHOLD_MS = 30_000;
+
+/** Events surface subset the watchdog needs. */
+export interface WatchdogTurnEvents {
+  on(event: 'STREAM_START', handler: () => void): () => void;
+  on(event: 'STREAM_DELTA', handler: () => void): () => void;
+  on(event: 'STREAM_END', handler: () => void): () => void;
+  on(event: 'TURN_COMPLETED', handler: () => void): () => void;
+  on(event: 'TURN_ERROR', handler: () => void): () => void;
+  on(event: 'TURN_CANCEL', handler: () => void): () => void;
+}
+
+export interface StreamStallWatchdogOptions {
+  /** The turns event surface to subscribe on. */
+  events: WatchdogTurnEvents;
+  /**
+   * Called once per turn when the stall threshold is exceeded.
+   * Receives the provider display name for the hint message.
+   */
+  onStall: (providerName: string) => void;
+  /**
+   * Provides the current provider display name at the moment the hint fires.
+   * Optional — defaults to 'provider' when not supplied.
+   */
+  getProviderName?: () => string;
+  /**
+   * Stall threshold in ms. Defaults to STALL_THRESHOLD_MS (30 000).
+   * Exposed for unit tests.
+   */
+  thresholdMs?: number;
+}
+
+export interface StreamStallWatchdog {
+  /** Tear down all subscriptions and cancel any pending timeout. */
+  dispose(): void;
+}
+
+/**
+ * Creates and starts a StreamStallWatchdog.
+ *
+ * Returns a dispose function; add it to the `unsubs` array alongside other
+ * event subscriptions so it is cleaned up on exit.
+ */
+export function createStreamStallWatchdog(opts: StreamStallWatchdogOptions): StreamStallWatchdog {
+  const { events, onStall, getProviderName, thresholdMs = STALL_THRESHOLD_MS } = opts;
+
+  let stallTimer: ReturnType<typeof setTimeout> | null = null;
+  let hintFiredForTurn = false;
+
+  function arm(): void {
+    disarm();
+    hintFiredForTurn = false;
+    stallTimer = setTimeout(() => {
+      stallTimer = null;
+      if (!hintFiredForTurn) {
+        hintFiredForTurn = true;
+        const provider = getProviderName ? getProviderName() : 'provider';
+        onStall(provider);
+      }
+    }, thresholdMs);
+  }
+
+  function disarm(): void {
+    if (stallTimer !== null) {
+      clearTimeout(stallTimer);
+      stallTimer = null;
+    }
+  }
+
+  const unsubs: Array<() => void> = [
+    events.on('STREAM_START', arm),
+    events.on('STREAM_DELTA', disarm),
+    events.on('STREAM_END', disarm),
+    events.on('TURN_COMPLETED', disarm),
+    events.on('TURN_ERROR', disarm),
+    events.on('TURN_CANCEL', disarm),
+  ];
+
+  return {
+    dispose(): void {
+      disarm();
+      for (const unsub of unsubs) unsub();
+    },
+  };
+}

package/src/core/system-message-router.ts

@@ -81,6 +81,8 @@ export class SystemMessageRouter {
    *
    * @param message  - Message text.
    * @param priority - 'high' | 'low'.
+   * @param kind     - Classification kind ('system' | 'wrfc' | 'operational');
+   *                   used to resolve routing target and conversation navigability.
    */
   routeTypedSystemMessage(
     message: string,
@@ -93,7 +95,9 @@ export class SystemMessageRouter {
       this.panel?.push(message, priority);
     }
     if (delivery.toConversation) {
-      this.conversation.addSystemMessage(message);
+      // addTypedSystemMessage threads the kind into the conversation so the
+      // renderer can use kind-based navigability instead of substring matching.
+      this.conversation.addTypedSystemMessage(message, kind);
     }
   }
 

package/src/export/cost-utils.ts

@@ -0,0 +1,71 @@
+// ---------------------------------------------------------------------------
+// cost-utils — canonical pricing source for token cost calculations (consumed by CostTrackerPanel and share-runtime)
+// ---------------------------------------------------------------------------
+
+export interface ModelPricing {
+  input: number;
+  output: number;
+}
+
+const MODEL_PRICING: Record<string, ModelPricing> = {
+  // Free tier
+  'openrouter/free': { input: 0, output: 0 },
+
+  // InceptionLabs
+  'mercury-2':    { input: 0.50, output: 1.50 },
+  'mercury-edit': { input: 0.50, output: 1.50 },
+
+  // OpenAI
+  'gpt-5.4':              { input: 5,    output: 15 },
+  'gpt-5.3-chat-latest':  { input: 3,    output: 10 },
+  'gpt-5-mini':           { input: 0.15, output: 0.60 },
+  'gpt-5-nano':           { input: 0.05, output: 0.20 },
+  'gpt-oss-120b':         { input: 0,    output: 0 },
+
+  // Anthropic
+  'claude-opus-4-6':   { input: 15,   output: 75 },
+  'claude-sonnet-4-6': { input: 3,    output: 15 },
+  'claude-haiku-4-5':  { input: 0.80, output: 4 },
+
+  // Google
+  'gemini-3.1-pro':        { input: 1.25,  output: 5 },
+  'gemini-3-flash':        { input: 0.075, output: 0.30 },
+  'gemini-3.1-flash-lite': { input: 0.02,  output: 0.10 },
+  'gemini-2.5-pro':        { input: 1.25,  output: 5 },
+};
+
+/**
+ * getPricing — resolve USD-per-1M-token pricing for a model ID.
+ * Exact match first; then prefix/substring; falls back to zero.
+ */
+export function getPricing(modelId: string): ModelPricing {
+  if (MODEL_PRICING[modelId]) return MODEL_PRICING[modelId]!;
+  if (modelId.endsWith(':free')) return { input: 0, output: 0 };
+  for (const [key, pricing] of Object.entries(MODEL_PRICING)) {
+    if (modelId.startsWith(key) || modelId.includes(key)) return pricing;
+  }
+  return { input: 0, output: 0 };
+}
+
+/**
+ * calcSessionCost — compute total session cost in USD given raw token counters
+ * and the active model ID. Same formula used by CostTrackerPanel.onTurnComplete.
+ *
+ * inputTokens    — cumulative input tokens
+ * outputTokens   — cumulative output tokens
+ * cacheRead      — cumulative cache-read tokens
+ * cacheWrite     — cumulative cache-write tokens
+ * modelId        — registry model identifier
+ */
+export function calcSessionCost(
+  inputTokens: number,
+  outputTokens: number,
+  cacheRead: number,
+  cacheWrite: number,
+  modelId: string,
+): number {
+  const pricing = getPricing(modelId);
+  // Cache reads/writes count toward billable input side (same convention as panel)
+  const billableInput = inputTokens + cacheRead + cacheWrite;
+  return (billableInput * pricing.input + outputTokens * pricing.output) / 1_000_000;
+}

package/src/export/gist-uploader.ts

@@ -0,0 +1,136 @@
+// ---------------------------------------------------------------------------
+// gist-uploader — upload export content to a GitHub Gist
+// ---------------------------------------------------------------------------
+//
+// Architecture: UploadTarget interface with a single GistUploadTarget
+// implementation. Future targets (HTTP PUT, Pastebin, etc.) implement
+// UploadTarget without changing the caller in share-runtime.
+//
+// Token resolution:
+//   1. serviceRegistry.resolveAuth('github') — standard service registry path
+//      (configured via .goodvibes/tui/services.json with tokenKey: GITHUB_TOKEN)
+//   2. process.env.GITHUB_TOKEN fallback
+//   3. No token → honest guidance; no upload.
+//
+// Privacy: Gist is created as secret=true (unlisted, not private — anyone with
+// the URL can view it).
+// ---------------------------------------------------------------------------
+
+export type UploadResult =
+  | { ok: true; url: string }
+  | { ok: false; error: string };
+
+/**
+ * UploadTarget — interface for pluggable export upload backends.
+ * Future HTTP PUT / other targets implement this.
+ */
+export interface UploadTarget {
+  upload(content: string, filename: string): Promise<UploadResult>;
+}
+
+export interface GistUploaderOptions {
+  /**
+   * GitHub PAT with `gist` scope. If not provided the uploader will try
+   * process.env.GITHUB_TOKEN then return an error with guidance.
+   */
+  token?: string;
+  /** Description shown on the Gist page. Defaults to filename. */
+  description?: string;
+}
+
+/**
+ * resolveGithubToken — try auth header map then env var.
+ * Returns undefined when no token is available.
+ */
+export function resolveGithubToken(
+  authHeaders: Record<string, string> | null | undefined,
+): string | undefined {
+  if (authHeaders) {
+    // Service registry returns { Authorization: 'Bearer <token>' } for bearer type
+    const authHeader = authHeaders['Authorization'] ?? authHeaders['authorization'];
+    if (authHeader) {
+      const match = /^Bearer (.+)$/.exec(authHeader);
+      if (match?.[1]) return match[1];
+    }
+    // Fallback: raw token value under any key that contains 'token'
+    for (const [key, val] of Object.entries(authHeaders)) {
+      if (key.toLowerCase().includes('token') && val) return val;
+    }
+  }
+  // Env var fallback
+  const envToken = process.env['GITHUB_TOKEN'];
+  return envToken || undefined;
+}
+
+/**
+ * GistUploadTarget — uploads content to a secret (unlisted) GitHub Gist.
+ */
+export class GistUploadTarget implements UploadTarget {
+  private readonly token: string;
+  private readonly description: string;
+
+  constructor(token: string, description?: string) {
+    this.token = token;
+    this.description = description ?? 'GoodVibes session export';
+  }
+
+  async upload(content: string, filename: string): Promise<UploadResult> {
+    const body = JSON.stringify({
+      description: this.description,
+      public: false, // secret gist: unlisted, not private
+      files: {
+        [filename]: { content },
+      },
+    });
+
+    let response: Response;
+    try {
+      response = await fetch('https://api.github.com/gists', {
+        method: 'POST',
+        headers: {
+          'Accept': 'application/vnd.github+json',
+          'Authorization': `Bearer ${this.token}`,
+          'Content-Type': 'application/json',
+          'X-GitHub-Api-Version': '2022-11-28',
+        },
+        body,
+      });
+    } catch (fetchErr: unknown) {
+      const msg = fetchErr instanceof Error ? fetchErr.message : String(fetchErr);
+      return { ok: false, error: `Network error: ${msg}` };
+    }
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      return {
+        ok: false,
+        error: `GitHub API error ${response.status}: ${text.slice(0, 200)}`,
+      };
+    }
+
+    let json: unknown;
+    try {
+      json = await response.json();
+    } catch {
+      return { ok: false, error: 'GitHub API returned non-JSON response' };
+    }
+
+    const gistUrl = (json as Record<string, unknown>)['html_url'];
+    if (typeof gistUrl !== 'string') {
+      return { ok: false, error: 'GitHub API response missing html_url field' };
+    }
+
+    return { ok: true, url: gistUrl };
+  }
+}
+
+/**
+ * noTokenGuidance — message printed when no GitHub PAT is found.
+ */
+export const NO_TOKEN_GUIDANCE = [
+  'No GitHub token found for --upload.',
+  'To enable Gist upload, configure a GitHub service entry:',
+  '  /services import .goodvibes/tui/services.json  (if already configured)',
+  'Or set the GITHUB_TOKEN environment variable to a PAT with the `gist` scope.',
+  'Token is sent to api.github.com only. Gists are secret (unlisted, not private).',
+].join('\n');

package/src/input/command-registry.ts

@@ -120,6 +120,16 @@ export interface CommandShellUiOpeners {
   openKnowledgePanel?: () => void;
   openRemotePanel?: () => void;
   openSubscriptionPanel?: () => void;
+  /**
+   * Open the LocalAuthPanel in masked-password-entry mode for the given
+   * operation and username. The panel captures keystrokes into a private
+   * buffer; no plaintext password is ever stored in input history, transcript,
+   * logs, or recovery files.
+   */
+  openLocalAuthMaskedEntry?: (
+    kind: 'add-user' | 'rotate-password',
+    username: string,
+  ) => void;
 }
 
 export interface CommandSessionServices {
@@ -233,8 +243,28 @@ export class CommandRegistry {
   private commands = new Map<string, SlashCommand>();
   private aliasIndex = new Map<string, SlashCommand>();
 
-  /** Register a command. Also indexes all aliases for O(1) lookup. */
+  /**
+   * Register a command. Also indexes all aliases for O(1) lookup.
+   * Throws if the primary name or any alias collides with an existing
+   * registration — silent last-write-wins previously shadowed whole
+   * commands, so collisions must fail fast at startup (and are caught
+   * statically by the alias lint test).
+   */
   register(command: SlashCommand): void {
+    const existingByName = this.commands.get(command.name) ?? this.aliasIndex.get(command.name);
+    if (existingByName) {
+      throw new Error(
+        `Command registration collision: "${command.name}" is already registered by /${existingByName.name}.`,
+      );
+    }
+    for (const alias of command.aliases ?? []) {
+      const holder = this.commands.get(alias) ?? this.aliasIndex.get(alias);
+      if (holder) {
+        throw new Error(
+          `Command alias collision: "${alias}" on /${command.name} is already registered by /${holder.name}.`,
+        );
+      }
+    }
     this.commands.set(command.name, command);
     for (const alias of command.aliases ?? []) {
       this.aliasIndex.set(alias, command);

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

@@ -196,9 +196,9 @@ export function registerControlRoomRuntimeCommands(registry: CommandRegistry): v
   });
 
   registry.register({
-    name: 'knowledge',
-    aliases: ['know'],
-    description: 'Inspect durable project knowledge, risks, runbooks, and architecture notes',
+    name: 'project-memory',
+    aliases: ['pmem'],
+    description: 'Inspect durable project memory: risks, runbooks, and architecture notes',
     usage: '[open | queue [limit] | explain <task...> [--scope <path> ...]]',
     handler(args, ctx) {
       const subcommand = (args[0] ?? 'open').toLowerCase();
@@ -237,7 +237,7 @@ export function registerControlRoomRuntimeCommands(registry: CommandRegistry): v
         });
         const task = taskTokens.join(' ').trim();
         if (!task) {
-          ctx.print('Usage: /knowledge explain <task...> [--scope <path> ...]');
+          ctx.print('Usage: /project-memory explain <task...> [--scope <path> ...]');
           return;
         }
         const injections = selectKnowledgeForTask(memory, task, scopeValues);
@@ -249,7 +249,7 @@ export function registerControlRoomRuntimeCommands(registry: CommandRegistry): v
         ctx.openKnowledgePanel();
         return;
       }
-      ctx.print(`Unknown knowledge subcommand: ${subcommand}`);
+      ctx.print(`Unknown project-memory subcommand: ${subcommand}`);
     },
   });
 }

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

@@ -222,7 +222,7 @@ export function registerExperienceRuntimeCommands(registry: CommandRegistry): vo
 
   registry.register({
     name: 'voice',
-    description: 'Review voice posture and package portable voice-surface metadata',
+    description: 'Review or toggle always-speak mode (same switch as /tts on|off) and package portable voice metadata',
     usage: '[review|enable|disable|bundle export <path>|bundle inspect <path>]',
     handler(args, ctx) {
       const shellPaths = requireShellPaths(ctx);
@@ -231,8 +231,9 @@ export function registerExperienceRuntimeCommands(registry: CommandRegistry): vo
         const enabled = Boolean(ctx.platform.configManager.get('ui.voiceEnabled') ?? false);
         ctx.print([
           'Voice Review',
-          `  enabled: ${enabled ? 'yes' : 'no'}`,
-          '  posture: optional local companion surface; disabled by default',
+          `  always-speak: ${enabled ? 'on' : 'off'}`,
+          '  config key: ui.voiceEnabled (same as /tts on|off)',
+          '  posture: optional local TTS output; disabled by default',
           '  note: voice remains an optional operator convenience, not a required SaaS dependency',
         ].join('\n'));
         return;
@@ -240,7 +241,7 @@ export function registerExperienceRuntimeCommands(registry: CommandRegistry): vo
       if (sub === 'enable' || sub === 'disable') {
         const next = sub === 'enable';
         ctx.platform.configManager.setDynamic('ui.voiceEnabled', next);
-        ctx.print(`Voice surface ${next ? 'enabled' : 'disabled'} for this runtime.`);
+        ctx.print(`Always-speak mode ${next ? 'enabled' : 'disabled'}. ${next ? 'Every submitted turn will be played through live TTS.' : 'Use /tts <prompt> to speak individual turns.'}`);
         return;
       }
       if (sub === 'bundle') {

package/src/input/commands/knowledge.ts

@@ -131,7 +131,7 @@ function renderKnowledgeAskResult(result: KnowledgeAskResult): string {
 
 export const knowledgeCommand: SlashCommand = {
   name: 'knowledge',
-  aliases: ['know', 'kb'],
+  aliases: ['know'],
   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',

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

@@ -17,11 +17,22 @@ export function handleLocalAuthCommand(args: string[], ctx: CommandContext): voi
   if (sub === 'add-user') {
     const username = args[1];
     const password = args[2];
-    const roles = args[3]?.split(',').map((value) => value.trim()).filter(Boolean) ?? ['admin'];
-    if (!username || !password) {
-      ctx.print('Usage: /auth local add-user <username> <password> [roles]');
+    if (!username) {
+      ctx.print('Usage: /auth local add-user <username> <password> [roles]\nTip: invoke without a password to use the masked panel: /auth local add-user <username>');
+      return;
+    }
+    if (!password) {
+      // No password supplied — open masked-entry mode on the LocalAuthPanel.
+      if (ctx.openLocalAuthMaskedEntry) {
+        ctx.openLocalAuthMaskedEntry('add-user', username);
+      } else {
+        ctx.print('Masked entry unavailable in this context. Use: /auth local add-user <username> <password>');
+      }
       return;
     }
+    // Password supplied as argv: warn that the history entry has been scrubbed.
+    ctx.print('Warning: passwords passed as command arguments are scrubbed from history, but may appear in shell scrollback. The masked entry is preferred: /auth local add-user <username>');
+    const roles = args[3]?.split(',').map((value) => value.trim()).filter(Boolean) ?? ['admin'];
     try {
       const added = auth.addUser(username, password, roles);
       ctx.print(`Added local auth user ${added.username} (${formatRoles(added.roles)}).`);
@@ -49,10 +60,21 @@ export function handleLocalAuthCommand(args: string[], ctx: CommandContext): voi
   if (sub === 'rotate-password') {
     const username = args[1];
     const password = args[2];
-    if (!username || !password) {
-      ctx.print('Usage: /auth local rotate-password <username> <password>');
+    if (!username) {
+      ctx.print('Usage: /auth local rotate-password <username> <password>\nTip: invoke without a password to use the masked panel: /auth local rotate-password <username>');
+      return;
+    }
+    if (!password) {
+      // No password supplied — open masked-entry mode on the LocalAuthPanel.
+      if (ctx.openLocalAuthMaskedEntry) {
+        ctx.openLocalAuthMaskedEntry('rotate-password', username);
+      } else {
+        ctx.print('Masked entry unavailable in this context. Use: /auth local rotate-password <username> <password>');
+      }
       return;
     }
+    // Password supplied as argv: warn that the history entry has been scrubbed.
+    ctx.print('Warning: passwords passed as command arguments are scrubbed from history, but may appear in shell scrollback. The masked entry is preferred: /auth local rotate-password <username>');
     try {
       auth.rotatePassword(username, password);
       ctx.print(`Rotated password for ${username}. Existing sessions were revoked.`);

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

@@ -1,5 +1,6 @@
 import { dirname, join } from 'path';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { atomicWriteFileSync } from '../../config/atomic-write.ts';
 import type { CommandRegistry } from '../command-registry.ts';
 import type { ConfigKey } from '../../config/index.ts';
 import { CONFIG_SCHEMA } from '../../config/index.ts';
@@ -204,18 +205,15 @@ export function registerLocalSetupCommands(registry: CommandRegistry): void {
             }
             if (bundle.services) {
               const servicesPath = getShellPaths().resolveProjectPath('tui', 'services.json');
-              mkdirSync(dirname(servicesPath), { recursive: true });
-              writeFileSync(servicesPath, JSON.stringify(bundle.services, null, 2) + '\n', 'utf-8');
+              atomicWriteFileSync(servicesPath, JSON.stringify(bundle.services, null, 2) + '\n', { mkdirp: true });
             }
             if (bundle.ecosystem?.plugins) {
               const pluginsPath = getShellPaths().resolveProjectPath('tui', 'ecosystem', 'plugins.json');
-              mkdirSync(dirname(pluginsPath), { recursive: true });
-              writeFileSync(pluginsPath, JSON.stringify(bundle.ecosystem.plugins, null, 2) + '\n', 'utf-8');
+              atomicWriteFileSync(pluginsPath, JSON.stringify(bundle.ecosystem.plugins, null, 2) + '\n', { mkdirp: true });
             }
             if (bundle.ecosystem?.skills) {
               const skillsPath = getShellPaths().resolveProjectPath('tui', 'ecosystem', 'skills.json');
-              mkdirSync(dirname(skillsPath), { recursive: true });
-              writeFileSync(skillsPath, JSON.stringify(bundle.ecosystem.skills, null, 2) + '\n', 'utf-8');
+              atomicWriteFileSync(skillsPath, JSON.stringify(bundle.ecosystem.skills, null, 2) + '\n', { mkdirp: true });
             }
             ctx.print(`Imported setup transfer bundle from ${targetPath}`);
           } catch (error) {