@sema-agent/core 5.30.0 → 5.32.0

package/dist/tools/fs/read-face.d.ts

@@ -2,6 +2,12 @@
  *  `"open"` = the containment step is skipped (canonicalization, deny set, UNC out-of-set refusal
  *  and the type gates all still run). */
 export type ReadFace = "open" | "roots";
+/** Loud value gate (#123): a `readFace` seat carries exactly "open" | "roots" — anything else
+ *  (case variants, truthy garbage) refuses at wiring time, never folds to a default. Exported
+ *  module-internally (not on the package surface) so prepare's unconditional config-guard leg can
+ *  screen the seats on runs that never mount hands — the resolver only runs beside a mount, and a
+ *  garbage value must not become silently legal on the hands-less path (5.30 re-review). */
+export declare function assertReadFaceValue(v: unknown, seat: string): ReadFace | undefined;
 /** Inputs to {@link resolveReadFace} — all structural/declaration facts, never permission modes
  *  (a deliberate axis separation: this shape carries facts, not verdicts). */
 export interface ReadFaceInputs {
@@ -23,6 +29,13 @@ export interface ReadFaceInputs {
      *  "open"… no — see the resolution order: an EXPLICIT open still wins (row 4 is a default, not a
      *  clamp); what it changes is that NOTHING implicit opens a bash-less mount. */
     fullShellReachable: boolean;
+    /** #237 — observation hook for the ONE silent branch of the order: row 1's deployment-seat clamp
+     *  (readOnly mount + deps "open" + NO task seat). Fired exactly when the deps declaration was the
+     *  deciding seat and the mount overrode it — not when a task-level "roots" pinned the same value
+     *  anyway (the mount changed nothing there, and announcing it would claim a false cause), and
+     *  never on the throw rows (those are already loud). The resolver stays the single owner of the
+     *  clamp predicate; stations own delivery/dedup ({@link deploymentReadFaceClampNotice}). */
+    onDeploymentClamp?: () => void;
 }
 /**
  * The ONE resolution order (§2.2), first hit wins. prepare-task AND createHandsToolkit both call
@@ -41,3 +54,17 @@ export interface ReadFaceInputs {
  *  5. default: ROOTS (D-1b — the engine never opens implicitly).
  */
 export declare function resolveReadFace(i: ReadFaceInputs): ReadFace;
+/**
+ * #237 — the ONE text of the deployment-clamp announcement (`config.read_face_deployment_clamped`).
+ * Both stations deliver THIS object through their own `deliverEngineNotice` call (prepare-task with
+ * the `RunnerDeps.onNotice` seat, once per notice sink — the sink, not the deps object, because the
+ * Runner rebuilds its deps; `createHandsToolkit` with its band-local `HandsToolkitOptions.onNotice`
+ * seat — toolkit creation is itself the one-per-mount boot moment, and an absent seat prints the
+ * same line via `console.warn`). Built here, import-free, so the message can never fork between
+ * the stations.
+ */
+export declare function deploymentReadFaceClampNotice(): {
+    code: string;
+    message: string;
+    detail: Record<string, unknown>;
+};

package/dist/tools/fs/read-face.js

@@ -1,4 +1,4 @@
-function assertReadFaceValue(v, seat) {
+export function assertReadFaceValue(v, seat) {
     if (v === undefined)
         return undefined;
     if (v === "open" || v === "roots")
@@ -16,6 +16,8 @@ export function resolveReadFace(i) {
             e.code = "config.read_face_readonly_conflict";
             throw e;
         }
+        if (deps === "open" && spec === undefined)
+            i.onDeploymentClamp?.();
         return "roots";
     }
     if (i.orgGoverned) {
@@ -36,3 +38,10 @@ export function resolveReadFace(i) {
         return "roots";
     return "roots";
 }
+export function deploymentReadFaceClampNotice() {
+    return {
+        code: "config.read_face_deployment_clamped",
+        message: `readFace (deployment seat): the deployment-wide "open" declaration is not in force on this read-only (verifier) mount — clamped to "roots" (stricter-wins: the mount's containment is load-bearing and never openable). Other mounts still honor "open".`,
+        detail: { seat: "readFace (deployment seat)", declared: "open", inForce: "roots", cause: "read_only_mount" },
+    };
+}

package/dist/tools/fs/safety.d.ts

@@ -270,6 +270,7 @@ export declare function lexicalViewOf(spelled: string, base: string): string;
 export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRootsCanonical?: readonly string[], exactFileReadExemption?: (canonicalKey: string) => boolean, readDeny?: {
     matchTarget(canonicalKey: string, lexicalView?: string): {
         pattern: string;
+        matchedView?: string;
     } | null;
 }, readFace?: "open" | "roots"): Promise<{
     ok: true;

package/dist/tools/fs/safety.js

@@ -49,7 +49,7 @@ const PROC_SENSITIVE_SUFFIXES = ["/environ", "/cmdline", "/auxv", "/maps", "/mem
 function isProcSensitiveFile(key) {
     return key.startsWith("/proc/") && PROC_SENSITIVE_SUFFIXES.some((suf) => key.endsWith(suf));
 }
-const WIN_RESERVED_RE = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.[^\\/]*)?$/i;
+const WIN_RESERVED_RE = /^(CON|PRN|AUX|NUL|COM[0-9¹²³]|LPT[0-9¹²³]|CONIN\$|CONOUT\$)(\.[^\\/]*)?$/i;
 export function isWinFormPath(p) {
     return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\") || (!p.startsWith("/") && p.includes("\\"));
 }
@@ -273,10 +273,21 @@ function stripWin32ExtendedPrefix(p) {
     if (!p.startsWith("\\\\?\\"))
         return p;
     const rest = p.slice(4);
-    const unc = /^UNC[\\/]/i.exec(rest);
-    if (unc)
-        return "\\\\" + rest.slice(unc[0].length);
-    return rest;
+    const unc = /^UNC\\/i.exec(rest);
+    const body = unc !== null ? rest.slice(unc[0].length) : /^[A-Za-z]:\\/.test(rest) ? rest.slice(3) : undefined;
+    if (body === undefined)
+        return p;
+    if (body !== "") {
+        for (const seg of body.split("\\")) {
+            if (seg === "" || seg === "." || seg === "..")
+                return p;
+            if (seg.endsWith(".") || seg.endsWith(" ") || seg.includes("/"))
+                return p;
+            if (WIN_RESERVED_RE.test(seg))
+                return p;
+        }
+    }
+    return unc ? "\\\\" + rest.slice(unc[0].length) : rest;
 }
 function foldUncLexically(p) {
     const body = p.slice(2);
@@ -295,7 +306,8 @@ function foldUncLexically(p) {
                 out.pop();
             continue;
         }
-        out.push(seg);
+        const stripped = seg.replace(/[. ]+$/, "");
+        out.push(stripped.length > 0 ? stripped : seg);
     }
     const anchor = `\\\\${host}${share !== undefined ? `\\${share}` : ""}`;
     return { key: out.length > 0 ? `${anchor}\\${out.join("\\")}` : anchor, climbedAboveShare: climbed };
@@ -329,11 +341,15 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
     if (readDeny !== undefined) {
         const hit = readDeny.matchTarget(key, lexicalViewOf(path, baseCwd ?? rootCanonical));
         if (hit !== null) {
+            const lexicalHit = hit.matchedView !== undefined && hit.matchedView !== key;
+            const judged = lexicalHit
+                ? `the requested path's spelling ("${hit.matchedView}") matches`
+                : `the target matches`;
             return {
                 ok: false,
                 violation: {
                     code: "read_path_denied",
-                    message: `reading "${path}" ${key !== path ? `(canonical target: "${key}") ` : ""}is refused: the target matches the sensitive-path read deny list (pattern "${hit.pattern}"). This list guards credential-class paths and applies regardless of the containment roots.`,
+                    message: `reading "${path}" ${key !== path ? `(canonical target: "${key}") ` : ""}is refused: ${judged} the sensitive-path read deny list (pattern "${hit.pattern}"). This list guards credential-class paths and applies regardless of the containment roots.`,
                     target: key,
                     pattern: hit.pattern,
                 },
@@ -373,6 +389,9 @@ export async function canonicalizeTarget(env, path, signal, baseCwd) {
         return { ok: false, message: `path "${path}" is a Win32 device-namespace path (\\\\.\\ names a raw device object, not a file); refused.` };
     }
     const unprefixed = stripWin32ExtendedPrefix(path);
+    if (unprefixed.startsWith("\\\\?\\")) {
+        return { ok: false, message: `path "${path}" is a Win32 extended-length namespace path with no DOS-path equivalent (only \\\\?\\<drive>: and \\\\?\\UNC\\ forms name files); refused.` };
+    }
     if (isUncPath(unprefixed) && isWinFormPath(unprefixed)) {
         const folded = foldUncLexically(unprefixed);
         if (folded.climbedAboveShare) {

package/dist/tools/fs/search.js

@@ -807,7 +807,8 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
     if (denyOut !== undefined && walked.denyPruned > 0) {
         denyOut.withheld = { kind: "pruned_count", count: walked.denyPruned, patterns: walked.denyPatterns };
     }
-    let caveat = walkCaveat(walked, true) + denyWithheldNote(walked);
+    let honestyCaveat = walkCaveat(walked, true);
+    const denyNote = denyWithheldNote(walked);
     let files = walked.files;
     files.sort();
     const cap = p.head_limit === 0 ? Infinity : Math.max(1, Math.floor(p.head_limit ?? GREP_DEFAULT_CAP));
@@ -962,11 +963,12 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
         if (multilineSkippedFiles > 0)
             extra.push(`${multilineSkippedFiles} file(s) skipped by multiline matching (content over ${longLineLimit} chars; the pattern's worst-case matching cost grows superlinearly with input length on the fallback engine)`);
         if (extra.length > 0) {
-            caveat = caveat.length > 0
-                ? caveat.replace(/\]$/, `; ${extra.join("; ")}]`)
+            honestyCaveat = honestyCaveat.length > 0
+                ? honestyCaveat.replace(/\]$/, `; ${extra.join("; ")}]`)
                 : `\n…[results may be incomplete: ${extra.join("; ")}]`;
         }
     }
+    const caveat = honestyCaveat + denyNote;
     const paged = (arr) => (off > 0 ? arr.slice(off, off + cap) : arr);
     const offNote = off > 0 ? `\n[offset ${off}]` : "";
     if (mode === "files_with_matches") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.30.0",
+  "version": "5.32.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",