@ours.network/install 0.13.0 → 0.14.1

package/README.md

@@ -1,8 +1,8 @@
 # @ours.network/install — `ours-install`
 
 The **unified ours.network stack installer**. ONE guided ~3-minute flow that installs the WHOLE
-stack for someone who already has Claude Code and/or Codex, then hands back a single copy-paste
-prompt to finish setup conversationally.
+stack for someone who already has Claude Code, Codex, and/or Hermes, safely offers optional
+voice-message transcription, then hands back a single copy-paste prompt for remaining setup.
 
 ## Install
 
@@ -43,7 +43,7 @@ dependency on the things it installs): an ASCII banner, tasteful colour (degrade
    answers `--version` promptly. A shell alias / hanging wrapper is **never called** (that would
    hang the run) — it's reported plainly with a fix, and a manual-install path is always offered.
    If neither harness exists it says so and exits.
-2. **Config-first** (first install only) — the only two settings the user ever types, up front:
+2. **Config-first** (first install only) — the daemon's two base settings, up front:
    the **broker** (end-to-end encrypted; the broker never sees message content — almost everyone
    just presses Enter) and the **port** (probes `3050`; only asks if it's busy; never hands out
    `3051`, reserved for the Telegram connector). Applied once, then the stack is built with it.
@@ -51,6 +51,10 @@ dependency on the things it installs): an ASCII banner, tasteful colour (degrade
    **Continue?** — never a start-twice-then-ask, never a silent failure:
    - **1/4 ours core (the daemon)** — write config → install/start ONCE → boot service. On a
      re-run it reuses the running config (no re-ask) and only updates when you say yes.
+     After core readiness, the installer checks `ours-mcp voice-status --json`. Complete
+     voice setup is kept without prompting. Missing/incomplete setup is offered on every
+     interactive rerun: provider, model/endpoint where required, and a hidden API-key prompt.
+     The secret is written atomically to mode-`0600` config; a failed daemon reload rolls back.
    - **2/4 harness plugins** — the installer **drives the plugin CLIs itself**
      (`claude plugin marketplace add …` + `claude plugin install ours@ours.network`;
      `codex plugin marketplace add …` + `codex plugin add ours@ours-codex-marketplace`). Choosing
@@ -64,7 +68,7 @@ dependency on the things it installs): an ASCII banner, tasteful colour (degrade
    copy-paste prompt** (root identity + fleet + Telegram) with the steps for any skipped/failed
    component dropped out. Copied to the clipboard where supported.
 
-The root identity is **deferred to the hand-off** — zero identity typing during install. Because
+The human identity is created idempotently after the daemon becomes reachable. Because
 `curl … | bash` gives the script its input over the pipe, every prompt is read from the
 controlling terminal (`/dev/tty`), so the flow still works piped.
 
@@ -80,6 +84,10 @@ exactly the commands it *would* run (npm installs, `ours-mcp start`, plugin adds
 init`, service installs) without executing them. That is the safe way to preview the flow on a
 machine you don't want to touch, and how the integration tests drive it.
 
+Non-interactive runs never prompt for or synthesize voice credentials. Supply a complete
+`OURS_STT_*` environment configuration yourself, or rerun interactively later; missing setup
+is reported and left unchanged.
+
 | var | meaning |
 |---|---|
 | `OURS_ASSUME_YES` | accept every default, never prompt (implies no tty needed) |
@@ -132,5 +140,5 @@ OURS_UNINSTALL_DAEMON=yes \
   published components.
 - **Idempotent + safe to re-run.** A re-run adds a skipped piece, re-points the plugins, or (only
   when you say yes) updates a component; an already-current daemon is left untouched, its running
-  port reused everywhere. Deep configuration (identities, bot tokens, fleet roles) is intentionally
-  **not** done here — it's the copy-paste hand-off's job.
+  port and complete voice setup are reused everywhere. Bot tokens and fleet roles remain in the
+  copy-paste hand-off; provider keys never enter that prompt or agent chat.

package/install.mjs

@@ -6,27 +6,30 @@
 // Codex / Hermes) + ours-fleet + the Telegram connector — for someone who ALREADY has Claude,
 // Codex, and/or Hermes.
 // Its whole job: install the stack cleanly, then hand back ONE copy-paste prompt the user drops
-// into their agent to finish all real configuration conversationally. No tokens, no port editing,
-// no config files. See packages/installer/README.md and the UX spec for the full contract.
+// into their agent to finish remaining configuration conversationally. Voice API credentials are
+// the one guided secret flow: interactive, masked, optional, and written atomically with mode 0600.
+// See packages/installer/README.md and the UX spec for the full contract.
 //
 // Design pillars (from the spec): config FIRST then act once; consent-first (Enter = no change);
 // slow, per-step "✓ … no problems" + Continue?; never silently broken; idempotent + safe re-run;
-// alias-safety / never-hang; deep config deferred to the copy-paste hand-off.
+// alias-safety / never-hang; most deep config deferred to the copy-paste hand-off.
 //
 // SAFETY: every side-effecting action goes through act(); with OURS_INSTALL_DRY_RUN=1 nothing is
 // installed/started/restarted — it prints exactly what it WOULD do. That is the safe way to walk
 // the whole flow on a machine you don't want to touch (and how the tests drive it).
 import { spawn, spawnSync } from 'node:child_process';
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { homedir, userInfo, platform as osPlatform, release as osRelease } from 'node:os';
-import { join, dirname } from 'node:path';
+import { join } from 'node:path';
 import { banner, heading, ok, info, warn, c, box, withSpinner, openTty, makeWriter, closeSync } from './lib/ui.mjs';
-import { askLine, askYesNo, isCancel } from './lib/prompt.mjs';
+import { askLine, askSecret, askYesNo, isCancel } from './lib/prompt.mjs';
 import {
   suggestPort, parsePort, validateBroker, mergeConfig, parseVersion, parseStatus,
   detectPlatform, classifyHarnessProbe, buildHandoffPrompt,
+  voiceSetupStatus, validateVoiceSecret, redactSensitive, VOICE_PROVIDERS,
   DEFAULT_PORT, resolveChannel, pkgSpec,
 } from './lib/logic.mjs';
+import { atomicWriteConfig, transactionalConfigUpdate } from './lib/config.mjs';
 
 const NPM = process.env.OURS_NPM || 'npm';
 // Release channel: OURS_CHANNEL=nightly installs @nightly for mcp/tg-connector/plugin
@@ -37,12 +40,6 @@ let DRY = !!process.env.OURS_INSTALL_DRY_RUN;
 const SELFHOST_URL = 'ours.network';
 const CLAUDE_MARKET = 'adapt-toolkit/ours-claude-marketplace';
 const CODEX_MARKET = 'adapt-toolkit/ours-codex-marketplace';
-// The ours-fleet HARNESS PLUGINS (separate from the `ours` plugin) — these are what actually give
-// Claude Code / Codex the fleet skill. Claude: plugin "fleet" in the ours.network marketplace
-// (@ours.network/fleet-claude-code). Codex: plugin "ours-fleet" in the ours-codex-marketplace
-// (@ours.network/fleet-codex).
-const CLAUDE_FLEET_PLUGIN = 'fleet@ours.network';
-const CODEX_FLEET_PLUGIN = 'ours-fleet@ours-codex-marketplace';
 
 const sink = (s) => process.stdout.write(s);
 const line = (s = '') => sink(`${s}\n`);
@@ -103,11 +100,21 @@ function configPath() { return process.env.OURS_CONFIG || join(homedir(), '.ours
 function readConfigObject() { try { return JSON.parse(readFileSync(configPath(), 'utf8')); } catch { return {}; } }
 function writeConfigPatch(patch) {
   const p = configPath();
-  mkdirSync(dirname(p), { recursive: true });
-  writeFileSync(p, mergeConfig(readConfigObject(), patch));
+  atomicWriteConfig(p, mergeConfig(readConfigObject(), patch));
   return p;
 }
 
+function daemonVoiceCapability() {
+  const r = run('ours-mcp', ['voice-status', '--json'], { capture: true, timeout: 6000 });
+  if (!r.ok) return null;
+  try {
+    const parsed = JSON.parse(r.out.trim());
+    return typeof parsed?.ready === 'boolean' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
 // Block the thread for `ms` without a subprocess — used for the brief daemon-reachability wait
 // before creating the human identity (a freshly-started daemon needs a moment to bind its port).
 function sleepMs(ms) {
@@ -370,6 +377,130 @@ async function main() {
   }
   cont();
 
+  // ============================================================================================
+  // Voice-message transcription — capability-based and safe to re-run. A complete setup is kept
+  // without prompting. An incomplete setup is offered every interactive run, including updates.
+  // Headless/CI never blocks or invents a provider/key. Secrets are read without echo and the
+  // config transaction is atomic + 0600; a failed daemon restart restores the previous file.
+  // ============================================================================================
+  if (summary.some((r) => r.key === 'core' && (r.state === 'installed' || r.state === 'current'))) {
+    line(heading('Voice messages'));
+    const cfgBefore = readConfigObject();
+    const probed = daemonVoiceCapability();
+    const localStatus = voiceSetupStatus(cfgBefore, process.env);
+    const voiceStatus = probed ?? localStatus;
+    if (voiceStatus.ready) {
+      line(ok(`Voice transcription is configured (${voiceStatus.provider}). API key: configured, never displayed.`));
+      record({ key: 'voice', label: 'Voice transcription', state: 'current', note: voiceStatus.provider });
+      cont(false);
+    } else if (!interactive) {
+      line(info('Voice transcription is not configured. Non-interactive mode leaves it unchanged.'));
+      line(info('Run ours-install in a terminal to enter the provider key with masked input.'));
+      record({ key: 'voice', label: 'Voice transcription', state: 'skipped', note: 'interactive setup available on re-run' });
+      cont(false);
+    } else {
+      line(info('Voice notes can be transcribed by a provider you choose. Audio is sent to that'));
+      line(info('provider; use a self-hosted endpoint if it must stay local. The API key is masked.'));
+      const configure = yes('  Set up voice transcription now?', true);
+      if (!configure) {
+        line(info('skipped — this will be offered again on the next installer run.'));
+        record({ key: 'voice', label: 'Voice transcription', state: 'skipped', note: 'declined; offered again on re-run' });
+        cont(false);
+      } else {
+        const fileVoice = cfgBefore?.stt && typeof cfgBefore.stt === 'object' ? cfgBefore.stt : {};
+        const providerDefault = String(process.env.OURS_STT_PROVIDER || fileVoice.provider || '').trim().toLowerCase();
+        const provider = ask(
+          `  Provider (${VOICE_PROVIDERS.join(' / ')})${providerDefault ? ` [${providerDefault}]` : ''}: `,
+          providerDefault,
+        ).trim().toLowerCase();
+        let setupError = '';
+        if (!VOICE_PROVIDERS.includes(provider)) setupError = `choose one of: ${VOICE_PROVIDERS.join(', ')}`;
+
+        let model = String(process.env.OURS_STT_MODEL || fileVoice.model || '').trim();
+        let baseUrl = String(process.env.OURS_STT_BASE_URL || fileVoice.baseUrl || '').trim();
+        let customUrl = String(fileVoice.custom?.url || '').trim();
+        if (!setupError && provider === 'openai-compatible') {
+          baseUrl = ask(`  Provider /v1 base URL${baseUrl ? ` [${baseUrl}]` : ''}: `, baseUrl).trim();
+          model = ask(`  Model name (sent verbatim)${model ? ` [${model}]` : ''}: `, model).trim();
+        } else if (!setupError && provider === 'elevenlabs') {
+          model = ask(`  ElevenLabs model id${model ? ` [${model}]` : ''}: `, model).trim();
+          baseUrl = ask(`  Custom base URL (Enter for provider default)${baseUrl ? ` [${baseUrl}]` : ''}: `, baseUrl).trim();
+        } else if (!setupError && provider === 'deepgram') {
+          model = ask(`  Model (optional; Enter for provider default)${model ? ` [${model}]` : ''}: `, model).trim();
+          baseUrl = ask(`  Custom base URL (optional)${baseUrl ? ` [${baseUrl}]` : ''}: `, baseUrl).trim();
+        } else if (!setupError && provider === 'custom') {
+          customUrl = ask(`  Full transcription endpoint URL${customUrl ? ` [${customUrl}]` : ''}: `, customUrl).trim();
+          model = ask(`  Model (optional unless URL contains {model})${model ? ` [${model}]` : ''}: `, model).trim();
+        }
+
+        const envHasKey = !!process.env.OURS_STT_API_KEY?.trim();
+        let keyToPersist = String(fileVoice.apiKey || '').trim();
+        if (!setupError && !envHasKey) {
+          const keyPrompt = keyToPersist
+            ? '  Provider API key [configured; Enter keeps it]: '
+            : '  Provider API key (input hidden): ';
+          const entered = askSecret(write, ttyFd, keyPrompt, keyToPersist);
+          if (entered === null) setupError = 'secure hidden input is unavailable on this terminal';
+          else {
+            const valid = validateVoiceSecret(entered);
+            if (!valid.ok) setupError = valid.reason;
+            else keyToPersist = valid.value;
+          }
+        }
+
+        const nextStt = {
+          ...fileVoice,
+          provider,
+          ...(keyToPersist ? { apiKey: keyToPersist } : {}),
+          ...(model ? { model } : {}),
+          ...(baseUrl ? { baseUrl } : {}),
+          ...(provider === 'custom' && customUrl
+            ? { custom: { ...(fileVoice.custom ?? {}), url: customUrl } }
+            : {}),
+        };
+        const intended = voiceSetupStatus({ ...cfgBefore, stt: nextStt }, process.env);
+        if (!setupError && !intended.ready) setupError = intended.reason;
+
+        if (setupError) {
+          line(warn(`Voice setup was not saved: ${redactSensitive(setupError, [keyToPersist])}.`));
+          line(info('No existing configuration was changed; re-run ours-install to try again.'));
+          record({ key: 'voice', label: 'Voice transcription', state: 'failed', note: 'incomplete setup; config unchanged' });
+          cont();
+        } else if (DRY) {
+          line('  ' + c.dim(`[dry-run] would: atomically update ${configPath()} (mode 0600) and restart ours-mcp`));
+          line(ok(`Voice transcription would be configured (${provider}); API key stays hidden.`));
+          record({ key: 'voice', label: 'Voice transcription', state: 'installed', note: `${provider} (dry-run)` });
+          cont();
+        } else {
+          const updated = transactionalConfigUpdate(
+            configPath(),
+            mergeConfig(cfgBefore, { stt: nextStt }),
+            () => {
+              const r = run('ours-mcp', ['restart'], { capture: true });
+              if (!r.ok) return { ok: false, error: r.err || r.out };
+              const verified = daemonVoiceCapability();
+              return verified && !verified.ready
+                ? { ok: false, error: verified.reason || 'voice capability remained incomplete after restart' }
+                : { ok: true };
+            },
+          );
+          if (!updated.ok && updated.stage === 'write') {
+            line(warn(`Could not save voice setup: ${redactSensitive(updated.error instanceof Error ? updated.error.message : String(updated.error), [keyToPersist])}.`));
+            line(info('The prior config is intact; no restart was attempted.'));
+            record({ key: 'voice', label: 'Voice transcription', state: 'failed', note: 'config write failed; prior config intact' });
+          } else if (!updated.ok) {
+            line(warn(`Daemon restart failed; ${updated.rolledBack ? 'restored the prior config' : 'automatic rollback also failed — inspect the config before restarting'}.`));
+            record({ key: 'voice', label: 'Voice transcription', state: 'failed', note: updated.rolledBack ? 'restart failed; rolled back' : 'restart and rollback failed' });
+          } else {
+            line(ok(`Voice transcription configured (${provider}) and daemon restarted. API key saved in mode-0600 config.`));
+            record({ key: 'voice', label: 'Voice transcription', state: 'installed', note: provider });
+          }
+          cont();
+        }
+      }
+    }
+  }
+
   // ============================================================================================
   // Human identity — created DURING install, right after the daemon is confirmed reachable (the
   // owner change that supersedes "defer to the hand-off"). `ours-mcp create-root` is the internal
@@ -501,34 +632,16 @@ async function main() {
     const init = await act('ours-fleet init (one-time host setup: units, dirs, linger)', async () => run('ours-fleet', ['init']));
     if (!init.ok) line(warn(`ours-fleet host setup didn't finish — retry '${c.cyan('ours-fleet init')}'.`));
 
-    // Install the fleet HARNESS PLUGIN into each real+safe harness — the piece that actually gives
-    // Claude Code / Codex the fleet skill. Same drive-the-CLI, alias-safe, loud-on-failure pattern
-    // as Step 2; never dead-ends. (The `ours` plugin does NOT bundle this — it's a separate plugin.)
-    const fleetIn = [];
-    for (const h of harnesses) {
-      if (h.status === 'absent') continue;
-      if (h.name === 'claude') {
-        if (h.status !== 'ok') { manualClaudeFleet(h); continue; }
-        await act(`claude plugin marketplace add ${CLAUDE_MARKET}`, async () => run('claude', ['plugin', 'marketplace', 'add', CLAUDE_MARKET], { capture: true }));
-        const r = await act(`claude plugin install ${CLAUDE_FLEET_PLUGIN}`, async () => run('claude', ['plugin', 'install', CLAUDE_FLEET_PLUGIN], { capture: true }));
-        if (r.ok) { line(ok('Claude Code fleet plugin installed — you can spawn agents from Claude Code. No problems.')); fleetIn.push('Claude Code'); }
-        else failClaudeFleet();
-      } else if (h.name === 'codex') {
-        if (h.status !== 'ok') { manualCodexFleet(h); continue; }
-        await act(`codex plugin marketplace add ${CODEX_MARKET}`, async () => run('codex', ['plugin', 'marketplace', 'add', CODEX_MARKET], { capture: true }));
-        const r = await act(`codex plugin add ${CODEX_FLEET_PLUGIN}`, async () => run('codex', ['plugin', 'add', CODEX_FLEET_PLUGIN], { capture: true }));
-        if (r.ok) { line(ok('Codex fleet plugin installed — you can spawn agents from Codex. No problems.')); fleetIn.push('Codex'); }
-        else failCodexFleet();
-      }
+    if (init.ok) {
+      line(ok('ours-fleet ready — the core ours plugin discovers every option through `ours-fleet docs`. No problems.'));
     }
-    // Only claim the skill is present where the fleet plugin actually installed.
-    if (init.ok && fleetIn.length) line(ok(`ours-fleet ready — ${fleetIn.join(' + ')} now know the fleet skill. No problems.`));
-    else if (init.ok) line(info('ours-fleet CLI is installed; add the fleet plugin to your harness with the commands above.'));
-    // Fleet plugins target Claude Code + Codex only (Hermes has none) — so "no fleet-capable harness
-    // to install into" means every claude/codex is absent, NOT every harness (Hermes doesn't count).
-    const fleetCapableAbsent = harnesses.filter((h) => h.name === 'claude' || h.name === 'codex').every((h) => h.status === 'absent');
-    const fleetOk = init.ok && (fleetIn.length > 0 || fleetCapableAbsent);
-    record({ key: 'fleet', label: 'ours-fleet', state: fleetOk ? 'installed' : 'failed', version: globalVersion('@ours.network/fleet'), note: fleetIn.length ? fleetIn.join(' + ') : (init.ok ? 'CLI only — add plugin manually' : 'ours-fleet init failed') });
+    record({
+      key: 'fleet',
+      label: 'ours-fleet',
+      state: init.ok ? 'installed' : 'failed',
+      version: globalVersion('@ours.network/fleet'),
+      note: init.ok ? 'CLI + core-plugin discovery' : 'ours-fleet init failed',
+    });
   } else {
     line(info('skipped cleanly — re-run ours-install any time to add it.'));
     record({ key: 'fleet', label: 'ours-fleet', state: 'skipped' });
@@ -611,38 +724,6 @@ function failHermes() {
   line('    ' + c.cyan('ours-hermes-install'));
   line(info('Your daemon and other steps are intact. Continuing.'));
 }
-// --- fleet HARNESS PLUGIN never-dead-end messaging ---------------------------------------------
-function manualClaudeFleet(h) {
-  line(warn(h.status === 'alias'
-    ? '"claude" is installed as an alias, so I can\'t add the fleet plugin for you.'
-    : 'Couldn\'t safely drive "claude" to add the fleet plugin.'));
-  line(info('Add it yourself — inside Claude Code, run these two:'));
-  line('    ' + c.cyan(`/plugin marketplace add ${CLAUDE_MARKET}`));
-  line('    ' + c.cyan('/plugin install fleet'));
-}
-function failClaudeFleet() {
-  line(warn('Couldn\'t install the Claude Code fleet plugin automatically.'));
-  line(info('Install it by hand — inside Claude Code, run these two, then re-run ours-install:'));
-  line('    ' + c.cyan(`/plugin marketplace add ${CLAUDE_MARKET}`));
-  line('    ' + c.cyan('/plugin install fleet'));
-  line(info('Your daemon and other steps are intact. Continuing.'));
-}
-function manualCodexFleet(h) {
-  line(warn(h.status === 'alias'
-    ? '"codex" is installed as an alias, so I can\'t add the fleet plugin for you.'
-    : 'Couldn\'t safely drive "codex" to add the fleet plugin.'));
-  line(info('Add it yourself — run these two in your terminal:'));
-  line('    ' + c.cyan(`codex plugin marketplace add ${CODEX_MARKET}`));
-  line('    ' + c.cyan(`codex plugin add ${CODEX_FLEET_PLUGIN}`));
-}
-function failCodexFleet() {
-  line(warn('Couldn\'t install the Codex fleet plugin automatically.'));
-  line(info('Install it by hand — run these two, then re-run ours-install:'));
-  line('    ' + c.cyan(`codex plugin marketplace add ${CODEX_MARKET}`));
-  line('    ' + c.cyan(`codex plugin add ${CODEX_FLEET_PLUGIN}`));
-  line(info('Your daemon and other steps are intact. Continuing.'));
-}
-
 // --- final summary + copy-paste hand-off -------------------------------------------------------
 function endScreen({ ttyFd, summary, chosenPort, chosenBroker }) {
   line('');

package/lib/config.mjs

@@ -0,0 +1,65 @@
+import {
+  chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+export function snapshotConfig(path) {
+  if (!existsSync(path)) return { exists: false, text: '', mode: 0o600 };
+  return {
+    exists: true,
+    text: readFileSync(path, 'utf8'),
+    mode: statSync(path).mode & 0o777,
+  };
+}
+
+// Write beside the destination and rename only after a complete write. A failure
+// leaves the old config byte-for-byte intact. The injectable rename seam is for failure tests.
+export function atomicWriteConfig(path, text, { rename = renameSync } = {}) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync(tmp, text, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    chmodSync(tmp, 0o600);
+    rename(tmp, path);
+    chmodSync(path, 0o600);
+  } catch (error) {
+    try { unlinkSync(tmp); } catch { /* absent or already renamed */ }
+    throw error;
+  }
+  return path;
+}
+
+export function restoreConfig(path, snapshot) {
+  if (snapshot.exists) {
+    atomicWriteConfig(path, snapshot.text);
+    // Restore the pre-transaction permissions. Normal successful secret writes always use 0600.
+    chmodSync(path, snapshot.mode);
+  } else {
+    try { unlinkSync(path); } catch { /* already absent */ }
+  }
+}
+
+// Apply a config and validate/reload it as one transaction. If the apply callback fails, restore
+// the exact previous bytes and invoke it once more to reload the old configuration.
+export function transactionalConfigUpdate(path, text, apply) {
+  const before = snapshotConfig(path);
+  try {
+    atomicWriteConfig(path, text);
+  } catch (error) {
+    return { ok: false, stage: 'write', rolledBack: true, error };
+  }
+  let applied;
+  try {
+    applied = apply();
+  } catch (error) {
+    applied = { ok: false, error };
+  }
+  if (applied?.ok) return { ok: true, stage: 'apply', rolledBack: false };
+  try {
+    restoreConfig(path, before);
+    apply();
+    return { ok: false, stage: 'apply', rolledBack: true, error: applied?.error };
+  } catch (error) {
+    return { ok: false, stage: 'rollback', rolledBack: false, error };
+  }
+}

package/lib/logic.mjs

@@ -111,6 +111,89 @@ export function mergeConfig(existing, patch) {
   return JSON.stringify(out, null, 2) + '\n';
 }
 
+export const VOICE_PROVIDERS = ['openai-compatible', 'elevenlabs', 'deepgram', 'custom'];
+
+// Resolve only the STT fields the daemon itself accepts. Environment values override
+// config.json field-by-field, matching packages/core/src/config.ts. The returned object
+// may contain a secret, so callers must never print or serialize it into diagnostics.
+export function effectiveVoiceConfig(config = {}, env = {}) {
+  const file = config?.stt && typeof config.stt === 'object' ? config.stt : {};
+  const out = { ...file };
+  const envFields = {
+    provider: env.OURS_STT_PROVIDER,
+    apiKey: env.OURS_STT_API_KEY,
+    model: env.OURS_STT_MODEL,
+    baseUrl: env.OURS_STT_BASE_URL,
+    language: env.OURS_STT_LANGUAGE,
+  };
+  for (const [key, raw] of Object.entries(envFields)) {
+    if (typeof raw === 'string' && raw.trim()) out[key] = raw.trim();
+  }
+  return out;
+}
+
+// Capability/readiness check, deliberately based on required fields rather than a package
+// version. Reasons contain field names only — never secret values.
+export function voiceSetupStatus(config = {}, env = {}) {
+  const stt = effectiveVoiceConfig(config, env);
+  const provider = String(stt.provider || '').trim().toLowerCase();
+  if (!provider) return { ready: false, provider: '', reason: 'no voice provider configured', missing: ['provider'] };
+  if (!VOICE_PROVIDERS.includes(provider)) {
+    return { ready: false, provider, reason: `unsupported voice provider "${provider}"`, missing: ['provider'] };
+  }
+  if (!String(stt.apiKey || '').trim()) {
+    return { ready: false, provider, reason: `voice provider "${provider}" is missing its API key`, missing: ['apiKey'] };
+  }
+  if (provider === 'openai-compatible') {
+    const missing = [];
+    if (!String(stt.baseUrl || '').trim()) missing.push('baseUrl');
+    if (!String(stt.model || '').trim()) missing.push('model');
+    if (missing.length) return { ready: false, provider, reason: `openai-compatible voice setup is missing ${missing.join(' and ')}`, missing };
+  }
+  if (provider === 'elevenlabs' && !String(stt.model || '').trim()) {
+    return { ready: false, provider, reason: 'elevenlabs voice setup is missing model', missing: ['model'] };
+  }
+  if (provider === 'custom') {
+    if (!String(stt.custom?.url || '').trim()) {
+      return { ready: false, provider, reason: 'custom voice setup is missing custom.url', missing: ['custom.url'] };
+    }
+    const wantsModel = stt.custom.url.includes('{model}')
+      || (stt.custom.modelField !== undefined && stt.custom.modelField !== '');
+    if (wantsModel && !String(stt.model || '').trim()) {
+      return { ready: false, provider, reason: 'custom voice setup references a model but model is missing', missing: ['model'] };
+    }
+  }
+  return {
+    ready: true,
+    provider,
+    reason: 'voice transcription is configured',
+    missing: [],
+    keySource: typeof env.OURS_STT_API_KEY === 'string' && env.OURS_STT_API_KEY.trim() ? 'environment' : 'config',
+  };
+}
+
+// Provider keys have different shapes, so validation is intentionally conservative: reject
+// empty, tiny, whitespace-containing, or control-character input without assuming a vendor prefix.
+export function validateVoiceSecret(input) {
+  const value = String(input || '').trim();
+  if (value.length < 8) return { ok: false, reason: 'API key must contain at least 8 characters' };
+  if (/[\s\x00-\x1f\x7f]/.test(value)) return { ok: false, reason: 'API key must not contain whitespace or control characters' };
+  return { ok: true, value };
+}
+
+// Last-resort diagnostic scrubber. Code should avoid putting secrets into errors in the first
+// place; this protects unexpected provider/tool errors before they reach a terminal or log.
+export function redactSensitive(text, secrets = []) {
+  let out = String(text ?? '');
+  for (const raw of secrets) {
+    const secret = String(raw || '');
+    if (secret) out = out.split(secret).join('[redacted]');
+  }
+  return out
+    .replace(/("(?:apiKey|apiToken|token)"\s*:\s*")[^"]*(")/gi, '$1[redacted]$2')
+    .replace(/((?:api[_ -]?key|token)\s*[=:]\s*)\S+/gi, '$1[redacted]');
+}
+
 // parseVersion: pull the first x.y.z out of a version string (e.g. `ours-mcp v0.9.9`), matching
 // install.sh's `grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1`. Returns '' when none is present.
 export function parseVersion(text) {

package/lib/prompt.mjs

@@ -63,6 +63,46 @@ export function askLine(write, fd, prompt, def = '') {
   return ans === '' ? def : ans;
 }
 
+// Secret variant of askLine: identical cancellation/backspace/default semantics, but typed
+// characters are never echoed (not even as placeholder stars). This keeps provider keys out of
+// terminal scrollback, curl|bash output, and captured CI logs.
+export function askSecret(write, fd, prompt, def = '') {
+  if (fd == null || ASSUME_YES()) return def;
+
+  const saved = spawnSync('stty', ['-g'], { stdio: [fd, 'pipe', 'ignore'], encoding: 'utf8' });
+  const rawOk = saved.status === 0
+    && spawnSync('stty', ['-icanon', '-echo', '-isig', 'min', '1', 'time', '0'], { stdio: [fd, 'ignore', 'ignore'] }).status === 0;
+  const restore = () => {
+    if (rawOk) spawnSync('stty', (saved.stdout || '').trim() ? [(saved.stdout || '').trim()] : ['sane'], { stdio: [fd, 'ignore', 'ignore'] });
+  };
+  if (!rawOk) {
+    // Fail closed: a cooked fallback would echo the secret. Returning null lets the caller
+    // explain that secure input is unavailable without ever reading a credential.
+    write(`${prompt}\n`);
+    return null;
+  }
+  // Disable echo BEFORE displaying the prompt. Otherwise an automated or very fast typist can
+  // submit bytes in the small prompt→stty window and have the terminal driver echo the secret.
+  write(prompt);
+
+  let s = '';
+  try {
+    for (;;) {
+      const b = readByte(fd);
+      if (b === null || b === 0x04) break;
+      if (b === 0x03) { restore(); write('^C'); throw new InstallCancelled(); }
+      if (b === 0x0a || b === 0x0d) { write('\n'); break; }
+      if (b === 0x7f || b === 0x08) { if (s.length) s = s.slice(0, -1); continue; }
+      if (b < 0x20) continue;
+      s += String.fromCharCode(b);
+    }
+  } finally {
+    restore();
+  }
+  const ans = s.trim();
+  return ans === '' ? def : ans;
+}
+
 // askYesNo: y/n with a default shown in caps. Returns boolean.
 export function askYesNo(write, fd, prompt, def = false) {
   if (fd == null || ASSUME_YES()) return def;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/install",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "private": false,
   "description": "The unified ours.network stack installer (ours-install): one guided ~3-minute flow for ours core (the daemon) + the harness plugins (Claude Code / Codex) + ours-fleet + the Telegram connector, then a single copy-paste hand-off prompt. Self-contained (Node built-ins only); run as `ours-install` or via curl|bash (install.sh).",
   "type": "module",