quoxcli 0.2.0 → 0.4.0

package/lib/core/selfUpdate.js

@@ -0,0 +1,188 @@
+/**
+ * The one CLI updater (owner 2026-10-16 "we need /update", "or quox --update"): shared by /update in the
+ * conversation client and `quox update` / `quox --update` in the shell.
+ *
+ * It updates THIS quox the way it was installed, and never builds a second path where one already exists:
+ *   npm         <root> is node_modules/quoxcli        -> npm install -g quoxcli@<latest>
+ *   shared-git  the box's shared CLI tree             -> quox-cli-refresh (it refuses a dirty tree itself)
+ *   git         any other git checkout                -> git -C <root> pull --ff-only (clean and on main only)
+ *   server      a self-hosted install, at a v* tag    -> points at `quox server update` (that is its updater)
+ *   bundle      a dev-server bundle (.bundle-sha)     -> points at the server's refresh
+ * It never runs git stash, reset or checkout. Every external call is injectable (deps.run / spawn) for tests.
+ *
+ * Network: `npm view quoxcli ...` (the npm registry) and `git fetch origin main` (the tree's own remote), only
+ * when the user asks for an update. Nothing is sent but those requests.
+ */
+import { spawnSync, execFile } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+import { RUNNING_ROOT, findOnPath } from '../quoxon/slash/restart.js';
+import { cmpSemver } from '../server/install.js';
+import { askText } from '../quoxon/ask.js';
+
+export const NPM_PACKAGE = 'quoxcli';
+export const NOTES_MAX = 5;
+
+function defaultRun(cmd, args, { timeout = 30000 } = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout });
+  if (r.error) return { code: null, stdout: '', stderr: `${r.error.code || 'failed'}: ${r.error.message}` };
+  return { code: r.status, stdout: String(r.stdout || '').trim(), stderr: String(r.stderr || '').trim() };
+}
+
+/** The same, without blocking: the check runs while the conversation client keeps painting. */
+function asyncRun(cmd, args, { timeout = 30000 } = {}) {
+  return new Promise((done) => {
+    execFile(cmd, args, { encoding: 'utf8', timeout }, (err, stdout, stderr) => {
+      if (err && typeof err.code !== 'number') return done({ code: null, stdout: '', stderr: `${err.code || (err.killed ? 'timed out' : 'failed')}: ${String(stderr || err.message).trim()}` });
+      done({ code: err ? err.code : 0, stdout: String(stdout || '').trim(), stderr: String(stderr || '').trim() });
+    });
+  });
+}
+
+function withDeps(deps = {}, run = defaultRun) {
+  return {
+    run,
+    exists: existsSync,
+    readFile: (p) => readFileSync(p, 'utf8'),
+    realpath: (p) => { try { return realpathSync(p); } catch { return p; } },
+    findOnPath,
+    home: os.homedir(),
+    ...deps,
+  };
+}
+
+const gitOut = (d, dir, args, timeout = 5000) => {
+  const r = d.run('git', ['-C', dir, ...args], { timeout });
+  return r.code === 0 ? String(r.stdout || '').trim() : null;
+};
+const gitOutA = async (d, dir, args, timeout = 5000) => {
+  const r = await d.run('git', ['-C', dir, ...args], { timeout });
+  return r.code === 0 ? String(r.stdout || '').trim() : null;
+};
+const lastLine = (s) => String(s || '').trim().split('\n').filter(Boolean).pop() || '';
+
+/** How this quox was installed. -> { kind, root, version, branch?, refresh?, tag? } */
+export function detectInstall({ root = RUNNING_ROOT, env = process.env, deps = {} } = {}) {
+  const d = withDeps(deps);
+  const real = d.realpath(root);
+  let version = null;
+  try { version = JSON.parse(d.readFile(join(root, 'package.json'))).version || null; } catch { /* no package.json */ }
+  if (/[/\\]node_modules[/\\]quoxcli$/.test(real)) return { kind: 'npm', root: real, version };
+  if (d.exists(join(root, '.bundle-sha'))) return { kind: 'bundle', root: real, version };
+  const top = gitOut(d, real, ['rev-parse', '--show-toplevel']);
+  if (top) {
+    const branch = gitOut(d, top, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const refresh = d.findOnPath('quox-cli-refresh', env);
+    const shared = d.realpath(env.QUOX_CLI_DIR || join(d.home, 'quox-dashboard-cli'));
+    if (refresh && d.realpath(top) === shared) return { kind: 'shared-git', root: top, refresh, branch, version };
+    if (branch === 'HEAD') {
+      const tag = gitOut(d, top, ['describe', '--tags', '--exact-match']);
+      if (tag && /^v\d/.test(tag)) return { kind: 'server', root: top, tag, version };
+    }
+    return { kind: 'git', root: top, branch, version };
+  }
+  return { kind: 'unknown', root: real, version };
+}
+
+async function checkNpm(info, d) {
+  const cur = info.version || '0.0.0';
+  const v = await d.run('npm', ['view', NPM_PACKAGE, 'version'], { timeout: 20000 });
+  if (v.code !== 0 || !v.stdout) return { ok: false, kind: 'npm', current: cur, error: `npm view ${NPM_PACKAGE} version failed: ${lastLine(v.stderr) || `exit ${v.code}`}` };
+  const latest = lastLine(v.stdout);
+  const cmd = `npm install -g ${NPM_PACKAGE}@${latest}`;
+  const base = { ok: true, kind: 'npm', current: cur, latest, notes: [], manual: cmd };
+  const c = cmpSemver(latest, cur);
+  if (c !== null && c <= 0) return { ...base, upToDate: true, ahead: c < 0, count: 0 };
+  let count = 1;
+  const all = await d.run('npm', ['view', NPM_PACKAGE, 'versions', '--json'], { timeout: 20000 });
+  try {
+    const list = JSON.parse(all.stdout);
+    const n = (Array.isArray(list) ? list : [list]).filter((x) => cmpSemver(x, cur) === 1 && cmpSemver(x, latest) <= 0).length;
+    if (n > 0) count = n;
+  } catch { /* keep 1 */ }
+  return { ...base, upToDate: false, count, command: { cmd: 'npm', args: ['install', '-g', `${NPM_PACKAGE}@${latest}`], display: cmd } };
+}
+
+async function checkGit(info, d) {
+  const { root, kind } = info;
+  const f = await d.run('git', ['-C', root, 'fetch', 'origin', 'main', '--quiet'], { timeout: 30000 });
+  if (f.code !== 0) return { ok: false, kind, error: `git -C ${root} fetch origin main failed: ${lastLine(f.stderr) || `exit ${f.code}`}` };
+  const current = await gitOutA(d, root, ['rev-parse', '--short', 'HEAD']) || '?';
+  const latest = await gitOutA(d, root, ['rev-parse', '--short', 'origin/main']) || '?';
+  const count = Number(await gitOutA(d, root, ['rev-list', '--count', 'HEAD..origin/main']) || 0) || 0;
+  const pull = `git -C ${root} pull --ff-only`;
+  const shared = kind === 'shared-git';
+  const manual = shared ? 'quox-cli-refresh' : pull;
+  const base = { ok: true, kind, root, current, latest, count, manual };
+  if (count === 0) return { ...base, upToDate: true, notes: [] };
+  const notes = (await gitOutA(d, root, ['log', '--format=%s', '-n', String(NOTES_MAX), 'HEAD..origin/main']) || '').split('\n').filter(Boolean);
+  if (shared) {
+    return { ...base, upToDate: false, notes, scope: `This runs quox-cli-refresh, which updates quox for every session on this box (${root}).`, command: { cmd: info.refresh, args: [], display: 'quox-cli-refresh' } };
+  }
+  let refused = null;
+  if (info.branch !== 'main') refused = `${root} is on branch ${info.branch || '(unknown)'}, not main. Switch to main yourself, then update again. Nothing was changed.`;
+  else {
+    const dirty = (await gitOutA(d, root, ['status', '--porcelain', '--untracked-files=no']) || '').split('\n').filter(Boolean);
+    if (dirty.length) refused = `${root} has ${dirty.length} file${dirty.length === 1 ? '' : 's'} with uncommitted changes. Commit or move them, then update again. Nothing was changed.`;
+  }
+  return { ...base, upToDate: false, notes, refused, command: refused ? null : { cmd: 'git', args: ['-C', root, 'pull', '--ff-only'], display: pull } };
+}
+
+/**
+ * What an update would do. -> { ok, kind, current, latest, count, notes[], upToDate, command?, manual, scope?, refused?, error? }
+ * refused: this install has its own updater (or is not in a state to update): say why and the manual way.
+ */
+export async function checkUpdate(info, { deps = {} } = {}) {
+  const d = withDeps(deps, asyncRun);
+  switch (info?.kind) {
+    case 'npm': return checkNpm(info, d);
+    case 'git': case 'shared-git': return checkGit(info, d);
+    case 'server': return { ok: true, kind: 'server', current: info.tag, manual: 'quox server update', refused: `This quox is part of your self-hosted Quox install (${info.tag} at ${info.root}), so it updates with the server: run quox server update (it shows the latest release and asks first).` };
+    case 'bundle': return { ok: true, kind: 'bundle', manual: null, refused: `This quox is the dev-server bundle in ${info.root}; the Quox server refreshes it while dev mode is on. Ask your admin, or install your own copy with npm install -g ${NPM_PACKAGE}@latest.` };
+    default: return { ok: true, kind: 'unknown', manual: `npm install -g ${NPM_PACKAGE}@latest`, refused: `Could not tell how this quox was installed (${info?.root || 'unknown path'}). To install the published one: npm install -g ${NPM_PACKAGE}@latest` };
+  }
+}
+
+/** Run the update with the terminal handed over (prompts, sudo). -> { ok, code } or { ok:false, error } */
+export function runUpdate(plan, { spawn = spawnSync, env = process.env } = {}) {
+  const r = spawn(plan.command.cmd, plan.command.args, { stdio: 'inherit', env });
+  if (r.error) return { ok: false, error: `${r.error.code || 'failed'}: ${r.error.message}` };
+  const code = r.status ?? (r.signal ? 128 + (os.constants.signals[r.signal] || 0) : 1);
+  return { ok: code === 0, code };
+}
+
+const isGit = (p) => p.kind === 'git' || p.kind === 'shared-git';
+
+/** The lines shown before the ask (or the one line when there is nothing to do). */
+export function updateLines(plan) {
+  if (!plan.ok) return [`Could not check for updates: ${plan.error}`];
+  if (plan.refused && plan.kind !== 'git') return [plan.refused];
+  if (plan.upToDate) return [isGit(plan) ? `quox ${plan.current} is up to date with origin/main.` : plan.ahead ? `quox ${plan.current} is newer than the published ${plan.latest}. Nothing to update.` : `quox ${plan.current} is the latest.`];
+  const out = [];
+  const notes = plan.notes || [];
+  if (notes.length) out.push(`What's new (${isGit(plan) ? 'commits on origin/main' : 'releases'}):`, ...notes.slice(0, NOTES_MAX).map((n) => `  · ${n}`));
+  if (plan.count > notes.length && notes.length) out.push(`  · and ${plan.count - notes.length} more`);
+  if (plan.kind === 'npm') out.push(`Runs: ${plan.command.display}. Release notes show after the restart (/whatsnew).`);
+  if (plan.scope) out.push(plan.scope);
+  if (plan.refused) out.push(`quox ${plan.current} -> ${plan.latest}: ${plan.count} change${plan.count === 1 ? '' : 's'}, not updated. ${plan.refused}`);
+  return out;
+}
+
+/** "▶ quox <cur> -> <latest>: <n> changes. Update now and restart? y/N/c" (the shared ask shape). */
+export function updateAsk(plan, { restart = true } = {}) {
+  const n = plan.count;
+  return askText(`Update now${restart ? ' and restart' : ''}?`, { reason: `quox ${plan.current} -> ${plan.latest}: ${n} change${n === 1 ? '' : 's'}.` });
+}
+
+/** `quox --update [...]` is `quox update [...]` when it comes before any subcommand. */
+export function rewriteUpdateFlag(argv) {
+  const VALUE = new Set(['-p', '--profile', '-o', '--output', '--org']);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--update') return [...argv.slice(0, i), 'update', ...argv.slice(i + 1)];
+    if (VALUE.has(a)) { i++; continue; }
+    if (!a.startsWith('-')) return argv; // a subcommand came first: its own flags are its business
+  }
+  return argv;
+}

package/lib/core/sessionHeartbeat.js

@@ -15,7 +15,7 @@
  *    released on every exit path.
  * Pure parts take injected tmux output / held slots / attach lookup.
  */
-import { spawn as realSpawn, spawnSync as realSpawnSync } from 'node:child_process';
+import { spawnSync as realSpawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync, appendFileSync, truncateSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -70,9 +70,10 @@ export function buildBeat({ probe, backend = null, agent = null, slot = null, he
   };
 }
 
-/** Live probe of one tmux session (exact match). null when it does not exist. */
+/** Live probe of one tmux session (exact match). null when it does not exist.
+ *  `=name:` (session form): tmux 3.4 answers a bare `=name` with an empty line. */
 export function probeTmux(name, spawnSync = realSpawnSync) {
-  const r = spawnSync('tmux', ['display-message', '-p', '-t', `=${name}`, PROBE_FORMAT], { encoding: 'utf8' });
+  const r = spawnSync('tmux', ['display-message', '-p', '-t', `=${name}:`, PROBE_FORMAT], { encoding: 'utf8' });
   if (!r || r.error || r.status !== 0) return null;
   const p = parseProbe(r.stdout);
   return p && p.name === name ? p : null;
@@ -177,16 +178,19 @@ export function fileLogger(name, dir = HB_DIR()) {
  * Start the detached heartbeat child for a tmux session the wrapper launched.
  * The child is this same quox binary; it survives the wrapper exiting on detach.
  */
-export function startHeartbeat({ tmuxSession, backend, agent, slot }, { spawn = realSpawn, argv = process.argv, execPath = process.execPath } = {}) {
+// Spawned by a short-lived node that exits at once, so the heartbeat is never
+// the wrapper's child: the wrapper blocks in spawnSync(tmux) for the session's
+// life and could not reap it (ZOMBIES 2026-10-24, one defunct per wrapper).
+const DETACH_LAUNCHER = "const{spawn}=require('node:child_process');const c=spawn(process.argv[1],process.argv.slice(2),{detached:true,stdio:'ignore'});c.on('error',()=>{});c.unref();";
+
+export function startHeartbeat({ tmuxSession, backend, agent, slot }, { spawnSync = realSpawnSync, argv = process.argv, execPath = process.execPath } = {}) {
   if (!argv[1]) return false;
   const args = [argv[1], 'sessions', 'heartbeat', tmuxSession, '--loop'];
   if (backend) args.push('--backend', backend);
   if (agent) args.push('--agent', agent);
   if (slot) args.push('--slot', slot);
   try {
-    const child = spawn(execPath, args, { detached: true, stdio: 'ignore' });
-    if (child && child.on) child.on('error', () => {});
-    if (child && child.unref) child.unref();
-    return true;
+    const r = spawnSync(execPath, ['-e', DETACH_LAUNCHER, execPath, ...args], { stdio: 'ignore', timeout: 10_000 });
+    return !!r && !r.error && r.status === 0;
   } catch { return false; }
 }

package/lib/core/sessionsOverview.js

@@ -107,6 +107,70 @@ export function overviewLines(index, { now = Date.now(), localHost = null, all =
   return out;
 }
 
+/**
+ * SESSIONS (owner 2026-10-15): the quox conversation client's bare `/sessions`.
+ * Human first: every row leads with the session NAME and WHERE it runs, then
+ * how long it has been up and when it was last active. Ids and attach commands
+ * only appear with `refs` (one dim line under each row). Sections by what the
+ * thing is (terminal sessions, slots, work, chats), newest activity first.
+ * A row with no host says "host unknown"; nothing is guessed.
+ * -> [{ text, tone, state? }]
+ */
+const SECTIONS = [
+  { title: 'Terminal sessions', test: (r) => r.kind === 'tmux' },
+  { title: 'Slots', test: (r) => r.kind === 'slot' },
+  { title: 'Work', test: (r) => r.kind !== 'tmux' && r.kind !== 'slot' && r.kind !== 'conversation' },
+  { title: 'Chats', test: (r) => r.kind === 'conversation' },
+];
+
+function whereLabel(r, localHost) {
+  if (r.kind === 'conversation') return 'on the Quox server';
+  if (!r.host) return 'host unknown';
+  return localHost && r.host === localHost ? `on ${r.host} (this machine)` : `on ${r.host}`;
+}
+
+function sessionName(r) {
+  if (r.kind === 'slot') return r.holder_session || r.name || '(unnamed slot)';
+  return r.name || '(unnamed)';
+}
+
+export function humanSessionLines(index, { now = Date.now(), localHost = null, all = false, refs = false, names = {} } = {}) {
+  const prepared = prepareIndex(index, { all, names });
+  const rows = prepared.groups.flatMap((g) => g.rows).sort((a, b) => timeOf(b) - timeOf(a));
+  const counts = index.counts || {};
+  const ago = (v) => { const t = Date.parse(v); return Number.isFinite(t) ? formatAge((now - t) / 1000) : null; };
+  const out = [
+    { text: stripAnsi(line('quox', 'sessions', { result: `${counts.total || 0} live` })), tone: 'accent' },
+    { text: `${counts.working || 0} working · ${counts.waiting || 0} waiting · ${counts.resting || 0} resting · ${counts.failing || 0} failing`, tone: 'dim' },
+  ];
+  if (!rows.length) out.push({ text: 'No live sessions in this org.', tone: 'dim' });
+  for (const sec of SECTIONS) {
+    const rs = rows.filter(sec.test);
+    if (!rs.length) continue;
+    out.push({ text: `${sec.title} (${rs.length})`, tone: 'accent' });
+    for (const r of rs) {
+      const bits = [whereLabel(r, localHost)];
+      if (r.kind === 'slot' && r.holder_session && r.name && r.name !== r.holder_session) bits.push(`holds slot ${r.name}`);
+      const up = r.started_at ? ago(r.started_at) : null;
+      if (up) bits.push(`up ${up}`);
+      const act = ago(r.last_active);
+      bits.push(act ? `active ${act} ago` : 'no activity recorded');
+      const who = [r.agent ? `agent ${r.agent}` : null, r.kind === 'tmux' && r.slot ? `slot ${r.slot}` : null, r.backend || null].filter(Boolean);
+      if (who.length) bits.push(who.join(', '));
+      if (r.unread) bits.push(`${r.unread} unread`);
+      if (r.turns) bits.push(`${r.turns} turn${r.turns === 1 ? '' : 's'}`);
+      if (r.state_reason && r.state === 'failing') bits.push(r.state_reason);
+      out.push({ text: `  ${GLYPH[r.state] || '?'} ${sessionName(r)}  ${bits.join(' · ')}`, tone: TONE[r.state] || 'dim', state: r.state });
+      if (refs) out.push({ text: `      ${[r.attach_hint || null, r.id ? `id ${r.id}` : null].filter(Boolean).join(' · ')}`, tone: 'dim' });
+    }
+  }
+  if (prepared.hiddenConversations > 0) out.push({ text: `  +${prepared.hiddenConversations} older chats (last 24 h) · /sessions all`, tone: 'dim' });
+  const bad = (index.sources || []).filter((s) => s.state !== 'connected');
+  if (bad.length) out.push({ text: `could not read: ${bad.map((s) => `${s.id} (${s.state}${s.note ? `: ${s.note}` : ''})`).join(' · ')}`, tone: 'dim' });
+  if (!refs && rows.length) out.push({ text: '/sessions refs adds ids and attach commands · /sessions all includes every chat', tone: 'dim' });
+  return out;
+}
+
 export function renderOverview(index, { now = Date.now(), localHost = osHostname(), color = false, all = false, names = {} } = {}) {
   return overviewLines(index, { now, localHost, all, names }).map((l) => {
     if (!color) return l.text;

package/lib/core/shortcut.js

@@ -0,0 +1,83 @@
+/**
+ * `quox shortcut add|remove` (QUOXON-Q): a short command (default `q`) that is a symlink to this quox.
+ *
+ * Rules: never shadow an existing command (a `q` already on PATH that is not ours is refused and named);
+ * a user-writable directory only (the one quox lives in, else ~/.local/bin); no sudo; no shell rc edits (a symlink
+ * works in every shell and script); idempotent; remove only ever removes a link that points at this quox.
+ * Local only: nothing is sent anywhere.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_NAME = 'q';
+export const NAME_OK = /^[A-Za-z][A-Za-z0-9_.-]{0,30}$/;
+export const QUOX_ENTRY = fileURLToPath(new URL('../../bin/quox.js', import.meta.url));
+
+const real = (p) => { try { return fs.realpathSync(p); } catch { return null; } };
+const isExec = (p) => { try { fs.accessSync(p, fs.constants.X_OK); return fs.statSync(p).isFile(); } catch { return false; } };
+const writable = (d) => { try { fs.accessSync(d, fs.constants.W_OK); return fs.statSync(d).isDirectory(); } catch { return false; } };
+const pathDirs = (env) => String(env.PATH || '').split(path.delimiter).filter(Boolean);
+
+/** `command -v name` over PATH -> the first executable path, or null. */
+export function whichOnPath(name, env = process.env) {
+  for (const d of pathDirs(env)) { const p = path.join(d, name); if (isExec(p)) return p; }
+  return null;
+}
+
+/** Where the link goes: { dir, onPath, target }. target is what `q` will point at. */
+export function planShortcut({ env = process.env, home = os.homedir(), entry = QUOX_ENTRY } = {}) {
+  const realEntry = real(entry) || entry;
+  const quoxOnPath = whichOnPath('quox', env);
+  // The `quox` on PATH may be a wrapper script rather than a link to this entry: it is still "this quox".
+  const onPathReal = quoxOnPath;
+  const target = onPathReal || realEntry;
+  const reals = new Set([realEntry, quoxOnPath && real(quoxOnPath)].filter(Boolean));
+  const dirs = pathDirs(env).map(d => path.resolve(d));
+  const local = path.join(home, '.local', 'bin');
+  const cands = [];
+  if (onPathReal) cands.push(path.dirname(onPathReal));
+  cands.push(local);
+  const dir = cands.find(writable) || (fs.existsSync(local) ? null : local);
+  return { dir, onPath: dir ? dirs.includes(path.resolve(dir)) : false, target, realEntry, reals };
+}
+
+const ours = (p, reals) => { try { return fs.lstatSync(p).isSymbolicLink() && reals.has(real(p)); } catch { return false; } };
+
+/** -> { ok, status: 'created'|'exists'|'refused'|'error', message, link?, onPath? } */
+export function addShortcut({ name = DEFAULT_NAME, env = process.env, home = os.homedir(), entry = QUOX_ENTRY } = {}) {
+  if (!NAME_OK.test(name)) return { ok: false, status: 'error', message: `"${name}" is not a usable command name (letters, digits, _ . -, starting with a letter).` };
+  const plan = planShortcut({ env, home, entry });
+  const found = whichOnPath(name, env);
+  if (found && plan.reals.has(real(found))) return { ok: true, status: 'exists', link: found, message: `${name} already runs quox (${found}). Nothing changed.` };
+  if (found) return { ok: false, status: 'refused', message: `Not created: "${name}" already runs ${found}. Quox never shadows an existing command. Pick another name with: quox shortcut add --name <name>` };
+  if (!plan.dir) return { ok: false, status: 'error', message: 'No writable directory for the link (tried the one quox lives in and ~/.local/bin). Nothing changed.' };
+  const link = path.join(plan.dir, name);
+  if (ours(link, plan.reals)) return { ok: true, status: 'exists', link, onPath: plan.onPath, message: `${name} already points at quox (${link}).${plan.onPath ? '' : ` ${plan.dir} is not on your PATH, so ${name} will not run yet.`}` };
+  let present = false;
+  try { fs.lstatSync(link); present = true; } catch { /* free */ }
+  if (present) return { ok: false, status: 'refused', message: `Not created: ${link} already exists and is not a link to quox. Left alone.` };
+  try {
+    fs.mkdirSync(plan.dir, { recursive: true });
+    fs.symlinkSync(plan.target, link);
+  } catch (e) { return { ok: false, status: 'error', message: `Could not create ${link}: ${e.message}` }; }
+  const warn = plan.onPath ? '' : ` ${plan.dir} is not on your PATH, so ${name} will not run until you add it.`;
+  return { ok: true, status: 'created', link, onPath: plan.onPath, message: `Created ${link} -> ${plan.target}.${warn}` };
+}
+
+/** Removes the link only if it points at this quox. */
+export function removeShortcut({ name = DEFAULT_NAME, env = process.env, home = os.homedir(), entry = QUOX_ENTRY } = {}) {
+  if (!NAME_OK.test(name)) return { ok: false, status: 'error', message: `"${name}" is not a usable command name.` };
+  const plan = planShortcut({ env, home, entry });
+  const dirs = [...new Set([...(plan.dir ? [plan.dir] : []), ...pathDirs(env), path.join(home, '.local', 'bin')])];
+  for (const d of dirs) {
+    const link = path.join(d, name);
+    if (ours(link, plan.reals)) {
+      try { fs.unlinkSync(link); } catch (e) { return { ok: false, status: 'error', message: `Could not remove ${link}: ${e.message}` }; }
+      return { ok: true, status: 'removed', link, message: `Removed ${link}.` };
+    }
+  }
+  const other = whichOnPath(name, env);
+  return { ok: true, status: 'none', message: other ? `Nothing removed: ${name} (${other}) is not a link to quox, so it is left alone.` : `Nothing to remove: no ${name} link to quox found.` };
+}