pi-braid 0.42.1 → 0.43.1

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 (81) hide show
  1. package/CHANGELOG.md +92 -0
  2. package/README.md +61 -228
  3. package/TOOLS.md +12 -14
  4. package/build-info.json +4 -4
  5. package/dist/extensions/core/polyfill/index.d.ts +3 -4
  6. package/dist/extensions/core/polyfill/index.js +34 -131
  7. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +13 -0
  8. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +8 -3
  9. package/dist/extensions/enforcement/session-health.d.ts +52 -4
  10. package/dist/extensions/enforcement/session-health.js +75 -5
  11. package/dist/extensions/enforcement/whisper.js +15 -1
  12. package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +17 -0
  13. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +40 -78
  14. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +2 -1
  15. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +26 -28
  16. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +62 -31
  17. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +130 -55
  18. package/dist/extensions/memory/context-lifecycle/index.js +11 -10
  19. package/dist/extensions/memory/context-manager/analysis.d.ts +2 -0
  20. package/dist/extensions/memory/context-manager/analysis.js +6 -2
  21. package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +3 -3
  22. package/dist/extensions/memory/context-manager/handlers/events.js +13 -1
  23. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +10 -14
  24. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +62 -88
  25. package/dist/extensions/self/watchdog/engine.d.ts +8 -1
  26. package/dist/extensions/self/watchdog/engine.js +25 -2
  27. package/dist/extensions/self/watchdog/index.js +14 -1
  28. package/dist/lib/ai/llm-call.js +23 -0
  29. package/dist/lib/ai/model-resolver.d.ts +11 -10
  30. package/dist/lib/ai/model-resolver.js +16 -19
  31. package/dist/lib/ai/presend-budget.d.ts +68 -0
  32. package/dist/lib/ai/presend-budget.js +83 -0
  33. package/dist/lib/config/braid-settings.d.ts +38 -0
  34. package/dist/lib/config/braid-settings.js +84 -0
  35. package/dist/lib/config/per-tool-settings.d.ts +4 -4
  36. package/dist/lib/config/per-tool-settings.js +4 -4
  37. package/dist/lib/detection/context-tiers.d.ts +18 -5
  38. package/dist/lib/detection/context-tiers.js +51 -33
  39. package/dist/lib/detection/context-usage.d.ts +62 -1
  40. package/dist/lib/detection/context-usage.js +158 -1
  41. package/dist/lib/errors/llm-error.d.ts +14 -0
  42. package/dist/lib/errors/llm-error.js +44 -1
  43. package/dist/lib/state/global-state.d.ts +4 -8
  44. package/dist/lib/state/global-state.js +11 -28
  45. package/dist/lib/telemetry/context-heartbeat.d.ts +9 -0
  46. package/dist/lib/telemetry/context-heartbeat.js +18 -8
  47. package/dist/lib/utils/wake-gate.d.ts +6 -0
  48. package/dist/lib/utils/wake-gate.js +52 -4
  49. package/docs/SETUP.md +7 -6
  50. package/package.json +8 -11
  51. package/src/extensions/core/polyfill/index.ts +29 -157
  52. package/src/extensions/enforcement/AGENTS.md +38 -1
  53. package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +13 -0
  54. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +8 -2
  55. package/src/extensions/enforcement/session-health.ts +94 -5
  56. package/src/extensions/enforcement/whisper.ts +15 -1
  57. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +53 -80
  58. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +34 -43
  59. package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +154 -52
  60. package/src/extensions/memory/AGENTS.md +37 -38
  61. package/src/extensions/memory/context-lifecycle/index.ts +11 -10
  62. package/src/extensions/memory/context-manager/analysis.ts +8 -1
  63. package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +3 -3
  64. package/src/extensions/memory/context-manager/handlers/events.ts +18 -1
  65. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +81 -115
  66. package/src/extensions/scheduling/timer/AGENTS.md +14 -4
  67. package/src/extensions/self/watchdog/AGENTS.md +36 -18
  68. package/src/extensions/self/watchdog/engine.ts +30 -2
  69. package/src/extensions/self/watchdog/index.ts +13 -1
  70. package/src/lib/ai/AGENTS.md +2 -0
  71. package/src/lib/ai/llm-call.ts +30 -0
  72. package/src/lib/ai/model-resolver.ts +16 -19
  73. package/src/lib/ai/presend-budget.ts +117 -0
  74. package/src/lib/config/braid-settings.ts +125 -0
  75. package/src/lib/config/per-tool-settings.ts +4 -4
  76. package/src/lib/detection/context-tiers.ts +52 -41
  77. package/src/lib/detection/context-usage.ts +211 -2
  78. package/src/lib/errors/llm-error.ts +55 -1
  79. package/src/lib/state/global-state.ts +11 -29
  80. package/src/lib/telemetry/context-heartbeat.ts +27 -7
  81. package/src/lib/utils/wake-gate.ts +59 -4
@@ -15,7 +15,6 @@ import { StringEnum } from "@earendil-works/pi-ai";
15
15
  import { Type } from "typebox";
16
16
  import { createLogger } from "../../../lib/core/logger.js";
17
17
  import { applyWhisperEnvelope } from "../../../lib/utils/whisper-format.js";
18
- import { formatTokensK } from "../../../lib/detection/context-usage.js";
19
18
  import { existsSync, readFileSync } from "node:fs";
20
19
  import * as path from "node:path";
21
20
  import { braidDir, tagsSlugFromCwd } from "../../../lib/config/braid-paths.js";
@@ -128,13 +127,14 @@ function sendCompactNudge(pi, evaluated, usage, tokens) {
128
127
  // >= USAGE_TOKENS_ESCALATE (0.85W) escalated wording (archive-or-handoff)
129
128
  // >= HARD_BACKSTOP (0.90W) or usage >= 80 full pipeline message
130
129
  // else light tag/checkout message
131
- // Percent stays as the secondary trigger (sub-1M windows).
132
- const tokensK = formatTokensK(tokens);
130
+ // Percent stays as the secondary trigger (sub-1M windows). The text names
131
+ // the deadline and the action, never the number: the bars own the number,
132
+ // and a percentage copied into prose drifts from the meter.
133
133
  const pipelineMsg = tokens >= USAGE_TOKENS_ESCALATE()
134
- ? `Context at ${Math.round(usage)}% (~${tokensK} tokens). Escalated: archive the current phase with context_compress(action="archive"), or hand off to a fresh session (write a handoff note first).`
134
+ ? `Escalated: an armed compaction fires when the run settles. Archive the current phase with context_compress(action="archive"), or hand off to a fresh session (write a handoff note first).`
135
135
  : usage >= 80 || tokens >= HYGIENE_AUTO_COMPACT_HARD_BACKSTOP()
136
- ? `Context at ${Math.round(usage)}% (~${tokensK} tokens). Pipeline: context_navigate(action="tag") -> context_navigate(action="checkout") -> context_compress(action="archive") -> context_compress(action="slide").`
137
- : `Context at ${Math.round(usage)}% (~${tokensK} tokens). Tag with context_navigate(action="tag"), then context_navigate(action="checkout") to branch with a summary.`;
136
+ ? `An armed compaction fires when the run settles. Pipeline: context_navigate(action="tag") -> context_navigate(action="checkout") -> context_compress(action="archive") -> context_compress(action="slide").`
137
+ : `An armed compaction fires when the run settles. Tag with context_navigate(action="tag"), then context_navigate(action="checkout") to branch with a summary before the next task.`;
138
138
  sendTrackedMessage(pi, {
139
139
  customType: "context-lifecycle",
140
140
  content: [
@@ -145,7 +145,7 @@ function sendCompactNudge(pi, evaluated, usage, tokens) {
145
145
  ],
146
146
  display: true,
147
147
  details: { [BRAID_INJECTED]: true, [BRAID_SOURCE]: "context-lifecycle/compact-suggestion" },
148
- }, { delivery: "park", deliverAs: "steer" }, { type: "context", source: "context-lifecycle/compact-suggestion" });
148
+ }, { deliverAs: "nextTurn" }, { type: "context", source: "context-lifecycle/compact-suggestion" });
149
149
  log.info(`Suggested compact: ${evaluated.policy.name} (context ${Math.round(usage)}%, ` +
150
150
  `priority ${evaluated.policy.priority})`);
151
151
  }
@@ -225,7 +225,7 @@ function executeAction(evaluated, pi, ctx, usage, branchLength) {
225
225
  customType: "context-lifecycle",
226
226
  content: [{ type: "text", text: msg }],
227
227
  display: true,
228
- }, { delivery: "park", deliverAs: "steer" }, { type: "context", source: "context-lifecycle/nudge" });
228
+ }, { deliverAs: "nextTurn" }, { type: "context", source: "context-lifecycle/nudge" });
229
229
  }
230
230
  break;
231
231
  }
@@ -246,7 +246,8 @@ function hasConcreteCompressionSignal(evaluated) {
246
246
  /**
247
247
  * Proposals triggered by PERSISTENT conditions - usage %, token counts,
248
248
  * density - stay true across turns, so the policy re-fires every cooldown
249
- * with a fresh copy of the SAME advice ("Context at 55%. Consider archive").
249
+ * with a fresh copy of the SAME advice ("an armed compaction fires when the
250
+ * run settles").
250
251
  * This is the measured 33% exact-repeat class. Event-triggered proposals
251
252
  * (topic_shift, task_boundary, task_complexity, decision_density,
252
253
  * task_completion_candidate) fire on discrete moments and are NOT this class
@@ -486,7 +487,7 @@ async function queueProposal(evaluated, pi, ctx, branchLength) {
486
487
  customType: "context-lifecycle",
487
488
  content: [{ type: "text", text: msg }],
488
489
  display: true,
489
- }, { deliverAs: "steer", triggerTurn: true }, { type: "context", source: "context-lifecycle/phase-boundary-enforcement" });
490
+ }, { deliverAs: "nextTurn" }, { type: "context", source: "context-lifecycle/phase-boundary-enforcement" });
490
491
  // Track navigation whisper for escalation monitoring
491
492
  state(ctx).lastNavigationWhisperTurn = state(ctx).turnCount;
492
493
  }
@@ -19,6 +19,8 @@ export interface AuditResult {
19
19
  };
20
20
  /** How the usage number was produced (live working set vs fallback). */
21
21
  usageSource: string;
22
+ /** The short provenance word for the number: measured or estimated. */
23
+ usageSourceKind: "measured" | "estimated" | "unavailable";
22
24
  /** Whole-branch token sum - labeled "not sent" wherever displayed. */
23
25
  branchTokens: number;
24
26
  branchLength: number;
@@ -1,6 +1,6 @@
1
1
  import { getContextUsage } from "../../../lib/detection/context-tiers.js";
2
2
  import { formatTokensK } from "../../../lib/detection/context-usage.js";
3
- import { measureLiveUsage, tokenArms, resolveWindow, } from "../../../lib/detection/context-usage.js";
3
+ import { describeUsage, measureLiveUsage, tokenArms, resolveWindow, } from "../../../lib/detection/context-usage.js";
4
4
  import { CONTEXT_COMPACT_REFUSE_PERCENT } from "../../../lib/detection/context-thresholds.js";
5
5
  import { isInternal } from "./handlers/shared.js";
6
6
  // isInternal comes from ./handlers/shared.js — the canonical list shared
@@ -38,6 +38,7 @@ export function analyzeSession(ctx) {
38
38
  const tree = sm.getTree();
39
39
  let usage = { percent: 0, tokens: 0, contextWindow: 0 };
40
40
  let usageSource = "unavailable";
41
+ let usageSourceKind = "unavailable";
41
42
  let branchTokens = 0;
42
43
  try {
43
44
  const live = measureLiveUsage(ctx);
@@ -47,7 +48,8 @@ export function analyzeSession(ctx) {
47
48
  tokens: live.tokens,
48
49
  contextWindow: live.contextWindow,
49
50
  };
50
- usageSource = `session tree (${live.windowSource} window)`;
51
+ usageSource = `session tree, ${live.windowSource} window, ${describeUsage(live)}`;
52
+ usageSourceKind = live.source;
51
53
  branchTokens = live.branchTokens;
52
54
  }
53
55
  else {
@@ -61,6 +63,7 @@ export function analyzeSession(ctx) {
61
63
  contextWindow: ctxUsage?.contextWindow ?? window.contextWindow,
62
64
  };
63
65
  usageSource = "ctx.getContextUsage fallback";
66
+ usageSourceKind = "estimated";
64
67
  branchTokens = usage.tokens;
65
68
  }
66
69
  }
@@ -233,6 +236,7 @@ export function analyzeSession(ctx) {
233
236
  return {
234
237
  usage,
235
238
  usageSource,
239
+ usageSourceKind,
236
240
  branchTokens,
237
241
  branchLength: branch.length,
238
242
  treeDepth: tree.length,
@@ -85,7 +85,7 @@ export async function handleOverflowFailure(pi, event, ctx, errorMessage) {
85
85
  try {
86
86
  const analysis = await analyzeSession(ctx);
87
87
  if (analysis.usage.percent >= 75) {
88
- log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% - triggering emergency rotation (overflow)`);
88
+ log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% ${analysis.usageSourceKind} - triggering emergency rotation (overflow)`);
89
89
  triggerEmergencyRotation(pi, ctx);
90
90
  return;
91
91
  }
@@ -150,7 +150,7 @@ export async function handleTransientError(pi, event, ctx, errorMessage) {
150
150
  try {
151
151
  const analysis = await analyzeSession(ctx);
152
152
  if (analysis.usage.percent >= 75) {
153
- log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% - triggering emergency rotation (transient)`);
153
+ log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% ${analysis.usageSourceKind} - triggering emergency rotation (transient)`);
154
154
  triggerEmergencyRotation(pi, ctx);
155
155
  return;
156
156
  }
@@ -252,7 +252,7 @@ export async function handleThresholdFailure(pi, event, ctx, errorMessage) {
252
252
  try {
253
253
  const analysis = await analyzeSession(ctx);
254
254
  if (analysis.usage.percent >= 75) {
255
- log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% - triggering emergency rotation (threshold)`);
255
+ log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% ${analysis.usageSourceKind} - triggering emergency rotation (threshold)`);
256
256
  triggerEmergencyRotation(pi, ctx);
257
257
  return;
258
258
  }
@@ -15,6 +15,8 @@ import { determineCompressionLevel } from "../../../../lib/detection/compression
15
15
  import { semanticCompress } from "../semantic-compress.js";
16
16
  import { updateContextDensity } from "../../../heartbeat/analytics/index.js";
17
17
  import { AGENT_END } from "../../../../lib/core/event-names.js";
18
+ import { clearRequestShapeFailure, noteRequestShapeFailure, } from "../../../../lib/utils/wake-gate.js";
19
+ import { isContextLengthRequestShape } from "../../../../lib/errors/llm-error.js";
18
20
  import { log, getCmState, compactionRetryState, overflowRetryState, COMPACTION_RETRY_MAX_ATTEMPTS, OVERFLOW_RETRY_MAX_ATTEMPTS, COMPACTION_RETRY_CUSTOM_TYPE, resetCompactionRetry, resetOverflowRetry, getCompactionRetryDelay, getOverflowRetryDelay, } from "./shared.js";
19
21
  export function registerAgentEndRetryHandler(pi) {
20
22
  pi.on(AGENT_END, async (event, ctx) => {
@@ -112,9 +114,19 @@ export function registerAgentEndApiErrorHandler(pi) {
112
114
  break;
113
115
  }
114
116
  }
115
- if (!lastAssistant || lastAssistant.stopReason !== "error")
117
+ if (!lastAssistant || lastAssistant.stopReason !== "error") {
118
+ // A turn that ended without an error means a request fit and came back:
119
+ // the shape verdict from an earlier refusal no longer applies.
120
+ clearRequestShapeFailure();
116
121
  return;
122
+ }
117
123
  const finalError = lastAssistant.errorMessage ?? "Unknown error";
124
+ // A context-length refusal is the request's shape, not the provider's
125
+ // mood. Record it here so the wake gate can keep failed-open wakes from
126
+ // re-firing a request that cannot succeed.
127
+ if (isContextLengthRequestShape(finalError)) {
128
+ noteRequestShapeFailure(finalError.slice(0, 200));
129
+ }
118
130
  sendTrackedMessage(pi, {
119
131
  customType: "context",
120
132
  content: [
@@ -13,7 +13,6 @@
13
13
  */
14
14
  import { Type } from "typebox";
15
15
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
16
- import { type TurnBoundary } from "../../../../../lib/events/turn-boundary.js";
17
16
  /**
18
17
  * Read the pending queue without creating state (inspect surfaces it).
19
18
  * Exported so context_inspect and the heartbeat advisory can report
@@ -32,8 +31,8 @@ export declare function readPendingCompactions(ctx: any): Array<{
32
31
  export declare function hasPendingLlmCompaction(ctx: any): boolean;
33
32
  /**
34
33
  * One pending-state line for the armed-but-unfired compaction queue
35
- * ("slide armed 17:28 — fires at the next turn boundary; live usage drops
36
- * when it lands"). Null when nothing is pending: no surface may fabricate an
34
+ * ("slide armed 17:28 — fires when the run settles; live usage drops when it
35
+ * lands"). Null when nothing is pending: no surface may fabricate an
37
36
  * expectation of a drop that is not armed. Shared by context_inspect and the
38
37
  * heartbeat advisory so both state the same fact the same way.
39
38
  */
@@ -61,20 +60,17 @@ export declare function resolveAutoSlideKeep(branchLength: number): number;
61
60
  * Usage-driven auto-arm: when live usage sits above the configured threshold
62
61
  * for `confirmTicks` consecutive observations, arm ONE deterministic slide so
63
62
  * a session that never gets a manual cleanup still gets relief. Reuses the
64
- * accounting context_inspect computes (analyzeSession), the same pending
65
- * queue the tool arms drain through, and the same boundary discipline: arming
66
- * only queues; the compaction itself still fires at the next turn boundary or
67
- * settle, never mid-run.
63
+ * accounting context_inspect computes (analyzeSession) and the same pending
64
+ * queue the tool arms drain through: arming only queues; the compaction itself
65
+ * fires when the run settles (or at the 0.90W backstop), never mid-run.
68
66
  *
69
67
  * Called from the heartbeat tick — the only cadence that runs while a session
70
- * works, and the only arm site that runs inside a turn boundary dispatch. It
71
- * hands that boundary in, so the arm is judged by the same rule the drain
72
- * applies: a "toolUse" boundary below the 0.90W backstop leaves the entry
73
- * queued for the next loop-done boundary instead of aborting the request the
74
- * loop is about to dispatch. Returns what happened and why, so the caller can
75
- * log it.
68
+ * works. Arming only queues: the entry waits for `agent_settled`, because the
69
+ * tick runs while the run is live and nothing at that point can prove the loop
70
+ * has no request left to dispatch. Returns what happened and why, so the
71
+ * caller can log it.
76
72
  */
77
- export declare function maybeArmAutoCompaction(pi: ExtensionAPI, ctx: any, boundary?: TurnBoundary): {
73
+ export declare function maybeArmAutoCompaction(pi: ExtensionAPI, ctx: any): {
78
74
  armed: boolean;
79
75
  reason: string;
80
76
  };
@@ -19,10 +19,9 @@ import { analyzeSession } from "../../analysis.js";
19
19
  import * as timerMod from "../../../../scheduling/timer/index.js";
20
20
  import { getState } from "../../../../enforcement/state.js";
21
21
  import { CONTEXT_COMPACT_REFUSE_PERCENT } from "../../../../../lib/detection/context-thresholds.js";
22
- import { turnBoundaryMayAbortRun, } from "../../../../../lib/events/turn-boundary.js";
23
22
  import { getCmState, isCompactionActive, log, recordNavigationAction } from "../shared.js";
24
23
  import { snapBoundaryOutsideToolBatch } from "../tool-batch-boundary.js";
25
- import { formatTokensK } from "../../../../../lib/detection/context-usage.js";
24
+ import { formatTokensK, tokenArms } from "../../../../../lib/detection/context-usage.js";
26
25
  import { formatLocalTime } from "../../../../../lib/utils/local-time.js";
27
26
  import { getAutoCompactConfig, } from "../../../../../lib/config/braid-settings.js";
28
27
  // Helpers
@@ -109,8 +108,8 @@ function getBatchSettleState(ctx) {
109
108
  /**
110
109
  * Release the call ids a turn's persisted tool results account for. A result
111
110
  * with no usable id is ignored: an unmatched active id stays protective, so a
112
- * malformed event can only delay a drain to a later boundary or the settle
113
- * backstop, never release a sibling that is still executing.
111
+ * malformed event can only delay a drain to the settle backstop, never
112
+ * release a sibling that is still executing.
114
113
  */
115
114
  function releaseSettledToolCallIds(st, toolResults) {
116
115
  if (!Array.isArray(toolResults))
@@ -150,8 +149,8 @@ export function hasPendingLlmCompaction(ctx) {
150
149
  }
151
150
  /**
152
151
  * One pending-state line for the armed-but-unfired compaction queue
153
- * ("slide armed 17:28 — fires at the next turn boundary; live usage drops
154
- * when it lands"). Null when nothing is pending: no surface may fabricate an
152
+ * ("slide armed 17:28 — fires when the run settles; live usage drops when it
153
+ * lands"). Null when nothing is pending: no surface may fabricate an
155
154
  * expectation of a drop that is not armed. Shared by context_inspect and the
156
155
  * heartbeat advisory so both state the same fact the same way.
157
156
  */
@@ -162,7 +161,7 @@ export function formatPendingCompactionsLine(ctx) {
162
161
  const newest = pending.reduce((a, b) => (b.armedAt > a.armedAt ? b : a));
163
162
  const kinds = [...new Set(pending.map((p) => p.kind))].join("+");
164
163
  const armedClock = formatLocalTime(new Date(newest.armedAt));
165
- return (`${kinds} armed ${armedClock} — fires at the next turn boundary (turn end or run settle); ` +
164
+ return (`${kinds} armed ${armedClock} — fires when the run settles (or at the 0.90W backstop); ` +
166
165
  `until then live usage reads pre-compaction state`);
167
166
  }
168
167
  /**
@@ -260,20 +259,7 @@ export function scheduleDegradedCompact(trigger) {
260
259
  setTimeout(trigger, DEGRADED_DEFERRAL_MS);
261
260
  }
262
261
  /**
263
- * Whether an arm may fire its own entry. Firing a compact aborts whatever run
264
- * is live, so an arm that happens inside a turn boundary dispatch hands that
265
- * boundary in and is judged by the same rule the TURN_END handler applies
266
- * (the rule lives in lib/events/turn-boundary.ts; it owns the "no boundary
267
- * known" case, which fires). Every other arm site runs inside a tool call,
268
- * where there is no boundary to read and the prior contract stands: the arm
269
- * drains unless a batch is still active (the arm's own call id keeps it
270
- * parked, so it does not fire there).
271
- */
272
- function armMayDrainNow(boundary, ctx) {
273
- return turnBoundaryMayAbortRun(boundary, () => captureUsage(ctx));
274
- }
275
- /**
276
- * Arm a one-shot compaction at a safe boundary (next turn end or run settle).
262
+ * Arm a one-shot compaction for the settle drain (or the 0.90W backstop).
277
263
  * Returns "pending-exists" when an LLM-class compaction is already armed: the
278
264
  * caller must NOT have written its own range/anchor state in that case (the
279
265
  * drain fires the first-armed trigger with the FIRST declaration's state).
@@ -285,7 +271,7 @@ function armMayDrainNow(boundary, ctx) {
285
271
  */
286
272
  function scheduleCompactionAtBatchSettle(pi, ctx, options, meta = {
287
273
  kind: "compact",
288
- }, boundary) {
274
+ }) {
289
275
  const trigger = () => {
290
276
  try {
291
277
  // Signal to session_compact handler that this is agent-initiated
@@ -306,7 +292,7 @@ function scheduleCompactionAtBatchSettle(pi, ctx, options, meta = {
306
292
  // coalesces them to the earliest cut.
307
293
  if (isLlmClass(meta.kind) && st.pending.some((p) => isLlmClass(p.kind))) {
308
294
  log.info(`[context-compress] ${meta.kind} arm refused: an LLM-class compaction is ` +
309
- `already armed and will fire at the next boundary.`);
295
+ `already armed and will fire when the run settles.`);
310
296
  return "pending-exists";
311
297
  }
312
298
  st.pending.push({ trigger, armedAt: Date.now(), ...meta });
@@ -315,14 +301,11 @@ function scheduleCompactionAtBatchSettle(pi, ctx, options, meta = {
315
301
  log.warn(`[context-compress] Pending queue overflow: dropped the newest armed ${dropped?.kind}` +
316
302
  ` (cap ${PENDING_COMPACT_QUEUE_MAX}); the first-armed entry still fires.`);
317
303
  }
318
- // Arming fires only where that is safe. Firing a compaction aborts whatever
319
- // run is live, and an arm site is not in a position to tell: the tool path
320
- // arms inside its own call (whose id parks the queue anyway), and the
321
- // heartbeat's arm runs inside a turn_end dispatch, where whether the loop
322
- // still has work to dispatch is a fact the event carries. That caller hands
323
- // its boundary in; every other caller keeps the prior contract.
324
- if (armMayDrainNow(boundary, ctx))
325
- firePendingCompactionsIfSettled(ctx, st);
304
+ // Arming never fires. Every arm site runs while the run is live - inside
305
+ // the tool call that asked for it, or inside the heartbeat's turn_end
306
+ // dispatch - and no arm site can see the steering queue that decides
307
+ // whether another request follows. The entry waits for the settle drain or
308
+ // the 0.90W backstop.
326
309
  return "queued";
327
310
  }
328
311
  catch {
@@ -344,10 +327,10 @@ function scheduleCompactionAtBatchSettle(pi, ctx, options, meta = {
344
327
  * and the usage-driven auto-arm, so both produce the same cut shape: the
345
328
  * boundary is snapped out of any tool batch, the slide state is persisted for
346
329
  * the SLIDE_MODE compaction branch, an audit entry is appended, and the
347
- * trigger is queued for the next safe boundary. Returns null when the branch
348
- * is not longer than the keep window (nothing to slide).
330
+ * trigger is queued for the settle drain. Returns null when the branch is not
331
+ * longer than the keep window (nothing to slide).
349
332
  */
350
- function armSlideCompaction(pi, ctx, keepCount, boundary) {
333
+ function armSlideCompaction(pi, ctx, keepCount) {
351
334
  const sm = ctx.sessionManager;
352
335
  if (!sm || typeof sm.getBranch !== "function")
353
336
  return null;
@@ -395,7 +378,7 @@ function armSlideCompaction(pi, ctx, keepCount, boundary) {
395
378
  catch {
396
379
  // Non-fatal
397
380
  }
398
- scheduleCompactionAtBatchSettle(pi, ctx, { customInstructions: "SLIDE_MODE:true" }, { kind: "slide", cutEntryId }, boundary);
381
+ scheduleCompactionAtBatchSettle(pi, ctx, { customInstructions: "SLIDE_MODE:true" }, { kind: "slide", cutEntryId });
399
382
  return { cutEntryId, keptCount, droppedCount };
400
383
  }
401
384
  /**
@@ -416,20 +399,17 @@ function getAutoArmState(ctx) {
416
399
  * Usage-driven auto-arm: when live usage sits above the configured threshold
417
400
  * for `confirmTicks` consecutive observations, arm ONE deterministic slide so
418
401
  * a session that never gets a manual cleanup still gets relief. Reuses the
419
- * accounting context_inspect computes (analyzeSession), the same pending
420
- * queue the tool arms drain through, and the same boundary discipline: arming
421
- * only queues; the compaction itself still fires at the next turn boundary or
422
- * settle, never mid-run.
402
+ * accounting context_inspect computes (analyzeSession) and the same pending
403
+ * queue the tool arms drain through: arming only queues; the compaction itself
404
+ * fires when the run settles (or at the 0.90W backstop), never mid-run.
423
405
  *
424
406
  * Called from the heartbeat tick — the only cadence that runs while a session
425
- * works, and the only arm site that runs inside a turn boundary dispatch. It
426
- * hands that boundary in, so the arm is judged by the same rule the drain
427
- * applies: a "toolUse" boundary below the 0.90W backstop leaves the entry
428
- * queued for the next loop-done boundary instead of aborting the request the
429
- * loop is about to dispatch. Returns what happened and why, so the caller can
430
- * log it.
407
+ * works. Arming only queues: the entry waits for `agent_settled`, because the
408
+ * tick runs while the run is live and nothing at that point can prove the loop
409
+ * has no request left to dispatch. Returns what happened and why, so the
410
+ * caller can log it.
431
411
  */
432
- export function maybeArmAutoCompaction(pi, ctx, boundary) {
412
+ export function maybeArmAutoCompaction(pi, ctx) {
433
413
  const config = getAutoCompactConfig();
434
414
  if (!config.enabled)
435
415
  return { armed: false, reason: "disabled" };
@@ -452,13 +432,13 @@ export function maybeArmAutoCompaction(pi, ctx, boundary) {
452
432
  }
453
433
  const branchLength = ctx?.sessionManager?.getBranch?.().length ?? 0;
454
434
  const keep = resolveAutoSlideKeep(branchLength);
455
- const armed = armSlideCompaction(pi, ctx, keep, boundary);
435
+ const armed = armSlideCompaction(pi, ctx, keep);
456
436
  st.aboveCount = 0;
457
437
  if (!armed)
458
438
  return { armed: false, reason: "branch-too-short" };
459
439
  log.info(`[context-compress] Auto-arm: usage sustained at ${usage.percent.toFixed(1)}% ` +
460
440
  `(>= ${config.armPercent}% for ${config.confirmTicks} observations) — slide armed ` +
461
- `(${armed.droppedCount} entries before the cut), fires at the next boundary.`);
441
+ `(${armed.droppedCount} entries before the cut), fires when the run settles.`);
462
442
  return { armed: true, reason: `usage ${usage.percent.toFixed(1)}% sustained` };
463
443
  }
464
444
  // Schema
@@ -513,9 +493,9 @@ export const contextCompressSchema = Type.Object({
513
493
  });
514
494
  export function registerContextCompress(pi) {
515
495
  // Batch-settle scheduling: track the ACTIVE tool calls of every running
516
- // batch by call id and fire the deferred compaction only at a safe boundary
517
- // (a loop-done turn_end or agent_settled). Never mid-batch (would drop a
518
- // parallel sibling's result) and never at tool_execution_end (the run is
496
+ // batch by call id and fire the deferred compaction when the run settles
497
+ // (plus the 0.90W backstop at a turn boundary). Never mid-batch (would drop
498
+ // a parallel sibling's result) and never at tool_execution_end (the run is
519
499
  // still live there — an aborting compact would surface a spurious "This
520
500
  // operation was aborted" error and tear the finishing turn).
521
501
  onEvent(pi, TOOL_EXECUTION_START, (event, ctx) => {
@@ -524,7 +504,7 @@ export function registerContextCompress(pi) {
524
504
  st.activeToolCallIds.add(toolCallIdOf(event) ?? UNIDENTIFIED_TOOL_CALL);
525
505
  }
526
506
  catch {
527
- // Settle tracking is unavailable — the pending compact then only fires
507
+ // Settle tracking is unavailable — the pending compact then fires only
528
508
  // via AGENT_SETTLED below, which is the conservative path.
529
509
  }
530
510
  });
@@ -538,8 +518,8 @@ export function registerContextCompress(pi) {
538
518
  // NOTE: do NOT fire here. The run is still active (the agent is
539
519
  // processing this tool's result and streaming its next response); an
540
520
  // aborting compact now would surface a spurious "This operation was
541
- // aborted" error and tear the finishing turn. Safe boundaries are
542
- // turn_end (below) and agent_settled.
521
+ // aborted" error and tear the finishing turn. The settle drain owns the
522
+ // fire.
543
523
  }
544
524
  catch {
545
525
  // Settle tracking unavailable — see TOOL_EXECUTION_START above; the
@@ -547,24 +527,19 @@ export function registerContextCompress(pi) {
547
527
  }
548
528
  });
549
529
  onEvent(pi, TURN_END, (event, ctx) => {
550
- // Turn boundary. The turn's assistant message and tool results are already
551
- // persisted here, but that alone does not make the run safe to abort: a
552
- // "toolUse" stop means the loop dispatches its next request the moment the
553
- // handlers return, so the deferred ctx.compact() tears that request
554
- // mid-stream and the compaction replaces the work it was about to do (the
555
- // rule is lib/events/turn-boundary.ts, and its residual section lists the
556
- // two cases a loop-done stop reason does not rule out). Only a loop-done
557
- // boundary drains, except at the 0.90W hard backstop, which exists
558
- // precisely to stop a runaway live loop before it overflows.
530
+ // The 0.90W hard backstop, the ONLY drain that fires while the run may
531
+ // still dispatch. Below it the queue waits for `agent_settled`: the loop
532
+ // polls its steering queue after this dispatch and a single queued steer
533
+ // starts another request, which the deferred ctx.compact() would abort.
534
+ // Above it the overflow is the worse failure: a run kept alive by
535
+ // continuous steers never settles, and without this cut the queue stays
536
+ // armed until the context is gone.
559
537
  //
560
538
  // The persisted results carry the toolCallIds of the calls they answer,
561
539
  // which releases a call whose tool_execution_end never arrived; an active
562
540
  // id with NO result in this event is kept (it may still be executing, and
563
- // a count could not tell which sibling completed). A run kept alive by
564
- // continuous steers never reaches agent_settled — this boundary keeps an
565
- // armed compaction from stalling behind live work. Ids are never blanket-
566
- // reset here (only agent_settled owns that backstop, which is what keeps a
567
- // missed end event from parking the queue forever).
541
+ // a count could not tell which sibling completed). The active set is never
542
+ // blanket-reset here; agent_settled owns that release.
568
543
  try {
569
544
  const st = getBatchSettleState(ctx);
570
545
  releaseSettledToolCallIds(st, event?.toolResults);
@@ -572,24 +547,23 @@ export function registerContextCompress(pi) {
572
547
  return;
573
548
  if (isCompactionActive(ctx))
574
549
  return;
575
- if (!turnBoundaryMayAbortRun(event, () => captureUsage(ctx)))
550
+ const usage = captureUsage(ctx);
551
+ if (!usage || usage.tokens < tokenArms(usage.contextWindow).backstop)
576
552
  return;
577
553
  firePendingCompactionsIfSettled(ctx, st);
578
554
  }
579
555
  catch {
580
- // A failed boundary drain must not tear the turn_end event pipeline;
581
- // the pending compactions retry on the next boundary.
556
+ // A failed backstop check must not tear the turn_end event pipeline;
557
+ // the queue stays armed for the settle drain.
582
558
  }
583
559
  });
584
560
  onEvent(pi, AGENT_SETTLED, (_event, ctx) => {
585
- // Backstop boundary: the run has fully settled, so ctx.compact()'s
586
- // abort() is a clean no-op — no spurious abort error, no torn turn, and
587
- // the post-compaction resume wake lands when the session is
588
- // idle/promptable. The whole pending queue drains here (coalesced); the
589
- // active set is cleared so parked compactions always fire even when a
590
- // start never saw its end and no turn boundary ever accounted for it.
591
- // Turn boundaries drain first when a run stays alive; this handler catches
592
- // everything they cannot reach.
561
+ // The one unconditional drain: `agent_settled` is emitted after the run
562
+ // is no longer active, so ctx.compact()'s abort() is a clean no-op — no
563
+ // torn request, and the post-compaction resume wake lands when the
564
+ // session is idle/promptable. The whole pending queue drains here
565
+ // (coalesced), and the active set is cleared first so a parked compaction
566
+ // always fires even when a start never saw its end.
593
567
  try {
594
568
  const st = getBatchSettleState(ctx);
595
569
  st.activeToolCallIds.clear();
@@ -659,7 +633,7 @@ export function registerContextCompress(pi) {
659
633
  ` Before: ${usageLine2}`,
660
634
  ` Keep recent: ${params?.keep ?? "auto"}`,
661
635
  ``,
662
- `Compaction armed; it fires at the next turn boundary (turn end or run settle) — live usage will NOT drop until it lands.`,
636
+ `Compaction armed; it fires when the run settles — live usage will NOT drop until it lands.`,
663
637
  `Agent will resume automatically after compaction completes.`,
664
638
  `Run context_inspect(detail='quick') after resume to verify.`,
665
639
  ].join("\n"),
@@ -733,7 +707,7 @@ export function registerContextCompress(pi) {
733
707
  };
734
708
  }
735
709
  // LLM-class dedup: refuse BEFORE any state write. An already-armed
736
- // compaction fires at the next boundary with the FIRST declaration's
710
+ // compaction fires when the run settles with the FIRST declaration's
737
711
  // range; a second arm here would overwrite rangeMode (clobber-class
738
712
  // loss) and queue an entry that can never fire.
739
713
  if (hasPendingLlmCompaction(ctx)) {
@@ -742,7 +716,7 @@ export function registerContextCompress(pi) {
742
716
  {
743
717
  type: "text",
744
718
  text: [
745
- `**Archive skipped — a compaction is already armed and will fire at the next turn boundary.**`,
719
+ `**Archive skipped — a compaction is already armed and will fire when the run settles.**`,
746
720
  `Nothing was recorded for "${topic}"; the pending compaction covers the cleanup.`,
747
721
  `After it lands, re-run this archive if the range still needs a record.`,
748
722
  ].join("\n"),
@@ -1013,8 +987,8 @@ export function registerContextCompress(pi) {
1013
987
  if (usageBefore) {
1014
988
  feedbackLines.push(` Before: ${usageBefore.percent.toFixed(1)}% used (${formatTokensK(usageBefore.tokens)} tokens)`);
1015
989
  }
1016
- feedbackLines.push("", "Compaction is armed and fires at the next turn boundary (turn end or run settle) — it may " +
1017
- "land while the run stays alive; live usage will NOT drop until it fires.", "Verify after it lands: context_inspect(detail='quick') shows the drop and any still-pending arm.");
990
+ feedbackLines.push("", "Compaction is armed and fires when the run settles — live usage " +
991
+ "will NOT drop until it fires.", "Verify after it lands: context_inspect(detail='quick') shows the drop and any still-pending arm.");
1018
992
  // Cancel any stale resume timer from a previous compaction cycle.
1019
993
  try {
1020
994
  const sessionId = ctx?.sessionManager?.getSessionId?.() ?? "anonymous";
@@ -1082,7 +1056,7 @@ export function registerContextCompress(pi) {
1082
1056
  };
1083
1057
  }
1084
1058
  // LLM-class dedup (same contract as archive): an armed compaction
1085
- // fires at the next boundary; refuse before writing the tag or the
1059
+ // fires when the run settles; refuse before writing the tag or the
1086
1060
  // archive anchor so the first declaration stands unmodified.
1087
1061
  if (hasPendingLlmCompaction(ctx)) {
1088
1062
  return {
@@ -1090,7 +1064,7 @@ export function registerContextCompress(pi) {
1090
1064
  {
1091
1065
  type: "text",
1092
1066
  text: [
1093
- `**Deep clean skipped — a compaction is already armed and will fire at the next turn boundary.**`,
1067
+ `**Deep clean skipped — a compaction is already armed and will fire when the run settles.**`,
1094
1068
  `Nothing was tagged for "${topic}"; the pending compaction covers the cleanup.`,
1095
1069
  ].join("\n"),
1096
1070
  },
@@ -1140,7 +1114,7 @@ export function registerContextCompress(pi) {
1140
1114
  ` 2. ~${count} entries before the tag point, estimated`,
1141
1115
  ` 3. Compaction scheduled${usageLine}`,
1142
1116
  "",
1143
- `Compaction armed; it fires at the next turn boundary (turn end or run settle) — live usage will NOT drop until it lands.`,
1117
+ `Compaction armed; it fires when the run settles — live usage will NOT drop until it lands.`,
1144
1118
  `Agent will resume automatically after compaction completes.`,
1145
1119
  `Run context_inspect(detail='quick') after resume to verify.`,
1146
1120
  "",
@@ -1266,7 +1240,7 @@ export function registerContextCompress(pi) {
1266
1240
  ` ~${droppedCount} entries before the slide point, estimated`,
1267
1241
  ` Before: ${usageLine}`,
1268
1242
  ``,
1269
- `Compaction armed; it fires at the next turn boundary (turn end or run settle) — live usage will NOT drop until it lands.`,
1243
+ `Compaction armed; it fires when the run settles — live usage will NOT drop until it lands.`,
1270
1244
  `Agent will resume automatically after compaction completes.`,
1271
1245
  `Run context_inspect(detail='quick') after resume to verify.`,
1272
1246
  ].join("\n"),
@@ -20,7 +20,8 @@
20
20
  * 3. tunnel-down: ≥ tunnelFailures consecutive getUpdates failures
21
21
  * (telegram emits the transition; this engine hosts the
22
22
  * confirmation gate + escalation).
23
- * - ESCALATE: waking whisper (wakeWhisper) + optional 1-line tg signal
23
+ * - ESCALATE: waking whisper (wakeWhisper) + optional 1-line tg signal,
24
+ * or the quiet whisper when the session's route latch is open
24
25
  * (tgSignal). The FIRST escalation of an open condition always fires
25
26
  * (threshold crossing). Repeats while the condition stays continuously
26
27
  * open are milestone-throttled so one long outage cannot flood the owner
@@ -164,6 +165,12 @@ export interface WatchdogEngineDeps {
164
165
  /** True when a timer/wake is due for this session: a due wake legitimately
165
166
  * keeps a quiet session quiet, so the turn is not classified dead. */
166
167
  isWakeDue?: (key: string) => boolean;
168
+ /** True when a self-started turn would park right now (the session's route
169
+ * has failed every attempt since its last successful call). An escalation
170
+ * is then delivered through `quietWhisper` while the out-of-band signal
171
+ * still fires — the content is not withdrawn, only the turn it would
172
+ * start. Absent or throwing ⇒ never parked (fail-open). */
173
+ isTurnStartBlocked?: () => boolean;
167
174
  log?: (level: "debug" | "info" | "warn" | "error", message: string, ...rest: unknown[]) => void;
168
175
  }
169
176
  /** Scalar-only watchdog observer line (see lib/telemetry/context-heartbeat.ts). */