@sema-agent/core 7.37.1 → 7.38.1

package/dist/tools/fs/index.js

@@ -16,7 +16,7 @@ import { BASH_READONLY_DEFAULT_ALLOW } from "./bash-readonly-classifier.js";
 export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
 import { checkedReadDenyHomes, compileReadDeny, compileWriteDeny, readDenyBuiltinConfigOf, readDenyPatternRun } from "./read-deny.js";
 import { withGateTimeout } from "../../core/gate-bounded-await.js";
-import { placeReadDenyAtHome, readDenyPlacedLater } from "./read-deny-home.js";
+import { carryHomeViews, homeViewsAt, placeReadDenyAtHome, placementViewsOf, readDenyPlacedLater, sayPlacementLost } from "./read-deny-home.js";
 import { deploymentFaceClampNotice, resolveContainmentFace } from "./containment-face.js";
 export * from "./containment-face.js";
 import {} from "./fs-shared.js";
@@ -48,9 +48,17 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
     const compileAt = (homes, linked) => compileReadDeny(readDenyAdditions, "HandsToolkitOptions.readDenyPatterns", readDenyBuiltinCfg, readDenyRules, homes, linked);
     const unplaced = compileAt([]);
     const carried = readDenyHomes !== undefined && opts.readDenyHomeLinks !== undefined;
+    const carriedViews = carried ? placementViewsOf(opts.readDenyHomes) : undefined;
+    if (carried && carriedViews === undefined)
+        sayPlacementLost();
     const placesNothing = !unplaced.entries.some((e) => readDenyPatternRun(e.pattern).homeAnchored);
-    const late = carried || placesNothing ? undefined : readDenyPlacedLater(unplaced, () => placeReadDenyAtHome(env, compileAt, readDenyHomes));
-    const readDeny = late?.matcher ?? (carried ? compileAt(readDenyHomes, opts.readDenyHomeLinks) : unplaced);
+    const late = carried || placesNothing ? undefined : readDenyPlacedLater(carryHomeViews(unplaced, homeViewsAt(env, [])), () => placeReadDenyAtHome(env, compileAt, readDenyHomes));
+    const readDeny = late?.matcher ??
+        (carried
+            ? carriedViews !== undefined
+                ? carryHomeViews(compileAt(readDenyHomes, opts.readDenyHomeLinks), carriedViews)
+                : carryHomeViews(unplaced, homeViewsAt(env, []))
+            : carryHomeViews(unplaced, homeViewsAt(env, readDenyHomes ?? [])));
     const afterPlacement = (tool) => late === undefined
         ? tool
         : {
@@ -61,7 +69,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
             },
         };
     const writeDenyCompiled = compileWriteDeny(readDenyRules);
-    const writeDeny = writeDenyCompiled.ruleRows.length > 0 ? writeDenyCompiled : undefined;
+    const writeDeny = writeDenyCompiled.ruleRows.length > 0 ? carryHomeViews(writeDenyCompiled, readDeny.homeViews) : undefined;
     const readFace = resolveContainmentFace({
         kind: "read",
         depsFace: opts.readFace,

package/dist/tools/fs/read-deny-home.d.ts

@@ -1,12 +1,18 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { type PathFamily } from "./safety.js";
 import { type ReadDenyMatcher } from "./read-deny.js";
-/** The environment's DECLARED home as an anchor list: `[homeDir]` when it declares an absolute one, else `[]` (no
- *  home — a home-anchored row then holds its run anywhere, see `compileReadDeny`). */
+/** The one bound every probe of an AUXILIARY home shares within one placement (see the module head): long enough for a
+ *  local directory's canonical spelling, its chain of identities and its rows' heads, short enough that a hung home
+ *  costs a placement seconds, not the gate's bound. */
+export declare const AUXILIARY_HOME_PROBE_MS = 2000;
+/** {@link declaredReadDenyHomesAnswered}'s anchor list. */
 export declare function declaredReadDenyHomes(env: Pick<ExecutionEnv, "homeDir">): string[];
-/** The declared home and, where the environment's canonical spelling of it differs (a home reached through a
- *  symlink), that spelling too: the faces judge canonical keys beside the spelled views, so a row placed only at
- *  the spelled home would never meet a canonical key. A home the environment cannot resolve keeps its spelling. */
+/** The declared home and the account home ({@link declaredReadDenyHomes}) and, where the environment's canonical
+ *  spelling of one differs (a home reached through a symlink), that spelling too: the faces judge canonical keys beside
+ *  the spelled views, so a row placed only at the spelled home would never meet a canonical key. A home the
+ *  environment cannot resolve keeps its spelling — the account home's probe waits at most {@link AUXILIARY_HOME_PROBE_MS}.
+ *  `[]` — the rows hold their run at every location — where the environment declares no home, where the account lookup
+ *  gave no answer, or where the declared home's own probe did not answer (ask again later). */
 export declare function readDenyHomesOf(env: Pick<ExecutionEnv, "homeDir" | "canonicalPath">, signal?: AbortSignal): Promise<string[]>;
 /**
  * Where the home-anchored rows of a table LEAD beyond the home's own spellings, keyed by the row's pattern — the
@@ -15,16 +21,20 @@ export declare function readDenyHomesOf(env: Pick<ExecutionEnv, "homeDir" | "can
  * (`canonicalizeTarget`: the longest existing prefix resolved, the rest rejoined); a location that differs from every
  * home's own spelling of the head is where one of the head's segments is a link, and the row is placed there too.
  *  · a head that resolves to its own spelling under a home adds nothing (the row is already placed there);
- *  · a head that cannot be resolved (an unanswered or refused probe, a probe that throws) adds nothing, and the answer
- *    is not WHOLE (`whole: false`): the row stays placed at the home's spellings until the mount places again;
+ *  · a head under a spelling that is no directory (a segment of it is a file, a symlink to a file, a device node or a
+ *    socket — the environment answers `not_directory` for the head) has nothing below it: an answer that adds nothing;
+ *  · any other head that cannot be resolved (an unanswered or refused probe — a directory the probe may not enter — a
+ *    probe that throws) adds nothing, and the answer is not WHOLE (`whole: false`): the row stays placed at the home's
+ *    spellings until the mount places again;
  *  · a row whose head is empty (`~/.sema.*`) has no location to resolve and adds nothing;
- *  · the heads are resolved together, so one placement waits at most one probe bound;
+ *  · the heads are resolved together, so one placement waits at most one probe bound — or, with `deadline` (an absolute
+ *    time), each head until then: a head still unresolved at the deadline is a head that did not answer;
  *  · read per placement — a link created afterwards is followed from the next placement on.
  */
 export declare function readDenyHomeLinksOf(env: ExecutionEnv, entries: readonly {
     readonly pattern: string;
     readonly caseSensitive?: boolean;
-}[], homes: readonly string[], signal?: AbortSignal): Promise<{
+}[], homes: readonly string[], signal?: AbortSignal, deadline?: number): Promise<{
     readonly linked: Map<string, string[]>;
     readonly whole: boolean;
 }>;
@@ -38,15 +48,81 @@ export declare function whereItLeads(env: ExecutionEnv, at: string, family?: Pat
  *  placed narrower than that base's own canonical spelling. The whole walk waits at most one bounded-await deadline.
  *  `undefined` when no prefix answers in time. */
 export declare function whereItsAnsweredPrefixLeads(env: ExecutionEnv, at: string, family?: PathFamily, signal?: AbortSignal): Promise<string | undefined>;
-/** One mount's read-deny judge with its home-anchored rows placed: at the home's spellings (`homes` when the mount
- *  carries them, else {@link readDenyHomesOf}, under the tree's bounded-await deadline — an environment that cannot
- *  answer rejects the placement instead of holding it open) and where their heads lead ({@link readDenyHomeLinksOf}).
- *  `whole` says whether the home and every head answered. A home the environment did not answer for places nothing:
- *  the rows are held anywhere (`compile([])`, the rule for a row that cannot be placed) rather than at a spelling that
- *  may miss the home's canonical one. `compile` is the mount's own compile over the two; the rows' patterns are read
- *  off its compile at the homes alone. */
+/** The environment surface a home view reads. */
+export type HomeViewEnv = Pick<ExecutionEnv, "homeDir" | "canonicalPath" | "fileIdentity">;
+/**
+ * The HOME VIEWS of one placement — the one reader every face that judges a deny row by location uses (the structured
+ * read and write tools' target judgment, the shell station's establishment, the search walker, the ripgrep leg's output
+ * check and its scope choice). A judge carries the source its placement made ({@link HomeViewsCarrier}); a judgment
+ * takes one {@link HomeViews} from it ({@link homeViewsOf}).
+ *
+ * The view of a path is the path itself when it IS a directory on a home's chain (each home's canonical spelling and
+ * each of its ancestors, matched by {@link ExecutionEnv.fileIdentity}) — that directory's canonical spelling — and
+ * otherwise its parent's view with its own name rejoined. One identity keeps ONE spelling, and a row is placed at a
+ * HOME's spelling: a directory that IS a home (its own identity answered) keeps the home's own spelling over an
+ * ancestor's (a declared home below a mount of the account home meets the account home's identity at an ancestor); a
+ * home whose own identity did not answer has no directory to claim. Homes in order: the declared home, then the
+ * auxiliary homes. The homes are the placement's:
+ *  · the DECLARED home (`env.homeDir`, no lookup) is always among them — whatever the account lookup answered — and its
+ *    chain is read by the first judgment that asks, kept once every level answered, and asked again by the next
+ *    judgment otherwise (a home that does not exist yet is read once it does);
+ *  · each AUXILIARY home's chain is the one its placement read, once ({@link AUXILIARY_HOME_PROBE_MS}); a chain that did
+ *    not answer stays unanswered for that placement.
+ */
+export interface HomeViewSource {
+    /** The home views of one judgment (a tool call, a command's establishment, one search): a view per directory is read
+     *  once and shared by every path below it. */
+    views(signal?: AbortSignal): HomeViews;
+}
+/** A judgment's views. `of` answers the view only where it differs from the path as spelled; `undefined` otherwise, and
+ *  wherever it cannot be read: no `fileIdentity` seat, no home, a level of the path whose identity fails (the path is
+ *  judged as spelled, never wider). A level that does not exist (a write's missing tail) takes its parent's view.
+ *  `leaf: "file"` skips the path's own identity (a file is never a directory on the chain). */
+export interface HomeViews {
+    of(path: string, opts?: {
+        readonly leaf?: "file";
+    }): Promise<string | undefined>;
+}
+/** A judge that carries the home views of the placement its rows were compiled at. */
+export interface HomeViewsCarrier {
+    readonly homeViews?: HomeViewSource;
+}
+/** A read deny judge with its placement's home views. */
+export type PlacedReadDenyMatcher = ReadDenyMatcher & {
+    readonly homeViews: HomeViewSource;
+};
+/** The views of the placement that returned `homes` — the very list object, as the engine hands it on (the Runner's
+ *  tool band). `undefined` for any other list: a copy, or a host's own. A mount that was handed the engine's placement
+ *  and cannot find its views has lost it: an engine defect, which the mount names ({@link sayPlacementLost}) and answers
+ *  by holding its home-anchored rows at every location — never by reading the homes a second time. */
+export declare function placementViewsOf(homes: readonly string[]): HomeViewSource | undefined;
+/** The line a mount says when the engine handed it a home list that is not its placement's (an engine defect, said every
+ *  time: no latch). */
+export declare function sayPlacementLost(): void;
+/** The home views over a home list fixed now — a mount that places nothing itself (a toolkit handed its placement, or
+ *  one whose table has no home-anchored row) and the public shell judgment: the declared home, and every entry of
+ *  `homes` that is not the declared home as an auxiliary home, read once, at once. */
+export declare function homeViewsAt(env: HomeViewEnv, homes: readonly string[]): HomeViewSource;
+/** The home views of one judgment, off the judge it judges with: the views of the judge's placement. A judge that
+ *  carries none (one built outside a mount) reads the declared home alone. */
+export declare function homeViewsOf(env: HomeViewEnv, judge: HomeViewsCarrier | undefined, signal?: AbortSignal): HomeViews;
+/** A judge with the home views `source` gives it. */
+export declare function carryHomeViews<T extends object>(judge: T, source: HomeViewSource): T & {
+    readonly homeViews: HomeViewSource;
+};
+/** One mount's read-deny judge with its home-anchored rows placed, and the home views of that placement:
+ *  · the HOME SET — `homes` when the mount carries a list (the account is not asked and no home is added), else the
+ *    declared home and the account lookup's answer ({@link declaredReadDenyHomes}); every home of the set is anchored at
+ *    its spelling and, where the environment answered one, its canonical spelling — one rule for both forms;
+ *  · the DECLARED home's canonical spelling under the tree's gate bound, and its rows' heads ({@link readDenyHomeLinksOf}):
+ *    a declared home, or a head under it, that did not answer leaves the placement not WHOLE — and an account lookup
+ *    with no answer, or a declared home that did not answer, places nothing: the rows are held anywhere (`compile([])`)
+ *    rather than at a spelling that may miss the home's canonical one;
+ *  · each AUXILIARY home (see the module head) read once under {@link AUXILIARY_HOME_PROBE_MS} — its spellings, its
+ *    chain, its rows' heads — at the same time; whatever of it did not answer costs that home alone and never `whole`.
+ *  `compile` is the mount's own compile; the rows' patterns are read off its compile at no home. */
 export declare function placeReadDenyAtHome(env: ExecutionEnv, compile: (homes: readonly string[], linked?: ReadonlyMap<string, readonly string[]>) => ReadDenyMatcher, homes?: readonly string[], signal?: AbortSignal): Promise<{
-    readonly matcher: ReadDenyMatcher;
+    readonly matcher: PlacedReadDenyMatcher;
     readonly homes: readonly string[];
     readonly linked: ReadonlyMap<string, readonly string[]>;
     readonly whole: boolean;
@@ -58,36 +134,13 @@ export declare function placeReadDenyAtHome(env: ExecutionEnv, compile: (homes:
  * (either way) and, while no placement has come back WHOLE (a failed one, or one with a head that did not answer),
  * places again first — an unanswered lookup is never kept as the answer. A failed placement leaves the table it
  * replaced (the rows held anywhere, or an earlier placement), never unplaced-and-narrow. The mount holds its read faces
- * until `ready()`.
+ * until `ready()`. The judge's home views are the latest settled placement's: a judgment that asks for one waits for the
+ * placement in flight (it never starts one).
  */
-export declare function readDenyPlacedLater(unplaced: ReadDenyMatcher, place: () => Promise<{
-    readonly matcher: ReadDenyMatcher;
+export declare function readDenyPlacedLater(unplaced: PlacedReadDenyMatcher, place: () => Promise<{
+    readonly matcher: PlacedReadDenyMatcher;
     readonly whole: boolean;
 }>): {
-    readonly matcher: ReadDenyMatcher;
+    readonly matcher: PlacedReadDenyMatcher;
     readonly ready: () => Promise<void>;
 };
-/** The environment surface a home view reads. */
-export type HomeViewEnv = Pick<ExecutionEnv, "homeDir" | "canonicalPath" | "fileIdentity">;
-/**
- * A path's HOME VIEW — the one reader every face that judges a deny row by location uses (the structured read and
- * write tools' target judgment, the shell station's establishment, the search walker, the ripgrep leg's output check
- * and its scope choice). The view of a path is the path itself when it IS a directory on the home's chain (the
- * canonical home and each of its ancestors, matched by {@link ExecutionEnv.fileIdentity}) — that directory's
- * canonical spelling — and otherwise its parent's view with its own name rejoined. `of` answers the view only where
- * it differs from the path as spelled; `undefined` otherwise, and wherever it cannot be read:
- *  · the environment declares no home, no `fileIdentity`, or its home does not resolve ⇒ no view (the spelling form);
- *    a home, or a level of its chain, that could not be read is asked again by the next judgment — an unanswered
- *    lookup is never kept as the answer;
- *  · a level that does not exist (a write's missing tail) has no identity of its own and takes its parent's view;
- *  · any other failure at a level stops the view there: the path is judged as spelled, never wider.
- * `leaf: "file"` skips the path's own identity (a file is never a directory on the chain).
- */
-export interface HomeViews {
-    of(path: string, opts?: {
-        readonly leaf?: "file";
-    }): Promise<string | undefined>;
-}
-/** The home views of one judgment (a tool call, a command's establishment, one search): a view per directory is read
- *  once and shared by every path below it. */
-export declare function homeViewsOf(env: HomeViewEnv, signal?: AbortSignal): HomeViews;