@logicseek/hello-cc 1.0.0 → 1.0.1

package/scripts/regression.mjs

@@ -26,6 +26,7 @@ const outDir = path.join(os.tmpdir(), `hcc-reg-out-${testId}`);
 const tmuxSession = `hcc-reg-${process.pid}`;
 const tmuxSocketName = `hcc-reg-${testId}`.replace(/[^A-Za-z0-9_-]/g, '-');
 const secondProjectRoot = path.join(root, 'second-project');
+const TERMINAL_WEBSOCKET_TIMEOUT_MS = 15_000;
 const realHome = process.env.HOME || os.homedir();
 const realRegistryFile = path.join(realHome, '.hello-cc', 'projects.json');
 const realTmuxBin = spawnSync('sh', ['-lc', 'command -v tmux || true'], {
@@ -432,6 +433,13 @@ async function assertTmuxGcPolicy() {
   managedTmuxSessions.add(rootEventSession);
   managedTmuxSessions.add(manualSession);
 
+  // Create the one runtime-managed authority before the bulk synthetic tmux
+  // fixtures. Leaving the runtime up while those sessions are created lets its
+  // five-second orphan scan adopt them and contend with this start on slow CI.
+  const eventActivePane = parsePane(hcc(['peer', 'start', eventPeer, '--kind', 'shell', '--', 'bash', '--noprofile', '--norc']));
+  const eventActiveSession = run('tmux', ['display-message', '-p', '-t', eventActivePane, '#{session_name}']).trim();
+  await stopRuntime();
+
   run('tmux', ['new-session', '-d', '-s', staleSession, '-e', `HCC_ROOT=${root}`, '-c', root, 'bash', '--noprofile', '--norc']);
   run('tmux', ['new-session', '-d', '-s', peerFilterSession, '-e', `HCC_ROOT=${root}`, '-c', root, 'bash', '--noprofile', '--norc']);
   run('tmux', ['new-session', '-d', '-s', attachedSession, '-e', `HCC_ROOT=${root}`, '-c', root, 'bash', '--noprofile', '--norc']);
@@ -489,10 +497,27 @@ async function assertTmuxGcPolicy() {
   insertRuntimeTargetBinding(deadBindingPeer, 'shell', 'tmux-gc-binding-dead-session', deadBindingPane);
   insertRuntimeTargetBinding(reusedBindingPeer, 'shell', 'tmux-gc-binding-reused-session', reusedBindingPane);
   insertRuntimeTargetBinding(clientUnknownBindingPeer, 'shell', 'tmux-gc-binding-client-unknown-session', clientUnknownBindingPane);
-  const eventActivePane = parsePane(hcc(['peer', 'start', eventPeer, '--kind', 'shell', '--', 'bash', '--noprofile', '--norc']));
-  const eventActiveSession = run('tmux', ['display-message', '-p', '-t', eventActivePane, '#{session_name}']).trim();
   withMeshDb((db) => {
     const t = Math.floor(Date.now() / 1000) - 30 * 86400;
+    for (const [peer, pane] of [
+      [stalePeer, stalePane],
+      [peerFilterPeer, peerFilterPane],
+      [attachedPeer, attachedPane],
+      [deadBindingPeer, deadBindingPane],
+      [reusedBindingPeer, reusedBindingPane],
+      [clientUnknownBindingPeer, clientUnknownBindingPane]
+    ]) {
+      db.prepare(`
+        UPDATE peer_bindings
+        SET transport = 'tmux', runtime_target = ?, updated_at = ?
+        WHERE peer = ?
+      `).run(pane, t, peer);
+    }
+    db.prepare(`
+      UPDATE peer_bindings
+      SET transport = 'tmux', runtime_target = ?
+      WHERE peer = ?
+    `).run(eventActivePane, eventPeer);
     db.prepare('UPDATE peers SET last_seen_at = ? WHERE id IN (?, ?, ?)').run(t, stalePeer, peerFilterPeer, attachedPeer);
     db.prepare("UPDATE peers SET status = 'exited' WHERE id IN (?, ?)").run(stalePeer, peerFilterPeer);
     db.prepare('UPDATE peer_bindings SET updated_at = ? WHERE peer IN (?, ?, ?)').run(t, stalePeer, peerFilterPeer, attachedPeer);
@@ -1582,7 +1607,10 @@ async function expectWebSocketMarker(peer, marker) {
     let sawSnapshot = false;
     let sawMarker = false;
     const ws = new WebSocket(runtimeWsUrl(peer), runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} websocket timeout`)), 5000);
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} websocket timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('open', () => {
       const result = hccMaybe(['inject', peer, `echo ${marker}`]);
       if (result.status !== 0) reject(new Error(result.stderr || result.stdout || 'inject failed'));
@@ -1599,14 +1627,17 @@ async function expectWebSocketMarker(peer, marker) {
         resolve();
       }
     });
-    ws.on('error', reject);
+    ws.on('error', (err) => { clearTimeout(timer); reject(err); });
   });
 }
 
 async function openTerminalWebSocket(peer) {
   return new Promise((resolve, reject) => {
     const ws = new WebSocket(runtimeWsUrl(peer), runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} websocket open timeout`)), 5000);
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} websocket open timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('open', () => {
       clearTimeout(timer);
       resolve(ws);
@@ -1627,7 +1658,10 @@ async function openSessionActionChannel(peer, params = {}) {
       if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
     }
     const ws = new WebSocket(url, runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} action token fetch timeout`)), 5000);
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} action token fetch timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('message', (raw) => {
       const msg = JSON.parse(String(raw));
       if (msg.type === 'snapshot') {
@@ -1668,7 +1702,10 @@ async function fetchTerminalSnapshot(peer, params = {}) {
       if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
     }
     const ws = new WebSocket(url, runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} terminal snapshot timeout`)), 5000);
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} terminal snapshot timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('message', (raw) => {
       const msg = JSON.parse(String(raw));
       if (msg.type !== 'snapshot') return;
@@ -1886,7 +1923,10 @@ async function expectResizeReplaceSnapshot(peer, marker) {
   await new Promise((resolve, reject) => {
     let sawSnapshot = false;
     const ws = new WebSocket(runtimeWsUrl(peer), runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} resize replace timeout`)), 5000);
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} resize replace timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('open', () => {
       const result = hccMaybe(['inject', peer, `echo ${marker}`]);
       if (result.status !== 0) reject(new Error(result.stderr || result.stdout || 'inject failed'));
@@ -1903,7 +1943,7 @@ async function expectResizeReplaceSnapshot(peer, marker) {
         resolve();
       }
     });
-    ws.on('error', reject);
+    ws.on('error', (err) => { clearTimeout(timer); reject(err); });
   });
 }
 
@@ -1915,7 +1955,10 @@ async function expectWebSocketInputVisible(peer, marker) {
     let sawFrameAfterInput = false;
     let actionToken = '';
     const ws = new WebSocket(runtimeWsUrl(peer), runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} websocket input visibility timeout`)), 5000);
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} websocket input visibility timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('message', (raw) => {
       const msg = JSON.parse(String(raw));
       const data = String(msg.data || '');
@@ -1938,7 +1981,7 @@ async function expectWebSocketInputVisible(peer, marker) {
         resolve();
       }
     });
-    ws.on('error', reject);
+    ws.on('error', (err) => { clearTimeout(timer); reject(err); });
   });
 }
 
@@ -4031,6 +4074,10 @@ async function multiProjectWebWorkflow() {
         !arbitraryRuntime.process_identity?.commandHash) {
       fail(`project API runtime pointer omitted the shared runtime fingerprint:\n${JSON.stringify(arbitraryRuntime, null, 2)}`);
     }
+    const arbitraryBufs = path.join(arbitraryRoot, '.hello-cc', 'bufs');
+    if (fs.existsSync(arbitraryBufs)) {
+      fail('project registration eagerly created the optional buffer directory');
+    }
     fs.rmSync(path.join(arbitraryRoot, '.hello-cc'), { recursive: true, force: true });
     await sleep(1250);
     if (fs.existsSync(path.join(arbitraryRoot, '.hello-cc'))) {
@@ -5277,50 +5324,6 @@ async function statusServer(status) {
   };
 }
 
-async function stalledRuntimeServer(phase) {
-  const child = spawn(process.execPath, ['-e', `
-    const http = require('node:http');
-    const sockets = new Set();
-    const server = http.createServer((req, res) => {
-      if (${JSON.stringify(phase)} === 'body') {
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.write('{"deleted":0');
-      }
-    });
-    server.on('connection', (socket) => {
-      sockets.add(socket);
-      socket.on('close', () => sockets.delete(socket));
-    });
-    server.listen(0, '127.0.0.1', () => process.stdout.write(String(server.address().port) + '\\n'));
-    process.on('SIGTERM', () => {
-      for (const socket of sockets) socket.destroy();
-      server.close(() => process.exit(0));
-    });
-  `], { stdio: ['ignore', 'pipe', 'inherit'] });
-  const port = await new Promise((resolve, reject) => {
-    let output = '';
-    const timer = setTimeout(() => reject(new Error(`timed out starting ${phase} stalled runtime`)), 5000);
-    child.stdout.on('data', (chunk) => {
-      output += chunk;
-      const match = output.match(/^(\d+)\n/);
-      if (!match) return;
-      clearTimeout(timer);
-      resolve(Number(match[1]));
-    });
-    child.once('exit', (code) => {
-      clearTimeout(timer);
-      reject(new Error(`${phase} stalled runtime exited early with ${code}`));
-    });
-  });
-  return {
-    baseUrl: `http://127.0.0.1:${port}`,
-    close: async () => {
-      child.kill('SIGTERM');
-      try { await waitForProcessExit(child.pid, `${phase} stalled runtime exit`, 3000); } catch {}
-    }
-  };
-}
-
 function bufferGcCanonicalizationRaceWorkflow() {
   for (const phase of ['before', 'after']) {
     const raceRoot = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-buffer-gc-realpath-${phase}-${testId}-`));
@@ -5445,7 +5448,10 @@ async function bufferGcArbitrationWorkflow() {
   if (!firstApply.ok || replayApply.ok) fail('buffer GC token was not exactly once');
 
   const cutoffMs = Date.now() - 60_000;
-  const oldTime = new Date(cutoffMs - 60_000);
+  // Ordinary deletion checks use a non-zero retention window so crossing a
+  // wall-clock second cannot legitimately activate clock-jump protection.
+  const stableGcRetentionDays = 1;
+  const oldTime = new Date(Date.now() - 2 * 86400_000);
   const rootBufs = path.join(root, '.hello-cc', 'bufs');
   const siblingBufs = path.join(secondProjectRoot, '.hello-cc', 'bufs');
   fs.mkdirSync(rootBufs, { recursive: true });
@@ -5586,7 +5592,9 @@ async function bufferGcArbitrationWorkflow() {
   const parentAlias = path.join(aliasContainer, 'parent');
   fs.symlinkSync(path.dirname(secondProjectRoot), parentAlias);
   const siblingAliasRoot = path.join(parentAlias, path.basename(secondProjectRoot));
-  const gcOutput = hccFrom(['--json', 'gc', '--older-than', '0', '--yes'], siblingAliasRoot);
+  const gcOutput = hccFrom([
+    '--json', 'gc', '--older-than', String(stableGcRetentionDays), '--yes'
+  ], siblingAliasRoot);
   fs.rmSync(aliasContainer, { recursive: true, force: true });
   const gcPayload = JSON.parse(gcOutput);
   const result = gcPayload.data || {};
@@ -5609,7 +5617,9 @@ async function bufferGcArbitrationWorkflow() {
   } finally {
     rootGcClockDb.close();
   }
-  const rootGcPayload = JSON.parse(hcc(['--json', 'gc', '--older-than', '0', '--yes']));
+  const rootGcPayload = JSON.parse(hcc([
+    '--json', 'gc', '--older-than', String(stableGcRetentionDays), '--yes'
+  ]));
   const rootGcResult = rootGcPayload.data || {};
   if (rootGcResult.buf_files !== 1 || rootGcResult.protected_buf_files < liveFiles.length ||
       rootGcResult.deferred_buf_files < legacyFiles.length || fs.existsSync(rootOrphan)) {
@@ -5735,7 +5745,9 @@ async function bufferGcArbitrationWorkflow() {
   const normalOrphan = path.join(siblingBufs, `gc-actual-dir-normal-${testId}.out`);
   fs.writeFileSync(normalOrphan, 'actual directory normal baseline');
   fs.utimesSync(normalOrphan, oldTime, oldTime);
-  const normalGc = JSON.parse(hccFrom(['--json', 'gc', '--older-than', '0', '--yes'], secondProjectRoot)).data;
+  const normalGc = JSON.parse(hccFrom([
+    '--json', 'gc', '--older-than', String(stableGcRetentionDays), '--yes'
+  ], secondProjectRoot)).data;
   if (fs.existsSync(gapOrphan) || fs.existsSync(normalOrphan) || Number(normalGc.buf_files || 0) < 2) {
     fail(`actual runtime buffer directory did not delete against a live baseline: ${JSON.stringify(normalGc)}`);
   }
@@ -5812,42 +5824,6 @@ async function bufferGcArbitrationWorkflow() {
     }
   }
 
-  for (const phase of ['headers', 'body']) {
-    const isolatedRoot = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-buffer-gc-stall-${phase}-${testId}-`));
-    const isolatedHome = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-buffer-gc-stall-home-${phase}-${testId}-`));
-    let server = null;
-    try {
-      const isolatedEnv = { ...env, HOME: isolatedHome };
-      run(process.execPath, [hccBin, '--root', isolatedRoot, 'init', '--no-guidance'], { env: isolatedEnv });
-      const directory = path.join(isolatedRoot, '.hello-cc', 'bufs');
-      fs.mkdirSync(directory, { recursive: true });
-      const orphan = path.join(directory, 'old-orphan.out');
-      fs.writeFileSync(orphan, 'orphan');
-      fs.utimesSync(orphan, oldTime, oldTime);
-      server = await stalledRuntimeServer(phase);
-      fs.writeFileSync(path.join(isolatedRoot, '.hello-cc', 'runtime.json'), JSON.stringify({
-        pid: process.pid,
-        base_url: server.baseUrl,
-        token: 'regression-token'
-      }));
-
-      const startedAt = Date.now();
-      const gc = run(process.execPath, [hccBin, '--root', isolatedRoot, '--json', 'gc', '--older-than', '0', '--yes'], { env: isolatedEnv });
-      const elapsedMs = Date.now() - startedAt;
-      const payload = JSON.parse(gc);
-      if (elapsedMs >= 9000 ||
-          Number(payload.data?.buf_files || 0) !== 0 ||
-          Number(payload.data?.deferred_buf_files || 0) < 1 ||
-          !fs.existsSync(orphan)) {
-        fail(`runtime ${phase} stall did not fail closed within deadline (${elapsedMs}ms): ${gc}`);
-      }
-    } finally {
-      await server?.close();
-      fs.rmSync(isolatedRoot, { recursive: true, force: true });
-      fs.rmSync(isolatedHome, { recursive: true, force: true });
-    }
-  }
-
   const localRoot = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-buffer-gc-local-${testId}-`));
   const localHome = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-buffer-gc-local-home-${testId}-`));
   try {
@@ -5991,9 +5967,24 @@ async function tmuxBackedStartWorkflow() {
   if (!restoredAuthority?.payload?.tmux_session_created || !restoredAuthority?.payload?.tmux_session_id) {
     fail(`startup auto GC left no complete immutable tmux authority: ${JSON.stringify({ authorityBindingAfterStop, restoredAuthority })}`);
   }
-  withMeshDb((db) => db.prepare('UPDATE events SET created_at = ? WHERE id = ?')
-    .run(oldAuthorityAt, restoredAuthority.id));
-  hcc(['gc', '--older-than', '14', '--yes']);
+  const authorityGcNow = Math.floor(Date.now() / 1000);
+  withMeshDb((db) => {
+    db.prepare('UPDATE events SET created_at = ? WHERE id = ?')
+      .run(oldAuthorityAt, restoredAuthority.id);
+    // Backdating the fixture must not itself look like a real wall-clock jump.
+    // Establish the same current baseline used by the other explicit GC tests.
+    db.prepare("DELETE FROM meta WHERE key IN ('clock_grace_until', 'clock_pending_gap')").run();
+    db.prepare(`
+      INSERT INTO meta(key, value) VALUES ('clock_last_observed_at', ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `).run(String(authorityGcNow));
+  });
+  // This assertion exercises manual history pruning. Request it explicitly
+  // instead of racing the runtime's asynchronous startup auto-GC.
+  const authorityGc = JSON.parse(hcc(['--json', 'gc', '--older-than', '14', '--history', '--yes']));
+  if (authorityGc.data?.deferred_age_based || Number(authorityGc.data?.deferred_old_events || 0) !== 0) {
+    fail(`tmux authority history GC was unexpectedly deferred: ${JSON.stringify(authorityGc.data)}`);
+  }
   const authorityRowsAfterFullGc = withMeshDb((db) => db.prepare(`
     SELECT id FROM events
     WHERE type = 'tmux.session.attached'
@@ -9726,6 +9717,10 @@ function uninstallWorkflow() {
 
 async function processEvidenceWorkflow() {
   log('process evidence: live, reused, legacy, dead, root mismatch');
+  // These fixtures deliberately backdate peers beyond the production reaper's
+  // grace window. Keep the runtime stopped until the external-adoption cases so
+  // a 30-second scheduler tick cannot turn an evidence snapshot into exited.
+  await stopRuntime();
 
   const createOwnedTask = (peer, title) => {
     const output = hcc(['task', 'create', '--from', 'human', '--to', peer, '--title', title]);
@@ -9831,6 +9826,8 @@ async function processEvidenceWorkflow() {
     cleanupBindingPeers(rootPeer);
   }
 
+  startRuntime();
+  await waitRuntime();
   const externalDir = path.join(root, '.hello-cc', 'bufs');
   const shortExternalId = `evidence-external-short-${testId}`;
   const shortProducer = spawn(process.execPath, [

package/docs/architecture-split-review.md

@@ -1,217 +0,0 @@
-# Architecture Split Review
-
-Date: 2026-06-14
-
-This review covers the local commits on `master` that are ahead of
-`origin/master` after `0.1.5`.
-
-It is written from the separate review branch
-`arch-review/split-layout-from-origin`. The main worktree is intentionally left
-untouched because other peers may still be finishing scoped implementation work.
-
-## Recommendation
-
-Keep the current architecture direction. Do not merge the new product-boundary
-modules back into `bin/hcc.mjs`, and do not collapse them into another large
-generic helper file.
-
-If the goal is to publish or synchronize soon, keep the current local commit
-history and add one or more cleanup commits. Those cleanup commits should focus
-on remaining boundary issues and compatibility-shim policy.
-
-If the goal is clean commit history, rebuild the stack in a separate worktree
-from `origin/master`. Do not rewrite the active `master` worktree while peers
-are coordinating through it.
-
-## What Happened
-
-The first local split commits were mostly flat helper extraction from
-`bin/hcc.mjs` into top-level `lib/*.mjs` files. They reduced the entrypoint size
-but did not yet express the product architecture:
-
-- provider and tmux helpers
-- lock and team planning helpers
-- peer identity, peer format, and peer binding helpers
-- project registry and project context helpers
-- handoff, timeline, runtime state, task liveness, automation, and render helpers
-- help text, message store, runtime request, task store, task CLI, and
-  coordination-state helpers
-
-Later commits introduced `docs/architecture.md` and started moving primary
-implementations into product boundaries:
-
-- `lib/core/coordination`
-- `lib/core/peers`
-- `lib/core/sessions`
-- `lib/db`
-- `lib/db/stores`
-- `lib/runtime`
-- `lib/terminal`
-- `lib/web`
-- `lib/integrations`
-- `lib/release`
-- `lib/shared`
-- `lib/ui`
-
-That second phase is the correct direction.
-
-## Keep
-
-These boundaries are worth keeping as the primary implementation shape:
-
-- `lib/core/coordination/*` for product coordination semantics.
-- `lib/core/peers/*` for pure peer semantics.
-- `lib/db/schema.mjs` and `lib/db/stores/*` for SQLite schema and stores.
-- `lib/runtime/*` for runtime files, runtime client access, project registry,
-  and project context.
-- `lib/terminal/tmux.mjs` for tmux adapter behavior.
-- `lib/web/*` for Web runtime, HTTP helpers, peer actions, and UI template.
-- `lib/integrations/*` for provider, hook, shim, and process integration
-  details.
-- `lib/release/*` for release metadata and release-note logic.
-- `lib/shared/*` only for small dependency-light utilities.
-- `lib/ui/*` for text/help/state rendering.
-
-## Cleanup Candidates
-
-The remaining cleanup should be deliberate, not another broad helper extraction.
-
-### Top-Level Compatibility Shims
-
-Many top-level `lib/*.mjs` files are now compatibility re-export shims. Examples
-include `lib/tmux.mjs`, `lib/provider-commands.mjs`, `lib/web-runtime.mjs`,
-`lib/web-http.mjs`, `lib/web-ui-template.mjs`, `lib/task-store.mjs`,
-`lib/messages.mjs`, `lib/locks.mjs`, `lib/db-schema.mjs`, and
-`lib/session-launch.mjs`.
-
-Before publish:
-
-- Treat the installed CLI commands as the public API. Do not document new
-  `@logicseek/hello-cc/lib/*` imports as user-facing API.
-- `@logicseek/hello-cc@0.1.5` is already published from git head `4969100`, and
-  that package exposed several top-level `lib/*.mjs` helper paths because the
-  package includes `lib/` and has no `exports` map.
-- Keep already-published top-level `lib/*.mjs` paths as compatibility
-  re-exports for at least one release cycle unless the project explicitly
-  chooses a breaking package-surface change.
-- For compatibility shims added only in local commits after `0.1.5`, either
-  remove them before the next publish or document them in the release notes as
-  compatibility-only and revisit removal before the following release.
-- Do not let compatibility shims become the target architecture. Primary
-  implementations should live under the product-boundary directories.
-
-Classify top-level shims before release:
-
-- Group A: already-published or CLI-facing helper paths that stay stable for
-  this release.
-- Group B: migration compatibility paths that re-export moved implementations;
-  keep only if needed and describe them as compatibility-only deep-import paths.
-- Group C: unpublished shims with no internal use and no compatibility value;
-  remove before publishing.
-
-### CLI Boundary
-
-`bin/hcc.mjs` is smaller but still mixes command dispatch, command handlers, Web
-startup, session lifecycle, and terminal/Web orchestration. Future work should
-move by command or subsystem boundary, not by helper name.
-
-Good next boundaries:
-
-- `lib/cli/args.mjs`
-- `lib/cli/context.mjs`
-- `lib/cli/dispatch.mjs`
-- `lib/cli/commands/*`
-
-### Regression Runner
-
-`scripts/regression.mjs` has grown too large. It should become a runner over
-domain-specific files:
-
-- `scripts/regression/cli.mjs`
-- `scripts/regression/db.mjs`
-- `scripts/regression/runtime.mjs`
-- `scripts/regression/web.mjs`
-- `scripts/regression/integrations.mjs`
-- `scripts/regression/release.mjs`
-
-This should be done after the current layout work is stable, because regression
-coverage is the safety net for the refactor.
-
-### Setup, Discover, Guidance, and Shims
-
-`lib/setup.mjs`, `lib/discover.mjs`, `lib/guidance.mjs`, and
-`lib/shim-script.mjs` still carry mixed responsibilities. Continue splitting
-these by product boundary:
-
-- hooks under `lib/integrations/hooks*`
-- shims under `lib/integrations/shims*`
-- shell and terminal adapters under `lib/terminal`
-- runtime/project concerns under `lib/runtime`
-- guidance text generation under `lib/ui` or a dedicated guidance boundary
-
-### Handoff Boundary
-
-`lib/handoff.mjs` is still a top-level helper. Decide whether it belongs in
-`lib/core/coordination/handoff.mjs` as product semantics or under
-`lib/cli/commands/handoff.mjs` if it is mostly CLI formatting and file listing.
-
-## Branch Strategy
-
-Use one of two paths.
-
-Path A: publish-oriented cleanup
-
-1. Keep current `master` history.
-2. Add focused cleanup commits.
-3. Run full regression, release checks, GitHub release dry-run, and pack dry-run.
-4. Publish/synchronize only after the cleanup decision is complete.
-
-Path B: clean-history rebuild
-
-1. Keep `master` untouched.
-2. Use a separate worktree from `origin/master`.
-3. Rebuild the split as fewer architectural commits:
-   - architecture docs
-   - core coordination and peer semantics
-   - db schema/stores
-   - runtime/project/session helpers
-   - terminal adapters
-   - web runtime and UI
-   - integrations providers/hooks/shims
-   - release/shared/ui helpers
-   - regression restructuring
-4. Run full regression and release checks before replacing the active stack.
-
-## Current Decision
-
-The safer default is Path A: keep current history and add cleanup commits.
-
-Choose Path B only if the project explicitly values a clean local commit stack
-more than the time and risk of rebuilding and revalidating the entire series.
-
-The current safety refs are:
-
-- `safety/layout-split-20260614-at-ffc42a7`, protecting the earlier split stack.
-- `safety/layout-split-20260614-at-11fd4f6`, protecting the split stack through
-  `11fd4f6` before this package-surface policy update.
-
-Because `0.1.5` is already on npm, the next publish that includes the current
-local commits must bump the package version. Do not republish `0.1.5`.
-
-## Coordination Notes
-
-Continue finishing any already-started layout lanes that are clearly correcting
-the architecture boundary. For example, moving setup hooks and shim
-implementation into `lib/integrations` is still part of the same boundary
-cleanup, not a new random helper extraction.
-
-After those active lanes finish, pause new implementation splits and make a
-cleanup decision:
-
-1. Decide whether this review document should be copied into `master` as a
-   durable design record.
-2. Decide whether top-level compatibility shims are public for this release.
-3. If shims are kept, document that they are compatibility paths.
-4. If shims are removed, do it before publish and run full pack/release checks.
-5. Do not start broad `bin/hcc.mjs` command extraction or regression runner
-   splitting until the shim policy is settled.