Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Use a native macOS image probe with bounded discovery fallback (#670)

Deec6e95924936d
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ddb720d01..71a9240d9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -162,6 +162,40 @@ jobs:
- name: Agent startup through the system zsh login shell
run: npx vitest run src/lib/engineShellStartup.spec.ts
+ # Build both slices and execute each host architecture. All process/tmux
+ # fixtures are private; no installed agent or running session is controlled.
+ process-images-native:
+ if: ${{ contains(fromJSON('["full","cli"]'), inputs.scope || 'full') }}
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [macos-15, macos-15-intel]
+ runs-on: ${{ matrix.os }}
+ timeout-minutes: 10
+ defaults:
+ run:
+ working-directory: cli
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-node@v7
+ with:
+ node-version: 22.23.2
+ cache: npm
+ cache-dependency-path: cli/package-lock.json
+ - run: npm ci --no-audit --no-fund
+ - run: command -v tmux || brew install tmux
+ - name: Read-only kernel probe, universal signing and byte-safe protocol
+ run: python3 native/test_process_images.py
+ - name: Build the embedded universal artifact
+ run: python3 scripts/build-process-images.py --output "$RUNNER_TEMP/process-images.json"
+ - name: Bundled native discovery, exec replacement and private tmux cleanup
+ env:
+ HARNESS_PROCESS_IMAGES_ARTIFACT: ${{ runner.temp }}/process-images.json
+ RUN_DARWIN_PROCESS_IMAGES: '1'
+ run: |
+ node scripts/test-process-images-bundled.mjs
+ npx vitest run src/lib/nativeProcessImages.spec.ts src/lib/processImages.spec.ts src/lib/processImages.real.spec.ts --maxWorkers=1
+
# Typecheck and contract checks run alongside the default suite's four shards.
cli-contracts:
if: ${{ contains(fromJSON('["full","cli"]'), inputs.scope || 'full') }}
@@ -225,6 +259,9 @@ jobs:
- run: npx tsc --noEmit
+ - name: Native helper build-input and portable bundle contracts
+ run: node --test scripts/test-process-image-bundle.mjs
+
# The guard fuzz suite measures a wall-clock CPU budget. Sibling workers running
# subprocess fixtures can deschedule it past that bound on a shared runner.
# Keep it outside the default-suite shards, with the same assertions and deadline.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index d43d5ff6d..d2c3051fa 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -22,8 +22,9 @@ name: Release
# key, so it points each at its own scratch file and merges once at the end. The CLI is ONE
# platform-independent bundle under ONE key, published by ONE job — the race the desktop
# designs around cannot occur here, so inventing a merge step would be ceremony.
-# * NO signing or notarization. The artifacts are two JavaScript files; integrity is the sha256
-# in the manifest, which selfUpdate.ts verifies in memory before it writes anything to disk.
+# * The two published artifacts remain JavaScript. cli.js embeds a universal,
+# ad-hoc-signed macOS process probe. Both its pinned digest and the manifest's
+# whole-bundle digest are checked before any extracted helper is executed.
#
# cli/scripts/upload-cli.sh is used EXACTLY as it is, with no flag this file invented: GCS_BUCKET,
# METADATA_PATH and OTA_KEY are env overrides it already supports. The script is the production
@@ -138,7 +139,24 @@ jobs:
echo "$GITHUB_RUN_ID" | gcloud storage cp - "$probe"
gcloud storage rm "$probe"
- # No vitest gate here. The full suite (ci.yml) runs on pull requests — but NOTE that ci.yml has no
+ # Produce the optional-at-runtime probe from this exact release source. CI
+ # exercises both host architectures; this job packages both in one JS bundle.
+ process-images:
+ needs: version
+ runs-on: macos-15
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@v7
+ - name: Build and verify universal read-only process probe
+ run: python3 cli/scripts/build-process-images.py --output "$RUNNER_TEMP/process-images.json"
+ - uses: actions/upload-artifact@v4
+ with:
+ name: process-images
+ path: ${{ runner.temp }}/process-images.json
+ if-no-files-found: error
+ retention-days: 1
+
+ # No vitest gate here. The full suite (ci.yml) runs on demand — but NOTE that ci.yml has no
# `push` trigger and main also takes direct pushes, so a tagged commit has NOT necessarily been
# through it. What stands between a tag and the fleet is exactly what `publish` runs itself:
# `tsc --noEmit` below (esbuild only strips types, it never checks them) and upload-cli.sh's own
@@ -147,7 +165,7 @@ jobs:
# the one thing cheap enough to keep in front of a publish that every daemon installs within a
# minute and that cannot be undone.
publish:
- needs: [version, preflight]
+ needs: [version, preflight, process-images]
runs-on: ubuntu-latest
timeout-minutes: 20
env:
@@ -155,9 +173,16 @@ jobs:
# dry run it is the scratch manifest nothing polls.
METADATA_PATH: ${{ needs.version.outputs.metadata_path }}
VERSION: ${{ needs.version.outputs.version }}
+ HARNESS_PROCESS_IMAGES_ARTIFACT: ${{ github.workspace }}/.process-images/process-images.json
+ HARNESS_REQUIRE_PROCESS_IMAGES: '1'
steps:
- uses: actions/checkout@v7
+ - uses: actions/download-artifact@v4
+ with:
+ name: process-images
+ path: .process-images
+
- uses: actions/setup-node@v7
with:
# THE runtime pin — the managed Node the shipped CLI actually executes on (see the same
diff --git a/cli/build-bundle.mjs b/cli/build-bundle.mjs
index cca5fa72b..430f5d7d6 100644
--- a/cli/build-bundle.mjs
+++ b/cli/build-bundle.mjs
@@ -1,6 +1,7 @@
/**
- * Release build: bundle the whole CLI into ONE self-contained `dist/cli.js` (all deps are pure-JS, so
- * a single artifact runs on every OS under the user's Node) + copy the standalone hook script.
+ * Release build: bundle the whole CLI into ONE self-contained `dist/cli.js`
+ * that runs on every OS under the user's Node, plus the standalone hook script.
+ * The optional macOS image probe is embedded as pinned bytes in that same JS.
*
* Version is baked in via esbuild `define(__ADAPTER_VERSION__)`, sourced from `ADAPTER_VERSION`
* (set by scripts/upload-cli.sh) else package.json — so the running binary's version EXACTLY
@@ -15,6 +16,7 @@ import { readDshRegistry } from './scripts/lib/dshRegistry.mjs'
import { readBuiltinBundle, readHarnessMonitorBundle, readModelManagerBundle } from './scripts/lib/modelManagerBundle.mjs'
import { plateWorkerSource } from './scripts/lib/plateWorker.mjs'
import { memoryWorkerSource } from './scripts/lib/memoryWorker.mjs'
+import { readProcessImageBundle } from './scripts/lib/processImageBundle.mjs'
import { fileURLToPath } from 'node:url'
const modelManagerBundle = JSON.stringify(readModelManagerBundle(fileURLToPath(new URL('../store/agents/autonomous-grid', import.meta.url))))
const devicesBundle = JSON.stringify(readBuiltinBundle(fileURLToPath(new URL('../store/agents/devices', import.meta.url)), ['harness.json', 'AGENTS.md', 'LICENSE', 'template']))
@@ -30,6 +32,10 @@ const dshRegistry = JSON.stringify(readDshRegistry(new URL('../store', import.me
// since the release is this one file.
const plateWorker = await plateWorkerSource({ minify: true })
const memoryWorker = await memoryWorkerSource({ minify: true })
+const processImages = readProcessImageBundle({
+ path: process.env.HARNESS_PROCESS_IMAGES_ARTIFACT,
+ required: process.env.HARNESS_REQUIRE_PROCESS_IMAGES === '1',
+})
// Start clean so no stale per-file `dist/*.js` / sourcemaps leak into the release artifact.
rmSync('dist', { recursive: true, force: true })
@@ -50,6 +56,7 @@ await esbuild.build({
__HARNESS_MONITOR_BUNDLE__: JSON.stringify(harnessMonitorBundle),
__PLATE_WORKER__: JSON.stringify(plateWorker),
__MEMORY_WORKER__: JSON.stringify(memoryWorker),
+ __DARWIN_PROCESS_IMAGES__: processImages ? JSON.stringify(processImages) : 'undefined',
},
// The copyright line is MIT's one condition — it has to travel with the copy the user actually
// receives, and the published bundle IS that copy (upload-cli.sh ships `cli.js` and `notify.mjs`,
diff --git a/cli/native/darwin-process-images.c b/cli/native/darwin-process-images.c
new file mode 100644
index 000000000..08b3992d1
--- /dev/null
+++ b/cli/native/darwin-process-images.c
@@ -0,0 +1,102 @@
+/*
+ * Read-only macOS executable-image probe. No process arguments or environment
+ * are read. PID/birth and a repeated path read bracket each result; callers
+ * retain their normal process-reader fallback for any unavailable identity.
+ *
+ * stdout is versioned JSON lines. Paths are hex-encoded filesystem bytes, not
+ * interpolated JSON or assumed UTF-8. A consumer must validate them before use.
+ */
+#include <errno.h>
+#include <limits.h>
+#include <locale.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include <libproc.h>
+#include <sys/proc_info.h>
+
+#define MAX_PIDS 4096
+
+static int parse_pid(const char *text, pid_t *pid) {
+ if (!text || !*text) return 0;
+ /* Reject signs, whitespace and nondecimal forms before strtol. */
+ for (const char *p = text; *p; ++p) {
+ if (*p < '0' || *p > '9') return 0;
+ }
+ errno = 0;
+ char *end = NULL;
+ long value = strtol(text, &end, 10);
+ if (errno || !end || *end || value <= 0 || value > INT_MAX) return 0;
+ *pid = (pid_t)value;
+ return 1;
+}
+
+static int birth(pid_t pid, struct proc_bsdinfo *info) {
+ memset(info, 0, sizeof(*info));
+ return proc_pidinfo(pid, PROC_PIDTBSDINFO, 0, info, sizeof(*info)) == sizeof(*info)
+ && info->pbi_pid == (uint32_t)pid && info->pbi_start_tvsec > 0;
+}
+
+static int image_path(pid_t pid, char *path, size_t capacity, size_t *length) {
+ memset(path, 0, capacity);
+ int count = proc_pidpath(pid, path, (uint32_t)capacity);
+ if (count <= 0 || (size_t)count >= capacity || path[0] != '/') return 0;
+ size_t size = strnlen(path, capacity);
+ if (!size || size >= capacity) return 0;
+ *length = size;
+ return 1;
+}
+
+static void print_hex(const unsigned char *value, size_t size) {
+ static const char digits[] = "0123456789abcdef";
+ for (size_t i = 0; i < size; ++i) {
+ putchar(digits[value[i] >> 4]);
+ putchar(digits[value[i] & 15]);
+ }
+}
+
+static void print_image(pid_t pid) {
+ struct proc_bsdinfo before, after;
+ char first[PROC_PIDPATHINFO_MAXSIZE], second[PROC_PIDPATHINFO_MAXSIZE];
+ size_t first_size = 0, second_size = 0;
+ char marker[32];
+ struct tm started;
+ if (!birth(pid, &before)
+ || !image_path(pid, first, sizeof(first), &first_size)
+ || !image_path(pid, second, sizeof(second), &second_size)
+ || !birth(pid, &after)
+ || before.pbi_start_tvsec != after.pbi_start_tvsec
+ || before.pbi_start_tvusec != after.pbi_start_tvusec
+ || first_size != second_size || memcmp(first, second, first_size) != 0) {
+ printf("{\"pid\":%d,\"unavailable\":true}\n", pid);
+ return;
+ }
+ time_t seconds = (time_t)before.pbi_start_tvsec;
+ if (seconds < 0 || (uint64_t)seconds != before.pbi_start_tvsec
+ || !localtime_r(&seconds, &started)
+ || !strftime(marker, sizeof(marker), "%a %b %e %H:%M:%S %Y", &started)) {
+ printf("{\"pid\":%d,\"unavailable\":true}\n", pid);
+ return;
+ }
+ /* LC_TIME is fixed below, so this marker contains only the ps date grammar. */
+ printf("{\"pid\":%d,\"startMarker\":\"%s\",\"startSeconds\":%llu,"
+ "\"startMicros\":%llu,\"imageHex\":\"", pid, marker,
+ (unsigned long long)before.pbi_start_tvsec,
+ (unsigned long long)before.pbi_start_tvusec);
+ print_hex((const unsigned char *)first, first_size);
+ puts("\"}");
+}
+
+int main(int argc, char **argv) {
+ if (argc < 3 || argc > MAX_PIDS + 2 || strcmp(argv[1], "--paths") != 0) return 64;
+ pid_t pids[MAX_PIDS];
+ for (int i = 2; i < argc; ++i) {
+ if (!parse_pid(argv[i], &pids[i - 2])) return 64;
+ }
+ if (!setlocale(LC_TIME, "C")) return 69;
+ puts("{\"schema\":1,\"mode\":\"paths\"}");
+ for (int i = 0; i < argc - 2; ++i) print_image(pids[i]);
+ return ferror(stdout) || fflush(stdout) ? 74 : 0;
+}
diff --git a/cli/native/test_process_images.py b/cli/native/test_process_images.py
new file mode 100644
index 000000000..452e09d8d
--- /dev/null
+++ b/cli/native/test_process_images.py
@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Native protocol, packaging, race rejection and disposable-process checks."""
+import base64
+import hashlib
+import json
+import os
+from pathlib import Path
+import select
+import subprocess
+import sys
+import tempfile
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SOURCE = ROOT / 'native/darwin-process-images.c'
+BUILDER = ROOT / 'scripts/build-process-images.py'
+STUB = r'''
+#include <errno.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+#include <libproc.h>
+#include <sys/proc_info.h>
+
+static unsigned births, paths;
+static int scenario(const char *name) {
+ const char *value = getenv("PROBE_FIXTURE_CASE");
+ return value && strcmp(value, name) == 0;
+}
+int fixture_proc_pidinfo(int pid, int flavor, uint64_t arg, void *buffer, int size) {
+ (void)flavor; (void)arg;
+ if (scenario("denied")) { errno = EPERM; return 0; }
+ if (scenario("short-info")) return size - 1;
+ struct proc_bsdinfo *info = buffer;
+ memset(info, 0, sizeof(*info));
+ info->pbi_pid = (uint32_t)(pid + (scenario("pid-mismatch") ? 1 : 0));
+ info->pbi_start_tvsec = scenario("bad-start") ? 0 : 1770000000;
+ info->pbi_start_tvusec = scenario("pid-reused") ? ++births : 123456;
+ return sizeof(*info);
+}
+int fixture_proc_pidpath(int pid, void *buffer, uint32_t size) {
+ (void)pid; ++paths;
+ if (scenario("missing-second-path") && paths == 2) return 0;
+ if (scenario("truncated-path")) { memset(buffer, 'a', size); return (int)size; }
+ const char *value = scenario("relative-path") ? "relative"
+ : scenario("exec-changed") && paths == 2 ? "/changed"
+ : scenario("raw-path") ? "/raw/quote\" line\n slash\\ byte\xff"
+ : "/fixture/probe";
+ size_t length = strlen(value);
+ if (length >= size) return 0;
+ memcpy(buffer, value, length + 1);
+ return (int)length;
+}
+'''
+
+
+def command(argv, **kwargs):
+ return subprocess.run(argv, check=True, capture_output=True, timeout=30, **kwargs)
+
+
[email protected](sys.platform == 'darwin', 'macOS process APIs are required')
+class ProcessImagesTest(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ cls.temporary = tempfile.TemporaryDirectory(prefix='harness-process-images-test-')
+ cls.root = Path(cls.temporary.name).resolve()
+ cls.addClassCleanup(cls.temporary.cleanup)
+ artifact = cls.root / 'artifact.json'
+ command([sys.executable, str(BUILDER), '--output', str(artifact)])
+ cls.artifact = json.loads(artifact.read_text())
+ cls.probe = cls.root / 'probe'
+ data = base64.b64decode(cls.artifact['base64'], validate=True)
+ if hashlib.sha256(data).hexdigest() != cls.artifact['sha256']:
+ raise AssertionError('Artifact checksum mismatch')
+ cls.probe.write_bytes(data)
+ cls.probe.chmod(0o700)
+ stub = cls.root / 'stub.c'
+ stub.write_text(STUB)
+ cls.stub = cls.root / 'stub-probe'
+ command(['/usr/bin/xcrun', 'clang', '-std=c11', '-Wall', '-Wextra', '-Werror',
+ '-Dproc_pidinfo=fixture_proc_pidinfo', '-Dproc_pidpath=fixture_proc_pidpath',
+ str(SOURCE), str(stub), '-o', str(cls.stub)])
+ sleeper = cls.root / 'sleeper.c'
+ sleeper.write_text('#include <stdio.h>\n#include <unistd.h>\n'
+ 'int main(void) { puts("ready"); fflush(stdout); '
+ 'char c; while (read(0, &c, 1) > 0) {} return 0; }\n')
+ cls.sleeper = cls.root / 'renamed 引擎 2.9.0'
+ command(['/usr/bin/xcrun', 'clang', '-Wall', '-Wextra', '-Werror',
+ str(sleeper), '-o', str(cls.sleeper)])
+
+ def setUp(self):
+ self.children = []
+ self.addCleanup(self.stop_children)
+
+ def stop_children(self):
+ for child in self.children:
+ if child.poll() is None:
+ child.terminate()
+ for child in self.children:
+ try:
+ child.wait(timeout=5)
+ except subprocess.TimeoutExpired:
+ child.kill()
+ child.wait(timeout=5)
+ for stream in [child.stdin, child.stdout, child.stderr]:
+ if stream:
+ stream.close()
+
+ def launch(self, argv):
+ child = subprocess.Popen(argv, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE)
+ self.children.append(child)
+ return child
+
+ def wait_ready(self, child):
+ self.assertTrue(select.select([child.stdout], [], [], 5)[0], 'Fixture failed to become ready')
+ self.assertEqual(child.stdout.readline(), b'ready\n')
+
+ def probe_pids(self, pids, *, stub=False, case='stable'):
+ result = command([str(self.stub if stub else self.probe), '--paths', *map(str, pids)],
+ env={**os.environ, 'PROBE_FIXTURE_CASE': case, 'LC_ALL': 'fr_FR.UTF-8'})
+ records = [json.loads(line) for line in result.stdout.splitlines()]
+ self.assertEqual(records.pop(0), {'schema': 1, 'mode': 'paths'})
+ self.assertEqual([row['pid'] for row in records], list(pids))
+ return records
+
+ def test_universal_artifact_and_signature_survive_embedding(self):
+ self.assertEqual(self.artifact['architectures'], ['arm64', 'x86_64'])
+ self.assertEqual(self.artifact['size'], self.probe.stat().st_size)
+ self.assertEqual(self.artifact['sourceSha256'], hashlib.sha256(SOURCE.read_bytes()).hexdigest())
+ self.assertEqual(self.artifact['builderSha256'], hashlib.sha256(BUILDER.read_bytes()).hexdigest())
+ self.assertEqual(sorted(command(['/usr/bin/lipo', str(self.probe), '-archs']).stdout.split()),
+ [b'arm64', b'x86_64'])
+ command(['/usr/bin/codesign', '--verify', '--strict', '--all-architectures', str(self.probe)])
+
+ def test_invalid_arguments_are_rejected_before_output(self):
+ for argv in [[], ['--paths'], ['--table', '7'], ['--paths', '7', 'bad'],
+ ['--paths', '+7'], ['--paths', '-1'], ['--paths', '0'],
+ ['--paths', ' 7'], ['--paths', '7\n'], ['--paths', '2147483648'],
+ ['--paths', '9' * 100], ['--paths', *['7'] * 4097]]:
+ with self.subTest(argv=argv[:3]):
+ result = subprocess.run([str(self.stub), *argv], capture_output=True, timeout=5)
+ self.assertEqual(result.returncode, 64)
+ self.assertEqual(result.stdout, b'')
+
+ def test_unavailable_racing_or_incomplete_identities_are_not_reported_as_paths(self):
+ for case in ['denied', 'short-info', 'pid-mismatch', 'pid-reused', 'exec-changed',
+ 'missing-second-path', 'truncated-path', 'relative-path', 'bad-start']:
+ with self.subTest(case=case):
+ self.assertEqual(self.probe_pids([7], stub=True, case=case),
+ [{'pid': 7, 'unavailable': True}])
+
+ def test_paths_preserve_raw_bytes_without_breaking_json(self):
+ [row] = self.probe_pids([7], stub=True, case='raw-path')
+ self.assertEqual(bytes.fromhex(row['imageHex']), b'/raw/quote" line\n slash\\ byte\xff')
+ self.assertEqual(row['startSeconds'], 1770000000)
+ self.assertEqual(row['startMicros'], 123456)
+ self.assertRegex(row['startMarker'], r'^\w{3} \w{3} [ \d]\d \d\d:\d\d:\d\d \d{4}$')
+
+ def test_real_renamed_unicode_symlink_hardlink_and_newline_paths(self):
+ alias = self.root / 'agent alias'
+ alias.symlink_to(self.sleeper)
+ hard = self.root / 'hard link'
+ os.link(self.sleeper, hard)
+ strange = self.root / 'quote" newline\nimage'
+ os.link(self.sleeper, strange)
+ children = [self.launch([str(path)]) for path in [self.sleeper, alias, hard, strange]]
+ for child in children:
+ self.wait_ready(child)
+ expected = self.sleeper.stat()
+ for row in self.probe_pids([child.pid for child in children]):
+ actual = os.stat(bytes.fromhex(row['imageHex']))
+ self.assertEqual((actual.st_dev, actual.st_ino), (expected.st_dev, expected.st_ino))
+
+ def test_same_pid_exec_gets_fresh_image_and_exit_has_no_identity(self):
+ child = self.launch(['/bin/sh', '-c', 'printf "ready\\n"; read -r line; exec "$1"',
+ 'harness-process-images-fixture', str(self.sleeper)])
+ self.wait_ready(child)
+ [before] = self.probe_pids([child.pid])
+ old = os.stat(bytes.fromhex(before['imageHex']))
+ # macOS can launch /bin/bash from /bin/sh. Compare the actual legacy
+ # reader, rather than assuming the launch pathname is the current image.
+ text_files = command(['/usr/sbin/lsof', '-b', '-a', '-p', str(child.pid),
+ '-d', 'txt', '-Fn']).stdout.splitlines()
+ first_text_path = next(line[1:] for line in text_files if line.startswith(b'n/'))
+ shell = os.stat(first_text_path)
+ self.assertEqual((old.st_dev, old.st_ino), (shell.st_dev, shell.st_ino))
+ child.stdin.write(b'go\n')
+ child.stdin.flush()
+ self.wait_ready(child)
+ [after] = self.probe_pids([child.pid])
+ native = os.stat(bytes.fromhex(after['imageHex']))
+ self.assertEqual(native.st_ino, self.sleeper.stat().st_ino)
+ self.assertNotEqual(before['imageHex'], after['imageHex'])
+ for key in ['startMarker', 'startSeconds', 'startMicros']:
+ self.assertEqual(before[key], after[key])
+ child.stdin.close()
+ child.wait(timeout=5)
+ self.assertEqual(self.probe_pids([child.pid]), [{'pid': child.pid, 'unavailable': True}])
+
+ def test_start_marker_matches_ps_despite_inherited_nonenglish_locale(self):
+ [row] = self.probe_pids([os.getpid()])
+ expected = command(['/bin/ps', '-p', str(os.getpid()), '-o', 'lstart='],
+ env={**os.environ, 'LC_ALL': '', 'LC_TIME': 'C'}).stdout.decode().strip()
+ self.assertEqual(row['startMarker'], expected)
+
+
+if __name__ == '__main__':
+ unittest.main(verbosity=2)
diff --git a/cli/scripts/build-process-images.py b/cli/scripts/build-process-images.py
new file mode 100644
index 000000000..cfd244ecb
--- /dev/null
+++ b/cli/scripts/build-process-images.py
@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Build the read-only image helper; no installation, downloads or release."""
+import argparse
+import base64
+import hashlib
+import json
+import os
+from pathlib import Path
+import platform
+import subprocess
+import tempfile
+
+
+def command(argv):
+ try:
+ return subprocess.run(argv, check=True, capture_output=True, timeout=60)
+ except subprocess.CalledProcessError as error:
+ detail = error.stderr.decode('utf-8', errors='replace').strip()
+ raise RuntimeError(f'{Path(argv[0]).name} failed: {detail}') from error
+
+
+def build(output):
+ if platform.system() != 'Darwin':
+ raise RuntimeError('Build the universal helper on a macOS host with Xcode')
+ output = output.resolve()
+ if output.exists():
+ raise RuntimeError('Use a fresh output path; existing artifacts are retained')
+ source = Path(__file__).resolve().parents[1] / 'native/darwin-process-images.c'
+ with tempfile.TemporaryDirectory(prefix='harness-process-images-') as root:
+ root = Path(root)
+ slices = []
+ for arch, minimum in [('arm64', '11.0'), ('x86_64', '10.15')]:
+ binary = root / arch
+ command(['/usr/bin/xcrun', '--sdk', 'macosx', 'clang', '-std=c11',
+ '-Wall', '-Wextra', '-Werror', '-O2', '-arch', arch,
+ f'-mmacosx-version-min={minimum}', str(source), '-o', str(binary)])
+ slices.append(binary)
+ universal = root / 'harness-process-images'
+ command(['/usr/bin/lipo', '-create', *map(str, slices), '-output', str(universal)])
+ command(['/usr/bin/codesign', '--force', '--sign', '-', '--identifier',
+ 'ai.autonomous.harness.process-images', '--timestamp=none', str(universal)])
+ command(['/usr/bin/codesign', '--verify', '--strict', '--all-architectures', str(universal)])
+ architectures = command(['/usr/bin/lipo', str(universal), '-archs']).stdout.decode().split()
+ if sorted(architectures) != ['arm64', 'x86_64']:
+ raise RuntimeError(f'Unexpected helper architectures: {architectures}')
+ # Execute the host slice and require a truthful record for this builder.
+ records = [json.loads(line) for line in command(
+ [str(universal), '--paths', str(os.getpid())]).stdout.splitlines()]
+ if (len(records) != 2 or records[0] != {'schema': 1, 'mode': 'paths'}
+ or records[1].get('pid') != os.getpid() or not records[1].get('imageHex')):
+ raise RuntimeError('The built helper failed its host-architecture smoke check')
+ data = universal.read_bytes()
+ artifact = {
+ 'schema': 1, 'platform': 'darwin', 'architectures': ['arm64', 'x86_64'],
+ 'sourceSha256': hashlib.sha256(source.read_bytes()).hexdigest(),
+ 'builderSha256': hashlib.sha256(Path(__file__).read_bytes()).hexdigest(),
+ 'sha256': hashlib.sha256(data).hexdigest(), 'size': len(data),
+ 'base64': base64.b64encode(data).decode('ascii'),
+ 'hostArchitecture': platform.machine(),
+ 'toolchain': command(['/usr/bin/xcrun', 'clang', '--version']).stdout.decode().strip(),
+ }
+ with output.open('x') as file:
+ json.dump(artifact, file, separators=(',', ':'))
+ file.write('\n')
+ print(json.dumps({key: value for key, value in artifact.items()
+ if key not in ['base64', 'toolchain']}))
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--output', type=Path, required=True)
+ build(parser.parse_args().output)
diff --git a/cli/scripts/lib/processImageBundle.mjs b/cli/scripts/lib/processImageBundle.mjs
new file mode 100644
index 000000000..f8ed4bf84
--- /dev/null
+++ b/cli/scripts/lib/processImageBundle.mjs
@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+const root = fileURLToPath(new URL('../..', import.meta.url))
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex')
+
+/** A build input produced from this checkout on macOS, embedded in the existing
+ * portable JS artifact. No download or compiler is required on the user's Mac.
+ * Linux/source-only development can omit it and keeps ordinary discovery. */
+export function readProcessImageBundle({ path, required = false, cliRoot = root } = {}) {
+ if (!path) {
+ if (required) throw new Error('Release requires HARNESS_PROCESS_IMAGES_ARTIFACT')
+ return undefined
+ }
+ if (statSync(path).size > 4 * 1024 * 1024) throw new Error('Native process-image artifact is too large')
+ const artifact = JSON.parse(readFileSync(path, 'utf8'))
+ if (artifact?.schema !== 1 || artifact.platform !== 'darwin'
+ || JSON.stringify(artifact.architectures) !== '["arm64","x86_64"]'
+ || artifact.sourceSha256 !== sha256(readFileSync(join(cliRoot, 'native/darwin-process-images.c')))
+ || artifact.builderSha256 !== sha256(readFileSync(join(cliRoot, 'scripts/build-process-images.py')))
+ || !Number.isInteger(artifact.size) || artifact.size < 32 || artifact.size > 2 * 1024 * 1024
+ || typeof artifact.base64 !== 'string') throw new Error('Native process-image build inputs do not match')
+ const bytes = Buffer.from(artifact.base64, 'base64')
+ if (bytes.length !== artifact.size || bytes.toString('base64') !== artifact.base64
+ || sha256(bytes) !== artifact.sha256) throw new Error('Native process-image artifact checksum mismatch')
+ return JSON.stringify({ schema: 1, size: bytes.length, sha256: artifact.sha256, base64: artifact.base64 })
+}
diff --git a/cli/scripts/test-process-image-bundle.mjs b/cli/scripts/test-process-image-bundle.mjs
new file mode 100644
index 000000000..f591bca84
--- /dev/null
+++ b/cli/scripts/test-process-image-bundle.mjs
@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict'
+import { createHash } from 'node:crypto'
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { after, test } from 'node:test'
+import { readProcessImageBundle } from './lib/processImageBundle.mjs'
+
+const root = mkdtempSync(join(tmpdir(), 'harness-image-bundle-'))
+after(() => rmSync(root, { recursive: true, force: true }))
+mkdirSync(join(root, 'native'))
+mkdirSync(join(root, 'scripts'))
+writeFileSync(join(root, 'native/darwin-process-images.c'), 'source')
+writeFileSync(join(root, 'scripts/build-process-images.py'), 'builder')
+const hash = value => createHash('sha256').update(value).digest('hex')
+const bytes = Buffer.alloc(64, 7)
+const artifact = { schema: 1, platform: 'darwin', architectures: ['arm64', 'x86_64'],
+ sourceSha256: hash('source'), builderSha256: hash('builder'), sha256: hash(bytes),
+ size: bytes.length, base64: bytes.toString('base64') }
+let serial = 0
+function read(value, required = true) {
+ const path = join(root, `asset-${serial++}.json`)
+ writeFileSync(path, JSON.stringify(value))
+ return readProcessImageBundle({ path, required, cliRoot: root })
+}
+
+test('source-only builds omit the helper; a release must supply it', () => {
+ assert.equal(readProcessImageBundle(), undefined)
+ assert.throws(() => readProcessImageBundle({ required: true }), /Release requires/)
+})
+
+test('embeds only exact binary bytes and identity, without build-machine metadata', () => {
+ assert.deepEqual(JSON.parse(read({ ...artifact, toolchain: 'private build path' })), {
+ schema: 1, size: 64, sha256: artifact.sha256, base64: artifact.base64,
+ })
+})
+
+test('rejects stale sources, stale builder, missing architectures and corrupted bytes', () => {
+ for (const change of [
+ { schema: 2 }, { sourceSha256: hash('old') }, { builderSha256: hash('old') },
+ { architectures: ['arm64'] }, { platform: 'linux' }, { size: 63 },
+ { sha256: hash('bad') }, { base64: artifact.base64 + '\n' }, { size: 3 * 1024 * 1024 },
+ ]) assert.throws(() => read({ ...artifact, ...change }))
+})
+
+test('optional means absent, not accepting a supplied broken build artifact', () => {
+ assert.throws(() => read({ ...artifact, sourceSha256: 'bad' }, false))
+})
diff --git a/cli/scripts/test-process-images-bundled.mjs b/cli/scripts/test-process-images-bundled.mjs
new file mode 100644
index 000000000..dfdb41745
--- /dev/null
+++ b/cli/scripts/test-process-images-bundled.mjs
@@ -0,0 +1,49 @@
+/** Exercise the same esbuild define, materialization and process-discovery path
+ * as the portable CLI. Only this Node process and a private cache are queried. */
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build } from 'esbuild'
+import { readProcessImageBundle } from './lib/processImageBundle.mjs'
+
+assert.equal(process.platform, 'darwin', 'Run the native bundle smoke check on macOS')
+const artifact = readProcessImageBundle({ path: process.env.HARNESS_PROCESS_IMAGES_ARTIFACT, required: true })
+const cli = fileURLToPath(new URL('..', import.meta.url))
+const root = mkdtempSync(join(tmpdir(), 'harness-images-bundled-'))
+try {
+ const noLsof = join(root, 'bin')
+ mkdirSync(noLsof)
+ writeFileSync(join(noLsof, 'lsof'), '#!/bin/sh\nprintf "unexpected fallback" >&2\nexit 64\n', { mode: 0o700 })
+ const entry = `
+ import assert from 'node:assert/strict';
+ import { realpathSync } from 'node:fs';
+ import { env } from ${JSON.stringify(join(cli, 'src/config/env.ts'))};
+ import { nativeProcessImages } from ${JSON.stringify(join(cli, 'src/lib/nativeProcessImages.ts'))};
+ import { processRows, enrichProcessRows } from ${JSON.stringify(join(cli, 'src/lib/tmux.ts'))};
+ env.ADAPTER_RUNTIME_DIR = process.argv[2];
+ const native = await nativeProcessImages([process.pid], 3000);
+ assert.equal(realpathSync(native.get(process.pid).path), realpathSync(process.execPath));
+ const rows = await processRows();
+ const own = rows.filter(row => row.pid === process.pid);
+ assert.equal(own.length, 1);
+ const enriched = await enrichProcessRows(own);
+ assert.equal(enriched.length, 1);
+ assert.equal(enriched[0].imagePath, native.get(process.pid).path);
+ assert.ok(enriched[0].imageFileKey);
+ console.log('Bundled native query and discovery passed on ' + process.arch);
+ `
+ const outfile = join(root, 'probe.mjs')
+ await build({ stdin: { contents: entry, resolveDir: cli, sourcefile: 'probe.mjs' },
+ outfile, bundle: true, platform: 'node', format: 'esm', target: 'node20',
+ external: ['bufferutil', 'utf-8-validate'],
+ banner: { js: 'import { createRequire } from "node:module"; const require = createRequire(import.meta.url);' },
+ define: { __DARWIN_PROCESS_IMAGES__: JSON.stringify(artifact) }, logLevel: 'silent' })
+ const stdout = execFileSync(process.execPath, [outfile, join(root, 'runtime')], {
+ timeout: 15_000, encoding: 'utf8', env: { ...process.env, PATH: noLsof + ':' + process.env.PATH,
+ ADAPTER_HOME: root, ADAPTER_CONFIG_DIR: join(root, 'config'), ADAPTER_DATA_DIR: join(root, 'data') },
+ })
+ process.stdout.write(stdout)
+} finally { rmSync(root, { recursive: true, force: true }) }
diff --git a/cli/src/lib/nativeProcessImages.spec.ts b/cli/src/lib/nativeProcessImages.spec.ts
new file mode 100644
index 000000000..9ce5555c2
--- /dev/null
+++ b/cli/src/lib/nativeProcessImages.spec.ts
@@ -0,0 +1,190 @@
+import { createHash } from 'node:crypto'
+import { chmod, lstat, mkdir, mkdtemp, readFile, readdir, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { env } from '../config/env.js'
+
+const host = vi.hoisted(() => ({ platform: 'darwin', execFile: vi.fn(), beforeStat: undefined as Promise<void> | undefined }))
+vi.mock('node:os', async original => ({ ...await original<typeof import('node:os')>(), platform: () => host.platform }))
+vi.mock('node:child_process', async original => ({ ...await original<typeof import('node:child_process')>(), execFile: host.execFile }))
+vi.mock('node:fs/promises', async original => {
+ const fs = await original<typeof import('node:fs/promises')>()
+ return { ...fs, lstat: async (...args: Parameters<typeof fs.lstat>) => {
+ await host.beforeStat
+ return fs.lstat(...args)
+ } }
+})
+const { nativeProcessImages, parseNativeProcessImages, prepareProcessImageHelper } = await import('./nativeProcessImages.js')
+
+const header = '{"schema":1,"mode":"paths"}\n'
+const record = (pid: number, path = '/fixture/native') => ({
+ pid, startMarker: 'Fri Oct 2 10:00:00 2026', startSeconds: 1770000000,
+ startMicros: 123456, imageHex: Buffer.from(path).toString('hex'),
+})
+const output = (...rows: unknown[]) => header + rows.map(row => JSON.stringify(row) + '\n').join('')
+// Never executed: the child-process mock represents the versioned protocol.
+const bytes = Buffer.alloc(64, 7)
+const artifact = { schema: 1 as const, sha256: createHash('sha256').update(bytes).digest('hex'),
+ size: bytes.length, base64: bytes.toString('base64') }
+const originalRuntime = env.ADAPTER_RUNTIME_DIR
+let root: string
+
+beforeEach(async () => {
+ root = await mkdtemp(join(tmpdir(), 'harness-native-images-'))
+ env.ADAPTER_RUNTIME_DIR = root
+ host.platform = 'darwin'
+ host.execFile.mockReset()
+ host.beforeStat = undefined
+})
+afterEach(async () => {
+ env.ADAPTER_RUNTIME_DIR = originalRuntime
+ vi.unstubAllGlobals()
+ vi.restoreAllMocks()
+ await rm(root, { recursive: true, force: true })
+})
+
+describe('native process-image protocol', () => {
+ it('preserves valid UTF-8 paths including JSON delimiters and newlines', () => {
+ const path = '/fixture/引擎 "quote"\nnew line\\tail'
+ expect(parseNativeProcessImages(output(record(10, path)), new Set([10])).get(10))
+ .toEqual({ path, startMarker: record(10).startMarker })
+ })
+
+ it('requires the protocol header and ignores unrequested processes', () => {
+ expect(parseNativeProcessImages(JSON.stringify(record(10)) + '\n', new Set([10])).size).toBe(0)
+ expect(parseNativeProcessImages(output(record(20)), new Set([10])).size).toBe(0)
+ expect(parseNativeProcessImages(output(record(10)).replace('"schema":1', '"schema":2'), new Set([10])).size).toBe(0)
+ })
+
+ it('keeps complete records before a truncated tail but refuses conflicting duplicates', () => {
+ const partial = output(record(10)) + JSON.stringify(record(20)).slice(0, -4)
+ expect([...parseNativeProcessImages(partial, new Set([10, 20])).keys()]).toEqual([10])
+ const conflict = output(record(10), { pid: 10, unavailable: true }, record(20), record(10))
+ expect([...parseNativeProcessImages(conflict, new Set([10, 20])).keys()]).toEqual([20])
+ })
+
+ it('rejects malformed bytes, relative paths and unavailable birth metadata', () => {
+ for (const row of [
+ record(10, 'relative'), record(10, '/with\0nul'), { ...record(10), imageHex: '2fff' },
+ { ...record(10), imageHex: '2f7' }, { ...record(10), imageHex: 'xx' },
+ { ...record(10), imageHex: '2f'.repeat(4096) }, { ...record(10), startSeconds: -1 },
+ { ...record(10), startMicros: 1_000_000 }, { ...record(10), startMarker: 'unknown' },
+ { ...record(10), unavailable: true }, { ...record(10), pid: 10.5 },
+ ]) expect(parseNativeProcessImages(output(row), new Set([10])).size).toBe(0)
+ })
+})
+
+describe('bundled native helper preparation', () => {
+ it('materializes exact pinned bytes once under a private, executable path', async () => {
+ const paths = await Promise.all(Array.from({ length: 4 }, () => prepareProcessImageHelper(artifact, root)))
+ expect(new Set(paths).size).toBe(1)
+ const path = paths[0]!
+ expect(await readFile(path)).toEqual(bytes)
+ expect((await lstat(path)).mode & 0o777).toBe(0o500)
+ expect(await readdir(join(root, 'process-images'))).toEqual([artifact.sha256])
+ expect(await prepareProcessImageHelper(artifact, root)).toBe(path)
+ })
+
+ it('rejects an invalid embedded hash without writing a file', async () => {
+ expect(await prepareProcessImageHelper({ ...artifact, sha256: '0'.repeat(64) }, root)).toBeNull()
+ expect(await readdir(root)).toEqual([])
+ })
+
+ it('does not execute, replace or repair an existing corrupt target or symlink', async () => {
+ const folder = join(root, 'process-images')
+ await mkdir(folder, { mode: 0o700 })
+ const target = join(folder, artifact.sha256)
+ await writeFile(target, 'other contents', { mode: 0o500 })
+ expect(await prepareProcessImageHelper(artifact, root)).toBeNull()
+ expect(await readFile(target, 'utf8')).toBe('other contents')
+ await rm(target)
+ const elsewhere = join(root, 'elsewhere')
+ await writeFile(elsewhere, bytes, { mode: 0o500 })
+ await symlink(elsewhere, target)
+ expect(await prepareProcessImageHelper(artifact, root)).toBeNull()
+ expect((await lstat(target)).isSymbolicLink()).toBe(true)
+ expect(await readFile(elsewhere)).toEqual(bytes)
+ })
+
+ it('leaves unsafe directory permissions unchanged and falls back', async () => {
+ await chmod(root, 0o777)
+ expect(await prepareProcessImageHelper(artifact, root)).toBeNull()
+ expect((await lstat(root)).mode & 0o777).toBe(0o777)
+ expect(await readdir(root)).toEqual([])
+ })
+})
+
+describe('fresh native image reads', () => {
+ it('does nothing on other platforms or when no native artifact was bundled', async () => {
+ expect((await nativeProcessImages([10], 500)).size).toBe(0)
+ vi.stubGlobal('__DARWIN_PROCESS_IMAGES__', JSON.stringify(artifact))
+ host.platform = 'linux'
+ expect((await nativeProcessImages([10], 500)).size).toBe(0)
+ expect(host.execFile).not.toHaveBeenCalled()
+ expect(await readdir(root)).toEqual([])
+ })
+
+ it('shares only executable preparation and issues a fresh query after exec', async () => {
+ vi.stubGlobal('__DARWIN_PROCESS_IMAGES__', JSON.stringify(artifact))
+ host.execFile.mockImplementationOnce((_path, _args, _options, done) => done(null, output(record(10, '/before'))))
+ .mockImplementationOnce((_path, _args, _options, done) => done(null, output(record(10, '/after'))))
+ expect((await nativeProcessImages([10], 500)).get(10)?.path).toBe('/before')
+ expect((await nativeProcessImages([10], 500)).get(10)?.path).toBe('/after')
+ expect(host.execFile).toHaveBeenCalledTimes(2)
+ for (const [path, args, options] of host.execFile.mock.calls) {
+ expect(path).toBe(join(root, 'process-images', artifact.sha256))
+ expect(args).toEqual(['--paths', '10'])
+ expect(options.timeout).toBeGreaterThan(0)
+ expect(options.timeout).toBeLessThanOrEqual(500)
+ expect(options.env.LC_TIME).toBe('C')
+ }
+ })
+
+ it('preserves complete records from a failed partial query and handles an unavailable helper', async () => {
+ vi.stubGlobal('__DARWIN_PROCESS_IMAGES__', JSON.stringify(artifact))
+ host.execFile.mockImplementationOnce((_path, _args, _options, done) => done(new Error('timeout'), output(record(10)) + '{'))
+ .mockImplementationOnce((_path, _args, _options, done) => done(new Error('cannot execute'), ''))
+ expect([...(await nativeProcessImages([10, 20], 500)).keys()]).toEqual([10])
+ expect((await nativeProcessImages([10], 500)).size).toBe(0)
+ })
+
+ it('rejects unbounded or invalid requests without preparing an executable', async () => {
+ vi.stubGlobal('__DARWIN_PROCESS_IMAGES__', JSON.stringify(artifact))
+ for (const pids of [[], [0], [-1], [10.1], [0x80000000], new Array(4097).fill(7)]) {
+ expect((await nativeProcessImages(pids, 500)).size).toBe(0)
+ }
+ expect((await nativeProcessImages([10], 0)).size).toBe(0)
+ expect(host.execFile).not.toHaveBeenCalled()
+ expect(await readdir(root)).toEqual([])
+ })
+
+ it('backs off a failed helper and rematerializes a deleted cache entry on retry', async () => {
+ vi.stubGlobal('__DARWIN_PROCESS_IMAGES__', JSON.stringify(artifact))
+ let now = 0
+ vi.spyOn(performance, 'now').mockImplementation(() => now)
+ host.execFile.mockImplementationOnce((_path, _args, _options, done) => done(null, output(record(10))))
+ .mockImplementationOnce((_path, _args, _options, done) => done(Object.assign(new Error('missing'), { code: 'ENOENT' }), ''))
+ .mockImplementationOnce((_path, _args, _options, done) => done(null, output(record(10, '/new'))))
+ expect((await nativeProcessImages([10], 500)).size).toBe(1)
+ const path = join(root, 'process-images', artifact.sha256)
+ await rm(path)
+ expect((await nativeProcessImages([10], 500)).size).toBe(0)
+ expect((await nativeProcessImages([10], 500)).size).toBe(0)
+ expect(host.execFile).toHaveBeenCalledTimes(2)
+ now = 60_001
+ expect((await nativeProcessImages([10], 500)).get(10)?.path).toBe('/new')
+ expect(await readFile(path)).toEqual(bytes)
+ })
+
+ it('does not launch a late helper when preparation exceeds the request deadline', async () => {
+ vi.stubGlobal('__DARWIN_PROCESS_IMAGES__', JSON.stringify(artifact))
+ let resume!: () => void
+ host.beforeStat = new Promise<void>(resolve => { resume = resolve })
+ expect((await nativeProcessImages([10], 20)).size).toBe(0)
+ expect(host.execFile).not.toHaveBeenCalled()
+ resume()
+ await vi.waitFor(async () => expect(await readFile(join(root, 'process-images', artifact.sha256))).toEqual(bytes))
+ expect(host.execFile).not.toHaveBeenCalled()
+ })
+})
diff --git a/cli/src/lib/nativeProcessImages.ts b/cli/src/lib/nativeProcessImages.ts
new file mode 100644
index 000000000..6a0e275c8
--- /dev/null
+++ b/cli/src/lib/nativeProcessImages.ts
@@ -0,0 +1,196 @@
+import { execFile } from 'node:child_process'
+import { createHash, randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { link, lstat, mkdir, open, unlink } from 'node:fs/promises'
+import { platform } from 'node:os'
+import { join } from 'node:path'
+import { TextDecoder } from 'node:util'
+import { env } from '../config/env.js'
+import { psEnv } from './childLocale.js'
+
+declare const __DARWIN_PROCESS_IMAGES__: string | undefined
+
+export interface ProcessImageArtifact {
+ schema: 1
+ sha256: string
+ size: number
+ base64: string
+}
+
+export interface NativeProcessImage {
+ path: string
+ startMarker: string
+}
+
+const MAX_ARTIFACT_BYTES = 2 * 1024 * 1024
+const MAX_PATH_BYTES = 4096
+const MAX_PIDS = 4096
+const utf8 = new TextDecoder('utf-8', { fatal: true })
+const prepared = new Map<string, Promise<string | null>>()
+const retryAfter = new Map<string, number>()
+let artifactSource: string | undefined
+let artifactValue: ProcessImageArtifact | null = null
+
+function validPid(pid: unknown): pid is number {
+ return typeof pid === 'number' && Number.isInteger(pid) && pid > 0 && pid <= 0x7fffffff
+}
+
+function artifactBytes(artifact: ProcessImageArtifact): Buffer {
+ if (artifact.schema !== 1 || !/^[0-9a-f]{64}$/.test(artifact.sha256)
+ || !Number.isInteger(artifact.size) || artifact.size < 32 || artifact.size > MAX_ARTIFACT_BYTES
+ || typeof artifact.base64 !== 'string' || artifact.base64.length > Math.ceil(MAX_ARTIFACT_BYTES / 3) * 4) {
+ throw new Error('Invalid native process-image artifact')
+ }
+ const bytes = Buffer.from(artifact.base64, 'base64')
+ if (bytes.length !== artifact.size || bytes.toString('base64') !== artifact.base64
+ || createHash('sha256').update(bytes).digest('hex') !== artifact.sha256) {
+ throw new Error('Native process-image artifact checksum mismatch')
+ }
+ return bytes
+}
+
+async function privateDirectory(path: string, recursive = false): Promise<void> {
+ try { await mkdir(path, { recursive, mode: 0o700 }) }
+ catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error }
+ const info = await lstat(path)
+ if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid?.()
+ || (info.mode & 0o022) !== 0) throw new Error('Unsafe native helper directory')
+}
+
+async function verifyFile(path: string, artifact: ProcessImageArtifact): Promise<boolean> {
+ let file
+ try {
+ file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+ const info = await file.stat()
+ if (!info.isFile() || info.uid !== process.getuid?.() || (info.mode & 0o022) !== 0
+ || (info.mode & 0o100) === 0 || info.size !== artifact.size) return false
+ const bytes = await file.readFile()
+ return createHash('sha256').update(bytes).digest('hex') === artifact.sha256
+ } catch { return false }
+ finally { await file?.close() }
+}
+
+/** Extract only bytes pinned by the CLI bundle, never a network download or a
+ * path supplied by terminal output. Creation is atomic across multiple daemons.
+ * This is an optional optimization: callers preserve their ordinary reader on
+ * every failure. No account state, sessions or existing files are replaced. */
+export async function prepareProcessImageHelper(
+ artifact: ProcessImageArtifact, runtimeDirectory: string,
+): Promise<string | null> {
+ let temporary: string | undefined
+ try {
+ const bytes = artifactBytes(artifact)
+ await privateDirectory(runtimeDirectory, true)
+ const directory = join(runtimeDirectory, 'process-images')
+ await privateDirectory(directory)
+ const target = join(directory, artifact.sha256)
+ if (await verifyFile(target, artifact)) return target
+ try { await lstat(target); return null }
+ catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+ // A bad existing target stays untouched and cannot be executed. link()
+ // below is create-only, so concurrent writers cannot replace one another.
+ temporary = join(directory, `.${artifact.sha256}-${randomUUID()}`)
+ const file = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o500)
+ try { await file.writeFile(bytes) }
+ finally { await file.close() }
+ try { await link(temporary, target) }
+ catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error }
+ return await verifyFile(target, artifact) ? target : null
+ } catch { return null }
+ finally { if (temporary) await unlink(temporary).catch(() => {}) }
+}
+
+/** Keep complete, uniquely identified records only. A timeout may leave usable
+ * records before a truncated line, exactly as with the ordinary image reader. */
+export function parseNativeProcessImages(
+ stdout: string, requested: ReadonlySet<number>,
+): Map<number, NativeProcessImage> {
+ const images = new Map<number, NativeProcessImage>()
+ const lines = stdout.slice(0, stdout.lastIndexOf('\n') + 1).split('\n')
+ try {
+ const header = JSON.parse(lines.shift() ?? '')
+ if (header?.schema !== 1 || header?.mode !== 'paths') return images
+ } catch { return images }
+ const seen = new Set<number>()
+ for (const line of lines) {
+ let row
+ try { row = JSON.parse(line) } catch { continue }
+ if (!row || !validPid(row.pid) || !requested.has(row.pid)) continue
+ if (seen.has(row.pid)) { images.delete(row.pid); continue }
+ seen.add(row.pid)
+ if (row.unavailable === true || typeof row.imageHex !== 'string'
+ || row.imageHex.length < 2 || row.imageHex.length >= MAX_PATH_BYTES * 2
+ || row.imageHex.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(row.imageHex)
+ || typeof row.startMarker !== 'string'
+ || !/^\w{3} \w{3} [ \d]\d \d{2}:\d{2}:\d{2} \d{4}$/.test(row.startMarker)
+ || !Number.isSafeInteger(row.startSeconds) || row.startSeconds <= 0
+ || !Number.isInteger(row.startMicros) || row.startMicros < 0 || row.startMicros >= 1_000_000) continue
+ try {
+ const path = utf8.decode(Buffer.from(row.imageHex, 'hex'))
+ if (path.startsWith('/') && !path.includes('\0')) images.set(row.pid, { path, startMarker: row.startMarker })
+ } catch { /* Invalid filesystem bytes cannot identify a JS string path. Fall back. */ }
+ }
+ return images
+}
+
+async function bundledHelper(): Promise<{ path: string; key: string } | null> {
+ const source = typeof __DARWIN_PROCESS_IMAGES__ === 'undefined' ? undefined : __DARWIN_PROCESS_IMAGES__
+ if (typeof source !== 'string') return null
+ if (source !== artifactSource) {
+ artifactSource = source
+ artifactValue = null
+ try { artifactValue = JSON.parse(artifactSource) } catch { /* Optional asset. */ }
+ }
+ const artifact = artifactValue
+ if (!artifact || typeof artifact.sha256 !== 'string') return null
+ const key = `${env.ADAPTER_RUNTIME_DIR}\0${artifact.sha256}`
+ if ((retryAfter.get(key) ?? 0) > performance.now()) return null
+ let helper = prepared.get(key)
+ if (!helper) {
+ helper = prepareProcessImageHelper(artifact, env.ADAPTER_RUNTIME_DIR)
+ .then(path => {
+ if (!path) {
+ prepared.delete(key)
+ retryAfter.set(key, performance.now() + 60_000)
+ }
+ return path
+ })
+ prepared.set(key, helper)
+ }
+ const path = await helper
+ return path ? { path, key } : null
+}
+
+/** A fresh kernel query on every call. Only the immutable executable's
+ * preparation is shared; no PID, image or completed process result is cached. */
+export async function nativeProcessImages(
+ pids: readonly number[], timeout: number,
+): Promise<Map<number, NativeProcessImage>> {
+ const empty = new Map<number, NativeProcessImage>()
+ if (platform() !== 'darwin' || !pids.length || pids.length > MAX_PIDS
+ || !pids.every(validPid) || !Number.isFinite(timeout) || timeout <= 0) return empty
+ const deadline = performance.now() + timeout
+ let timer: ReturnType<typeof setTimeout> | undefined
+ try {
+ // A slow cache filesystem must not block discovery or start a late helper.
+ const helper = await Promise.race([bundledHelper(), new Promise<null>(resolve => {
+ timer = setTimeout(() => resolve(null), timeout)
+ })])
+ const remaining = Math.floor(deadline - performance.now())
+ if (!helper || remaining <= 0) return empty
+ return await new Promise(resolve => {
+ execFile(helper.path, ['--paths', ...new Set(pids).values()].map(String),
+ { timeout: remaining, maxBuffer: 4 * 1024 * 1024, env: psEnv() }, (error, stdout) => {
+ const images = parseNativeProcessImages(stdout ?? '', new Set(pids))
+ if (error && !images.size) {
+ // A missing/blocked helper must not become a failed spawn every
+ // reconcile. Retry preparation later; ordinary discovery continues.
+ prepared.delete(helper.key)
+ retryAfter.set(helper.key, performance.now() + 60_000)
+ }
+ resolve(images)
+ })
+ })
+ } catch { return empty }
+ finally { if (timer) clearTimeout(timer) }
+}
diff --git a/cli/src/lib/processImages.real.spec.ts b/cli/src/lib/processImages.real.spec.ts
index 684dc1720..ddeda0ff7 100644
--- a/cli/src/lib/processImages.real.spec.ts
+++ b/cli/src/lib/processImages.real.spec.ts
@@ -1,10 +1,12 @@
import { execFile, spawn, type ChildProcess } from 'node:child_process'
import { once } from 'node:events'
-import { link, mkdtemp, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import { link, mkdtemp, readFile, realpath, rm, symlink, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { promisify } from 'node:util'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { env } from '../config/env.js'
+import { nativeProcessImages } from './nativeProcessImages.js'
import { isolatedTmux, type IsolatedTmux } from '../testing/isolatedTmux.js'
import { executableFileIdentity } from './engineBin.js'
import { TmuxBackend } from './tmuxBackend.js'
@@ -17,6 +19,7 @@ const children: ChildProcess[] = []
const folders: string[] = []
let server: IsolatedTmux | undefined
const exec = promisify(execFile)
+const originalRuntime = env.ADAPTER_RUNTIME_DIR
afterEach(async () => {
for (const child of children.splice(0)) {
@@ -28,6 +31,8 @@ afterEach(async () => {
await server?.close()
server = undefined
vi.unstubAllEnvs()
+ vi.unstubAllGlobals()
+ env.ADAPTER_RUNTIME_DIR = originalRuntime
for (const path of folders.splice(0)) await rm(path, { recursive: true, force: true })
})
@@ -56,6 +61,17 @@ async function images(pids: number[]) {
}
realDescribe.sequential('real macOS executable identity', () => {
+ beforeEach(async () => {
+ const artifact = process.env.HARNESS_PROCESS_IMAGES_ARTIFACT
+ if (!artifact) return
+ vi.stubGlobal('__DARWIN_PROCESS_IMAGES__', await readFile(artifact, 'utf8'))
+ env.ADAPTER_RUNTIME_DIR = await fixture()
+ // First execution of a freshly written Mach-O may wait on macOS signature
+ // inspection. Production can use lsof during that cold start; warm the
+ // private helper here before requiring the native integration path.
+ expect((await nativeProcessImages([process.pid], 3000)).size).toBe(1)
+ })
+
it('resolves renamed, Unicode, symlinked and hard-linked native images', async () => {
const root = await fixture()
const native = await nativeSleeper(root, 'renamed 引擎 2.9.0')
@@ -91,7 +107,12 @@ realDescribe.sequential('real macOS executable identity', () => {
const pid = Number(await server.run('display-message', '-p', '-t', pane, '#{pane_pid}'))
await server.run('set-option', '-w', '-t', pane, 'remain-on-exit', 'on')
const [before] = await images([pid])
- expect(before.imageFileKey).toBe(executableFileIdentity('/bin/sh')!.fileKey)
+ // macOS can execute /bin/sh with /bin/bash as its kernel image. Compare
+ // the actual mapped executable, not the shell's launch pathname.
+ const mapped = (await exec('/usr/sbin/lsof', ['-a', '-p', String(pid), '-d', 'txt', '-Fn'], { timeout: 3000 }))
+ .stdout.split('\n').find(line => line.startsWith('n/'))?.slice(1)
+ expect(mapped).toBeDefined()
+ expect(before.imageFileKey).toBe(executableFileIdentity(mapped!)!.fileKey)
await server.run('send-keys', '-t', pane, 'Enter')
const expected = executableFileIdentity(native)!.fileKey
try {
diff --git a/cli/src/lib/processImages.spec.ts b/cli/src/lib/processImages.spec.ts
index e549cb491..999ee4d5f 100644
--- a/cli/src/lib/processImages.spec.ts
+++ b/cli/src/lib/processImages.spec.ts
@@ -2,6 +2,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { ProcessRow } from './tmux.js'
const execFile = vi.hoisted(() => vi.fn())
+const nativeImages = vi.hoisted(() => vi.fn())
+vi.mock('./nativeProcessImages.js', () => ({ nativeProcessImages: nativeImages }))
vi.mock('child_process', async original => ({
...await original<typeof import('child_process')>(), execFile,
}))
@@ -18,10 +20,49 @@ const image = (pid: number, path: string) => `p${pid}\nftxt\nn${path}\n`
const answer = (text: string, error: Error | null = null) =>
execFile.mockImplementationOnce((_command, _args, _options, callback) => callback(error, text))
-beforeEach(() => execFile.mockReset())
+beforeEach(() => {
+ execFile.mockReset()
+ nativeImages.mockReset().mockResolvedValue(new Map())
+})
afterEach(() => vi.restoreAllMocks())
describe('macOS executable images', () => {
+ it('uses fresh native paths without starting lsof when all births match', async () => {
+ nativeImages.mockResolvedValue(new Map([[10, { path: '/fixture/native', startMarker: 'Fri Oct 2 10:00:00 2026' }]]))
+ expect((await enrichProcessRows([row(10)]))[0].imagePath).toBe('/fixture/native')
+ expect(nativeImages).toHaveBeenCalledWith([10], 500)
+ expect(execFile).not.toHaveBeenCalled()
+ })
+
+ it('uses the ordinary reader only for native identities that are unavailable', async () => {
+ nativeImages.mockResolvedValue(new Map([[10, { path: '/fixture/native', startMarker: row(10).startMarker }]]))
+ answer(image(20, '/fixture/fallback'))
+ expect((await enrichProcessRows([row(10), row(20)])).map(row => row.imagePath))
+ .toEqual(['/fixture/native', '/fixture/fallback'])
+ expect(execFile.mock.calls[0][1]).toEqual(['-b', '-a', '-p', '20', '-d', 'txt', '-Fn'])
+ })
+
+ it('drops a PID with a proven new birth instead of combining new identity and old arguments', async () => {
+ nativeImages.mockResolvedValue(new Map([[10, { path: '/fixture/new-owner', startMarker: 'Fri Oct 2 10:00:01 2026' }]]))
+ const rows = [row(10), row(20)]
+ expect(await enrichProcessRows(rows, new Set([10]))).toEqual([rows[1]])
+ expect(rows).toHaveLength(2)
+ expect(execFile).not.toHaveBeenCalled()
+ })
+
+ it('includes native-query time in the overall fallback deadline', async () => {
+ let now = 0
+ vi.spyOn(performance, 'now').mockImplementation(() => now)
+ nativeImages.mockImplementation(async () => { now = 500; return new Map() })
+ execFile.mockImplementationOnce((_command, _args, _options, callback) => {
+ now = 1500
+ callback(new Error('timeout'), '')
+ })
+ answer(image(10, '/fixture/fallback'))
+ await enrichProcessRows([row(10)])
+ expect(execFile.mock.calls[1][2]).toEqual({ timeout: 1500 })
+ })
+
it('gets all images in one nonblocking call, preserving spaces and Unicode', async () => {
answer(image(10, '/fixture/renamed engine') + image(10, '/fixture/later.dylib')
+ image(20, '/fixture/引擎'))
diff --git a/cli/src/lib/tmux.ts b/cli/src/lib/tmux.ts
index e19a8a2d3..8e1024980 100644
--- a/cli/src/lib/tmux.ts
+++ b/cli/src/lib/tmux.ts
@@ -16,6 +16,7 @@ import {
} from './engineBin.js'
import { BYPASS_PERMISSION_FLAGS, PERMISSION_MODES, permissionModeApproves } from './engineLaunch.js'
import { psEnv } from './childLocale.js'
+import { nativeProcessImages } from './nativeProcessImages.js'
export { captureTmuxPane, tmuxCaptureArgs } from './tmuxCapture.js'
function cleanPaneTitle(title: string): string | null {
@@ -334,23 +335,44 @@ function parseDarwinProcessImages(stdout: string | null): Map<number, string> {
return images
}
-/** macOS has no /proc. Its libproc-backed lsof supplies text-region paths from
- * the kernel; -b avoids filesystem stat/readlink helpers unnecessary for those
- * names. Keep the normal probe for missing paths, inside the same 3s budget.
+/** macOS has no /proc. Prefer the bundled read-only kernel image probe; retain
+ * both lsof readers for missing paths, inside the same total 3s budget.
* Never cache by PID: exec can replace an image without changing its birth. */
-async function darwinProcessImages(pids: readonly number[]): Promise<Map<number, string>> {
- if (!pids.length) return new Map()
+async function darwinProcessImages(rows: readonly ProcessRow[]): Promise<{
+ images: Map<number, string>; stale: Set<number>
+}> {
+ const images = new Map<number, string>()
+ const stale = new Set<number>()
+ if (!rows.length) return { images, stale }
const deadline = performance.now() + 3000
+ const pids = rows.map(row => row.pid)
+ const native = await nativeProcessImages(pids, 500)
+ const normalizeStart = (marker: string) => marker.trim().split(/\s+/)
+ .map((part, index) => index === 2 ? String(Number(part)) : part).join(' ')
+ for (const row of rows) {
+ const image = native.get(row.pid)
+ if (!image) continue
+ if (normalizeStart(image.startMarker) === normalizeStart(row.startMarker)) images.set(row.pid, image.path)
+ // The PID changed owners since ps. Do not combine the new executable with
+ // old ancestry/arguments, or let the fallback reintroduce that stale row.
+ else stale.add(row.pid)
+ }
const args = (selected: readonly number[]) => ['-a', '-p', selected.join(','), '-d', 'txt', '-Fn']
- const images = parseDarwinProcessImages(await execText('lsof', ['-b', ...args(pids)], 1000))
- const missing = pids.filter(pid => !images.has(pid))
- const remaining = Math.floor(deadline - performance.now())
+ let missing = pids.filter(pid => !images.has(pid) && !stale.has(pid))
+ let remaining = Math.floor(deadline - performance.now())
+ if (missing.length && remaining > 0) {
+ for (const [pid, path] of parseDarwinProcessImages(
+ await execText('lsof', ['-b', ...args(missing)], Math.min(1000, remaining)),
+ )) images.set(pid, path)
+ }
+ missing = missing.filter(pid => !images.has(pid))
+ remaining = Math.floor(deadline - performance.now())
if (missing.length && remaining > 0) {
for (const [pid, path] of parseDarwinProcessImages(await execText('lsof', args(missing), remaining))) {
images.set(pid, path)
}
}
- return images
+ return { images, stale }
}
/**
@@ -367,6 +389,7 @@ export async function enrichProcessRows(
if (!candidates.length) return rows
const imagePaths = new Map<number, string>()
const imageIdentities = new Map<number, ReturnType<typeof executableFileIdentity>>()
+ let stale = new Set<number>()
if (platform() === 'linux') {
await Promise.all(candidates.map(async (row) => {
const procImage = `/proc/${row.pid}/exe`
@@ -379,13 +402,15 @@ export async function enrichProcessRows(
}
}))
} else if (platform() === 'darwin') {
- for (const [pid, path] of await darwinProcessImages(candidates.map((row) => row.pid))) {
+ const result = await darwinProcessImages(candidates)
+ stale = result.stale
+ for (const [pid, path] of result.images) {
imagePaths.set(pid, path)
imageIdentities.set(pid, executableFileIdentity(path.replace(/ \(deleted\)$/, '')))
}
}
- return rows.map((row) => {
+ return rows.filter(row => !stale.has(row.pid)).map((row) => {
if (!selectedPids.has(row.pid)) return row
const imagePath = imagePaths.get(row.pid)
const image = imageIdentities.get(row.pid) ?? null
diff --git a/scripts/record-ci-validation.py b/scripts/record-ci-validation.py
index ab40290e1..45fad92e6 100644
--- a/scripts/record-ci-validation.py
+++ b/scripts/record-ci-validation.py
@@ -20,7 +20,7 @@ import zipfile
CLI_JOBS = {"cli-contracts", "typecheck-test"} | {f"cli-tests ({i})" for i in range(1, 5)} | {
f"serial-native ({system}, {node})" for system in ["ubuntu-latest", "macos-latest"] for node in ["20.19.0", "22.23.2"]
-}
+} | {f"process-images-native ({system})" for system in ["macos-15", "macos-15-intel"]}
TUI_JOBS = {"tui-test (ubuntu-latest, x86_64-unknown-linux-musl)", "tui-test (ubuntu-24.04-arm, aarch64-unknown-linux-musl)"}
DESKTOP_PLATFORMS = {"ubuntu-22.04", "macos-15"}
DESKTOP_JOBS = {"desktop-test-summary"} | {f"desktop-tests ({platform}, {index})" for platform in DESKTOP_PLATFORMS for index in range(1, 5)}