@sema-agent/core 7.17.4 → 7.17.6

package/dist/core/remote-env.js

@@ -40,5 +40,8 @@ export function isSuspendable(env) {
     return isRemoteExecutionEnv(env) && env.capabilities.suspendable && missingRestoreSurface(env).length === 0;
 }
 export function isIsolated(env) {
-    return isRemoteExecutionEnv(env) ? env.capabilities.isolation : false;
+    return isRemoteExecutionEnv(env) ? env.capabilities.isolation === true : false;
+}
+export function boundaryIsTheSandbox(env) {
+    return isIsolated(env);
 }

package/dist/core/runner/prepare-hands-readface.js

@@ -1,6 +1,7 @@
 import { emitTrace } from "../trace.js";
 import { StubExecutionEnv } from "../stub-env.js";
 import { hasBackgroundShell } from "../background-shell.js";
+import { boundaryIsTheSandbox } from "../remote-env.js";
 import { defaultTaskRegistry } from "../task-registry.js";
 import { bashReadBoundaryProbe, bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, pdfModelCapabilitiesOf, resolveReadDenyBuiltins, inheritSessionReadFileState, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
 import { resolveKey, sha256 } from "../../tools/fs/safety.js";
@@ -293,6 +294,13 @@ export async function prepareHandsMount(input) {
                         sessionSeats.reanchor(sessionId, readFileState, ownCommittedTailEntryId);
                 }
                 : undefined;
+        const shellReadBoundary = () => ({
+            roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
+            ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
+            ...(executionEnv.homeDir !== undefined ? { homeDir: executionEnv.homeDir } : {}),
+            denyMatch: (p) => readDenyMatcher?.matchPath(p)?.pattern ?? null,
+            ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
+        });
         const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
             ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
             ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),
@@ -306,6 +314,7 @@ export async function prepareHandsMount(input) {
             ...(input.onFileEdited !== undefined ? { onFileEdited: input.onFileEdited } : {}),
             includeShell: handsIncludeShell,
             readOnly: handsReadOnly,
+            shellReadBoundary,
             ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),
             taskRegistry: defaultTaskRegistry,
             taskOwner: hostTaskId,
@@ -346,18 +355,11 @@ export async function prepareHandsMount(input) {
         if (!(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
             if (shellGate === "off") {
                 deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — the read boundary is ` +
-                    `still judged on every command (a deny-listed or out-of-root read asks; the ask is mandated), but no ` +
+                    `still judged on every command (a deny-listed or out-of-root read asks; the ask is mandated${boundaryIsTheSandbox(executionEnv) ? "" : "; a read that only leaves the roots after symlink resolution is refused before it runs"}), but no ` +
                     `residual shell-risk classifier is installed: writes, egress and unknown commands are adjudicated by ` +
                     `the ordinary policy/hook chain only. Set spec.shellGate to "classify" or "always" if this deployment ` +
                     `expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
             }
-            const shellReadBoundary = () => ({
-                roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
-                ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
-                ...(executionEnv.homeDir !== undefined ? { homeDir: executionEnv.homeDir } : {}),
-                denyMatch: (p) => readDenyMatcher?.matchPath(p)?.pattern ?? null,
-                ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
-            });
             const installShellSeat = (name) => {
                 const tierBefore = irreversibilityTier.get(name);
                 const seatOwned = !egressTools.has(name) && tierBefore !== "always" && tierBefore !== "maybe";

package/dist/core/tool-catalog-entries.js

@@ -56,7 +56,7 @@ export const TOOL_CATALOG_ENTRIES = [
     },
     {
         id: "bash", name: "Bash", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"],
-        cards: ["bash", "bash_invalid_timeout"],
+        cards: ["bash", "readonly_out_of_root", "bash_invalid_timeout"],
         face: {
             family: "shell", effect: "write", contentOrigin: "execution", contract: c(FULL_SHELL_CONTRACT_ID),
             ruleFace: SHELL_RULE_FACE,

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -140,10 +140,22 @@ export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<
 export declare function carriesShellRedirection(text: string): boolean;
 /** What {@link splitShellCompoundSegments} produces: the connector-delimited segments, plus which of
  *  them a PIPE fed (the read-only classifier's stdin arm needs that distinction; a rule lane does not). */
+/** The connector bash ran a segment through — `"start"` for the first one. A closed set, because the read
+ *  boundary distinguishes all four: `&&` is the only one under which the previous segment is known to have
+ *  exited ZERO, `||` is the only one under which the previous segment may have been SKIPPED ENTIRELY, `|`
+ *  puts the segment in a subshell whose directory changes never reach the parent, and `;` is plain sequence. */
+export type ShellSegmentConnector = "start" | ";" | "&&" | "||" | "|";
 export interface ShellCompoundSegments {
     segments: string[];
-    /** Parallel to {@link segments}: was this segment preceded by `|` (rather than `;`/`&&`/`||`/nothing)? */
+    /** Parallel to {@link segments}: was this segment preceded by `|` (rather than `;`/`&&`/`||`/nothing)?
+     *  A VIEW of {@link connectors}, derived at the one place both are minted — two rows that could drift are
+     *  two rows that will. */
     pipeFed: boolean[];
+    /** Parallel to {@link segments}: the connector bash reached this segment through. Read by the read
+     *  boundary, where it is the difference between a directory change the shell itself proved happened and
+     *  one this walk cannot verify. A consumer that does not read it gets the unverified reading, which is
+     *  the fail-closed one. */
+    connectors: ShellSegmentConnector[];
 }
 /**
  * Split a compound command into the segments bash would run, or refuse the whole string.
@@ -228,10 +240,10 @@ export interface BashReadonlyRootBoundary {
      *  allowlists classifies by its ordinary form and can auto-run a traversal unjudged);
      *  ② LEXICAL only — an in-root symlink whose target is a
      *  guarded path reads as its innocent spelling here, exactly as it does for the containment half
-     *  (the enforcing/canonicalizing recheck is the bash_readonly leg's job via checkedPaths; the
+     *  (the enforcing/canonicalizing recheck is both shell faces' execute leg, via checkedPaths; the
      *  classify auto-allow lane has no I/O seat by contract). The structured read faces judge BOTH
-     *  views (canonical + lexical) — this seat is the shell lane's honest-friction floor, not its
-     *  security boundary. The `bash_readonly` face deliberately does NOT wire this seat (its
+     *  views (canonical + lexical); what this seat is and is not is stated once, at
+     *  `shell.read_boundary.friction_floor`. The `bash_readonly` face deliberately does NOT wire this seat (its
      *  roots containment + command allowlist double gate is the deployment's own read-safety
      *  declaration — v1 ruling). */
     denyMatch?: (resolvedPath: string) => string | null;
@@ -315,6 +327,20 @@ export interface CompoundReadonlyVerdict {
      * and miss the other.
      */
     undecidedPaths?: readonly string[];
+    /** The KERNEL spellings of the {@link checkedPaths} / {@link undecidedPaths} entries whose operand
+     *  traverses `..`: the same absolute path, `..` UNCOLLAPSED ({@link OperandSpellings.spelled}). A fold
+     *  names a different file whenever a parent step follows a symlink — `<root>/link/../x` is
+     *  `dirname(realpath(link))/x` to the kernel, `<root>/x` to the text. Absent when nothing traverses
+     *  `..`, and never a replacement: a resolving caller judges these BESIDE the folded entries, list for
+     *  list. Containment, deny judgment and every `reason` here stay decided on the FOLDED form — this file
+     *  is zero-I/O, and only a caller holding the filesystem can tell the two apart. */
+    checkedSpellings?: readonly string[];
+    /** The kernel spellings of {@link undecidedPaths} — see {@link checkedSpellings}. */
+    undecidedSpellings?: readonly string[];
+    /** The kernel spellings of {@link outOfRootPaths} — see {@link checkedSpellings}. A caller GRANTING
+     *  anything off a resolved out-of-root path judges this beside it: the two can disagree about whether
+     *  the target is back inside. */
+    outOfRootSpellings?: readonly string[];
     /**
      * Operands (written spellings) the walk could NOT resolve at all — a `~user` form, a `~` under no declared
      * home, an argument the shell rewrites (brace/variable/command expansion), a `cd` target it cannot follow
@@ -389,6 +415,20 @@ export declare function formatOutOfRootReadApprovalOption(directory: string): st
  *  has no filesystem and stays lexical, and a REMOTE env keeps the lexical behaviour (its
  *  `canonicalPath` is an RPC per candidate). */
 export declare function resolveOperandLexically(base: string | undefined, operand: string, homeDir: string | undefined): string | undefined;
+/** One operand's two absolute spellings. `folded` has its `..` collapsed in the TEXT and is the
+ *  containment answer — every root comparison, deny judgment and verdict field here is built from it.
+ *  `spelled` keeps those segments, the walk the KERNEL performs: each prefix resolves (symlinks included)
+ *  BEFORE a parent step applies, so `<root>/link/../x` names `dirname(realpath(link))/x`. Present ONLY
+ *  when the operand traverses `..`; a filesystem-resolving caller judges it BESIDE the folded form. */
+export interface OperandSpellings {
+    /** The `..`-collapsed absolute path — what containment is decided on. */
+    folded: string;
+    /** The uncollapsed absolute path, when the operand traverses `..`. */
+    spelled?: string;
+}
+/** Resolve one operand into {@link OperandSpellings}, or `undefined` on the same unresolvable operands
+ *  {@link resolveOperandLexically} reports (it is this function's folded half). */
+export declare function resolveOperandSpellings(base: string | undefined, operand: string, homeDir: string | undefined): OperandSpellings | undefined;
 /** Whether a command the grammar gate REFUSED WHOLE may READ a file the boundary never judged. The answer is the
  *  complement of a WHITELIST: the command is exempt only when every part of it is a shape the scan fully understands
  *  and none of those shapes reads a file outside the walk's reach — everything else is read evidence, so a token the
@@ -459,7 +499,8 @@ opts?: {
  * so this face bounds where a command may NAME a file, not where the kernel will ultimately take it.
  * A deployment that needs filesystem-true containment resolves the operands itself, and this
  * verdict hands it the list to resolve ({@link CompoundReadonlyVerdict.checkedPaths}, on both arms).
- * `createBashReadonlyTool` is that caller for the `bash_readonly` leg and does it on a local env.
+ * The engine's own shell legs are that caller on a local env — the read-only face before it runs an
+ * allowlisted command, the full face after its gate allowed one.
  */
 export declare function classifySimpleCommandReadBoundary(command: string, boundary: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
 /**