wendkeep 0.76.3 → 0.76.4

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.76.4] — 2026-08-22
+
+### Added
+
+- **Registry multi-contexto.** `active_contexts` mantém change, branch e HEAD por
+  `repository_id` + `worktree_id` + `work_session_id`, com schema, revisão, CAS e writes atômicos;
+  duas worktrees ou sessões deixam de sobrescrever o foco operacional umas das outras.
+- **Resolução causal de change.** Change, spec e verify usam a sessão/worktree chamadora; ausência
+  de sessão só aceita um contexto inequívoco e qualquer ambiguidade falha fechado.
+- **Compatibilidade conservadora.** `CURRENT_CHANGE.md` é somente projeção quando há um único
+  contexto ativo, e a migração legada não inventa worktree ou sessão quando a identidade não pode
+  ser provada.
+
 ## [0.76.3] — 2026-08-21
 
 ### Added

package/README.en.md

@@ -115,7 +115,7 @@ npx wendkeep init
 
 1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
 2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault, then merge the session hooks into **`.claude/settings.json`**. The binding is provider-neutral by design: any agent resolves the same vault from its session `cwd`, with no machine-global environment variable. Older registrations already in `.claude/settings.json` are adopted automatically.
-3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. If a divergence is already quarantined, `context status --session <id>` inventories sanitized `reserved`/`observed` candidates; `context recover --session <id> --select <reserved|observed> --revision <n> --reason <text>` requires an explicit choice, CAS, and current-checkout proof, failing closed before clearing the conflict if revalidation changes. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
+3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. If a divergence is already quarantined, `context status --session <id>` inventories sanitized `reserved`/`observed` candidates; `context recover --session <id> --select <reserved|observed> --revision <n> --reason <text>` requires an explicit choice, CAS, and current-checkout proof, failing closed before clearing the conflict if revalidation changes. The change lifecycle uses `active_contexts`, identified by `repository_id` + `worktree_id` + `work_session_id`; two matching sessions fail with ambiguity instead of selecting silently, `CURRENT_CHANGE.md` is only a derived projection for one unambiguous context, and migration never invents a worktree or session identity. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
 4. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 5. Offer to pin **companion** plugins/MCP (multi-choice; **none** pre-checked — wendkeep is a neutral harness and presumes no third-party plugin). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, wired as a Claude Code plugin. It ships its own MCP server, so wendkeep deliberately adds no `.mcp.json` entry (registering both cold-started two servers at once). On non-Claude agents, add the MCP by hand: `npx -y context-mode`.
@@ -239,7 +239,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 |---|---|---|
 | **Installation and updates** | `init`, `sync`, companions, and the first project↔vault binding | [Installation and first use](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/getting-started.md) |
 | **Managed worktrees** | `worktree create/list/status/open`, Vault binding, and recovery | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
-| **Active context** | `context switch/status/recover`, causal transition, quarantine, and explicit recovery | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.md) |
+| **Active context** | `active_contexts` by `repository_id`/`worktree_id`/`work_session_id`, causal transition, quarantine, and explicit recovery | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.md) |
 | **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
 | **Changes and verification** | `change`, specs, sensors, TDD, evidence, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |
 | **Shared memory** | CORE, SHARED, status, validation, repair, and curation | [Memory](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory.md) |

package/README.md

@@ -115,7 +115,7 @@ npx wendkeep init
 
 1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
 2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault, then merge the session hooks into **`.claude/settings.json`**. The binding is provider-neutral by design: any agent resolves the same vault from its session `cwd`, with no machine-global environment variable. Older registrations already in `.claude/settings.json` are adopted automatically.
-3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. If a divergence is already quarantined, `context status --session <id>` inventories sanitized `reserved`/`observed` candidates; `context recover --session <id> --select <reserved|observed> --revision <n> --reason <text>` requires an explicit choice, CAS, and current-checkout proof, failing closed before clearing the conflict if revalidation changes. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
+3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. If a divergence is already quarantined, `context status --session <id>` inventories sanitized `reserved`/`observed` candidates; `context recover --session <id> --select <reserved|observed> --revision <n> --reason <text>` requires an explicit choice, CAS, and current-checkout proof, failing closed before clearing the conflict if revalidation changes. The change lifecycle uses `active_contexts`, identified by `repository_id` + `worktree_id` + `work_session_id`; two matching sessions fail with ambiguity instead of selecting silently, `CURRENT_CHANGE.md` is only a derived projection for one unambiguous context, and migration never invents a worktree or session identity. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
 4. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 5. Offer to pin **companion** plugins/MCP (multi-choice; **none** pre-checked — wendkeep is a neutral harness and presumes no third-party plugin). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, wired as a Claude Code plugin. It ships its own MCP server, so wendkeep deliberately adds no `.mcp.json` entry (registering both cold-started two servers at once). On non-Claude agents, add the MCP by hand: `npx -y context-mode`.
@@ -239,7 +239,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 |---|---|---|
 | **Installation and updates** | `init`, `sync`, companions, and the first project↔vault binding | [Installation and first use](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/getting-started.md) |
 | **Managed worktrees** | `worktree create/list/status/open`, Vault binding, and recovery | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
-| **Active context** | `context switch/status/recover`, causal transition, quarantine, and explicit recovery | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.md) |
+| **Active context** | `active_contexts` by `repository_id`/`worktree_id`/`work_session_id`, causal transition, quarantine, and explicit recovery | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.md) |
 | **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
 | **Changes and verification** | `change`, specs, sensors, TDD, evidence, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |
 | **Shared memory** | CORE, SHARED, status, validation, repair, and curation | [Memory](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory.md) |

package/docs/en/commands/changes-and-verification.md

@@ -25,12 +25,12 @@ Initialize the project, keep the vault healthy, and provide a valid `wendkeep.se
 ## Syntax
 
 ```bash
-npx wendkeep change new <slug> [--simple|--guide]
-npx wendkeep change status [slug]
-npx wendkeep spec effective --change <slug>
+npx wendkeep change new <slug> [--simple|--guide] [--session <id>]
+npx wendkeep change status [slug] [--session <id>]
+npx wendkeep spec effective [--change <slug>] [--session <id>]
 npx wendkeep sensors list
-npx wendkeep verify [--deep] [--change <slug>]
-npx wendkeep change archive <slug>
+npx wendkeep verify [--deep] [--change <slug>] [--session <id>]
+npx wendkeep change archive <slug> [--session <id>]
 ```
 
 ## Options and exit codes
@@ -43,6 +43,8 @@ npx wendkeep change archive <slug>
   without archiving it.
 - `change continue <archived> <new>` starts follow-up work without inheriting stale proof.
 - `change bind <slug> --session <id>` attaches an existing session.
+- `--session <id>` selects the causal `active_contexts` entry for implicit commands. Without it,
+  only one unambiguous active context for the worktree is accepted; ambiguity returns exit `2`.
 - `change relink [--apply]` and `change backlink [--apply]` repair graph links; preview is default.
 - `change abandon <slug>` drops work without an ADR; `archive --force` needs explicit human choice.
 - `wendkeep spec list|show|effective|migrate|rebase` manages living contracts and deltas.
@@ -54,6 +56,7 @@ npx wendkeep change archive <slug>
 
 ```bash
 npx wendkeep change new tenant-login
+npx wendkeep change use tenant-login --session <id>
 npx wendkeep change new internal-adjustment --guide
 npx wendkeep spec effective --change tenant-login
 npx wendkeep change done 1.1 --change tenant-login
@@ -82,6 +85,10 @@ tool runs, it compares the session, project, Git root, remote, branch, and workt
 recorded in `SESSION_REGISTRY.json`. Missing, ambiguous, concurrent, or cross-project targets are
 blocked before the tool.
 
+Implicit change focus comes from `active_contexts`, not `CURRENT_CHANGE.md`. Its key combines
+`repository_id`, `worktree_id`, and `work_session_id`; the Markdown pointer remains only a
+compatibility projection when there is one unambiguous context.
+
 The [local Observer](observer.md) is a read-only observability projection: the vault and change
 remain local authorities. Observer queries do not complete, archive, repair, or promote state in a
 vault.

package/docs/en/commands/context.md

@@ -85,6 +85,22 @@ preserves the change/lease/authorizations, clears only the quarantine, and appen
 receipt to `context_recoveries`. Any failure leaves the registry and quarantine byte-identical.
 This is fail-closed: no candidate, receipt, or partial scope is published after a failed check.
 
+### Multi-context change registry
+
+`SESSION_REGISTRY.json` keeps `active_contexts` with its own schema and revision. Each entry is
+identified by `repository_id` + `worktree_id` + `work_session_id`; branch, HEAD, and `change_slug`
+belong to that entry. Two worktrees can therefore select different changes without overwriting
+each other's operational focus.
+
+With an explicit causal session, change, spec, and verify resolve only the matching entry. Without
+a session, only one active entry for the worktree is accepted; two sessions produce ambiguity and
+the operation must fail closed without silently selecting a change.
+
+`CURRENT_CHANGE.md` is only a derived projection: it contains a change when there is one single,
+unambiguous active context. With zero or multiple contexts it stays empty. Migration is conservative
+and never invents a worktree or session identity. The legacy pointer becomes a context only
+when one active session, a complete scope, and worktree metadata prove one identity.
+
 ## Common errors and diagnosis
 
 - `WENDKEEP_CONTEXT_AMBIGUOUS`: pass `--session <id>`; no candidate is selected silently.

package/docs/pt-BR/commands/changes-and-verification.md

@@ -25,12 +25,12 @@ Tenha o projeto inicializado, um vault saudável e `wendkeep.sensors.json` váli
 ## Sintaxe
 
 ```bash
-npx wendkeep change new <slug> [--simple|--guide]
-npx wendkeep change status [slug]
-npx wendkeep spec effective --change <slug>
+npx wendkeep change new <slug> [--simple|--guide] [--session <id>]
+npx wendkeep change status [slug] [--session <id>]
+npx wendkeep spec effective [--change <slug>] [--session <id>]
 npx wendkeep sensors list
-npx wendkeep verify [--deep] [--change <slug>]
-npx wendkeep change archive <slug>
+npx wendkeep verify [--deep] [--change <slug>] [--session <id>]
+npx wendkeep change archive <slug> [--session <id>]
 ```
 
 ## Opções e códigos de saída
@@ -43,6 +43,8 @@ npx wendkeep change archive <slug>
   trabalho sem arquivar.
 - `change continue <arquivada> <nova>` abre continuação sem herdar evidência antiga.
 - `change bind <slug> --session <id>` liga uma sessão existente.
+- `--session <id>` seleciona o `active_contexts` causal nos comandos implícitos. Sem a opção,
+  somente um contexto ativo inequívoco da worktree é aceito; ambiguidade retorna exit `2`.
 - `change relink [--apply]` e `change backlink [--apply]` reparam o grafo; dry-run é o padrão.
 - `change abandon <slug>` descarta sem ADR; `archive --force` exige decisão humana explícita.
 - `wendkeep spec list|show|effective|migrate|rebase` administra contratos vivos e deltas.
@@ -54,6 +56,7 @@ npx wendkeep change archive <slug>
 
 ```bash
 npx wendkeep change new login-tenant
+npx wendkeep change use login-tenant --session <id>
 npx wendkeep change new ajuste-interno --guide
 npx wendkeep spec effective --change login-tenant
 npx wendkeep change done 1.1 --change login-tenant
@@ -82,6 +85,10 @@ uma ferramenta de escrita suportada, ele compara sessão, projeto, raiz Git, rem
 worktree com a lease registrada no `SESSION_REGISTRY.json`. Um alvo ausente, ambíguo, concorrente ou
 fora do projeto é bloqueado antes da ferramenta.
 
+O foco implícito de change vem de `active_contexts`, não de `CURRENT_CHANGE.md`. A chave combina
+`repository_id`, `worktree_id` e `work_session_id`; o ponteiro Markdown permanece apenas como
+projeção compatível quando existe um único contexto inequívoco.
+
 O [Observer local](observer.md) é uma projeção read-only da observabilidade: o vault e a change
 continuam autoridades locais. Consultas do Observer não concluem, arquivam, reparam ou promovem
 estado no vault.

package/docs/pt-BR/commands/context.md

@@ -82,6 +82,22 @@ atuais. Sob o lock do registry, o comando revalida a revisão, incrementa `conte
 change/lease/autorizações, limpa somente a quarentena e anexa um receipt sanitizado em
 `context_recoveries`. Qualquer falha deixa registry e quarentena byte a byte intactos.
 
+### Registry multi-contexto de changes
+
+O `SESSION_REGISTRY.json` mantém `active_contexts` com schema e revisão próprios. Cada entrada é
+identificada por `repository_id` + `worktree_id` + `work_session_id`; branch, HEAD e `change_slug`
+pertencem a essa entrada. Assim, duas worktrees podem selecionar changes diferentes sem
+sobrescrever o foco uma da outra.
+
+Com sessão causal explícita, change, spec e verify resolvem somente a entrada correspondente. Sem
+sessão, uma única entrada ativa da worktree pode ser usada; duas sessões compatíveis causam
+ambiguidade e a operação falha fechada, sem escolher uma change em silêncio.
+
+`CURRENT_CHANGE.md` é apenas uma projeção derivada: contém a change somente quando existe um único
+contexto ativo inequívoco. Com zero ou múltiplos contextos, fica vazio. A migração é conservadora:
+não inventa uma identidade de worktree ou sessão. O ponteiro legado só vira contexto quando uma sessão
+ativa, scope completa e metadados da worktree provam uma única identidade.
+
 ## Erros comuns e diagnóstico
 
 - `WENDKEEP_CONTEXT_AMBIGUOUS`: informe `--session <id>`; nenhuma candidata é escolhida em silêncio.

package/hooks/active-context-store.mjs

@@ -0,0 +1,232 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { mutateSessionRegistry, readSessionRegistry } from './obsidian-common.mjs';
+import { mkdirVaultPath, writeVaultFileSync } from './vault-path-safety.mjs';
+
+export const ACTIVE_CONTEXTS_SCHEMA_VERSION = 1;
+const POINTER = '.brain/CURRENT_CHANGE.md';
+const ID_PATTERN = /^[A-Za-z0-9._-]{1,160}$/;
+const SLUG_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$/;
+
+function contextError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function requiredId(value, label) {
+  const normalized = String(value || '').trim();
+  if (!ID_PATTERN.test(normalized)) {
+    throw contextError('WENDKEEP_ACTIVE_CONTEXT_IDENTITY_INVALID', `${label} inválido ou ausente`);
+  }
+  return normalized;
+}
+
+function optionalText(value, maxLength = 240) {
+  const normalized = String(value || '').trim();
+  return normalized.length <= maxLength ? normalized : normalized.slice(0, maxLength);
+}
+
+function normalizeIdentity(identity = {}, { requireWorkSession = true } = {}) {
+  const workSessionId = requireWorkSession
+    ? requiredId(identity.workSessionId ?? identity.work_session_id, 'work_session_id')
+    : optionalText(identity.workSessionId ?? identity.work_session_id, 160);
+  return {
+    projectId: requiredId(identity.projectId ?? identity.project_id, 'project_id'),
+    repositoryId: requiredId(identity.repositoryId ?? identity.repository_id, 'repository_id'),
+    worktreeId: requiredId(identity.worktreeId ?? identity.worktree_id, 'worktree_id'),
+    workSessionId,
+    branch: optionalText(identity.branch, 240),
+    headSha: optionalText(identity.headSha ?? identity.head_sha, 80),
+  };
+}
+
+export function activeContextKey(identity) {
+  const normalized = normalizeIdentity(identity);
+  return `${normalized.repositoryId}:${normalized.worktreeId}:${normalized.workSessionId}`;
+}
+
+function contextsOf(registry) {
+  return registry?.active_contexts && typeof registry.active_contexts === 'object'
+    && !Array.isArray(registry.active_contexts)
+    ? registry.active_contexts : {};
+}
+
+function currentGlobalRevision(registry) {
+  const value = Number(registry?.active_contexts_revision);
+  return Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+function currentContextRevision(context) {
+  const value = Number(context?.revision);
+  return Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+function activeContexts(registry) {
+  return Object.entries(contextsOf(registry)).filter(([, context]) => context?.state === 'active');
+}
+
+function legacyProjection(registry) {
+  const active = activeContexts(registry);
+  if (active.length !== 1) return '';
+  return String(active[0][1]?.change_slug || '').trim();
+}
+
+export function projectLegacyActiveChange(vaultBase, registry = readSessionRegistry(vaultBase)) {
+  const slug = legacyProjection(registry);
+  mkdirVaultPath(vaultBase, join(vaultBase, '.brain'), { label: 'raiz de controle da change' });
+  writeVaultFileSync(
+    vaultBase,
+    join(vaultBase, POINTER),
+    slug ? `change: ${slug}\n` : 'change:\n',
+    'utf8',
+    { label: 'projeção legada CURRENT_CHANGE.md' },
+  );
+  return slug;
+}
+
+export function resolveActiveContext(vaultBase, query = {}) {
+  const normalized = normalizeIdentity(query, { requireWorkSession: false });
+  const registry = readSessionRegistry(vaultBase);
+  let workSessionId = normalized.workSessionId;
+  const sessionId = optionalText(query.sessionId ?? query.session_id, 160);
+  if (!workSessionId && sessionId) {
+    const entry = registry.sessions?.[sessionId];
+    if (entry?.status !== 'active' || !entry.work_session_id) {
+      throw contextError('WENDKEEP_ACTIVE_CONTEXT_NOT_FOUND', 'sessão causal ativa não encontrada');
+    }
+    workSessionId = String(entry.work_session_id);
+  }
+
+  const candidates = activeContexts(registry).filter(([, context]) => (
+    context.project_id === normalized.projectId
+    && context.repository_id === normalized.repositoryId
+    && context.worktree_id === normalized.worktreeId
+    && (!workSessionId || context.work_session_id === workSessionId)
+  ));
+  if (!candidates.length) {
+    throw contextError('WENDKEEP_ACTIVE_CONTEXT_NOT_FOUND', 'active context não encontrado para a identidade informada');
+  }
+  if (candidates.length > 1) {
+    throw contextError(
+      'WENDKEEP_ACTIVE_CONTEXT_AMBIGUOUS',
+      'mais de um active context corresponde à worktree; informe a sessão causal',
+    );
+  }
+  return structuredClone(candidates[0][1]);
+}
+
+export function mutateActiveContext(vaultBase, identity, updater, {
+  expectedRevision,
+  now = new Date().toISOString(),
+  mutateRegistry = mutateSessionRegistry,
+} = {}) {
+  const normalized = normalizeIdentity(identity);
+  const key = activeContextKey(normalized);
+  const result = mutateRegistry(vaultBase, (registry) => {
+    const contexts = contextsOf(registry);
+    const existing = contexts[key] || null;
+    const revision = currentContextRevision(existing);
+    if (expectedRevision !== undefined && Number(expectedRevision) !== revision) {
+      throw contextError(
+        'WENDKEEP_ACTIVE_CONTEXT_STALE',
+        `active context revision mudou de ${expectedRevision} para ${revision}`,
+      );
+    }
+    const base = existing || {
+      project_id: normalized.projectId,
+      repository_id: normalized.repositoryId,
+      worktree_id: normalized.worktreeId,
+      work_session_id: normalized.workSessionId,
+      branch: normalized.branch,
+      head_sha: normalized.headSha,
+      change_slug: '',
+      state: 'active',
+      revision: 0,
+      updated_at: String(now),
+    };
+    const updated = updater(structuredClone(base));
+    if (!updated || typeof updated !== 'object' || Array.isArray(updated)) {
+      throw contextError('WENDKEEP_ACTIVE_CONTEXT_INVALID', 'mutação retornou active context inválido');
+    }
+    for (const [field, expected] of [
+      ['project_id', normalized.projectId],
+      ['repository_id', normalized.repositoryId],
+      ['worktree_id', normalized.worktreeId],
+      ['work_session_id', normalized.workSessionId],
+    ]) {
+      if (updated[field] !== expected) {
+        throw contextError('WENDKEEP_ACTIVE_CONTEXT_IDENTITY_MISMATCH', `${field} não pode mudar`);
+      }
+    }
+    const next = {
+      ...updated,
+      branch: normalized.branch || optionalText(updated.branch, 240),
+      head_sha: normalized.headSha || optionalText(updated.head_sha, 80),
+      state: updated.state === 'closed' ? 'closed' : 'active',
+      revision: revision + 1,
+      updated_at: String(now),
+    };
+    registry.active_contexts_schema = ACTIVE_CONTEXTS_SCHEMA_VERSION;
+    registry.active_contexts_revision = currentGlobalRevision(registry) + 1;
+    registry.active_contexts = { ...contexts, [key]: next };
+    return { key, context: structuredClone(next), registryRevision: registry.active_contexts_revision };
+  });
+  projectLegacyActiveChange(vaultBase);
+  return result;
+}
+
+export function setActiveContextChange(vaultBase, identity, slug, options = {}) {
+  const normalizedSlug = String(slug || '').trim();
+  if (!SLUG_PATTERN.test(normalizedSlug)) {
+    throw contextError('WENDKEEP_ACTIVE_CONTEXT_CHANGE_INVALID', 'change_slug inválido ou ausente');
+  }
+  return mutateActiveContext(vaultBase, identity, (context) => ({
+    ...context,
+    change_slug: normalizedSlug,
+    state: 'active',
+  }), options);
+}
+
+export function clearActiveContextChange(vaultBase, identity, options = {}) {
+  return mutateActiveContext(vaultBase, identity, (context) => ({
+    ...context,
+    change_slug: '',
+    state: 'active',
+  }), options);
+}
+
+function legacyPointer(vaultBase) {
+  try {
+    return readFileSync(join(vaultBase, POINTER), 'utf8').match(/^change:\s*(.+)$/m)?.[1]?.trim() || '';
+  } catch {
+    return '';
+  }
+}
+
+export function migrateLegacyActiveContext(vaultBase, {
+  identityForSession,
+  now = new Date().toISOString(),
+} = {}) {
+  const slug = legacyPointer(vaultBase);
+  if (!slug) return { migrated: false, reason: 'no-pointer' };
+  const registry = readSessionRegistry(vaultBase);
+  if (Object.keys(contextsOf(registry)).length) return { migrated: false, reason: 'already-initialized' };
+  if (typeof identityForSession !== 'function') return { migrated: false, reason: 'identity-unavailable' };
+
+  const candidates = [];
+  for (const [sessionId, entry] of Object.entries(registry.sessions || {})) {
+    if (entry?.status !== 'active' || entry?.project_scope?.complete !== true || !entry?.work_session_id) continue;
+    let candidate;
+    try { candidate = normalizeIdentity(identityForSession(sessionId, entry)); } catch { continue; }
+    if (candidate.projectId !== entry.project_scope.projectId
+      || candidate.workSessionId !== String(entry.work_session_id)) continue;
+    candidates.push(candidate);
+  }
+  if (candidates.length !== 1) {
+    return { migrated: false, reason: candidates.length ? 'ambiguous' : 'identity-unavailable' };
+  }
+  const result = setActiveContextChange(vaultBase, candidates[0], slug, { now });
+  return { migrated: true, key: result.key, context: result.context };
+}

package/hooks/change-core.mjs

@@ -10,6 +10,11 @@ import {
   assertVaultPathSafe, assertVaultPathsSafe, mkdirVaultPath, renameVaultPath,
   unlinkVaultFile, writeVaultFileSync,
 } from './vault-path-safety.mjs';
+import {
+  clearActiveContextChange,
+  resolveActiveContext,
+  setActiveContextChange,
+} from './active-context-store.mjs';
 
 export const ARCHIVE_DIR = '_arquivo';
 const POINTER = '.brain/CURRENT_CHANGE.md';
@@ -118,7 +123,14 @@ export function scaffoldPlaceholders(dir) {
   return found;
 }
 
-export function activeChange(vaultBase) {
+export function activeChange(vaultBase, { context } = {}) {
+  if (context) {
+    try { return String(resolveActiveContext(vaultBase, context).change_slug || '').trim(); }
+    catch (error) {
+      if (error?.code === 'WENDKEEP_ACTIVE_CONTEXT_NOT_FOUND') return '';
+      throw error;
+    }
+  }
   try {
     const m = readFileSync(join(vaultBase, POINTER), 'utf8').match(/^change:\s*(.+)$/m);
     return m ? m[1].trim() : '';
@@ -127,7 +139,8 @@ export function activeChange(vaultBase) {
   }
 }
 
-export function setActiveChange(vaultBase, slug) {
+export function setActiveChange(vaultBase, slug, { context } = {}) {
+  if (context) return setActiveContextChange(vaultBase, context, slug);
   mkdirVaultPath(vaultBase, join(vaultBase, '.brain'), { label: 'raiz de controle da change' });
   writeVaultFileSync(
     vaultBase,
@@ -138,7 +151,8 @@ export function setActiveChange(vaultBase, slug) {
   );
 }
 
-export function clearActiveChange(vaultBase) {
+export function clearActiveChange(vaultBase, { context } = {}) {
+  if (context) return clearActiveContextChange(vaultBase, context);
   const p = join(vaultBase, POINTER);
   const checked = assertVaultPathSafe(vaultBase, p, {
     expectedType: 'file', label: 'ponteiro CURRENT_CHANGE.md',
@@ -191,7 +205,9 @@ export function assertChangeScaffoldTargetsSafe(vaultBase, slug, {
   return { dir, rel: changeDirRel(slug, vaultBase) };
 }
 
-export function newChange(vaultBase, slug, { sessionRel = '', dateStr, simple = false, guide = false }) {
+export function newChange(vaultBase, slug, {
+  sessionRel = '', dateStr, simple = false, guide = false, context,
+}) {
   const compact = simple || guide;
   const loc = getLocale(vaultBase);
   const { dir } = assertChangeScaffoldTargetsSafe(vaultBase, slug, { simple: compact });
@@ -218,14 +234,14 @@ export function newChange(vaultBase, slug, { sessionRel = '', dateStr, simple =
     write('design.md', files.design);
   }
   if (!existed) captureSpecBaseline(vaultBase, dir);
-  setActiveChange(vaultBase, slug);
+  setActiveChange(vaultBase, slug, { context });
   return { rel: changeDirRel(slug, vaultBase), created: !existed };
 }
 
-export function useChange(vaultBase, slug) {
+export function useChange(vaultBase, slug, { context } = {}) {
   const dir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
   if (!existsSync(join(dir, 'proposta.md'))) return { ok: false, error: `change aberta não encontrada: ${slug}` };
-  setActiveChange(vaultBase, slug);
+  setActiveChange(vaultBase, slug, { context });
   return { ok: true, rel: changeDirRel(slug, vaultBase) };
 }
 
@@ -314,8 +330,8 @@ export function listChanges(vaultBase) {
 // comandos implícitos; provider/session nunca filtram a fila, para que outro agente possa assumir
 // o trabalho. O hash leva o conteúdo inteiro de cada tarefas.md — não apenas as contagens — pois
 // ele controla a reinjeção por sessão dos hooks.
-export function allChangesState(vaultBase) {
-  const current = activeChange(vaultBase);
+export function allChangesState(vaultBase, { context } = {}) {
+  const current = activeChange(vaultBase, { context });
   const { active } = listChanges(vaultBase);
   const chDir = getLocale(vaultBase).folders.changes;
   const fingerprint = [`current:${current}`];
@@ -407,16 +423,16 @@ export function buildActiveChangeInjection(vaultBase, options = {}) {
   return renderOpenChanges(allChangesState(vaultBase), options);
 }
 
-export function activeChangeLink(vaultBase) {
-  const slug = activeChange(vaultBase);
+export function activeChangeLink(vaultBase, { context } = {}) {
+  const slug = activeChange(vaultBase, { context });
   return slug ? `Change ativa: [[${getLocale(vaultBase).folders.changes}/${slug}/proposta]]` : '';
 }
 
 // --- Estado rápido do gate + sentinelas por sessão (0.31.0) --------------------
 // Fonte única e barata (só leituras, tudo fail-open) do estado do gate, consumida pelos hooks
 // de lifecycle (change-guard/change-nag/change-context) e pelo CLI. null sem change ativa.
-export function quickGateState(vaultBase) {
-  const slug = activeChange(vaultBase);
+export function quickGateState(vaultBase, { context } = {}) {
+  const slug = activeChange(vaultBase, { context });
   if (!slug) return null;
   const dir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
   let tarefasMd = '';
@@ -536,7 +552,9 @@ export function gateGreen() {
   return { ok: true, failing: [] };
 }
 
-export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrNum, adrFlags = {} }) {
+export function archiveChange(vaultBase, slug, {
+  gate = gateGreen, dateStr, adrNum, adrFlags = {}, context,
+}) {
   const loc = getLocale(vaultBase);
   const chDir = loc.folders.changes;
   const src = join(vaultBase, chDir, slug);
@@ -656,7 +674,7 @@ Mudança ${changeWikilink} concluída e arquivada.${capLine}${reqLine}${forcedNo
 
   // Only clear the pointer when the archived change IS the active one — archiving some other
   // slug explicitly must not blank the pointer of a different, still-active change.
-  if (activeChange(vaultBase) === slug) clearActiveChange(vaultBase);
+  if (activeChange(vaultBase, { context }) === slug) clearActiveChange(vaultBase, { context });
   return { ok: true, failing: [], archivedRel: destRel, adrRel: createAdr ? adrRel : '', promoted, specWarnings, linksRewritten };
 }
 
@@ -849,7 +867,7 @@ export function relinkChanges(vaultBase, { apply = false } = {}) {
 // Abandono (0.31.0): a saída legítima para uma change que não vai adiante — o que antes só o
 // `archive --force` "resolvia", minting um ADR falso. Sem ADR, sem promoteSpecs (abandono não é
 // decisão arquitetural nem promove contrato); move para _arquivo com sufixo -abandonada.
-export function abandonChange(vaultBase, slug, { dateStr }) {
+export function abandonChange(vaultBase, slug, { dateStr, context } = {}) {
   const chDir = getLocale(vaultBase).folders.changes;
   const src = join(vaultBase, chDir, slug);
   const checkedProposal = assertVaultPathSafe(vaultBase, join(src, 'proposta.md'), {
@@ -882,6 +900,6 @@ export function abandonChange(vaultBase, slug, { dateStr }) {
   } catch { /* proposta sem frontmatter — segue */ }
   let linksRewritten = 0;
   try { linksRewritten = rewriteChangeLinks(vaultBase, `${chDir}/${slug}`, destRel.replaceAll('\\', '/')); } catch { /* abandono já íntegro */ }
-  if (activeChange(vaultBase) === slug) clearActiveChange(vaultBase);
+  if (activeChange(vaultBase, { context }) === slug) clearActiveChange(vaultBase, { context });
   return { ok: true, failing: [], archivedRel: destRel, linksRewritten };
 }

package/hooks/obsidian-common.mjs

@@ -276,9 +276,12 @@ export function readSessionRegistry(vaultBase) {
 
   try {
     const parsed = JSON.parse(readFileSync(checked.target, 'utf-8'));
+    const root = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
     return {
-      version: Math.max(2, parsed.version || 1),
-      sessions: parsed.sessions && typeof parsed.sessions === 'object' ? parsed.sessions : {},
+      ...root,
+      version: Math.max(2, root.version || 1),
+      sessions: root.sessions && typeof root.sessions === 'object' && !Array.isArray(root.sessions)
+        ? root.sessions : {},
     };
   } catch {
     return { version: 2, sessions: {} };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.76.3",
+  "version": "0.76.4",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [

package/packages/cli/src/index.mjs

@@ -64,6 +64,7 @@ Usage:
                            Inspect or explicitly recover a quarantined causal scope conflict.
   wendkeep change <sub>        Change lifecycle: new [--simple|--guide] | use | bind <slug> --session <id> | continue | list | show |
                            status | done <id> | undone <id> | diff | archive [--force] | abandon | relink | backlink.
+                           --session <id> selects the causal active_context for implicit change operations.
                            archive exige verdict (rode verify --deep); abandon descarta sem ADR.
                            backlink [--apply]: injeta o backlink pro proposta em design/tarefas/spec órfãos (open + _arquivo).
   wendkeep theme sync          Re-aplica o color system (snippet CSS + graph color groups) num vault
@@ -76,7 +77,7 @@ Usage:
                            FLOW records scope, sensors and a receipt without creating a change.
   wendkeep delivery <sub>      Operational delivery: start | status | finish | abandon.
                            Records authorization and an append-only receipt; never creates a change/spec/ADR.
-  wendkeep spec <sub>          Specs: list | show | effective [--change] [--json] | migrate | rebase.
+  wendkeep spec <sub>          Specs: list | show | effective [--change] [--session] [--json] | migrate | rebase.
   wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
   wendkeep cost [opts]         Aggregate AI-coding spend across the vault's sessions.
                            --since <date> · --top [N] (priciest) · --trend [day|week|month]
@@ -91,7 +92,7 @@ Usage:
                            --rescan-decisions (capture prose decisions from already-imported transcripts) ·
                            --from <dir> · --codex-from <dir> · --since <date> · --limit N ·
                            --dry-run · --json.
-  wendkeep verify [--deep] [--change s]  Run a change's task sensors + record evidence (the gate);
+  wendkeep verify [--deep] [--change s] [--session id]  Run a change's task sensors + record evidence (the gate);
                            --deep assembles the verification package for the wk-verify pass.
   wendkeep dashboard [--force]  (Re)generate the vault's folder-filtered Bases + 00-Dashboard MOC.
   wendkeep renumber-decisions   Renumber 04-Decisões to ADR-<NNNN>-<slug> in chronological order,

package/src/active-context-runtime.mjs

@@ -0,0 +1,131 @@
+import { readSessionRegistry } from '../hooks/obsidian-common.mjs';
+import { migrateLegacyActiveContext } from '../hooks/active-context-store.mjs';
+import { captureProjectScope, compareProjectScopes } from '../hooks/project-scope.mjs';
+import {
+  discoverWorktreeRepository,
+  readWorktreeRegistry,
+  worktreeIdentity,
+} from '../packages/vault/src/worktree-metadata.mjs';
+import { readProjectForValidation } from '../packages/vault/src/validate-memory.mjs';
+
+function runtimeError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function activeSession(entry) {
+  return entry?.status === 'active'
+    && entry?.project_scope?.complete === true
+    && typeof entry?.work_session_id === 'string'
+    && entry.work_session_id.trim();
+}
+
+export function resolveRuntimeActiveContext({
+  vaultBase,
+  projectRoot = process.cwd(),
+  sessionId = '',
+  spawn,
+} = {}) {
+  const project = readProjectForValidation(vaultBase);
+  if (!project.ok || !project.projectId) {
+    throw runtimeError('WENDKEEP_ACTIVE_CONTEXT_IDENTITY_UNAVAILABLE', 'PROJECT.json não prova project_id');
+  }
+  let repository;
+  try { repository = discoverWorktreeRepository({ startDir: projectRoot, ...(spawn ? { spawn } : {}) }); }
+  catch (error) {
+    throw runtimeError('WENDKEEP_ACTIVE_CONTEXT_IDENTITY_UNAVAILABLE', error.message);
+  }
+  const metadata = readWorktreeRegistry(repository).registry;
+  if (!metadata) {
+    throw runtimeError(
+      'WENDKEEP_ACTIVE_CONTEXT_IDENTITY_UNAVAILABLE',
+      'registry de worktrees ausente; não é seguro inventar repository_id/worktree_id',
+    );
+  }
+  if (metadata.projectId !== project.projectId) {
+    throw runtimeError('WENDKEEP_ACTIVE_CONTEXT_IDENTITY_MISMATCH', 'registry de worktrees pertence a outro projeto');
+  }
+
+  const registry = readSessionRegistry(vaultBase);
+  const sessions = registry.sessions || {};
+  const worktreeId = worktreeIdentity(metadata.repositoryId, repository.gitDir);
+  const requested = String(sessionId || '').trim();
+  const rows = requested ? [[requested, sessions[requested]]] : Object.entries(sessions);
+  const matches = [];
+  for (const [candidateId, entry] of rows) {
+    if (!activeSession(entry)) continue;
+    const actual = captureProjectScope({
+      input: { cwd: projectRoot },
+      projectRoot,
+      projectId: project.projectId,
+      provider: entry.provider || '',
+      sessionId: candidateId,
+      ...(spawn ? { spawn } : {}),
+    });
+    if (!compareProjectScopes(entry.project_scope, actual).ok) continue;
+    matches.push({ sessionId: candidateId, entry, actual });
+  }
+  if (!matches.length) {
+    throw runtimeError(
+      'WENDKEEP_ACTIVE_CONTEXT_NOT_FOUND',
+      requested ? 'sessão causal não corresponde à worktree atual' : 'nenhuma sessão ativa corresponde à worktree atual',
+    );
+  }
+  let selected = matches[0];
+  if (matches.length > 1) {
+    const active = Object.values(registry.active_contexts || {}).filter((context) => (
+      context?.state === 'active'
+      && context.project_id === project.projectId
+      && context.repository_id === metadata.repositoryId
+      && context.worktree_id === worktreeId
+    ));
+    const narrowed = active.length === 1
+      ? matches.filter(({ entry }) => String(entry.work_session_id) === active[0].work_session_id)
+      : [];
+    if (narrowed.length !== 1) {
+      throw runtimeError(
+        'WENDKEEP_ACTIVE_CONTEXT_AMBIGUOUS',
+        'mais de uma sessão ativa corresponde à worktree; informe --session',
+      );
+    }
+    [selected] = narrowed;
+  }
+  return {
+    projectId: project.projectId,
+    repositoryId: metadata.repositoryId,
+    worktreeId,
+    workSessionId: String(selected.entry.work_session_id),
+    branch: selected.actual.branch,
+    headSha: selected.actual.head,
+    sessionId: selected.sessionId,
+  };
+}
+
+export function resolveCommandActiveContext({
+  vaultBase,
+  projectRoot = process.cwd(),
+  sessionId = '',
+  spawn,
+} = {}) {
+  const requestedSession = String(sessionId || '').trim();
+  let identity;
+  try {
+    identity = resolveRuntimeActiveContext({
+      vaultBase, projectRoot, sessionId: requestedSession, ...(spawn ? { spawn } : {}),
+    });
+  } catch (error) {
+    const registry = readSessionRegistry(vaultBase);
+    const initialized = Object.keys(registry.active_contexts || {}).length > 0;
+    const legacyUnavailable = error?.code === 'WENDKEEP_ACTIVE_CONTEXT_IDENTITY_UNAVAILABLE'
+      || (!requestedSession && error?.code === 'WENDKEEP_ACTIVE_CONTEXT_NOT_FOUND');
+    if (!initialized && legacyUnavailable) return null;
+    throw error;
+  }
+  migrateLegacyActiveContext(vaultBase, {
+    identityForSession: (candidateId) => resolveRuntimeActiveContext({
+      vaultBase, projectRoot, sessionId: candidateId, ...(spawn ? { spawn } : {}),
+    }),
+  });
+  return identity;
+}

package/src/change.mjs

@@ -17,6 +17,7 @@ import {
   backfillArtifactLinks,
   scaffoldPlaceholders,
   isGuideCompactChange,
+  setActiveChange,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
 import { buildEffectiveRequirementPackage, evaluateVerdict, formatOrphanReqs, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta, validateSpecImpact } from '../hooks/spec-core.mjs';
@@ -24,6 +25,7 @@ import { getNextAdrNumber, readControl, readSessionRegistry, upsertSessionRegist
 import { getLocale } from '../hooks/locale.mjs';
 import { enqueueObserverDocumentChange } from './observer-sql-publish.mjs';
 import { readProjectForValidation } from '../packages/vault/src/validate-memory.mjs';
+import { resolveCommandActiveContext } from './active-context-runtime.mjs';
 
 function observerMarkdownUnder(vaultBase, relativeRoot) {
   const output = [];
@@ -71,6 +73,24 @@ export function runChange(argv) {
   const vaultBase = resolveVault(rest);
   const VALUE_FLAGS = new Set(['--vault', '--change', '--project', '--session']);
   const slugArg = () => rest.find((a, i) => !a.startsWith('-') && !VALUE_FLAGS.has(rest[i - 1]));
+  const projectRoot = resolve(opt(rest, '--project') || process.cwd());
+  let contextResolved = false;
+  let resolvedContext = null;
+  const context = () => {
+    if (contextResolved) return resolvedContext;
+    contextResolved = true;
+    const sessionId = opt(rest, '--session')
+      || process.env.CODEX_THREAD_ID
+      || process.env.CLAUDE_SESSION_ID
+      || '';
+    try {
+      resolvedContext = resolveCommandActiveContext({ vaultBase, projectRoot, sessionId });
+      return resolvedContext;
+    } catch (error) {
+      process.stderr.write(`wendkeep change: ${error.code || 'WENDKEEP_ACTIVE_CONTEXT_FAILED'}: ${error.message}\n`);
+      process.exit(2);
+    }
+  };
 
   if (sub === 'new') {
     const slug = slugArg();
@@ -80,6 +100,7 @@ export function runChange(argv) {
     try { sessionRel = readControl(vaultBase).session_file || ''; } catch { /* sem control */ }
     const r = newChange(vaultBase, slug, {
       dateStr: today(), simple: rest.includes('--simple'), guide: rest.includes('--guide'), sessionRel,
+      context: context(),
     });
     process.stdout.write(`change ${r.created ? 'created' : 'exists'}: ${r.rel} (active)\n`);
     process.exit(0);
@@ -88,7 +109,7 @@ export function runChange(argv) {
   if (sub === 'use') {
     const slug = slugArg();
     if (!slug) { process.stderr.write('wendkeep change use: missing <slug>\n'); process.exit(2); }
-    const r = useChange(vaultBase, slug);
+    const r = useChange(vaultBase, slug, { context: context() });
     if (!r.ok) { process.stderr.write(`wendkeep change use: ${r.error}\n`); process.exit(2); }
     process.stdout.write(`current change: ${slug}\n`);
     process.exit(0);
@@ -102,6 +123,8 @@ export function runChange(argv) {
     if (!state.changes.some((item) => item.slug === slug)) { process.stderr.write(`wendkeep change bind: open change not found: ${slug}\n`); process.exit(2); }
     if (!readSessionRegistry(vaultBase).sessions?.[sessionId]) { process.stderr.write(`wendkeep change bind: session not found: ${sessionId}\n`); process.exit(2); }
     upsertSessionRegistry(vaultBase, sessionId, { change_slug: slug });
+    const selectedContext = context();
+    if (selectedContext) setActiveChange(vaultBase, slug, { context: selectedContext });
     process.stdout.write(`session ${sessionId} -> change ${slug}\n`);
     process.exit(0);
   }
@@ -117,6 +140,7 @@ export function runChange(argv) {
     try { sessionRel = readControl(vaultBase).session_file || ''; } catch { /* no control */ }
     const r = continueChange(vaultBase, archivedSlug, newSlug, {
       dateStr: today(), simple: rest.includes('--simple'), guide: rest.includes('--guide'), sessionRel,
+      context: context(),
     });
     if (!r.ok) { process.stderr.write(`wendkeep change continue: ${r.error}\n`); process.exit(2); }
     process.stdout.write(`change created: ${r.rel} (continues ${r.archived}; active)\n`);
@@ -124,7 +148,7 @@ export function runChange(argv) {
   }
 
   if (sub === 'list') {
-    const state = allChangesState(vaultBase);
+    const state = allChangesState(vaultBase, { context: context() });
     const { archived } = listChanges(vaultBase);
     process.stdout.write(`${renderOpenChanges(state, { tag: '' }) || 'open changes: (none)'}\n`);
     process.stdout.write(`archived: ${archived.join(', ') || '(none)'}\n`);
@@ -147,7 +171,7 @@ export function runChange(argv) {
   if (sub === 'status') {
     const slug = slugArg();
     if (!slug) {
-      const state = allChangesState(vaultBase);
+      const state = allChangesState(vaultBase, { context: context() });
       if (!state.changes.length && !state.pointerWarning) {
         process.stderr.write('wendkeep change status: no open changes\n');
         process.exit(2);
@@ -161,7 +185,7 @@ export function runChange(argv) {
     catch { process.stderr.write(`wendkeep change status: not found: ${slug}\n`); process.exit(2); }
     const tasks = parseTasks(tarefasMd);
     const done = tasks.filter((t) => t.done).length;
-    process.stdout.write(`change: ${slug}${slug === activeChange(vaultBase) ? ' (ativa)' : ''}\n`);
+    process.stdout.write(`change: ${slug}${slug === activeChange(vaultBase, { context: context() }) ? ' (ativa)' : ''}\n`);
     let specs = [];
     try { specs = parseSpecsList(readFileSync(join(dir, 'proposta.md'), 'utf8')); } catch { /* sem proposta */ }
     process.stdout.write(`specs: ${specs.join(', ') || '(nenhuma)'}\n`);
@@ -194,7 +218,7 @@ export function runChange(argv) {
   if (sub === 'done' || sub === 'undone') {
     const taskId = slugArg();
     if (!taskId) { process.stderr.write(`wendkeep change ${sub}: missing <taskId>\n`); process.exit(2); }
-    const slug = opt(rest, '--change') || activeChange(vaultBase);
+    const slug = opt(rest, '--change') || activeChange(vaultBase, { context: context() });
     if (!slug) { process.stderr.write(`wendkeep change ${sub}: no active change\n`); process.exit(2); }
     const dir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
     let ok = false;
@@ -205,7 +229,7 @@ export function runChange(argv) {
   }
 
   if (sub === 'diff') {
-    const slug = slugArg() || activeChange(vaultBase);
+    const slug = slugArg() || activeChange(vaultBase, { context: context() });
     if (!slug) { process.stderr.write('wendkeep change diff: no change (arg or active)\n'); process.exit(2); }
     const dir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
     let specs = [];
@@ -228,7 +252,8 @@ export function runChange(argv) {
   }
 
   if (sub === 'archive') {
-    const slug = slugArg() || activeChange(vaultBase);
+    const selectedContext = context();
+    const slug = slugArg() || activeChange(vaultBase, { context: selectedContext });
     if (!slug) { process.stderr.write('wendkeep change archive: missing <slug> and no active change\n'); process.exit(2); }
     // Real gate (Pilar C): every sensor a task declared must be green in evidencia.json.
     const gate = (dir) => {
@@ -310,7 +335,10 @@ export function runChange(argv) {
     if (trivial) process.stderr.write(compactGuide
       ? 'aviso: GUIDE compacta sem [req:]/[sensor:] — resultado permanece auditável no archive, sem ADR automático\n'
       : 'aviso: change trivial (sem [req:]/[sensor:]) — ADR marcado trivial: true\n');
-    const r = archiveChange(vaultBase, slug, { dateStr: today(), adrNum: getNextAdrNumber(vaultBase), gate, adrFlags: { forced, trivial } });
+    const r = archiveChange(vaultBase, slug, {
+      dateStr: today(), adrNum: getNextAdrNumber(vaultBase), gate,
+      adrFlags: { forced, trivial }, context: selectedContext,
+    });
     if (!r.ok) {
       process.stderr.write(`change archive BLOCKED (gate): ${r.failing.join('; ')}\n`);
       process.exit(1);
@@ -366,9 +394,10 @@ export function runChange(argv) {
   }
 
   if (sub === 'abandon') {
-    const slug = slugArg() || activeChange(vaultBase);
+    const selectedContext = context();
+    const slug = slugArg() || activeChange(vaultBase, { context: selectedContext });
     if (!slug) { process.stderr.write('wendkeep change abandon: missing <slug> and no active change\n'); process.exit(2); }
-    const r = abandonChange(vaultBase, slug, { dateStr: today() });
+    const r = abandonChange(vaultBase, slug, { dateStr: today(), context: selectedContext });
     if (!r.ok) { process.stderr.write(`wendkeep change abandon: ${r.failing.join('; ')}\n`); process.exit(2); }
     process.stdout.write(`abandoned: ${r.archivedRel}\n`);
     process.exit(0);

package/src/spec.mjs

@@ -11,6 +11,7 @@ import {
 } from '../hooks/spec-core.mjs';
 import { activeChange, parseTasks } from '../hooks/change-core.mjs';
 import { getLocale } from '../hooks/locale.mjs';
+import { resolveCommandActiveContext } from './active-context-runtime.mjs';
 
 function resolveVault(argv) {
   let vault;
@@ -38,9 +39,21 @@ export function runSpec(argv) {
     const entry = rest.find((a) => a.startsWith(`${name}=`));
     return entry ? entry.slice(name.length + 1) : undefined;
   };
+  const commandContext = () => {
+    try {
+      return resolveCommandActiveContext({
+        vaultBase,
+        projectRoot: resolve(option('--project') || process.cwd()),
+        sessionId: option('--session') || process.env.CODEX_THREAD_ID || process.env.CLAUDE_SESSION_ID || '',
+      });
+    } catch (error) {
+      process.stderr.write(`wendkeep spec: ${error.code || 'WENDKEEP_ACTIVE_CONTEXT_FAILED'}: ${error.message}\n`);
+      process.exit(2);
+    }
+  };
 
   if (sub === 'effective') {
-    const slug = option('--change') || activeChange(vaultBase);
+    const slug = option('--change') || activeChange(vaultBase, { context: commandContext() });
     if (!slug) { process.stderr.write('wendkeep spec effective: no change (--change or current)\n'); process.exit(2); }
     const changeDir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
     let tasks = [];
@@ -74,7 +87,7 @@ export function runSpec(argv) {
   }
 
   if (sub === 'rebase') {
-    const slug = option('--change') || activeChange(vaultBase);
+    const slug = option('--change') || activeChange(vaultBase, { context: commandContext() });
     if (!slug) { process.stderr.write('wendkeep spec rebase: no change (--change or current)\n'); process.exit(2); }
     const changeDir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
     try { readFileSync(join(changeDir, 'proposta.md'), 'utf8'); }

package/src/verify.mjs

@@ -20,6 +20,7 @@ import {
 } from '../hooks/spec-core.mjs';
 import { addLesson } from '../hooks/lessons-core.mjs';
 import { getLocale } from '../hooks/locale.mjs';
+import { resolveCommandActiveContext } from './active-context-runtime.mjs';
 
 function today() {
   const d = new Date();
@@ -40,7 +41,20 @@ export function runVerify(argv) {
   // --project wins; otherwise climb from cwd to the nearest project marker (agent shells
   // keep their cwd across commands, so verify from a subdirectory is a recurring miss).
   const projectRoot = resolve(opt(argv, '--project') || findProjectRoot(process.cwd()) || process.cwd());
-  const slug = opt(argv, '--change') || activeChange(vaultBase);
+  let commandContext = null;
+  if (!opt(argv, '--change')) {
+    try {
+      commandContext = resolveCommandActiveContext({
+        vaultBase,
+        projectRoot,
+        sessionId: opt(argv, '--session') || process.env.CODEX_THREAD_ID || process.env.CLAUDE_SESSION_ID || '',
+      });
+    } catch (error) {
+      process.stderr.write(`wendkeep verify: ${error.code || 'WENDKEEP_ACTIVE_CONTEXT_FAILED'}: ${error.message}\n`);
+      process.exit(2);
+    }
+  }
+  const slug = opt(argv, '--change') || activeChange(vaultBase, { context: commandContext });
   if (!slug) { process.stderr.write('wendkeep verify: no change (--change or active).\n'); process.exit(2); }
 
   const changeDir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);