sortie-dogs 0.14.2 → 0.14.4

package/README.md

@@ -19,8 +19,8 @@ evidence-backed result, not more agents for their own sake.
 [![Node.js](https://img.shields.io/node/v/sortie-dogs)](https://www.npmjs.com/package/sortie-dogs)
 [![MIT License](https://img.shields.io/npm/l/sortie-dogs)](LICENSE)
 
-**Current release: [v0.14.2](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.14.2)**
-· [Release notes](docs/release-v0.14.2.md) · [Execution vision](docs/v0.14.0-execution-vision.md)
+**Current release: [v0.14.4](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.14.4)**
+· [Release notes](docs/release-v0.14.4.md) · [Execution vision](docs/v0.14.0-execution-vision.md)
 
 [Quick start](#quick-start) · [Workflow](#mission-workflow) · [Models](#default-models) ·
 [Measured results](#measured-results) · [Configuration](#configuration) · [Documentation](#documentation)
@@ -57,7 +57,7 @@ Use an existing Codex CLI signed in with **ChatGPT**. On Windows, PowerShell **7
 available; POSIX uses bash. Sortie does not install Codex, start login or use a metered API fallback.
 
 ```sh
-npm install --save-dev sortie-dogs@0.14.2
+npm install --save-dev sortie-dogs@0.14.4
 npx --no-install sortie-dogs codex init .
 ```
 
@@ -86,7 +86,7 @@ bridge. [Codex guide: SDK, permissions, progress, resume and manifest route](doc
 Use **OpenCode V2**. In the target project:
 
 ```sh
-npm install --save-dev sortie-dogs@0.14.2
+npm install --save-dev sortie-dogs@0.14.4
 npx --no-install sortie-dogs init .
 ```
 
@@ -242,7 +242,7 @@ Install the desired package version and rerun **your host's** initializer:
 
 An OpenCode config-local bridge may resolve a separate package; npm-global update alone does not
 update it. [Global/update instructions](docs/configuration.md#global-availability).
-The current Mission asset marker is `0.14.2-cold-resume-v1`; the unchanged Codex skill marker is
+The current Mission asset marker is `0.14.4-docker-read-v1`; the unchanged Codex skill marker is
 `0.13.11-codex-skill-v2`. Installed markers alone do not prove a running host reloaded the new version.
 
 There is no supported uninstall command. Remove the dependency and only known Sortie-owned paths;
@@ -258,7 +258,7 @@ follow the [manual removal guide](docs/uninstall.md), never delete the entire `.
   [SWE-bench history](docs/benchmarks/swebench-lite-history.md) · [Historical local case study](docs/benchmark-reference.md).
 - **Development:** [Testing](docs/testing.md) · [CLI testing](docs/cli-testing.md) ·
   [Windows tests](docs/windows-tests.md) · [Release routine](docs/release-batch.md).
-- **Releases:** [v0.14.2](docs/release-v0.14.2.md) · [v0.14.1](docs/release-v0.14.1.md) · [v0.14.0](docs/release-v0.14.0.md) · [v0.13.22](docs/release-v0.13.22.md) · [v0.13.21](docs/release-v0.13.21.md) · [v0.13.20](docs/release-v0.13.20.md) · [v0.13.19](docs/release-v0.13.19.md) · [v0.13.18](docs/release-v0.13.18.md) · [v0.13.17](docs/release-v0.13.17.md) · [v0.13.16](docs/release-v0.13.16.md) · [v0.13.15](docs/release-v0.13.15.md) · [v0.13.14](docs/release-v0.13.14.md) · [v0.13.13](docs/release-v0.13.13.md) · [v0.13.12](docs/release-v0.13.12.md) · [v0.13.11](docs/release-v0.13.11.md) · [v0.13.10](docs/release-v0.13.10.md) ·
+- **Releases:** [v0.14.4](docs/release-v0.14.4.md) · [v0.14.3](docs/release-v0.14.3.md) · [v0.14.2](docs/release-v0.14.2.md) · [v0.14.1](docs/release-v0.14.1.md) · [v0.14.0](docs/release-v0.14.0.md) · [v0.13.22](docs/release-v0.13.22.md) · [v0.13.21](docs/release-v0.13.21.md) · [v0.13.20](docs/release-v0.13.20.md) · [v0.13.19](docs/release-v0.13.19.md) · [v0.13.18](docs/release-v0.13.18.md) · [v0.13.17](docs/release-v0.13.17.md) · [v0.13.16](docs/release-v0.13.16.md) · [v0.13.15](docs/release-v0.13.15.md) · [v0.13.14](docs/release-v0.13.14.md) · [v0.13.13](docs/release-v0.13.13.md) · [v0.13.12](docs/release-v0.13.12.md) · [v0.13.11](docs/release-v0.13.11.md) · [v0.13.10](docs/release-v0.13.10.md) ·
   [v0.13.9](docs/release-v0.13.9.md) · [All GitHub releases](https://github.com/zufall-upon/Sortie-dogs/releases).
 
 ## Community

package/dist/asset-version.d.ts

@@ -3,6 +3,6 @@
  * installed project marker without importing every asset body.
  */
 export declare const RUNTIME_ASSET_VERSION = "0.3.89-completion-proof-v1";
-export declare const V010_RUNTIME_ASSET_VERSION = "0.14.2-cold-resume-v1";
+export declare const V010_RUNTIME_ASSET_VERSION = "0.14.4-docker-read-v1";
 export declare const CODEX_SKILL_ASSET_VERSION = "0.13.11-codex-skill-v2";
 export type RuntimeAssetVersion = typeof RUNTIME_ASSET_VERSION | typeof V010_RUNTIME_ASSET_VERSION | typeof CODEX_SKILL_ASSET_VERSION;

package/dist/asset-version.js

@@ -3,5 +3,5 @@
  * installed project marker without importing every asset body.
  */
 export const RUNTIME_ASSET_VERSION = "0.3.89-completion-proof-v1";
-export const V010_RUNTIME_ASSET_VERSION = "0.14.2-cold-resume-v1";
+export const V010_RUNTIME_ASSET_VERSION = "0.14.4-docker-read-v1";
 export const CODEX_SKILL_ASSET_VERSION = "0.13.11-codex-skill-v2";

package/dist/core/goal-bound.d.ts

@@ -45,6 +45,16 @@ export interface GoalEvidence {
         /** Non-generating native validation pins inputs/concrete outputs, not write-only directory bookkeeping.
          * Missing on old evidence: retain its full source/output recipe. */
         readonly validation_policy?: "inputs-and-concrete-outputs-v1";
+        /** Snapshot and recheck the exact Git workspace inside one validated Docker task container. */
+        readonly docker_workspace?: {
+            readonly container_id: string;
+            readonly cwd: string;
+            /** Physical Docker CWD for a declared logical alias; absent on legacy/non-alias proof. */
+            readonly actual_cwd?: string;
+            readonly repository_root: string;
+            readonly source: string;
+            readonly candidate: string;
+        };
         /** Fixed when validation starts. Full manifest_hash still identifies the historical execution contract. */
         readonly freshness?: {
             readonly contract_hash: string;

package/dist/core/goal-bound.js

@@ -59,6 +59,7 @@ export function validGoalEvidence(value, state) {
         return false;
     const criteria = state.acceptance_contract?.criteria.filter(({ criterion_id }) => value.measurement.criterion_ids.includes(criterion_id)) ?? [];
     const protectedBinding = value.protected_binding;
+    const dockerWorkspace = protectedBinding?.docker_workspace;
     const protectedBindingValid = protectedBinding !== undefined && HASH.test(protectedBinding.manifest_hash) &&
         text(protectedBinding.project_root) && text(protectedBinding.manifest_path) && Array.isArray(protectedBinding.source_paths) &&
         protectedBinding.source_paths.every(text) && Array.isArray(protectedBinding.candidate_paths) &&
@@ -67,6 +68,11 @@ export function validGoalEvidence(value, state) {
             protectedBinding.source_policy === "declared-paths-v1") &&
         (protectedBinding.candidate_policy === undefined || protectedBinding.candidate_policy === "project-root-artifacts-v1") &&
         (protectedBinding.validation_policy === undefined || protectedBinding.validation_policy === "inputs-and-concrete-outputs-v1") &&
+        (dockerWorkspace === undefined || (typeof dockerWorkspace.container_id === "string" && /^[a-f0-9]{12,64}$/u.test(dockerWorkspace.container_id) &&
+            typeof dockerWorkspace.cwd === "string" && dockerWorkspace.cwd.startsWith("/") &&
+            (dockerWorkspace.actual_cwd === undefined || typeof dockerWorkspace.actual_cwd === "string" && dockerWorkspace.actual_cwd.startsWith("/")) &&
+            typeof dockerWorkspace.repository_root === "string" && dockerWorkspace.repository_root.startsWith("/") &&
+            HASH.test(dockerWorkspace.source) && HASH.test(dockerWorkspace.candidate))) &&
         (protectedBinding.freshness === undefined || (protectedBinding.freshness !== null && typeof protectedBinding.freshness === "object" &&
             HASH.test(protectedBinding.freshness.contract_hash) &&
             Array.isArray(protectedBinding.freshness.scratch_paths) && protectedBinding.freshness.scratch_paths.every(text) &&
@@ -89,10 +95,10 @@ export function validGoalEvidence(value, state) {
             sameStrings(criterion.oracle_coverage, value.measurement.oracle_coverage) &&
             criterion.build_boundary === value.measurement.build_boundary &&
             (criterion.source_binding === "current-protected"
-                ? protectedBindingValid && HASH.test(value.identity.source)
+                ? protectedBindingValid && HASH.test(value.identity.source) && (dockerWorkspace === undefined || dockerWorkspace.source === value.identity.source)
                 : criterion.source === value.identity.source) &&
             (criterion.candidate_binding === "current-protected"
-                ? protectedBindingValid && HASH.test(value.identity.candidate)
+                ? protectedBindingValid && HASH.test(value.identity.candidate) && (dockerWorkspace === undefined || dockerWorkspace.candidate === value.identity.candidate)
                 : criterion.candidate === value.identity.candidate) &&
             (criterion.validation_command === undefined ||
                 (value.execution.command.length === 1 && value.execution.command[0] === criterion.validation_command)) &&

package/dist/core/operator-runtime.js

@@ -1344,7 +1344,9 @@ export class OperatorRuntime {
         }
         if (unit.reviewerCorrection ? args.task_id !== unit.reviewerCorrection.author : args.task_id !== undefined && args.task_id !== "")
             return false;
-        if (args.subagent_type !== unit.task.subagent_type || args.description !== unit.task.description)
+        // The caller's display label does not change the retained task or its signed
+        // reference. Keep agent, continuation identity and exact prompt authoritative.
+        if (args.subagent_type !== unit.task.subagent_type || typeof args.description !== "string")
             return false;
         return args.prompt === unit.task.prompt || args.prompt === this.workerTask(state, unit).prompt;
     }

package/dist/plugin/docker-validation.d.ts

@@ -0,0 +1,17 @@
+export interface DockerWorkspaceSnapshot {
+    readonly container_id: string;
+    /** Declared Docker --workdir; keep its logical alias for validation matching. */
+    readonly cwd: string;
+    /** Physical CWD when Docker resolves the declared path through an alias. */
+    readonly actual_cwd?: string;
+    readonly repository_root: string;
+    readonly source: string;
+    readonly candidate: string;
+}
+/** Hash the fixed container's actual workspace, including non-Git and ignored inputs. */
+export declare function captureDockerWorkspaceSnapshot(containerID: string, cwd: string): Promise<DockerWorkspaceSnapshot | undefined>;
+export declare function isDockerContainerID(value: unknown): value is string;
+export declare function isDockerWorkspacePath(value: unknown): value is string;
+/** Inspect bytes, never execute caller-supplied code. The Review envelope's
+ * immutable Docker candidate must match both before and after the read. */
+export declare function readDockerWorkspaceFile(containerID: string, cwd: string, candidate: string, path: string, offset?: number, limit?: number): Promise<Record<string, unknown>>;

package/dist/plugin/docker-validation.js

@@ -0,0 +1,278 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { posix } from "node:path";
+import { promisify } from "node:util";
+import { readDockerWorkspaceWithoutPython } from "./docker-workspace-read-fallback.js";
+const exec = promisify(execFile);
+const CONTAINER_ID = /^[a-f0-9]{12,64}$/u;
+const SNAPSHOT_MARKER = "SORTIE_DOCKER_WORKSPACE_V1";
+// Terminal tasks need not contain Git at all. Capture actual bytes and file
+// identity, including ignored inputs; timestamps alone are not candidate edits.
+const FILE_SNAPSHOT = String.raw `
+import errno
+import hashlib, json, os, stat, subprocess
+cwd = os.path.realpath(os.getcwd())
+root = cwd
+try:
+    # Remove Git's terminating LF, not meaningful whitespace in the root path.
+    root = subprocess.check_output(["git", "rev-parse", "--show-toplevel"], stderr=subprocess.DEVNULL).decode("utf-8")[:-1]
+    head = subprocess.check_output(["git", "rev-parse", "--verify", "HEAD^{tree}"], stderr=subprocess.DEVNULL, text=True).strip()
+except (OSError, subprocess.CalledProcessError):
+    # An unborn repository still has a root; missing HEAD must not narrow it.
+    head = "no-git"
+root = os.path.realpath(root)
+rows = []
+def digest(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as stream:
+        for block in iter(lambda: stream.read(1024 * 1024), b""):
+            h.update(block)
+    return h.hexdigest()
+for directory, dirs, files in os.walk(root, followlinks=False, onerror=lambda error: (_ for _ in ()).throw(error)):
+    if directory == root:
+        dirs[:] = [name for name in dirs if name != ".git"]
+        files = [name for name in files if name != ".git"]
+    for name in [".", *dirs, *files]:
+        path = directory if name == "." else os.path.join(directory, name)
+        relative = os.path.relpath(path, root)
+        info = os.lstat(path)
+        mode = stat.S_IMODE(info.st_mode)
+        if stat.S_ISREG(info.st_mode):
+            value = [relative, "file", mode, digest(path)]
+        elif stat.S_ISLNK(info.st_mode):
+            target = os.path.realpath(path)
+            # Missing/cyclic targets retain their literal link identity. Do not
+            # let isfile/isdir turn permission or I/O errors into missing input.
+            try:
+                referent = os.stat(path)
+            except OSError as error:
+                if error.errno not in (errno.ENOENT, errno.ENOTDIR, errno.ELOOP):
+                    raise
+                referent = None
+            is_file = referent is not None and stat.S_ISREG(referent.st_mode)
+            is_directory = referent is not None and stat.S_ISDIR(referent.st_mode)
+            if referent is not None and not (is_file or is_directory):
+                raise RuntimeError("unsupported-workspace-file-type")
+            # Internal directory targets are captured at their own lexical path.
+            # External directory trees are not silently omitted from a proof.
+            if is_directory and os.path.commonpath([root, target]) != root:
+                raise RuntimeError("external-directory-link-snapshot-unavailable")
+            value = [relative, "link", mode, os.readlink(path), digest(path) if is_file else None]
+            if is_file or is_directory:
+                value.extend([target, stat.S_IMODE(referent.st_mode)])
+        elif stat.S_ISDIR(info.st_mode):
+            value = [relative, "directory", mode]
+        else:
+            raise RuntimeError("unsupported-workspace-file-type")
+        rows.append(value)
+tree = hashlib.sha256(json.dumps(sorted(rows), ensure_ascii=True, separators=(",", ":")).encode()).hexdigest()
+print("SORTIE_DOCKER_WORKSPACE_V1")
+print(cwd)
+print(root)
+print(tree)
+print(hashlib.sha256(head.encode()).hexdigest())
+print("0" * 64)
+`;
+const SNAPSHOT_COMMAND = [
+    "set -eu",
+    "if command -v python3 >/dev/null 2>&1; then",
+    "python3 -I -S - <<'SORTIE_WORKSPACE_PY'",
+    FILE_SNAPSHOT,
+    "SORTIE_WORKSPACE_PY",
+    "else",
+    "actual_cwd=$(pwd -P)",
+    "root=$(git rev-parse --show-toplevel)",
+    "cd \"$root\"",
+    "tree=$(git rev-parse --verify 'HEAD^{tree}')",
+    // Capture successful producer output before hashing: POSIX pipelines otherwise
+    // hide failed Git/file reads behind a successful hash of empty/partial data.
+    "tracked=$(git diff --binary HEAD -- && printf '.')",
+    "tracked=${tracked%.}",
+    "tracked=$(printf '%s' \"$tracked\" | sha256sum)",
+    "tracked=${tracked%% *}",
+    // A NUL on enumeration failure is an invalid empty filename, so xargs fails
+    // rather than treating a failed Git listing as an empty untracked set.
+    // An untracked internal directory alias is already covered at its target.
+    // Filter only that case before the batched hash; retain all producer failures.
+    "untracked_bytes=$({",
+    "{ git ls-files -z --others || printf '\\0'; } | xargs -0 -r sh -c '",
+    "root=$1; shift",
+    "for path do",
+    "  [ -n \"$path\" ] || exit 1",
+    "  if [ -L \"$path\" ] && [ -d \"$path\" ]; then",
+    "    target=$(readlink -f -- \"$path\") || exit 1",
+    "    case \"$target\" in \"$root\"|\"$root\"/*) : ;; *) exit 1 ;; esac",
+    "  else printf \"%s\\0\" \"$path\"",
+    "  fi",
+    "done' sh \"$root\" || printf '\\0'",
+    "} | xargs -0 -r sha256sum --)",
+    // Git may ignore tracked executable-bit changes (core.filemode=false).
+    // Observe workspace modes/links independently, excluding only Git bookkeeping.
+    "workspace_modes=$({ find . -path ./.git -prune -o -print0 || printf '\\0'; } | LC_ALL=C QUOTING_STYLE=c xargs -0 -r stat -c '%f %N' --)",
+    "workspace_modes=$(printf '%s' \"$workspace_modes\" | LC_ALL=C sort)",
+    // Index visibility flags and Git's stat cache can hide changed tracked bytes.
+    // Observe actual regular files independently, with stable filename/hash pairs.
+    "workspace_bytes=$({ find . -path ./.git -prune -o -type f -print0 || printf '\\0'; } | xargs -0 -r sha256sum --)",
+    "workspace_bytes=$(printf '%s' \"$workspace_bytes\" | LC_ALL=C sort)",
+    // Git records a tracked link's text, not the regular-file bytes it reads.
+    "link_bytes=$({ find . -path ./.git -prune -o -type l -print0 || printf '\\0'; } | xargs -0 -r sh -c '",
+    "root=$1; shift",
+    "for path do",
+    "  [ -n \"$path\" ] || exit 1",
+    // find's target type distinguishes known missing/cyclic links (N/L) from
+    // failed observations; shell -f/-d predicates hide permission and I/O errors.
+    "  kind=$(find \"$path\" -maxdepth 0 -printf \"%Y\") || exit 1",
+    "  case \"$kind\" in",
+    "    f) sha256sum -- \"$path\" || exit 1 ;;",
+    "    d) : ;;",
+    "    N|L) continue ;;",
+    "    *) exit 1 ;;",
+    "  esac",
+    // Pair the lexical link with its resolved target/mode before hashing. Keeping
+    // each pair together prevents swapping equal-byte targets between two links.
+    "  target=$(readlink -fn -- \"$path\" && printf .) || exit 1",
+    "  target=${target%.}",
+    "  if [ \"$kind\" = d ]; then",
+    "    case \"$target\" in \"$root\"|\"$root\"/*) : ;; *) exit 1 ;; esac",
+    "  fi",
+    "  referent=$(LC_ALL=C QUOTING_STYLE=c stat -L -c \"%f %N\" -- \"$path\" \"$target\") || exit 1",
+    "  printf \"%s\" \"$referent\" | sha256sum || exit 1",
+    "done' sh \"$root\")",
+    "link_bytes=$(printf '%s' \"$link_bytes\" | LC_ALL=C sort)",
+    "if [ -n \"$link_bytes\" ]; then",
+    "untracked=$(printf '%s\\0%s\\0%s\\0%s' \"$untracked_bytes\" \"$workspace_modes\" \"$workspace_bytes\" \"$link_bytes\" | sha256sum)",
+    "else",
+    "untracked=$(printf '%s\\0%s\\0%s' \"$untracked_bytes\" \"$workspace_modes\" \"$workspace_bytes\" | sha256sum)",
+    "fi",
+    "untracked=${untracked%% *}",
+    "printf '%s\\n%s\\n%s\\n%s\\n%s\\n%s\\n' 'SORTIE_DOCKER_WORKSPACE_V1' \"$actual_cwd\" \"$root\" \"$tree\" \"$tracked\" \"$untracked\"",
+    "fi",
+].join("\n");
+/** Hash the fixed container's actual workspace, including non-Git and ignored inputs. */
+export async function captureDockerWorkspaceSnapshot(containerID, cwd) {
+    if (!CONTAINER_ID.test(containerID) || !posix.isAbsolute(cwd) || posix.normalize(cwd) !== cwd || cwd.includes("\0"))
+        return undefined;
+    try {
+        const result = await exec("docker", ["exec", "--workdir", cwd, containerID, "sh", "-lc", SNAPSHOT_COMMAND], {
+            encoding: "buffer", timeout: 30_000, maxBuffer: 64 * 1024 * 1024,
+        });
+        const output = result.stdout;
+        let offset = 0;
+        const line = () => {
+            const end = output.indexOf(0x0a, offset);
+            if (end < 0)
+                return undefined;
+            const value = output.subarray(offset, end).toString("utf8");
+            offset = end + 1;
+            return value;
+        };
+        if (line() !== SNAPSHOT_MARKER)
+            return undefined;
+        const actualCwd = line(), repositoryRoot = line(), tree = line(), tracked = line(), untracked = line();
+        if (!actualCwd || !isDockerWorkspacePath(actualCwd) || !repositoryRoot || !posix.isAbsolute(repositoryRoot) || !tree || !/^[a-f0-9]{40,64}$/u.test(tree) ||
+            !tracked || !/^[a-f0-9]{64}$/u.test(tracked) || !untracked || !/^[a-f0-9]{64}$/u.test(untracked) || offset !== output.length)
+            return undefined;
+        const source = `sha256:${createHash("sha256").update(`git-tree\0${repositoryRoot}\0${tree}`).digest("hex")}`;
+        // Preserve existing non-alias identities. For aliases bind the real execution
+        // directory too: retargeting within the same repository must stale the proof.
+        const physicalCwd = actualCwd === cwd ? [] : [actualCwd];
+        const candidate = `sha256:${createHash("sha256").update(JSON.stringify([containerID, cwd, repositoryRoot, tree, tracked, untracked, ...physicalCwd])).digest("hex")}`;
+        return { container_id: containerID, cwd, ...(actualCwd === cwd ? {} : { actual_cwd: actualCwd }),
+            repository_root: repositoryRoot, source, candidate };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isDockerContainerID(value) {
+    return typeof value === "string" && CONTAINER_ID.test(value);
+}
+export function isDockerWorkspacePath(value) {
+    return typeof value === "string" && value.length > 0 && posix.isAbsolute(value) &&
+        posix.normalize(value) === value && !value.includes("\0");
+}
+const READ_WORKSPACE = String.raw `
+import hashlib, json, os, stat, sys
+root, requested, offset, limit = sys.argv[1], sys.argv[2], int(sys.argv[3]), int(sys.argv[4])
+requested_path = os.path.join(root, requested)
+path = os.path.realpath(requested_path)
+if os.path.commonpath([root, path]) != root:
+    # Admit only the actual candidate entry and its bound regular-file target.
+    # A canceled outside-directory hop can normalize inside root yet reach a
+    # different link; file/../ hops must not create an entry either. Resolve the
+    # parent to exclude root Git bookkeeping even through directory aliases.
+    lexical = os.path.abspath(requested_path)
+    entry = os.path.join(os.path.realpath(os.path.dirname(lexical)), os.path.basename(lexical))
+    if (os.path.commonpath([root, lexical]) != root or os.path.commonpath([root, entry]) != root or
+            os.path.relpath(entry, root).split(os.sep)[0] == ".git" or not os.path.islink(entry) or
+            os.path.realpath(entry) != path or not os.path.islink(requested_path) or
+            not stat.S_ISREG(os.stat(entry).st_mode)):
+        raise ValueError("file-outside-candidate-workspace")
+if os.path.isdir(path):
+    entries = sorted(os.listdir(path))
+    result = {"kind": "directory", "entries": entries[offset - 1:offset - 1 + limit], "total": len(entries)}
+elif stat.S_ISREG(os.stat(path).st_mode):
+    h = hashlib.sha256()
+    lines, total, size = [], 0, 0
+    excerpt, pending = bytearray(), False
+    with open(path, "rb") as stream:
+        # Bound allocations even when a logical line is a large generated file.
+        for block in iter(lambda: stream.readline(64000), b""):
+            h.update(block)
+            pending = True
+            if offset <= total + 1 < offset + limit and size < 64000:
+                retained = block[:64000-size]
+                excerpt.extend(retained)
+                size += len(retained)
+            if block.endswith(b"\n"):
+                total += 1
+                if excerpt:
+                    lines.append([total, excerpt.decode("utf-8", errors="replace")])
+                    excerpt.clear()
+                pending = False
+    if pending:
+        total += 1
+        if excerpt:
+            lines.append([total, excerpt.decode("utf-8", errors="replace")])
+    result = {"kind": "file", "lines": lines, "total_lines": total, "sha256": h.hexdigest()}
+else:
+    raise ValueError("candidate-file-not-readable")
+print(json.dumps({"path": path, **result}, ensure_ascii=True))
+`;
+/** Inspect bytes, never execute caller-supplied code. The Review envelope's
+ * immutable Docker candidate must match both before and after the read. */
+export async function readDockerWorkspaceFile(containerID, cwd, candidate, path, offset = 1, limit = 200) {
+    if (!/^sha256:[a-f0-9]{64}$/u.test(candidate) || typeof path !== "string" || path.includes("\0") ||
+        !Number.isSafeInteger(offset) || offset < 1 || !Number.isSafeInteger(limit) || limit < 1 || limit > 2000) {
+        throw new Error("docker-candidate-read-invalid");
+    }
+    const before = await captureDockerWorkspaceSnapshot(containerID, cwd);
+    if (!before || before.candidate !== candidate)
+        throw new Error("docker-review-candidate-stale-or-unavailable");
+    // An admitted 2000-name page (255-byte names) can expand sixfold in JSON;
+    // the 64 KB file excerpt also needs escaping headroom. Keep the read limits.
+    let result;
+    try {
+        const { stdout } = await exec("docker", ["exec", "--workdir", cwd, containerID, "python3", "-I", "-S", "-c", READ_WORKSPACE,
+            before.repository_root, path, String(offset), String(limit)], { encoding: "utf8", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
+        result = JSON.parse(stdout);
+    }
+    catch (error) {
+        // A failed observation is not a reason to switch recipes. Use the existing
+        // shell reader only after the task itself confirms Python is absent.
+        let absent = false;
+        try {
+            const probe = await exec("docker", ["exec", "--workdir", cwd, containerID, "sh", "-c",
+                "if command -v python3 >/dev/null 2>&1; then printf 'SORTIE_PYTHON_PRESENT'; else printf 'SORTIE_PYTHON_ABSENT'; fi"], { encoding: "utf8", timeout: 30_000, maxBuffer: 1024 });
+            absent = probe.stdout === "SORTIE_PYTHON_ABSENT";
+        }
+        catch { /* Preserve the original read failure when capability is unknown. */ }
+        if (!absent)
+            throw error;
+        result = await readDockerWorkspaceWithoutPython(containerID, cwd, before.repository_root, path, offset, limit);
+    }
+    const after = await captureDockerWorkspaceSnapshot(containerID, cwd);
+    if (!after || after.candidate !== candidate)
+        throw new Error("docker-review-candidate-changed-during-read");
+    return { workspace: before, ...result };
+}

package/dist/plugin/docker-workspace-read-fallback.d.ts

@@ -0,0 +1,2 @@
+/** Same result as the Python reader, without mutating/installing in the task. */
+export declare function readDockerWorkspaceWithoutPython(containerID: string, cwd: string, root: string, requested: string, offset: number, limit: number): Promise<Record<string, unknown>>;

package/dist/plugin/docker-workspace-read-fallback.js

@@ -0,0 +1,185 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+// Fixed read-only transport for images with Git/coreutils but no Python. Paths
+// are argv, never shell source. Node frames names and streams file bytes so long
+// logical lines cannot become unbounded shell variables or buffered stdout.
+const READ = String.raw `
+set -eu
+root=$1; requested=$2; lexical=$3; parent=$4; name=$5
+fail() { printf '%s\n' "$1" >&2; exit 1; }
+physical() {
+  resolved=$(readlink -fn -- "$1" && printf .) || fail file-outside-candidate-workspace
+  resolved=${"$"}{resolved%.}
+}
+inside() {
+  [ "$root" = / ] && return 0
+  case "$1" in "$root"|"$root"/*) return 0 ;; esac
+  return 1
+}
+physical "$requested"; path=$resolved
+if ! inside "$path"; then
+  physical "$parent"; entry="${"$"}{resolved%/}/$name"
+  inside "$lexical" && inside "$entry" || fail file-outside-candidate-workspace
+  case "$entry" in "$root/.git"|"$root/.git/"*) fail file-outside-candidate-workspace ;; esac
+  [ -L "$entry" ] && [ -L "$requested" ] && [ -f "$entry" ] || fail file-outside-candidate-workspace
+  physical "$entry"
+  [ "$resolved" = "$path" ] || fail file-outside-candidate-workspace
+fi
+if [ -d "$path" ]; then kind=d
+elif [ -f "$path" ]; then kind=f
+else fail candidate-file-not-readable
+fi
+printf 'SORTIE_READ_V1\0%s\0%s\0' "$path" "$kind"
+if [ "$kind" = f ]; then cat -- "$path"
+else find "$path" -mindepth 1 -maxdepth 1 -print0
+fi
+`;
+/** Same result as the Python reader, without mutating/installing in the task. */
+export function readDockerWorkspaceWithoutPython(containerID, cwd, root, requested, offset, limit) {
+    // Keep the raw path for real filesystem resolution; a normalized canceled
+    // directory hop must not select a different entry outside the candidate.
+    const raw = posix.isAbsolute(requested) ? requested : `${root}/${requested}`;
+    const lexical = posix.resolve(root, requested);
+    return new Promise((resolve, reject) => {
+        const child = spawn("docker", ["exec", "--workdir", cwd, containerID, "sh", "-c", READ,
+            "sortie-read", root, raw, lexical, posix.dirname(lexical), posix.basename(lexical)], { stdio: ["ignore", "pipe", "pipe"], timeout: 30_000 });
+        let failure, stderr = Buffer.alloc(0), field = Buffer.alloc(0);
+        const header = [], lines = [];
+        const hash = createHash("sha256");
+        let total = 0, size = 0, pending = false, excerpt = [];
+        // Keep only the first offset+limit directory names in a max-heap, rather
+        // than retaining an entire large directory in the gateway process.
+        const names = [], count = Math.min(Number.MAX_SAFE_INTEGER, offset - 1 + limit);
+        const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+        const fail = (error) => {
+            if (!failure) {
+                failure = error instanceof Error ? error : new Error(String(error));
+                child.kill();
+            }
+        };
+        const keepName = (value) => {
+            if (!value.length)
+                throw new Error("docker-candidate-directory-frame-invalid");
+            // find emits actual paths using its existing -print0 capability. Keep
+            // filenames only, without requiring image-side GNU -printf or JSON tools.
+            value = Buffer.from(posix.basename(utf8.decode(value)));
+            total++;
+            if (names.length < count) {
+                names.push(Buffer.from(value));
+                for (let i = names.length - 1; i > 0;) {
+                    const parent = (i - 1) >>> 1;
+                    if (Buffer.compare(names[parent], names[i]) >= 0)
+                        break;
+                    [names[parent], names[i]] = [names[i], names[parent]];
+                    i = parent;
+                }
+            }
+            else if (Buffer.compare(value, names[0]) < 0) {
+                names[0] = Buffer.from(value);
+                for (let i = 0;;) {
+                    const left = i * 2 + 1, right = left + 1;
+                    if (left >= names.length)
+                        break;
+                    const next = right < names.length && Buffer.compare(names[right], names[left]) > 0 ? right : left;
+                    if (Buffer.compare(names[i], names[next]) >= 0)
+                        break;
+                    [names[i], names[next]] = [names[next], names[i]];
+                    i = next;
+                }
+            }
+        };
+        const finishLine = () => {
+            total++;
+            if (excerpt.length) {
+                lines.push([total, Buffer.concat(excerpt).toString("utf8")]);
+                excerpt = [];
+            }
+            pending = false;
+        };
+        const fileBytes = (chunk) => {
+            hash.update(chunk);
+            for (let start = 0; start < chunk.length;) {
+                const newline = chunk.indexOf(10, start), end = newline < 0 ? chunk.length : newline + 1;
+                pending = true;
+                if (total >= offset - 1 && total < offset - 1 + limit && size < 64000) {
+                    const kept = chunk.subarray(start, Math.min(end, start + 64000 - size));
+                    excerpt.push(Buffer.from(kept));
+                    size += kept.length;
+                }
+                if (newline >= 0)
+                    finishLine();
+                start = end;
+            }
+        };
+        child.stdout.on("data", (chunk) => {
+            if (failure)
+                return;
+            try {
+                let start = 0;
+                while (start < chunk.length && header.length < 3) {
+                    const end = chunk.indexOf(0, start);
+                    const part = chunk.subarray(start, end < 0 ? chunk.length : end);
+                    if (field.length + part.length > 65536)
+                        throw new Error("docker-candidate-read-header-invalid");
+                    field = Buffer.concat([field, part]);
+                    if (end < 0)
+                        return;
+                    header.push(utf8.decode(field));
+                    field = Buffer.alloc(0);
+                    start = end + 1;
+                    if (header.length === 3 && (header[0] !== "SORTIE_READ_V1" || !posix.isAbsolute(header[1]) || !["f", "d"].includes(header[2]))) {
+                        throw new Error("docker-candidate-read-header-invalid");
+                    }
+                }
+                if (header.length < 3)
+                    return;
+                if (header[2] === "f")
+                    fileBytes(chunk.subarray(start));
+                else
+                    while (start < chunk.length) {
+                        const end = chunk.indexOf(0, start), part = chunk.subarray(start, end < 0 ? chunk.length : end);
+                        if (field.length + part.length > 65536)
+                            throw new Error("docker-candidate-directory-frame-invalid");
+                        field = Buffer.concat([field, part]);
+                        if (end < 0)
+                            return;
+                        keepName(field);
+                        field = Buffer.alloc(0);
+                        start = end + 1;
+                    }
+            }
+            catch (error) {
+                fail(error);
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            if (stderr.length < 64000)
+                stderr = Buffer.concat([stderr, chunk.subarray(0, 64000 - stderr.length)]);
+        });
+        child.once("error", error => { fail(error); reject(error); });
+        child.once("close", (code, signal) => {
+            if (failure) {
+                reject(failure);
+                return;
+            }
+            if (code !== 0 || signal) {
+                reject(new Error(`docker-candidate-read-failed:${signal ?? code}:${stderr.toString("utf8")}`));
+                return;
+            }
+            if (header.length !== 3 || field.length) {
+                reject(new Error("docker-candidate-read-frame-incomplete"));
+                return;
+            }
+            if (header[2] === "f") {
+                if (pending)
+                    finishLine();
+                resolve({ path: header[1], kind: "file", lines, total_lines: total, sha256: hash.digest("hex") });
+            }
+            else {
+                names.sort(Buffer.compare);
+                resolve({ path: header[1], kind: "directory", entries: names.slice(offset - 1, offset - 1 + limit).map(name => utf8.decode(name)), total });
+            }
+        });
+    });
+}