wendkeep 0.80.0 → 0.80.1

package/CHANGELOG.md

@@ -4,6 +4,17 @@ 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.80.1] — 2026-08-24
+
+### Fixed
+
+- **Bootstrap causal das sessões Codex.** `session-start` e `session-ensure` agora derivam um
+  `work_session_id` estável do `session_id` canônico quando o host não envia essa identidade,
+  preservando primeiro handoff explícito e valor já registrado. Novas sessões deixam de falhar em
+  `profile route`, `change new` e active context por identidade ausente, sem relaxar as validações
+  de projeto, repositório, worktree ou branch; README e o guia de contexto foram atualizados em
+  PT-BR/EN.
+
 ## [0.80.0] — 2026-08-24
 
 ### 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. `doctor` diagnoses orphaned active contexts, removed worktrees, and expired `request-stop` leases without writing; `context repair --key <key> --revision <n> --reason <text> --session <id>` revalidates under lock, closes only the ownerless/removed context or expires only its lease, while preserving the record and all historical memory. 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**.
+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`. When the host omits `work_session_id`, `session-start` and `session-ensure` derive it from the canonical `session_id`, preserving an explicit handoff and the already registered value first. 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. `doctor` diagnoses orphaned active contexts, removed worktrees, and expired `request-stop` leases without writing; `context repair --key <key> --revision <n> --reason <text> --session <id>` revalidates under lock, closes only the ownerless/removed context or expires only its lease, while preserving the record and all historical memory. 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**.
    Once `active_contexts` is initialized, `brain-inject` and `change-context` mark only the causal context's change as current; the backlog remains global, and an empty or ambiguous store never revives `CURRENT_CHANGE.md`.
 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:

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. `doctor` diagnoses orphaned active contexts, removed worktrees, and expired `request-stop` leases without writing; `context repair --key <key> --revision <n> --reason <text> --session <id>` revalidates under lock, closes only the ownerless/removed context or expires only its lease, while preserving the record and all historical memory. 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**.
+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`. When the host omits `work_session_id`, `session-start` and `session-ensure` derive it from the canonical `session_id`, preserving an explicit handoff and the already registered value first. 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. `doctor` diagnoses orphaned active contexts, removed worktrees, and expired `request-stop` leases without writing; `context repair --key <key> --revision <n> --reason <text> --session <id>` revalidates under lock, closes only the ownerless/removed context or expires only its lease, while preserving the record and all historical memory. 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**.
    Once `active_contexts` is initialized, `brain-inject` and `change-context` mark only the causal context's change as current; the backlog remains global, and an empty or ambiguous store never revives `CURRENT_CHANGE.md`.
 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:

package/docs/en/commands/context.md

@@ -108,6 +108,11 @@ identified by `repository_id` + `worktree_id` + `work_session_id`; branch, HEAD,
 belong to that entry. Two worktrees can therefore select different changes without overwriting
 each other's operational focus.
 
+During the session lifecycle, `session-start` and `session-ensure` first preserve an explicit
+handoff `work_session_id`, then the already registered value, and, when the host supplies neither,
+derive the stable identity from the canonical `session_id`. Providers such as Codex can therefore
+initialize an active context without weakening project, repository, worktree, or branch checks.
+
 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.

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

@@ -105,6 +105,12 @@ identificada por `repository_id` + `worktree_id` + `work_session_id`; branch, HE
 pertencem a essa entrada. Assim, duas worktrees podem selecionar changes diferentes sem
 sobrescrever o foco uma da outra.
 
+No lifecycle de sessão, `session-start` e `session-ensure` preservam primeiro um
+`work_session_id` explícito do handoff, depois o valor já registrado e, quando o host não fornece
+nenhum deles, derivam a identidade estável do `session_id` canônico. Assim, providers como o Codex
+podem inicializar o active context sem enfraquecer as validações de projeto, repositório, worktree
+ou branch.
+
 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.

package/hooks/session-ensure.mjs

@@ -32,31 +32,19 @@ import {
   writeHookOutput,
   yamlQuote,
 } from './obsidian-common.mjs';
-import { resolveSessionIdentity } from './session-identity.mjs';
+import { resolveSessionIdentity, sessionWorkSessionPatch } from './session-identity.mjs';
 import { readCodexRolloutMeta } from './codex-rollout-meta.mjs';
 import { mutateSessionNote } from './session-note-io.mjs';
 import { captureProjectScope, projectScopePatch } from './project-scope.mjs';
-import { sanitizeMemoryText } from './memory-schema.mjs';
 
 function sessionIdFromInput(input) {
   return input.session_id || input.sessionId || input.codex_session_id || '';
 }
 
-function workSessionIdFromInput(input = {}) {
-  const shared = input.shared || input.handoff?.shared;
-  const value = input.work_session_id
-    || input.workSessionId
-    || shared?.work_session_id
-    || shared?.workSessionId
-    || input.handoff?.work_session_id
-    || input.handoff?.workSessionId
-    || '';
-  return sanitizeMemoryText(value).trim();
-}
-
-function workSessionPatch(input = {}) {
-  const workSessionId = workSessionIdFromInput(input);
-  return workSessionId ? { work_session_id: workSessionId } : {};
+function workSessionPatch(vaultBase, sessionId, input = {}) {
+  const existingWorkSessionId = readSessionRegistry(vaultBase)
+    .sessions?.[sessionId]?.work_session_id || '';
+  return sessionWorkSessionPatch({ input, sessionId, existingWorkSessionId });
 }
 
 function turnSequenceFromInput(input = {}) {
@@ -308,7 +296,7 @@ function activateExistingSession({ vaultBase, relPath, startedAt, sessionId, inp
     transcript_path: identity.transcriptPath,
     transcript_id: identity.transcriptId,
     provider: identity.provider,
-    ...workSessionPatch(input),
+    ...workSessionPatch(vaultBase, sessionId, input),
     ...scopePatch,
     ...causalTurnPatch(input, now),
   });
@@ -337,7 +325,7 @@ function createSession({ vaultBase, sessionId, input, now, identity, scopePatch
     transcript_path: identity.transcriptPath,
     transcript_id: identity.transcriptId,
     provider: identity.provider,
-    ...workSessionPatch(input),
+    ...workSessionPatch(vaultBase, sessionId, input),
     ...scopePatch,
     ...causalTurnPatch(input, now),
   });
@@ -381,7 +369,7 @@ function main() {
       upsertSessionRegistry(vaultBase, sessionId, {
         transcript_paths: [identity.transcriptPath],
         provider: identity.provider,
-        ...workSessionPatch(input),
+        ...workSessionPatch(vaultBase, sessionId, input),
       });
     }
     writeHookOutput({});
@@ -419,7 +407,7 @@ function main() {
           transcript_path: identity.transcriptPath,
           transcript_id: identity.transcriptId,
           provider: identity.provider,
-          ...workSessionPatch(input),
+          ...workSessionPatch(vaultBase, sessionId, input),
           ...scopePatch,
           ...causalTurnPatch(input, now),
         });
@@ -465,7 +453,7 @@ function main() {
         transcript_path: identity.transcriptPath,
         transcript_id: identity.transcriptId,
         provider: identity.provider,
-        ...workSessionPatch(input),
+        ...workSessionPatch(vaultBase, sessionId || control.session_id, input),
         ...scopePatch,
         ...causalTurnPatch(input, now),
       });

package/hooks/session-identity.mjs

@@ -6,6 +6,26 @@ import {
   resolveSessionIdentitySnapshot,
 } from '../packages/integrations/src/session-identity.mjs';
 import { readCodexRolloutMeta } from './codex-rollout-meta.mjs';
+import { sanitizeMemoryText } from './memory-schema.mjs';
+
+export function sessionWorkSessionPatch({
+  input = {},
+  sessionId = '',
+  existingWorkSessionId = '',
+} = {}) {
+  const shared = input.shared || input.handoff?.shared;
+  const explicit = input.work_session_id
+    || input.workSessionId
+    || shared?.work_session_id
+    || shared?.workSessionId
+    || input.handoff?.work_session_id
+    || input.handoff?.workSessionId
+    || '';
+  const workSessionId = sanitizeMemoryText(
+    explicit || existingWorkSessionId || sessionId,
+  ).trim();
+  return workSessionId ? { work_session_id: workSessionId } : {};
+}
 
 function unknownTranscriptIdentity() {
   return {

package/hooks/session-start.mjs

@@ -32,7 +32,7 @@ import {
   writeHookOutput,
   yamlQuote,
 } from './obsidian-common.mjs';
-import { resolveSessionIdentity } from './session-identity.mjs';
+import { resolveSessionIdentity, sessionWorkSessionPatch } from './session-identity.mjs';
 import { captureProjectScope, projectScopePatch } from './project-scope.mjs';
 
 export function buildSessionContent({ relPath, now, summary = 'session', provider: providerId, sessionId = '' }) {
@@ -183,11 +183,18 @@ function main() {
     readSessionRegistry(vaultBase).sessions?.[canonicalSessionId]?.project_scope,
     { ...initialScope, sessionId: canonicalSessionId },
   );
+  const workSessionPatchFor = (canonicalSessionId) => sessionWorkSessionPatch({
+    input,
+    sessionId: canonicalSessionId,
+    existingWorkSessionId: readSessionRegistry(vaultBase)
+      .sessions?.[canonicalSessionId]?.work_session_id || '',
+  });
   const control = readControl(vaultBase);
   const activationId = input.activation_id || input.activationId || randomUUID();
   const activationStartedAt = formatLocalIso(now);
   const registerActivation = (canonicalSessionId, patch) => upsertSessionRegistry(vaultBase, canonicalSessionId, {
     ...patch,
+    ...workSessionPatchFor(canonicalSessionId),
     ...scopePatchFor(canonicalSessionId),
     activation_id: activationId,
     activation_started_at: activationStartedAt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.80.0",
+  "version": "0.80.1",
   "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": [