@logicseek/hello-cc 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -16,6 +16,83 @@ the release description from the current changelog section. Use
 `npm run release:github` with `GH_TOKEN` or `GITHUB_TOKEN` only for local
 backfills.
 
+## 1.0.1
+
+### Summary
+
+hello-cc 1.0.1 is a file-lock determinism, buffer-GC safety, fresh-install, and
+release-reliability patch. It makes worker shutdown reclaim kernel lock
+endpoints deterministically when an identity probe keeps its client write half
+open, restores real PTY startup in fresh macOS npm installations, and keeps
+automatic GC fail-closed when optional buffer paths disappear or change.
+
+### Highlights
+
+- The socket-lock worker now tracks each locally accepted socket and destroys
+  those accepted handles during server shutdown, so release no longer depends
+  on the peer closing its writable half after reading the lock banner.
+- A real half-open identity-probe regression verifies that release returns
+  promptly, a nonblocking reacquisition succeeds immediately, and the probe is
+  explicitly stopped and awaited during final cleanup.
+- `node-pty` is exactly pinned to `1.2.0-beta.15`. The stable `node-pty 1.1.0`
+  npm artifact contains non-executable Darwin helpers, which makes a fresh
+  macOS install fail with `posix_spawnp failed`; the selected artifact publishes
+  both Darwin helpers with executable modes.
+- Linux, macOS, and WSL installation instructions now list Node.js 24, tmux
+  commands for the major system package managers, CLI verification, and safe
+  handling for npm global-install permission errors.
+- `hcc down` now waits for the exact Runtime process identity to exit before it
+  reports success, including safe handling for PID reuse and a bounded timeout
+  when shutdown cannot be confirmed.
+- Background Web startup keeps its immediate child-exit failure but allows a
+  bounded 60-second health window, avoiding false failures on loaded macOS CI
+  hosts where process identity and project restoration can exceed 30 seconds.
+- Manual buffer GC allows a bounded 30-second window for runtime evidence
+  planning and apply, while still deferring all eligible files if the runtime
+  remains unavailable.
+- Automatic GC now treats a missing `.hello-cc/bufs` leaf as empty without
+  recreating it. A missing state directory, a symlinked path component, an
+  inode replacement, or a retargeted project-root alias fails closed with
+  `PROJECT_PATH_FORBIDDEN` before buffer, clock, lock, or history mutation.
+- Buffer path identity is retained through evidence collection, lease
+  acquisition, planning, clock reads, and database transactions. GC uses a
+  no-create lease while existing file-lock callers retain their original
+  parent-creation behavior.
+- Per-connection Web action tokens now require their issuing terminal socket to
+  still be open, closing the handshake race before asynchronous token cleanup.
+- Runtime request deadlines now reach the underlying HTTP transport, and peer
+  start/attach preflight and mutation requests use a bounded 60-second window
+  while stop and terminal-input operations use 30 seconds, instead of all
+  inheriting the shorter read-request default.
+
+### Compatibility Notes
+
+- No CLI command or package-surface behavior changes are intended. Schema v7,
+  Runtime API v2, the authenticated browser's ability to choose any existing
+  server directory as a project root, and the 1.0.0 accepted-risk boundaries
+  are unchanged.
+- Stable project-root aliases remain supported. Only path disappearance,
+  replacement, symlink traversal, or alias retargeting during GC is rejected.
+- The existing five-second fail-closed deadline and cleanup-error behavior are
+  unchanged.
+- `node-pty@1.2.0-beta.15` is a bounded prerelease dependency risk. The exact
+  pin prevents unreviewed beta movement, and release tests verify the installed
+  version, regular-file identity, executable modes, and a real PTY. There is no
+  postinstall or CI-only `chmod` workaround.
+
+### Validation
+
+The 1.0.1 release gate includes repeated macOS Node 24 tests; a no-cache Linux
+Node 24/tmux image build followed by three complete `npm test` runs in that same
+image, each ending with `FULL_REGRESSION_OK`; and a fourth clean container that
+installs the same 1.0.1 package tarball and passes PTY, database, Web, and
+missing-buffer GC smoke checks. Fresh macOS consumer installs pass both normal
+and `--ignore-scripts` installation, proving that executable helper modes come
+from the package artifact rather than lifecycle-script mutation. GC regression
+coverage includes absent optional leaves, symlink and ancestor replacement,
+alias retargeting, no-create lock acquisition, and path guards around clock and
+history writes.
+
 ## 1.0.0
 
 ### Summary

package/README.md

@@ -70,10 +70,42 @@ currently supported; use WSL for a Linux-like environment.
 Linux has richer process auto-discovery through `/proc`. On macOS, use
 hello-cc shims or `hcc peer start` for reliable tmux-managed terminal sessions.
 
+Install Node.js 24 or newer from the official Node.js packages or a Node
+version manager. Then install `tmux` for your platform:
+
+```bash
+# Debian / Ubuntu
+sudo apt-get update && sudo apt-get install -y tmux
+# Fedora / RHEL
+sudo dnf install -y tmux
+# Older RHEL / CentOS
+sudo yum install -y tmux
+# Alpine
+sudo apk add tmux
+# Arch Linux
+sudo pacman -S --needed tmux
+# openSUSE
+sudo zypper install tmux
+# macOS only
+brew install tmux
+```
+
+On Linux, use the distribution package manager; Homebrew is only the macOS
+command above. Root shells can omit `sudo`. In WSL, run the matching Linux
+distribution commands inside WSL. Then install and verify hello-cc:
+
 ```bash
 npm install -g @logicseek/hello-cc
+node --version
+npm --version
+tmux -V
+hcc --version
+hcc --help
 ```
 
+If npm reports `EACCES`, use a Node version manager or a user-owned npm prefix;
+do not work around it with `sudo npm install -g`.
+
 Update an existing global install:
 
 ```bash

package/README.zh-CN.md

@@ -57,10 +57,41 @@ hello-cc 支持 Linux 和 macOS。需要 Node.js 24 或更新版本；可被浏
 Linux 可以通过 `/proc` 做更完整的进程自动发现。macOS 上建议通过 hello-cc
 shim 或 `hcc peer start` 启动会话，以获得可靠的 tmux 托管终端。
 
+先通过 Node.js 官方软件包或 Node 版本管理器安装 Node.js 24 或更新版本，再按
+系统安装 `tmux`：
+
+```bash
+# Debian / Ubuntu
+sudo apt-get update && sudo apt-get install -y tmux
+# Fedora / RHEL
+sudo dnf install -y tmux
+# 旧版 RHEL / CentOS
+sudo yum install -y tmux
+# Alpine
+sudo apk add tmux
+# Arch Linux
+sudo pacman -S --needed tmux
+# openSUSE
+sudo zypper install tmux
+# 仅 macOS
+brew install tmux
+```
+
+Linux 必须使用当前发行版的系统包管理器，而不是 Homebrew。root shell 可以省略
+`sudo`。WSL 用户应在 WSL 内部执行对应 Linux 发行版的命令。然后安装并验证：
+
 ```bash
 npm install -g @logicseek/hello-cc
+node --version
+npm --version
+tmux -V
+hcc --version
+hcc --help
 ```
 
+如果 npm 报 `EACCES`，请使用 Node 版本管理器或用户自有的 npm prefix，不要用
+`sudo npm install -g` 绕过权限问题。
+
 更新已有的全局安装：
 
 ```bash

package/docs/guide.md

@@ -40,12 +40,70 @@ the supported downgrade contract.
 
 ## Install, Update, And Uninstall
 
+### Prerequisites
+
+Install Node.js 24 or newer from the official Node.js packages or a Node
+version manager. Browser-controllable terminals also require `tmux`:
+
+```bash
+# Debian / Ubuntu
+sudo apt-get update
+sudo apt-get install -y tmux
+# Fedora / RHEL
+sudo dnf install -y tmux
+# Older RHEL / CentOS
+sudo yum install -y tmux
+# Alpine
+sudo apk add tmux
+# Arch Linux
+sudo pacman -S --needed tmux
+# openSUSE
+sudo zypper install tmux
+# macOS only
+brew install tmux
+```
+
+On Linux, use the distribution package manager, not Homebrew. A root shell can
+omit `sudo`. WSL follows the matching Linux distribution instructions inside
+WSL; native Windows shells are not supported.
+
+`hcc web` can attempt to install tmux when a supported package manager and
+sufficient privileges are available. Manual installation is the deterministic
+choice for servers, containers, and non-interactive sudo configurations.
+
+### Install And Verify
+
 Install hello-cc globally:
 
 ```bash
 npm install -g @logicseek/hello-cc
 ```
 
+If npm reports `EACCES`, use a Node version manager or configure a user-owned
+npm prefix. Do not use `sudo npm install -g`, because it can create root-owned
+package and configuration files.
+
+Verify every prerequisite and the installed CLI:
+
+```bash
+node --version
+npm --version
+tmux -V
+hcc --version
+hcc --help
+```
+
+The Node version must start with `v24` or a newer major. Every command above
+must exit successfully before starting a managed terminal.
+
+To avoid a global install, use:
+
+```bash
+npx @logicseek/hello-cc web
+```
+
+### Update And Uninstall
+
 Update an existing global install:
 
 ```bash

package/docs/guide.zh-CN.md

@@ -36,12 +36,67 @@ v1 会把恢复的数据库重新迁移到 schema v7；用旧版本 hello-cc 打
 
 ## 安装、更新和卸载
 
+### 前置依赖
+
+通过 Node.js 官方软件包或 Node 版本管理器安装 Node.js 24 或更新版本。浏览器可
+控制的终端还需要 `tmux`：
+
+```bash
+# Debian / Ubuntu
+sudo apt-get update
+sudo apt-get install -y tmux
+# Fedora / RHEL
+sudo dnf install -y tmux
+# 旧版 RHEL / CentOS
+sudo yum install -y tmux
+# Alpine
+sudo apk add tmux
+# Arch Linux
+sudo pacman -S --needed tmux
+# openSUSE
+sudo zypper install tmux
+# 仅 macOS
+brew install tmux
+```
+
+Linux 必须使用当前发行版的系统包管理器，而不是 Homebrew。root shell 可以省略
+`sudo`。WSL 用户应在 WSL 内部按对应 Linux 发行版安装；不支持原生 Windows
+shell。
+
+当存在受支持的包管理器且权限足够时，`hcc web` 可以尝试自动安装 tmux。对于
+服务器、容器和非交互式 sudo 环境，手动安装是确定性更高的方式。
+
+### 安装和验证
+
 全局安装 hello-cc：
 
 ```bash
 npm install -g @logicseek/hello-cc
 ```
 
+如果 npm 报 `EACCES`，请使用 Node 版本管理器或配置用户自有的 npm prefix。
+不要使用 `sudo npm install -g`，否则可能产生 root 所有的包和配置文件。
+
+验证全部前置依赖和 CLI：
+
+```bash
+node --version
+npm --version
+tmux -V
+hcc --version
+hcc --help
+```
+
+Node 版本应为 `v24` 开头或更高主版本；启动托管终端前，上述命令都应成功退出。
+
+不全局安装时可以使用：
+
+```bash
+npx @logicseek/hello-cc web
+```
+
+### 更新和卸载
+
 更新已有的全局安装：
 
 ```bash

package/lib/cli/app.mjs

@@ -51,6 +51,7 @@ import { readPackageMeta } from '../package-meta.mjs';
 import { removeGuidanceBlocks as removeGuidanceBlocksForRoot, writeGuidance as writeGuidanceForRoot } from '../guidance.mjs';
 import { globalRuntimePath, runtimePath } from '../runtime/paths.mjs';
 import { readRuntime, reclaimRuntimePointerFiles } from '../runtime/state.mjs';
+import { waitForProcessIdentityExit } from '../process/identity.mjs';
 
 import { runtimeRequest } from '../runtime/client.mjs';
 
@@ -310,6 +311,7 @@ const { cmdDown, cmdFindRoot, cmdWhichReal } = createMiscCommands({
   path, fs, process, CliError, parseOpts, printResult,
   readRuntime, runtimeRequest, runtimePath, globalRuntimePath,
   reclaimRuntimePointerFiles, helpDown, loadSetup,
+  waitForProcessIdentityExit,
   PRODUCT_NAME
 });
 

package/lib/cli/commands/coordination.mjs

@@ -1,6 +1,8 @@
 // Coordination CLI commands extracted from bin/hcc.mjs: handoff, event,
 // heartbeat, ask, broadcast, inject. Factory pattern with injected deps.
 
+import { RUNTIME_SESSION_MUTATION_TIMEOUT_MS } from '../../runtime/client.mjs';
+
 export function createCoordinationCommands(deps) {
   const {
     connect,
@@ -228,7 +230,7 @@ export function createCoordinationCommands(deps) {
     return runtimeRequest(ctx, 'POST', `/api/sessions/${encodeURIComponent(peer)}/input`, {
       text,
       enter
-    }, runtime);
+    }, runtime, { timeoutMs: RUNTIME_SESSION_MUTATION_TIMEOUT_MS });
   }
 
   async function cmdInject(ctx, args) {

package/lib/cli/commands/gc.mjs

@@ -39,6 +39,8 @@ import {
 } from '../../runtime/buffer-gc.mjs';
 import { applyClockSafeBufferPlan } from '../../runtime/buffer-gc-protocol.mjs';
 
+export const RUNTIME_BUFFER_GC_TIMEOUT_MS = 30_000;
+
 export function createGcCommands(deps) {
   const {
     connect, now, helpGc,
@@ -109,7 +111,8 @@ function observeGcClockSafety(ctx, db, {
   observedAt,
   historyCategories,
   includeStalePeers,
-  historySnapshot
+  historySnapshot,
+  bufferPathGuard = null
 }) {
   try {
     return runOptimisticEvidenceMutation(db, {
@@ -124,10 +127,13 @@ function observeGcClockSafety(ctx, db, {
       }),
       observe: (subject) => observeGcEvidence(ctx, subject),
       same: (left, right) => JSON.stringify(left) === JSON.stringify(right),
-      beforeMutate: (subject, evidenceByOwner) => observeClockSafetyInTransactionOrThrow(
-        db,
-        gcClockSafetyOptions(subject, evidenceByOwner, olderThanDays)
-      ),
+      beforeMutate: (subject, evidenceByOwner) => {
+        if (bufferPathGuard) assertBufferDirectoryPathUnchanged(bufferPathGuard);
+        return observeClockSafetyInTransactionOrThrow(
+          db,
+          gcClockSafetyOptions(subject, evidenceByOwner, olderThanDays)
+        );
+      },
       changedMessage: 'GC subjects changed while clock evidence was being observed; retry',
       mutate: (subject, evidenceByOwner, observation) => ({
         ...observation,
@@ -192,6 +198,128 @@ function previewGcClockSafety(ctx, db, options) {
   }
 }
 
+function bufferDirectoryPathForbidden(message, directory) {
+  return new CliError('PROJECT_PATH_FORBIDDEN', `${message}: ${directory}`);
+}
+
+function assertBufferDirectoryPathUnchanged(captured) {
+  let resolvedRoot;
+  try {
+    resolvedRoot = fs.realpathSync.native(captured.requestedRoot);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    throw bufferDirectoryPathForbidden(
+      'Project root changed during buffer GC',
+      captured.requestedRoot
+    );
+  }
+  if (resolvedRoot !== captured.canonicalRoot) {
+    throw bufferDirectoryPathForbidden(
+      'Project root changed during buffer GC',
+      captured.requestedRoot
+    );
+  }
+  for (const component of captured.components) {
+    let current;
+    try {
+      current = fs.lstatSync(component.path);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      throw bufferDirectoryPathForbidden(
+        'Buffer directory path changed during lease acquisition',
+        captured.directory
+      );
+    }
+    if (current.isSymbolicLink() || !current.isDirectory() ||
+        current.dev !== component.stat.dev || current.ino !== component.stat.ino) {
+      throw bufferDirectoryPathForbidden(
+        'Buffer directory path changed during lease acquisition',
+        captured.directory
+      );
+    }
+  }
+  if (!captured.exists) {
+    try {
+      fs.lstatSync(captured.directory);
+    } catch (error) {
+      if (error?.code === 'ENOENT') return;
+      throw error;
+    }
+    throw bufferDirectoryPathForbidden(
+      'Buffer directory path changed during lease acquisition',
+      captured.directory
+    );
+  }
+}
+
+function captureRequiredBufferDirectoryComponent(component, description) {
+  const stat = fs.lstatSync(component);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw bufferDirectoryPathForbidden(`${description} must be a real directory`, component);
+  }
+  return { path: component, stat };
+}
+
+function captureOptionalBufferDirectory(root, directoryName) {
+  const requestedRoot = path.resolve(root);
+  const canonicalRoot = fs.realpathSync.native(requestedRoot);
+  const stateDirectory = path.join(canonicalRoot, '.hello-cc');
+  const directory = path.join(stateDirectory, directoryName);
+  const components = [
+    captureRequiredBufferDirectoryComponent(canonicalRoot, 'Project root'),
+    captureRequiredBufferDirectoryComponent(stateDirectory, 'Project state directory')
+  ];
+
+  let stat;
+  try {
+    stat = fs.lstatSync(directory);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      const captured = {
+        requestedRoot,
+        canonicalRoot,
+        directory,
+        components,
+        exists: false
+      };
+      assertBufferDirectoryPathUnchanged(captured);
+      return captured;
+    }
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw bufferDirectoryPathForbidden('Buffer directory must be a real directory', directory);
+  }
+  components.push({ path: directory, stat });
+  return { requestedRoot, canonicalRoot, directory, components, exists: true };
+}
+
+function collectGuardedBufferEvidence(collector, captured) {
+  const evidence = collector(captured.directory);
+  assertBufferDirectoryPathUnchanged(captured);
+  return evidence;
+}
+
+function withOptionalBufferDirectoryLease(captured, callback) {
+  assertBufferDirectoryPathUnchanged(captured);
+  if (!captured.exists) return null;
+  return withBufferDirectoryLease(captured.directory, (leasedDirectory) => {
+    const assertDirectoryUnchanged = () => {
+      assertBufferDirectoryPathUnchanged(captured);
+      if (fs.realpathSync.native(captured.directory) !== leasedDirectory) {
+        throw bufferDirectoryPathForbidden(
+          'Buffer directory path changed during lease acquisition',
+          captured.directory
+        );
+      }
+    };
+    assertDirectoryUnchanged();
+    const result = callback(leasedDirectory, assertDirectoryUnchanged);
+    assertDirectoryUnchanged();
+    return result;
+  }, { createParent: false });
+}
+
 function runGc(ctx, db, {
   olderThanDays = 7,
   dryRun = false,
@@ -203,6 +331,9 @@ function runGc(ctx, db, {
   history = false,
   observedAt = null
 } = {}) {
+  const bufferPathGuard = skipBufferFiles
+    ? null
+    : captureOptionalBufferDirectory(ctx.root, BUFS_DIR_NAME);
   const auto = scope === 'auto';
   const historyCategories = auto ? ['events'] : ['events', 'tasks', 'messages', 'handoffs'];
   const applyHistory = auto || history;
@@ -213,16 +344,19 @@ function runGc(ctx, db, {
     : gcNow * 1000 - (auto ? Math.min(olderThanDays, 7) : olderThanDays) * 86400000;
   const bufferRetentionSec = (auto ? Math.min(olderThanDays, 7) : olderThanDays) * 86400;
   const preparedBufferEvidence = !skipBufferFiles && collectBufferEvidenceNow
-    ? collectBufferEvidenceNow()
+    ? collectGuardedBufferEvidence(collectBufferEvidenceNow, bufferPathGuard)
     : null;
-  const bufferGcCutoffs = bufferDirectoryPaths(bufferDirectory(ctx)).flatMap((file) => {
-    try {
-      const stat = fs.lstatSync(file);
-      return [Math.max(0, Math.floor(stat.mtimeMs / 1000) + bufferRetentionSec)];
-    } catch {
-      return [];
-    }
-  });
+  const bufferGcCutoffs = skipBufferFiles
+    ? []
+    : bufferDirectoryPaths(bufferPathGuard.directory).flatMap((file) => {
+        try {
+          const stat = fs.lstatSync(file);
+          return [Math.max(0, Math.floor(stat.mtimeMs / 1000) + bufferRetentionSec)];
+        } catch {
+          return [];
+        }
+      });
+  if (bufferPathGuard) assertBufferDirectoryPathUnchanged(bufferPathGuard);
   bufferGcCutoffs.push(...(preparedBufferEvidence?.gcCutoffs || []));
   const historySnapshot = createHistoryGcSnapshot(db, gcNow - retentionSec, {
     categories: historyCategories,
@@ -245,7 +379,8 @@ function runGc(ctx, db, {
       bufferGcCutoffs,
       historyCategories,
       gcNow,
-      historySnapshot
+      historySnapshot,
+      bufferPathGuard
     }),
     'History GC run'
   );
@@ -266,6 +401,7 @@ function runGcWithHistorySnapshot(ctx, db, {
   historyCategories,
   gcNow,
   historySnapshot,
+  bufferPathGuard = null,
   clockObservation: preparedClockObservation = null,
   forceDefer = false
 }) {
@@ -275,17 +411,23 @@ function runGcWithHistorySnapshot(ctx, db, {
     observedAt: gcNow,
     historyCategories,
     includeStalePeers: !auto,
-    historySnapshot
+    historySnapshot,
+    bufferPathGuard
   });
   const graceActive = forceDefer || clockGraceSuppressed(gcNow, clockObservation.graceUntil);
   let databaseGraceActive = graceActive;
   const beforeDatabaseMutate = () => {
+    if (bufferPathGuard) assertBufferDirectoryPathUnchanged(bufferPathGuard);
     if (databaseGraceActive) return false;
     try {
       const observedAt = now();
       const allowed = !clockGraceSuppressed(observedAt, readClockGraceUntil(db));
-      if (!allowed) databaseGraceActive = true;
-      return allowed;
+      if (!allowed) {
+        databaseGraceActive = true;
+        return false;
+      }
+      if (bufferPathGuard) assertBufferDirectoryPathUnchanged(bufferPathGuard);
+      return true;
     } catch (error) {
       if (error instanceof CliError) throw error;
       throw clockSafetyUnavailable(error);
@@ -325,14 +467,16 @@ function runGcWithHistorySnapshot(ctx, db, {
   const bufCutoffMs = Number.isFinite(bufferCutoffMs)
     ? bufferCutoffMs
     : gcNow * 1000 - (auto ? Math.min(olderThanDays, 7) : olderThanDays) * 86400000;
-  const bufsDir = path.join(ctx.root, '.hello-cc', BUFS_DIR_NAME);
   if (!graceActive && !skipBufferFiles) {
-    const bufferResult = withBufferDirectoryLease(bufsDir, () => {
+    const bufferResult = withOptionalBufferDirectoryLease(bufferPathGuard, (
+      leasedBufsDir,
+      assertDirectoryUnchanged
+    ) => {
       const currentEvidence = collectBufferEvidenceNow
-        ? collectBufferEvidenceNow()
+        ? collectGuardedBufferEvidence(collectBufferEvidenceNow, bufferPathGuard)
         : preparedBufferEvidence || { protectedPaths: protectedBuffers, unknownPaths: new Set(), gcCutoffs: [] };
       const currentPlan = planBufferFiles({
-        directories: [bufsDir],
+        directories: [leasedBufsDir],
         cutoffMs: bufCutoffMs,
         protectedPaths: currentEvidence.protectedPaths,
         unknownPaths: currentEvidence.unknownPaths,
@@ -341,12 +485,16 @@ function runGcWithHistorySnapshot(ctx, db, {
           ...(currentEvidence.gcCutoffs || [])
         ]
       });
+      assertDirectoryUnchanged();
       const currentObservedAt = now();
-      const currentObservation = tx(db, () => observeClockSafetyInTransaction(db, {
-        operation: 'gc',
-        gcCutoffs: bufferPlanGcCutoffs(currentPlan, bufferRetentionSec),
-        nowSec: currentObservedAt
-      }));
+      const currentObservation = tx(db, () => {
+        assertDirectoryUnchanged();
+        return observeClockSafetyInTransaction(db, {
+          operation: 'gc',
+          gcCutoffs: bufferPlanGcCutoffs(currentPlan, bufferRetentionSec),
+          nowSec: currentObservedAt
+        });
+      });
       if (clockGraceSuppressed(currentObservedAt, currentObservation.graceUntil)) {
         databaseGraceActive = true;
         return deferBufferPlan(currentPlan);
@@ -360,9 +508,11 @@ function runGcWithHistorySnapshot(ctx, db, {
       }
       return applyBufferPlan(currentPlan);
     });
-    results.buf_files = bufferResult.deleted;
-    results.protected_buf_files = bufferResult.protected;
-    results.deferred_buf_files = bufferResult.deferred;
+    if (bufferResult !== null) {
+      results.buf_files = bufferResult.deleted;
+      results.protected_buf_files = bufferResult.protected;
+      results.deferred_buf_files = bufferResult.deferred;
+    }
   }
 
   // A clock jump can make every lock look expired at once. Preserve those rows
@@ -589,7 +739,7 @@ async function prepareManualBufferGc(ctx, db, { retentionSec, dryRun }) {
         phase: 'prepare',
         retentionSec,
         dryRun
-      }, runtime, { timeoutMs: 5000 });
+      }, runtime, { timeoutMs: RUNTIME_BUFFER_GC_TIMEOUT_MS });
       return {
         mode: 'runtime',
         runtime,
@@ -668,7 +818,7 @@ async function applyManualBufferGc(ctx, db, prepared, { dryRun, graceActive }) {
     const applied = await runtimeRequest(ctx, 'POST', '/api/runtime/gc-buffers', {
       phase: 'apply',
       token: prepared.token
-    }, prepared.runtime, { timeoutMs: 5000 });
+    }, prepared.runtime, { timeoutMs: RUNTIME_BUFFER_GC_TIMEOUT_MS });
     const counts = requireBufferGcResult(applied);
     if (typeof applied?.complete !== 'boolean' || typeof applied?.graceActive !== 'boolean') {
       throw new CliError('RUNTIME_BAD_RESPONSE', 'Runtime buffer GC returned invalid completion state');