@awebai/oats 0.52.0 → 0.54.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.
Files changed (100) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +314 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
  6. package/docs/desktop-cli-api.md +696 -60
  7. package/docs/desktop-instance-start.md +25 -12
  8. package/docs/execution-targets.md +1 -0
  9. package/docs/implementation.md +184 -12
  10. package/docs/integrations.md +6 -3
  11. package/docs/knowledge.md +2 -2
  12. package/docs/macos-test-runs.md +246 -0
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-lane.md +210 -6
  16. package/docs/release-notes/v0.53.0.md +1288 -0
  17. package/docs/release-notes/v0.54.0.md +142 -0
  18. package/docs/schedules.md +7 -1
  19. package/docs/souls-and-instances.md +239 -16
  20. package/docs/tui.md +453 -21
  21. package/docs/upgrading.md +310 -0
  22. package/docs/workspaces.md +123 -3
  23. package/lib/automations.mjs +22 -22
  24. package/lib/claim.mjs +93 -4
  25. package/lib/config-data.mjs +4 -1
  26. package/lib/core.mjs +569 -121
  27. package/lib/instance-events.mjs +19 -1
  28. package/lib/instance-git.mjs +39 -3
  29. package/lib/instance-inspect.mjs +5 -6
  30. package/lib/instance-lifecycle.mjs +145 -18
  31. package/lib/instance-resolution.mjs +59 -6
  32. package/lib/launch-preference.mjs +226 -15
  33. package/lib/local-edit.mjs +118 -0
  34. package/lib/packages.mjs +18 -5
  35. package/lib/pi-bridge.mjs +308 -0
  36. package/lib/refused-text.mjs +11 -0
  37. package/lib/remote.mjs +404 -60
  38. package/lib/resolve.mjs +2 -1
  39. package/lib/retained-after-retire.mjs +2 -2
  40. package/lib/retire-output.mjs +12 -1
  41. package/lib/schedule-host.mjs +6 -35
  42. package/lib/shell-word.mjs +13 -0
  43. package/lib/soul-launch-verbs.mjs +153 -0
  44. package/lib/stable-node.mjs +62 -0
  45. package/lib/teams-verbs.mjs +18 -46
  46. package/lib/workspace.mjs +75 -27
  47. package/package-catalog.json +4 -4
  48. package/package.json +2 -1
  49. package/packages/client/attach-exit.mjs +25 -0
  50. package/packages/client/cli-adapter.mjs +16 -3
  51. package/packages/client/cli-locator.mjs +2 -2
  52. package/packages/client/deployment-contract.mjs +4 -0
  53. package/packages/client/deployment-facts.mjs +71 -10
  54. package/packages/client/deployment-panel.mjs +49 -11
  55. package/packages/client/deployment-read-cli.mjs +7 -3
  56. package/packages/client/display-text.mjs +8 -2
  57. package/packages/client/instance-acts.mjs +46 -10
  58. package/packages/client/instance-events-contract.mjs +4 -2
  59. package/packages/client/instance-presentation.mjs +66 -2
  60. package/packages/client/instance-tree.mjs +23 -14
  61. package/packages/client/kernel-lines.mjs +31 -0
  62. package/packages/client/kernel-made.mjs +23 -0
  63. package/packages/client/launch-prompt-outcome.mjs +51 -16
  64. package/packages/client/lifecycle-contract.mjs +45 -4
  65. package/packages/client/liveness.mjs +14 -1
  66. package/packages/client/own-codes.mjs +31 -0
  67. package/packages/client/panel-views.mjs +18 -11
  68. package/packages/client/readiness-contract.mjs +3 -1
  69. package/packages/client/remote-address.mjs +34 -9
  70. package/packages/client/remote-identity-memory.mjs +94 -0
  71. package/packages/client/remote-roster.mjs +92 -6
  72. package/packages/client/session-attach.mjs +175 -0
  73. package/packages/client/spawn-apply-contract.mjs +16 -4
  74. package/packages/client/spawn-messages.mjs +26 -3
  75. package/packages/client/spawn-preview-cli.mjs +8 -2
  76. package/packages/client/spawn-preview-contract.mjs +5 -1
  77. package/packages/client/terminal-exec.mjs +21 -0
  78. package/packages/client/workspace-choices.mjs +95 -0
  79. package/packages/client/workspace-views.mjs +39 -3
  80. package/packages/record/README.md +21 -0
  81. package/packages/record/bin/setup.mjs +108 -15
  82. package/packages/tui/README.md +30 -12
  83. package/packages/tui/lib/actions.mjs +16 -1
  84. package/packages/tui/lib/client.mjs +32 -1
  85. package/packages/tui/lib/config.mjs +151 -0
  86. package/packages/tui/lib/main.mjs +117 -46
  87. package/packages/tui/lib/model.mjs +392 -0
  88. package/packages/tui/lib/read.mjs +473 -0
  89. package/packages/tui/lib/store.mjs +364 -0
  90. package/packages/tui/lib/term/keys.mjs +44 -0
  91. package/packages/tui/lib/term/screen.mjs +16 -4
  92. package/packages/tui/lib/term/text.mjs +60 -0
  93. package/packages/tui/lib/term/tty.mjs +13 -3
  94. package/packages/tui/lib/views/detail.mjs +46 -0
  95. package/packages/tui/lib/views/frame.mjs +230 -36
  96. package/packages/tui/lib/views/help.mjs +125 -13
  97. package/packages/tui/lib/views/instances.mjs +137 -0
  98. package/packages/tui/lib/views/scroll.mjs +19 -0
  99. package/packages/tui/lib/views/switcher.mjs +97 -0
  100. package/skills/oats-getting-started/SKILL.md +8 -2
package/lib/remote.mjs CHANGED
@@ -13,8 +13,12 @@
13
13
  * commit locally. `ensureCommit` does a shallow, partial
14
14
  * `git fetch --depth 1 --no-tags --filter=blob:limit=64k origin <oid>` into a
15
15
  * content-addressed BARE cache repo under `<cacheRoot>/<sha256(key)>/` and then
16
- * pins the commit with `refs/oats/commits/<oid>` so `gc` cannot prune it (the
17
- * pins are also what a later fetch advertises as `have`, so it is incremental).
16
+ * pins the commit with `refs/oats/commits/<oid>` so `gc` cannot prune it. The
17
+ * pins are also what a later fetch advertises as `have`, so it is incremental:
18
+ * a new head beside the last one arrives in a few kilobytes. An incremental pack
19
+ * may refer to a blob the filter left out of the cache, and git then cannot
20
+ * complete it; that fetch is made once more without negotiation, which brings
21
+ * the commit whole (fetchCommit, awebai/oats#1059).
18
22
  * The commit arrives with ALL its trees (every listing is complete) and the blobs
19
23
  * up to SMALL_BLOB_LIMIT: every file discovery reads, in one round trip.
20
24
  * 3. Reads are then local plumbing: `git ls-tree -r -t -l -z` for listing and
@@ -66,6 +70,13 @@
66
70
  * `error.overflowed`. A listing failure git does not explain is never a raw
67
71
  * Node error escaping this module: it is E_REMOTE_UNREADABLE { reason: "unknown" }.
68
72
  *
73
+ * UNKNOWN vs NETWORK (awebai/oats#1059): a failed git call whose text shows nothing the
74
+ * kernel recognises is `unknown`, never `network`: `network` is what the text shows to
75
+ * be the network (classifyText). The message of an `unknown` failure carries git's own
76
+ * line (the last for a remote call, the first for a listing) through scrubGitLine.
77
+ * The renderer either permits that whole line with proven unchanged operation
78
+ * references and no literal @, or substitutes its fixed Git notice.
79
+ *
69
80
  * TREE SAFETY: every entry name git reports is validated BEFORE anything touches
70
81
  * the disk. A component that is empty, `.`, `..`, `.git` (any case) or contains
71
82
  * `\` / NUL is E_REMOTE_TREE_UNSAFE { why: "path" } — a crafted tree object can
@@ -83,8 +94,12 @@
83
94
  * kernel's live write (retried briefly) or to a git that was killed: one older than the
84
95
  * longest fetch, inside the cache and a regular file, is removed (a session notice says
85
96
  * so) and the write made once more; any other is E_REMOTE_UNREADABLE { reason: "cache" }
86
- * naming it. git is ended with SIGTERM first (it removes its own locks), SIGKILL after a
87
- * grace unless its group is seen empty first (process-group.mjs terminateGroup, watchGroup).
97
+ * naming it. Every fetch first removes the temporary files of the object store that are
98
+ * older than the longest fetch (a failed fetch's pack, which git does not remove), and
99
+ * no younger one: it may be another git's (removeStaleTemporaryFiles; temporaryStaleMs
100
+ * says what the longest fetch is). git is ended with
101
+ * SIGTERM first (it removes its own locks), SIGKILL after a grace unless its
102
+ * group is seen empty first (process-group.mjs terminateGroup, watchGroup).
88
103
  *
89
104
  * CACHE PIN vs OBJECTS: the pin ref is the fast-path marker, but a wiped or
90
105
  * pruned object store is detected (`rev-parse <oid>^{commit}`) and refetched;
@@ -156,6 +171,7 @@ import { homedir } from "node:os";
156
171
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
157
172
  import { fileURLToPath } from "node:url";
158
173
  import { oatsError } from "./errors.mjs";
174
+ import { REFUSED_TEXT } from "./refused-text.mjs";
159
175
  import { killGroup, signalGroup, terminateGroup, watchGroup } from "./process-group.mjs";
160
176
 
161
177
  export const FILE_BUDGET = 4 * 1024 * 1024; // readRemoteFile: 4 MiB per file
@@ -195,9 +211,27 @@ const AT_BAD_RE = /^[-/]|\/$|\.\.|[\s~^:?*[\\\x00-\x1f\x7f]|@\{|\/\.|^\.|\.lock(
195
211
  const BAD_COMPONENT_RE = /^(?:|\.|\.\.|\.git)$/i;
196
212
 
197
213
  /** oatsError with the details reachable as BOTH e.provenance (today's field) and e.details. */
198
- function fail(code, message, details) {
199
- const e = oatsError(code, message, details);
200
- if (details) e.details = details;
214
+ function fail(code, message, details, { rejected = [] } = {}) {
215
+ // All diagnostics cross this boundary, including auxiliary fields and rejected objects.
216
+ // Keep the caller's ref untouched: it remains the transport input, never this rendered copy.
217
+ // Only the refusing boundary selects other rejected inputs; successful values
218
+ // with the same field names remain operational and exact.
219
+ const source = [details?.url, details?.ref, ...rejected.map(field => details?.[field])];
220
+ const safe = { details: details && Object.fromEntries(Object.entries(details).map(([field, value]) => [field, redactUrl(value, source, { known: false })])) };
221
+ for (const field of ["url", "ref", ...rejected]) if (details && field in details) {
222
+ safe.details[field] = redactUrl(details[field], null, { reference: true, rejectedValue: rejected.includes(field) });
223
+ }
224
+ // Malformed userinfo may already have been split by the parser into host/path.
225
+ if (code === "E_REPO_REF") for (const field of ["host", "path"]) if (!rejected.includes(field) && details && field in details) {
226
+ safe.details[field] = redactUrl(details[field], source, { fragment: true, known: false });
227
+ }
228
+ // Refused-input sentences can format the selected display directly. This keeps
229
+ // a rejected word/key (such as "commit" or "https") from replacing fixed reason
230
+ // text that happens to contain the same word. The renderer still owns the clause.
231
+ safe.message = redactUrl(typeof message === "function" ? message(safe.details) : message, source,
232
+ { known: false, refusal: code === "E_REPO_REF", substitute: rejected.length === 0, rejectedValue: rejected.length > 0 });
233
+ const e = oatsError(code, safe.message, safe.details);
234
+ if (details) e.details = safe.details;
201
235
  return e;
202
236
  }
203
237
 
@@ -232,7 +266,7 @@ function hostedRef(host, rawPath, text, { fetchUrl = null, transport = "https" }
232
266
  function transportOf(options) {
233
267
  const t = options?.transport;
234
268
  if (t === undefined || t === null) return "https";
235
- if (!TRANSPORTS.has(t)) throw fail("E_REPO_REF", `remoteOptions.transport must be "https" or "ssh", got ${JSON.stringify(t)}`, { transport: t });
269
+ if (!TRANSPORTS.has(t)) throw fail("E_REPO_REF", ({ transport }) => `remoteOptions.transport must be "https" or "ssh", got ${JSON.stringify(transport)}`, { transport: t }, { rejected: ["transport"] });
236
270
  return t;
237
271
  }
238
272
 
@@ -270,7 +304,12 @@ export function parseRepoRef(text, options = undefined) {
270
304
  try { return localRef(fileURLToPath(ref)); } catch { throw fail("E_REPO_REF", `invalid file URL: ${ref}`, { ref }); }
271
305
  }
272
306
  if (isAbsolute(ref)) return localRef(ref);
273
- throw fail("E_REPO_REF", `unrecognized repository reference: ${ref}`, { ref });
307
+ // These forms already failed the accepted grammar above. State the HTTP authority
308
+ // rule here; rendering and its omission clause belong only to the diagnostic boundary.
309
+ const reason = /^https?:\/\/[^/]*@/.test(ref)
310
+ ? `repository reference ${ref} carries user information, which an http(s) reference may not: give credentials to Git (a credential helper), not in the URL`
311
+ : `unrecognized repository reference: ${ref}`;
312
+ throw fail("E_REPO_REF", reason, { ref });
274
313
  }
275
314
 
276
315
  // ---------------------------------------------------------------------------
@@ -417,30 +456,64 @@ function stderrText(error) {
417
456
  return Buffer.isBuffer(s) ? s.toString("utf8") : typeof s === "string" ? s : String(error?.message ?? "");
418
457
  }
419
458
 
420
- /** Classify a failed network git call into the contract's reasons. A `maxBuffer`
421
- * overflow is never a timeout (the child is killed in both cases; only the timeout kill
422
- * counts) — it falls through to the stderr text, else "network". A timeout is our own
423
- * timer's kill (`timedOut`), whatever signal it sent. A git lock still held by another
424
- * process (a lost race that outlived retryLockRace, or a dead process's stale lock) is
425
- * "cache": a local cache write failed, nothing about the remote. Any other signal exit is
426
- * "killed" (the system killed git, e.g. out of memory). */
459
+ /** Classify a failed git call into the contract's reasons. A `maxBuffer` overflow is never
460
+ * a timeout (the child is killed in both cases; only the timeout kill counts): it is what
461
+ * its stderr text shows. A timeout is our own timer's kill (`timedOut`), whatever signal it
462
+ * sent. A git lock still held by another process (a lost race that outlived retryLockRace,
463
+ * or a dead process's stale lock) is "cache": a local cache write failed, nothing about the
464
+ * remote. Any other signal exit is "killed" (the system killed git, e.g. out of memory).
465
+ * Otherwise the text decides, and a text that shows nothing the kernel recognises is
466
+ * "unknown" (awebai/oats#1059): "network" is only what the text shows to be the network. */
427
467
  export function classifyRemoteFailure(error) {
428
- if (error?.overflowed === true || error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return classifyText(error) ?? "network";
468
+ if (error?.overflowed === true || error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return classifyText(error) ?? "unknown";
429
469
  if (error?.timedOut) return "timeout";
430
470
  if (isLockRace(error) || isLocalWriteFailure(error)) return "cache";
431
471
  if (typeof error?.signal === "string" && error.signal) return "killed";
432
- return classifyText(error) ?? "network";
472
+ return classifyText(error) ?? "unknown";
433
473
  }
434
474
 
435
- /** The stderr-text half of classifyRemoteFailure; null when the text says nothing recognisable. */
475
+ /** An object id as git prints it (SHA-1 or SHA-256). */
476
+ const OBJECT_ID_RE = /\b[0-9a-f]{40}(?:[0-9a-f]{24})?\b/g;
477
+ /** The stderr-text half of classifyRemoteFailure; null when the text says nothing recognisable. The object
478
+ * ids git names are taken out first: an id is evidence of nothing, and one that holds `403` must not read
479
+ * as a refusal of the operator's credentials. The network texts are git's own and its transports' (libcurl's
480
+ * come after git's "unable to access"; ssh's and getaddrinfo's are named). */
436
481
  function classifyText(error) {
437
- const text = stderrText(error).toLowerCase();
482
+ const text = stderrText(error).toLowerCase().replace(OBJECT_ID_RE, "");
438
483
  if (/authentication failed|could not read username|could not read password|permission denied|publickey|403|forbidden|terminal prompts disabled|invalid username or password|access denied|unauthori[sz]ed/.test(text)) return "auth";
439
484
  if (/repository not found|repository '.*' not found|not found|does not appear to be a git repository|no such file or directory|not our ref|unadvertised object|couldn't find remote ref|remote ref .* not found|not a valid object name|not a tree object|bad object|is not a valid revision|no such ref/.test(text)) return "not-found";
440
- if (/could not resolve host|connection refused|connection timed out|network is unreachable|unable to access|early eof|remote end hung up|connection reset|ssl|tls|unable to connect/.test(text)) return "network";
485
+ if (/could not resolve host|could not resolve proxy|name or service not known|temporary failure in name resolution|connection refused|connection timed out|operation timed out|network is unreachable|no route to host|unable to access|early eof|remote end hung up|unexpected disconnect|connection reset|connection closed by|ssl|tls|unable to connect|failed to connect/.test(text)) return "network";
441
486
  return null;
442
487
  }
443
488
 
489
+ /** How much of one line of git's is printed in a message. */
490
+ export const GIT_LINE_MAX = 300;
491
+ const REFUSED_TEXT_ALL = new RegExp(REFUSED_TEXT.source, "gu");
492
+ /** A terminal's control sequence (a colour, a cursor move), which goes whole and not only its escape character. */
493
+ const ANSI_SEQUENCE_RE = /\x1b\[[0-9;?]*[ -\/]*[@-~]/g;
494
+ /**
495
+ * One line of git's own words, made fit to print in a message (a failure message is an output channel:
496
+ * the fetch url is on git's command line, may carry credentials, and git or its transport can echo it).
497
+ * The renderer decides whether the ORIGINAL line may be shown using the ORIGINAL
498
+ * operation reference; otherwise it returns its fixed Git notice. Formatting here
499
+ * folds whitespace and bounds the display to GIT_LINE_MAX code points. An absent
500
+ * or blank line has no words to quote and returns "".
501
+ */
502
+ export function scrubGitLine(line, url = null) {
503
+ const original = String(line ?? "");
504
+ if (!original.trim()) return "";
505
+ const text = redactUrl(original, url);
506
+ const points = [...text.replace(ANSI_SEQUENCE_RE, "").replace(/\s+/g, " ").replace(REFUSED_TEXT_ALL, "").trim()];
507
+ return points.length > GIT_LINE_MAX ? `${points.slice(0, GIT_LINE_MAX - 1).join("")}…` : points.join("");
508
+ }
509
+ /** The last line git wrote that says anything (a progress line ends with a carriage return), scrubbed. */
510
+ function gitLastLine(error, url) {
511
+ const stderr = error?.stderr;
512
+ const text = Buffer.isBuffer(stderr) ? stderr.toString("utf8") : typeof stderr === "string" ? stderr : "";
513
+ const lines = text.split(/[\r\n]+/).map((line) => scrubGitLine(line, url)).filter(Boolean);
514
+ return lines.length ? lines[lines.length - 1] : "";
515
+ }
516
+
444
517
  /** What to do when git on a macOS host cannot reach its keychain: the credentials git uses must live
445
518
  * somewhere a session without a terminal can read. */
446
519
  export const KEYCHAIN_REMEDY = "on macOS a session without a terminal (an ssh command, a background job) cannot open the login keychain where git's credential helper keeps the forge token; store git credentials outside the keychain (`gh auth login --insecure-storage`, then `gh auth setup-git`), or use an SSH key the session can reach: one without a passphrase, or the desktop login's ssh-agent (point SSH_AUTH_SOCK at it in the shell's startup file)";
@@ -453,11 +526,17 @@ export function keychainHint({ platform = process.platform, stdinIsTTY = process
453
526
  return !stdinIsTTY || !!env.SSH_CONNECTION ? "keychain-non-interactive" : null;
454
527
  }
455
528
 
529
+ /** A failed git call as E_REMOTE_UNREADABLE, by its reason (classifyRemoteFailure). The message prints the
530
+ * url as every message of the cache does, without its user information (redactUrl); `details.url` carries that
531
+ * rendered url too. A failure the kernel cannot classify (`unknown`) carries the permitted last Git
532
+ * line or the renderer's fixed notice (scrubGitLine). With no text, an output over its budget is said,
533
+ * and otherwise the message ends at the reason. */
456
534
  function unreadable(ref, error, extra = {}) {
457
535
  const reason = classifyRemoteFailure(error), killed = reason === "killed";
458
536
  if (reason === "cache") return cacheFailure(ref, error, extra);
459
537
  const hint = keychainHint({ reason });
460
- return fail("E_REMOTE_UNREADABLE", `cannot read remote ${ref.url} (${reason})${killed ? `: git was killed (signal ${error.signal})` : ""}${hint ? `: ${KEYCHAIN_REMEDY}` : ""}`,
538
+ const said = reason === "unknown" ? gitLastLine(error, ref.url) || (error?.overflowed === true ? "git's output exceeded its budget" : "") : "";
539
+ return fail("E_REMOTE_UNREADABLE", `cannot read remote ${redactUrl(ref.url, null, { reference: true })} (${reason})${killed ? `: git was killed (signal ${error.signal})` : ""}${said ? `: ${said}` : ""}${hint ? `: ${KEYCHAIN_REMEDY}` : ""}`,
461
540
  { url: ref.url, key: ref.key, reason, ...(killed ? { signal: error.signal } : {}), ...(hint ? { hint, remedy: KEYCHAIN_REMEDY } : {}), ...extra });
462
541
  }
463
542
 
@@ -479,9 +558,10 @@ const isLocalWriteFailure = (error) => /cannot open '[^']+': |unable to create t
479
558
 
480
559
  /** A write to the local cache repo failed — reason "cache" (a timeout stays "timeout"), never "network" — with a
481
560
  * message that says what to do: a lock still held names its file, safe to remove once no oats process runs;
482
- * any other failure carries git's own words. `extra.stage` says which write (init, pin, config, fetch). */
561
+ * any other failure carries the permitted Git line or fixed notice. `extra.stage` says which write
562
+ * (init, pin, config, fetch). */
483
563
  function cacheFailure(ref, error, extra = {}) {
484
- const url = redactUrl(ref.url);
564
+ const url = redactUrl(ref.url, null, { reference: true });
485
565
  if (error?.timedOut) return fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url} (timeout)`, { url: ref.url, key: ref.key, reason: "timeout", ...extra });
486
566
  const where = extra.cacheDir ? ` at ${extra.cacheDir}` : "";
487
567
  const lock = isLockRace(error) ? lockFileOf(error, extra.cacheDir) : null;
@@ -490,7 +570,7 @@ function cacheFailure(ref, error, extra = {}) {
490
570
  return fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url}${where} (cache${extra.stage ? `, ${extra.stage}` : ""}): ${held} by another git process, or left by one that died; it is safe to remove once no oats or git process is running`,
491
571
  { url: ref.url, key: ref.key, reason: "cache", ...extra, ...(lock ? { lock } : {}) });
492
572
  }
493
- const why = stderrText(error).trim().split("\n").filter(Boolean).join(" ") || error?.message || error?.code || "git failed";
573
+ const why = scrubGitLine(stderrText(error) || error?.message || error?.code || "git failed", ref.url);
494
574
  const check = isLocalWriteFailure(error) ? `; check that ${extra.cacheDir ?? "the cache"} is writable by this user and its disk has room` : "";
495
575
  return fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url}${where} (cache${extra.stage ? `, ${extra.stage}` : ""}): ${why}${check}`, { url: ref.url, key: ref.key, reason: "cache", ...extra });
496
576
  }
@@ -586,7 +666,7 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
586
666
  const signal = session?.signal;
587
667
  const lock = cacheWriteLockOf(dir);
588
668
  const owner = { pid: process.pid, token: randomBytes(12).toString("hex"), startedAt: new Date().toISOString() };
589
- const url = redactUrl(ref.url);
669
+ const url = redactUrl(ref.url, null, { reference: true });
590
670
  const refuse = (message, extra = {}) => fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url} at ${dir} (cache, ${stage}): ${message}`,
591
671
  { url: ref.url, key: ref.key, reason: "cache", stage, cacheDir: dir, lock, ...extra });
592
672
  try { mkdirSync(dirname(lock), { recursive: true, mode: 0o700 }); } catch (error) { throw refuse(`cannot create ${dirname(lock)} (${error.code ?? error.message})`); }
@@ -694,7 +774,7 @@ async function cacheGit(repo, args, opts = {}) {
694
774
  catch (error) {
695
775
  const lockFile = isLockRace(error) ? lockFileOf(error, repo.dir) : null;
696
776
  if (!lockFile || !reclaimGitLock(repo, lockFile)) throw error;
697
- repo.session?.notices.push(`removed a stale git lock ${lockFile} (left by a git process that was killed mid-write)`);
777
+ repo.session?.notices.push(redactUrl(`removed a stale git lock ${lockFile} (left by a git process that was killed mid-write)`, null, { known: false }));
698
778
  return await run();
699
779
  }
700
780
  }
@@ -703,9 +783,184 @@ const sha256 = (text) => createHash("sha256").update(text).digest("hex");
703
783
  const cacheRootOf = (options) => options.cacheDir ?? defaultCacheRoot();
704
784
  const cacheDirOf = (root, ref) => join(root, sha256(ref.key));
705
785
 
706
- /** A url without its userinfo (`ssh://user:secret@host/…` → `ssh://host/…`): what may be written to disk. */
707
- function redactUrl(url) {
708
- return typeof url === "string" ? url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^@/]*@/i, "$1") : url;
786
+ /** Diagnostic display policy. Selected values are constructed from recognised components,
787
+ * or withheld whole; bounded plain selected values retain their original spelling.
788
+ * Unvalidated fragments require a plain original source, never a fragment-only check.
789
+ * Raw parser results and transport never pass through this display-only function.
790
+ * Untrusted Git prose is displayed only with unchanged operation references and no @.
791
+ * Kernel/schema prose explicitly selects known:false and replaces only its source.
792
+ */
793
+ export function redactUrl(value, source = null, { reference = false, fragment = false, known = true, refusal = false, substitute = true, rejectedValue = false, pinned = false } = {}) {
794
+ const withheld = "[repository reference withheld]";
795
+ const valueWithheld = "[value withheld]";
796
+ const valueWithholding = "(the value was withheld)";
797
+ const omission = "(its user information is not shown)";
798
+ const withholding = "(the repository reference was withheld)";
799
+ const plans = new Map();
800
+ const isPlain = (input) => input.length > 0 && input.length <= 256 && !/[^A-Za-z0-9 ._/+:\-]/.test(input);
801
+ // Plain display belongs to selected diagnostics, not Git operation provenance
802
+ // or the stricter pinned-source component constructor.
803
+ const allowPlain = !pinned && (reference || fragment || !known);
804
+ const hostOK = (host) => /^[a-z0-9.-]+$/i.test(host);
805
+ // Use the admission parser's path components, without calling its throwing helpers:
806
+ // failure construction must never recurse through parsing and back into rendering.
807
+ const pathOK = (path) => {
808
+ const cleaned = path.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "");
809
+ const parts = cleaned.split("/");
810
+ return parts.length >= 2 && parts.every(p => SEGMENT_RE.test(p) && p !== "." && p !== "..");
811
+ };
812
+ const plan = (input) => {
813
+ if (plans.has(input)) return plans.get(input);
814
+ const result = { input, display: withheld, withheld: true, info: "", http: false };
815
+ plans.set(input, result);
816
+ const plain = isPlain(input);
817
+ if (rejectedValue) {
818
+ Object.assign(result, { display: plain ? input : valueWithheld, withheld: !plain });
819
+ return result;
820
+ }
821
+ if (allowPlain && plain) {
822
+ Object.assign(result, { display: input, withheld: false, plain: true });
823
+ return result;
824
+ }
825
+ const text = input.trim();
826
+ // Local paths are path data, including @. Restrict the display grammar so a
827
+ // composed file/remote value cannot masquerade as a standalone local path.
828
+ if (/^(?:file:\/{3,}|\/)[A-Za-z0-9_./@% +~-]*$/.test(text)) {
829
+ Object.assign(result, { display: text, withheld: false });
830
+ return result;
831
+ }
832
+ let scheme, authority, path, info = "", port = "", host;
833
+ const prefix = /^(https?|ssh):\/\//i.exec(text);
834
+ if (prefix) {
835
+ scheme = prefix[1];
836
+ const slash = text.indexOf("/", prefix[0].length);
837
+ if (slash < 0) return result;
838
+ authority = text.slice(prefix[0].length, slash);
839
+ path = text.slice(slash + 1);
840
+ const at = authority.indexOf("@");
841
+ if (at >= 0) {
842
+ info = authority.slice(0, at);
843
+ // Same userinfo characters as admitted SSH; display HTTP may recognise
844
+ // these components even though HTTP admission refuses userinfo entirely.
845
+ if (/[@/\s]/.test(info) || authority.indexOf("@", at + 1) >= 0) return result;
846
+ authority = authority.slice(at + 1);
847
+ }
848
+ const colon = authority.indexOf(":");
849
+ host = colon < 0 ? authority : authority.slice(0, colon);
850
+ if (colon >= 0) {
851
+ port = authority.slice(colon);
852
+ if (!/^:\d+$/.test(port)) return result;
853
+ }
854
+ } else {
855
+ const scp = /^([^@/\s]+)@([^:/@\s]+):([\s\S]*)$/.exec(text);
856
+ if (scp) { scheme = "ssh"; info = scp[1]; host = scp[2]; path = scp[3]; }
857
+ else {
858
+ const bare = /^(git:)?([^/:@\s]+)\/([\s\S]*)$/.exec(text);
859
+ if (!bare) return result;
860
+ scheme = bare[1] ? "git" : ""; host = bare[2]; path = bare[3];
861
+ }
862
+ }
863
+ if (!hostOK(host) || !pathOK(path)) return result;
864
+ const display = scheme === "git" ? `git:${host}/${path}` : scheme ? `${scheme}://${host}${port}/${path}` : `${host}/${path}`;
865
+ Object.assign(result, { display, withheld: false, info, http: /^https?$/i.test(scheme), host, path });
866
+ return result;
867
+ };
868
+ // Pinned-source interpretation is explicit display context, never reference
869
+ // admission or a fallback for arbitrary strings. Both components must be usable.
870
+ const pinnedDisplay = (input) => {
871
+ if (input === withheld) return withheld;
872
+ const at = input.lastIndexOf("@");
873
+ const parts = pinned === true ? { ref: input.slice(0, at), commit: input.slice(at + 1) } : pinned;
874
+ if (!parts || typeof parts.ref !== "string" || typeof parts.commit !== "string"
875
+ || parts.commit.length !== 40 || !OID_RE.test(parts.commit) || input !== `${parts.ref}@${parts.commit}`) return withheld;
876
+ const ref = plan(parts.ref);
877
+ return ref.withheld ? withheld : `${ref.display}@${parts.commit}`;
878
+ };
879
+ const selected = [], seenSource = new WeakSet();
880
+ const collect = (input) => {
881
+ if (typeof input === "string") {
882
+ selected.push(plan(input));
883
+ } else if (input && typeof input === "object" && !seenSource.has(input)) {
884
+ seenSource.add(input);
885
+ for (const [key, item] of Object.entries(input)) { if (!Array.isArray(input)) collect(key); collect(item); }
886
+ }
887
+ };
888
+ collect(source);
889
+ const replacements = new Map();
890
+ for (const p of selected) if (p.input && p.input !== p.display) {
891
+ replacements.set(p.input, p.display);
892
+ replacements.set(JSON.stringify(p.input).slice(1, -1), JSON.stringify(p.display).slice(1, -1));
893
+ }
894
+ const exact = [...replacements].sort((a,b) => b[0].length - a[0].length);
895
+ // Decide from the ORIGINAL operation references and ORIGINAL Git line, before
896
+ // replacement, control handling or truncation. Missing provenance cannot prove
897
+ // safe references. Kernel/schema text uses known:false instead of this policy.
898
+ const gitNotice = "Git's diagnostic was withheld; run the same Git operation by hand to see Git's own words.";
899
+ const safeOperation = (typeof source === "string" || (Array.isArray(source) && source.every(item => typeof item === "string")))
900
+ && selected.every(p => !p.withheld && p.input === p.display);
901
+ const gitLine = (input) => safeOperation && !input.includes("@")
902
+ ? input.replace(ANSI_SEQUENCE_RE, "").replace(/\s+/g, " ").replace(REFUSED_TEXT_ALL, "") : gitNotice;
903
+ // KMP returns nonoverlapping literal matches in linear time, including absent
904
+ // periodic matches. Never search long parser fragments in their raw source.
905
+ const matches = (input, pattern) => {
906
+ const prefix = new Uint32Array(pattern.length), found = [];
907
+ for (let i=1,j=0; i<pattern.length; i++) {
908
+ while (j && pattern[i] !== pattern[j]) j=prefix[j-1];
909
+ if (pattern[i] === pattern[j]) j++;
910
+ prefix[i]=j;
911
+ }
912
+ for (let i=0,j=0; i<input.length; i++) {
913
+ while (j && input[i] !== pattern[j]) j=prefix[j-1];
914
+ if (input[i] === pattern[j]) j++;
915
+ if (j === pattern.length) { found.push(i-j+1); j=0; }
916
+ }
917
+ return found;
918
+ };
919
+ const text = (input) => {
920
+ if (pinned) return pinnedDisplay(input);
921
+ if (reference) return plan(input).display;
922
+ if (fragment && selected.length) {
923
+ if (selected.some(p => p.withheld)) return withheld;
924
+ // Only plain ORIGINAL sources permit unvalidated derived text. A credentialed
925
+ // source must still provide a validated component, even if its fragment is plain.
926
+ if (selected.every(p => p.plain)) return input;
927
+ return selected.some(p => input === p.host || input === p.path) ? input : withheld;
928
+ }
929
+ if (known) return gitLine(input);
930
+ // A fixed kernel reason can share words with the rejected value. It still
931
+ // needs the source-derived explanation, but contains no source copy to replace.
932
+ if (!substitute) return input;
933
+ let pieces = [{ value: input, safe: false }];
934
+ for (const [raw, display] of exact) pieces = pieces.flatMap(piece => {
935
+ if (piece.safe) return [piece];
936
+ let start=0; const result=[];
937
+ for (const at of matches(piece.value, raw)) {
938
+ const end=at+raw.length;
939
+ if ((at && !/[\s'"=(]/.test(piece.value[at-1]))
940
+ || (end < piece.value.length && !/[\s'"),;>]/.test(piece.value[end]))) continue;
941
+ result.push({ value: piece.value.slice(start,at), safe:false }, { value:display, safe:true }); start=end;
942
+ }
943
+ result.push({ value:piece.value.slice(start), safe:false }); return result;
944
+ });
945
+ // Only exact selected-source copies change inside kernel/schema prose.
946
+ return pieces.map(piece => piece.value).join("");
947
+ };
948
+ const seen = new WeakMap();
949
+ const render = (input) => {
950
+ if (typeof input === "string") return text(input);
951
+ if (!input || typeof input !== "object") return input;
952
+ if (seen.has(input)) return seen.get(input);
953
+ const result = Array.isArray(input) ? [] : {};
954
+ seen.set(input,result);
955
+ for (const [key,item] of Object.entries(input)) Object.defineProperty(result, Array.isArray(input) ? key : text(key), {
956
+ value:render(item), enumerable:true, configurable:true, writable:true,
957
+ });
958
+ return result;
959
+ };
960
+ const rendered = render(value);
961
+ const clause = selected.some(p => p.withheld) ? (rejectedValue ? valueWithholding : withholding) : selected.some(p => p.info) ? omission : null;
962
+ return refusal && typeof rendered === "string" && clause && !rendered.includes(omission) && !rendered.includes(withholding) && !rendered.includes(valueWithholding)
963
+ ? `${rendered} ${clause}` : rendered;
709
964
  }
710
965
 
711
966
  function repoHandle(dir, exec, session) {
@@ -741,7 +996,7 @@ async function initCacheRepo(ref, dir, exec, session = null) {
741
996
  try {
742
997
  try { mkdirSync(tmp, { recursive: true, mode: 0o700 }); } catch (error) { throw failInit(error); }
743
998
  try { await sessionExec(exec, session, ["init", "-q", "--bare", tmp]); } catch (error) { throw failInit(error); }
744
- try { writeFileSync(join(tmp, "oats-remote.json"), JSON.stringify({ key: ref.key, url: redactUrl(ref.url) }, null, 2) + "\n"); } catch {}
999
+ try { writeFileSync(join(tmp, "oats-remote.json"), JSON.stringify({ key: ref.key, url: redactUrl(ref.url, null, { reference: true }) }, null, 2) + "\n"); } catch {}
745
1000
  const deadline = Date.now() + HALF_INIT_WAIT_MS;
746
1001
  for (;;) {
747
1002
  try { renameSync(tmp, dir); return; } // replaces nothing, or an EMPTY directory
@@ -1216,14 +1471,14 @@ async function ensureCommit(ref, oid, options) {
1216
1471
  const mode = await fetchMode(repo)
1217
1472
  ?? (keepsPartialCache(version) ? await startPartialFetches(repo, ref) : await recordFullFetches(repo, ref, olderGitNotice(version, ref)));
1218
1473
  const filter = mode === "partial" ? [`--filter=${PARTIAL_FILTER}`] : ["--no-filter"];
1219
- const { stderr } = await fetchInto(repo, ref, ["fetch", "-q", "--depth", "1", "--no-tags", "--no-recurse-submodules", ...filter, "origin", oid], { what: oid, commit: oid });
1474
+ const { stderr } = await fetchCommit(repo, ref, ["fetch", "-q", "--depth", "1", "--no-tags", "--no-recurse-submodules", ...filter, "origin", oid], oid);
1220
1475
  // A server without filters says so and sends the whole tree: nothing is lost, the cache remembers.
1221
1476
  if (mode === "partial" && /filtering not recognized by server/i.test(stderr.toString("utf8"))) await recordFullFetches(repo, ref);
1222
1477
  const commit = await asReadTimeout(repo, peelCommit(repo, oid));
1223
1478
  if (!commit) {
1224
1479
  // The peel answered: the object is missing or not a commit (a peel the deadline ended was thrown above).
1225
1480
  const type = await asReadTimeout(repo, objectType(repo, oid));
1226
- throw fail("E_REMOTE_UNREADABLE", `${oid} in ${ref.url} is ${type ? `a ${type}` : "missing"}, not a commit`, { url: ref.url, key: ref.key, reason: "not-found", commit: oid, type });
1481
+ throw fail("E_REMOTE_UNREADABLE", `${oid} in ${redactUrl(ref.url, null, { reference: true })} is ${type ? `a ${type}` : "missing"}, not a commit`, { url: ref.url, key: ref.key, reason: "not-found", commit: oid, type });
1227
1482
  }
1228
1483
  await writePin(repo, ref, pinRef(commit), commit, commit);
1229
1484
  if (commit !== oid) await writePin(repo, ref, `refs/oats/tags/${oid}`, oid, commit);
@@ -1232,6 +1487,32 @@ async function ensureCommit(ref, oid, options) {
1232
1487
  });
1233
1488
  }
1234
1489
 
1490
+ /**
1491
+ * The fetch of a commit into the cache (awebai/oats#1059). The fetch negotiates: git tells the server the
1492
+ * commits the cache holds (its pins), and the pack holds only what they lack, a few kilobytes for a new head
1493
+ * beside the last one. But the server may then send an object as a delta against one it takes the cache to
1494
+ * hold, and the cache does not hold the blobs its filter left out (nor, in a cache that turned to whole
1495
+ * trees, those of the commits fetched before): the pack cannot be completed, git may not fetch the missing
1496
+ * base on its own (GIT_NO_LAZY_FETCH), and the fetch dies with words the kernel cannot classify. `git fetch`
1497
+ * has no way to ask for a pack that is complete by itself while negotiating. So a fetch whose failure the
1498
+ * kernel cannot classify (`unknown`: never by git's wording) is made once more without negotiation
1499
+ * (`fetch.negotiationAlgorithm=noop`, as the fetch of blobs by id): the server is told nothing of what the
1500
+ * cache holds and sends the commit whole, which is complete whatever the cache holds. One second attempt,
1501
+ * never a third; if it fails, its failure is the answer. The first attempt's temporary pack stays in the
1502
+ * object store until a later fetch finds it old enough (removeStaleTemporaryFiles): one pack per commit that
1503
+ * needed its second attempt, since that commit is then present and never fetched again.
1504
+ * → { stdout, stderr } of the fetch that succeeded.
1505
+ */
1506
+ async function fetchCommit(repo, ref, args, oid) {
1507
+ try { return await fetchInto(repo, ref, args, { what: oid, commit: oid, raw: true }); }
1508
+ catch (error) {
1509
+ if (typeof error?.code === "string" && error.code.startsWith("E_")) throw error; // the fetch's timeout
1510
+ // A command that gave the read up is not asked again; neither is a failure the kernel can name.
1511
+ if (error?.code === "ABORT_ERR" || repo.session?.signal?.aborted || classifyRemoteFailure(error) !== "unknown") throw fetchFailure(repo, ref, error, oid);
1512
+ }
1513
+ return fetchInto(repo, ref, ["-c", "fetch.negotiationAlgorithm=noop", ...args], { what: oid, commit: oid });
1514
+ }
1515
+
1235
1516
  /** Pin `name` to `oid` in the cache repo. Two processes pinning one commit write the same value: a lost lock
1236
1517
  * race is retried, and a ref that already holds `oid` (another process's write) counts as written. */
1237
1518
  async function writePin(repo, ref, name, oid, commit) {
@@ -1270,14 +1551,14 @@ async function writeConfig(repo, ref, key, value) {
1270
1551
 
1271
1552
  /** This cache fetches whole trees from now on (its server cannot serve partial fetches, or this git cannot keep
1272
1553
  * a partial cache): recorded, and said once (the session's notices; the CLI prints them when the command ends). */
1273
- async function recordFullFetches(repo, ref, notice = `${redactUrl(ref.url)} does not serve partial fetches; OATS fetches whole trees from it`) {
1554
+ async function recordFullFetches(repo, ref, notice = `${redactUrl(ref.url, null, { reference: true })} does not serve partial fetches; OATS fetches whole trees from it`) {
1274
1555
  await writeConfig(repo, ref, "oats.fetch", "full");
1275
- repo.session?.notices.push(notice);
1556
+ repo.session?.notices.push(redactUrl(notice, ref.url, { known: false }));
1276
1557
  return "full";
1277
1558
  }
1278
1559
 
1279
1560
  const olderGitNotice = (version, ref) =>
1280
- `git ${version?.text ?? "(unknown version)"} cannot keep a partial cache (it needs ${PARTIAL_FETCH_GIT.join(".")}); OATS fetches whole trees from ${redactUrl(ref.url)}`;
1561
+ `git ${version?.text ?? "(unknown version)"} cannot keep a partial cache (it needs ${PARTIAL_FETCH_GIT.join(".")}); OATS fetches whole trees from ${redactUrl(ref.url, null, { reference: true })}`;
1281
1562
 
1282
1563
  /** `git --version` of the git `exec` runs, asked once per exec: → { text: "2.54.0", major, minor } | null.
1283
1564
  * `opts` (a timeout, a signal) go to the call that asks. A call that timed out says nothing about this git:
@@ -1362,20 +1643,82 @@ function markCacheDamaged(repo, why) {
1362
1643
  /** The repository carries a damage mark this session did not set: the next fetch rebuilds it first. */
1363
1644
  const toRebuild = (dir, session) => existsSync(join(dir, DAMAGED_MARK)) && !session?.damaged.has(dir);
1364
1645
 
1365
- /** `git fetch` from the remote into the cache (args start at the subcommand and name the remote "origin"):
1366
- * a lost on-disk `.lock` race is retried, a timeout names the fetch (`what`) and how long it ran, any other
1367
- * failure is E_REMOTE_UNREADABLE (`raw`: the git error itself, for a caller that reads its stderr). → { stdout, stderr } */
1646
+ /**
1647
+ * THE LONGEST FETCH, the age past which a fetch may remove a temporary file of git's: 11 minutes, which is the
1648
+ * 10 minutes any kernel gives the fetch of a commit (GIT_FETCH_TIMEOUT_MS) and one minute of margin, the
1649
+ * constant a stale git lock is judged by (GIT_LOCK_STALE_MS); or, when the session making this fetch was given
1650
+ * a longer fetch timeout of its own, that timeout and the same minute (`fetchTimeoutMs`; no caller in the
1651
+ * kernel gives one). No fetch a kernel started can still be writing a file that old: git is ended at the
1652
+ * timeout, and an older kernel's fetch, which takes no write lock, has the same 10 minutes.
1653
+ */
1654
+ const temporaryStaleMs = (session) => Math.max(GIT_LOCK_STALE_MS, (session?.fetchTimeoutMs ?? 0) + 60_000);
1655
+ /**
1656
+ * The temporary files git has in the cache's object store: → Map path → mtimeMs. A fetch receives
1657
+ * its pack into `objects/pack/tmp_pack_*` (index-pack; its index and reverse index are written as
1658
+ * `tmp_idx_*` and `tmp_rev_*` there), and a pack small enough to be unpacked writes each object as
1659
+ * `objects/<xx>/tmp_obj_*` first; git's own `prune` looks for `tmp_*` in `objects`, `objects/pack` and those
1660
+ * directories, and so does this. index-pack does not remove its file when it dies, and nothing else in the
1661
+ * cache ever would (it runs no gc). Regular files only, and only inside the cache entry: no symbolic link
1662
+ * is followed below it (the rule of reclaimGitLock), so a directory that is one, or that lies behind one,
1663
+ * holds none, as does a directory that cannot be read.
1664
+ */
1665
+ function gitTemporaryFiles(repo) {
1666
+ const found = new Map();
1667
+ let root;
1668
+ try { root = realpathSync(repo.dir); } catch { return found; }
1669
+ const scan = (...below) => {
1670
+ const dir = join(root, ...below);
1671
+ let names;
1672
+ try {
1673
+ if (!lstatSync(dir).isDirectory() || realpathSync(dir) !== dir) return [];
1674
+ names = readdirSync(dir);
1675
+ } catch { return []; }
1676
+ for (const name of names) {
1677
+ if (!name.startsWith("tmp_")) continue;
1678
+ try { const st = lstatSync(join(dir, name)); if (st.isFile()) found.set(join(dir, name), st.mtimeMs); } catch { /* gone meanwhile */ }
1679
+ }
1680
+ return names;
1681
+ };
1682
+ for (const name of scan("objects")) if (/^[0-9a-f]{2}$/.test(name)) scan("objects", name);
1683
+ scan("objects", "pack");
1684
+ return found;
1685
+ }
1686
+ /**
1687
+ * Before a fetch, under the cache's write lock: remove the temporary files of the object store that are older
1688
+ * than the longest fetch (temporaryStaleMs says what that is). That is the only rule, for a failed fetch's own leftovers too:
1689
+ * a file that appeared during a fetch cannot be told from one another git is writing (an older kernel's fetch
1690
+ * takes no write lock, git names its pack file itself, and nothing says who holds a file open), so none is
1691
+ * removed for having appeared; git's own `prune` goes by age for the same reason. A failed fetch's pack
1692
+ * therefore stays until a fetch into this entry finds it old enough.
1693
+ */
1694
+ function removeStaleTemporaryFiles(repo) {
1695
+ const staleMs = temporaryStaleMs(repo.session), now = Date.now();
1696
+ for (const [file, mtimeMs] of gitTemporaryFiles(repo)) {
1697
+ if (now - mtimeMs <= staleMs) continue;
1698
+ try { unlinkSync(file); } catch { /* a later fetch finds it again */ }
1699
+ }
1700
+ }
1701
+
1702
+ /** A failed fetch as E_REMOTE_UNREADABLE: a failed write of the cache says where and at which stage. */
1703
+ const fetchFailure = (repo, ref, error, commit) => unreadable(ref, error, { commit, ...(classifyRemoteFailure(error) === "cache" ? { cacheDir: repo.dir, stage: "fetch" } : {}) });
1704
+
1705
+ /** `git fetch` from the remote into the cache (args start at the subcommand and name the remote "origin"),
1706
+ * made under the cache's write lock: a lost on-disk `.lock` race is retried, a timeout names the fetch
1707
+ * (`what`) and how long it ran, any other failure is E_REMOTE_UNREADABLE (`raw`: the git error itself, for
1708
+ * a caller that reads it). Every fetch first removes the temporary files earlier fetches left in the object
1709
+ * store, by their age (removeStaleTemporaryFiles). → { stdout, stderr } */
1368
1710
  async function fetchInto(repo, ref, args, { what, commit, input, raw = false } = {}) {
1369
1711
  const started = Date.now();
1712
+ removeStaleTemporaryFiles(repo);
1370
1713
  let lastError;
1371
1714
  try { return await cacheGit(repo, ["-c", `remote.origin.url=${ref.url}`, ...args], { timeout: repo.session?.fetchTimeoutMs ?? GIT_FETCH_TIMEOUT_MS, ...(input !== undefined ? { input } : {}) }); }
1372
1715
  catch (error) { lastError = error; }
1373
1716
  if (lastError?.timedOut) {
1374
1717
  const elapsedMs = Date.now() - started;
1375
- throw fail("E_REMOTE_UNREADABLE", `cannot read remote ${ref.url} (timeout): git fetch of ${what} timed out after ${Math.round(elapsedMs / 1000)} s`,
1718
+ throw fail("E_REMOTE_UNREADABLE", `cannot read remote ${redactUrl(ref.url, null, { reference: true })} (timeout): git fetch of ${what} timed out after ${Math.round(elapsedMs / 1000)} s`,
1376
1719
  { url: ref.url, key: ref.key, reason: "timeout", commit, operation: "fetch", elapsedMs });
1377
1720
  }
1378
- throw raw ? lastError : unreadable(ref, lastError, { commit, ...(classifyRemoteFailure(lastError) === "cache" ? { cacheDir: repo.dir, stage: "fetch" } : {}) });
1721
+ throw raw ? lastError : fetchFailure(repo, ref, lastError, commit);
1379
1722
  }
1380
1723
 
1381
1724
  /** The sizes of `oids` in the cache, one `cat-file --batch-check`: → Map oid → size, null when the cache lacks it. */
@@ -1419,14 +1762,14 @@ async function ensureBlobs(repo, ref, commit, entries) {
1419
1762
  { what, commit, input: wanted.map((o) => `${o}\n`).join(""), raw: true });
1420
1763
  } catch (error) {
1421
1764
  if (typeof error?.code === "string" && error.code.startsWith("E_")) throw error;
1422
- if (!isRefusedWant(error)) throw unreadable(ref, error, { commit, ...(classifyRemoteFailure(error) === "cache" ? { cacheDir: repo.dir, stage: "fetch" } : {}) });
1765
+ if (!isRefusedWant(error)) throw fetchFailure(repo, ref, error, commit);
1423
1766
  await refetch();
1424
1767
  await recordFullFetches(repo, ref);
1425
1768
  }
1426
1769
  }
1427
1770
  sizes = await blobSizes(repo, oids);
1428
1771
  const still = oids.find((o) => sizes.get(o) === null);
1429
- if (still) throw fail("E_REMOTE_UNREADABLE", `cannot read remote ${ref.url} (not-found): blob ${still} at ${commit} was not fetched`, { url: ref.url, key: ref.key, reason: "not-found", commit, oid: still });
1772
+ if (still) throw fail("E_REMOTE_UNREADABLE", `cannot read remote ${redactUrl(ref.url, null, { reference: true })} (not-found): blob ${still} at ${commit} was not fetched`, { url: ref.url, key: ref.key, reason: "not-found", commit, oid: still });
1430
1773
  });
1431
1774
  for (const e of unknown) e.size = sizes.get(e.oid);
1432
1775
  });
@@ -1437,7 +1780,7 @@ async function ensureBlobs(repo, ref, commit, entries) {
1437
1780
  // ---------------------------------------------------------------------------
1438
1781
 
1439
1782
  function requireCommit(commit) {
1440
- if (typeof commit !== "string" || !OID_RE.test(commit)) throw fail("E_REPO_REF", "commit must be a full 40-hex OID", { commit });
1783
+ if (typeof commit !== "string" || !OID_RE.test(commit)) throw fail("E_REPO_REF", "commit must be a full 40-hex OID", { commit }, { rejected: ["commit"] });
1441
1784
  return commit;
1442
1785
  }
1443
1786
 
@@ -1479,7 +1822,7 @@ function resolveAt(parsed, at) {
1479
1822
  */
1480
1823
  export async function observeRemote(refText, { at, ...options } = {}) {
1481
1824
  const ref = parseRepoRef(refText, options);
1482
- if (at !== undefined && at !== null && typeof at !== "string") throw fail("E_REPO_REF", "at must be a string (full OID, tag or branch name)", { at });
1825
+ if (at !== undefined && at !== null && typeof at !== "string") throw fail("E_REPO_REF", "at must be a string (full OID, tag or branch name)", { at }, { rejected: ["at"] });
1483
1826
  if (typeof at === "string" && OID_RE.test(at)) {
1484
1827
  // A tag OID is accepted here; the commit recorded is the one it peels to (M4).
1485
1828
  const { commit } = await ensureCommit(ref, at, options);
@@ -1498,7 +1841,7 @@ export async function observeRemote(refText, { at, ...options } = {}) {
1498
1841
  /** The `ls-remote` argv of a head observation (`at`: HEAD, a tag or a branch; never a full OID). */
1499
1842
  function lsRemoteArgs(ref, at) {
1500
1843
  const wantHead = isHeadAt(at);
1501
- if (!wantHead && AT_BAD_RE.test(at)) throw fail("E_REPO_REF", `at must be a full OID or a plain tag/branch name, got ${JSON.stringify(at)}`, { at });
1844
+ if (!wantHead && AT_BAD_RE.test(at)) throw fail("E_REPO_REF", ({ at }) => `at must be a full OID or a plain tag/branch name, got ${JSON.stringify(at)}`, { at }, { rejected: ["at"] });
1502
1845
  const args = ["ls-remote", "--symref", ref.url];
1503
1846
  if (wantHead) args.push("HEAD");
1504
1847
  else args.push(`refs/tags/${at}`, `refs/tags/${at}^{}`, `refs/heads/${at}`, at);
@@ -1649,7 +1992,7 @@ async function observeLive(ref, args, at, options) {
1649
1992
  const run = (argv, extra = {}) => sessionExec(exec, session, argv, { timeout: GIT_TIMEOUT_MS, ...(signal ? { signal } : {}), ...extra });
1650
1993
  const root = cacheRootOf(options);
1651
1994
  const now = () => (session ? session.now() : Date.now());
1652
- const url = redactUrl(ref.url);
1995
+ const url = redactUrl(ref.url, null, { reference: true });
1653
1996
  const say = (notice) => { if (session && !session.notices.includes(notice)) session.notices.push(notice); };
1654
1997
  let out = null, retried = null;
1655
1998
  const v0 = isHeadAt(at) && !lsRemoteV2Recorded(root, ref, now()) && !(await protocolPinned(exec, session));
@@ -1683,8 +2026,8 @@ async function observeLive(ref, args, at, options) {
1683
2026
  }
1684
2027
  const parsed = parseLsRemote(out.stdout);
1685
2028
  const hit = resolveAt(parsed, at);
1686
- if (!hit) throw fail("E_REMOTE_UNREADABLE", `remote ${ref.url} has no ref matching ${at ?? "HEAD"}`, { url: ref.url, key: ref.key, reason: "not-found", at: at ?? null });
1687
- if (!OID_RE.test(hit.commit)) throw fail("E_REMOTE_UNREADABLE", `remote ${ref.url} returned a non-OID for ${at ?? "HEAD"}`, { url: ref.url, key: ref.key, reason: "not-found", at: at ?? null });
2029
+ if (!hit) throw fail("E_REMOTE_UNREADABLE", `remote ${redactUrl(ref.url, null, { reference: true })} has no ref matching ${at ?? "HEAD"}`, { url: ref.url, key: ref.key, reason: "not-found", at: at ?? null });
2030
+ if (!OID_RE.test(hit.commit)) throw fail("E_REMOTE_UNREADABLE", `remote ${redactUrl(ref.url, null, { reference: true })} returned a non-OID for ${at ?? "HEAD"}`, { url: ref.url, key: ref.key, reason: "not-found", at: at ?? null });
1688
2031
  const { commit } = await ensureCommit(ref, hit.commit, options);
1689
2032
  if (retried) say(`${url} failed under protocol v0 (${retried}); observed with protocol v2`);
1690
2033
  return { key: ref.key, url: ref.url, commit, ref: hit.ref, observedAt: new Date().toISOString() };
@@ -1698,12 +2041,12 @@ const formatBytes = (n) => (n % (1024 * 1024) === 0 ? `${n / (1024 * 1024)} MiB`
1698
2041
  function normalizeTreePath(path, { allowRoot }) {
1699
2042
  if (path === undefined || path === null || path === "" || path === ".") {
1700
2043
  if (allowRoot) return "";
1701
- throw fail("E_REPO_REF", "path must name a file, not the tree root", { path });
2044
+ throw fail("E_REPO_REF", "path must name a file, not the tree root", { path }, { rejected: ["path"] });
1702
2045
  }
1703
- if (typeof path !== "string") throw fail("E_REPO_REF", "path must be a string", { path });
2046
+ if (typeof path !== "string") throw fail("E_REPO_REF", "path must be a string", { path }, { rejected: ["path"] });
1704
2047
  const parts = path.replace(/\\/g, "/").split("/").filter((p) => p !== "" && p !== ".");
1705
- if (parts.length === 0) { if (allowRoot) return ""; throw fail("E_REPO_REF", "path must name a file", { path }); }
1706
- if (parts.some((p) => p === "..")) throw fail("E_REPO_REF", "path must be relative and must not escape the tree", { path });
2048
+ if (parts.length === 0) { if (allowRoot) return ""; throw fail("E_REPO_REF", "path must name a file", { path }, { rejected: ["path"] }); }
2049
+ if (parts.some((p) => p === "..")) throw fail("E_REPO_REF", "path must be relative and must not escape the tree", { path }, { rejected: ["path"] });
1707
2050
  return parts.join("/");
1708
2051
  }
1709
2052
 
@@ -1783,12 +2126,13 @@ async function lsTree(repo, spec, { flags = [], path, ref, commit, maxBuffer = 6
1783
2126
  * repository is marked damaged), else "unknown". An oats error passes through as itself. */
1784
2127
  function listingUnreadable(error, { repo, spec, path, ref, commit }) {
1785
2128
  if (typeof error?.code === "string" && error.code.startsWith("E_")) return error;
1786
- const text = stderrText(error).toLowerCase();
1787
- const missingObject = /could not read [0-9a-f]{40,64}|missing (?:tree|blob|object) [0-9a-f]{40,64}|bad tree object/.test(text);
2129
+ const text = stderrText(error);
2130
+ const missingObject = /could not read [0-9a-f]{40,64}|missing (?:tree|blob|object) [0-9a-f]{40,64}|bad tree object/.test(text.toLowerCase());
1788
2131
  if (missingObject) markCacheDamaged(repo, `${spec}: ${text.trim().split("\n")[0]}`);
1789
2132
  const killed = !error?.timedOut && !error?.overflowed && typeof error?.signal === "string" && error.signal !== "";
1790
2133
  const reason = error?.timedOut ? "timeout" : killed ? "killed" : missingObject ? "cache" : "unknown";
1791
- const why = error?.overflowed ? "listing exceeded the output budget" : killed ? `git was killed (signal ${error.signal})` : (text.trim().split("\n")[0] || error?.code || error?.message || "git ls-tree failed");
2134
+ // Decide on the original first line and operation URL; use Node's message only when Git said nothing.
2135
+ const why = error?.overflowed ? "listing exceeded the output budget" : killed ? `git was killed (signal ${error.signal})` : (scrubGitLine(text.split("\n")[0], ref?.url) || error?.code || scrubGitLine(error?.message, ref?.url) || "git ls-tree failed");
1792
2136
  return fail("E_REMOTE_UNREADABLE", `cannot list ${spec}${path !== undefined ? ` -- ${path}` : ""} in ${ref?.key ?? repo.dir} (${reason}: ${why})`, { url: ref?.url ?? null, key: ref?.key ?? null, reason, commit: commit ?? null, spec, path: path ?? null, cause: error?.code ?? null, overflowed: error?.overflowed === true, ...(killed ? { signal: error.signal } : {}) });
1793
2137
  }
1794
2138
 
@@ -2058,7 +2402,7 @@ export function browseUrl(key, commit, path = null) {
2058
2402
  export async function listRemoteTree(refText, commitArg, dir, { depth = 2, ...options } = {}) {
2059
2403
  const ref = parseRepoRef(refText, options);
2060
2404
  requireCommit(commitArg);
2061
- if (!Number.isInteger(depth) || depth < 1) throw fail("E_REPO_REF", "depth must be a positive integer", { depth });
2405
+ if (!Number.isInteger(depth) || depth < 1) throw fail("E_REPO_REF", "depth must be a positive integer", { depth }, { rejected: ["depth"] });
2062
2406
  const rel = normalizeTreePath(dir, { allowRoot: true });
2063
2407
  const { repo, commit } = await ensureCommit(ref, commitArg, options);
2064
2408
  const spec = rel ? `${commit}:${rel}` : commit;
@@ -2096,7 +2440,7 @@ export async function listRemoteTree(refText, commitArg, dir, { depth = 2, ...op
2096
2440
  export async function listRemoteFiles(refText, commitArg, dir, { limit, ...options } = {}) {
2097
2441
  const ref = parseRepoRef(refText, options);
2098
2442
  requireCommit(commitArg);
2099
- if (limit !== undefined && (!Number.isInteger(limit) || limit < 0)) throw fail("E_REPO_REF", "limit must be a non-negative integer", { limit });
2443
+ if (limit !== undefined && (!Number.isInteger(limit) || limit < 0)) throw fail("E_REPO_REF", "limit must be a non-negative integer", { limit }, { rejected: ["limit"] });
2100
2444
  const rel = normalizeTreePath(dir, { allowRoot: true });
2101
2445
  const none = { files: [], total: 0 };
2102
2446
  return memoAtCommit(ref, commitArg, `files\0${rel}\0${limit ?? "all"}`, async () => {
@@ -2163,7 +2507,7 @@ function posixNormalize(p) {
2163
2507
  export const OATS_ALIAS_SYMLINK = (relPath) => typeof relPath === "string" && (relPath === "CLAUDE.md" || relPath.endsWith("/CLAUDE.md"));
2164
2508
 
2165
2509
  export function contentDigest(dir, { allowSymlinks = null, omit = null } = {}) {
2166
- if (typeof dir !== "string" || !isAbsolute(dir)) throw fail("E_REPO_REF", "contentDigest requires an absolute directory path", { path: dir });
2510
+ if (typeof dir !== "string" || !isAbsolute(dir)) throw fail("E_REPO_REF", "contentDigest requires an absolute directory path", { path: dir }, { rejected: ["path"] });
2167
2511
  let st;
2168
2512
  try { st = lstatSync(dir); } catch { throw fail("E_REMOTE_PATH_MISSING", `${dir} does not exist`, { path: dir }); }
2169
2513
  if (!st.isDirectory()) throw fail("E_REMOTE_PATH_MISSING", `${dir} is not a directory`, { path: dir });
@@ -2206,7 +2550,7 @@ export async function fetchRemoteTree(refText, commitArg, dir, destDir, options
2206
2550
  const ref = parseRepoRef(refText, options);
2207
2551
  requireCommit(commitArg);
2208
2552
  const rel = normalizeTreePath(dir, { allowRoot: true });
2209
- if (typeof destDir !== "string" || !isAbsolute(destDir)) throw fail("E_REPO_REF", "destDir must be an absolute path", { destDir });
2553
+ if (typeof destDir !== "string" || !isAbsolute(destDir)) throw fail("E_REPO_REF", "destDir must be an absolute path", { destDir }, { rejected: ["destDir"] });
2210
2554
  const dest = resolve(destDir);
2211
2555
  let destStat = null;
2212
2556
  try { destStat = lstatSync(dest); } catch {}