@ours.network/install 0.17.0-nightly.9 → 0.17.0

package/lib/components.mjs

@@ -1,351 +0,0 @@
-// ours-install v3 — component selection and attachment.
-//
-// Spec: installer-spec-v3 §5 (and the repoint half of §7, which cannot be
-// separated from attaching the connector without making a silent move possible).
-// Pure, like target.mjs and plan.mjs: the caller injects the current file
-// contents and the installed versions, and every function returns a plan.
-//
-// The three components are the MCP server, the Telegram connector and cowork.
-// None of them IS the daemon; all three attach to one. The messenger is out of
-// scope by the owner's instruction, and ours-fleet sits on top and is not
-// installed here.
-
-import { join, resolve } from 'node:path';
-import { pkgSpec, resolveChannel } from './logic.mjs';
-
-// `pkg` is the package's IDENTITY — bare, no dist-tag — because that is what
-// `npm ls -g --json <pkg>` needs to read an installed version back, and what a
-// component is keyed by in every summary. `specKey` is the same package's name
-// in lib/logic.mjs's channel map, and `componentSpec` below is the only thing
-// that turns the two into an `npm i -g` argument.
-//
-// THE TWO MUST STAY SEPARATE. Putting the tag in `pkg` would make
-// effects.installedVersion('@ours.network/mcp@nightly') return null forever,
-// which fails the cowork version floor CLOSED and blanks the version column —
-// a silent regression that looks like "cowork is too old".
-export const COMPONENTS = [
-  { key: 'mcp', label: 'MCP server', pkg: '@ours.network/mcp', specKey: 'mcp', default: true },
-  { key: 'tg', label: 'Telegram connector', pkg: '@ours.network/tg-connector', specKey: 'tg-connector', default: false },
-  { key: 'cowork', label: 'cowork', pkg: '@ours.network/cowork', specKey: 'cowork', default: false },
-];
-
-/**
- * The `npm i -g` argument for one component on one channel.
- *
- * WHY THIS EXISTS AT ALL. `args.channel` was resolved in the orchestrator and
- * then reached only lib/extras.mjs's two planners, while these three packages
- * were installed by their bare names. So `CHANNEL=nightly` installed the NIGHTLY
- * Codex/Hermes plugins and NIGHTLY ours-fleet beside a STABLE MCP server — the
- * split-brain deployment the channel exists to prevent, and the same class of
- * bug the extras.mjs channel-map correction fixed for ours-fleet one package
- * over. Every install path for these three now goes through here.
- *
- * All three publish a real `nightly` dist-tag (verified against the registry,
- * 2026-08-17), so none of these pins can 404. `pkgSpec` falls back to `latest`
- * for anything unmapped rather than inventing a tag, so an unknown component
- * degrades to today's behaviour instead of failing.
- *
- * ON THE STABLE CHANNEL THIS RETURNS THE BARE NAME, byte for byte what shipped
- * before. `npm i -g pkg` and `npm i -g pkg@latest` are the same install, so
- * appending the tag would have bought nothing and changed every stable screen
- * line and assertion. The nightly channel is the case that was broken; it is the
- * only case that changes.
- */
-export const componentByKey = (key) => COMPONENTS.find((c) => c.key === key);
-
-export function componentSpec(component, channel = 'latest') {
-  const key = typeof component === 'string' ? component : component?.specKey ?? component?.key;
-  const name = typeof component === 'string' ? null : component?.pkg ?? null;
-  if (resolveChannel(channel) === 'latest') return name ?? `@ours.network/${String(key).replace(/^@ours\.network\//, '')}`;
-  return pkgSpec(key, channel);
-}
-
-// cowork must be at least this build to understand an external-daemon block.
-export const COWORK_DAEMON_FLOOR = '0.4.1-nightly.20260816.4aaf940';
-
-// -----------------------------------------------------------------------------
-// THE REGISTRY THAT IS NOT OURS TO TOUCH
-// -----------------------------------------------------------------------------
-
-/**
- * The Telegram connector keeps its OWN registry of routes, and the installer must
- * never write into it.
- *
- *   ~/.ours-telegram/bots.json        the bot registry
- *   ~/.ours-telegram/<route>/         one directory per route, each holding
- *                                     identity.key, state_data.bin, connection.json
- *
- * (tg-connector `src/connector.ts:35-42,170-173`, `src/config.ts:39`.)
- *
- * WHY THIS IS STATED AS A CONSTANT AND ASSERTED BY A TEST. The connector
- * distinguishes its identities by walking its own state directory, NOT by asking
- * the daemon: a daemon's identity list is FLAT and carries no attribution to the
- * app that created it. So there is no way to reconstruct this registry from the
- * daemon side, and anything the installer clears here is gone. The installer's
- * entire business with the connector is three keys in one config file.
- *
- * This also keeps the door open for the route migration the owner is considering
- * — moving each route's packet into the shared daemon. That migration has to read
- * this registry to know which daemon identity corresponds to which route; an
- * installer that had trampled it would have destroyed the mapping.
- */
-export const TG_STATE_DIR_NAME = '.ours-telegram';
-export const TG_REGISTRY_FILES = ['bots.json'];
-export const TG_ROUTE_FILES = ['identity.key', 'state_data.bin', 'connection.json'];
-
-export const tgConfigPath = (home, env = {}) => env.OURS_TG_CONFIG ?? join(home, TG_STATE_DIR_NAME, 'config.json');
-export const coworkConfigPath = (home, env = {}) => env.OURS_COWORK_CONFIG ?? join(home, '.ours-cowork', 'config.json');
-
-// -----------------------------------------------------------------------------
-// §5 — selection
-// -----------------------------------------------------------------------------
-
-/**
- * Which components this run installs. Defaults are MCP server yes, connector no,
- * cowork no — the same answers a non-interactive run takes, so
- * `OURS_ASSUME_YES=1 ours-install` produces a daemon plus the MCP server and
- * nothing else (spec §9).
- *
- * `installed` marks a component already present so the question reads "keep it?"
- * — and DECLINING AN ALREADY-INSTALLED COMPONENT NEVER UNINSTALLS IT. Removal is
- * `ours-uninstall`. A "no" here means "do not add", never "take it away".
- */
-export function planComponentSelection({ answers = {}, installed = {}, assumeYes = false } = {}) {
-  return COMPONENTS.map((component) => {
-    const already = installed[component.key] === true;
-    const answer = assumeYes ? component.default : answers[component.key];
-    const wanted = answer === undefined ? (already || component.default) : answer === true;
-    return {
-      ...component,
-      already,
-      action: already ? (wanted ? 'keep' : 'leave-alone') : (wanted ? 'install' : 'skip'),
-    };
-  });
-}
-
-// -----------------------------------------------------------------------------
-// §5 — the MCP server
-// -----------------------------------------------------------------------------
-
-/**
- * The MCP server runs per session, not as a daemon: the harness spawns
- * `ours-mcp proxy` over stdio. No systemd unit is installed for it, and the only
- * thing written to disk is the harness's MCP registration.
- *
- * For a non-default state directory the registration carries
- * `OURS_CONFIG=<state-dir>/config.json`, so the endpoint and the state directory
- * travel together — which is what keeps "endpoint given, state directory
- * defaulted" unreachable. Several harnesses can each point at a different daemon
- * precisely because the pair lives in each registration.
- */
-export function planMcpAttachment({ stateDir, isDefaultStateDir, channel = 'latest' }) {
-  const dir = resolve(stateDir);
-  return {
-    key: 'mcp',
-    install: ['npm', 'i', '-g', componentSpec(componentByKey('mcp'), channel)],
-    service: null, // deliberate: per-session stdio proxy, never a unit
-    harnessEnv: isDefaultStateDir ? {} : { OURS_CONFIG: join(dir, 'config.json') },
-    writes: ['the harness MCP registration'],
-  };
-}
-
-// -----------------------------------------------------------------------------
-// §5 / §7 — the Telegram connector
-// -----------------------------------------------------------------------------
-
-/**
- * Attach the connector to this daemon by setting exactly three keys in its config
- * file, preserving every other key in it — the file also holds the operator's bot
- * token and STT settings. If all three already match, the file is not touched.
- *
- * Both daemon keys are ALWAYS written together. A half-formed pair is what makes
- * "endpoint selected, state directory defaulted" reachable downstream, and the
- * SDK refuses that before it opens a socket.
- *
- * Returns `action: 'confirm-repoint'` when the connector is currently attached to
- * a DIFFERENT daemon. There is exactly one `daemonUrl`/`daemonStateDir` pair and
- * one unit, so pointing it elsewhere MOVES the connector; it does not add a
- * second one. That is not something to do silently, and unlike the legacy-unit
- * case it is not recoverable by re-running: the operator's routes would be
- * talking to a daemon they did not choose.
- */
-export function planTgAttachment({ existing, endpoint, stateDir, brokerUrl, assumeYes = false, channel = 'latest' }) {
-  const dir = resolve(stateDir);
-  const base = existing && typeof existing === 'object' && !Array.isArray(existing) ? existing : {};
-  const desired = { daemonUrl: endpoint, daemonStateDir: dir, brokerUrl };
-
-  const current = typeof base.daemonUrl === 'string' || typeof base.daemonStateDir === 'string'
-    ? { daemonUrl: base.daemonUrl ?? null, daemonStateDir: base.daemonStateDir ?? null }
-    : null;
-  const pointsElsewhere = current !== null
-    && (current.daemonStateDir === null || resolve(current.daemonStateDir) !== dir);
-
-  const merged = { ...base };
-  const changes = [];
-  for (const [key, value] of Object.entries(desired)) {
-    if (value === undefined || value === null) continue;
-    if (merged[key] === value) continue;
-    changes.push(key);
-    merged[key] = value;
-  }
-  const plan = {
-    key: 'tg',
-    install: ['npm', 'i', '-g', componentSpec(componentByKey('tg'), channel)],
-    changed: changes.length > 0,
-    changes,
-    config: merged,
-    // Written BEFORE the service: `ours-tg-connector install-service` bakes the
-    // resolved values into the unit as environment, and environment outranks the
-    // config file afterwards.
-    service: ['ours-tg-connector', 'install-service'],
-    untouched: [...TG_REGISTRY_FILES, ...TG_ROUTE_FILES],
-  };
-  if (!pointsElsewhere) return { ...plan, action: plan.changed ? 'attach' : 'unchanged' };
-  const repoint = {
-    ...plan,
-    action: 'confirm-repoint',
-    from: current,
-    to: { daemonUrl: endpoint, daemonStateDir: dir },
-    prompt: `The Telegram connector currently uses ${current.daemonUrl ?? 'an unrecorded daemon'} (${current.daemonStateDir ?? 'unrecorded state directory'}).\nPoint it at ${endpoint} (${dir}) instead? This MOVES the connector; it does not add a second one.`,
-  };
-  // Never repointed without a human, in any mode (spec §9).
-  return assumeYes ? { ...repoint, action: 'skip-repoint', reason: 'never repointed non-interactively' } : repoint;
-}
-
-// -----------------------------------------------------------------------------
-// §5 — cowork
-// -----------------------------------------------------------------------------
-
-/**
- * Compare an installed version against a floor. Prerelease-aware and CONSERVATIVE
- * by design: anything unparseable is "too old", because the failure it guards is
- * handing a daemon block to a build whose config is strict and whose boot is
- * fail-closed. Being wrong in the cautious direction leaves cowork embedded;
- * being wrong the other way stops it starting.
- */
-export function atLeastVersion(actual, floor) {
-  const parse = (v) => {
-    const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(String(v ?? '').trim());
-    return m ? { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null } : null;
-  };
-  const a = parse(actual);
-  const b = parse(floor);
-  if (!a || !b) return false;
-  for (let i = 0; i < 3; i += 1) {
-    if (a.nums[i] !== b.nums[i]) return a.nums[i] > b.nums[i];
-  }
-  if (a.pre === b.pre) return true;
-  if (a.pre === null) return true; // a release outranks any prerelease of the same version
-  if (b.pre === null) return false;
-  return a.pre >= b.pre;
-}
-
-/**
- * cowork's external-daemon block. Both halves are required: a half-formed block
- * is REFUSED rather than written, because cowork's boot is fail-closed.
- *
- * The top-level `stateDir` in that file is cowork's OWN private state and is left
- * alone; only `daemon.stateDir` is the ours daemon's. Confusing the two fails
- * closed at boot, which is why they are never touched in the same write.
- */
-/**
- * cowork's own defaults, seeded ONLY into a config that does not have them.
- *
- * WHY THIS IS NOT "CONFIGURING SOMEBODY ELSE'S TOOL". On a first install cowork's
- * config file does not exist, so v3 wrote it with a `daemon` block and nothing
- * else — no version, no broker, no REST port. The nightly installer seeds all
- * three (`planCoworkConfig`, lib/logic.mjs), and the broker in particular is a
- * value the INSTALLER knows and cowork cannot guess: it is the one the operator
- * chose in this run, and a cowork pointed at a different broker cannot reach the
- * agents it was installed to talk to.
- *
- * SEEDED ONLY INTO A FILE THAT DOES NOT EXIST YET. An existing cowork config is
- * copied through untouched — every key, including ones we would have defaulted.
- * That line is deliberate and narrower than "write any key that is absent": a
- * config the operator already has is theirs, and adding keys to it on a re-run
- * would rewrite a file for no reason the operator asked for. A file this run is
- * CREATING is a different thing, and it is the only case seeded here.
- *
- * NOT VERIFIED, and stated rather than assumed: whether cowork boots happily on a
- * daemon block alone. Its own defaults may well cover all three. Seeding what the
- * installer already knows is the safe direction either way, and it is what the
- * flow being replaced does.
- */
-export const COWORK_DEFAULT_REST_PORT = 3052;
-
-export function seedCoworkDefaults(base, { brokerUrl, home }) {
-  const seeded = { ...base };
-  const added = [];
-  if (seeded.version === undefined) { seeded.version = 1; added.push('version'); }
-  if (typeof seeded.brokerUrl !== 'string' && brokerUrl) { seeded.brokerUrl = brokerUrl; added.push('brokerUrl'); }
-  // cowork's OWN state directory, never the daemon's. Confusing the two fails
-  // closed at boot, which is why they are never written in the same expression.
-  if (typeof seeded.stateDir !== 'string' && home) { seeded.stateDir = join(home, '.ours-cowork'); added.push('stateDir'); }
-  const rest = seeded.rest && typeof seeded.rest === 'object' && !Array.isArray(seeded.rest) ? seeded.rest : null;
-  if (!rest || !Number.isInteger(rest.port)) {
-    seeded.rest = { enabled: rest?.enabled ?? true, ...(rest ?? {}), port: rest?.port ?? COWORK_DEFAULT_REST_PORT };
-    added.push('rest.port');
-  }
-  return { config: seeded, added };
-}
-
-export function planCoworkAttachment({ existing, endpoint, stateDir, installedVersion, channel = 'latest', brokerUrl, home }) {
-  const dir = resolve(stateDir);
-  if (!endpoint || !stateDir) {
-    return { key: 'cowork', action: 'refuse', reason: 'half-formed-block', message: 'a cowork daemon block needs both an endpoint and a state directory; refusing to write half of one' };
-  }
-  if (!atLeastVersion(installedVersion, COWORK_DAEMON_FLOOR)) {
-    return {
-      key: 'cowork',
-      action: 'leave-embedded',
-      reason: 'version-floor',
-      installedVersion: installedVersion ?? null,
-      message: `the installed cowork (${installedVersion ?? 'version unreadable'}) predates ${COWORK_DAEMON_FLOOR}, which is the first build that understands an external-daemon block; leaving cowork embedded`,
-    };
-  }
-  const base = existing && typeof existing === 'object' && !Array.isArray(existing) ? existing : {};
-  const daemon = { mode: 'external', endpoint, stateDir: dir };
-  const daemonUnchanged = base.daemon
-    && base.daemon.mode === 'external'
-    && base.daemon.endpoint === endpoint
-    && typeof base.daemon.stateDir === 'string'
-    && resolve(base.daemon.stateDir) === dir;
-  // Seeded only where the key is ABSENT, so an existing config is still copied
-  // through untouched — which was already the right behaviour and is not changed.
-  const creating = existing === null || existing === undefined;
-  const { config: seeded, added } = creating
-    ? seedCoworkDefaults(base, { brokerUrl, home })
-    : { config: base, added: [] };
-  const unchanged = daemonUnchanged && added.length === 0;
-  return {
-    key: 'cowork',
-    action: unchanged ? 'unchanged' : 'attach',
-    install: ['npm', 'i', '-g', componentSpec(componentByKey('cowork'), channel)],
-    changed: !unchanged,
-    seeded: added,
-    // The top-level stateDir is cowork's own; an existing one is copied through
-    // untouched and only an ABSENT one is seeded. Confusing it with the daemon's
-    // fails closed at boot, which is why they are never written together.
-    config: { ...seeded, daemon },
-    service: ['ours-cowork', 'install-service'],
-  };
-}
-
-// -----------------------------------------------------------------------------
-// §5 — one component failing does not stop the others
-// -----------------------------------------------------------------------------
-
-/**
- * A component that fails is reported with its reason and the exact manual
- * command, and the run continues to the next. The daemon and the
- * already-installed components stay as they are — a failed component is never a
- * reason to undo a successful one.
- */
-export function summarizeComponentRun(results) {
-  return {
-    installed: results.filter((r) => r.state === 'installed').map((r) => r.key),
-    failed: results.filter((r) => r.state === 'failed').map((r) => ({ key: r.key, reason: r.reason, retry: r.retry ?? null })),
-    skipped: results.filter((r) => r.state === 'skipped').map((r) => r.key),
-    continued: true,
-  };
-}

package/lib/detect.mjs

@@ -1,182 +0,0 @@
-// ours-install v3 — which daemons are already on this machine, and which one this
-// run is for.
-//
-// OWNER RULING (C1, 2026-08-17), and the whole shape of this file follows from it:
-// never ask the user to TYPE a state directory or a port — that is what spec §2
-// forbids and it stands — but when several daemons are DETECTED, show them and let
-// the user pick. Selection from what was found is not prompting for a path.
-//
-// Pure, like target.mjs and plan.mjs: the caller injects the directory listing and
-// the file reads, so the whole decision is testable without a filesystem.
-//
-// DETECTION, NOT A REGISTRY. Coordinator ruling: build this from what is actually
-// on disk rather than from a persisted ~/.ours/installer-profiles.json. A stored
-// list is a second source of truth that goes stale against the daemons that really
-// exist, and staleness in exactly that file is how an installer ends up
-// confidently offering a daemon that is gone.
-
-import { basename, join, resolve } from 'node:path';
-
-// Artefacts ONLY a daemon writes. A directory carrying any of these is a daemon's
-// state directory, whatever else is in it.
-export const DAEMON_ARTEFACTS = ['daemon-token', 'ours-cli-daemon.json', 'root.json'];
-
-/**
- * CONFIG.JSON IS THE ONE PIECE OF EVIDENCE THAT IS AMBIGUOUS, SO IT CANNOT BE THE
- * TEST. This is the trap this function exists to avoid, and it is worth stating
- * plainly because the obvious implementation walks straight into it:
- *
- * `~/.ours-telegram/config.json` and `~/.ours-cowork/config.json` both exist on a
- * normal machine, both match a `~/.ours*` scan, and NEITHER is a daemon — they are
- * the connectors' own configs. A selection screen built on "has a config.json"
- * shows three daemons on a machine with one, and choosing the Telegram connector's
- * directory would have the installer create a daemon inside it.
- *
- * So a config.json counts only when its SHAPE is a daemon's: it records a `port`
- * or a `stateDir`, and it carries none of the keys that identify it as somebody
- * else's. `daemonUrl`/`daemonStateDir` are the Telegram connector's; a `daemon`
- * block is cowork's; `botToken` is the connector's too.
- */
-export function looksLikeDaemonConfig(config) {
-  if (!config || typeof config !== 'object' || Array.isArray(config)) return false;
-  if (typeof config.daemonUrl === 'string' || typeof config.daemonStateDir === 'string') return false;
-  if (config.daemon !== undefined) return false;
-  if (typeof config.botToken === 'string') return false;
-  return typeof config.port === 'number' || typeof config.stateDir === 'string';
-}
-
-/**
- * Is this directory a daemon's state directory? Returns the evidence, so a screen
- * or a test can say WHY rather than just yes.
- */
-export function classifyStateDir(dir, { exists, readJson }) {
-  const target = resolve(dir);
-  const artefact = DAEMON_ARTEFACTS.find((name) => exists(join(target, name)));
-  if (artefact) return { isDaemon: true, evidence: artefact, config: readJson(join(target, 'config.json')) };
-  const config = readJson(join(target, 'config.json'));
-  if (looksLikeDaemonConfig(config)) return { isDaemon: true, evidence: 'config.json', config };
-  return { isDaemon: false, evidence: null, config: null };
-}
-
-/**
- * Every daemon state directory this machine can be seen to have.
- *
- * KNOWN LIMIT, inherited from effects.knownStateDirs and stated rather than
- * implied: only `~/.ours` and its `~/.ours*` siblings are looked at. A state
- * directory somewhere else entirely is not found, and the failure is that it is not
- * offered — never that the wrong one is chosen, because `--state-dir` still names
- * anything and overrides all of this.
- */
-export function detectDaemons({ candidates = [], exists, readJson }) {
-  const found = [];
-  for (const dir of candidates) {
-    const target = resolve(dir);
-    if (found.some((d) => d.stateDir === target)) continue;
-    const verdict = classifyStateDir(target, { exists, readJson });
-    if (!verdict.isDaemon) continue;
-    found.push({
-      stateDir: target,
-      port: typeof verdict.config?.port === 'number' ? verdict.config.port : null,
-      evidence: verdict.evidence,
-      label: basename(target),
-    });
-  }
-  // Deterministic, and the default daemon first when it is one of them — it is the
-  // one an operator means by "my daemon".
-  return found.sort((a, b) => {
-    if (basename(a.stateDir) === '.ours') return -1;
-    if (basename(b.stateDir) === '.ours') return 1;
-    return a.stateDir.localeCompare(b.stateDir);
-  });
-}
-
-/**
- * A state directory for a daemon this run would CREATE, derived and never typed.
- *
- * Spec §2 forbids asking for a path, and the C1 ruling did not change that — it
- * added "pick from what was found". So "create a new one" has to derive somewhere
- * to put it: `~/.ours` when free, else the first free `~/.ours-2`, `~/.ours-3`…
- * An operator who wants a specific path still has `--state-dir`, which bypasses
- * this screen entirely.
- */
-export function deriveNewStateDir(home, taken = [], { limit = 64 } = {}) {
-  const used = new Set(taken.map((d) => resolve(d)));
-  const first = resolve(join(home, '.ours'));
-  if (!used.has(first)) return first;
-  for (let n = 2; n < limit; n += 1) {
-    const candidate = resolve(join(home, `.ours-${n}`));
-    if (!used.has(candidate)) return candidate;
-  }
-  return null;
-}
-
-export const SELECT_CREATE = '__create__';
-
-// The nightly flow kept a registry of daemon profiles here. v3 does not read it —
-// detection replaced it (coordinator ruling) — so anyone who used that flow has a
-// file describing daemons that nothing consults any more.
-//
-// It is NOT deleted. Quietly removing a file that describes someone's daemons is
-// not an installer's business, and the file is harmless. But leaving it looking
-// live is worse than saying it is not, so the run says so once.
-export const LEGACY_PROFILE_REGISTRY = 'installer-profiles.json';
-export const legacyRegistryPath = (home) => join(resolve(home), '.ours', LEGACY_PROFILE_REGISTRY);
-
-/**
- * What this run should do about choosing a daemon (C1's five rules, in one place
- * so they can be read together and tested without a terminal):
- *
- *   flags given          → no screen at all. `--state-dir` or `--port` is an
- *                          explicit target and outranks anything detected.
- *   non-interactive      → no screen. Flags only, and every existing refusal still
- *                          applies — OURS_ASSUME_YES suppresses questions, never a
- *                          refusal.
- *   none detected        → create, exactly as before.
- *   exactly one detected → no prompt, use it, and SAY which one. A question with
- *                          one answer is not a choice, it is a keystroke tax.
- *   several detected     → show them and pick, with "create a new one" as the last
- *                          option.
- */
-export function planDaemonSelection({
-  candidates = [],
-  stateDirExplicit = false,
-  portExplicit = false,
-  assumeYes = false,
-  home,
-} = {}) {
-  if (stateDirExplicit || portExplicit) {
-    return { action: 'flags', reason: stateDirExplicit ? '--state-dir names the target' : '--port names the target' };
-  }
-  if (assumeYes) return { action: 'flags', reason: 'non-interactive: flags only, no screen' };
-  if (candidates.length === 0) return { action: 'create', stateDir: deriveNewStateDir(home, []) };
-  if (candidates.length === 1) {
-    return { action: 'use', stateDir: candidates[0].stateDir, only: candidates[0], announce: true };
-  }
-  return {
-    action: 'choose',
-    candidates,
-    createOption: { id: SELECT_CREATE, stateDir: deriveNewStateDir(home, candidates.map((c) => c.stateDir)) },
-  };
-}
-
-/**
- * Resolve a typed answer against the offered list.
- *
- * Deliberately strict: an answer that is not a number in range, or the create
- * option, is NOT a state directory to be interpreted. Accepting free text here
- * would be exactly the "type a path" prompt spec §2 forbids, arriving through the
- * back door.
- */
-export function resolveSelection(answer, { candidates = [], createOption = null } = {}) {
-  const value = String(answer ?? '').trim().toLowerCase();
-  if (!value) return { action: 'invalid', reason: 'no answer' };
-  if (value === 'n' || value === 'new' || value === String(candidates.length + 1)) {
-    return createOption?.stateDir
-      ? { action: 'create', stateDir: createOption.stateDir }
-      : { action: 'invalid', reason: 'no free state directory could be derived' };
-  }
-  if (!/^\d+$/.test(value)) return { action: 'invalid', reason: 'that is not one of the numbers offered' };
-  const index = Number(value) - 1;
-  if (!Number.isInteger(index) || !candidates[index]) return { action: 'invalid', reason: 'that is not one of the numbers offered' };
-  return { action: 'use', stateDir: candidates[index].stateDir };
-}