@ours.network/install 0.14.0 → 0.15.0

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,14 +43,20 @@ 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.
 3. **Four consent gates**, each paced with a clean `✓ … No problems.` line + an explicit
    **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.
+   - **1/4 ours core (the daemon)** — write config → optional voice setup → install/start ONCE
+     → boot service. On a re-run it reuses the running config (no re-ask) and only updates when
+     you say yes. Complete voice setup is kept without prompting. Missing/incomplete setup is
+     offered before the first start or pending update restart, then delegated to the canonical
+     `ours-mcp voice-setup` provider selector and hidden API-key prompt. Accepted setup owns the
+     one restart/readiness transaction; declining or already-ready setup preserves the normal
+     core lifecycle. 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 +70,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 +86,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 +142,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 {
   suggestPort, parsePort, validateBroker, mergeConfig, parseVersion, parseStatus,
   detectPlatform, classifyHarnessProbe, buildHandoffPrompt,
+  voiceSetupStatus,
   DEFAULT_PORT, resolveChannel, pkgSpec,
 } from './lib/logic.mjs';
+import { atomicWriteConfig } from './lib/config.mjs';
 
 const NPM = process.env.OURS_NPM || 'npm';
 // Release channel: OURS_CHANNEL=nightly installs @nightly for mcp/tg-connector/plugin
@@ -85,7 +88,12 @@ async function actSpin(label, desc, fn) {
 // --- daemon probes (always safe to run — read-only) --------------------------------------------
 const daemonVersionLine = () => (run('ours-mcp', ['--version'], { capture: true }).out.split('\n')[0] || '').trim();
 const daemonStatusText = () => run('ours-mcp', ['status'], { capture: true }).out;
-const daemonRunning = () => run('ours-mcp', ['status'], { capture: true }).code === 0;
+function daemonLifecycleState() {
+  const status = run('ours-mcp', ['status'], { capture: true });
+  if (!status.ok) return 'stopped';
+  return /^\s*pid:\s*\d+/m.test(status.out) ? 'managed' : 'external';
+}
+const daemonRunning = () => daemonLifecycleState() !== 'stopped';
 const globalVersion = (pkg) => {
   const ls = run(NPM, ['ls', '-g', pkg], { capture: true }).out;
   const m = ls.match(new RegExp(pkg.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&') + '@([0-9][0-9.]*)'));
@@ -97,11 +105,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) {
@@ -318,8 +336,88 @@ async function main() {
   const summary = [];
   const record = (row) => summary.push(row);
 
+  // Voice setup is part of the core lifecycle, not a follow-up after it. On a
+  // fresh install this runs after the CLI is installed/configured but before
+  // the first daemon start. On an update it runs before any pending restart;
+  // a successful canonical voice-setup owns that one restart/readiness check.
+  // Declining, headless skipping, or an already-complete setup leaves the
+  // caller's normal start/restart lifecycle untouched.
+  const offerVoiceSetup = ({ readinessAfterStart = false, daemonState = 'stopped' } = {}) => {
+    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);
+      return { setupRan: false, restartHandled: false };
+    }
+    if (!interactive) {
+      line(info('Voice transcription is not configured. Non-interactive mode leaves it unchanged.'));
+      line(info('Run `ours-mcp voice-setup` in a terminal, or supply OURS_STT_* environment values.'));
+      record({ key: 'voice', label: 'Voice transcription', state: 'skipped', note: 'interactive setup available on re-run' });
+      cont(false);
+      return { setupRan: false, restartHandled: false };
+    }
+
+    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 hidden.'));
+    if (!yes('  Set up voice transcription now?', true)) {
+      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);
+      return { setupRan: false, restartHandled: false };
+    }
+
+    line(info('Opening the canonical ours-mcp voice setup (same command you can re-run later).'));
+    const setupArgs = ['voice-setup', ...(DRY ? ['--dry-run'] : [])];
+    const setup = run('ours-mcp', setupArgs);
+    if (!setup.ok) {
+      line(warn('Voice setup did not complete; no installer-side credential fallback was used.'));
+      line(info('Run `ours-mcp voice-setup` directly to try again.'));
+      record({ key: 'voice', label: 'Voice transcription', state: 'failed', note: 'ours-mcp voice-setup did not complete' });
+      cont();
+      // Exit 2 is the canonical command's explicit signal that it already
+      // attempted restart/readiness and rollback. Never layer the pending
+      // installer update restart on top of that recovery transaction.
+      return { setupRan: true, restartHandled: setup.code === 2 };
+    }
+    if (DRY) {
+      line(ok('Canonical voice setup dry-run completed; no config or daemon state changed.'));
+      record({ key: 'voice', label: 'Voice transcription', state: 'current', note: 'voice-setup dry-run' });
+      cont();
+      return { setupRan: true, restartHandled: false };
+    }
+    if (readinessAfterStart) {
+      line(ok('Voice configuration saved securely; it will be readiness-checked after the first daemon start.'));
+      record({ key: 'voice', label: 'Voice transcription', state: 'installed', note: 'configured before first start' });
+      cont();
+      return { setupRan: true, restartHandled: false };
+    }
+
+    const verified = daemonVoiceCapability();
+    if (verified?.ready) {
+      line(ok(`Voice transcription is ready (${verified.provider}); API key remains hidden.`));
+      record({ key: 'voice', label: 'Voice transcription', state: 'installed', note: verified.provider });
+    } else {
+      line(warn('Voice setup returned without a ready capability; inspect `ours-mcp voice-status`.'));
+      record({ key: 'voice', label: 'Voice transcription', state: 'failed', note: 'readiness check failed' });
+    }
+    cont();
+    // Exit 0 also covers config-only success for a stopped daemon or an
+    // externally launched daemon. Only a still-managed daemon proves that
+    // canonical setup owned apply + readiness and may suppress an update
+    // restart.
+    return {
+      setupRan: true,
+      restartHandled: daemonState === 'managed' && daemonLifecycleState() === 'managed',
+    };
+  };
+
   // ============================================================================================
-  // STEP 1 / 4 — ours core (the daemon). Config-first: write config → install/start ONCE.
+  // STEP 1 / 4 — ours core (the daemon). Config-first: write config → optional voice → start ONCE.
   // ============================================================================================
   line(heading('1/4 — ours core (the daemon)'));
   line(info('This is the piece that lets your agents talk to each other securely. Everything else'));
@@ -338,25 +436,55 @@ async function main() {
     const patch = { port: chosenPort };
     if (chosenBroker) patch.brokerUrl = chosenBroker;
     await act(`write config (${configPath()}) with port ${chosenPort}${chosenBroker ? ' + custom broker' : ''}`, async () => { writeConfigPatch(patch); return { ok: true }; });
+    const voice = offerVoiceSetup({ readinessAfterStart: true });
     const started = await act(`ours-mcp start (port ${chosenPort})`, async () => run('ours-mcp', ['start']));
     const svc = await act('ours-mcp install-service (survives reboot)', async () => run('ours-mcp', ['install-service']));
     if (started.ok) line(ok(`ours core ready — running on port ${chosenPort}. No problems.`));
     else line(warn(`could not auto-start — run '${c.cyan('ours-mcp start')}' to bring it up.`));
     if (!svc.ok && !svc.dry) line(warn(`boot-service not installed — retry '${c.cyan('ours-mcp install-service')}' later.`));
+    if (voice.setupRan && !DRY && started.ok) {
+      const verified = daemonVoiceCapability();
+      if (verified?.ready) {
+        line(ok(`Voice transcription readiness confirmed (${verified.provider}) after the first start.`));
+      } else {
+        line(warn('Voice configuration was saved, but readiness was not confirmed after start; run `ours-mcp voice-status`.'));
+        const row = summary.find((entry) => entry.key === 'voice');
+        if (row) {
+          row.state = 'failed';
+          row.note = 'readiness check failed after first start';
+        }
+      }
+    }
     record({ key: 'core', label: 'ours core (daemon)', state: started.ok ? 'installed' : 'failed', version: parseVersion(daemonVersionLine()), note: 'starts on boot' });
   } else {
     // Installed: offer an update; never re-ask config; reuse the running port everywhere.
-    const running = daemonRunning();
+    const daemonState = daemonLifecycleState();
+    const running = daemonState !== 'stopped';
     const upd = yes(`  ours core is installed (${before || '?'}) — check for an update now?`, false);
+    let pendingUpdateRestart = false;
+    let after = before;
     if (upd) {
       await actSpin(`updating ${spec('mcp')}…`, `npm i -g ${spec('mcp')}`, () => runAsync(NPM, ['i', '-g', spec('mcp')]));
-      const after = parseVersion(daemonVersionLine());
-      if (before && after && before !== after) {
+      after = parseVersion(daemonVersionLine());
+      pendingUpdateRestart = !!(before && after && before !== after);
+    }
+
+    const voice = offerVoiceSetup({ daemonState });
+    if (pendingUpdateRestart && !voice.restartHandled) {
+      const restartState = daemonLifecycleState();
+      if (restartState === 'external') {
+        line(warn(`ours core updated (v${before} → v${after}); restart its external launcher to load the update.`));
+      } else {
         await act(`ours-mcp restart (now v${after})`, async () => { if (!run('ours-mcp', ['restart']).ok) run('ours-mcp', ['start']); return { ok: true }; });
         line(ok(`ours core updated (v${before} → v${after}) and restarted. No problems.`));
-      } else {
-        line(ok(`ours core already current${after ? ` (v${after})` : ''} — nothing to change.`));
       }
+    } else if (pendingUpdateRestart) {
+      const voiceFailed = summary.find((entry) => entry.key === 'voice')?.state === 'failed';
+      line(voiceFailed
+        ? warn(`ours core updated (v${before} → v${after}); voice setup handled restart/rollback but did not change voice settings.`)
+        : ok(`ours core updated (v${before} → v${after}); voice setup performed the required restart and readiness check.`));
+    } else if (upd) {
+      line(ok(`ours core already current${after ? ` (v${after})` : ''} — nothing to change.`));
     } else {
       line(ok(`ours core ready — running on port ${chosenPort}${running ? '' : ' (start with ours-mcp start)'}. No problems.`));
     }

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.14.0",
+  "version": "0.15.0",
   "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",