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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Use a native macOS image probe with bounded discovery fallback (#670)
Deec6e95924936d
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 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 shellrun: 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.ymlindex 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-latesttimeout-minutes: 20env:@@ -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@v7with:# THE runtime pin — the managed Node the shipped CLI actually executes on (see the samediff --git a/cli/build-bundle.mjs b/cli/build-bundle.mjsindex 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.cnew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 | undefinedconst exec = promisify(execFile)+const originalRuntime = env.ADAPTER_RUNTIME_DIRafterEach(async () => {for (const child of children.splice(0)) {@@ -28,6 +31,8 @@ afterEach(async () => {await server?.close()server = undefinedvi.unstubAllEnvs()+ vi.unstubAllGlobals()+ env.ADAPTER_RUNTIME_DIR = originalRuntimefor (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)!.fileKeytry {diff --git a/cli/src/lib/processImages.spec.ts b/cli/src/lib/processImages.spec.tsindex 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.tsindex 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 rowsconst 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 rowconst imagePath = imagePaths.get(row.pid)const image = imageIdentities.get(row.pid) ?? nulldiff --git a/scripts/record-ci-validation.py b/scripts/record-ci-validation.pyindex ab40290e1..45fad92e6 100644--- a/scripts/record-ci-validation.py+++ b/scripts/record-ci-validation.py@@ -20,7 +20,7 @@ import zipfileCLI_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)}