pi-braid 0.40.1 → 0.40.2

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 (84) hide show
  1. package/CONTRIBUTING.md +27 -3
  2. package/README.md +13 -13
  3. package/TOOLS.md +27 -3
  4. package/build-info.json +9 -0
  5. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +9 -0
  6. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +13 -1
  7. package/dist/extensions/cognitive/metacognition/handlers/verify.js +35 -4
  8. package/dist/extensions/core/prompt-builder/inspect.js +9 -3
  9. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +1 -1
  10. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +1 -1
  11. package/dist/extensions/enforcement/handlers/turn-end-handler.js +1 -1
  12. package/dist/extensions/enforcement/self-state-claims.d.ts +1 -1
  13. package/dist/extensions/enforcement/self-state-claims.js +3 -2
  14. package/dist/extensions/manifest.js +2 -2
  15. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +22 -5
  16. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +43 -11
  17. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +174 -50
  18. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +4 -1
  19. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +16 -0
  20. package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +21 -9
  21. package/dist/extensions/memory/scratchpad/format.js +8 -2
  22. package/dist/extensions/memory/scratchpad/index.js +11 -2
  23. package/dist/extensions/memory/session-recall/index.js +19 -6
  24. package/dist/extensions/memory/three-memory-stores/episodes.d.ts +1 -1
  25. package/dist/extensions/memory/three-memory-stores/episodes.js +2 -2
  26. package/dist/extensions/orchestrator/index.js +73 -8
  27. package/dist/extensions/self/health-maintenance/index.js +112 -9
  28. package/dist/lib/config/braid-settings.d.ts +21 -0
  29. package/dist/lib/config/braid-settings.js +36 -0
  30. package/dist/lib/constants/session-thresholds.d.ts +2 -3
  31. package/dist/lib/constants/session-thresholds.js +2 -3
  32. package/dist/lib/enforcement/turn-dedup.d.ts +2 -2
  33. package/dist/lib/enforcement/turn-dedup.js +2 -2
  34. package/dist/lib/harness/index.d.ts +1 -1
  35. package/dist/lib/harness/index.js +1 -1
  36. package/dist/lib/harness/types.d.ts +1 -1
  37. package/dist/lib/harness/types.js +1 -1
  38. package/dist/lib/orchestrator/index.d.ts +2 -2
  39. package/dist/lib/orchestrator/index.js +1 -1
  40. package/dist/lib/orchestrator/workers.d.ts +184 -2
  41. package/dist/lib/orchestrator/workers.js +521 -6
  42. package/dist/lib/utils/injection-tracker.js +1 -1
  43. package/docs/CONTEXT-POLICY.md +13 -5
  44. package/docs/LOCAL_DEV.md +31 -5
  45. package/docs/ROADMAP.md +10 -7
  46. package/docs/SETUP.md +3 -2
  47. package/package.json +11 -8
  48. package/skills/braid-reference/SKILL.md +23 -23
  49. package/skills/release-pipeline/SKILL.md +46 -37
  50. package/skills/subagent-orchestration/SKILL.md +51 -1
  51. package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +14 -1
  52. package/src/extensions/cognitive/metacognition/handlers/verify.ts +39 -5
  53. package/src/extensions/core/prompt-builder/inspect.ts +10 -3
  54. package/src/extensions/enforcement/AGENTS.md +25 -19
  55. package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +1 -1
  56. package/src/extensions/enforcement/handlers/turn-end-handler.ts +1 -1
  57. package/src/extensions/enforcement/self-state-claims.ts +3 -2
  58. package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +6 -3
  59. package/src/extensions/manifest.ts +2 -2
  60. package/src/extensions/memory/AGENTS.md +13 -5
  61. package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +45 -11
  62. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +202 -60
  63. package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +4 -1
  64. package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +16 -0
  65. package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +22 -9
  66. package/src/extensions/memory/scratchpad/format.ts +8 -2
  67. package/src/extensions/memory/scratchpad/index.ts +12 -2
  68. package/src/extensions/memory/session-recall/index.ts +20 -8
  69. package/src/extensions/memory/three-memory-stores/episodes.ts +2 -2
  70. package/src/extensions/orchestrator/index.ts +100 -11
  71. package/src/extensions/scheduling/timer/AGENTS.md +7 -0
  72. package/src/extensions/self/health-maintenance/index.ts +143 -14
  73. package/src/extensions/self/watchdog/AGENTS.md +1 -0
  74. package/src/lib/AGENTS.md +21 -21
  75. package/src/lib/config/braid-settings.ts +74 -0
  76. package/src/lib/constants/session-thresholds.ts +2 -3
  77. package/src/lib/enforcement/turn-dedup.ts +2 -2
  78. package/src/lib/harness/AGENTS.md +1 -1
  79. package/src/lib/harness/index.ts +1 -1
  80. package/src/lib/harness/types.ts +1 -1
  81. package/src/lib/orchestrator/index.ts +26 -0
  82. package/src/lib/orchestrator/workers.ts +705 -7
  83. package/src/lib/utils/AGENTS.md +1 -1
  84. package/src/lib/utils/injection-tracker.ts +1 -1
@@ -19,11 +19,14 @@
19
19
  * Writes are atomic (temp file + rename) with mode 0600. Reads tolerate a
20
20
  * missing or corrupt file by returning an empty registry, like locks.ts.
21
21
  */
22
- import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
22
+ import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
23
23
  import { execFileSync } from "node:child_process";
24
24
  import { dirname, join } from "node:path";
25
- import { getWorkersFilePath, projectsDir } from "../config/braid-paths.js";
25
+ import { braidDir, getWorkersFilePath, projectsDir } from "../config/braid-paths.js";
26
+ import { getCloseGateWellFormedness } from "../config/braid-settings.js";
27
+ import { createLogger } from "../core/logger.js";
26
28
  import { getAllLocks, releaseLock } from "./locks.js";
29
+ const log = createLogger("orchestrator:workers");
27
30
  // ── Constants ──────────────────────────────────────────────────────────────
28
31
  export const WORKER_REGISTRY_VERSION = 1;
29
32
  /**
@@ -466,14 +469,476 @@ function assertGateEvidence(workerId, outcome, gates) {
466
469
  if (!gate || typeof gate !== "object" || Array.isArray(gate)) {
467
470
  throw new Error(`closeWorker: gates[${i}] must be an object carrying cmd and exit (worker ${workerId})`);
468
471
  }
469
- const { cmd, exit } = gate;
472
+ const { cmd, exit, stamp } = gate;
470
473
  if (typeof cmd !== "string" || cmd.trim() === "") {
471
474
  throw new Error(`closeWorker: gates[${i}].cmd must be a non-empty string (worker ${workerId})`);
472
475
  }
473
476
  if (typeof exit !== "number" || !Number.isFinite(exit)) {
474
477
  throw new Error(`closeWorker: gates[${i}].exit must be a number (worker ${workerId})`);
475
478
  }
479
+ // Only the field's type is decided here: whether a stamp is the contract's
480
+ // shape, or is missing from a gate that scanned a population, is the
481
+ // readers' business (the result validator warns; the merge path compares).
482
+ // A non-string stamp cannot be read by either, so it is a shape refusal.
483
+ if (stamp !== undefined && typeof stamp !== "string") {
484
+ throw new Error(`closeWorker: gates[${i}].stamp must be a string (worker ${workerId})`);
485
+ }
486
+ }
487
+ }
488
+ /** One leading `VAR=value` assignment, quoted value or not. */
489
+ const ENV_ASSIGNMENT_RE = /^\s*[A-Za-z_][A-Za-z0-9_]*=(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s]*)(?=\s|$)/;
490
+ /**
491
+ * Strip leading env assignments one at a time. A single-assignment regex
492
+ * applied in a loop, rather than one repeated group: the repeated form
493
+ * backtracks over the whole field when it fails to match, and this runs before
494
+ * any row is judged, on a field a caller controls.
495
+ */
496
+ function stripLeadingEnvAssignments(cmd) {
497
+ let rest = cmd;
498
+ for (;;) {
499
+ const match = rest.match(ENV_ASSIGNMENT_RE);
500
+ if (!match)
501
+ return rest;
502
+ rest = rest.slice(match[0].length);
503
+ }
504
+ }
505
+ /** The first whitespace-delimited token after leading env assignments, or null. */
506
+ export function firstCommandToken(cmd) {
507
+ const rest = stripLeadingEnvAssignments(cmd).trimStart();
508
+ const token = rest.split(/\s+/, 1)[0];
509
+ return token.length > 0 ? token : null;
510
+ }
511
+ function runShell(args) {
512
+ try {
513
+ execFileSync("sh", args, {
514
+ stdio: ["ignore", "ignore", "pipe"],
515
+ encoding: "utf8",
516
+ timeout: 5000,
517
+ });
518
+ return { ok: true };
519
+ }
520
+ catch (error) {
521
+ const e = error;
522
+ if (e.code === "ENOENT")
523
+ return { unavailable: true };
524
+ if (e.code === "ERR_INVALID_ARG_VALUE") {
525
+ const message = error instanceof Error ? error.message : String(error);
526
+ return { ok: false, detail: `sh rejected the field (${message})` };
527
+ }
528
+ if (e.status == null)
529
+ return { unavailable: true };
530
+ const stderr = typeof e.stderr === "string" ? e.stderr : "";
531
+ const line = stderr
532
+ .split("\n")
533
+ .map((candidate) => candidate.trim())
534
+ .find((candidate) => candidate.length > 0);
535
+ return { ok: false, detail: line ?? `sh exited ${String(e.status)}` };
536
+ }
537
+ }
538
+ /**
539
+ * The (c) instrument: a top-level decoration that makes the field more than
540
+ * the command, so the recorded exit cannot be attributed to what the field
541
+ * names: an unquoted `;` or newline (whatever follows owns the exit), a
542
+ * background `&` (the shell owns it), or a word-starting `#` (the field
543
+ * carries a comment). Quotes, command substitutions and redirections are
544
+ * shell syntax rather than decorations and are skipped, so `2>&1 | tail`,
545
+ * `cd x && npm run ci:check` and a quoted `';'` stay accepted. Returns the
546
+ * decoration found, or null when the field carries none.
547
+ */
548
+ export function findTopLevelDecoration(cmd) {
549
+ const frames = ["top"];
550
+ let quote = null;
551
+ let wordStart = true;
552
+ for (let i = 0; i < cmd.length; i++) {
553
+ const ch = cmd[i];
554
+ const next = cmd[i + 1];
555
+ if (quote === "single") {
556
+ if (ch === "'")
557
+ quote = null;
558
+ continue;
559
+ }
560
+ if (quote === "backtick") {
561
+ if (ch === "\\")
562
+ i++;
563
+ else if (ch === "`")
564
+ quote = null;
565
+ continue;
566
+ }
567
+ if (quote === "double") {
568
+ if (ch === "\\")
569
+ i++;
570
+ else if (ch === '"')
571
+ quote = null;
572
+ else if (ch === "$" && next === "(") {
573
+ frames.push("subst");
574
+ i++;
575
+ }
576
+ else if (ch === "`")
577
+ quote = "backtick";
578
+ continue;
579
+ }
580
+ // Unquoted: at the top level, or inside a command substitution.
581
+ if (ch === "\\") {
582
+ i++;
583
+ continue;
584
+ }
585
+ if (ch === "'") {
586
+ quote = "single";
587
+ wordStart = false;
588
+ continue;
589
+ }
590
+ if (ch === '"') {
591
+ quote = "double";
592
+ wordStart = false;
593
+ continue;
594
+ }
595
+ if (ch === "`") {
596
+ quote = "backtick";
597
+ wordStart = false;
598
+ continue;
599
+ }
600
+ if (ch === "$" && next === "(") {
601
+ frames.push("subst");
602
+ i++;
603
+ wordStart = false;
604
+ continue;
605
+ }
606
+ if (frames[frames.length - 1] === "subst") {
607
+ if (ch === "(")
608
+ frames.push("subst");
609
+ else if (ch === ")")
610
+ frames.pop();
611
+ continue;
612
+ }
613
+ if (ch === ";")
614
+ return ";";
615
+ if (ch === "\n")
616
+ return "newline";
617
+ if (ch === "#" && wordStart)
618
+ return "comment";
619
+ if (ch === "&") {
620
+ const previous = cmd[i - 1];
621
+ const andAnd = next === "&";
622
+ const redirection = previous === ">" || previous === "<" || next === ">";
623
+ if (!andAnd && !redirection)
624
+ return "&";
625
+ if (andAnd)
626
+ i++;
627
+ wordStart = false;
628
+ continue;
629
+ }
630
+ wordStart = ch === " " || ch === "\t";
631
+ }
632
+ return null;
633
+ }
634
+ /**
635
+ * Run the four predicates over one recorded row and return the first
636
+ * violation, or null when the row is well formed. (a)/(b) need `sh`; when the
637
+ * shell cannot be spawned they are left unjudged (the string-only (c) and (d)
638
+ * still run), so a missing instrument cannot fail every row.
639
+ */
640
+ export function findGateRowViolation(cmd, exit, outcome) {
641
+ const parse = runShell(["-n", "-c", cmd]);
642
+ if ("ok" in parse && !parse.ok) {
643
+ return { predicate: "a", detail: `does not parse under sh -n (${parse.detail})` };
644
+ }
645
+ if ("ok" in parse) {
646
+ const token = firstCommandToken(cmd);
647
+ if (token === null) {
648
+ return { predicate: "b", detail: "no command token after the env prefixes" };
649
+ }
650
+ const resolved = runShell(["-c", 'command -v "$1" >/dev/null 2>&1', "sh", token]);
651
+ if ("ok" in resolved && !resolved.ok) {
652
+ return { predicate: "b", detail: `first token "${token}" does not resolve to an executable` };
653
+ }
654
+ }
655
+ const decoration = findTopLevelDecoration(cmd);
656
+ if (decoration !== null) {
657
+ return {
658
+ predicate: "c",
659
+ detail: `top-level ${decoration}: not the command alone`,
660
+ };
661
+ }
662
+ if (outcome === "completed" && exit !== 0) {
663
+ return { predicate: "d", detail: `exit ${exit} recorded under a completed outcome` };
664
+ }
665
+ return null;
666
+ }
667
+ /** Where close-gate refusals land: one JSONL line per failing row. */
668
+ export function closeGateRefusalLogPath() {
669
+ return join(braidDir(), "orchestrator", "close-gate-refusals.jsonl");
670
+ }
671
+ /** Warned once per process about an unwritable refusal log. */
672
+ let _warnedRefusalLogFailure = false;
673
+ /**
674
+ * Append one refusal line. Never throws: a failed append warns once and
675
+ * leaves the close's own behavior untouched, so an unwritable braid root
676
+ * cannot refuse a close that shadow mode would have accepted.
677
+ */
678
+ export function logCloseGateRefusal(record) {
679
+ try {
680
+ const file = closeGateRefusalLogPath();
681
+ mkdirSync(dirname(file), { recursive: true });
682
+ appendFileSync(file, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
683
+ }
684
+ catch (error) {
685
+ if (_warnedRefusalLogFailure)
686
+ return;
687
+ _warnedRefusalLogFailure = true;
688
+ const message = error instanceof Error ? error.message : String(error);
689
+ log.warn(`close-gate refusal log not writable; refusals continue unlogged: ${message}`);
690
+ }
691
+ }
692
+ /** Where the seat publishes the production-write class it owns. */
693
+ export function productionWriteClassPath() {
694
+ return join(braidDir(), "orchestrator", "production-writes.json");
695
+ }
696
+ /** Warned once per process about an unreadable class file. */
697
+ let _warnedProductionWriteClass = false;
698
+ function warnProductionWriteClass(detail) {
699
+ if (_warnedProductionWriteClass)
700
+ return;
701
+ _warnedProductionWriteClass = true;
702
+ log.warn(`production-write class not read (${detail}); closes are not refused for recorded writes`);
703
+ }
704
+ /**
705
+ * Read one array of rules out of the class table, keeping only entries a reader
706
+ * can use: a non-empty id, a non-empty pattern that compiles, and a label
707
+ * (falling back to the id). Junk entries are dropped rather than thrown: the
708
+ * file is seat-edited data, and an unusable one must fail open.
709
+ */
710
+ function readRuleList(raw) {
711
+ if (!Array.isArray(raw))
712
+ return [];
713
+ const rules = [];
714
+ for (const entry of raw) {
715
+ if (!entry || typeof entry !== "object" || Array.isArray(entry))
716
+ continue;
717
+ const { id, label, pattern, registry } = entry;
718
+ if (typeof id !== "string" || id.trim() === "")
719
+ continue;
720
+ if (typeof pattern !== "string" || pattern === "")
721
+ continue;
722
+ try {
723
+ new RegExp(pattern);
724
+ }
725
+ catch {
726
+ continue;
727
+ }
728
+ rules.push({
729
+ id,
730
+ label: typeof label === "string" && label !== "" ? label : id,
731
+ pattern,
732
+ ...(typeof registry === "string" ? { registry } : {}),
733
+ });
476
734
  }
735
+ return rules;
736
+ }
737
+ /**
738
+ * Load the class table the seat owns. Never throws: a braid home that cannot be
739
+ * resolved, a missing file, an unreadable file and a malformed one all yield an
740
+ * empty class, which refuses nothing.
741
+ */
742
+ export function readProductionWriteClass(file) {
743
+ const empty = { members: [], pieces: [] };
744
+ let path;
745
+ try {
746
+ path = file ?? productionWriteClassPath();
747
+ }
748
+ catch (error) {
749
+ warnProductionWriteClass(error instanceof Error ? error.message : String(error));
750
+ return empty;
751
+ }
752
+ let parsed;
753
+ try {
754
+ parsed = JSON.parse(readFileSync(path, "utf-8"));
755
+ }
756
+ catch (error) {
757
+ const code = error.code;
758
+ if (code !== "ENOENT") {
759
+ warnProductionWriteClass(`${path}: ${error instanceof Error ? error.message : String(error)}`);
760
+ }
761
+ return empty;
762
+ }
763
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
764
+ warnProductionWriteClass(`${path}: top level is not an object`);
765
+ return empty;
766
+ }
767
+ const table = parsed;
768
+ const pieces = table.preflight?.pieces;
769
+ return { members: readRuleList(table.members), pieces: readRuleList(pieces) };
770
+ }
771
+ /** Compile a rule list, dropping any pattern that does not compile. */
772
+ function compileProductionWriteRules(rules) {
773
+ const compiled = [];
774
+ for (const rule of rules) {
775
+ try {
776
+ compiled.push({ rule, re: new RegExp(rule.pattern) });
777
+ }
778
+ catch {
779
+ // readRuleList already dropped these; a caller-supplied table may not have.
780
+ }
781
+ }
782
+ return compiled;
783
+ }
784
+ /**
785
+ * Read a close's gate rows for production writes and their preflight evidence.
786
+ * A row is a write when any member pattern matches its cmd — a field carrying a
787
+ * write beside reads is still a write, because the members match the write
788
+ * verbs only. A piece is recorded when any row's cmd matches its pattern, so
789
+ * one composed preflight row and several separate ones both satisfy. Pure over
790
+ * the rows and the table.
791
+ */
792
+ export function readProductionWrites(rows, table = readProductionWriteClass()) {
793
+ if (!rows || rows.length === 0)
794
+ return { rows: [], unsatisfied: [] };
795
+ const members = compileProductionWriteRules(table.members);
796
+ const pieces = compileProductionWriteRules(table.pieces);
797
+ if (members.length === 0)
798
+ return { rows: [], unsatisfied: [] };
799
+ const cmdAt = (row) => typeof row?.cmd === "string" ? row.cmd : "";
800
+ const writes = [];
801
+ for (let i = 0; i < rows.length; i++) {
802
+ const cmd = cmdAt(rows[i]);
803
+ const member = members.find(({ re }) => re.test(cmd));
804
+ if (!member)
805
+ continue;
806
+ const missing = [];
807
+ const preflightRows = new Set();
808
+ for (const piece of pieces) {
809
+ let recorded = false;
810
+ for (let j = 0; j < rows.length; j++) {
811
+ if (piece.re.test(cmdAt(rows[j]))) {
812
+ recorded = true;
813
+ preflightRows.add(j);
814
+ }
815
+ }
816
+ if (!recorded)
817
+ missing.push(piece.rule.id);
818
+ }
819
+ writes.push({
820
+ row: i,
821
+ cmd,
822
+ member: member.rule.id,
823
+ preflightRows: [...preflightRows].sort((a, b) => a - b),
824
+ missingPieces: missing,
825
+ });
826
+ }
827
+ return { rows: writes, unsatisfied: writes.filter((row) => row.missingPieces.length > 0) };
828
+ }
829
+ /**
830
+ * The refusal sentence for the first write row missing a piece: its index, the
831
+ * member, the missing piece ids and the command. Null when every write row is
832
+ * satisfied, so a caller cannot refuse on an empty read.
833
+ */
834
+ export function productionWriteRefusalDetail(read) {
835
+ const row = read.unsatisfied[0];
836
+ if (!row)
837
+ return null;
838
+ return (`gates[${row.row}] records a production write ("${row.member}") without a complete ` +
839
+ `preflight row: missing pieces: ${row.missingPieces.join(", ")}; cmd: ${row.cmd}`);
840
+ }
841
+ /**
842
+ * Bare-token revision rules: an all-hex token is a sha only at 7-40 chars, so
843
+ * a six-char prefix does not slip through the ref-name alternative as a
844
+ * revision git can never resolve.
845
+ */
846
+ const POPULATION_STAMP_RE = /^scanned (\d+) ([a-z]+) at ([0-9a-fA-F]{7,40}|[A-Za-z0-9][A-Za-z0-9._/-]*)$/;
847
+ const ALL_HEX_RE = /^[0-9a-fA-F]+$/;
848
+ /** Parse the stamp shape above; null when the value is not that shape. */
849
+ export function parsePopulationStamp(value) {
850
+ if (typeof value !== "string")
851
+ return null;
852
+ const match = POPULATION_STAMP_RE.exec(value);
853
+ if (!match)
854
+ return null;
855
+ const [, rawN, unit, revision] = match;
856
+ if (ALL_HEX_RE.test(revision) && (revision.length < 7 || revision.length > 40))
857
+ return null;
858
+ return { n: Number(rawN), unit, revision };
859
+ }
860
+ function populationLines(rows) {
861
+ const lines = [];
862
+ for (const row of rows) {
863
+ if (row.verdict === "unreadable") {
864
+ lines.push(`population stamp unreadable: row ${row.row} ${JSON.stringify(row.raw)}`);
865
+ continue;
866
+ }
867
+ if (row.stamp === null || row.stamp.unit !== "files")
868
+ continue;
869
+ if (row.verdict === "unresolved") {
870
+ lines.push(`population delta: recorded ${row.stamp.n} at ${row.stamp.revision} ` +
871
+ `(row ${row.row}; revision unresolved, not compared)`);
872
+ }
873
+ else if (row.census !== null) {
874
+ lines.push(`population delta: recorded ${row.stamp.n} vs census ${row.census} at ` +
875
+ `${row.stamp.revision} (row ${row.row})`);
876
+ }
877
+ }
878
+ if (!rows.some((row) => row.stamp !== null && row.stamp.unit === "files")) {
879
+ lines.push("no recorded population");
880
+ }
881
+ return lines;
882
+ }
883
+ /**
884
+ * Read every gate row for a population stamp and compare the `files` ones
885
+ * against the census the caller supplies for their named revision. Pure: the
886
+ * count is a lookup parameter, so the parse and the comparison are testable
887
+ * without a repository. Rows of another unit are not census subjects and are
888
+ * left uncompared; an unreadable stamp is named, never silently dropped.
889
+ */
890
+ export function readPopulationStamps(gates, censusAt) {
891
+ const rows = [];
892
+ const list = Array.isArray(gates) ? gates : [];
893
+ for (let i = 0; i < list.length; i++) {
894
+ const gate = list[i];
895
+ const record = gate && typeof gate === "object" && !Array.isArray(gate)
896
+ ? gate
897
+ : null;
898
+ const cmd = typeof record?.cmd === "string" ? record.cmd : "";
899
+ const present = record !== null && record.stamp !== undefined;
900
+ const raw = present ? record.stamp : undefined;
901
+ const stamp = present ? parsePopulationStamp(raw) : null;
902
+ let census = null;
903
+ let delta = null;
904
+ let verdict;
905
+ if (!present)
906
+ verdict = "absent";
907
+ else if (stamp === null)
908
+ verdict = "unreadable";
909
+ else if (stamp.unit !== "files")
910
+ verdict = "other-subject";
911
+ else {
912
+ census = censusAt(stamp.revision);
913
+ if (census === null)
914
+ verdict = "unresolved";
915
+ else {
916
+ delta = census - stamp.n;
917
+ verdict = delta === 0 ? "match" : delta > 0 ? "below" : "above";
918
+ }
919
+ }
920
+ rows.push({ row: i, cmd, raw, present, stamp, census, delta, verdict });
921
+ }
922
+ return {
923
+ rows,
924
+ comparisons: rows.filter((row) => row.stamp !== null && row.census !== null),
925
+ standing: rows.find((row) => row.verdict === "below") ?? null,
926
+ recorded: rows.some((row) => row.stamp !== null && row.stamp.unit === "files"),
927
+ lines: populationLines(rows),
928
+ };
929
+ }
930
+ /**
931
+ * The refusal sentence for the first standing delta: row index, stamp, census,
932
+ * delta, and the remedy. Null when no comparison sits below its census, so a
933
+ * caller cannot refuse on an empty read.
934
+ */
935
+ export function populationRefusalDetail(read) {
936
+ const row = read.standing;
937
+ if (!row || row.stamp === null || row.census === null || row.delta === null)
938
+ return null;
939
+ return (`row ${row.row} stamp "scanned ${row.stamp.n} ${row.stamp.unit} at ${row.stamp.revision}" ` +
940
+ `records ${row.stamp.n} but the census at ${row.stamp.revision} is ${row.census} ` +
941
+ `(delta ${row.delta}); re-run the gate on the staged tree and re-issue the close`);
477
942
  }
478
943
  /**
479
944
  * Close an entry with a terminal outcome and optional gate evidence.
@@ -484,8 +949,24 @@ function assertGateEvidence(workerId, outcome, gates) {
484
949
  * A completed close carries evidence: the reporter contract requires a
485
950
  * non-empty `gate_evidence` block, and a probe measured this path storing a
486
951
  * bare `completed` with no gates at all. That contradiction is refused now,
487
- * and each provided gate is shape-checked (non-empty `cmd`, numeric `exit`)
488
- * before any write — a violation leaves the row and the lock table untouched.
952
+ * and each provided gate is shape-checked (non-empty `cmd`, numeric `exit`,
953
+ * string `stamp` when present) before any write — a violation leaves the row
954
+ * and the lock table untouched. A valid `stamp` is stored verbatim, so the
955
+ * merge path can read the recorded population off the row.
956
+ *
957
+ * Every provided row is then read for well-formedness: its `cmd` must parse
958
+ * under `sh -n`, resolve its first token, and name the command alone, and a
959
+ * completed close's exits must be 0. The mode is settings-driven
960
+ * (`braid.orchestrator.closeGateWellFormedness`): "shadow" (default) records
961
+ * a refusal line and proceeds, "enforce" refuses before any write or lock
962
+ * release, "off" skips the read. No gate is re-run; replay stays the
963
+ * sampler's sampled job.
964
+ *
965
+ * Every row is also read against the seat's production-write class: a row the
966
+ * class marks as a write is refused unless the close records every named
967
+ * preflight piece (identity, registry, dry-run) somewhere in its rows. The
968
+ * class lives in the seat's data file; when it is absent the class is empty and
969
+ * nothing is refused.
489
970
  *
490
971
  * Releases the worker's file locks: close is terminal, and a lock that
491
972
  * survives it blocks the next spawn on the same files. The release runs with
@@ -501,6 +982,35 @@ export function closeWorker(workerId, outcome, gates, cwd) {
501
982
  if (entry.closedAt)
502
983
  return entry;
503
984
  assertGateEvidence(workerId, parsed, gates);
985
+ const wellFormedness = getCloseGateWellFormedness();
986
+ if (wellFormedness.mode !== "off" && gates && gates.length > 0) {
987
+ for (let i = 0; i < gates.length; i++) {
988
+ const violation = findGateRowViolation(gates[i].cmd, gates[i].exit, parsed);
989
+ if (!violation)
990
+ continue;
991
+ logCloseGateRefusal({
992
+ at: new Date().toISOString(),
993
+ workerId,
994
+ row: i,
995
+ predicate: violation.predicate,
996
+ cmd: gates[i].cmd,
997
+ mode: wellFormedness.mode,
998
+ outcome: parsed,
999
+ detail: violation.detail,
1000
+ });
1001
+ if (wellFormedness.mode === "enforce") {
1002
+ throw new Error(`closeWorker: gates[${i}] fails predicate (${violation.predicate}): ${violation.detail}; ` +
1003
+ `cmd: ${gates[i].cmd} (worker ${workerId}, outcome ${parsed})`);
1004
+ }
1005
+ }
1006
+ }
1007
+ // A recorded production write must carry its preflight evidence. The class
1008
+ // table is the seat's data, and an absent one reads as empty (fail-open), so
1009
+ // this refuses only what the seat has declared a write without its pieces.
1010
+ const productionRefusal = productionWriteRefusalDetail(readProductionWrites(gates, readProductionWriteClass()));
1011
+ if (productionRefusal) {
1012
+ throw new Error(`closeWorker: ${productionRefusal} (worker ${workerId}, outcome ${parsed})`);
1013
+ }
504
1014
  releaseLock(workerId, located.key);
505
1015
  const nowIso = new Date().toISOString();
506
1016
  entry.status = parsed;
@@ -510,7 +1020,12 @@ export function closeWorker(workerId, outcome, gates, cwd) {
510
1020
  entry.resultAt = nowIso;
511
1021
  if (gates && gates.length > 0) {
512
1022
  for (const gate of gates) {
513
- entry.gates.push({ cmd: gate.cmd, exit: gate.exit, at: nowIso });
1023
+ entry.gates.push({
1024
+ cmd: gate.cmd,
1025
+ exit: gate.exit,
1026
+ at: nowIso,
1027
+ ...(gate.stamp === undefined ? {} : { stamp: gate.stamp }),
1028
+ });
514
1029
  }
515
1030
  }
516
1031
  writeWorkers(located.registry, located.key);
@@ -558,7 +558,7 @@ wakeDefer) {
558
558
  `(source: ${injectionMeta.source})`);
559
559
  return false;
560
560
  }
561
- // ROADMAP EW-7.12+: apply the universal whisper envelope so the agent
561
+ // Apply the universal whisper envelope so the agent
562
562
  // can distinguish system-injected messages from human user input. Done
563
563
  // before the flood cap so the tracked (and potentially suppressed)
564
564
  // content reflects what would have been delivered. See
@@ -38,6 +38,14 @@ usage; hygiene acts re-arm at most once every three turns.
38
38
  Owner: [`src/lib/detection/context-thresholds.ts`](../src/lib/detection/context-thresholds.ts)
39
39
  (single home; consumers import, never restate).
40
40
 
41
+ ### Usage-driven slide compaction
42
+
43
+ | Setting | Default | Effect | Read cadence |
44
+ | ---------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
45
+ | `braid.context.contextAutoCompact` | `{ enabled: true, armPercent: 60, confirmTicks: 2 }` | When live usage stays at or above `armPercent` for `confirmTicks` consecutive heartbeat observations, queues one deterministic slide for the next turn boundary. Set `enabled: false` to turn off this automatic arm. | Re-read at use time, on each heartbeat observation. |
46
+
47
+ Owner: [`src/lib/config/braid-settings.ts`](../src/lib/config/braid-settings.ts); auto-arm runs in [`src/extensions/memory/context-manager/handlers/tools/context-compress.ts`](../src/extensions/memory/context-manager/handlers/tools/context-compress.ts).
48
+
41
49
  ## The compaction reserve
42
50
 
43
51
  pi-core fires native threshold compaction when `contextTokens > contextWindow −
@@ -58,11 +66,11 @@ from [`src/extensions/core/polyfill/index.ts`](../src/extensions/core/polyfill/i
58
66
 
59
67
  ## Caps and offload
60
68
 
61
- | Setting | Default | Effect |
62
- | --------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
63
- | `braid.context.toolResultSizeCap` | ON, 262144 chars | capture-time cap: an oversized tool result is flushed to disk and replaced by a stub naming the file |
64
- | `braid.context.staleToolResultOffload` | OFF | age/size offload of stale large results (minChars 4000, stalenessTurns 40, keepRecentTurns 20, 65536/run) |
65
- | `braid.context.contextEmergencyOffload` | ON | on a context-window (413) error: offload the largest results, retry once (minChars 262144, 1048576/run) |
69
+ | Setting | Default | Effect | Read cadence |
70
+ | ----------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
71
+ | `braid.context.toolResultSizeCap` (`enabled`; `maxChars`: `braid.context.toolResultSizeCap.maxChars`) | `enabled: true`, `maxChars: 262144` | Set `enabled: false` to turn off this cap. Results above `maxChars` are flushed losslessly to disk and replaced by a stub naming the file. | Re-read at use time on each tool result and offload recovery call. |
72
+ | `braid.context.staleToolResultOffload` | OFF | Age/size offload of stale large results (`minChars` 4000, `stalenessTurns` 40, `keepRecentTurns` 20, 65536/run). | Re-read at use time. |
73
+ | `braid.context.contextEmergencyOffload` | ON | On a context-window (413) error: offload the largest results, then retry once (`minChars` 262144, 1048576/run). | Re-read at use time. |
66
74
 
67
75
  Offloaded payloads land at `<braid home>/offload/<sessionId>/<toolName>-<toolCallId>.txt`
68
76
  (`offloadDir()` / `getOffloadFilePath` in
package/docs/LOCAL_DEV.md CHANGED
@@ -16,8 +16,10 @@ For one-time setup, the full install-path catalog, and module toggling see
16
16
  | git | any | `git --version` |
17
17
  | pi | peer-resolved | `which pi && pi --version` |
18
18
 
19
- The Node floor is the `engines` field in every workspace manifest; if this
20
- table and `engines` ever disagree, trust `engines`.
19
+ The Node floor is the `engines` field in every workspace manifest; the pi floor
20
+ is the `@earendil-works/*` peer range in the same manifests (a caret on the
21
+ family the seat runs, kept moving by the update pipeline). If this table and a
22
+ manifest ever disagree, trust the manifest.
21
23
 
22
24
  ## Monorepo layout
23
25
 
@@ -136,6 +138,26 @@ Example: `0.40.0-main.17`. When `package.json` already carries a full
136
138
  versioned release string (e.g. `0.40.0-main.17`), it is used verbatim instead
137
139
  of being double-suffixed.
138
140
 
141
+ ### Provenance in the tarball
142
+
143
+ Every artifact carries `build-info.json` - package name, packed version, commit
144
+ sha and branch, dirty flag, pack time (`scripts/build-info.mjs` is the one
145
+ generator). It is written by each workspace's `prepack` (`scripts/pack-provenance.mjs`),
146
+ expanded into the `files` allowlist of every package, and removed by `postpack`,
147
+ so an `npm publish` pays the same step a plain `npm pack` does and the checkout
148
+ ends as it started. `publish-local` reads git before the version bump and
149
+ writes the record from that read, so the recorded `dirty` is the pre-bump
150
+ state; it carries the `BRAID_PROVENANCE_DEFER` marker into the pack, and the
151
+ prepack step keeps a record only under that marker, because the temporary bump
152
+ would otherwise read as a dirty tree. A record a killed pack left
153
+ behind is regenerated from a fresh read - a matching version and commit are not
154
+ enough to defer to.
155
+
156
+ Read the record to tell two builds of the same version apart, and to check what
157
+ a stranger installed: `sha` plus `dirty == false` is the pair that means the
158
+ tarball is a clean checkout of a named commit - a version string identifies
159
+ neither.
160
+
139
161
  ## Upstream pi update pipeline
140
162
 
141
163
  `update-pipeline.mjs` codifies the full update run for the pair - the braid
@@ -151,11 +173,15 @@ npm run release:update:runtime -- --yes # real sequence plus `pi update` (last)
151
173
  Default mode writes nothing. It resolves the upstream pi version, compares it
152
174
  against the repo pins and the local-packages resolution, and prints the target
153
175
  version, every pin it would change (file, field, from -> to), the braid version
154
- bump, the publish commands, the runtime command, and the rollback commands.
176
+ bump, the publish commands, the runtime command, and the rollback commands. The
177
+ host-family peers are pins here too: each workspace manifest declares the
178
+ `@earendil-works/*` peers (and `typebox`) as an explicit caret floor, and the
179
+ plan rewrites those ranges alongside the exact pins, so the floor moves with
180
+ the runtime instead of drifting behind it.
155
181
 
156
182
  The local-packages trap: braid resolves the pi family from
157
- `~/.pi/agent/local-packages`, and its manifests declare those packages as
158
- `*` peers. Installing a new braid tarball NEVER moves those copies - the
183
+ `~/.pi/agent/local-packages`, and those resolutions are not what its peer ranges
184
+ control. Installing a new braid tarball NEVER moves those copies - the
159
185
  explicit pins in `local-packages/package.json` must be realigned to the
160
186
  upstream version as their own step. That is why `--apply` aligns both sides,
161
187
  then republishes braid, and why the runtime update is always last and only runs