@awebai/oats 0.53.0 → 0.55.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 (42) hide show
  1. package/bin/oats.mjs +17 -7
  2. package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
  3. package/docs/desktop-cli-api.md +44 -12
  4. package/docs/implementation.md +12 -4
  5. package/docs/integrations.md +2 -2
  6. package/docs/knowledge.md +14 -2
  7. package/docs/official-catalog.md +5 -5
  8. package/docs/packages.md +14 -14
  9. package/docs/release-notes/v0.53.0.md +14 -0
  10. package/docs/release-notes/v0.54.0.md +142 -0
  11. package/docs/release-notes/v0.55.0.md +158 -0
  12. package/docs/servers.md +13 -3
  13. package/docs/souls-and-instances.md +2 -1
  14. package/docs/upgrading.md +14 -2
  15. package/docs/workspaces.md +122 -2
  16. package/lib/packages.mjs +5 -1
  17. package/lib/remote.mjs +255 -76
  18. package/lib/servers.mjs +82 -34
  19. package/lib/workspace.mjs +27 -9
  20. package/package-catalog.json +4 -4
  21. package/package.json +1 -1
  22. package/packages/client/cli-locator.mjs +2 -2
  23. package/packages/client/workspace-views.mjs +4 -3
  24. package/packages/record/README.md +54 -13
  25. package/packages/record/bin/capture.mjs +107 -53
  26. package/packages/record/docs/capture-service.md +193 -0
  27. package/packages/record/docs/capture-status.schema.json +100 -0
  28. package/packages/record/lib/capture-aw.mjs +96 -94
  29. package/packages/record/lib/capture-cc.mjs +109 -187
  30. package/packages/record/lib/capture-db-reader.mjs +39 -0
  31. package/packages/record/lib/capture-issues.mjs +64 -0
  32. package/packages/record/lib/capture-scratch.mjs +111 -0
  33. package/packages/record/lib/capture-state.mjs +105 -0
  34. package/packages/record/lib/derived-state.mjs +60 -0
  35. package/packages/record/lib/formats.mjs +31 -31
  36. package/packages/record/lib/index-db.mjs +74 -34
  37. package/packages/record/lib/receipt-summary.mjs +62 -0
  38. package/packages/record/lib/session-snapshot.mjs +56 -1
  39. package/packages/record/lib/sqlite-rows.mjs +14 -0
  40. package/packages/record/lib/store.mjs +122 -43
  41. package/packages/record/lib/transcript-prefix.mjs +40 -0
  42. package/skills/oats-getting-started/SKILL.md +8 -2
package/lib/remote.mjs CHANGED
@@ -73,8 +73,9 @@
73
73
  * UNKNOWN vs NETWORK (awebai/oats#1059): a failed git call whose text shows nothing the
74
74
  * kernel recognises is `unknown`, never `network`: `network` is what the text shows to
75
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 one scrub
77
- * (scrubGitLine): one line, bounded, no control characters, no url's user information.
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.
78
79
  *
79
80
  * TREE SAFETY: every entry name git reports is validated BEFORE anything touches
80
81
  * the disk. A component that is empty, `.`, `..`, `.git` (any case) or contains
@@ -210,9 +211,27 @@ const AT_BAD_RE = /^[-/]|\/$|\.\.|[\s~^:?*[\\\x00-\x1f\x7f]|@\{|\/\.|^\.|\.lock(
210
211
  const BAD_COMPONENT_RE = /^(?:|\.|\.\.|\.git)$/i;
211
212
 
212
213
  /** oatsError with the details reachable as BOTH e.provenance (today's field) and e.details. */
213
- function fail(code, message, details) {
214
- const e = oatsError(code, message, details);
215
- 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;
216
235
  return e;
217
236
  }
218
237
 
@@ -247,7 +266,7 @@ function hostedRef(host, rawPath, text, { fetchUrl = null, transport = "https" }
247
266
  function transportOf(options) {
248
267
  const t = options?.transport;
249
268
  if (t === undefined || t === null) return "https";
250
- 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"] });
251
270
  return t;
252
271
  }
253
272
 
@@ -285,7 +304,12 @@ export function parseRepoRef(text, options = undefined) {
285
304
  try { return localRef(fileURLToPath(ref)); } catch { throw fail("E_REPO_REF", `invalid file URL: ${ref}`, { ref }); }
286
305
  }
287
306
  if (isAbsolute(ref)) return localRef(ref);
288
- 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 });
289
313
  }
290
314
 
291
315
  // ---------------------------------------------------------------------------
@@ -467,46 +491,26 @@ export const GIT_LINE_MAX = 300;
467
491
  const REFUSED_TEXT_ALL = new RegExp(REFUSED_TEXT.source, "gu");
468
492
  /** A terminal's control sequence (a colour, a cursor move), which goes whole and not only its escape character. */
469
493
  const ANSI_SEQUENCE_RE = /\x1b\[[0-9;?]*[ -\/]*[@-~]/g;
470
- /** The user information of a url, wherever a text holds one: `scheme://user:secret@host` → `scheme://host`. */
471
- const URL_USERINFO_RE = /\b([a-z][a-z0-9+.-]*:\/\/)[^\s\/]*@/gi;
472
- /**
473
- * What a line about the fetch of `url` must not repeat, by the module's own rule of a url that carries a
474
- * secret (CREDENTIAL_URL_RE): the user information, as written and decoded, and with it
475
- * - on http(s), each of its parts: there the user alone is a secret (a forge token is put in a url as
476
- * `https://<token>@host`, or as the user before a fixed password), so the whole of it goes whether or
477
- * not it holds a colon;
478
- * - on another scheme, its password alone, and nothing where it holds no colon: a user name alone
479
- * (`ssh://git@host`) is no secret and stays.
480
- * The longest first, so that no part of a secret is left by removing a shorter one inside it. The cost of
481
- * removing each part: a user that is a common word goes from git's line wherever the line repeats it, and a
482
- * mangled line is better than a printed token.
483
- */
484
- function urlSecrets(url) {
485
- const m = typeof url === "string" ? /^([a-z][a-z0-9+.-]*):\/\/([^\s\/]*)@/i.exec(url) : null;
486
- if (!m) return [];
487
- const http = /^https?$/i.test(m[1]), info = m[2], colon = info.indexOf(":");
488
- if (colon < 0 && !http) return [];
489
- const parts = colon < 0 ? [] : http ? [info.slice(0, colon), info.slice(colon + 1)] : [info.slice(colon + 1)];
490
- const forms = (text) => { try { return [text, decodeURIComponent(text)]; } catch { return [text]; } };
491
- return [...new Set([info, ...parts].flatMap(forms))].filter(Boolean).sort((a, b) => b.length - a.length);
492
- }
493
494
  /**
494
495
  * One line of git's own words, made fit to print in a message (a failure message is an output channel:
495
496
  * the fetch url is on git's command line, may carry credentials, and git or its transport can echo it).
496
- * The user information of every url in it is removed, and that of `url` (the fetch url) wherever it
497
- * appears; a terminal's control sequences, control characters and the other characters the kernel never
498
- * prints (lib/refused-text.mjs) are removed, runs of white space become one space, and the line is cut to
499
- * GIT_LINE_MAX characters. "" when nothing is left.
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 "".
500
501
  */
501
502
  export function scrubGitLine(line, url = null) {
502
- let text = String(line ?? "").replace(URL_USERINFO_RE, "$1");
503
- for (const secret of urlSecrets(url)) text = text.split(secret).join("");
503
+ const original = String(line ?? "");
504
+ if (!original.trim()) return "";
505
+ const text = redactUrl(original, url);
504
506
  const points = [...text.replace(ANSI_SEQUENCE_RE, "").replace(/\s+/g, " ").replace(REFUSED_TEXT_ALL, "").trim()];
505
507
  return points.length > GIT_LINE_MAX ? `${points.slice(0, GIT_LINE_MAX - 1).join("")}…` : points.join("");
506
508
  }
507
509
  /** The last line git wrote that says anything (a progress line ends with a carriage return), scrubbed. */
508
510
  function gitLastLine(error, url) {
509
- const lines = stderrText(error).split(/[\r\n]+/).map((line) => scrubGitLine(line, url)).filter(Boolean);
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);
510
514
  return lines.length ? lines[lines.length - 1] : "";
511
515
  }
512
516
 
@@ -523,16 +527,16 @@ export function keychainHint({ platform = process.platform, stdinIsTTY = process
523
527
  }
524
528
 
525
529
  /** A failed git call as E_REMOTE_UNREADABLE, by its reason (classifyRemoteFailure). The message prints the
526
- * url as every message of the cache does, without its user information (redactUrl); `details.url` is the
527
- * url as written. A failure the kernel cannot classify (`unknown`) carries git's own last line, scrubbed
528
- * (scrubGitLine), so that the message shows what the kernel could not name; with no line, an output over
529
- * its budget is said, and otherwise the message ends at the reason. */
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. */
530
534
  function unreadable(ref, error, extra = {}) {
531
535
  const reason = classifyRemoteFailure(error), killed = reason === "killed";
532
536
  if (reason === "cache") return cacheFailure(ref, error, extra);
533
537
  const hint = keychainHint({ reason });
534
538
  const said = reason === "unknown" ? gitLastLine(error, ref.url) || (error?.overflowed === true ? "git's output exceeded its budget" : "") : "";
535
- return fail("E_REMOTE_UNREADABLE", `cannot read remote ${redactUrl(ref.url)} (${reason})${killed ? `: git was killed (signal ${error.signal})` : ""}${said ? `: ${said}` : ""}${hint ? `: ${KEYCHAIN_REMEDY}` : ""}`,
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}` : ""}`,
536
540
  { url: ref.url, key: ref.key, reason, ...(killed ? { signal: error.signal } : {}), ...(hint ? { hint, remedy: KEYCHAIN_REMEDY } : {}), ...extra });
537
541
  }
538
542
 
@@ -554,9 +558,10 @@ const isLocalWriteFailure = (error) => /cannot open '[^']+': |unable to create t
554
558
 
555
559
  /** A write to the local cache repo failed — reason "cache" (a timeout stays "timeout"), never "network" — with a
556
560
  * message that says what to do: a lock still held names its file, safe to remove once no oats process runs;
557
- * 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). */
558
563
  function cacheFailure(ref, error, extra = {}) {
559
- const url = redactUrl(ref.url);
564
+ const url = redactUrl(ref.url, null, { reference: true });
560
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 });
561
566
  const where = extra.cacheDir ? ` at ${extra.cacheDir}` : "";
562
567
  const lock = isLockRace(error) ? lockFileOf(error, extra.cacheDir) : null;
@@ -565,7 +570,7 @@ function cacheFailure(ref, error, extra = {}) {
565
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`,
566
571
  { url: ref.url, key: ref.key, reason: "cache", ...extra, ...(lock ? { lock } : {}) });
567
572
  }
568
- 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);
569
574
  const check = isLocalWriteFailure(error) ? `; check that ${extra.cacheDir ?? "the cache"} is writable by this user and its disk has room` : "";
570
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 });
571
576
  }
@@ -661,7 +666,7 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
661
666
  const signal = session?.signal;
662
667
  const lock = cacheWriteLockOf(dir);
663
668
  const owner = { pid: process.pid, token: randomBytes(12).toString("hex"), startedAt: new Date().toISOString() };
664
- const url = redactUrl(ref.url);
669
+ const url = redactUrl(ref.url, null, { reference: true });
665
670
  const refuse = (message, extra = {}) => fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url} at ${dir} (cache, ${stage}): ${message}`,
666
671
  { url: ref.url, key: ref.key, reason: "cache", stage, cacheDir: dir, lock, ...extra });
667
672
  try { mkdirSync(dirname(lock), { recursive: true, mode: 0o700 }); } catch (error) { throw refuse(`cannot create ${dirname(lock)} (${error.code ?? error.message})`); }
@@ -769,7 +774,7 @@ async function cacheGit(repo, args, opts = {}) {
769
774
  catch (error) {
770
775
  const lockFile = isLockRace(error) ? lockFileOf(error, repo.dir) : null;
771
776
  if (!lockFile || !reclaimGitLock(repo, lockFile)) throw error;
772
- 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 }));
773
778
  return await run();
774
779
  }
775
780
  }
@@ -778,10 +783,184 @@ const sha256 = (text) => createHash("sha256").update(text).digest("hex");
778
783
  const cacheRootOf = (options) => options.cacheDir ?? defaultCacheRoot();
779
784
  const cacheDirOf = (root, ref) => join(root, sha256(ref.key));
780
785
 
781
- /** A url without its userinfo (`ssh://user:secret@host/…` → `ssh://host/…`): what may be written to disk,
782
- * and how a message prints a url. The one function for it. */
783
- function redactUrl(url) {
784
- 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;
785
964
  }
786
965
 
787
966
  function repoHandle(dir, exec, session) {
@@ -817,7 +996,7 @@ async function initCacheRepo(ref, dir, exec, session = null) {
817
996
  try {
818
997
  try { mkdirSync(tmp, { recursive: true, mode: 0o700 }); } catch (error) { throw failInit(error); }
819
998
  try { await sessionExec(exec, session, ["init", "-q", "--bare", tmp]); } catch (error) { throw failInit(error); }
820
- 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 {}
821
1000
  const deadline = Date.now() + HALF_INIT_WAIT_MS;
822
1001
  for (;;) {
823
1002
  try { renameSync(tmp, dir); return; } // replaces nothing, or an EMPTY directory
@@ -1299,7 +1478,7 @@ async function ensureCommit(ref, oid, options) {
1299
1478
  if (!commit) {
1300
1479
  // The peel answered: the object is missing or not a commit (a peel the deadline ended was thrown above).
1301
1480
  const type = await asReadTimeout(repo, objectType(repo, oid));
1302
- 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 });
1303
1482
  }
1304
1483
  await writePin(repo, ref, pinRef(commit), commit, commit);
1305
1484
  if (commit !== oid) await writePin(repo, ref, `refs/oats/tags/${oid}`, oid, commit);
@@ -1372,14 +1551,14 @@ async function writeConfig(repo, ref, key, value) {
1372
1551
 
1373
1552
  /** This cache fetches whole trees from now on (its server cannot serve partial fetches, or this git cannot keep
1374
1553
  * a partial cache): recorded, and said once (the session's notices; the CLI prints them when the command ends). */
1375
- 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`) {
1376
1555
  await writeConfig(repo, ref, "oats.fetch", "full");
1377
- repo.session?.notices.push(notice);
1556
+ repo.session?.notices.push(redactUrl(notice, ref.url, { known: false }));
1378
1557
  return "full";
1379
1558
  }
1380
1559
 
1381
1560
  const olderGitNotice = (version, ref) =>
1382
- `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 })}`;
1383
1562
 
1384
1563
  /** `git --version` of the git `exec` runs, asked once per exec: → { text: "2.54.0", major, minor } | null.
1385
1564
  * `opts` (a timeout, a signal) go to the call that asks. A call that timed out says nothing about this git:
@@ -1536,7 +1715,7 @@ async function fetchInto(repo, ref, args, { what, commit, input, raw = false } =
1536
1715
  catch (error) { lastError = error; }
1537
1716
  if (lastError?.timedOut) {
1538
1717
  const elapsedMs = Date.now() - started;
1539
- 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`,
1540
1719
  { url: ref.url, key: ref.key, reason: "timeout", commit, operation: "fetch", elapsedMs });
1541
1720
  }
1542
1721
  throw raw ? lastError : fetchFailure(repo, ref, lastError, commit);
@@ -1590,7 +1769,7 @@ async function ensureBlobs(repo, ref, commit, entries) {
1590
1769
  }
1591
1770
  sizes = await blobSizes(repo, oids);
1592
1771
  const still = oids.find((o) => sizes.get(o) === null);
1593
- 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 });
1594
1773
  });
1595
1774
  for (const e of unknown) e.size = sizes.get(e.oid);
1596
1775
  });
@@ -1601,7 +1780,7 @@ async function ensureBlobs(repo, ref, commit, entries) {
1601
1780
  // ---------------------------------------------------------------------------
1602
1781
 
1603
1782
  function requireCommit(commit) {
1604
- 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"] });
1605
1784
  return commit;
1606
1785
  }
1607
1786
 
@@ -1643,7 +1822,7 @@ function resolveAt(parsed, at) {
1643
1822
  */
1644
1823
  export async function observeRemote(refText, { at, ...options } = {}) {
1645
1824
  const ref = parseRepoRef(refText, options);
1646
- 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"] });
1647
1826
  if (typeof at === "string" && OID_RE.test(at)) {
1648
1827
  // A tag OID is accepted here; the commit recorded is the one it peels to (M4).
1649
1828
  const { commit } = await ensureCommit(ref, at, options);
@@ -1662,7 +1841,7 @@ export async function observeRemote(refText, { at, ...options } = {}) {
1662
1841
  /** The `ls-remote` argv of a head observation (`at`: HEAD, a tag or a branch; never a full OID). */
1663
1842
  function lsRemoteArgs(ref, at) {
1664
1843
  const wantHead = isHeadAt(at);
1665
- 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"] });
1666
1845
  const args = ["ls-remote", "--symref", ref.url];
1667
1846
  if (wantHead) args.push("HEAD");
1668
1847
  else args.push(`refs/tags/${at}`, `refs/tags/${at}^{}`, `refs/heads/${at}`, at);
@@ -1813,7 +1992,7 @@ async function observeLive(ref, args, at, options) {
1813
1992
  const run = (argv, extra = {}) => sessionExec(exec, session, argv, { timeout: GIT_TIMEOUT_MS, ...(signal ? { signal } : {}), ...extra });
1814
1993
  const root = cacheRootOf(options);
1815
1994
  const now = () => (session ? session.now() : Date.now());
1816
- const url = redactUrl(ref.url);
1995
+ const url = redactUrl(ref.url, null, { reference: true });
1817
1996
  const say = (notice) => { if (session && !session.notices.includes(notice)) session.notices.push(notice); };
1818
1997
  let out = null, retried = null;
1819
1998
  const v0 = isHeadAt(at) && !lsRemoteV2Recorded(root, ref, now()) && !(await protocolPinned(exec, session));
@@ -1847,8 +2026,8 @@ async function observeLive(ref, args, at, options) {
1847
2026
  }
1848
2027
  const parsed = parseLsRemote(out.stdout);
1849
2028
  const hit = resolveAt(parsed, at);
1850
- 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 });
1851
- 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 });
1852
2031
  const { commit } = await ensureCommit(ref, hit.commit, options);
1853
2032
  if (retried) say(`${url} failed under protocol v0 (${retried}); observed with protocol v2`);
1854
2033
  return { key: ref.key, url: ref.url, commit, ref: hit.ref, observedAt: new Date().toISOString() };
@@ -1862,12 +2041,12 @@ const formatBytes = (n) => (n % (1024 * 1024) === 0 ? `${n / (1024 * 1024)} MiB`
1862
2041
  function normalizeTreePath(path, { allowRoot }) {
1863
2042
  if (path === undefined || path === null || path === "" || path === ".") {
1864
2043
  if (allowRoot) return "";
1865
- 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"] });
1866
2045
  }
1867
- 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"] });
1868
2047
  const parts = path.replace(/\\/g, "/").split("/").filter((p) => p !== "" && p !== ".");
1869
- if (parts.length === 0) { if (allowRoot) return ""; throw fail("E_REPO_REF", "path must name a file", { path }); }
1870
- 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"] });
1871
2050
  return parts.join("/");
1872
2051
  }
1873
2052
 
@@ -1947,13 +2126,13 @@ async function lsTree(repo, spec, { flags = [], path, ref, commit, maxBuffer = 6
1947
2126
  * repository is marked damaged), else "unknown". An oats error passes through as itself. */
1948
2127
  function listingUnreadable(error, { repo, spec, path, ref, commit }) {
1949
2128
  if (typeof error?.code === "string" && error.code.startsWith("E_")) return error;
1950
- const text = stderrText(error).toLowerCase();
1951
- 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());
1952
2131
  if (missingObject) markCacheDamaged(repo, `${spec}: ${text.trim().split("\n")[0]}`);
1953
2132
  const killed = !error?.timedOut && !error?.overflowed && typeof error?.signal === "string" && error.signal !== "";
1954
2133
  const reason = error?.timedOut ? "timeout" : killed ? "killed" : missingObject ? "cache" : "unknown";
1955
- // git's first line, as before, through the one scrub (scrubGitLine); a message of Node's when git said nothing.
1956
- const why = error?.overflowed ? "listing exceeded the output budget" : killed ? `git was killed (signal ${error.signal})` : (scrubGitLine(text.trim().split("\n")[0], ref?.url) || error?.code || scrubGitLine(error?.message, ref?.url) || "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");
1957
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 } : {}) });
1958
2137
  }
1959
2138
 
@@ -2223,7 +2402,7 @@ export function browseUrl(key, commit, path = null) {
2223
2402
  export async function listRemoteTree(refText, commitArg, dir, { depth = 2, ...options } = {}) {
2224
2403
  const ref = parseRepoRef(refText, options);
2225
2404
  requireCommit(commitArg);
2226
- 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"] });
2227
2406
  const rel = normalizeTreePath(dir, { allowRoot: true });
2228
2407
  const { repo, commit } = await ensureCommit(ref, commitArg, options);
2229
2408
  const spec = rel ? `${commit}:${rel}` : commit;
@@ -2261,7 +2440,7 @@ export async function listRemoteTree(refText, commitArg, dir, { depth = 2, ...op
2261
2440
  export async function listRemoteFiles(refText, commitArg, dir, { limit, ...options } = {}) {
2262
2441
  const ref = parseRepoRef(refText, options);
2263
2442
  requireCommit(commitArg);
2264
- 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"] });
2265
2444
  const rel = normalizeTreePath(dir, { allowRoot: true });
2266
2445
  const none = { files: [], total: 0 };
2267
2446
  return memoAtCommit(ref, commitArg, `files\0${rel}\0${limit ?? "all"}`, async () => {
@@ -2328,7 +2507,7 @@ function posixNormalize(p) {
2328
2507
  export const OATS_ALIAS_SYMLINK = (relPath) => typeof relPath === "string" && (relPath === "CLAUDE.md" || relPath.endsWith("/CLAUDE.md"));
2329
2508
 
2330
2509
  export function contentDigest(dir, { allowSymlinks = null, omit = null } = {}) {
2331
- 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"] });
2332
2511
  let st;
2333
2512
  try { st = lstatSync(dir); } catch { throw fail("E_REMOTE_PATH_MISSING", `${dir} does not exist`, { path: dir }); }
2334
2513
  if (!st.isDirectory()) throw fail("E_REMOTE_PATH_MISSING", `${dir} is not a directory`, { path: dir });
@@ -2371,7 +2550,7 @@ export async function fetchRemoteTree(refText, commitArg, dir, destDir, options
2371
2550
  const ref = parseRepoRef(refText, options);
2372
2551
  requireCommit(commitArg);
2373
2552
  const rel = normalizeTreePath(dir, { allowRoot: true });
2374
- 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"] });
2375
2554
  const dest = resolve(destDir);
2376
2555
  let destStat = null;
2377
2556
  try { destStat = lstatSync(dest); } catch {}