syndes 0.1.0

package/runtime/config.mjs

@@ -0,0 +1,116 @@
+/**
+ * Config: <claudeDir>/syndes.json, with a per-project override at
+ * .claude/syndes.json.
+ *
+ * Never read from runtime/hook.mjs. The hot path pays for nothing.
+ *
+ * A malformed config falls back to defaults and reports it rather than throwing
+ * into a hook, and it is never silently rewritten over what a human hand-edited.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { configFile, projectConfigFile } from './paths.mjs';
+
+export const DEFAULTS = {
+  /** 'redacted' keeps text with secrets scrubbed | 'full' | 'metadata' (no text) */
+  privacy: 'redacted',
+  /** Extra regex sources appended to the built-in secret patterns. */
+  redactPatterns: [],
+
+  track: {
+    tools: true,       // PreToolUse + PostToolUse — the expensive pair, on by default
+    prompts: true,
+    permissions: true,
+    transcript: true,  // token, cost and cache numbers
+    git: true,
+  },
+
+  coach: {
+    enabled: true,
+    maxPerDay: 3,
+    cooldownHours: 24,
+    channels: { notification: true, terminal: true, digest: true },
+    injectContext: false, // changes Claude's own behaviour; opt-in, never a surprise
+    muted: [],
+  },
+
+  dashboard: {
+    port: 4317,
+    idleTimeoutMinutes: 60,
+    openOnStart: true,
+  },
+
+  retention: {
+    days: 0,          // 0 = forever. Deleting a user's history is opt-in.
+    gzipAfterDays: 30,
+  },
+
+  /** Gap below which two events count as continuous work, for active time. */
+  idleGapMinutes: 5,
+};
+
+let cached = null;
+
+export function loadConfig(cwd = null) {
+  if (!cached) cached = merge(DEFAULTS, readJson(configFile).data ?? {});
+  if (!cwd) return cached;
+
+  const override = readJson(projectConfigFile(cwd)).data;
+  return override ? merge(cached, override) : cached;
+}
+
+/** @returns {{data: object|null, error: string|null, exists: boolean}} */
+export function readJson(file) {
+  if (!existsSync(file)) return { data: null, error: null, exists: false };
+  try {
+    return { data: JSON.parse(readFileSync(file, 'utf8')), error: null, exists: true };
+  } catch (error) {
+    return { data: null, error: error.message, exists: true };
+  }
+}
+
+export function saveConfig(config) {
+  mkdirSync(dirname(configFile), { recursive: true });
+  writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`);
+  cached = merge(DEFAULTS, config);
+  return cached;
+}
+
+/** Read the on-disk config only, without defaults folded in — for editing. */
+export function rawConfig() {
+  return readJson(configFile).data ?? {};
+}
+
+export function getPath(object, path) {
+  return path.split('.').reduce((node, key) => (node == null ? undefined : node[key]), object);
+}
+
+export function setPath(object, path, value) {
+  const keys = path.split('.');
+  const last = keys.pop();
+  let node = object;
+  for (const key of keys) {
+    if (typeof node[key] !== 'object' || node[key] === null) node[key] = {};
+    node = node[key];
+  }
+  node[last] = value;
+  return object;
+}
+
+/** Deep merge for plain objects. Arrays replace rather than concatenate. */
+function merge(base, override) {
+  const out = { ...base };
+  for (const [key, value] of Object.entries(override ?? {})) {
+    const existing = out[key];
+    const bothPlain =
+      value && typeof value === 'object' && !Array.isArray(value) &&
+      existing && typeof existing === 'object' && !Array.isArray(existing);
+    out[key] = bothPlain ? merge(existing, value) : value;
+  }
+  return out;
+}
+
+export function resetCache() {
+  cached = null;
+}

package/runtime/hook.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * THE CRITICAL PATH. Claude Code blocks on this file, on every single tool call.
+ *
+ * Rules for this file, and only this file:
+ *   • No imports from this package. Every local import is another file Node must
+ *     resolve, read and parse before the user gets their tool call back. The
+ *     three paths it needs are re-derived inline, on purpose.
+ *   • No config read, no transcript read, no hashing, no classification.
+ *   • node: builtins only, and child_process only in the branch that spawns.
+ *   • Never throw. A tracker that breaks a session is worse than no tracker.
+ *
+ * Budget: Node's own start plus ~10 ms. test/hook-latency.test.mjs enforces both
+ * the budget and the no-local-import rule. A regression here is a correctness
+ * bug, not a performance nit. See DESIGN.md §1.
+ */
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const runtimeDir = dirname(fileURLToPath(import.meta.url));
+const claudeDir = process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), '.claude');
+const dataDir = join(claudeDir, 'syndes');
+const spoolDir = join(dataDir, 'spool');
+
+/** Events worth waking the worker for immediately: the user has just paused. */
+const BREAKPOINTS = new Set([
+  'SessionStart', 'Stop', 'SubagentStop', 'SessionEnd', 'PreCompact',
+  'Notification', 'PermissionRequest',
+]);
+
+/** Otherwise the worker is woken at most this often, however fast tools fire. */
+const SPAWN_INTERVAL_MS = 2000;
+
+main();
+
+function main() {
+  let payload;
+  try {
+    payload = readFileSync(0, 'utf8');
+  } catch {
+    return; // no stdin: nothing happened worth recording
+  }
+  if (!payload) return;
+
+  // One existsSync is the entire cost of the off switch on the fast path.
+  if (existsSync(join(dataDir, 'tracking.off')) && stillPaused()) return;
+
+  const event = eventName(payload);
+
+  try {
+    write(payload, event);
+  } catch {
+    // A full disk or a vanished directory must not surface inside a session.
+  }
+
+  if (event === 'SessionStart') printPendingCard();
+
+  try {
+    if (shouldSpawn(event)) spawnWorker();
+  } catch {
+    // The next hook will try again; the spool is still there.
+  }
+}
+
+/**
+ * The event name, without parsing the payload.
+ *
+ * A regex over the raw string beats JSON.parse of a tool_response that can be a
+ * megabyte of file content — and the hook has no other use for the parsed object.
+ */
+function eventName(payload) {
+  const match = /"hook_event_name"\s*:\s*"([A-Za-z]+)"/.exec(payload);
+  return match ? match[1] : 'Unknown';
+}
+
+function write(payload, event) {
+  mkdirSync(spoolDir, { recursive: true });
+
+  const now = Date.now();
+  const stamp = String(now).padStart(15, '0');
+  const unique = `${stamp}-${String(process.pid).padStart(7, '0')}-${Math.random().toString(36).slice(2, 8)}`;
+
+  const line = `${JSON.stringify({
+    t: now,
+    n: Number(process.hrtime.bigint() % 1000000n),
+    e: event,
+    p: payload,
+  })}\n`;
+
+  // Write then rename: rename is atomic on all three platforms, so the worker
+  // can never observe a half-written spool file. Discarding a torn line would
+  // be data loss, and this ledger's whole claim is that it does not lose lines.
+  const part = join(spoolDir, `${unique}.part`);
+  writeFileSync(part, line);
+  renameSync(part, join(spoolDir, `${unique}.jsonl`));
+}
+
+function shouldSpawn(event) {
+  // Never pile a second worker onto a live one; it would exit on the lock anyway
+  // and we would have paid a whole Node start to learn that.
+  if (existsSync(join(dataDir, 'writer.lock'))) return false;
+  if (BREAKPOINTS.has(event)) return true;
+
+  try {
+    return Date.now() - statSync(join(dataDir, 'last-spawn')).mtimeMs > SPAWN_INTERVAL_MS;
+  } catch {
+    return true; // no marker yet
+  }
+}
+
+async function spawnWorker() {
+  try {
+    writeFileSync(join(dataDir, 'last-spawn'), '');
+  } catch { /* the marker is an optimisation, not a requirement */ }
+
+  const { spawn } = await import('node:child_process');
+  // process.execPath, never "node": the PATH inside a hook is not your shell's.
+  spawn(process.execPath, [join(runtimeDir, 'worker.mjs')], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  }).unref();
+}
+
+/**
+ * The coach's terminal channel.
+ *
+ * The worker cannot write into the user's session, so it leaves a card here and
+ * the next SessionStart prints it. Checked on SessionStart only — the fast path
+ * for a tool call never pays for this.
+ */
+function printPendingCard() {
+  const card = join(dataDir, 'state', 'card.txt');
+  try {
+    if (!existsSync(card)) return;
+    process.stdout.write(readFileSync(card, 'utf8'));
+    renameSync(card, `${card}.shown`);
+  } catch { /* a card is never worth failing a session start over */ }
+}
+
+/** Only read when the pause file exists, which is the rare case. */
+function stillPaused() {
+  try {
+    const raw = readFileSync(join(dataDir, 'tracking.off'), 'utf8').trim();
+    if (!raw) return true; // `off` with no expiry: paused until turned back on
+    const until = Number(JSON.parse(raw).until);
+    return !Number.isFinite(until) || Date.now() < until;
+  } catch {
+    return true;
+  }
+}

package/runtime/jsonl.mjs

@@ -0,0 +1,104 @@
+/**
+ * JSONL read/write, and the canonical JSON the hash chain depends on.
+ *
+ * Without canonical(), the same record hashes two different ways depending on
+ * key insertion order and `verify` becomes a coin flip.
+ */
+
+import { createReadStream, appendFileSync, openSync, readSync, fstatSync, closeSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { createGunzip } from 'node:zlib';
+
+/**
+ * Deterministic JSON: keys sorted at every depth, no insignificant whitespace,
+ * `undefined` dropped rather than reordered into `null`.
+ */
+export function canonical(value) {
+  if (value === undefined) return 'null';
+  if (value === null || typeof value !== 'object') {
+    const encoded = JSON.stringify(value);
+    return encoded === undefined ? 'null' : encoded;
+  }
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+
+  const keys = Object.keys(value).filter((key) => value[key] !== undefined).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+}
+
+/** Parse one line, tolerating a trailing \r and blank lines. @returns {object|null} */
+export function parseLine(line) {
+  const trimmed = line.endsWith('\r') ? line.slice(0, -1) : line;
+  if (!trimmed.trim()) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stream a .jsonl or .jsonl.gz file as objects.
+ *
+ * Streaming rather than reading whole: a heavy year of use is hundreds of
+ * megabytes and the dashboard must not need it resident to answer one question.
+ *
+ * `crlfDelay: Infinity` is what makes a Windows-written file read correctly.
+ */
+export async function* streamRecords(file) {
+  let input = createReadStream(file);
+  if (file.endsWith('.gz')) input = input.pipe(createGunzip());
+
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const record = parseLine(line);
+    if (record) yield record;
+  }
+}
+
+/** Append one object as a line. The caller is responsible for holding the lock. */
+export function appendLine(file, object) {
+  appendFileSync(file, `${JSON.stringify(object)}\n`);
+}
+
+/**
+ * The last parseable line of a file, read from the tail rather than the head.
+ *
+ * Used to recover the chain tip when state/tip.json is missing or stale — which
+ * is exactly the case after a worker is killed mid-write, so it must not depend
+ * on reading a multi-megabyte segment from the front.
+ *
+ * @returns {{record: object|null, torn: boolean}} torn when the final line
+ *          exists but does not parse: a half-written record, not tampering.
+ */
+export function lastRecordOf(file, window = 65536) {
+  let handle;
+  try {
+    handle = openSync(file, 'r');
+    const size = fstatSync(handle).size;
+    if (size === 0) return { record: null, torn: false };
+
+    const length = Math.min(window, size);
+    const buffer = Buffer.alloc(length);
+    readSync(handle, buffer, 0, length, size - length);
+
+    const lines = buffer.toString('utf8').split('\n');
+    // A window that does not start at byte 0 may open mid-record; that first
+    // fragment is not evidence of anything and is dropped.
+    if (length < size) lines.shift();
+
+    let torn = false;
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      if (!lines[i].trim()) continue;
+      const record = parseLine(lines[i]);
+      if (record) return { record, torn };
+      torn = true;
+    }
+    return { record: null, torn };
+  } catch {
+    return { record: null, torn: false };
+  } finally {
+    if (handle !== undefined) {
+      try { closeSync(handle); } catch { /* already gone */ }
+    }
+  }
+}

package/runtime/lock.mjs

@@ -0,0 +1,98 @@
+/**
+ * The writer lock. Exactly one process may append to the ledger.
+ *
+ * Implemented with mkdirSync because directory creation is atomic on macOS,
+ * Linux and Windows alike — unlike flock/fcntl, which is POSIX-only, and unlike
+ * "check then create", which is a race wearing a lock's clothes.
+ *
+ * A worker killed mid-write must not wedge the ledger forever, so a lock older
+ * than STALE_MS, or one whose owner process is gone, can be broken.
+ */
+
+import { mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { lockDir } from './paths.mjs';
+import { debug } from './log.mjs';
+
+const OWNER_FILE = join(lockDir, 'owner.json');
+const STALE_MS = 60_000;
+
+let held = false;
+
+/** @returns {boolean} true when this process now owns the lock. */
+export function acquire() {
+  if (held) return true;
+
+  if (tryCreate()) return true;
+
+  const owner = readOwner();
+  if (!isStale(owner)) return false;
+
+  debug('breaking stale lock', owner);
+  try {
+    rmSync(lockDir, { recursive: true, force: true });
+  } catch {
+    return false;
+  }
+  return tryCreate();
+}
+
+function tryCreate() {
+  try {
+    mkdirSync(lockDir, { recursive: false });
+  } catch (error) {
+    if (error.code === 'EEXIST') return false;
+    // ENOENT means the parent is missing — the caller has not run ensureDataDirs.
+    throw error;
+  }
+
+  try {
+    writeFileSync(OWNER_FILE, JSON.stringify({ pid: process.pid, at: Date.now() }));
+  } catch {
+    // An unwritable owner file only costs us stale detection, not correctness.
+  }
+  held = true;
+  return true;
+}
+
+export function release() {
+  if (!held) return;
+  held = false;
+  try {
+    rmSync(lockDir, { recursive: true, force: true });
+  } catch {
+    // The next worker's stale check will clear it.
+  }
+}
+
+export function isHeld() {
+  return existsSync(lockDir) && !isStale(readOwner());
+}
+
+function readOwner() {
+  try {
+    return JSON.parse(readFileSync(OWNER_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A lock with no readable owner is stale — it was created by a process that died
+ * between mkdir and the owner write, and nothing else will ever clear it.
+ */
+function isStale(owner) {
+  if (!owner || typeof owner.pid !== 'number') return true;
+  if (Date.now() - (owner.at ?? 0) > STALE_MS) return true;
+  if (owner.pid === process.pid) return false;
+
+  try {
+    process.kill(owner.pid, 0); // signal 0 tests existence without delivering
+    return false;
+  } catch (error) {
+    // EPERM means it exists and belongs to someone else. Still alive.
+    return error.code !== 'EPERM';
+  }
+}
+
+export { STALE_MS };

package/runtime/log.mjs

@@ -0,0 +1,37 @@
+/**
+ * Debug log, off unless SYNDES_DEBUG=1.
+ *
+ * Never writes to stdout or stderr from inside a hook: Claude Code reads hook
+ * stdout, and stray output there becomes model context or a visible error.
+ */
+
+import { appendFileSync, statSync, renameSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { debugLogFile } from './paths.mjs';
+
+const ENABLED = process.env.SYNDES_DEBUG === '1';
+const MAX_BYTES = 2 * 1024 * 1024;
+
+export function debug(...parts) {
+  if (!ENABLED) return;
+  try {
+    mkdirSync(dirname(debugLogFile), { recursive: true });
+    rotateIfLarge();
+    const line = parts
+      .map((part) => (typeof part === 'string' ? part : JSON.stringify(part)))
+      .join(' ');
+    appendFileSync(debugLogFile, `${new Date().toISOString()} [${process.pid}] ${line}\n`);
+  } catch {
+    // Logging must never be the thing that breaks a session.
+  }
+}
+
+function rotateIfLarge() {
+  try {
+    if (statSync(debugLogFile).size > MAX_BYTES) renameSync(debugLogFile, `${debugLogFile}.1`);
+  } catch {
+    // No log yet, or it vanished. Either way there is nothing to rotate.
+  }
+}
+
+export const debugEnabled = ENABLED;

package/runtime/paths.mjs

@@ -0,0 +1,116 @@
+/**
+ * Every filesystem location syndes touches.
+ *
+ * Derived from this module's URL, never from process.cwd() — hooks run with the
+ * cwd of whatever project Claude Code was launched in, not the package.
+ *
+ * `packageRoot` is the copy executing; `installDir` is the copy settings.json
+ * points at. They differ under `npx` (the npm cache, which npm prunes) and in
+ * development, which is why install copies to a stable home.
+ *
+ * NOTE: runtime/hook.mjs deliberately does NOT import this module. It re-derives
+ * the three paths it needs inline. See DESIGN.md §1 — every local import is a
+ * file Node must resolve while the user waits.
+ */
+
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdirSync } from 'node:fs';
+
+const runtimeDir = dirname(fileURLToPath(import.meta.url));
+
+/** The package this process is running from. */
+export const packageRoot = dirname(runtimeDir);
+
+/** Claude Code honours CLAUDE_CONFIG_DIR; we must resolve it the same way. */
+export const claudeDir = process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), '.claude');
+
+/** True when the config directory has been redirected. An isolated install stays isolated. */
+export const isIsolated = Boolean(process.env.CLAUDE_CONFIG_DIR?.trim());
+
+export const settingsFile = join(claudeDir, 'settings.json');
+export const configFile = join(claudeDir, 'syndes.json');
+
+/** The stable home that installed hooks point at. */
+export const installDir = join(claudeDir, 'hooks', 'syndes');
+export const installedHookScript = join(installDir, 'runtime', 'hook.mjs');
+export const installedCliScript = join(installDir, 'bin', 'cli.mjs');
+export const isInstalledCopy = resolve(packageRoot) === resolve(installDir);
+
+/** The worker, resolved within the running copy so the hook spawns its own twin. */
+export const workerScript = join(runtimeDir, 'worker.mjs');
+
+// ── The data root ───────────────────────────────────────────────────────────
+// Only rollup/ and state/ are disposable. Everything else is the record.
+
+export const dataDir = join(claudeDir, 'syndes');
+export const logDir = join(dataDir, 'log');
+export const sealDir = join(dataDir, 'seal');
+export const keysDir = join(dataDir, 'keys');
+export const spoolDir = join(dataDir, 'spool');
+export const rollupDir = join(dataDir, 'rollup');
+export const stateDir = join(dataDir, 'state');
+
+export const chainKeyFile = join(keysDir, 'chain.key');
+export const authFile = join(dataDir, 'auth.json');
+export const lockDir = join(dataDir, 'writer.lock');
+export const debugLogFile = join(dataDir, 'debug.log');
+export const pauseFile = join(dataDir, 'tracking.off');
+export const spawnMarker = join(dataDir, 'last-spawn');
+
+export const tipFile = join(stateDir, 'tip.json');
+export const cursorsFile = join(stateDir, 'cursors.json');
+export const sessionsFile = join(stateDir, 'sessions.json');
+export const coachFile = join(stateDir, 'coach.json');
+export const projectsFile = join(stateDir, 'projects.json');
+
+/**
+ * Set by the npm postinstall, cleared the first time the CLI runs.
+ *
+ * npm hides postinstall output unless --foreground-scripts, so printing the
+ * briefing there means nobody sees it. It waits for the user's next command.
+ */
+export const briefingPending = join(stateDir, 'briefing-pending');
+
+export function segmentFile(day) {
+  return join(logDir, `${day}.jsonl`);
+}
+
+export function sealFileFor(day) {
+  return join(sealDir, `${day}.seal.json`);
+}
+
+export function rollupFile(day) {
+  return join(rollupDir, `${day}.json`);
+}
+
+/** Per-project override, read relative to the session's working directory. */
+export function projectConfigFile(cwd) {
+  return join(cwd, '.claude', 'syndes.json');
+}
+
+/**
+ * A path shortened for display. Only the home directory is abbreviated —
+ * rewriting claudeDir to a literal `~/.claude` would be a lie whenever
+ * CLAUDE_CONFIG_DIR points elsewhere, and printed paths exist to be copied.
+ */
+export function displayPath(path) {
+  const home = homedir();
+  return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+
+/**
+ * Create the data directories. Safe to call from anywhere: `recursive` makes it
+ * a no-op once they exist, and a failure here must never be fatal.
+ */
+export function ensureDataDirs() {
+  try {
+    for (const dir of [logDir, sealDir, keysDir, spoolDir, rollupDir, stateDir]) {
+      mkdirSync(dir, { recursive: true });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/runtime/platform.mjs

@@ -0,0 +1,74 @@
+/**
+ * The one module that knows what operating system this is. Everyone else asks.
+ *
+ * A probe that cannot answer returns null and the caller degrades. "Unsupported"
+ * and "broken" must never look alike — the failure mode to design out is a tool
+ * that installs six hooks on Windows, reports them green, and runs none.
+ */
+
+import { existsSync } from 'node:fs';
+import { join, delimiter } from 'node:path';
+
+export const PLATFORM = process.platform;
+export const isMac = PLATFORM === 'darwin';
+export const isWindows = PLATFORM === 'win32';
+export const isLinux = PLATFORM === 'linux';
+
+const NAMES = { darwin: 'macOS', win32: 'Windows', linux: 'Linux' };
+export const platformName = NAMES[PLATFORM] ?? PLATFORM;
+
+export const isSupportedPlatform = isMac || isWindows || isLinux;
+
+/**
+ * Locate an executable on PATH.
+ *
+ * Walks PATH itself rather than shelling out: `which` does not exist on Windows,
+ * PATHEXT is what decides executability there, and a loop beats a process spawn.
+ *
+ * @returns {string|null} the absolute path, or null when it is not installed
+ */
+const whichCache = new Map();
+
+export function which(binary) {
+  if (whichCache.has(binary)) return whichCache.get(binary);
+  const found = lookup(binary);
+  whichCache.set(binary, found);
+  return found;
+}
+
+function lookup(binary) {
+  const extensions = isWindows
+    ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+    : [''];
+
+  for (const dir of (process.env.PATH ?? '').split(delimiter).filter(Boolean)) {
+    for (const extension of ['', ...extensions]) {
+      const candidate = join(dir, binary + extension);
+      try {
+        if (existsSync(candidate)) return candidate;
+      } catch {
+        // An unreadable PATH entry is not an answer about `binary`.
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * argv for opening a URL or file in the platform's default handler.
+ *
+ * The empty string after `start` is required: `start` reads its first quoted
+ * argument as a window title, so `start "http://…"` opens a console window
+ * titled with the URL and no browser at all.
+ *
+ * @returns {{command: string, args: string[]}|null}
+ */
+export function openArgs(target) {
+  if (isMac) return { command: '/usr/bin/open', args: [target] };
+  if (isWindows) return { command: 'cmd', args: ['/c', 'start', '', target] };
+  const xdg = which('xdg-open');
+  return xdg ? { command: xdg, args: [target] } : null;
+}
+
+/** True when POSIX file modes actually mean anything here. */
+export const honoursFileModes = !isWindows;