@lyupro/codex-bridge 0.6.8 → 0.6.9

package/cli/prune.mjs

@@ -1,11 +1,10 @@
 /** Confirms, executes, and reports the destructive actions in a prune plan. */
 import fs from 'node:fs';
-import path from 'node:path';
-import readline from 'node:readline/promises';
-import { normalizePath } from '../src/home/hooks/live-runs.mjs';
+import { inspectSegments } from './link-segments.mjs';
 import { parsePruneArgs } from './prune-args.mjs';
 import { prunePlan } from './prune-plan.mjs';
 import { recursiveSize } from './runs-inventory.mjs';
+import { askYesNo, isInteractive } from './terminal-question.mjs';
 
 function formatBytes(bytes) {
   if (!Number.isFinite(bytes)) return 'unknown';
@@ -102,64 +101,6 @@ function result(exitCode, text) {
   return { exitCode, output: text };
 }
 
-// One spelling only. A guard that answers to several option names is a guard with several ways
-// to be switched off by accident.
-function tty(options) {
-  if (options.isTTY !== undefined) return Boolean(options.isTTY);
-  return Boolean((options.stdin || process.stdin).isTTY);
-}
-
-async function defaultPrompt(question, options = {}) {
-  const input = options.stdin || process.stdin;
-  const outputStream = options.promptOutput || process.stderr;
-  const interfaceHandle = readline.createInterface({ input, output: outputStream });
-  try {
-    const answer = await interfaceHandle.question(`${question} [y/N] `);
-    return /^(y|yes)$/i.test(answer.trim());
-  } finally {
-    interfaceHandle.close();
-  }
-}
-
-function accepted(answer) {
-  return answer === true || /^(y|yes)$/i.test(String(answer ?? '').trim());
-}
-
-// The package compares paths through one function, and this guard is the last thing standing
-// between a bug and rm -r. Raw string comparison is case-sensitive: a runs root spelled
-// `C:\Users\...` against a target resolved as `c:\users\...` would put every target "outside the
-// root", and the deletion would fail with a reason that names the wrong problem.
-function targetInsideRoot(target, root) {
-  const normalizedRoot = normalizePath(root);
-  const normalizedTarget = normalizePath(target);
-  if (!normalizedRoot || !normalizedTarget) return false;
-  return normalizedTarget !== normalizedRoot && normalizedTarget.startsWith(`${normalizedRoot}/`);
-}
-
-/**
- * Refuses a target reached through a link. Independent review found that lexical containment alone
- * is satisfiable: replace `<root>/<project>` with a junction to an external directory and a target
- * that still spells out as inside the root deletes what is outside it. The package deliberately
- * does not resolve paths (`realpath` returns `\\?\` and UNC forms on Windows and creates a new
- * class of mismatch), so the check is the cheap half instead: every segment from the root down to
- * the target must be a real directory, verified with lstat right before deletion.
- */
-function linkedSegment(target, root) {
-  const normalizedRoot = normalizePath(root);
-  let current = path.resolve(target);
-  while (normalizePath(current) !== normalizedRoot) {
-    try {
-      if (fs.lstatSync(current).isSymbolicLink()) return current;
-    } catch {
-      return null; // Already gone: rmSync will report it honestly.
-    }
-    const parent = path.dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-  return null;
-}
-
 function currentTargetBytes(target, strategy) {
   if (strategy === 'purge') {
     // The inventory's recursive measurement is the same accounting used by projects and keeps
@@ -174,18 +115,21 @@ function currentTargetBytes(target, strategy) {
 }
 
 async function confirmAll(plan, args, options) {
-  const prompt = options.prompt || defaultPrompt;
   for (const action of plan.actions) {
     const question = action.strategy === 'purge'
       ? `Delete folder ${action.path}?`
       : `Delete archived transport from ${action.project}/${action.run}?\n  ${action.targets.join('\n  ')}`;
-    let answer;
+    let outcome;
     try {
-      answer = await prompt(question, action, options);
+      const prompt = options.prompt;
+      outcome = await askYesNo(question, {
+        ...options,
+        prompt: prompt ? (text) => prompt(text, action, options) : undefined,
+      });
     } catch (err) {
       return { error: `codex-bridge prune: confirmation failed: ${err.message}` };
     }
-    if (!accepted(answer)) return { declined: true };
+    if (outcome !== 'yes') return { declined: true };
   }
   return { declined: false };
 }
@@ -196,21 +140,30 @@ function bytesAfterRemoval(values) {
     : null;
 }
 
+/**
+ * Uses the shared top-down check before deletion: the old leaf-up walk inspected descendants under
+ * a link, and its catch treated every lstat error as a clear path.
+ */
 async function execute(plan, options) {
   const removed = [];
   const sizes = [];
   const failed = [];
   for (const action of plan.actions) {
     for (const target of action.targets) {
-      if (!targetInsideRoot(target, plan.root)) {
+      const inspection = inspectSegments(target, plan.root);
+      if (inspection.kind === 'outside') {
         failed.push({ target, error: 'target is outside the configured runs root' });
         continue;
       }
-      const linked = linkedSegment(target, plan.root);
-      if (linked) {
-        failed.push({ target, error: `refusing to delete through a link: ${linked}` });
+      if (inspection.kind === 'link') {
+        failed.push({ target, error: `refusing to delete through a link: ${inspection.at}` });
         continue;
       }
+      if (inspection.kind === 'error') {
+        failed.push({ target, error: `cannot inspect ${inspection.at} (${inspection.code}); nothing deleted` });
+        continue;
+      }
+      // `missing` goes on: rmSync reports the vanished target honestly, as it always did.
       const bytes = currentTargetBytes(target, action.strategy);
       try {
         fs.rmSync(target, { recursive: action.strategy === 'purge', force: false });
@@ -253,7 +206,7 @@ export async function prune(argv = [], options = {}) {
     const payload = { status: 'completed', ...basePayload(plan), removed: [], bytesFreed: 0, failed: [] };
     return result(0, output(payload, args.json));
   }
-  if (!tty(options)) {
+  if (!isInteractive(options)) {
     const message = 'No TTY: refusing deletion because deletion is an operator action; no files were changed.';
     const payload = { status: 'refused', ...basePayload(plan), error: message, removed: [], bytesFreed: 0 };
     return result(1, output(payload, args.json));
@@ -274,5 +227,3 @@ export async function prune(argv = [], options = {}) {
     ? output(executed.payload, true)
     : reportLines(executed.payload, executed.payload.status));
 }
-
-export { defaultPrompt };

package/cli/purge-live-runs.mjs

@@ -0,0 +1,98 @@
+/**
+ * Answers whether any recorded Codex run may still be executing, failing closed on anything unreadable.
+ *
+ * Plan_65 D22 item 5: purge removes the home image a live run executes from. The hook scanner's
+ * skipped read errors and fresh-heartbeat requirement cannot prove that image is unused: a hung
+ * run still holds it. Purge therefore keeps uncertainty visible and uses the single liveness judge.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonFileSync } from '../src/home/lib/json-file.mjs';
+import { runLiveness } from '../src/home/lib/meta/run-liveness.mjs';
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+import { STOP_COMMAND } from '../src/home/lib/stop-contract.mjs';
+
+function recordError(unknown, file, error) {
+  unknown.push({ path: file, reason: error.code || error.message });
+}
+
+// ENOENT is the only proof of absence: a root never created holds no runs, and a project folder
+// pruned between the root listing and its own is gone too. Every other code stays a finding.
+function readEntries(directory, unknown) {
+  try {
+    return fs.readdirSync(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code !== 'ENOENT') recordError(unknown, directory, error);
+    return [];
+  }
+}
+
+function isDirectory(entry, file, unknown) {
+  if (entry.isDirectory()) return true;
+  if (!entry.isSymbolicLink()) return false;
+  try {
+    // Plan_65 D4 forbids deleting through links, not reading their run records.
+    return fs.statSync(file).isDirectory();
+  } catch (error) {
+    if (error.code !== 'ENOENT') recordError(unknown, file, error);
+    return false;
+  }
+}
+
+function inspectRun(runDir, identityOptions, blocked, unknown) {
+  const statusPath = path.join(runDir, 'status.json');
+  let status;
+  try {
+    status = readJsonFileSync(statusPath);
+  } catch (error) {
+    // Lifecycle step 10 writes status first; old folders without it are not recorded runs.
+    if (error.cause instanceof SyntaxError) {
+      unknown.push({ path: statusPath, reason: 'invalid JSON' });
+    } else if (error.code !== 'ENOENT') {
+      recordError(unknown, statusPath, error);
+    }
+    return;
+  }
+  if (!status || typeof status !== 'object' || Array.isArray(status)) {
+    unknown.push({ path: statusPath, reason: 'status.json is not a plain object' });
+    return;
+  }
+  if (status.state !== 'running') return;
+  try {
+    if (runLiveness({ ...identityOptions, runDir, status }).processMayBeAlive === true) {
+      blocked.push({
+        runDir,
+        agent: status.agent,
+        slug: status.slug,
+        stop: `${STOP_COMMAND} "${runDir}"`,
+      });
+    }
+  } catch (error) {
+    recordError(unknown, statusPath, error);
+  }
+}
+
+export function inspectLiveRuns({ root = runsRoot(), ...identityOptions } = {}) {
+  const blocked = [];
+  const unknown = [];
+  for (const project of readEntries(root, unknown)) {
+    const projectDir = path.join(root, project.name);
+    if (!isDirectory(project, projectDir, unknown)) continue;
+    for (const run of readEntries(projectDir, unknown)) {
+      const runDir = path.join(projectDir, run.name);
+      if (isDirectory(run, runDir, unknown)) inspectRun(runDir, identityOptions, blocked, unknown);
+    }
+  }
+  const verdict = blocked.length ? 'blocked' : unknown.length ? 'unknown' : 'clear';
+  return { verdict, blocked, unknown };
+}
+
+export function liveRunLines(result) {
+  if (result.verdict === 'clear') return [];
+  return [
+    ...result.blocked.map(({ runDir, stop }) => `Live run ${path.basename(runDir)}: ${stop}`),
+    ...result.unknown.map(({ path: file, reason }) =>
+      `Could not read ${file} (${reason}): purge cannot prove no run is live.`),
+  ];
+}
+

package/cli/purge-preflight.mjs

@@ -0,0 +1,103 @@
+/**
+ * Holds purge's one set of refusal checks: under a live ticket it asks both consents and mints
+ * the executor's authorization; for a dry run it only reports.
+ *
+ * Plan_65 D12 items 5-6 and D14 require one ordered check inside the lifecycle transaction:
+ * live runs, installation inventory, inventory consent, then separate data consent. The executor
+ * consumes its result instead of checking again, so permission cannot outlive or change its plan.
+ */
+import path from 'node:path';
+import { assertLiveTicket } from './lifecycle-transaction.mjs';
+import { askPurgeConsent } from './inventory-removal.mjs';
+import { inspectLiveRuns, liveRunLines } from './purge-live-runs.mjs';
+import { buildHomeRemovalPlan } from './home-removal-plan.mjs';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+
+const authorizations = new WeakMap();
+
+// D14 item 2: this is THE live-run step, reached only as the default liveRunCheck of
+// runPurgePreflight and diagnosePurge. Plan_74 replaces it alone with the admission gate.
+export function checkLiveRuns() {
+  return inspectLiveRuns();
+}
+
+function freezePlan(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) freezePlan(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+const refused = (line) => ({ verdict: 'refused', lines: [line] });
+
+export function planRefusals(plan, host) {
+  if (plan.homeRoot === 'error') {
+    return [`Could not read ${host.brandRoot}: purge cannot inventory the home.`];
+  }
+  if (plan.recordState === 'corrupt') {
+    return [`The installation record of ${host.brandRoot} is unreadable: purge cannot tell who uses this home.`];
+  }
+
+  const ownerKey = normalizeRepoPath(host.root);
+  const otherOwners = plan.recordState === 'valid'
+    ? Object.keys(plan.format2.owners).filter((root) => root !== ownerKey)
+    : [];
+  return otherOwners.map((root) => `${root} is recorded as using ${host.brandRoot}; uninstall it first.`);
+}
+
+export function purgeDataFiles(plan) {
+  return plan.rows.filter((row) => row.removal === 'purge-only' && row.action === 'remove')
+    .map((row) => row.relative).sort();
+}
+
+export async function diagnosePurge({ host, packageRoot, liveRunCheck = checkLiveRuns }) {
+  const liveRuns = await liveRunCheck();
+  const plan = await buildHomeRemovalPlan({
+    command: 'purge', host, packageRoot, imagePolicy: { remove: true, reason: 'purge' },
+  });
+  return {
+    refusals: [...liveRunLines(liveRuns), ...planRefusals(plan, host)], plan, dataFiles: purgeDataFiles(plan),
+  };
+}
+
+export async function runPurgePreflight({ host, ticket, packageRoot, options = {}, liveRunCheck = checkLiveRuns }) {
+  assertLiveTicket(ticket, host);
+  const liveRuns = await liveRunCheck();
+  if (liveRuns.verdict !== 'clear') return { verdict: 'refused', lines: liveRunLines(liveRuns) };
+
+  const plan = await buildHomeRemovalPlan({
+    command: 'purge', host, packageRoot, imagePolicy: { remove: true, reason: 'purge' },
+  });
+  const lines = planRefusals(plan, host);
+  if (lines.length) return { verdict: 'refused', lines };
+
+  const ownerKey = normalizeRepoPath(host.root);
+  const inventoryConsent = await askPurgeConsent(host, 'inventory', options);
+  if (inventoryConsent === 'cancel') return { verdict: 'cancelled' };
+  if (inventoryConsent === 'no') {
+    return refused(`Purge needs your confirmation that no other host uses ${host.brandRoot}.`);
+  }
+
+  const dataFiles = purgeDataFiles(plan);
+  const dataConsent = await askPurgeConsent(host, 'data', options, dataFiles);
+  if (dataConsent === 'cancel') return { verdict: 'cancelled' };
+  if (dataConsent === 'no') {
+    return refused(`Purge needs your consent to delete your data in ${host.brandRoot}.`);
+  }
+
+  freezePlan(plan);
+  const authorization = Object.freeze({});
+  authorizations.set(authorization, { home: path.resolve(host.brandRoot), ownerKey, ticket, plan });
+  return { verdict: 'authorized', plan, authorization };
+}
+
+export function consumePurgeAuthorization(authorization, host, plan) {
+  const entry = authorizations.get(authorization);
+  if (!entry) throw new Error('purge requires its preflight authorization (Plan_65 D12 item 6)');
+  // D14: every attempt consumes the capability, including a stale ticket or wrong plan/home.
+  authorizations.delete(authorization);
+  assertLiveTicket(entry.ticket, host);
+  if (path.resolve(host.brandRoot) !== entry.home) throw new Error('purge authorization belongs to a different home');
+  if (entry.plan !== plan) throw new Error('purge authorization was granted for a different plan');
+}

package/cli/read.mjs

@@ -1,12 +1,13 @@
 /** Renders a run's structured Codex transport as a readable event-by-event report. */
 import { readEvents } from '../src/home/lib/meta/events.mjs';
+import { safeSlice } from '../src/home/lib/meta/paths.mjs';
 import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
 import { resolveRunFolder } from './run-lookup.mjs';
 
 const result = (exitCode, output) => ({ exitCode, output });
 const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
 
-const inline = (value, max = 300) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+const inline = (value, max = 300) => safeSlice(String(value ?? '').replace(/\s+/g, ' ').trim(), max);
 
 function compactJson(value, max = 300) {
   let text;

package/cli/record-removal.mjs

@@ -0,0 +1,43 @@
+/**
+ * Removes files listed in an installation record through the home adapter, so uninstall and update
+ * cannot remove an unregistered path from the package home.
+ */
+import fs from 'node:fs/promises';
+import { createHomeWriter } from '../src/home/lib/home-write.mjs';
+import { recordTarget } from './install-record.mjs';
+import { claudeBoundary, removeEmptyParents, removeEmptyHomeParents } from './remove-layout.mjs';
+import { inspectSegments } from './link-segments.mjs';
+
+export function recordHomeWriter(host, files) {
+  const imageMembers = files.filter((entry) => entry.root === 'brand').map((entry) => entry.path);
+  return createHomeWriter({ root: host.brandRoot, imageMembers });
+}
+
+export async function removeRecordedFile(host, writer, entry) {
+  const target = recordTarget(host, entry);
+  if (entry.root === 'brand') {
+    // Plan_65 D4 item 4 covers unlink too: a real file can sit beneath a junction.
+    const finding = inspectSegments(target, host.brandRoot);
+    if (finding.kind !== 'clear' && finding.kind !== 'missing') return { kept: finding };
+    if (finding.kind === 'clear') {
+      try {
+        await writer.unlink('install-image', target);
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw err;
+      }
+    }
+    // A file already gone still gets its emptied parents taken down: a repeated uninstall after a
+    // partial one must finish the folders the first run left. The segments were just checked, so a
+    // link the walk finds now is a race; it stops the walk, and the file's own outcome is reported.
+    await removeEmptyHomeParents(writer, 'install-image', target, host.brandRoot);
+  } else {
+    await removeOutside(writer, target);
+    await removeEmptyParents(target, claudeBoundary(host, target));
+  }
+  return { kept: null };
+}
+
+export async function removeOutside(writer, target) {
+  writer.assertOutside(target);
+  await fs.rm(target, { force: true });
+}

package/cli/removal-outcomes.mjs

@@ -0,0 +1,115 @@
+/**
+ * Turns home removal outcomes, or a plan for a dry run, into the lines and exit code the operator sees.
+ *
+ * Plan_65 D12 item 7 requires actual counts and named keeps: planned removal must not claim
+ * that edited image files disappeared, or confuse removing an owner with deleting its record.
+ */
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+
+const unsafeReason = (reason) => reason.startsWith('link') || reason.startsWith('unreadable');
+// An image file kept by content evidence is named; one kept by policy (another owner, an incomplete
+// inventory) is not — that would print ~90 lines the caller explains in one sentence.
+const EVIDENCE_KEEP = new Set(['changed', 'link']);
+const namedKeep = (entry) => unsafeReason(entry.reason) || entry.id === null
+  || (entry.id === 'install-image' && EVIDENCE_KEEP.has(entry.reason));
+const artifactsLine = () => `Run artifacts in ${runsRoot()} are outside uninstall and stay.`;
+
+function fileLines(files, host, dryRun) {
+  const lines = [];
+  const removing = dryRun ? 'remove' : 'removed';
+  const verb = dryRun ? 'Would remove' : 'Removed';
+  const removed = files.filter((entry) => entry.result === removing);
+  const images = removed.filter((entry) => entry.id === 'install-image').length;
+  const data = removed.length - images;
+  if (images > 0) lines.push(`${verb} ${images} image file(s) from ${host.brandRoot}.`);
+  if (data > 0) lines.push(`${verb} ${data} data file(s) from ${host.brandRoot}.`);
+  for (const entry of files) {
+    if ((entry.result === 'kept' || entry.result === 'blocked') && namedKeep(entry)) {
+      lines.push(`${dryRun ? 'Would leave' : 'Left'} brand/${entry.relative} (${entry.reason})`);
+    }
+  }
+  const retained = files.filter((entry) => entry.result === 'kept' && entry.reason === 'purge-only');
+  if (retained.length > 0) {
+    const paths = retained.map((entry) => entry.relative).sort().join(', ');
+    const location = `in ${host.brandRoot} for --purge: ${paths}`;
+    lines.push(`${dryRun ? 'Would keep' : 'Kept'} ${retained.length} operator file(s) ${location}`);
+  }
+  for (const entry of files) {
+    if (entry.result === 'failed') lines.push(`Could not remove brand/${entry.relative}: ${entry.reason}`);
+  }
+  return lines;
+}
+
+function recordLines(record, host) {
+  if (record.result === 'removed') return [`Removed the installation record of ${host.brandRoot}.`];
+  if (record.result === 'failed') return [`Could not remove brand/${record.relative}: ${record.reason}`];
+  if (record.result !== 'kept') return [];
+  if (record.reason === 'this host removed from the record') {
+    return [`Removed ${host.root} from the installation record of ${host.brandRoot}; the shared image stays.`];
+  }
+  if (record.reason === 'this host is still attached') {
+    return [`Kept ${host.root} in the installation record because its hooks could not be removed.`];
+  }
+  return [`Kept the installation record of ${host.brandRoot} (${record.reason}).`];
+}
+
+export function outcomeLines(outcomes, { host }) {
+  const files = outcomes.filter((entry) => entry.kind === 'file');
+  const record = outcomes.find((entry) => entry.kind === 'record');
+  const lines = fileLines(files, host, false);
+  if (record) lines.push(...recordLines(record, host));
+  for (const entry of outcomes.filter((candidate) => candidate.kind === 'directory')) {
+    if (entry.relative === '' && entry.result === 'removed') {
+      lines.push(`Removed ${host.brandRoot}.`);
+    } else if (entry.result === 'kept') {
+      lines.push(`Left brand/${entry.relative}/ (${entry.reason})`);
+    } else if (entry.result === 'failed') {
+      lines.push(`Could not remove brand/${entry.relative}/: ${entry.reason}`);
+    }
+  }
+  lines.push(artifactsLine());
+  return lines;
+}
+
+export function outcomeExitCode(outcomes) {
+  return outcomes.some((entry) => entry.result === 'blocked' || entry.result === 'failed'
+    || (entry.result === 'kept' && unsafeReason(entry.reason))) ? 1 : 0;
+}
+
+export function planExitCode(plan) {
+  return plan.blocked || plan.rows.some((row) => (row.action === 'keep' || row.action === 'blocked')
+    && unsafeReason(row.reason)) ? 1 : 0;
+}
+
+export function planLines(plan, { host, detached = true }) {
+  const files = plan.rows.map((row) => ({ ...row, result: row.action === 'keep' ? 'kept' : row.action }));
+  const lines = fileLines(files, host, true);
+  if (plan.record.dependsOnDetach && detached === false) {
+    lines.push(`Would keep ${host.root} in the installation record because its hooks could not be removed.`);
+  } else if (plan.record.operation === 'delete') {
+    lines.push(`Would remove the installation record of ${host.brandRoot}.`);
+  } else if (plan.record.operation === 'remove-current-owner') {
+    lines.push(`Would remove ${host.root} from the installation record of ${host.brandRoot}; the shared image stays.`);
+  } else if (plan.record.operation === 'retain') {
+    lines.push(`Would keep the installation record of ${host.brandRoot} (${plan.record.reason})`);
+  }
+  lines.push(artifactsLine());
+  return lines;
+}
+
+export function purgeDryRunLines({ refusals, plan, dataFiles }, { host }) {
+  if (plan.homeRoot === 'missing' && refusals.length === 0) {
+    return [`Nothing to purge: ${host.brandRoot} does not exist.`, artifactsLine()];
+  }
+  const lines = [];
+  if (refusals.length) lines.push('A real purge would refuse:', ...refusals.map((line) => `  ${line}`));
+  const question = `A real purge would ask two questions: whether any other host uses ${host.brandRoot}`;
+  lines.push(`${question}, and whether to delete your data in it.`);
+  if (dataFiles.length) lines.push(`Your data it would ask about: ${dataFiles.join(', ')}`);
+  lines.push('If you confirm both questions:', ...planLines(plan, { host }));
+  return lines;
+}
+
+export function purgeDryRunExitCode({ refusals, plan }) {
+  return refusals.length ? 1 : planExitCode(plan);
+}