@crewhaus/runtime-core 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,676 @@
1
+ /**
2
+ * Where a path-kind operative value really lands, for the permission gate.
3
+ *
4
+ * The matcher (`@crewhaus/tool-permission-matcher`) and the subject builder
5
+ * (`preparePermissionSubject` in `@crewhaus/tool-executor`) are pure — the
6
+ * worker runtime runs them on a Cloudflare Worker, where there is no
7
+ * filesystem to ask. Following symlinks needs one, so it lives here, in the
8
+ * Node runtime that owns the workspace, and is handed to the subject builder
9
+ * as its `canonicalizePath`.
10
+ *
11
+ * A path is resolved against the workspace root, `..` collapsed, and its
12
+ * directories followed through symlinks (the deepest one that exists is
13
+ * realpath'd) — so it names the place the tool will actually touch — then
14
+ * written relative to the workspace. When the last component exists, it is
15
+ * written the way the directory stores it: on a filesystem that ignores case
16
+ * or Unicode normal form (macOS, Windows), `.ENV` opens `.env`, and a rule
17
+ * about `.env` must see that. When the last component is itself a symlink,
18
+ * its target is a second value. A path that ends up outside the workspace,
19
+ * whose destination cannot be worked out, or that is longer than any path can
20
+ * be ({@link MAX_PATH_CHARS}), is flagged; the matcher never lets it satisfy
21
+ * an allow rule and always lets it satisfy a deny or ask.
22
+ * A path on a filesystem that ignores case (or where that cannot be told) is
23
+ * marked `caseInsensitive`, so a deny or ask compares it ignoring case — the
24
+ * name a tool is about to CREATE has no stored spelling to read. A path that
25
+ * names an existing file (or a link to one) is marked `notDirectory`: a tool
26
+ * that walks what a directory holds finds nothing beneath it.
27
+ *
28
+ * The workspace root can itself be reached another way — the shell's `$PWD`
29
+ * through a symlinked directory, or a top-level symlink such as macOS's
30
+ * `/tmp` → `/private/tmp` — and a rule may name it that way:
31
+ * `alwaysDeny Write(/tmp/ws/.crewhaus/**)` while the runtime's cwd reads
32
+ * `/private/tmp/ws`. The same location under each of those spellings of the
33
+ * root is a further spelling, so such a deny is not dodged by a relative
34
+ * path. (A spelling, not a canonical value: it widens what a deny or ask
35
+ * catches, never what an allow grants.)
36
+ */
37
+ import { lstatSync, readdirSync, readlinkSync, realpathSync, statSync } from "node:fs";
38
+ import * as path from "node:path";
39
+ import { physicalPath } from "@crewhaus/tool-safety/fs";
40
+ function toPosix(p) {
41
+ return path.sep === "\\" ? p.split(path.sep).join("/") : p;
42
+ }
43
+ /**
44
+ * The longest path this resolves, in UTF-16 code units; a longer one is
45
+ * refused before it is walked. Nothing that long can be opened or created:
46
+ * PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
47
+ * 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
48
+ * UTF-16 one. The limit is twice that because the part of a path that exists
49
+ * is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
50
+ * own: no spelling of the place reaches it, not even one through a symlink
51
+ * that shortens the part that exists.
52
+ */
53
+ export const MAX_PATH_CHARS = 2 * (process.platform === "darwin" ? 1_024 : process.platform === "win32" ? 32_767 : 4_096);
54
+ /** Top-level symlinks and the directory each resolves to, read once per process. */
55
+ let topLevelLinksRead;
56
+ function topLevelLinks() {
57
+ if (topLevelLinksRead !== undefined)
58
+ return topLevelLinksRead;
59
+ const out = [];
60
+ const top = path.parse(path.resolve("/")).root;
61
+ try {
62
+ for (const entry of readdirSync(top, { withFileTypes: true })) {
63
+ if (!entry.isSymbolicLink())
64
+ continue;
65
+ const link = path.join(top, entry.name);
66
+ try {
67
+ out.push([link, realpathSync(link)]);
68
+ }
69
+ catch {
70
+ // A dangling top-level link names no directory a workspace is in.
71
+ }
72
+ }
73
+ }
74
+ catch {
75
+ // An unreadable root has no aliases to offer.
76
+ }
77
+ topLevelLinksRead = out;
78
+ return out;
79
+ }
80
+ /**
81
+ * The other absolute spellings of the workspace root `rootReal` (already
82
+ * realpath'd): the root as given, `$PWD` when it resolves to the root, and
83
+ * the root under each top-level symlink whose target contains it.
84
+ */
85
+ function rootAliases(rootAbs, rootReal, sources) {
86
+ const out = new Set();
87
+ if (rootAbs !== rootReal)
88
+ out.add(rootAbs);
89
+ const pwd = "pwd" in sources ? sources.pwd : process.env["PWD"];
90
+ if (pwd !== undefined && path.isAbsolute(pwd)) {
91
+ try {
92
+ if (realpathSync(pwd) === rootReal)
93
+ out.add(path.resolve(pwd));
94
+ }
95
+ catch {
96
+ // A $PWD that no longer resolves names nothing.
97
+ }
98
+ }
99
+ for (const [link, target] of sources.topLevelLinks ?? topLevelLinks()) {
100
+ if (rootReal === target)
101
+ out.add(link);
102
+ else if (rootReal.startsWith(target.endsWith(path.sep) ? target : `${target}${path.sep}`)) {
103
+ out.add(`${link}${rootReal.slice(target.length)}`);
104
+ }
105
+ }
106
+ out.delete(rootReal);
107
+ return [...out];
108
+ }
109
+ /** A relative path that leaves its base: `..`, `../x`, or another drive. */
110
+ function climbsOut(relative) {
111
+ return relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
112
+ }
113
+ /** True when the NAME exists, whether or not a symlink there leads anywhere. */
114
+ function nameExists(p) {
115
+ try {
116
+ lstatSync(p);
117
+ return true;
118
+ }
119
+ catch {
120
+ return false;
121
+ }
122
+ }
123
+ /**
124
+ * True when `p` names an existing entry that is not a directory, following a
125
+ * symlink: nothing lies beneath it. A dangling link, or a name that is not
126
+ * there, is not known to be a file, so a tool that walks directories may
127
+ * still find something beneath it by the time it runs.
128
+ */
129
+ function isNonDirectory(p) {
130
+ try {
131
+ return !statSync(p).isDirectory();
132
+ }
133
+ catch {
134
+ return false;
135
+ }
136
+ }
137
+ function isSymlink(p) {
138
+ try {
139
+ return lstatSync(p).isSymbolicLink();
140
+ }
141
+ catch {
142
+ return false;
143
+ }
144
+ }
145
+ /**
146
+ * Where `target` would land with every symlink on the way followed — the
147
+ * deepest ancestor that exists is resolved, a dangling link is followed a hop
148
+ * by hand (a missing target is still a door), and the parts that do not exist
149
+ * yet are appended. Mirrors `resolveLocation` in `@crewhaus/tool-fs`, which is
150
+ * what the file tools check containment against. Throws when the chain
151
+ * cannot be resolved; the caller treats that as "cannot tell where it lands".
152
+ */
153
+ function resolveLocation(target, depth = 0) {
154
+ if (depth > 40)
155
+ throw new Error(`symlink chain at "${target}" is too long to resolve`);
156
+ const { probe, tail } = deepestName(target);
157
+ let real;
158
+ try {
159
+ real = realpathSync(probe);
160
+ }
161
+ catch (err) {
162
+ if (err.code !== "ENOENT")
163
+ throw err;
164
+ const link = readlinkSync(probe);
165
+ real = resolveLocation(path.resolve(realpathSync(path.dirname(probe)), link), depth + 1);
166
+ }
167
+ // One string, not one argument per name: Bun's `path.join` keeps only
168
+ // (argument count mod 65,536) of its arguments, so 65,536 missing names
169
+ // would give back `real` alone — a path the tool, whose own walk has one
170
+ // name more, does not act on.
171
+ return tail.length > 0 ? path.join(real, tail) : real;
172
+ }
173
+ /**
174
+ * `target`, an absolute path, split where its deepest prefix that exists as
175
+ * a NAME ends: that prefix, and the names below it, which do not exist, as
176
+ * one string ("" when `target` itself exists). This is `path.dirname` and
177
+ * `path.basename` worked by index on `target` itself: handing them each
178
+ * shorter prefix in turn copied the rest of the path once per missing name,
179
+ * the square of a count the caller picks.
180
+ */
181
+ function deepestName(target) {
182
+ const top = path.parse(target).root.length;
183
+ const isSep = (i) => target[i] === "/" || target[i] === path.sep;
184
+ let probe = target;
185
+ let start = target.length;
186
+ let stop = -1;
187
+ while (!nameExists(probe)) {
188
+ // `path.basename(probe)` is `target.slice(start, end)`, and
189
+ // `path.dirname(probe)` is `target.slice(0, up)`.
190
+ let end = probe.length;
191
+ while (end > top && isSep(end - 1))
192
+ end--;
193
+ if (stop < 0)
194
+ stop = end;
195
+ start = end;
196
+ while (start > top && !isSep(start - 1))
197
+ start--;
198
+ const up = start > top ? start - 1 : top;
199
+ if (up === probe.length)
200
+ break; // reached the filesystem root
201
+ probe = target.slice(0, up);
202
+ }
203
+ return { probe, tail: stop < 0 ? "" : target.slice(start, stop) };
204
+ }
205
+ /** Two paths that are the same directory entry: same device, same inode. */
206
+ function sameEntry(a, b) {
207
+ try {
208
+ const x = lstatSync(a);
209
+ const y = lstatSync(b);
210
+ return x.dev === y.dev && x.ino === y.ino;
211
+ }
212
+ catch {
213
+ return false;
214
+ }
215
+ }
216
+ /** Case and Unicode normal form folded away — how a folding filesystem compares names. */
217
+ function foldName(name) {
218
+ return name.normalize("NFC").toLowerCase();
219
+ }
220
+ /**
221
+ * How the directory `dir` stores the existing entry the caller named `name`:
222
+ * `[name]` when that is an entry as spelled, otherwise the entry (or, for a
223
+ * name with several hard links there, the entries) the filesystem resolved it
224
+ * to — `.env` for `.ENV` on a case-insensitive volume. `undefined` when the
225
+ * directory cannot be listed or no entry is that file: the caller cannot tell
226
+ * which name a rule should see.
227
+ */
228
+ function storedNames(dir, name) {
229
+ let entries;
230
+ try {
231
+ entries = readdirSync(dir);
232
+ }
233
+ catch {
234
+ return undefined;
235
+ }
236
+ if (entries.includes(name))
237
+ return [name];
238
+ const at = path.join(dir, name);
239
+ // A folding filesystem resolves `name` to an entry that folds the same way;
240
+ // look at those first, and at every entry only if its folding is not ours.
241
+ const folded = foldName(name);
242
+ const likely = entries.filter((e) => foldName(e) === folded && sameEntry(path.join(dir, e), at));
243
+ if (likely.length > 0)
244
+ return likely;
245
+ const any = entries.filter((e) => sameEntry(path.join(dir, e), at));
246
+ return any.length > 0 ? any : undefined;
247
+ }
248
+ /**
249
+ * Does the filesystem at `dir` treat names that differ only in letter case as
250
+ * the same? Asked of the nearest existing directory whose own name has a
251
+ * letter: its name with the case swapped either finds the same directory
252
+ * (yes) or nothing (no). `undefined` when no such directory answers.
253
+ */
254
+ function ignoresCase(dir) {
255
+ // `path.basename` and `path.dirname` worked by index on `dir`, as in
256
+ // `deepestName`: `dir` can end in as many missing names as a caller wrote.
257
+ const top = path.parse(dir).root.length;
258
+ const isSep = (i) => dir[i] === "/" || dir[i] === path.sep;
259
+ let end = dir.length;
260
+ for (;;) {
261
+ let stop = end;
262
+ while (stop > top && isSep(stop - 1))
263
+ stop--;
264
+ let start = stop;
265
+ while (start > top && !isSep(start - 1))
266
+ start--;
267
+ const probe = dir.slice(0, end);
268
+ const parent = dir.slice(0, start > top ? start - 1 : top);
269
+ const base = dir.slice(start, stop);
270
+ const swapped = [...base]
271
+ .map((c) => (c === c.toLowerCase() ? c.toUpperCase() : c.toLowerCase()))
272
+ .join("");
273
+ if (swapped !== base && nameExists(probe)) {
274
+ const other = path.join(parent, swapped);
275
+ if (!nameExists(other))
276
+ return false;
277
+ return sameEntry(probe, other);
278
+ }
279
+ if (parent.length === end)
280
+ return undefined;
281
+ end = parent.length;
282
+ }
283
+ }
284
+ /**
285
+ * The value(s) `raw` names inside the workspace at `root`. Parent
286
+ * directories are followed through symlinks — `build/link/app.ts` with
287
+ * `build/link → ../src` IS `src/app.ts` for every tool. The last component is
288
+ * not followed, because a tool that replaces or deletes it acts on the link
289
+ * itself; but it is written the way its directory stores it when it exists
290
+ * (`.ENV` is `.env` on macOS), and when it is a symlink, a tool that opens it
291
+ * acts on the target instead, so the target is a second value. An allow then
292
+ * has to cover both, and a deny fires on either. The name as written stays a
293
+ * spelling a deny also fires on.
294
+ */
295
+ export function canonicalWorkspacePath(raw, root, rootSpellings = {}) {
296
+ return readWorkspacePath(raw, root, rootSpellings).values;
297
+ }
298
+ /**
299
+ * {@link canonicalWorkspacePath}, with the place each value stands for: the
300
+ * absolute location, with every symlink followed, that a value inside the
301
+ * workspace names in `canonical` — and that a value flagged outside does
302
+ * not, since a rule needs only the flag. An approval is bound to these
303
+ * places, and an outside place is a place an operator approved as much as an
304
+ * inside one.
305
+ *
306
+ * Where `realpath` cannot say where a path lands, the rule still reads only
307
+ * the outside flag, but the place is walked the way the file tools walk it
308
+ * (`physicalPath` in `@crewhaus/tool-safety/fs`, one `lstat`/`readlink` per
309
+ * name): a directory that can be searched but not read (mode 0300) stops
310
+ * `realpath` and stops listing it, and stops no tool. Only where that walk
311
+ * fails too (a loop of links, a directory that cannot be searched), which is
312
+ * where the tool cannot open the path either, is the place
313
+ * {@link UNRESOLVED_PLACE} followed by the path as written.
314
+ */
315
+ function readWorkspacePath(raw, root, rootSpellings) {
316
+ const rootAbs = path.resolve(root);
317
+ let rootReal;
318
+ try {
319
+ rootReal = realpathSync(rootAbs);
320
+ }
321
+ catch {
322
+ rootReal = rootAbs;
323
+ }
324
+ const aliases = rootAliases(rootAbs, rootReal, rootSpellings);
325
+ // Lexical: `..` collapsed, symlinks untouched.
326
+ const lexicalAbs = path.resolve(rootAbs, raw);
327
+ const lexicalRel = path.relative(rootAbs, lexicalAbs);
328
+ const spellings = [raw, toPosix(lexicalRel === "" ? "." : lexicalRel), toPosix(lexicalAbs)];
329
+ const outside = {
330
+ kind: "path",
331
+ canonical: [],
332
+ spellings,
333
+ outsideWorkspace: true,
334
+ };
335
+ const asWritten = toPosix(path.resolve(rootReal, lexicalRel));
336
+ const unresolved = `${UNRESOLVED_PLACE}${toPosix(lexicalAbs)}`;
337
+ const known = { lexical: rootAbs, physical: rootReal };
338
+ /** Where `abs` lands, walked as the tools walk it; `undefined` where they could not open it. */
339
+ const walked = (abs) => {
340
+ try {
341
+ return toPosix(physicalPath(abs, { known }));
342
+ }
343
+ catch {
344
+ return undefined;
345
+ }
346
+ };
347
+ /**
348
+ * The entry `name` in the directory that really holds it, and where it
349
+ * leads when it is a symlink: the places the normal reading below gives a
350
+ * rule, for a directory it could not read.
351
+ */
352
+ const entryPlaces = (dir, name) => {
353
+ const at = path.join(dir, name);
354
+ if (!isSymlink(at))
355
+ return [toPosix(at)];
356
+ const target = walked(at);
357
+ if (target === undefined)
358
+ return [toPosix(at), unresolved];
359
+ return target === toPosix(at) ? [toPosix(at)] : [toPosix(at), target];
360
+ };
361
+ /** The places of `lexicalAbs` where its directory could not be read. */
362
+ const placesByWalk = () => {
363
+ const dir = walked(path.dirname(lexicalAbs));
364
+ return dir === undefined ? [unresolved] : entryPlaces(dir, path.basename(lexicalAbs));
365
+ };
366
+ const read = (values, places) => {
367
+ let known = typeof places === "function" ? undefined : places;
368
+ return {
369
+ values,
370
+ places: () => {
371
+ known ??= places();
372
+ return known;
373
+ },
374
+ asWritten,
375
+ };
376
+ };
377
+ let caseInsensitive = true;
378
+ const located = (real) => {
379
+ const rel = path.relative(rootReal, real);
380
+ if (climbsOut(rel))
381
+ return outside;
382
+ const relPosix = rel === "" ? "." : toPosix(rel);
383
+ const underAliases = aliases.map((a) => toPosix(rel === "" ? a : path.join(a, rel)));
384
+ return {
385
+ kind: "path",
386
+ canonical: relPosix === "." ? [".", toPosix(real)] : [relPosix, `./${relPosix}`, toPosix(real)],
387
+ spellings: underAliases.length === 0 ? spellings : [...spellings, ...underAliases],
388
+ ...(caseInsensitive ? { caseInsensitive: true } : {}),
389
+ // A tool that walks a directory (`beneath`) acts on nothing beneath a
390
+ // file, so a deny naming something under this name cannot concern it.
391
+ ...(isNonDirectory(real) ? { notDirectory: true } : {}),
392
+ };
393
+ };
394
+ if (climbsOut(lexicalRel)) {
395
+ // A rule needs only the flag. The place is walked for only when an
396
+ // approval asks, so a grant made for one place outside is not spent on
397
+ // another — and walked in one pass over the path: `resolveLocation`
398
+ // hands the rest of the path to dirname and basename once per missing
399
+ // name, the square of a length the model chooses.
400
+ return read([outside], () => [walked(lexicalAbs) ?? unresolved]);
401
+ }
402
+ // Longer than any path can be: no tool acts on it, and it is not walked.
403
+ if (lexicalAbs.length > MAX_PATH_CHARS)
404
+ return read([outside], [unresolved]);
405
+ if (lexicalAbs === rootAbs) {
406
+ caseInsensitive = ignoresCase(rootReal) !== false;
407
+ return read([located(rootReal)], [toPosix(rootReal)]);
408
+ }
409
+ let parent;
410
+ try {
411
+ parent = resolveLocation(path.dirname(lexicalAbs));
412
+ }
413
+ catch {
414
+ // Where it lands cannot be worked out: an allow must not guess.
415
+ return read([outside], placesByWalk());
416
+ }
417
+ // Unknown counts as "ignores case": that only widens what a deny or an ask
418
+ // catches, never what an allow grants.
419
+ caseInsensitive = ignoresCase(parent) !== false;
420
+ const leaf = path.basename(lexicalAbs);
421
+ let names = [leaf];
422
+ if (nameExists(path.join(parent, leaf))) {
423
+ // It exists, so the tool will open the entry the filesystem resolves the
424
+ // name to — which, on a filesystem that folds case or Unicode form, may
425
+ // be stored under another spelling. A rule sees that spelling.
426
+ const stored = storedNames(parent, leaf);
427
+ if (stored === undefined)
428
+ return read([outside], placesByWalk());
429
+ names = stored;
430
+ }
431
+ const values = [];
432
+ const places = [];
433
+ for (const name of names) {
434
+ const at = path.join(parent, name);
435
+ values.push(located(at));
436
+ places.push(toPosix(at));
437
+ if (isSymlink(at)) {
438
+ let target;
439
+ try {
440
+ target = resolveLocation(at);
441
+ }
442
+ catch {
443
+ values.push(outside);
444
+ places.push(walked(at) ?? unresolved);
445
+ continue;
446
+ }
447
+ if (target !== at) {
448
+ values.push(located(target));
449
+ places.push(toPosix(target));
450
+ }
451
+ }
452
+ }
453
+ return read(values, places);
454
+ }
455
+ /**
456
+ * How a place reads when even the tools' own walk cannot follow the path: a
457
+ * loop of links, or a directory that cannot be searched. A tool cannot open
458
+ * such a path either.
459
+ */
460
+ export const UNRESOLVED_PLACE = "unresolved:";
461
+ function isSeparator(code) {
462
+ return code === 0x2f || (path.sep === "\\" && code === 0x5c);
463
+ }
464
+ /**
465
+ * `rel` walked from the physical directory `dir` the way the kernel walks it:
466
+ * `physicalPath` from a start already known to be physical, so each `..` is
467
+ * applied after the link before it, never folded as text first.
468
+ */
469
+ function walkFrom(dir, rel) {
470
+ if (rel === "")
471
+ return dir;
472
+ const joined = dir.endsWith(path.sep) ? `${dir}${rel}` : `${dir}${path.sep}${rel}`;
473
+ return physicalPath(joined, { known: { lexical: dir, physical: dir } });
474
+ }
475
+ /**
476
+ * Where a command word that names a file lands (`ProgramPathReader` in
477
+ * `@crewhaus/tool-executor`): from the directory the command runs in — the
478
+ * tools join `runsIn` to the root as text and the kernel then follows it —
479
+ * each name followed the way the kernel follows it, a `..` after a link
480
+ * climbing out of the link's target. `link/../run.sh` with `link →
481
+ * secrets/deep` is `secrets/run.sh`, which `path.resolve` would fold to
482
+ * `run.sh` before any link was seen. The last name is kept as written; when
483
+ * it is a symlink, where it leads is the program the kernel runs, and a
484
+ * second place.
485
+ */
486
+ function readProgramPlace(word, runsIn, rootReal, prefix, walked) {
487
+ const dirLexical = path.resolve(rootReal, runsIn ?? ".");
488
+ const lexical = path.resolve(dirLexical, prefix, word);
489
+ const asWritten = toPosix(lexical);
490
+ const unresolved = {
491
+ reading: undefined,
492
+ at: [`${UNRESOLVED_PLACE}${asWritten}`],
493
+ asWritten,
494
+ };
495
+ // Longer than any path can be: the kernel refuses to run it.
496
+ if (word.length > MAX_PATH_CHARS ||
497
+ dirLexical.length > MAX_PATH_CHARS ||
498
+ prefix.length > MAX_PATH_CHARS) {
499
+ return unresolved;
500
+ }
501
+ const inWorkspace = (p) => {
502
+ const rel = path.relative(rootReal, p);
503
+ return climbsOut(rel) ? undefined : rel === "" ? "." : toPosix(rel);
504
+ };
505
+ // The last name, and the directory part before it, by index.
506
+ let end = word.length;
507
+ while (end > 0 && isSeparator(word.charCodeAt(end - 1)))
508
+ end--;
509
+ let cut = end;
510
+ while (cut > 0 && !isSeparator(word.charCodeAt(cut - 1)))
511
+ cut--;
512
+ const leaf = word.slice(cut, end);
513
+ const head = word.slice(0, cut);
514
+ const known = { lexical: rootReal, physical: rootReal };
515
+ let at;
516
+ let target;
517
+ const absolute = path.isAbsolute(word);
518
+ // The directory a relative word is walked from: the one the command runs
519
+ // in, then where a wrapper moved it. Walked once per call for every word
520
+ // read there, so a deep directory and many words cost their sum.
521
+ let start;
522
+ if (absolute)
523
+ start = path.parse(word).root;
524
+ else {
525
+ const key = `${dirLexical}\u0000${prefix}`;
526
+ let dir = walked.get(key);
527
+ if (dir === undefined) {
528
+ try {
529
+ const base = physicalPath(dirLexical, { known });
530
+ dir =
531
+ prefix === ""
532
+ ? base
533
+ : path.isAbsolute(prefix)
534
+ ? physicalPath(prefix, { known })
535
+ : walkFrom(base, prefix);
536
+ }
537
+ catch {
538
+ dir = null;
539
+ }
540
+ walked.set(key, dir);
541
+ }
542
+ if (dir === null)
543
+ return unresolved;
544
+ start = dir;
545
+ }
546
+ try {
547
+ const from = (rel) => absolute ? physicalPath(`${start}${rel}`, { known }) : walkFrom(start, rel);
548
+ const relHead = absolute ? head.slice(start.length) : head;
549
+ if (leaf === "" || leaf === "." || leaf === "..") {
550
+ at = from(absolute ? word.slice(start.length) : word);
551
+ }
552
+ else {
553
+ const parent = from(relHead);
554
+ at = path.join(parent, leaf);
555
+ if (isSymlink(at)) {
556
+ const led = walkFrom(parent, leaf);
557
+ if (led !== at)
558
+ target = led;
559
+ }
560
+ }
561
+ }
562
+ catch {
563
+ return unresolved;
564
+ }
565
+ const atInWorkspace = inWorkspace(at);
566
+ const targetInWorkspace = target !== undefined ? inWorkspace(target) : undefined;
567
+ const reading = {
568
+ at: toPosix(at),
569
+ ...(atInWorkspace !== undefined ? { inWorkspace: atInWorkspace } : {}),
570
+ asWritten,
571
+ writtenInWorkspace: inWorkspace(lexical) !== undefined,
572
+ ...(target !== undefined
573
+ ? {
574
+ target: {
575
+ at: toPosix(target),
576
+ ...(targetInWorkspace !== undefined ? { inWorkspace: targetInWorkspace } : {}),
577
+ },
578
+ }
579
+ : {}),
580
+ };
581
+ return {
582
+ reading,
583
+ at: target !== undefined ? [toPosix(at), toPosix(target)] : [toPosix(at)],
584
+ asWritten,
585
+ };
586
+ }
587
+ /** `text` without its trailing separators, in one pass from the end. */
588
+ function withoutTrailingSeparators(text) {
589
+ let end = text.length;
590
+ while (end > 0 && isSeparator(text.charCodeAt(end - 1)))
591
+ end--;
592
+ return text.slice(0, end);
593
+ }
594
+ /**
595
+ * The gate's canonicaliser, keeping a record of every path it read and where
596
+ * each one lands — absolute, every symlink followed, one place per value it
597
+ * gave a rule (the entry itself and, when that is a symlink, its target),
598
+ * inside or outside the workspace alike. That record is what a headless
599
+ * approval is bound to (`landsWhereApproved` in this package). Paths a call names through a directory field (a
600
+ * command's `cwd`, a PATH entry it sets) are read through it too, and so is
601
+ * each command word that names a file — the program run by its path, the
602
+ * script an interpreter is handed — through `readProgramPath`, so the record
603
+ * is everything on the filesystem the gate's decision rested on.
604
+ */
605
+ export function placeRecordingCanonicalizer(root = process.cwd()) {
606
+ const seen = new Map();
607
+ const programs = new Map();
608
+ // The root as the kernel finds it, and each directory a word was read
609
+ // from, walked once (see readProgramPlace).
610
+ let rootReal;
611
+ const realRoot = () => {
612
+ if (rootReal === undefined) {
613
+ const rootAbs = path.resolve(root);
614
+ try {
615
+ rootReal = realpathSync(rootAbs);
616
+ }
617
+ catch {
618
+ rootReal = rootAbs;
619
+ }
620
+ }
621
+ return rootReal;
622
+ };
623
+ const walked = new Map();
624
+ const byKey = (entries) => [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
625
+ return {
626
+ canonicalizePath: (raw) => {
627
+ const reading = readWorkspacePath(raw, root, {});
628
+ seen.set(raw, reading);
629
+ return reading.values;
630
+ },
631
+ readProgramPath: (word, runsIn, opts) => {
632
+ const prefix = opts?.prefix ?? "";
633
+ const place = readProgramPlace(word, runsIn, realRoot(), prefix, walked);
634
+ // A bare word an interpreter is handed may be a subcommand or a module
635
+ // (`bun run build`, `python -m pytest`): it is a place only where it
636
+ // names an entry, or a card would list files that are not there.
637
+ const separated = word.includes("/") || (path.sep === "\\" && word.includes("\\"));
638
+ if (!separated && place.reading !== undefined && !nameExists(place.reading.at)) {
639
+ return place.reading;
640
+ }
641
+ // An argument (or a candidate on a PATH the call sets) is a place only
642
+ // where it lands elsewhere than it reads, or is a link: anywhere else
643
+ // its text says where it lands, and it would only crowd the card. A
644
+ // grant is still bound to it, since a link moving in or out of its way
645
+ // adds or drops it. One that cannot be walked (text longer than any
646
+ // path, a loop of links) is no file the call names.
647
+ const onItsFace = place.at.length === 1 && place.at[0] === place.asWritten;
648
+ if (opts?.argument === true && (onItsFace || place.reading === undefined)) {
649
+ return place.reading;
650
+ }
651
+ const dir = [runsIn, prefix]
652
+ .map((d) => (d !== undefined ? withoutTrailingSeparators(d) : ""))
653
+ .filter((d) => d !== "" && d !== ".")
654
+ .join("/");
655
+ const key = dir === "" || path.isAbsolute(word) ? word : `${dir}/${word}`;
656
+ programs.set(key, place);
657
+ return place.reading;
658
+ },
659
+ places: () => [
660
+ ...byKey(seen.entries()).map(([p, r]) => ({ path: p, at: [...r.places()] })),
661
+ ...byKey(programs.entries()).map(([p, r]) => ({ path: p, at: [...r.at] })),
662
+ ],
663
+ allAsWritten: () => [...seen.values()].every((r) => {
664
+ const at = r.places();
665
+ return at.length === 1 && at[0] === r.asWritten;
666
+ }) && [...programs.values()].every((r) => r.at.length === 1 && r.at[0] === r.asWritten),
667
+ };
668
+ }
669
+ /**
670
+ * The canonicaliser the permission gate hands `preparePermissionSubject`:
671
+ * paths resolved against `root` — by default the current working directory,
672
+ * which is the root every workspace tool resolves against at call time.
673
+ */
674
+ export function workspacePathCanonicalizer(root = process.cwd()) {
675
+ return (raw) => canonicalWorkspacePath(raw, root);
676
+ }
@@ -31,11 +31,13 @@
31
31
  * reason `classifier failed`;
32
32
  * 6. otherwise the hint only carries `eligible[]` and the policy decides.
33
33
  *
34
- * Also here: the SYNTHETIC-message marker. runtime-core pushes five kinds of
34
+ * Also here: the SYNTHETIC-message marker. runtime-core pushes six kinds of
35
35
  * non-human `role: "user"` messages onto the transcript (the grader-rationale
36
36
  * correction, the continue nudge, the tombstone retry, loop-detection
37
- * notices, the resume/toolset marker); they are `synthetic: true` in the
38
- * event log and marked in memory here so `latestHumanUserMessage` — the
37
+ * notices, the resume/toolset marker, and autocompact's summary marker and
38
+ * continuation notice); the first five are `synthetic: true` in the event
39
+ * log (compaction output is never logged as a user message), and all are
40
+ * marked in memory here so `latestHumanUserMessage` — the
39
41
  * text the rules and the classifier read — never sees them (a `/model fast`
40
42
  * echoed inside a judge's rationale must not steer routing, §7.2.1).
41
43
  * Directives themselves are parsed at the typed INPUT seams (the REPL input,