@wrongstack/core 0.313.1 → 0.316.1

package/dist/types/system-prompt.d.ts

@@ -1,3 +1,4 @@
+import type { SystemInstructionVariant } from '../core/instruction-bundle.js';
 import type { MailboxAgentStatus } from '../coordination/mailbox-types.js';
 import type { TextBlock } from './blocks.js';
 import type { Tool } from './tool.js';
@@ -32,6 +33,32 @@ export interface BuildContext {
      * linked Git worktrees in the same canonical project.
      */
     onlineAgents?: MailboxAgentStatus[] | undefined;
+    /**
+     * Identity variant for THIS build — `system.md`, `system-lite.md` or
+     * `system-pro.md`.
+     *
+     * The builder is one process-wide instance and used to take the variant once,
+     * at construction, from the boot config. With four conversations on one
+     * process that made the identity a property of the process: picking a lighter
+     * identity in one tab was either discarded on that tab's next turn (the
+     * pre-run prompt refresh rebuilt it from the boot variant) or applied to all
+     * of them. Passing it per build makes it a property of the conversation,
+     * which is what it always described.
+     *
+     * Omitted keeps the builder's configured default.
+     */
+    systemVariant?: SystemInstructionVariant | undefined;
+    /**
+     * Autonomy mode of THIS conversation.
+     *
+     * The ETERNAL AUTONOMY block is injected from a process-wide mode ref, which
+     * one tab could move for all of them — so switching a background tab to
+     * eternal put those instructions into every other conversation's prompt.
+     * Passing it per build makes the block follow the conversation that is
+     * actually in that mode. Omitted keeps the host's process-wide answer, which
+     * is the only one a CLI or TUI has.
+     */
+    autonomy?: string | undefined;
 }
 /**
  * Stability regions for the system prompt.

package/dist/utils/config-backup.d.ts

@@ -2,7 +2,7 @@
  * Minimal paths object needed for config backup — just the global root
  * from which we derive the backup history directory.
  */
-export interface ConfigBackupPaths {
+interface ConfigBackupPaths {
     globalRoot: string;
 }
 /**
@@ -11,10 +11,18 @@ export interface ConfigBackupPaths {
  * recover from accidental changes. Backups are never cleaned up automatically.
  */
 export declare function configHistoryDir(globalRoot: string): string;
+/**
+ * Derive a human-readable slug for a config file path relative to the
+ * ~/.wrongstack root. Examples:
+ *   config.json                            →  config
+ *   profiles/default/config.json           →  profiles-default-config
+ */
+export declare function configSlug(absolutePath: string, globalRoot: string): string;
 /**
  * Before overwriting a config file, save its current content to the
  * config-history directory with a timestamp. Best-effort: failures are
  * silently ignored so they never block the config write itself.
  */
 export declare function backupConfigFile(filePath: string, paths: ConfigBackupPaths): Promise<void>;
+export {};
 //# sourceMappingURL=config-backup.d.ts.map

package/dist/utils/heap-watchdog.js

@@ -3,8 +3,8 @@ import {
   startHeapWatchdog,
   startSharedHeapWatchdog,
   takeHeapSample
-} from "../chunk-KBZGE6LN.js";
-import "../chunk-YNCVSFGF.js";
+} from "../chunk-DYLPMV4Q.js";
+import "../chunk-SAFHACFA.js";
 export {
   defaultHeapLogPath,
   startHeapWatchdog,

package/dist/utils/index.js

@@ -49,7 +49,7 @@ import {
   toStyle,
   unifiedDiff,
   watchProjectTree
-} from "../chunk-TYW2GI5I.js";
+} from "../chunk-J2WRWR37.js";
 import {
   buildWin32CmdShimInvocation
 } from "../chunk-LHOA5DWA.js";
@@ -58,7 +58,7 @@ import {
   expandIPv6,
   isPrivateIPv4,
   isPrivateIPv6
-} from "../chunk-GFJOMSHG.js";
+} from "../chunk-LA7CLDRW.js";
 import {
   compileGlob,
   escapeGlobSubject,
@@ -69,7 +69,7 @@ import {
   matchGlob,
   normalizePathSubject,
   subjectForToolInput
-} from "../chunk-QRTG4XTI.js";
+} from "../chunk-WAHQVNWT.js";
 import {
   mergeModelsPayload
 } from "../chunk-EODDVJBM.js";
@@ -77,14 +77,15 @@ import {
   activateProjectStateGuard,
   backupConfigFile,
   configHistoryDir,
+  configSlug,
   startProjectStateGuard
-} from "../chunk-CQQL4ZOQ.js";
+} from "../chunk-ZT7JNIGX.js";
 import {
   safeParse,
   safeStringify,
   sanitizeJsonString,
   stripCodeFences
-} from "../chunk-RPOA7IAE.js";
+} from "../chunk-W5VITDM2.js";
 import {
   WIRE_TOOL_NAME_MAX_LENGTH,
   WIRE_TOOL_NAME_PATTERN,
@@ -103,21 +104,12 @@ import {
   updateJsonObjectFile,
   validateAgainstSchema,
   writeJsonObjectFile
-} from "../chunk-FFSX2QDQ.js";
+} from "../chunk-YPT4A46F.js";
 import {
   FORBIDDEN_PROTO_KEYS,
   deepMerge,
   isPrimitiveArray
-} from "../chunk-DEIQMBD2.js";
-import {
-  SageCachePragmas,
-  getPerfProfile,
-  indexParallelBatchSize,
-  isFrugalPerf,
-  sqliteCachePragmas,
-  tuiStreamFlushMs,
-  useDaemonPerfDefaults
-} from "../chunk-FNXVT7HF.js";
+} from "../chunk-B7F4WVP4.js";
 import {
   DEFAULT_TOOL_DESCRIPTION_MODE,
   applyToolDescriptionModeToTool,
@@ -128,15 +120,24 @@ import {
   setToolDescriptionMode,
   simplifyToolDescription
 } from "../chunk-WQTOVMGV.js";
+import {
+  SageCachePragmas,
+  getPerfProfile,
+  indexParallelBatchSize,
+  isFrugalPerf,
+  sqliteCachePragmas,
+  tuiStreamFlushMs,
+  useDaemonPerfDefaults
+} from "../chunk-FNXVT7HF.js";
 import {
   sessionScopedPath
-} from "../chunk-AD7ZFZCS.js";
+} from "../chunk-5BMIE7QG.js";
 import {
   defaultHeapLogPath,
   startHeapWatchdog,
   startSharedHeapWatchdog,
   takeHeapSample
-} from "../chunk-KBZGE6LN.js";
+} from "../chunk-DYLPMV4Q.js";
 import {
   readBundledInstructionText,
   renderInstructionTemplate
@@ -153,33 +154,18 @@ import {
   hasOpenTodos,
   sanitizeMemoryEvidenceBody,
   sanitizeMemoryEvidenceSource
-} from "../chunk-WZO23AWO.js";
+} from "../chunk-M27LIEKV.js";
 import "../chunk-XEBHSJLT.js";
 import {
   buildChildEnv,
   configureChildEnvGitIdentity,
   getChildEnvGitIdentity,
   sanitizeNodeOptions
-} from "../chunk-VB3H5WWB.js";
+} from "../chunk-6NWEVFEL.js";
 import {
   hasMeaningfulContent,
   repairToolUseAdjacency
-} from "../chunk-M2WF6AXG.js";
-import {
-  PROJECT_IDENTITY_RELATIVE_PATH,
-  PROJECT_IDENTITY_VERSION,
-  PROJECT_ID_PREFIX,
-  createProjectId,
-  ensureProjectGitignore,
-  ensureProjectIdentity,
-  isProjectId,
-  isUlid,
-  projectIdentityPath,
-  readProjectIdentity,
-  readProjectIdentitySync,
-  rekeyProjectIdentity,
-  ulid
-} from "../chunk-4XV6IR37.js";
+} from "../chunk-LSMMOS2Z.js";
 import {
   ESCAPE_TERMINATOR,
   TerminalLifecycle,
@@ -210,8 +196,22 @@ import {
   recordUserIntentEvidence,
   repeatedReadPressure,
   syncCompletedWorkLedgerBlock
-} from "../chunk-EFEHDQGY.js";
-import "../chunk-AWNQ6ED6.js";
+} from "../chunk-ZHZ2Y2DH.js";
+import {
+  PROJECT_IDENTITY_RELATIVE_PATH,
+  PROJECT_IDENTITY_VERSION,
+  PROJECT_ID_PREFIX,
+  createProjectId,
+  ensureProjectGitignore,
+  ensureProjectIdentity,
+  isProjectId,
+  isUlid,
+  projectIdentityPath,
+  readProjectIdentity,
+  readProjectIdentitySync,
+  rekeyProjectIdentity,
+  ulid
+} from "../chunk-HI3JGZR2.js";
 import {
   compactSchemaDescriptions,
   compactToolDefinitionForWire,
@@ -227,7 +227,7 @@ import {
   normalizeTopLevelToolSchema,
   recordActualUsage,
   resetCalibration
-} from "../chunk-FSWCWSTS.js";
+} from "../chunk-HMLIGAU7.js";
 import {
   isPidAlive
 } from "../chunk-TRT2HRWZ.js";
@@ -238,19 +238,20 @@ import {
   assertUnixSocketPathWithinLimit,
   checkUnixSocketPath,
   unixSocketPathLimit
-} from "../chunk-FAYRX2AD.js";
+} from "../chunk-POOOIWE5.js";
 import {
   atomicReplaceWithWriter,
   atomicWrite,
   ensureDir,
   withFileLock
-} from "../chunk-7ZHZE5EO.js";
+} from "../chunk-OSGLYW5J.js";
+import "../chunk-FC2ZGRF3.js";
+import "../chunk-THEGTRAG.js";
 import {
   SAGE_INJECTOR_HEADINGS,
   capSageLines,
   splitSageOutputBlock
 } from "../chunk-SVT4RNTR.js";
-import "../chunk-WEBMSQP2.js";
 import {
   bootstrapProfileName,
   canonicalProjectRoot,
@@ -259,20 +260,20 @@ import {
   resolveWstackPaths,
   safeProfileName,
   wstackGlobalRoot
-} from "../chunk-YNCVSFGF.js";
-import "../chunk-CB2HFKTP.js";
+} from "../chunk-SAFHACFA.js";
+import "../chunk-VVBP6KGT.js";
 import "../chunk-KJ2ZTQSL.js";
 import {
   truncate
 } from "../chunk-B4AMLZPB.js";
+import {
+  expectDefined
+} from "../chunk-PFZO3C6H.js";
 import "../chunk-O37BQ65S.js";
-import "../chunk-WOEZV3Q4.js";
+import "../chunk-25LSLC3G.js";
 import {
   toErrorMessage
 } from "../chunk-TBRL2RCC.js";
-import {
-  expectDefined
-} from "../chunk-PFZO3C6H.js";
 export {
   ALLOWED_IMAGE_MEDIA_TYPES,
   COMPLETED_WORK_LEDGER_MARKER,
@@ -331,6 +332,7 @@ export {
   computeMessageTokens,
   computeTaskItemProgress,
   configHistoryDir,
+  configSlug,
   configureChildEnvGitIdentity,
   createContextEvidenceState,
   createProjectId,

package/dist/utils/message-invariants.d.ts

@@ -9,6 +9,9 @@ export interface MessageRepairResult {
     messages: Message[];
     report: MessageRepairReport;
 }
+export interface MessageRepairOptions {
+    preserveTrailingToolUse?: boolean | undefined;
+}
 /**
  * Repair provider-level tool-call adjacency invariants.
  *
@@ -18,7 +21,7 @@ export interface MessageRepairResult {
  * exchange. This function removes only the now-orphaned protocol blocks,
  * preserving surrounding text/images/thinking blocks where possible.
  */
-export declare function repairToolUseAdjacency(messages: Message[]): MessageRepairResult;
+export declare function repairToolUseAdjacency(messages: Message[], opts?: MessageRepairOptions): MessageRepairResult;
 /**
  * True when a message content payload carries meaningful information for
  * the provider: non-whitespace text, a tool call/result, thinking with

package/dist/utils/regex-guard.d.ts

@@ -8,5 +8,5 @@
  * `tools/tests/regex-guard-parity.test.ts` still pins all three historical
  * entry points to identical verdicts (now trivially true — one code path).
  */
-export { type CompileFail, type CompileResult, capSubject, compileUserRegex, MAX_SUBJECT_LEN, } from '@wrongstack/primitives';
+export { type CompileFail, type CompileResult, type CompileUserRegexResult, capSubject, compileUserRegex, MAX_SUBJECT_LEN, } from '@wrongstack/primitives';
 //# sourceMappingURL=regex-guard.d.ts.map

package/dist/utils/socket-path.d.ts

@@ -4,5 +4,5 @@
  * share one implementation with packages that depend on persistence directly
  * (kanban). See `packages/persistence/src/socket-path.ts` for rationale.
  */
-export { assertUnixSocketPathWithinLimit, checkUnixSocketPath, type UnixSocketPathCheck, unixSocketPathLimit, } from '@wrongstack/persistence';
+export { assertUnixSocketPathWithinLimit, checkUnixSocketPath, unixSocketPathLimit } from '@wrongstack/persistence';
 //# sourceMappingURL=socket-path.d.ts.map

package/dist/utils/token-estimate.d.ts

@@ -1,12 +1,16 @@
 import type { Message } from '../types/messages.js';
 /**
  * Estimate tokens for a tool_use block input.
- * Caches the stringified result keyed by the stable string representation
- * to avoid repeated JSON.stringify calls during context window checks.
+ *
+ * Memoized on the input object, so the repeated context-window checks and
+ * breakdown re-runs that walk the same history serialize each payload once.
  */
 export declare function estimateToolInputTokens(input: unknown): number;
 /**
  * Estimate tokens for a tool_result content.
+ *
+ * Same memo as {@link estimateToolInputTokens}; non-object contents (null,
+ * numbers) are cheap enough to stringify outright and cannot key a WeakMap.
  */
 export declare function estimateToolResultTokens(content: string | unknown): number;
 /**

package/dist/utils/wstack-paths.d.ts

@@ -41,6 +41,8 @@ export interface WstackPaths {
     profileModeConfig: (name: string) => string;
     /** Resolve ~/.wrongstack/profiles/<name>/provider-status.json */
     profileProviderStatus: (name: string) => string;
+    /** Resolve ~/.wrongstack/profiles/<name>/provider-status-audit.jsonl */
+    profileProviderAudit: (name: string) => string;
     /** Resolve ~/.wrongstack/profiles/<name>/update-cache.json */
     profileUpdateCache: (name: string) => string;
     /** ~/.wrongstack/.key — 32 random bytes, mode 0600, AES-GCM key for the secret vault. */

package/dist/wiring/proxy-rewrite.d.ts

@@ -54,6 +54,34 @@ export interface ProxyConfig {
     /** Last-known reachability state from the periodic probe. */
     active: boolean;
 }
+/**
+ * Minimal structural logger for probe transitions. Deliberately not core's
+ * full `Logger` so any host (CLI logger, subcommand, test stub) can pass a
+ * plain object.
+ */
+export interface ProxyTransitionLogger {
+    info(message: string): void;
+    warn(message: string): void;
+}
+/**
+ * Install (or replace) the probe's transition logger. Affects the running
+ * probe immediately (the flip path reads this variable at log time).
+ * Passing undefined silences transition logging again.
+ */
+export declare function setProxyTransitionLogger(logger: ProxyTransitionLogger | undefined): void;
+/**
+ * Redact a URL for logging: keep scheme://host[:port]/path, drop query and
+ * fragment. Provider/proxy URLs may embed credentials there (`?key=...`);
+ * a log line must never persist them.
+ */
+export declare function sanitizeUrlForLog(raw: string | undefined): string;
+/**
+ * Emit one probe-transition line. Called ONLY when `active` actually flips
+ * (never on verdict-identical probes) — every flip is a routing change for
+ * every subsequent provider build. Fully isolated: a throwing logger must
+ * never alter probe control flow.
+ */
+export declare function logProxyTransition(next: boolean, reason: string): void;
 /** Read the current proxy configuration. Safe to call from any layer. */
 export declare function getProxyConfig(): ProxyConfig;
 /**

package/dist/wiring/proxy-rewrite.js

@@ -7,11 +7,14 @@ import {
   deactivateProxyOnConnectionFailure,
   getProxyConfig,
   isProxyEligible,
+  logProxyTransition,
   rewriteBaseUrl,
+  sanitizeUrlForLog,
+  setProxyTransitionLogger,
   shouldRewriteFor,
   subscribeToProxyConfig,
   waitForProxyRoutingSettle
-} from "../chunk-4ZHTKJHM.js";
+} from "../chunk-4SJNS7OB.js";
 export {
   PROXY_EXCLUDED_PROVIDERS,
   PROXY_ROUTING_SETTLE_CAP_MS,
@@ -21,7 +24,10 @@ export {
   deactivateProxyOnConnectionFailure,
   getProxyConfig,
   isProxyEligible,
+  logProxyTransition,
   rewriteBaseUrl,
+  sanitizeUrlForLog,
+  setProxyTransitionLogger,
   shouldRewriteFor,
   subscribeToProxyConfig,
   waitForProxyRoutingSettle

package/dist/worktree/index.js

@@ -1,8 +1,8 @@
 import {
   WorktreeManager,
   assertSafePath
-} from "../chunk-RCQYT2I4.js";
-import "../chunk-VB3H5WWB.js";
+} from "../chunk-NVIZG63R.js";
+import "../chunk-6NWEVFEL.js";
 import "../chunk-TBRL2RCC.js";
 export {
   WorktreeManager,

package/instructions/agents/explore-companion.md

@@ -1,9 +1,9 @@
-You are the Explore Companion — a read-only reconnaissance agent running
-behind a leader agent that is executing the main task. You do not lead
-work, you do not block the leader, and you never modify anything: you
-answer narrow probes by scanning the codebase intensively and feeding
-findings back asynchronously ("this file is here, that component works
-like this").
+You are the Explore Companion. Your job is to make the leader faster, not
+to lead. The leader is already executing the main task; you run behind it,
+answer one narrow probe, and hand back just enough map that the leader does
+not spend its own context discovering where things are.
+
+You do not plan, implement, review, or verify. You never modify the tree.
 
 Scope:
 - Answer probes scoped to the leader's current in-progress work
@@ -12,24 +12,51 @@ Scope:
 - Stay inside the probe scope; if the probe is ambiguous, state your
   interpretation and answer anyway
 
+Hard stop (do not wander):
+- Answer the probe, then stop. Do not open "related" modules, tests,
+  docs, changelogs, or adjacent features unless the probe or hint
+  names them.
+- Cap the pass: index first, then at most a handful of file reads
+  (typically 3–6, never a directory walk). One next-read suggestion,
+  not a reading list.
+- Do not spawn work, run commands, or follow a second question you invented.
+- If the first index hits already answer the probe, skip extra reads.
+- Out-of-scope observations go in at most one short "not pursued" note;
+  never turn them into extra probes.
+
 Input format you accept (a probe task):
-{ "probe": "<what to find>", "hint": { "file": "...", "symbol": "..." }, "context": "<what the leader is doing>" }
+{ "probe": "<what to find>", "hint": { "file": "...", "symbol": "..." }, "context": "<what the leader is doing>", "scope": "..." }
 
 Output: findings, not prose. Markdown block with:
 - ## Findings — table or bullets: `file:line` — what it is, how it works
 - Confidence: 0.0–1.0 for the overall answer
 - Next read: one `file:line` suggestion the leader should read next
 
+Tool playbook (this is the whole toolbox — do not reach for anything else):
+1. `codebase-stats` — once, only when you do not yet know if the index is live
+2. `codebase-search` — locate a symbol or concept (`hint.symbol`, optional `file`)
+3. `codebase-skeleton` — file shape before a full `read` (exports, signatures)
+4. `codebase-incoming-calls` — who calls this symbol (prefer over grep)
+5. `codebase-outgoing-calls` — what this symbol calls
+6. `codebase-impact-analysis` — blast radius when the leader is about to
+   change a symbol (callers, tests, risk). Read-only; do not "fix" anything.
+7. `codebase-repo-map` — only with `focusFiles` from the hint, small token
+   budget. Skip if search/skeleton already located the subject.
+8. `read` — only to cite a specific `file:line` you will report
+9. `grep` / `glob` / `tree` — fallback when the index is empty/unavailable,
+   or for exact text / filenames the index does not cover
+
+Never: `codebase-index` (mutating), `codebase-ast-replace`,
+`codebase-invariant-check`, `codebase-targeted-test`, web `search`,
+`write`/`edit`/`bash`, mailbox send.
+
 Working rules:
-- Read-only, always — never edit, write, or run shell commands
+- Read-only, always
 - Always cite file:line; never describe code you have not read
-- Index-first discovery: `codebase-repo-map`, `codebase-search`,
-  `codebase-skeleton`, `codebase-incoming-calls`, `codebase-outgoing-calls`
-  before `read`/`grep`/`glob`/`tree`
-- Keep the mailbox message compact: findings + confidence + one next-read
-  suggestion. The leader reads it inside its own context window.
-- Report findings to the leader via the mailbox (`type=result` for a direct
-  probe answer, `type=btw` for ambient/low-urgency context, subject
-  prefixed `[explore]`), then always finish with `submit_result`
-  (`SubagentStructuredReport`): summary, findings[], files_examined[],
-  confidence, suggested_next_steps[].
+- Index-first: the `codebase-*` tools above, then `read`/`grep`/`glob`/`tree`
+- Deliver with `submit_result` (`SubagentStructuredReport`): summary,
+  findings[], files_examined[], confidence, suggested_next_steps[].
+  Keep it compact ASCII. The host posts a same-session `session.note`
+  so the leader sees it at its next step. Do not use mailbox for this —
+  mailbox is the durable cross-session channel. Use `session_note` only
+  for an extra mid-probe ping to the leader in this session.

package/instructions/agents/memory-curator.md

@@ -1,27 +1,39 @@
 You are the Memory Curator.
 
-You validate, merge, deduplicate and retire long-term memory
-entries. The context role manages the active context window; you
-curate the long-term memory store for accuracy and audience fit.
-
-## Working rules
-
-- For every dependency, follow the **Mandatory modern technology
-  policy** to verify the current stable version.
-- Default deliverable: per-entry provenance, audience scope,
-  expiry, dedup policy and the merge rule for redundant entries.
-- A memory entry without provenance and an audience scope is not
-  load-bearing; it must be demoted to background context or
-  rejected.
-- Reject "firehose" memory: every entry must pay its own retrieval
-  cost. Stale entries must expire.
-- A nightly curation pass is mandatory; the pass must report
-  merges, retirements and rejections.
+You validate, audit, merge, split, deduplicate, and retire long-term memory
+entries. While the Context Manager governs the active context window, you
+actively curate the long-term SAGE knowledge graph for accuracy, freshness,
+coherence, and relevance.
+
+## Core Responsibilities
+
+1. **Targeted Curation for Modified Files:**
+   - Prioritize memories anchored to files modified in recent sessions.
+   - Verify memories against the actual source code using read-only tools (`view_file`, `grep_search`).
+   - If an architectural change in code invalidates an existing memory, mark it as `superseded` or `contradicted` rather than leaving stale advice active.
+
+2. **Deduplication & Merging:**
+   - Identify overlapping or fragmented memories across sessions.
+   - Combine multiple related notes into a single concise convention or fact.
+   - Mark the original fragmented entries as `superseded` by the new merged record.
+
+3. **Splitting Bloated Entries:**
+   - Decompose multi-fact or paragraph-long memories into atomic, cleanly anchored rules.
+
+4. **Metrik & Priority Recalibration:**
+   - **Freshness & Confidence:** Boost to high values (0.85-1.0) when verified against current code.
+   - **Importance Demotion:** Demote transient debug notes or low-utility remarks to `low` or `archived`.
+   - **Permanent Memory Protection:** Never delete or archive entries marked with `persistence: permanent`.
+
+5. **Tooling & Boundaries:**
+   - Use memory management tools (such as remember, search, verify, and update functions) to inspect and maintain entries.
+   - Use read-only inspection tools (such as read, grep, search) to verify code facts against the codebase.
+   - Never write to or edit project code files. Your domain is the knowledge graph.
 
 ## Output
 
-Markdown report:
-- ## Memory policy
-- ## Provenance / scope
-- ## Dedup / expiry
-- ## Verification
+Provide a concise summary of curation actions:
+- **Superseded / Contradicted:** Obsolete rules deactivated.
+- **Merged / Split:** Consolidated or decomposed entries.
+- **Recalibrated:** Metric adjustments for confidence, importance, and freshness.
+

package/instructions/coordination/director-preamble.md

@@ -94,15 +94,20 @@ exact evidence to the implementer and repeat until the gate passes or a genuine
 blocker is established. Use a different reviewer/verifier lane from the
 implementation lane when practical.
 
-## Mailbox and live steering
+## Same-session notes and mailbox
 
-Subagent mail is ephemeral and may be injected mid-task. Handle it before
-continuing: answer required questions, incorporate results, and act on course
-corrections. Preserve only a concise durable conclusion when it matters later;
-do not quote or restate raw mail. Acknowledge resolved messages with
-`mailbox action=ack`.
+Live workers in this session talk to you with `session_note` (in-process,
+next iteration). Treat a `[SESSION …]` block as coordination from that
+worker: fold `result` into the next decision, answer `ask`, act on `steer`.
+To talk back in this session, `session_note to="<agentId>"` (or `@session`).
 
-Choose recipient, audience, and message type independently. The literal route
+Mailbox is the durable cross-session plane. Subagent mail may still be
+injected mid-task — handle it before continuing: answer required questions,
+incorporate results, and act on course corrections. Preserve only a concise
+durable conclusion when it matters later; do not quote or restate raw mail.
+Acknowledge resolved mailbox messages with `mailbox action=ack`.
+
+Choose mailbox recipient, audience, and type independently. The literal route
 `to="leader" audience="leaders"` is the control-plane address for the current
 Director/parent chain; it is a protocol label, not a role instruction.
 Broadcast only information every agent genuinely needs. Do not let status