pi-braid 0.43.43 → 0.43.45

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.
package/CHANGELOG.md CHANGED
@@ -80,6 +80,33 @@ record; the tag scheme above applies unchanged.
80
80
  contract; a new fixture covers both trees, the scoping and the absent-versus-empty
81
81
  populations.
82
82
 
83
+ ## Core — 0.43.45 (2026-11-11: a re-read is a covered range, not a repeated path)
84
+
85
+ The re-read whisper keyed `recentlyReadFiles` on the path, so a second slice of one document in a turn
86
+ was reported as already in context: over the session corpus, 238 of the checkable flags were different
87
+ ranges of the same file and 6 were the same range again. The record is now a bounded set of line
88
+ windows per path, and a read is waste only when the range it asks for is fully covered by what is
89
+ already in context since the last edit, write or command. A slice past the read tool's default window
90
+ is not covered by a read that returned only the first 2000 lines, and the per-path bound drops the
91
+ oldest window, which can hide a repeat but can never invent one.
92
+
93
+ ## Core — 0.43.44 (2026-11-10: the version that carries the telegram release)
94
+
95
+ No core change. The `pi-braid-telegram` bump to 0.1.9 rides on a core version so the release line
96
+ stays ordered; the fix itself is described in the Telegram section below.
97
+
98
+ ## Telegram — 0.1.9 (2026-11-10: the lock names the boot by the kernel's id, not the clock)
99
+
100
+ `kern.boottime` is the wall clock minus uptime, so a clock step moves it and two processes on one
101
+ boot compute different instance identities. A handover then reads the lock as held across
102
+ namespaces and the channel cannot be taken: measured twice, the second time after a restart moved
103
+ the boot time by two seconds. The lock now prefers `/proc/sys/kernel/random/boot_id`, then
104
+ `kern.bootsessionuuid` on darwin, and keeps `kern.boottime` only as the documented last resort.
105
+
106
+ The fix was written and has been carried inside core since 0.43.30, but the standalone extension
107
+ the agent loads is this package, and it had not been published since 0.1.8: the running poller's
108
+ lock still carried a boottime identity. This release is the fix reaching the process that uses it.
109
+
83
110
  ## Telegram — 0.1.8 (2026-11-04: a pre-identity lock is judged by its pid, so a dead holder cannot wedge the channel)
84
111
 
85
112
  - **The legacy arm has three outcomes instead of a permanent refusal.** A lock
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.43",
4
- "sha": "faafcad8ff2d1ffaa02e18245e334016e5be6e95",
5
- "shaShort": "faafcad8",
3
+ "version": "0.43.45",
4
+ "sha": "615ea4c889b4ed58120ba82f1a3d8a4150df29fb",
5
+ "shaShort": "615ea4c8",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-11-10T18:33:21.495Z"
8
+ "packedAt": "2026-11-10T22:28:49.644Z"
9
9
  }
@@ -1,6 +1,7 @@
1
1
  import type { EnforcementState } from "../state.js";
2
2
  /**
3
- * Record file paths from read/edit operations for re-read detection.
3
+ * Record the window each read asks for, so turn validation can name only the
4
+ * reads whose lines are already in context.
4
5
  * Called from tool_call event handler which has access to event.input.
5
6
  */
6
7
  export declare function recordToolInput(toolName: string, input: Record<string, unknown> | undefined, s: EnforcementState): void;
@@ -5,7 +5,99 @@ import { recordCodeChange } from "../detection/verification.js";
5
5
  import { PROGRESS_TOOLS } from "../substate/tool-tracking-state.js";
6
6
  import { getState, recordToolChainCall, recordMemoryAccess, recordContextTool, resetScratchpadNudge, } from "../state.js";
7
7
  /**
8
- * Record file paths from read/edit operations for re-read detection.
8
+ * Lines a read brings into context when it names no `limit`: the read tool
9
+ * truncates to its own DEFAULT_MAX_LINES (2000) from the offset. Without the
10
+ * cap a read with no limit would look like it covered the whole file and every
11
+ * later line the tool never returned would read as already in context.
12
+ */
13
+ const READ_DEFAULT_LIMIT = 2000;
14
+ /**
15
+ * Windows kept per path, the oldest dropped past this. A dropped window only
16
+ * shrinks what counts as in context, so the bound can hide a repeat but can
17
+ * never invent one.
18
+ */
19
+ const READ_RANGES_PER_PATH = 8;
20
+ /** The line window a read asks for, `[start, end)`, from its own bounds and the tool's defaults. */
21
+ function readWindow(input) {
22
+ const offset = typeof input.offset === "number" && Number.isFinite(input.offset) ? input.offset : 0;
23
+ const limit = typeof input.limit === "number" && Number.isFinite(input.limit) && input.limit > 0
24
+ ? input.limit
25
+ : READ_DEFAULT_LIMIT;
26
+ const start = offset > 0 ? offset : 0;
27
+ return { start, end: start + limit };
28
+ }
29
+ /**
30
+ * Whether these windows leave no line of `[start, end)` out. They are merged
31
+ * and ascending, so one pass over this path's own windows settles it.
32
+ */
33
+ function coversWindow(windows, start, end) {
34
+ let coveredTo = start;
35
+ for (const w of windows) {
36
+ if (w.start > coveredTo)
37
+ return false;
38
+ if (w.end > coveredTo)
39
+ coveredTo = w.end;
40
+ if (coveredTo >= end)
41
+ return true;
42
+ }
43
+ return coveredTo >= end;
44
+ }
45
+ /** The newest position among a path's windows, for the path-population prune. */
46
+ function newestReadAt(windows) {
47
+ let newest = 0;
48
+ for (const w of windows)
49
+ if (w.at > newest)
50
+ newest = w.at;
51
+ return newest;
52
+ }
53
+ /**
54
+ * Record one `read` call: flag the path when every line it asks for is already
55
+ * in context, then keep the window for the reads that follow.
56
+ */
57
+ function recordRead(s, path, input) {
58
+ const { start, end } = readWindow(input);
59
+ // A window recorded before the last progress tool describes context an
60
+ // edit, write or command has since replaced: stale, not waste.
61
+ const windows = (s.recentlyReadFiles.get(path) ?? []).filter((w) => w.at >= s.lastProgressToolCall);
62
+ if (coversWindow(windows, start, end) && !s.turnReReadWastePaths.includes(path)) {
63
+ s.turnReReadWastePaths.push(path);
64
+ }
65
+ windows.push({ start, end, at: s.totalToolCalls });
66
+ windows.sort((a, b) => a.start - b.start);
67
+ // Keep a disjoint ascending set: reading one slice again then costs one
68
+ // window instead of consuming the per-path bound.
69
+ const merged = [];
70
+ for (const w of windows) {
71
+ const last = merged[merged.length - 1];
72
+ if (last && w.start <= last.end) {
73
+ last.end = Math.max(last.end, w.end);
74
+ last.at = Math.max(last.at, w.at);
75
+ }
76
+ else {
77
+ merged.push({ ...w });
78
+ }
79
+ }
80
+ while (merged.length > READ_RANGES_PER_PATH) {
81
+ let oldest = 0;
82
+ for (let i = 1; i < merged.length; i++) {
83
+ if (merged[i].at < merged[oldest].at)
84
+ oldest = i;
85
+ }
86
+ merged.splice(oldest, 1);
87
+ }
88
+ s.recentlyReadFiles.set(path, merged);
89
+ // Prune old entries (keep only last 50 files)
90
+ if (s.recentlyReadFiles.size > 50) {
91
+ const oldest = [...s.recentlyReadFiles.entries()]
92
+ .sort((a, b) => newestReadAt(a[1]) - newestReadAt(b[1]))
93
+ .slice(0, 10);
94
+ for (const [k] of oldest)
95
+ s.recentlyReadFiles.delete(k);
96
+ }
97
+ }
98
+ /**
99
+ * Record the window each read asks for, so turn validation can name only the
100
+ * reads whose lines are already in context.
9
101
  * Called from tool_call event handler which has access to event.input.
10
102
  */
11
103
  export function recordToolInput(toolName, input, s) {
@@ -15,23 +107,7 @@ export function recordToolInput(toolName, input, s) {
15
107
  if (!path)
16
108
  return;
17
109
  if (toolName === "read") {
18
- // Map value: the tool-call position of the last read of this path. A path
19
- // that is already mapped with no progress tool since was read before and
20
- // is being read again without anything changing in between; the list is
21
- // consumed by turn validation.
22
- const priorRead = s.recentlyReadFiles.get(path);
23
- if (priorRead !== undefined &&
24
- priorRead >= s.lastProgressToolCall &&
25
- !s.turnReReadWastePaths.includes(path)) {
26
- s.turnReReadWastePaths.push(path);
27
- }
28
- s.recentlyReadFiles.set(path, s.totalToolCalls);
29
- // Prune old entries (keep only last 50 files)
30
- if (s.recentlyReadFiles.size > 50) {
31
- const oldest = [...s.recentlyReadFiles.entries()].sort((a, b) => a[1] - b[1]).slice(0, 10);
32
- for (const [k] of oldest)
33
- s.recentlyReadFiles.delete(k);
34
- }
110
+ recordRead(s, path, input);
35
111
  }
36
112
  }
37
113
  export function recordToolCall(toolName, ctx) {
@@ -11,6 +11,24 @@ import type { ToolChainState, ToolSequencePattern } from "../types.js";
11
11
  * the same set.
12
12
  */
13
13
  export declare const PROGRESS_TOOLS: Set<string>;
14
+ /**
15
+ * One read's worth of context: the line window a single `read` call asked the
16
+ * tool to bring in.
17
+ *
18
+ * The window is what the re-read check compares, because a long file is read
19
+ * in slices: a second read of the same path repeats work only when every line
20
+ * it asks for is already in context. `at` is the tool-call position of the
21
+ * read that recorded the window, so a progress tool after it can mark the
22
+ * window as stale rather than waste.
23
+ */
24
+ export interface ReadRange {
25
+ /** First line the read asked for (the read tool's `offset`, or none). */
26
+ start: number;
27
+ /** One past the last line the read asked for. */
28
+ end: number;
29
+ /** `totalToolCalls` position of the read that recorded this window. */
30
+ at: number;
31
+ }
14
32
  export interface CalibrationPair {
15
33
  predicted: number;
16
34
  actual: number;
@@ -36,7 +54,10 @@ export interface ToolTrackingState {
36
54
  turnsSinceExplore: number;
37
55
  exploreBeforeActNudged: boolean;
38
56
  toolDiversityNudged: boolean;
39
- recentlyReadFiles: Map<string, number>;
57
+ /** Per path, the line windows read since the last progress tool, merged and
58
+ * ascending by start. Bounded by `READ_RANGES_PER_PATH` in
59
+ * handlers/tool-tracker.ts, the module that fills it. */
60
+ recentlyReadFiles: Map<string, ReadRange[]>;
40
61
  /** Paths re-read this turn while a prior read was still current (no
41
62
  * edit/write/bash since). Filled by recordToolInput; validateTurn consumes
42
63
  * the list and clears it. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.43",
3
+ "version": "0.43.45",
4
4
  "description": "🥨 Braid - Metacognitive extension suite for pi coding agent: Adds memory, plan tracking, structured cognitive signals and completion checks on top of pi core loop, so long sessions keep their context and stop claiming unfinished work.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -3,6 +3,7 @@
3
3
  */
4
4
  import { recordCodeChange } from "../detection/verification.js";
5
5
  import { PROGRESS_TOOLS } from "../substate/tool-tracking-state.js";
6
+ import type { ReadRange } from "../substate/tool-tracking-state.js";
6
7
  import {
7
8
  getState,
8
9
  recordToolChainCall,
@@ -13,7 +14,106 @@ import {
13
14
  import type { EnforcementState } from "../state.js";
14
15
 
15
16
  /**
16
- * Record file paths from read/edit operations for re-read detection.
17
+ * Lines a read brings into context when it names no `limit`: the read tool
18
+ * truncates to its own DEFAULT_MAX_LINES (2000) from the offset. Without the
19
+ * cap a read with no limit would look like it covered the whole file and every
20
+ * later line the tool never returned would read as already in context.
21
+ */
22
+ const READ_DEFAULT_LIMIT = 2000;
23
+
24
+ /**
25
+ * Windows kept per path, the oldest dropped past this. A dropped window only
26
+ * shrinks what counts as in context, so the bound can hide a repeat but can
27
+ * never invent one.
28
+ */
29
+ const READ_RANGES_PER_PATH = 8;
30
+
31
+ /** The line window a read asks for, `[start, end)`, from its own bounds and the tool's defaults. */
32
+ function readWindow(input: Record<string, unknown>): { start: number; end: number } {
33
+ const offset =
34
+ typeof input.offset === "number" && Number.isFinite(input.offset) ? input.offset : 0;
35
+ const limit =
36
+ typeof input.limit === "number" && Number.isFinite(input.limit) && input.limit > 0
37
+ ? input.limit
38
+ : READ_DEFAULT_LIMIT;
39
+ const start = offset > 0 ? offset : 0;
40
+ return { start, end: start + limit };
41
+ }
42
+
43
+ /**
44
+ * Whether these windows leave no line of `[start, end)` out. They are merged
45
+ * and ascending, so one pass over this path's own windows settles it.
46
+ */
47
+ function coversWindow(windows: ReadRange[], start: number, end: number): boolean {
48
+ let coveredTo = start;
49
+ for (const w of windows) {
50
+ if (w.start > coveredTo) return false;
51
+ if (w.end > coveredTo) coveredTo = w.end;
52
+ if (coveredTo >= end) return true;
53
+ }
54
+ return coveredTo >= end;
55
+ }
56
+
57
+ /** The newest position among a path's windows, for the path-population prune. */
58
+ function newestReadAt(windows: ReadRange[]): number {
59
+ let newest = 0;
60
+ for (const w of windows) if (w.at > newest) newest = w.at;
61
+ return newest;
62
+ }
63
+
64
+ /**
65
+ * Record one `read` call: flag the path when every line it asks for is already
66
+ * in context, then keep the window for the reads that follow.
67
+ */
68
+ function recordRead(s: EnforcementState, path: string, input: Record<string, unknown>): void {
69
+ const { start, end } = readWindow(input);
70
+
71
+ // A window recorded before the last progress tool describes context an
72
+ // edit, write or command has since replaced: stale, not waste.
73
+ const windows = (s.recentlyReadFiles.get(path) ?? []).filter(
74
+ (w) => w.at >= s.lastProgressToolCall,
75
+ );
76
+
77
+ if (coversWindow(windows, start, end) && !s.turnReReadWastePaths.includes(path)) {
78
+ s.turnReReadWastePaths.push(path);
79
+ }
80
+
81
+ windows.push({ start, end, at: s.totalToolCalls });
82
+ windows.sort((a, b) => a.start - b.start);
83
+
84
+ // Keep a disjoint ascending set: reading one slice again then costs one
85
+ // window instead of consuming the per-path bound.
86
+ const merged: ReadRange[] = [];
87
+ for (const w of windows) {
88
+ const last = merged[merged.length - 1];
89
+ if (last && w.start <= last.end) {
90
+ last.end = Math.max(last.end, w.end);
91
+ last.at = Math.max(last.at, w.at);
92
+ } else {
93
+ merged.push({ ...w });
94
+ }
95
+ }
96
+ while (merged.length > READ_RANGES_PER_PATH) {
97
+ let oldest = 0;
98
+ for (let i = 1; i < merged.length; i++) {
99
+ if (merged[i].at < merged[oldest].at) oldest = i;
100
+ }
101
+ merged.splice(oldest, 1);
102
+ }
103
+ s.recentlyReadFiles.set(path, merged);
104
+
105
+ // Prune old entries (keep only last 50 files)
106
+ if (s.recentlyReadFiles.size > 50) {
107
+ const oldest = [...s.recentlyReadFiles.entries()]
108
+ .sort((a, b) => newestReadAt(a[1]) - newestReadAt(b[1]))
109
+ .slice(0, 10);
110
+ for (const [k] of oldest) s.recentlyReadFiles.delete(k);
111
+ }
112
+ }
113
+
114
+ /**
115
+ * Record the window each read asks for, so turn validation can name only the
116
+ * reads whose lines are already in context.
17
117
  * Called from tool_call event handler which has access to event.input.
18
118
  */
19
119
  export function recordToolInput(
@@ -27,24 +127,7 @@ export function recordToolInput(
27
127
  if (!path) return;
28
128
 
29
129
  if (toolName === "read") {
30
- // Map value: the tool-call position of the last read of this path. A path
31
- // that is already mapped with no progress tool since was read before and
32
- // is being read again without anything changing in between; the list is
33
- // consumed by turn validation.
34
- const priorRead = s.recentlyReadFiles.get(path);
35
- if (
36
- priorRead !== undefined &&
37
- priorRead >= s.lastProgressToolCall &&
38
- !s.turnReReadWastePaths.includes(path)
39
- ) {
40
- s.turnReReadWastePaths.push(path);
41
- }
42
- s.recentlyReadFiles.set(path, s.totalToolCalls);
43
- // Prune old entries (keep only last 50 files)
44
- if (s.recentlyReadFiles.size > 50) {
45
- const oldest = [...s.recentlyReadFiles.entries()].sort((a, b) => a[1] - b[1]).slice(0, 10);
46
- for (const [k] of oldest) s.recentlyReadFiles.delete(k);
47
- }
130
+ recordRead(s, path, input);
48
131
  }
49
132
  }
50
133
 
@@ -14,6 +14,25 @@ import type { ToolChainState, ToolSequencePattern } from "../types.js";
14
14
  */
15
15
  export const PROGRESS_TOOLS = new Set<string>(["edit", "write", "bash"]);
16
16
 
17
+ /**
18
+ * One read's worth of context: the line window a single `read` call asked the
19
+ * tool to bring in.
20
+ *
21
+ * The window is what the re-read check compares, because a long file is read
22
+ * in slices: a second read of the same path repeats work only when every line
23
+ * it asks for is already in context. `at` is the tool-call position of the
24
+ * read that recorded the window, so a progress tool after it can mark the
25
+ * window as stale rather than waste.
26
+ */
27
+ export interface ReadRange {
28
+ /** First line the read asked for (the read tool's `offset`, or none). */
29
+ start: number;
30
+ /** One past the last line the read asked for. */
31
+ end: number;
32
+ /** `totalToolCalls` position of the read that recorded this window. */
33
+ at: number;
34
+ }
35
+
17
36
  export interface CalibrationPair {
18
37
  predicted: number;
19
38
  actual: number;
@@ -40,7 +59,10 @@ export interface ToolTrackingState {
40
59
  turnsSinceExplore: number;
41
60
  exploreBeforeActNudged: boolean;
42
61
  toolDiversityNudged: boolean;
43
- recentlyReadFiles: Map<string, number>;
62
+ /** Per path, the line windows read since the last progress tool, merged and
63
+ * ascending by start. Bounded by `READ_RANGES_PER_PATH` in
64
+ * handlers/tool-tracker.ts, the module that fills it. */
65
+ recentlyReadFiles: Map<string, ReadRange[]>;
44
66
  /** Paths re-read this turn while a prior read was still current (no
45
67
  * edit/write/bash since). Filled by recordToolInput; validateTurn consumes
46
68
  * the list and clears it. */
@@ -92,7 +114,7 @@ export function createToolTrackingState(): ToolTrackingState {
92
114
  turnsSinceExplore: 0,
93
115
  exploreBeforeActNudged: false,
94
116
  toolDiversityNudged: false,
95
- recentlyReadFiles: new Map<string, number>(),
117
+ recentlyReadFiles: new Map<string, ReadRange[]>(),
96
118
  turnReReadWastePaths: [],
97
119
  lastProgressToolCall: 0,
98
120