engineering-behavior-observatory 0.2.4 → 0.2.5

package/dist/src/run-bundles.js

@@ -1,7 +1,7 @@
 import { execFile, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { createReadStream, createWriteStream } from "node:fs";
-import { cp, lstat, mkdir, mkdtemp, readdir, rm, rmdir, utimes, writeFile } from "node:fs/promises";
+import { cp, lstat, mkdir, mkdtemp, readdir, realpath, rm, rmdir, utimes, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { promisify } from "node:util";
@@ -268,6 +268,7 @@ async function withWorkspaceOutcomeProjection(options, use) {
     try {
         await cp(finalPath, projectedPath, {
             recursive: true,
+            verbatimSymlinks: true,
             preserveTimestamps: true,
             force: false,
             filter: async (source) => source === finalPath
@@ -648,7 +649,7 @@ async function workspacePatchApplies(startingWorkspacePath, patch) {
     const applied = join(temporaryRoot, "workspace");
     const patchPath = join(temporaryRoot, "workspace.patch");
     try {
-        await cp(resolve(startingWorkspacePath), applied, { recursive: true, preserveTimestamps: true, force: false });
+        await cp(resolve(startingWorkspacePath), applied, { recursive: true, verbatimSymlinks: true, preserveTimestamps: true, force: false });
         if (patch.length > 0) {
             await writeFile(patchPath, patch, { flag: "wx", mode: 0o600 });
             await execFileAsync("git", ["apply", "--check", "--binary", patchPath], { cwd: applied });
@@ -842,7 +843,7 @@ async function removeIgnoredWorkspaceEntries(startPath, finalPath) {
     const globalExcludes = join(temporaryRoot, "global-excludes");
     try {
         await writeFile(globalExcludes, "");
-        await cp(startPath, baseline, { recursive: true, preserveTimestamps: true, force: false });
+        await cp(startPath, baseline, { recursive: true, verbatimSymlinks: true, preserveTimestamps: true, force: false });
         await execFileAsync("git", ["init", "--quiet"], { cwd: baseline });
         await execFileAsync("git", ["add", "--force", "--all"], { cwd: baseline });
         for (const relativePath of await ignoredWorkspacePaths(baseline, finalPath, globalExcludes)) {
@@ -910,12 +911,31 @@ async function isExcludedWorkspaceDirectory(root, source, exclusions) {
     }
     return false;
 }
-async function removeEmptyDirectories(directory, root = directory) {
+async function removeEmptyDirectories(directory, root = directory, targets) {
+    if (targets === undefined) {
+        targets = new Set();
+        async function collect(path) {
+            for (const entry of await readdir(path, { withFileTypes: true })) {
+                const child = join(path, entry.name);
+                if (entry.isDirectory())
+                    await collect(child);
+                else if (entry.isSymbolicLink()) {
+                    // Omission must not turn a valid link into a dangling one. Invalid
+                    // links are rejected later by workspace hashing; no content is read.
+                    try {
+                        targets.add(await realpath(child));
+                    }
+                    catch { /* validated by hashing */ }
+                }
+            }
+        }
+        await collect(directory);
+    }
     for (const entry of await readdir(directory, { withFileTypes: true })) {
         if (entry.isDirectory())
-            await removeEmptyDirectories(join(directory, entry.name), root);
+            await removeEmptyDirectories(join(directory, entry.name), root, targets);
     }
-    if (directory !== root && (await readdir(directory)).length === 0)
+    if (directory !== root && !targets.has(await realpath(directory)) && (await readdir(directory)).length === 0)
         await rmdir(directory);
 }
 async function restoreProjectedDirectoryTimestamps(source, projected) {
@@ -938,7 +958,7 @@ async function workspacePatch(startPath, finalPath, finalTreeDigest) {
     const applied = join(temporaryRoot, "applied");
     const patchPath = join(temporaryRoot, "workspace.patch");
     try {
-        await cp(startPath, worktree, { recursive: true, preserveTimestamps: true, force: false });
+        await cp(startPath, worktree, { recursive: true, verbatimSymlinks: true, preserveTimestamps: true, force: false });
         await execFileAsync("git", ["init", "--quiet"], { cwd: worktree });
         await execFileAsync("git", ["add", "--force", "--all"], { cwd: worktree });
         // A tree is enough for the diff. A commit can spawn detached maintenance
@@ -951,7 +971,7 @@ async function workspacePatch(startPath, finalPath, finalTreeDigest) {
         for (const entry of await readdir(finalPath)) {
             if (entry === ".git")
                 throw new Error("Workspace patches cannot retain Git administrative state.");
-            await cp(join(finalPath, entry), join(worktree, entry), { recursive: true, preserveTimestamps: true, force: false });
+            await cp(join(finalPath, entry), join(worktree, entry), { recursive: true, verbatimSymlinks: true, preserveTimestamps: true, force: false });
         }
         await execFileAsync("git", ["add", "--force", "--intent-to-add", "--all"], { cwd: worktree });
         let stdout;
@@ -966,12 +986,14 @@ async function workspacePatch(startPath, finalPath, finalTreeDigest) {
             throw error;
         }
         const patch = Buffer.from(stdout);
-        await cp(startPath, applied, { recursive: true, preserveTimestamps: true, force: false });
+        await cp(startPath, applied, { recursive: true, verbatimSymlinks: true, preserveTimestamps: true, force: false });
         if (patch.length > 0) {
             await writeFile(patchPath, patch, { flag: "wx", mode: 0o600 });
             await execFileAsync("git", ["apply", "--binary", patchPath], { cwd: applied });
         }
-        const appliedTreeDigest = await digestWorkspaceTree(applied);
+        // Git omits empty directories, including legitimate link targets. An
+        // invalid reconstructed tree is a patch limitation, so use the snapshot.
+        const appliedTreeDigest = await digestWorkspaceTree(applied).catch(() => undefined);
         if (appliedTreeDigest !== finalTreeDigest) {
             return undefined;
         }
@@ -989,8 +1011,8 @@ async function workspaceSnapshot(finalPath, finalTreeDigest, use) {
     const extracted = join(temporaryRoot, "extracted");
     try {
         await mkdir(snapshotParent);
-        await cp(finalPath, snapshotRoot, { recursive: true, preserveTimestamps: true, force: false });
-        const child = spawn(TAR_COMMAND, ["-czf", "-", "-C", snapshotParent, "workspace"], { stdio: ["ignore", "pipe", "pipe"] });
+        await cp(finalPath, snapshotRoot, { recursive: true, verbatimSymlinks: true, preserveTimestamps: true, force: false });
+        const child = spawn(TAR_COMMAND, [...(process.platform === "darwin" ? ["--no-mac-metadata"] : []), "-czf", "-", "-C", snapshotParent, "workspace"], { stdio: ["ignore", "pipe", "pipe"] });
         let stderr = "";
         child.stderr.on("data", (chunk) => { stderr = (stderr + chunk.toString("utf8")).slice(-8192); });
         const exited = new Promise((resolveExit, reject) => {
@@ -1012,7 +1034,16 @@ async function workspaceSnapshot(finalPath, finalTreeDigest, use) {
             await Promise.allSettled([exited, streamed]);
         }
         await mkdir(extracted, { mode: 0o700 });
-        await execFileAsync(TAR_COMMAND, ["-xzpf", snapshotPath, "-C", extracted]);
+        // macOS libarchive consumes genuine ._* AppleDouble files even when its
+        // metadata flags are disabled. Native pax preserves them with copyfile off.
+        if (process.platform === "darwin") {
+            await execFileAsync("/bin/pax", ["-rz", "-p", "p", "-f", snapshotPath], {
+                cwd: extracted, env: { ...process.env, COPYFILE_DISABLE: "1" },
+            });
+        }
+        else {
+            await execFileAsync(TAR_COMMAND, ["-xzpf", snapshotPath, "-C", extracted]);
+        }
         if (await digestWorkspaceTree(join(extracted, "workspace")) !== finalTreeDigest) {
             throw new Error("Bounded workspace snapshot cannot reproduce the final workspace tree.");
         }

package/dist/src/verifiers.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { createReadStream, createWriteStream } from "node:fs";
-import { chmod, lstat, mkdir, mkdtemp, open, readdir, readFile, realpath, rm, utimes } from "node:fs/promises";
+import { chmod, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rm, utimes } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
 import { tmpdir } from "node:os";
 import { performance } from "node:perf_hooks";
@@ -72,10 +72,10 @@ async function digestWorkspaceEntries(workspacePath, includeTimestamps, signal)
     if (!metadata.isDirectory() || metadata.isSymbolicLink())
         throw new Error("Workspace root is not a directory.");
     hash.update(`root\0${metadata.mode & 4095n}\0${includeTimestamps ? `${workspaceTimestamp(metadata)}\0` : ""}`);
-    await hashWorkspaceDirectory(root, "", hash, includeTimestamps, signal);
+    await hashWorkspaceDirectory(root, "", hash, includeTimestamps, signal, root);
     return `sha256:${hash.digest("hex")}`;
 }
-async function hashWorkspaceDirectory(directory, relativeDirectory, hash, includeTimestamps, signal) {
+async function hashWorkspaceDirectory(directory, relativeDirectory, hash, includeTimestamps, signal, root = directory) {
     assertNotAborted(signal);
     const entries = await readdir(directory, { withFileTypes: true });
     entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
@@ -83,11 +83,31 @@ async function hashWorkspaceDirectory(directory, relativeDirectory, hash, includ
         const path = join(directory, entry.name);
         const relativePath = posix.join(relativeDirectory, entry.name);
         const metadata = await lstat(path, { bigint: true });
-        if (metadata.isSymbolicLink())
-            throw new Error(`Workspace contains a symbolic link at "${relativePath}".`);
-        if (metadata.isDirectory()) {
+        if (metadata.isSymbolicLink()) {
+            // Preserve link text, never hash the referent through the link. Both its
+            // lexical target and resolved chain must stay in this workspace.
+            const target = await readlink(path);
+            const contained = (candidate) => {
+                const rel = relative(root, candidate);
+                return !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
+            };
+            if (isAbsolute(target) || !contained(resolve(dirname(path), target))) {
+                throw new Error(`Workspace symbolic link escapes its root at "${relativePath}".`);
+            }
+            let resolved;
+            try {
+                resolved = await realpath(path);
+            }
+            catch {
+                throw new Error(`Workspace symbolic link is dangling or cyclic at "${relativePath}".`);
+            }
+            if (!contained(resolved))
+                throw new Error(`Workspace symbolic link escapes its root at "${relativePath}".`);
+            hash.update(`symlink\0${relativePath}\0${metadata.mode & 4095n}\0${includeTimestamps ? `${workspaceTimestamp(metadata)}\0` : ""}${Buffer.byteLength(target)}\0${target}`);
+        }
+        else if (metadata.isDirectory()) {
             hash.update(`directory\0${relativePath}\0${metadata.mode & 4095n}\0${includeTimestamps ? `${workspaceTimestamp(metadata)}\0` : ""}`);
-            await hashWorkspaceDirectory(path, relativePath, hash, includeTimestamps, signal);
+            await hashWorkspaceDirectory(path, relativePath, hash, includeTimestamps, signal, root);
         }
         else if (metadata.isFile()) {
             if (metadata.nlink > 1n)

package/docs/guides/evidence-and-sharing.md

@@ -46,6 +46,34 @@ missing-evidence entries. Inspect the detail before retrying capture against a
 retained workspace. A later successful capture is recovery evidence; it does
 not change the original attempt's recorded failure.
 
+When the native run completed but capture failed, recover capture without
+executing the task again. Materialize the same frozen starting workspace, use
+the same capture exclusions, and assemble a separate bundle with byte-identical
+native evidence plus the recovered workspace outcome. Record the original
+manifest digest, recovery time, capture-code identity and qualification beside
+the recovered bundle. Preserve the original failed bundle. A later workspace
+capture cannot prove the retained directory was unchanged since execution ended
+unless a fingerprint was recorded then. Do not count the recovery as another
+model trial or as an independent sample.
+
+Workspace outcomes preserve relative symbolic links whose lexical targets and
+resolved referents stay inside the workspace. Link text is hashed and copied
+verbatim, not replaced by the referent's bytes. Empty-directory omission keeps
+directories referenced by links. Absolute, escaping, dangling and
+cyclic links fail capture. Patch application or snapshot extraction must still
+reproduce the resulting tree digest. This does not relax task-archive admission
+or verifier sandbox rules.
+
+On macOS, snapshot creation disables generated AppleDouble metadata. Snapshot
+verification uses the built-in `/bin/pax` with `COPYFILE_DISABLE=1` so genuine
+`._*` files remain files. macOS tar may otherwise consume them as metadata,
+changing the reconstructed tree. To extract a snapshot for inspection on macOS:
+
+```sh
+mkdir restored
+(cd restored && COPYFILE_DISABLE=1 /bin/pax -rz -p p -f /absolute/path/workspace.tar.gz)
+```
+
 Workspace capture tries a patch up to 64 MiB, then falls back to a snapshot
 when the patch is too large or cannot reproduce the tree. Snapshots stream to
 disk with a 1 GiB compressed limit and are extracted to verify the tree digest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-behavior-observatory",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Capture engineering-agent trajectories, evaluate behavior, and inspect cited evidence across harnesses.",
   "license": "Apache-2.0",
   "repository": {
@@ -48,6 +48,7 @@
     "release/0.2.2/",
     "release/0.2.3/",
     "release/0.2.4/",
+    "release/0.2.5/",
     "schemas/",
     "scripts/atlas-grafana.sh"
   ],

package/release/0.2.5/KNOWN_LIMITATIONS.md

@@ -0,0 +1,12 @@
+# v0.2.5 known limitations
+
+The [v0.2.4 limitations](../0.2.4/KNOWN_LIMITATIONS.md) continue to apply.
+
+- Symlink support applies to workspace outcome capture, not task-archive
+  admission or permission to read outside the workspace.
+- On macOS, use the documented native `pax` command when inspecting snapshots
+  containing genuine AppleDouble files. Default `tar` extraction can consume them.
+- Capture-only recovery can use retained evidence and workspace files without
+  rerunning a model, but cannot reconstruct missing files or prove an earlier
+  workspace state without a fingerprint captured at that time.
+- Workspace snapshots remain restricted evidence, not sanitized partner exports.

package/release/0.2.5/README.md

@@ -0,0 +1,25 @@
+# v0.2.5: Preserve framework files in workspace capture
+
+Workspace capture now preserves contained relative symbolic links, including
+framework link chains and links to empty directories. Absolute, escaping,
+dangling, and cyclic links remain rejected. Copies retain the original link
+text, and patches that cannot reproduce the tree fall back to a snapshot.
+
+On macOS, snapshot verification uses native `pax` to preserve genuine AppleDouble
+files that macOS `tar` otherwise consumes as metadata. Snapshots remain tar.gz
+archives. No runtime dependencies, pins, or serialized artifact formats change.
+
+## Verification
+
+Regression tests cover link preservation, invalid targets, empty target
+directories, AppleDouble bytes, and long paths. A completed model attempt's
+retained workspace was recovered as a 695,459,840-byte snapshot with a verified
+extracted tree digest, without another model call or rewriting original evidence.
+The recovery qualified with an explicit missing-telemetry-receipt gap; it records
+the later capture time rather than claiming an exact end-of-turn snapshot.
+
+Run `npm ci` and `npm run acceptance` on Node 24.19.0 for tests, documentation
+and package checks, and two byte-identical package builds. See
+[known limitations](KNOWN_LIMITATIONS.md), the
+[reproducibility manifest](reproducibility.json), and the
+[workspace inspection guide](../../docs/guides/evidence-and-sharing.md).

package/release/0.2.5/reproducibility.json

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": "ebo.release-reproducibility/v1",
+  "release": {
+    "name": "engineering-behavior-observatory",
+    "version": "0.2.5"
+  },
+  "runtime": {
+    "node": "24.19.0",
+    "claudeAgentSdk": "0.3.258",
+    "openhandsAgentServer": "1.46.0",
+    "deepseekClient": "0.1.1-rc.2",
+    "deepseekProtocol": "0.1.1-rc.2",
+    "deepseekRuntime": "0.1.1-rc.2",
+    "codexAppServer": "0.153.4",
+    "grafana": "13.2.0",
+    "grafanaInfinity": "4.0.0",
+    "piSdk": "0.85.1",
+    "cursorSdk": "1.0.31"
+  },
+  "commands": [
+    "npm ci",
+    "npm run acceptance"
+  ],
+  "fixtureCoverage": {
+    "agent-sdk": "frozen queue entry through qualified capture, approved export, normalization, configurable judging, review, aggregation, and Atlas",
+    "openhands-agent-server": "pinned REST/WebSocket stream-final reconciliation, workspace/outcome evidence, partial capture, and retained evaluation",
+    "deepseek-harness": "official-client JSON-RPC composition, receipt-to-idle completion, stderr, interruption, shutdown, swaps, and retained evaluation",
+    "codex-app-server": "owned stdio lifecycle, full history, OTLP, interruption/failure, export, and retained evaluation; configurable workspace-write networking with explicit offline queue propagation",
+    "acceptance-cases": "seeded ordering, secret scanning, partial attempts, native references, abstention, disputes, denominators, and unsupported comparisons",
+    "pi-sdk": "frozen queue, passive hooks, durable session, partial cleanup, export, retained normalization and evaluation",
+    "cursor-sdk": "frozen queue, official store, callbacks/history, bounded cancellation, export, retained normalization and evaluation",
+    "workspace-capture": "Contained relative symlinks, empty link targets, AppleDouble files and long paths; streamed snapshots with verified tree digests and unchanged 1 GiB bound"
+  },
+  "determinism": {
+    "stable": [
+      "task, run, attempt, event, assertion, aggregate, and Atlas case identities",
+      "fixture, native-reference, normalized-dataset, source/cohort, archive, and package digests",
+      "seeded queue and review-sample ordering"
+    ],
+    "excluded": [
+      "native and EBO observation timestamps",
+      "lifecycle start/finish timestamps",
+      "provider timing and usage",
+      "temporary workspace and output paths"
+    ]
+  },
+  "fixtures": {
+    "tests/fixtures/task-packet.valid.v1.json": "ac2ef1043c0cc16bf4c21d05c1dc880ca1b4b8cc2f9ea7653328e91f0b0e2681",
+    "test/fixtures/agent-sdk-normalizer/complete.input.json": "7285dee088517e5de38ceda84fc7c58d9303949c7448ab3b5e10a5a2d2ebdfe3",
+    "test/fixtures/agent-sdk-normalizer/complete.expected.jsonl": "d32fa3a013bc179f1673f7e1a89b8a721bb8ddaf63eba5bc8a3f14f1cc148ed8",
+    "contracts/openhands-agent-server-v1.44.1.json": "e7a07977688a0703b15751a8a1ab17f29be45f9fdf438017e0dbcbc49cca37b0",
+    "contracts/openhands-agent-server-v1.46.0.json": "455cdddd2c206cb2f20245c2189b92e773657ec14d651236baa532b2dbadeb28",
+    "test/fixtures/openhands/v1.44.1/streamed-events.json": "d751083ba2ef94c9865117db481cc2f4933772bbbbb6b9fcf60571563715c1ea",
+    "test/fixtures/openhands/v1.44.1/final-events.json": "551db9904e860004d604c923692b5c5d3aaee966220492214c60003d2df415b6",
+    "test/fixtures/deepseek/golden-success.json": "f3867d38169bf0e28f64aba1dd60553f21cf07f41f81b4bad48261e49fa3ca88",
+    "test/fixtures/deepseek/golden-interrupted.json": "79e1f8404df1ee3b562d0bdbc0b2ee712ffc6d5774992b92970814ea815677b7",
+    "test/fixtures/deepseek/compositions/minimal/composition.json": "72fe4368e105f1bad82b7fdf8380e92c9fa689d8985f6ab91f534f0baf3eda02",
+    "contracts/codex-app-server-0.153.4/manifest.json": "e62281ff5e5d1cc71d07763b85e997ccc9ddbad9aa82a469da4181ee4b1890a8",
+    "test/fixtures/codex/legacy-0.150.1.dataset.json": "f71906b009e546afbf3b4e79396f223181382f3b3d8795e9cfcd032398a9d6bf",
+    "test/fixtures/behavior-assertions/abstained.json": "7f1962864f664c794925a67d93074e7b150af0f57c58041a81e062990d641197",
+    "test/fixtures/behavior-assertions/disputed.review.json": "450d3d9efe7feefaf7500b3ad20ab2803b412c7e53b91763125e15a83be87981",
+    "test/fixtures/comparison/exact.json": "cafa68e94b8d50dc308ddcfc2e73aa139c828b4ecd1e1c762bbc51bf1b44501e",
+    "test/fixtures/structural-observations/golden.json": "bad71a3a93524b76c0a2fdbb58e98e1e65be46cae14acf18ac89d9ba76e03e8a",
+    "test/atlas-fixture.ts": "9f03ce9cbcd0e5d3e3a5916866554ceb1c21f1c8712e58529499c1ea499f048d",
+    "test/pi.test.ts": "a00997c5617ca178e19b25b0d483cbdce8ce7c306d4c871557945b31a2e657cf",
+    "test/cursor-sdk.test.ts": "753094f127b11dc392ec2244c9edddabec27aa94347bb6159a292129ed2a2822",
+    "examples/cursor-sdk/README.md": "a2cf481123e7f3deb1c5a682ba208a775c3f91c35e1a6c1a428c517c79692618",
+    "examples/cursor-sdk/capture-profile.json": "d1a5787875daf5523b3783f259b891c256a904cbb10279d5be214af846305a2d",
+    "examples/cursor-sdk/harness.json": "2f1da6f2b17258d0ee59431f687696901ce3692589175d182f3a4bbe8dd4d689",
+    "examples/cursor-sdk/model.json": "ad8f31ff5d2387c02d79226679022358afafc61ba5dda73040e3f754530a230a",
+    "examples/cursor-sdk/native-limits.json": "40fe451f56b0863e79b42f5c85defbce678e1dc90dd248d15c430db176d71511",
+    "examples/cursor-sdk/native-tool-policy.json": "0fef98b36cd39de82914c5b068022c1335dadda24b7d6e7df398b2430e6a16e0"
+  }
+}

package/release/README.md

@@ -5,6 +5,7 @@ For downloads and published artifacts, see
 
 | Version | Changes and verification | Support boundary |
 | :--- | :--- | :--- |
+| [0.2.5](0.2.5/README.md) | Preserve contained workspace symlinks and macOS AppleDouble files | [Known limitations](0.2.5/KNOWN_LIMITATIONS.md) |
 | [0.2.4](0.2.4/README.md) | Stream workspace snapshots and integrity checks; support archives up to 1 GiB | [Known limitations](0.2.4/KNOWN_LIMITATIONS.md) |
 | [0.2.3](0.2.3/README.md) | Retain workspace capture errors in partial-bundle reports | [Known limitations](0.2.3/KNOWN_LIMITATIONS.md) |
 | [0.2.2](0.2.2/README.md) | Configurable Codex tool networking, enabled by default for workspace-write | [Known limitations](0.2.2/KNOWN_LIMITATIONS.md) |