switchroom 0.21.16 → 0.21.17

package/dist/host-control/main.js

@@ -11144,6 +11144,10 @@ var init_schema = __esm(() => {
     }).optional().describe("Operator-declared, per-specialist Hindsight mental models (RFC " + "Phase 5). Named, opt-in curated reflections this agent's bank should " + "carry — e.g. a coach's 'training-plan-state' or a lawyer's " + "'open-matters'. Ensured idempotently at scaffold/reconcile: NOTHING " + "is created unless declared here (zero declarations = zero models, " + "matching post-#2447 behaviour), and no fixed identity model is " + "reintroduced — 'who the user is' stays owned by dedicated profile " + "banks (users.*.profile_bank), never a per-agent model. Per-agent " + "ONLY: intentionally not accepted at the defaults/profile tier, so a " + "model can never be fleet-seeded — each specialist opts in on its own " + "(the invariant-clean inverse of the retired blind auto-seeding)."),
     observations_mission: exports_external.string().optional().describe("Steers what the observation-consolidation LLM synthesises from raw " + "facts (the higher-order 'what patterns matter' lens). Cascade: override."),
     rules_block: exports_external.boolean().default(false).describe("Memory v2 M3 go-live flag (M1 only DEFINES this, default false; " + "M3 flips it per agent). When true, the sanctioned rules/index " + "blocks render live in this agent's CLAUDE.md (marker-delimited, " + "below the `# --- Yours ---` line) AND the permission deny for " + "direct Edit/Write of the agent's own CLAUDE.md is seeded — the " + "flag couples deny + tools together so a live deny never orphans " + "the invited free-text edit path (the `memory_edit_yours` verb is " + "the only sanctioned writer once flipped). Unset/false ⇒ byte-" + "identical to pre-M1 behaviour: no blocks, no deny, dark build. " + "Cascade: override (per-agent wins over default; never fleet-" + "seeded — each agent's flip is a deliberate M3 rollout step)."),
+    orientation: exports_external.boolean().optional().describe("Memory v2 M5 go-live flag (Surface B: orientation-at-boot), " + "effective default false — dark build (unset ⇒ OFF, applied by the " + "scaffold resolver, NOT a Zod .default() — a hard default here would " + "shadow the per-agent value in the cascade the way it does every other " + "memory knob). When true, the orientation SessionStart " + "hook injects this agent's cron-refreshed `orientation` mental model " + "into context at boot AND re-seats it after every compaction (E-88), " + "deterministically and with zero tool call. Unset/false ⇒ byte-" + "identical to pre-M5 behaviour: the hook no-ops before any bank " + "resolve or network call. Per-agent ONLY (never fleet-seeded — a " + "flip is a deliberate canary/rollout step gated on the agent's " + "m2-residue measurement + operator-created model, carve-M5 §7). " + "Cascade: override (per-agent wins over default)."),
+    orientation_reinject_turns: exports_external.number().int().min(0).optional().describe("Memory v2 M5 optional per-turn re-inject cadence, effective default " + "0 = off (unset ⇒ 0, applied by the scaffold resolver, not a Zod " + ".default() — same cascade-shadowing reason as `orientation`). At 0 the " + "briefing is injected only at SessionStart + compaction (the cheap " + "path). N>0 " + "would additionally re-inject the orientation briefing every N turns; " + "priced at ~55M tok/30d at every-turn, which is WHY it defaults off " + "(carve-M5 §2/§4). Only late-session context loss should ever set it, " + "per-agent, measured. A stripped/absent value fails to 0 (fail-safe " + "AND fail-cheap). Per-agent ONLY. Cascade: override."),
+    orientation_cadence_hours: exports_external.number().int().min(1).optional().describe("Memory v2 M5 per-agent refresh cadence tier (hours), effective " + "default 48 (unset ⇒ 48, applied by the scaffold resolver, not a Zod " + ".default() — a hard default would shadow a `defaults.memory." + "orientation_cadence_hours` fleet value in the cascade). " + "The fast-churning agents (klanker, overlord) set 24; everyone else " + "inherits 48 (carve-M5 §6, Ken's locked tiered cadence). Drives BOTH " + "the out-of-session refresh scheduler AND the staleness guard's " + "per-tier thresholds (stale prefix at 1.5× cadence, cold degrade at " + "3×) — so a fixed 36h can never mislabel a 48h-tier agent as stale a " + "day early. Modelled as an explicit int (not a hard-coded name list) " + "so the tiering is data-driven and auditable. A cost knob, not an " + "enablement knob: a stripped/absent value failing to 48 is safe " + "(the cheaper tier). Cascade: override (per-agent wins over default); " + "unlike `orientation`/`_reinject_turns` it IS accepted at the " + "defaults/profile tier."),
+    inject_directives: exports_external.boolean().optional().describe("Memory v2 M3 Surface-A directive-injection switch (default TRUE — " + "on-by-default via the plugin settings.json stamp + config.py " + "DEFAULTS). When left unset the agent keeps injecting the " + "`<active_directives>` block on every turn, byte-identical to pre-M3. " + "Set FALSE to SUPPRESS that injection for this agent — its standing " + "rules are then served from the live rules block (memory.rules_block) " + "instead of re-injected directives, which is the change that collapses " + "the always-on directive-token spend (E-41). The suppression is " + "fail-safe and re-checked every turn in recall.py: it fires ONLY when " + "a non-empty rules block is physically present in the agent's " + "CLAUDE.md — a false flag with an empty/absent block keeps injecting " + "AND emits a degraded-canary notice, so a zero-standing-rules turn is " + "unreachable. Requires memory.rules_block=true first (the block must " + "be live before injection is turned off — enforce the ordering with " + "`switchroom memory flip`, never a bare flag flip). Coordinates with " + "M4's memory.recall prefetch (memoryPrefetchEnabled): the same guard " + "gates all three recall.py emit sites so a flipped agent leaks no " + "directive on a cache/prefetch hit. Cascade: override, per-agent ONLY " + "(never fleet-seeded from the defaults/profile tier — each flip is a " + "deliberate staggered M3 rollout step, same darkness safeguard as " + "rules_block). Default-true is the fail-safe direction under the " + "Zod-strip footgun: a stripped/misread key keeps the agent injecting."),
     disposition: exports_external.object({
       skepticism: exports_external.number().int().min(1).max(5).optional().describe("How much the bank doubts unverified claims (1-5; engine default 3)."),
       literalism: exports_external.number().int().min(1).max(5).optional().describe("How literally the bank reads statements vs inferring intent (1-5; engine default 3)."),
@@ -11589,6 +11593,7 @@ var init_schema = __esm(() => {
       profile: exports_external.string().optional(),
       directive_capture_nudge: exports_external.boolean().optional(),
       profile_capture_nudge: exports_external.boolean().optional(),
+      orientation_cadence_hours: exports_external.number().int().min(1).optional(),
       anti_confabulation_directive: AntiConfabulationDirectiveSchema,
       observation_scopes: ObservationScopesSchema,
       observation_scope_strategy: ObservationScopeStrategySchema,
@@ -21593,7 +21598,7 @@ function allocateAgentUid(name) {
 }
 
 // src/build-info.ts
-var VERSION = "0.21.16";
+var VERSION = "0.21.17";
 
 // src/setup/hindsight-recall-passthrough.ts
 var HINDSIGHT_RECALL_TAG_WEIGHT_SEED = Object.freeze({ sidechain: 0.8 });

package/dist/vault/approvals/kernel-server.js

@@ -4584,6 +4584,10 @@ var init_schema = __esm(() => {
     }).optional().describe("Operator-declared, per-specialist Hindsight mental models (RFC " + "Phase 5). Named, opt-in curated reflections this agent's bank should " + "carry — e.g. a coach's 'training-plan-state' or a lawyer's " + "'open-matters'. Ensured idempotently at scaffold/reconcile: NOTHING " + "is created unless declared here (zero declarations = zero models, " + "matching post-#2447 behaviour), and no fixed identity model is " + "reintroduced — 'who the user is' stays owned by dedicated profile " + "banks (users.*.profile_bank), never a per-agent model. Per-agent " + "ONLY: intentionally not accepted at the defaults/profile tier, so a " + "model can never be fleet-seeded — each specialist opts in on its own " + "(the invariant-clean inverse of the retired blind auto-seeding)."),
     observations_mission: exports_external.string().optional().describe("Steers what the observation-consolidation LLM synthesises from raw " + "facts (the higher-order 'what patterns matter' lens). Cascade: override."),
     rules_block: exports_external.boolean().default(false).describe("Memory v2 M3 go-live flag (M1 only DEFINES this, default false; " + "M3 flips it per agent). When true, the sanctioned rules/index " + "blocks render live in this agent's CLAUDE.md (marker-delimited, " + "below the `# --- Yours ---` line) AND the permission deny for " + "direct Edit/Write of the agent's own CLAUDE.md is seeded — the " + "flag couples deny + tools together so a live deny never orphans " + "the invited free-text edit path (the `memory_edit_yours` verb is " + "the only sanctioned writer once flipped). Unset/false ⇒ byte-" + "identical to pre-M1 behaviour: no blocks, no deny, dark build. " + "Cascade: override (per-agent wins over default; never fleet-" + "seeded — each agent's flip is a deliberate M3 rollout step)."),
+    orientation: exports_external.boolean().optional().describe("Memory v2 M5 go-live flag (Surface B: orientation-at-boot), " + "effective default false — dark build (unset ⇒ OFF, applied by the " + "scaffold resolver, NOT a Zod .default() — a hard default here would " + "shadow the per-agent value in the cascade the way it does every other " + "memory knob). When true, the orientation SessionStart " + "hook injects this agent's cron-refreshed `orientation` mental model " + "into context at boot AND re-seats it after every compaction (E-88), " + "deterministically and with zero tool call. Unset/false ⇒ byte-" + "identical to pre-M5 behaviour: the hook no-ops before any bank " + "resolve or network call. Per-agent ONLY (never fleet-seeded — a " + "flip is a deliberate canary/rollout step gated on the agent's " + "m2-residue measurement + operator-created model, carve-M5 §7). " + "Cascade: override (per-agent wins over default)."),
+    orientation_reinject_turns: exports_external.number().int().min(0).optional().describe("Memory v2 M5 optional per-turn re-inject cadence, effective default " + "0 = off (unset ⇒ 0, applied by the scaffold resolver, not a Zod " + ".default() — same cascade-shadowing reason as `orientation`). At 0 the " + "briefing is injected only at SessionStart + compaction (the cheap " + "path). N>0 " + "would additionally re-inject the orientation briefing every N turns; " + "priced at ~55M tok/30d at every-turn, which is WHY it defaults off " + "(carve-M5 §2/§4). Only late-session context loss should ever set it, " + "per-agent, measured. A stripped/absent value fails to 0 (fail-safe " + "AND fail-cheap). Per-agent ONLY. Cascade: override."),
+    orientation_cadence_hours: exports_external.number().int().min(1).optional().describe("Memory v2 M5 per-agent refresh cadence tier (hours), effective " + "default 48 (unset ⇒ 48, applied by the scaffold resolver, not a Zod " + ".default() — a hard default would shadow a `defaults.memory." + "orientation_cadence_hours` fleet value in the cascade). " + "The fast-churning agents (klanker, overlord) set 24; everyone else " + "inherits 48 (carve-M5 §6, Ken's locked tiered cadence). Drives BOTH " + "the out-of-session refresh scheduler AND the staleness guard's " + "per-tier thresholds (stale prefix at 1.5× cadence, cold degrade at " + "3×) — so a fixed 36h can never mislabel a 48h-tier agent as stale a " + "day early. Modelled as an explicit int (not a hard-coded name list) " + "so the tiering is data-driven and auditable. A cost knob, not an " + "enablement knob: a stripped/absent value failing to 48 is safe " + "(the cheaper tier). Cascade: override (per-agent wins over default); " + "unlike `orientation`/`_reinject_turns` it IS accepted at the " + "defaults/profile tier."),
+    inject_directives: exports_external.boolean().optional().describe("Memory v2 M3 Surface-A directive-injection switch (default TRUE — " + "on-by-default via the plugin settings.json stamp + config.py " + "DEFAULTS). When left unset the agent keeps injecting the " + "`<active_directives>` block on every turn, byte-identical to pre-M3. " + "Set FALSE to SUPPRESS that injection for this agent — its standing " + "rules are then served from the live rules block (memory.rules_block) " + "instead of re-injected directives, which is the change that collapses " + "the always-on directive-token spend (E-41). The suppression is " + "fail-safe and re-checked every turn in recall.py: it fires ONLY when " + "a non-empty rules block is physically present in the agent's " + "CLAUDE.md — a false flag with an empty/absent block keeps injecting " + "AND emits a degraded-canary notice, so a zero-standing-rules turn is " + "unreachable. Requires memory.rules_block=true first (the block must " + "be live before injection is turned off — enforce the ordering with " + "`switchroom memory flip`, never a bare flag flip). Coordinates with " + "M4's memory.recall prefetch (memoryPrefetchEnabled): the same guard " + "gates all three recall.py emit sites so a flipped agent leaks no " + "directive on a cache/prefetch hit. Cascade: override, per-agent ONLY " + "(never fleet-seeded from the defaults/profile tier — each flip is a " + "deliberate staggered M3 rollout step, same darkness safeguard as " + "rules_block). Default-true is the fail-safe direction under the " + "Zod-strip footgun: a stripped/misread key keeps the agent injecting."),
     disposition: exports_external.object({
       skepticism: exports_external.number().int().min(1).max(5).optional().describe("How much the bank doubts unverified claims (1-5; engine default 3)."),
       literalism: exports_external.number().int().min(1).max(5).optional().describe("How literally the bank reads statements vs inferring intent (1-5; engine default 3)."),
@@ -5029,6 +5033,7 @@ var init_schema = __esm(() => {
       profile: exports_external.string().optional(),
       directive_capture_nudge: exports_external.boolean().optional(),
       profile_capture_nudge: exports_external.boolean().optional(),
+      orientation_cadence_hours: exports_external.number().int().min(1).optional(),
       anti_confabulation_directive: AntiConfabulationDirectiveSchema,
       observation_scopes: ObservationScopesSchema,
       observation_scope_strategy: ObservationScopeStrategySchema,

package/dist/vault/broker/server.js

@@ -4180,6 +4180,10 @@ var init_schema = __esm(() => {
     }).optional().describe("Operator-declared, per-specialist Hindsight mental models (RFC " + "Phase 5). Named, opt-in curated reflections this agent's bank should " + "carry — e.g. a coach's 'training-plan-state' or a lawyer's " + "'open-matters'. Ensured idempotently at scaffold/reconcile: NOTHING " + "is created unless declared here (zero declarations = zero models, " + "matching post-#2447 behaviour), and no fixed identity model is " + "reintroduced — 'who the user is' stays owned by dedicated profile " + "banks (users.*.profile_bank), never a per-agent model. Per-agent " + "ONLY: intentionally not accepted at the defaults/profile tier, so a " + "model can never be fleet-seeded — each specialist opts in on its own " + "(the invariant-clean inverse of the retired blind auto-seeding)."),
     observations_mission: exports_external.string().optional().describe("Steers what the observation-consolidation LLM synthesises from raw " + "facts (the higher-order 'what patterns matter' lens). Cascade: override."),
     rules_block: exports_external.boolean().default(false).describe("Memory v2 M3 go-live flag (M1 only DEFINES this, default false; " + "M3 flips it per agent). When true, the sanctioned rules/index " + "blocks render live in this agent's CLAUDE.md (marker-delimited, " + "below the `# --- Yours ---` line) AND the permission deny for " + "direct Edit/Write of the agent's own CLAUDE.md is seeded — the " + "flag couples deny + tools together so a live deny never orphans " + "the invited free-text edit path (the `memory_edit_yours` verb is " + "the only sanctioned writer once flipped). Unset/false ⇒ byte-" + "identical to pre-M1 behaviour: no blocks, no deny, dark build. " + "Cascade: override (per-agent wins over default; never fleet-" + "seeded — each agent's flip is a deliberate M3 rollout step)."),
+    orientation: exports_external.boolean().optional().describe("Memory v2 M5 go-live flag (Surface B: orientation-at-boot), " + "effective default false — dark build (unset ⇒ OFF, applied by the " + "scaffold resolver, NOT a Zod .default() — a hard default here would " + "shadow the per-agent value in the cascade the way it does every other " + "memory knob). When true, the orientation SessionStart " + "hook injects this agent's cron-refreshed `orientation` mental model " + "into context at boot AND re-seats it after every compaction (E-88), " + "deterministically and with zero tool call. Unset/false ⇒ byte-" + "identical to pre-M5 behaviour: the hook no-ops before any bank " + "resolve or network call. Per-agent ONLY (never fleet-seeded — a " + "flip is a deliberate canary/rollout step gated on the agent's " + "m2-residue measurement + operator-created model, carve-M5 §7). " + "Cascade: override (per-agent wins over default)."),
+    orientation_reinject_turns: exports_external.number().int().min(0).optional().describe("Memory v2 M5 optional per-turn re-inject cadence, effective default " + "0 = off (unset ⇒ 0, applied by the scaffold resolver, not a Zod " + ".default() — same cascade-shadowing reason as `orientation`). At 0 the " + "briefing is injected only at SessionStart + compaction (the cheap " + "path). N>0 " + "would additionally re-inject the orientation briefing every N turns; " + "priced at ~55M tok/30d at every-turn, which is WHY it defaults off " + "(carve-M5 §2/§4). Only late-session context loss should ever set it, " + "per-agent, measured. A stripped/absent value fails to 0 (fail-safe " + "AND fail-cheap). Per-agent ONLY. Cascade: override."),
+    orientation_cadence_hours: exports_external.number().int().min(1).optional().describe("Memory v2 M5 per-agent refresh cadence tier (hours), effective " + "default 48 (unset ⇒ 48, applied by the scaffold resolver, not a Zod " + ".default() — a hard default would shadow a `defaults.memory." + "orientation_cadence_hours` fleet value in the cascade). " + "The fast-churning agents (klanker, overlord) set 24; everyone else " + "inherits 48 (carve-M5 §6, Ken's locked tiered cadence). Drives BOTH " + "the out-of-session refresh scheduler AND the staleness guard's " + "per-tier thresholds (stale prefix at 1.5× cadence, cold degrade at " + "3×) — so a fixed 36h can never mislabel a 48h-tier agent as stale a " + "day early. Modelled as an explicit int (not a hard-coded name list) " + "so the tiering is data-driven and auditable. A cost knob, not an " + "enablement knob: a stripped/absent value failing to 48 is safe " + "(the cheaper tier). Cascade: override (per-agent wins over default); " + "unlike `orientation`/`_reinject_turns` it IS accepted at the " + "defaults/profile tier."),
+    inject_directives: exports_external.boolean().optional().describe("Memory v2 M3 Surface-A directive-injection switch (default TRUE — " + "on-by-default via the plugin settings.json stamp + config.py " + "DEFAULTS). When left unset the agent keeps injecting the " + "`<active_directives>` block on every turn, byte-identical to pre-M3. " + "Set FALSE to SUPPRESS that injection for this agent — its standing " + "rules are then served from the live rules block (memory.rules_block) " + "instead of re-injected directives, which is the change that collapses " + "the always-on directive-token spend (E-41). The suppression is " + "fail-safe and re-checked every turn in recall.py: it fires ONLY when " + "a non-empty rules block is physically present in the agent's " + "CLAUDE.md — a false flag with an empty/absent block keeps injecting " + "AND emits a degraded-canary notice, so a zero-standing-rules turn is " + "unreachable. Requires memory.rules_block=true first (the block must " + "be live before injection is turned off — enforce the ordering with " + "`switchroom memory flip`, never a bare flag flip). Coordinates with " + "M4's memory.recall prefetch (memoryPrefetchEnabled): the same guard " + "gates all three recall.py emit sites so a flipped agent leaks no " + "directive on a cache/prefetch hit. Cascade: override, per-agent ONLY " + "(never fleet-seeded from the defaults/profile tier — each flip is a " + "deliberate staggered M3 rollout step, same darkness safeguard as " + "rules_block). Default-true is the fail-safe direction under the " + "Zod-strip footgun: a stripped/misread key keeps the agent injecting."),
     disposition: exports_external.object({
       skepticism: exports_external.number().int().min(1).max(5).optional().describe("How much the bank doubts unverified claims (1-5; engine default 3)."),
       literalism: exports_external.number().int().min(1).max(5).optional().describe("How literally the bank reads statements vs inferring intent (1-5; engine default 3)."),
@@ -4625,6 +4629,7 @@ var init_schema = __esm(() => {
       profile: exports_external.string().optional(),
       directive_capture_nudge: exports_external.boolean().optional(),
       profile_capture_nudge: exports_external.boolean().optional(),
+      orientation_cadence_hours: exports_external.number().int().min(1).optional(),
       anti_confabulation_directive: AntiConfabulationDirectiveSchema,
       observation_scopes: ObservationScopesSchema,
       observation_scope_strategy: ObservationScopeStrategySchema,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.21.16",
+  "version": "0.21.17",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/profiles/_base/start.sh.hbs

@@ -1198,6 +1198,17 @@ export HINDSIGHT_DIRECTIVE_CAPTURE_NUDGE={{hindsightDirectiveCaptureNudge}}
 {{#if hindsightProfileCaptureNudge}}
 export HINDSIGHT_PROFILE_CAPTURE_NUDGE={{hindsightProfileCaptureNudge}}
 {{/if}}
+# Memory v2 M3 Surface-A — directive-injection switch (memory.inject_directives
+# cascade). On by default (plugin settings.json): recall.py injects the
+# <active_directives> block every turn. Export only when the operator overrode
+# it; set false to SUPPRESS injection for this agent (a flipped M3 canary) — its
+# standing rules then come from the live rules block instead. recall.py keeps
+# the suppression fail-safe: it drops injection ONLY when a non-empty rules
+# block is physically present in CLAUDE.md, else it keeps injecting and emits a
+# degraded-canary notice. Flip via `switchroom memory flip`, never a bare edit.
+{{#if hindsightInjectDirectives}}
+export HINDSIGHT_INJECT_DIRECTIVES={{hindsightInjectDirectives}}
+{{/if}}
 # Per-row observation scope (memory.observation_scopes cascade). Stamped on
 # every retain — Stop hook, sidechain, boot reconcile, queue drain, backfill.
 # "shared" makes consolidation pool this agent's observations into ONE global

package/telegram-plugin/dist/gateway/gateway.js

@@ -21798,6 +21798,10 @@ var init_schema = __esm(() => {
     }).optional().describe("Operator-declared, per-specialist Hindsight mental models (RFC " + "Phase 5). Named, opt-in curated reflections this agent's bank should " + "carry \u2014 e.g. a coach's 'training-plan-state' or a lawyer's " + "'open-matters'. Ensured idempotently at scaffold/reconcile: NOTHING " + "is created unless declared here (zero declarations = zero models, " + "matching post-#2447 behaviour), and no fixed identity model is " + "reintroduced \u2014 'who the user is' stays owned by dedicated profile " + "banks (users.*.profile_bank), never a per-agent model. Per-agent " + "ONLY: intentionally not accepted at the defaults/profile tier, so a " + "model can never be fleet-seeded \u2014 each specialist opts in on its own " + "(the invariant-clean inverse of the retired blind auto-seeding)."),
     observations_mission: exports_external.string().optional().describe("Steers what the observation-consolidation LLM synthesises from raw " + "facts (the higher-order 'what patterns matter' lens). Cascade: override."),
     rules_block: exports_external.boolean().default(false).describe("Memory v2 M3 go-live flag (M1 only DEFINES this, default false; " + "M3 flips it per agent). When true, the sanctioned rules/index " + "blocks render live in this agent's CLAUDE.md (marker-delimited, " + "below the `# --- Yours ---` line) AND the permission deny for " + "direct Edit/Write of the agent's own CLAUDE.md is seeded \u2014 the " + "flag couples deny + tools together so a live deny never orphans " + "the invited free-text edit path (the `memory_edit_yours` verb is " + "the only sanctioned writer once flipped). Unset/false \u21d2 byte-" + "identical to pre-M1 behaviour: no blocks, no deny, dark build. " + "Cascade: override (per-agent wins over default; never fleet-" + "seeded \u2014 each agent's flip is a deliberate M3 rollout step)."),
+    orientation: exports_external.boolean().optional().describe("Memory v2 M5 go-live flag (Surface B: orientation-at-boot), " + "effective default false \u2014 dark build (unset \u21d2 OFF, applied by the " + "scaffold resolver, NOT a Zod .default() \u2014 a hard default here would " + "shadow the per-agent value in the cascade the way it does every other " + "memory knob). When true, the orientation SessionStart " + "hook injects this agent's cron-refreshed `orientation` mental model " + "into context at boot AND re-seats it after every compaction (E-88), " + "deterministically and with zero tool call. Unset/false \u21d2 byte-" + "identical to pre-M5 behaviour: the hook no-ops before any bank " + "resolve or network call. Per-agent ONLY (never fleet-seeded \u2014 a " + "flip is a deliberate canary/rollout step gated on the agent's " + "m2-residue measurement + operator-created model, carve-M5 \u00a77). " + "Cascade: override (per-agent wins over default)."),
+    orientation_reinject_turns: exports_external.number().int().min(0).optional().describe("Memory v2 M5 optional per-turn re-inject cadence, effective default " + "0 = off (unset \u21d2 0, applied by the scaffold resolver, not a Zod " + ".default() \u2014 same cascade-shadowing reason as `orientation`). At 0 the " + "briefing is injected only at SessionStart + compaction (the cheap " + "path). N>0 " + "would additionally re-inject the orientation briefing every N turns; " + "priced at ~55M tok/30d at every-turn, which is WHY it defaults off " + "(carve-M5 \u00a72/\u00a74). Only late-session context loss should ever set it, " + "per-agent, measured. A stripped/absent value fails to 0 (fail-safe " + "AND fail-cheap). Per-agent ONLY. Cascade: override."),
+    orientation_cadence_hours: exports_external.number().int().min(1).optional().describe("Memory v2 M5 per-agent refresh cadence tier (hours), effective " + "default 48 (unset \u21d2 48, applied by the scaffold resolver, not a Zod " + ".default() \u2014 a hard default would shadow a `defaults.memory." + "orientation_cadence_hours` fleet value in the cascade). " + "The fast-churning agents (klanker, overlord) set 24; everyone else " + "inherits 48 (carve-M5 \u00a76, Ken's locked tiered cadence). Drives BOTH " + "the out-of-session refresh scheduler AND the staleness guard's " + "per-tier thresholds (stale prefix at 1.5\u00d7 cadence, cold degrade at " + "3\u00d7) \u2014 so a fixed 36h can never mislabel a 48h-tier agent as stale a " + "day early. Modelled as an explicit int (not a hard-coded name list) " + "so the tiering is data-driven and auditable. A cost knob, not an " + "enablement knob: a stripped/absent value failing to 48 is safe " + "(the cheaper tier). Cascade: override (per-agent wins over default); " + "unlike `orientation`/`_reinject_turns` it IS accepted at the " + "defaults/profile tier."),
+    inject_directives: exports_external.boolean().optional().describe("Memory v2 M3 Surface-A directive-injection switch (default TRUE \u2014 " + "on-by-default via the plugin settings.json stamp + config.py " + "DEFAULTS). When left unset the agent keeps injecting the " + "`<active_directives>` block on every turn, byte-identical to pre-M3. " + "Set FALSE to SUPPRESS that injection for this agent \u2014 its standing " + "rules are then served from the live rules block (memory.rules_block) " + "instead of re-injected directives, which is the change that collapses " + "the always-on directive-token spend (E-41). The suppression is " + "fail-safe and re-checked every turn in recall.py: it fires ONLY when " + "a non-empty rules block is physically present in the agent's " + "CLAUDE.md \u2014 a false flag with an empty/absent block keeps injecting " + "AND emits a degraded-canary notice, so a zero-standing-rules turn is " + "unreachable. Requires memory.rules_block=true first (the block must " + "be live before injection is turned off \u2014 enforce the ordering with " + "`switchroom memory flip`, never a bare flag flip). Coordinates with " + "M4's memory.recall prefetch (memoryPrefetchEnabled): the same guard " + "gates all three recall.py emit sites so a flipped agent leaks no " + "directive on a cache/prefetch hit. Cascade: override, per-agent ONLY " + "(never fleet-seeded from the defaults/profile tier \u2014 each flip is a " + "deliberate staggered M3 rollout step, same darkness safeguard as " + "rules_block). Default-true is the fail-safe direction under the " + "Zod-strip footgun: a stripped/misread key keeps the agent injecting."),
     disposition: exports_external.object({
       skepticism: exports_external.number().int().min(1).max(5).optional().describe("How much the bank doubts unverified claims (1-5; engine default 3)."),
       literalism: exports_external.number().int().min(1).max(5).optional().describe("How literally the bank reads statements vs inferring intent (1-5; engine default 3)."),
@@ -22243,6 +22247,7 @@ var init_schema = __esm(() => {
       profile: exports_external.string().optional(),
       directive_capture_nudge: exports_external.boolean().optional(),
       profile_capture_nudge: exports_external.boolean().optional(),
+      orientation_cadence_hours: exports_external.number().int().min(1).optional(),
       anti_confabulation_directive: AntiConfabulationDirectiveSchema,
       observation_scopes: ObservationScopesSchema,
       observation_scope_strategy: ObservationScopeStrategySchema,
@@ -105871,10 +105876,10 @@ function startOutboxSweep(deps) {
 }
 
 // ../src/build-info.ts
-var VERSION2 = "0.21.16";
-var COMMIT_SHA = "d6c1267a";
-var COMMIT_DATE = "2026-08-17T09:16:43Z";
-var LATEST_PR = 4763;
+var VERSION2 = "0.21.17";
+var COMMIT_SHA = "ac61272c";
+var COMMIT_DATE = "2026-08-17T16:42:58Z";
+var LATEST_PR = 4768;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts

package/vendor/hindsight-memory/hooks/hooks.json

@@ -10,6 +10,15 @@
             "timeout": 30
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/orientation.py\"",
+            "timeout": 8
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [

package/vendor/hindsight-memory/scripts/directive_verify.py

@@ -64,6 +64,7 @@ from lib.directives import (  # noqa: E402
     parse_active_directives_block,
     rule_already_captured,
 )
+from lib import recall_buffer  # noqa: E402
 
 # Reuse Stage B's pleasantry scrub so "as always" / "always happy to help"
 # can't trip the high-confidence detector either. Imported lazily-safe: if
@@ -387,6 +388,37 @@ def invalidate_cache_on_directive_write(messages: list, config: dict) -> None:
         debug_log(config, f"Directives cache invalidation skipped (error): {e}")
 
 
+def invalidate_prefetch_buffer_on_directive_write(messages: list, config: dict, session_id: str) -> None:
+    """Drop this session's pending M4 prefetch buffer if this turn wrote a
+    directive (create/update/delete/retire).
+
+    red-team-M3 R2 (BLOCKER): the A4 cache invalidation above keeps the fresh
+    <active_directives> block current, but the M4 prefetch buffer carries a
+    RECALLED memories block captured at a prior turn's Stop — and a rule/
+    directive that was just retired can survive in that snapshot as recalled
+    text. Without this, a buffer prefetched while the rule was active would
+    re-inject the retired rule on the next turn (the exact §4.4 resurrection
+    failure), and `run_prefetch` bailing on an empty recall would leave that
+    stale buffer to be served on later turns too. Deleting the buffer + sentinel
+    here forces the consumer to fall to the synchronous, always-current path
+    (or the explicitly stale-marked fallback) instead of resurrecting it.
+
+    Only fires when `memoryPrefetchEnabled` is on (the buffer only exists then)
+    — a cheap no-op statting two absent files otherwise, so gated to avoid it.
+    Self-guarded; never raises (a Stop hook must not wedge a turn).
+    """
+    try:
+        if not messages or not config.get("memoryPrefetchEnabled", False):
+            return
+        idx, _text = find_last_human_turn(messages)
+        start = idx if idx is not None else -1
+        if turn_contains_directive_write(messages, start):
+            recall_buffer.invalidate(session_id or "unknown")
+            debug_log(config, "Prefetch buffer invalidated — turn wrote a directive (R2 resurrection guard)")
+    except Exception as e:  # pragma: no cover - defensive; Stop must not wedge
+        debug_log(config, f"Prefetch-buffer invalidation skipped (error): {e}")
+
+
 def read_transcript(transcript_path: str) -> list:
     """Read a JSONL transcript into a list of message dicts (role/content).
 
@@ -508,6 +540,7 @@ def main():
     #     and this is not an already-blocked re-fire.
     ttl = config.get("directivesCacheTtlSeconds", DIRECTIVES_CACHE_TTL_SECONDS)
     cache_on = isinstance(ttl, (int, float)) and ttl > 0
+    prefetch_on = bool(config.get("memoryPrefetchEnabled", False))
     verify_maybe = (
         config.get("directiveCaptureNudge", True)
         and config.get("directiveCaptureVerify", True)
@@ -515,7 +548,7 @@ def main():
     )
 
     messages: list = []
-    if cache_on or verify_maybe:
+    if cache_on or verify_maybe or prefetch_on:
         messages = read_transcript(hook_input.get("transcript_path", ""))
 
     # A4: invalidate the directives cache when this turn wrote a directive, so
@@ -524,6 +557,15 @@ def main():
     if cache_on:
         invalidate_cache_on_directive_write(messages, config)
 
+    # R2 (BLOCKER): invalidate this session's M4 prefetch buffer when this turn
+    # wrote/retired a directive, so a stale pre-retire snapshot can never
+    # resurrect the retired rule on a later turn. Self-guarded no-op when
+    # prefetch is off.
+    if prefetch_on:
+        invalidate_prefetch_buffer_on_directive_write(
+            messages, config, hook_input.get("session_id") or "unknown"
+        )
+
     try:
         reason = evaluate(hook_input, config, messages=messages)
     except Exception as e:  # never wedge a turn on a verify bug

package/vendor/hindsight-memory/scripts/lib/client.py

@@ -519,3 +519,38 @@ class HindsightClient:
         if retain_mission:
             updates["retain_mission"] = retain_mission
         return self._request("PATCH", path, {"updates": updates}, timeout=timeout)
+
+    def list_mental_models(self, bank_id: str, timeout: int = 5) -> dict:
+        """List the mental models for a bank (Memory v2 M5 — orientation-at-boot).
+
+        The orientation SessionStart hook knows the orientation model by NAME
+        (the configured `memoryOrientationModel`), not by its `mm-…` id, so it
+        lists the bank's models and matches on name → id before reading content
+        (carve-M5 §0d/§3). Read-only GET on the ungated engine REST surface;
+        m5-0-probe measured the own-bank read at ~4ms on klanker.
+
+        REST: ``GET /v1/default/banks/{bank_id}/mental-models``. Returns the raw
+        response dict, expected to carry an ``items`` list where each item has at
+        least ``id`` and ``name``.
+        """
+        path = f"/v1/default/banks/{urllib.parse.quote(bank_id, safe='')}/mental-models"
+        return self._request("GET", path, timeout=timeout)
+
+    def get_mental_model(
+        self, bank_id: str, model_id: str, detail: str = "full", timeout: int = 5
+    ) -> dict:
+        """Read one mental model's content + freshness watermark (M5).
+
+        REST: ``GET /v1/default/banks/{bank_id}/mental-models/{model_id}?detail=full``
+        (m5-0-probe Q3/Q4 proved this returns ``content`` + the
+        ``last_refreshed_at`` watermark the staleness guard keys on, ~4ms warm).
+        Read-only; ungated. The caller wraps this in a generous read-timeout and
+        degrades to the cold notice on any error — a slow/failed read must never
+        block boot (carve §3 fail-safe).
+        """
+        bank = urllib.parse.quote(bank_id, safe="")
+        model = urllib.parse.quote(model_id, safe="")
+        path = f"/v1/default/banks/{bank}/mental-models/{model}"
+        if detail:
+            path = f"{path}?{urllib.parse.urlencode({'detail': detail})}"
+        return self._request("GET", path, timeout=timeout)

package/vendor/hindsight-memory/scripts/lib/config.py

@@ -130,6 +130,20 @@ DEFAULTS = {
     # opt out per-agent via memory.profile_capture_nudge=false →
     # HINDSIGHT_PROFILE_CAPTURE_NUDGE.
     "profileCaptureNudge": True,
+    # Switchroom Memory v2 M3 Surface-A — directive-injection switch. When True
+    # (default), recall.py injects the `<active_directives>` block on every
+    # UserPromptSubmit at all three emit sites (main + prefetch/cache fast
+    # paths). When False (a flipped M3 canary), that injection is SUPPRESSED —
+    # the agent's standing rules come from the live rules block instead, which
+    # is the change that collapses the always-on directive-token spend (E-41).
+    # Suppression is fail-safe and re-checked every turn: it fires ONLY when a
+    # non-empty rules block is physically present in CLAUDE.md; a False flag
+    # with an empty/absent block keeps injecting AND emits a degraded-canary
+    # notice, so a zero-standing-rules turn is unreachable. Operators flip a
+    # canary per-agent via memory.inject_directives=false →
+    # HINDSIGHT_INJECT_DIRECTIVES; the ordered flip (rules_block live → migrate
+    # → this flag off) is enforced by `switchroom memory flip`.
+    "injectDirectives": True,
     # Switchroom #2873/#2903 Fix 6.2 — the BLOCKING half (Stage C
     # directive_verify.py Stop hook) split out from the advisory nudge. When
     # True (default) the verifier may block the stop once to re-prompt capture;
@@ -140,6 +154,23 @@ DEFAULTS = {
     # per-agent via memory.directive_capture_verify=false →
     # HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY.
     "directiveCaptureVerify": True,
+    # Memory v2 M5 — orientation-at-boot (Surface B). All four fail-safe by
+    # default so a stripped/absent key (the Zod-strip footgun, carve §1) boots
+    # exactly as pre-M5. `memoryOrientationEnabled` is the per-agent kill switch,
+    # default OFF (dark build — the orientation SessionStart hook no-ops before
+    # any bank resolve or network call when off). `memoryOrientationModel` is the
+    # mental-model NAME the hook resolves to an id (the agent's OWN bank).
+    # `memoryOrientationCadenceHours` is the per-agent refresh cadence tier
+    # (klanker/overlord 24, everyone else 48) the staleness guard's per-tier
+    # thresholds (1.5×/3×) key on. `memoryOrientationReinjectTurns` is the
+    # epic's optional per-turn re-inject knob, default 0 = SessionStart+compaction
+    # only (the cheap path; N>0 is the ~55M/30d-at-every-turn expensive variant,
+    # which is why it defaults off). Delivered per-agent via the scaffold
+    # settings.json stamp and overridable via the HINDSIGHT_ORIENTATION_* env.
+    "memoryOrientationEnabled": False,
+    "memoryOrientationModel": "orientation",
+    "memoryOrientationCadenceHours": 48,
+    "memoryOrientationReinjectTurns": 0,
     # Switchroom hindsight-leverage A4 — TTL (seconds) for the directives-list
     # cache on the recall critical path (see lib/directives.py). The list is
     # re-fetched at most once per TTL window for no-write turns; in-session
@@ -510,11 +541,27 @@ ENV_OVERRIDES = {
     # it; the switchroom default is on (settings.json pins true; recall.py falls
     # back to True).
     "HINDSIGHT_PROFILE_CAPTURE_NUDGE": ("profileCaptureNudge", bool),
+    # Switchroom Memory v2 M3 Surface-A: directive-injection switch on/off. Set
+    # by start.sh from agents.<name>.memory.inject_directives only when the
+    # operator overrode it; the switchroom default is on (settings.json pins
+    # true; recall.py falls back to True). False SUPPRESSES the
+    # <active_directives> injection for a flipped canary, fail-safe on a live
+    # rules block (see recall.py directive_injection_decision).
+    "HINDSIGHT_INJECT_DIRECTIVES": ("injectDirectives", bool),
     # Switchroom #2873/#2903 Fix 6.2: the Stage C block on/off, independent of
     # the Stage B nudge. Set by start.sh from
     # agents.<name>.memory.directive_capture_verify only when the operator
     # overrode it; the switchroom default is on.
     "HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY": ("directiveCaptureVerify", bool),
+    # Memory v2 M5 — orientation-at-boot. Env override channel for the four
+    # orientation knobs (settings.json carries the per-agent value; env wins for
+    # a docker-exec'd hook or an agent `env:` map). `memoryOrientationEnabled`
+    # is the per-agent kill switch (default off); the model NAME, cadence tier,
+    # and reinject count follow. See DEFAULTS above and carve-M5 §4.
+    "HINDSIGHT_ORIENTATION_ENABLED": ("memoryOrientationEnabled", bool),
+    "HINDSIGHT_ORIENTATION_MODEL": ("memoryOrientationModel", str),
+    "HINDSIGHT_ORIENTATION_CADENCE_HOURS": ("memoryOrientationCadenceHours", int),
+    "HINDSIGHT_ORIENTATION_REINJECT_TURNS": ("memoryOrientationReinjectTurns", int),
     # Switchroom hindsight-leverage A4 — directives-list cache TTL (seconds).
     # 0 disables the cache (rollback lever).
     "HINDSIGHT_DIRECTIVES_CACHE_TTL_SECONDS": ("directivesCacheTtlSeconds", int),

package/vendor/hindsight-memory/scripts/lib/orientation.py

@@ -0,0 +1,248 @@
+"""Memory v2 M5 — Surface B: orientation-at-boot (pure logic).
+
+carve-M5.md §3/§5/§0c. This module holds the network-free, deterministically
+testable half of the orientation SessionStart hook: staleness classification
+(per-tier thresholds, NOT a fixed 36h), rule-aware truncation to the content
+token budget, and the `additionalContext` rendering. The hook entry
+(`orientation.py`) does the I/O — resolve own bank, list mental models, match
+the orientation model by name, GET its content — and calls into here so the
+budget/staleness/render logic can be unit-tested without a live engine.
+
+Why the split mirrors the fleet's other deterministic memory surfaces
+(recall.py's nudge regexes, prefetch.py's buffer contract): the value is a
+DETERMINISTIC mechanism, not model discretion, so every branch that decides
+"inject / prefix-as-stale / degrade-to-cold / truncate" must be pinned by a
+test that fails on the bug it guards (carve §8 tautology-guard discipline).
+
+TOKEN BUDGET (carve §0c). The epic caps the injected briefing at 2048 tokens,
+but M0 measured real mental models at ~1,766–1,962 tokens of CONTENT alone —
+so a naive "cap at 2048" overflows the moment a stale prefix or framing is
+prepended. The real number to design to is a CONTENT budget below the cap,
+leaving headroom for the prefix + framing. Truncation is rule-aware: whole
+markdown sections are kept, trailing sections dropped, and a visible marker is
+emitted so the loss is never silent.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+
+#: Hard ceiling on the total injected `additionalContext` (epic line 143).
+ORIENTATION_TOTAL_TOKEN_CAP = 2048
+#: Budget for the model CONTENT alone, below the cap so the stale prefix +
+#: framing tags fit inside 2048 (carve §0c: ~1,800, reserving ~250).
+ORIENTATION_CONTENT_TOKEN_BUDGET = 1800
+#: Chars-per-token estimate M0 used to convert measured char sizes to tokens
+#: (7,063 chars ≈ 1,766 tokens). Deterministic proxy — no tokenizer dependency
+#: on the boot critical path.
+CHARS_PER_TOKEN = 4
+
+#: Emitted (once) when trailing sections were dropped to fit the budget, so the
+#: loss is visible to the model rather than a silent mid-sentence byte-cut.
+TRUNCATION_MARKER = "(orientation truncated to fit context budget)"
+
+# Framing tags. Kept intentionally tiny — they count against the 2048 cap.
+_OPEN_TAG = "<orientation source=\"memory\">"
+_CLOSE_TAG = "</orientation>"
+
+
+def estimate_tokens(text: str) -> int:
+    """Deterministic token estimate (ceil of chars / CHARS_PER_TOKEN).
+
+    A proxy, not a real tokenizer — but the SAME proxy M0 measured content
+    sizes with, so the budget math is internally consistent, and it needs no
+    model/tokenizer on the boot path. Empty string is 0 tokens.
+    """
+    if not text:
+        return 0
+    return math.ceil(len(text) / CHARS_PER_TOKEN)
+
+
+def classify_staleness(
+    last_refreshed_at: str | None,
+    cadence_hours: int,
+    now: datetime | None = None,
+) -> tuple[str, float | None]:
+    """Classify an orientation model's freshness against its agent's TIER.
+
+    Returns ``(state, hours_ago)`` where state is one of:
+      - ``"fresh"``    — refreshed < 1.5× cadence ago: inject plainly.
+      - ``"stale"``    — 1.5×–3× cadence ago: inject WITH a visible prefix.
+      - ``"degraded"`` — > 3× cadence ago: do NOT inject stale-as-fresh; the
+                          hook emits the cold notice + enqueues a refresh.
+      - ``"unknown"``  — no/unparseable ``last_refreshed_at``: treat as cold
+                          (fail closed — never present an un-dated model as
+                          fresh). ``hours_ago`` is None.
+
+    The thresholds are PER-TIER (carve §5): a fixed 36h would mislabel every
+    48h-cadence agent as stale a full day early. 1.5× / 3× of the resolved
+    cadence is the tier-correct boundary — 36h/72h at cadence 24, 72h/144h at
+    cadence 48. Keyed on ``last_refreshed_at`` (the freshness watermark the
+    persisting refresh advances — m5-0-probe Q3), NOT ``updated_at`` (returned
+    null on the single-model read) and NOT the engine's own ``is_stale`` (its
+    threshold is engine-defined, not the agent's tier).
+    """
+    if now is None:
+        now = datetime.now(timezone.utc)
+    if not last_refreshed_at:
+        return ("unknown", None)
+    ts = _parse_iso(last_refreshed_at)
+    if ts is None:
+        return ("unknown", None)
+    # A naive timestamp is assumed UTC (the engine stores tz-aware UTC; this is
+    # belt-and-braces so an aware/naive mismatch can never raise on subtract).
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    hours_ago = (now - ts).total_seconds() / 3600.0
+    # Guard a clock-skew future timestamp: treat as fresh, never negative-stale.
+    if hours_ago < 0:
+        hours_ago = 0.0
+    stale_at = 1.5 * cadence_hours
+    degrade_at = 3.0 * cadence_hours
+    if hours_ago < stale_at:
+        return ("fresh", hours_ago)
+    if hours_ago < degrade_at:
+        return ("stale", hours_ago)
+    return ("degraded", hours_ago)
+
+
+def _parse_iso(value: str) -> datetime | None:
+    """Parse an engine ISO-8601 timestamp, tolerating a trailing ``Z``."""
+    try:
+        # datetime.fromisoformat handles "+00:00" and fractional seconds; map a
+        # trailing Z (some engine surfaces emit it) to the offset form first.
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (ValueError, AttributeError):
+        return None
+
+
+def truncate_to_budget(content: str, token_budget: int) -> tuple[str, bool]:
+    """Rule-aware truncation to ``token_budget`` tokens.
+
+    Returns ``(text, truncated)``. Prefers WHOLE markdown sections (a section
+    starts at a line beginning with ``#``): accumulates sections while they fit,
+    drops trailing sections that don't, and signals ``truncated=True`` so the
+    caller can append :data:`TRUNCATION_MARKER`. If the very first section
+    already exceeds the budget, hard-cuts at a whitespace boundary (never
+    mid-word) rather than emitting nothing.
+
+    Never returns more than the budget; an empty/whitespace input returns
+    ``("", False)``.
+    """
+    content = (content or "").strip()
+    if not content:
+        return ("", False)
+    if estimate_tokens(content) <= token_budget:
+        return (content, False)
+
+    sections = _split_sections(content)
+    kept: list[str] = []
+    used = 0
+    for sec in sections:
+        sec_tokens = estimate_tokens(sec)
+        # +1 token slack for the join newline between kept sections.
+        if kept and used + sec_tokens + 1 > token_budget:
+            break
+        if not kept and sec_tokens > token_budget:
+            # First section alone overflows — hard-cut on a word boundary.
+            return (_hard_cut(sec, token_budget), True)
+        kept.append(sec)
+        used += sec_tokens + (1 if len(kept) > 1 else 0)
+
+    if not kept:
+        return (_hard_cut(sections[0], token_budget), True)
+    return ("\n".join(kept).strip(), True)
+
+
+def _split_sections(content: str) -> list[str]:
+    """Split markdown into whole sections at lines beginning with ``#``.
+
+    Leading preamble before the first header is its own section. A document
+    with no headers is a single section (the hard-cut path handles overflow).
+    """
+    lines = content.split("\n")
+    sections: list[str] = []
+    cur: list[str] = []
+    for line in lines:
+        if line.startswith("#") and cur:
+            sections.append("\n".join(cur))
+            cur = [line]
+        else:
+            cur.append(line)
+    if cur:
+        sections.append("\n".join(cur))
+    return sections
+
+
+def _hard_cut(text: str, token_budget: int) -> str:
+    """Cut ``text`` to fit ``token_budget`` at a whitespace boundary."""
+    char_budget = max(0, token_budget * CHARS_PER_TOKEN)
+    if len(text) <= char_budget:
+        return text.strip()
+    cut = text[:char_budget]
+    # Back up to the last whitespace so we never slice a word in half.
+    ws = cut.rfind(" ")
+    nl = cut.rfind("\n")
+    boundary = max(ws, nl)
+    if boundary > 0:
+        cut = cut[:boundary]
+    return cut.strip()
+
+
+def stale_prefix(hours_ago: float | None) -> str:
+    """One-line visible staleness prefix (carve §5). Never presents stale as fresh."""
+    if hours_ago is None:
+        return "(orientation staleness unknown — may be stale)"
+    return f"(orientation last refreshed {int(round(hours_ago))}h ago — may be stale)"
+
+
+def cold_notice() -> str:
+    """One-line cold notice (carve §3-4): no usable model, boot un-blocked.
+
+    Visible by design — a missing/degraded briefing degrades to a NOTICE the
+    model can see, never a silently memoryless boot.
+    """
+    return (
+        f"{_OPEN_TAG}\n"
+        "orientation model not yet built or refreshed — booting without a "
+        "briefing (a background refresh has been requested)\n"
+        f"{_CLOSE_TAG}"
+    )
+
+
+def render_orientation(
+    content: str,
+    staleness: str,
+    hours_ago: float | None,
+) -> str:
+    """Render the injected `additionalContext` for a usable model.
+
+    Applies the stale prefix when warranted, truncates the CONTENT to
+    :data:`ORIENTATION_CONTENT_TOKEN_BUDGET` (rule-aware), wraps in the tiny
+    framing tags, and guarantees the WHOLE rendered block (prefix + framing +
+    content) stays within :data:`ORIENTATION_TOTAL_TOKEN_CAP` — if the prefix
+    pushes it over, the content budget is trimmed further so the cap holds.
+
+    Callers pass only ``fresh`` or ``stale`` here; ``degraded``/``unknown`` go
+    to :func:`cold_notice` in the hook (never rendered as fresh).
+    """
+    prefix = stale_prefix(hours_ago) if staleness == "stale" else ""
+    # Reserve budget for the framing tags + prefix so the TOTAL stays under the
+    # hard cap, not just the content.
+    framing_tokens = estimate_tokens(_OPEN_TAG) + estimate_tokens(_CLOSE_TAG) + 2
+    prefix_tokens = estimate_tokens(prefix) + (1 if prefix else 0)
+    content_budget = min(
+        ORIENTATION_CONTENT_TOKEN_BUDGET,
+        ORIENTATION_TOTAL_TOKEN_CAP - framing_tokens - prefix_tokens,
+    )
+    body, truncated = truncate_to_budget(content, content_budget)
+    if truncated:
+        body = f"{body}\n\n{TRUNCATION_MARKER}"
+
+    parts = [_OPEN_TAG]
+    if prefix:
+        parts.append(prefix)
+    parts.append(body)
+    parts.append(_CLOSE_TAG)
+    return "\n".join(parts)