switchroom 0.21.16 → 0.21.18

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.18";
 
 // 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.18",
   "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.18";
+var COMMIT_SHA = "ae063418";
+var COMMIT_DATE = "2026-08-18T03:14:53Z";
+var LATEST_PR = 4772;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts

package/telegram-plugin/scripts/bun-test-ci.sh

@@ -82,6 +82,12 @@ else
     uat/load-env.test.ts
     uat/uat-driver.test.ts
     uat/runners/
+    # M3 directive-flip UAT — deterministic (no-model, no-network) gate half.
+    # Same rationale as uat/runners/: vitest excludes all of uat/**, and these
+    # import `vitest` (bun runs them via its vitest-compat shim) — so they run
+    # on the BUN side. Directory match (trailing slash) never widens into
+    # uat/scenarios/. Fenced by scripts/check-test-runner-coverage.mjs.
+    uat/flip/
   )
 fi
 

package/telegram-plugin/uat/flip/allowlist.test.ts

@@ -0,0 +1,229 @@
+/**
+ * Unit suite for the UAT allowlist add/remove helper. Runs under `bun test`
+ * (this tree is vitest-excluded) via the `uat/flip/` entry in
+ * telegram-plugin/scripts/bun-test-ci.sh.
+ *
+ * Everything is hermetic: a tmp `agentsDir` is built per-test and torn down,
+ * and the clock is injected so `expiresAt`/`--expired` are deterministic. No
+ * real ~/.switchroom is touched.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  addToAllowlist,
+  removeFromAllowlist,
+  sweepAllowlist,
+  runAllowlistCli,
+  accessFilePath,
+  receiptPath,
+  DEFAULT_TTL_MS,
+  type AllowlistReceipt,
+} from "./allowlist.js";
+
+let agentsDir: string;
+let root: string;
+
+function seedAccess(agent: string, obj: unknown): void {
+  const p = accessFilePath(agentsDir, agent);
+  mkdirSync(join(p, ".."), { recursive: true });
+  writeFileSync(p, JSON.stringify(obj, null, 2) + "\n");
+}
+
+function readAccess(agent: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(accessFilePath(agentsDir, agent), "utf8"));
+}
+
+function readReceipt(agent: string): AllowlistReceipt {
+  return JSON.parse(readFileSync(receiptPath(agentsDir, agent), "utf8"));
+}
+
+function mkAgentDir(agent: string): void {
+  mkdirSync(join(agentsDir, agent, "telegram"), { recursive: true });
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "sr-uat-allowlist-"));
+  agentsDir = join(root, "agents");
+  mkdirSync(agentsDir, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("addToAllowlist", () => {
+  it("appends the id, preserves sibling keys, and writes a receipt first", () => {
+    seedAccess("ziggy", {
+      dmPolicy: "allowlist",
+      allowFrom: ["111"],
+      groups: { "-100": { allowFrom: ["222"] } },
+      voice_in: true,
+    });
+    const now = Date.parse("2026-08-18T00:00:00.000Z");
+    const r = addToAllowlist("ziggy", "999", { agentsDir, now: () => now });
+
+    expect(r.added).toBe(true);
+    expect(r.preexisting).toBe(false);
+
+    const access = readAccess("ziggy");
+    expect(access.allowFrom).toEqual(["111", "999"]);
+    // sibling keys survive the whole-object rewrite.
+    expect(access.groups).toEqual({ "-100": { allowFrom: ["222"] } });
+    expect(access.voice_in).toBe(true);
+    expect(access.dmPolicy).toBe("allowlist");
+
+    const rcpt = readReceipt("ziggy");
+    expect(rcpt).toMatchObject({ agent: "ziggy", userId: "999", preexisting: false });
+    expect(rcpt.addedAt).toBe("2026-08-18T00:00:00.000Z");
+    expect(Date.parse(rcpt.expiresAt) - now).toBe(DEFAULT_TTL_MS);
+  });
+
+  it("creates access.json when none exists yet", () => {
+    mkAgentDir("newbie");
+    const r = addToAllowlist("newbie", "42", { agentsDir });
+    expect(r.added).toBe(true);
+    expect(readAccess("newbie").allowFrom).toEqual(["42"]);
+  });
+
+  it("is a no-op with preexisting:true when the id is already allowlisted", () => {
+    seedAccess("ziggy", { allowFrom: ["999"] });
+    const r = addToAllowlist("ziggy", "999", { agentsDir });
+    expect(r.added).toBe(false);
+    expect(r.preexisting).toBe(true);
+    // access.json unchanged; receipt records preexisting so revert won't strip it.
+    expect(readAccess("ziggy").allowFrom).toEqual(["999"]);
+    expect(readReceipt("ziggy").preexisting).toBe(true);
+  });
+
+  it("a second add is a no-op preserving the original receipt", () => {
+    seedAccess("ziggy", { allowFrom: [] });
+    const first = addToAllowlist("ziggy", "999", { agentsDir, now: () => 1000 });
+    const second = addToAllowlist("ziggy", "999", { agentsDir, now: () => 5000 });
+    expect(first.added).toBe(true);
+    expect(second.added).toBe(false);
+    // original addedAt preserved (not re-stamped to 5000).
+    expect(readReceipt("ziggy").addedAt).toBe(new Date(1000).toISOString());
+  });
+});
+
+describe("removeFromAllowlist", () => {
+  it("reverts an id the UAT added and clears the receipt", () => {
+    seedAccess("ziggy", { allowFrom: ["111"] });
+    addToAllowlist("ziggy", "999", { agentsDir });
+    expect(readAccess("ziggy").allowFrom).toEqual(["111", "999"]);
+
+    const r = removeFromAllowlist("ziggy", { agentsDir });
+    expect(r.reverted).toBe(true);
+    expect(r.receiptCleared).toBe(true);
+    expect(readAccess("ziggy").allowFrom).toEqual(["111"]);
+    expect(existsSync(receiptPath(agentsDir, "ziggy"))).toBe(false);
+  });
+
+  it("does NOT strip a preexisting id, but clears the receipt", () => {
+    seedAccess("ziggy", { allowFrom: ["999"] });
+    addToAllowlist("ziggy", "999", { agentsDir }); // preexisting
+    const r = removeFromAllowlist("ziggy", { agentsDir });
+    expect(r.reverted).toBe(false);
+    expect(r.reason).toBe("preexisting");
+    expect(r.receiptCleared).toBe(true);
+    expect(readAccess("ziggy").allowFrom).toEqual(["999"]);
+    expect(existsSync(receiptPath(agentsDir, "ziggy"))).toBe(false);
+  });
+
+  it("no-ops with no-receipt when there is nothing to revert", () => {
+    seedAccess("ziggy", { allowFrom: ["111"] });
+    const r = removeFromAllowlist("ziggy", { agentsDir });
+    expect(r.reverted).toBe(false);
+    expect(r.reason).toBe("no-receipt");
+    expect(readAccess("ziggy").allowFrom).toEqual(["111"]);
+  });
+
+  it("is idempotent — a second remove after revert is a no-op", () => {
+    seedAccess("ziggy", { allowFrom: [] });
+    addToAllowlist("ziggy", "999", { agentsDir });
+    removeFromAllowlist("ziggy", { agentsDir });
+    const second = removeFromAllowlist("ziggy", { agentsDir });
+    expect(second.reverted).toBe(false);
+    expect(second.reason).toBe("no-receipt");
+  });
+
+  it("handles a receipt whose id was already manually removed", () => {
+    seedAccess("ziggy", { allowFrom: [] });
+    addToAllowlist("ziggy", "999", { agentsDir });
+    // someone else stripped the id out of band.
+    seedAccess("ziggy", { allowFrom: [] });
+    const r = removeFromAllowlist("ziggy", { agentsDir });
+    expect(r.reverted).toBe(false);
+    expect(r.reason).toBe("not-present");
+    expect(r.receiptCleared).toBe(true);
+  });
+});
+
+describe("sweepAllowlist", () => {
+  it("reverts every agent's receipt and is idempotent on a clean second pass", () => {
+    seedAccess("a", { allowFrom: [] });
+    seedAccess("b", { allowFrom: ["7"] });
+    addToAllowlist("a", "999", { agentsDir });
+    addToAllowlist("b", "888", { agentsDir });
+
+    const first = sweepAllowlist({ agentsDir });
+    expect(first.map((r) => r.agent).sort()).toEqual(["a", "b"]);
+    expect(first.every((r) => r.reverted)).toBe(true);
+    expect(readAccess("a").allowFrom).toEqual([]);
+    expect(readAccess("b").allowFrom).toEqual(["7"]);
+
+    const second = sweepAllowlist({ agentsDir });
+    expect(second).toEqual([]);
+  });
+
+  it("with expiredOnly, leaves un-expired receipts alone", () => {
+    seedAccess("a", { allowFrom: [] });
+    seedAccess("b", { allowFrom: [] });
+    const t0 = Date.parse("2026-08-18T00:00:00.000Z");
+    addToAllowlist("a", "111", { agentsDir, now: () => t0, ttlMs: 1000 });
+    addToAllowlist("b", "222", { agentsDir, now: () => t0, ttlMs: 60 * 60 * 1000 });
+
+    // 2s later: a's receipt (ttl 1s) is expired, b's (ttl 1h) is not.
+    const swept = sweepAllowlist({ agentsDir, expiredOnly: true, now: () => t0 + 2000 });
+    expect(swept.map((r) => r.agent)).toEqual(["a"]);
+    expect(readAccess("a").allowFrom).toEqual([]);
+    // b untouched.
+    expect(readAccess("b").allowFrom).toEqual(["222"]);
+    expect(existsSync(receiptPath(agentsDir, "b"))).toBe(true);
+  });
+
+  it("returns empty on a missing agents dir", () => {
+    expect(sweepAllowlist({ agentsDir: join(root, "nope") })).toEqual([]);
+  });
+});
+
+describe("runAllowlistCli", () => {
+  it("add then remove --sweep round-trips to zero residue", () => {
+    seedAccess("ziggy", { allowFrom: ["1"] });
+    expect(runAllowlistCli(["add", "ziggy", "999", "--agents-dir", agentsDir])).toBe(0);
+    expect(readAccess("ziggy").allowFrom).toEqual(["1", "999"]);
+
+    expect(runAllowlistCli(["remove", "--sweep", "--agents-dir", agentsDir])).toBe(0);
+    expect(readAccess("ziggy").allowFrom).toEqual(["1"]);
+    expect(existsSync(receiptPath(agentsDir, "ziggy"))).toBe(false);
+  });
+
+  it("add without a userId is a usage error (exit 1)", () => {
+    expect(runAllowlistCli(["add", "ziggy", "--agents-dir", agentsDir])).toBe(1);
+  });
+
+  it("unknown command is exit 1; bare invocation is exit 0", () => {
+    expect(runAllowlistCli(["frobnicate"])).toBe(1);
+    expect(runAllowlistCli([])).toBe(0);
+  });
+});