wendkeep 0.68.1 → 0.68.5

package/hooks/project-scope.mjs

@@ -0,0 +1,435 @@
+import { realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const TOOL_CWD_FIELDS = ['cwd', 'workdir', 'work_dir', 'working_directory', 'directory'];
+const SAFE_GIT_COMMANDS = new Set([
+  'status', 'diff', 'log', 'show', 'reflog', 'describe', 'ls-files', 'ls-tree', 'cat-file',
+  'rev-parse', 'symbolic-ref', 'for-each-ref', 'for-each-repo', 'shortlog', 'whatchanged',
+]);
+const MUTABLE_TOOL_NAMES = new Set([
+  'apply_patch', 'ApplyPatch', 'write_file', 'Write', 'Edit', 'MultiEdit', 'delete_file',
+  'remove_file', 'move_file', 'rename_file',
+]);
+
+function canonicalPath(value) {
+  const candidate = resolve(String(value || process.cwd()));
+  let physical = candidate;
+  try { physical = realpathSync.native(candidate); } catch { /* target may not exist yet */ }
+  const normalized = physical.replaceAll('\\', '/');
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+function displayPath(value) {
+  return String(value || '').replaceAll('\\', '/');
+}
+
+function runGit(cwd, args, spawn = spawnSync) {
+  const result = spawn('git', args, { cwd, encoding: 'utf8', windowsHide: true });
+  if (result.error || result.status !== 0) {
+    const detail = String(result.stderr || result.error?.message || 'falhou').trim();
+    const error = new Error(`git ${args.join(' ')}: ${detail}`);
+    error.code = 'WENDKEEP_SCOPE_GIT_ERROR';
+    throw error;
+  }
+  return String(result.stdout || '').trim();
+}
+
+function optionalGit(cwd, args, spawn = spawnSync) {
+  try { return runGit(cwd, args, spawn); } catch { return ''; }
+}
+
+export function normalizeRemote(value) {
+  let raw = String(value || '').trim();
+  if (!raw) return '';
+  try {
+    const url = new URL(raw);
+    url.username = '';
+    url.password = '';
+    url.hash = '';
+    url.hostname = url.hostname.toLowerCase();
+    raw = url.toString().replace(/\/$/, '');
+    return raw;
+  } catch { /* scp-like remotes and local paths */ }
+  raw = raw.replace(/^[^/\\]+@(?=[^/:]+[:/])/, '');
+  return raw.replaceAll('\\', '/').replace(/\/$/, '');
+}
+
+export function extractToolCommand(input = {}) {
+  const value = input?.tool_input ?? input?.toolInput ?? input;
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) return value.map((part) => String(part)).join(' ');
+  if (!value || typeof value !== 'object') return '';
+  if (typeof value.command === 'string') return value.command;
+  if (Array.isArray(value.command)) return value.command.map((part) => String(part)).join(' ');
+  if (Array.isArray(value.argv)) return value.argv.map((part) => String(part)).join(' ');
+  if (Array.isArray(value.args)) return value.args.map((part) => String(part)).join(' ');
+  return '';
+}
+
+export function requestedToolCwd(input = {}) {
+  const tool = input?.tool_input ?? input?.toolInput;
+  if (tool && typeof tool === 'object' && !Array.isArray(tool)) {
+    for (const field of TOOL_CWD_FIELDS) {
+      if (typeof tool[field] === 'string' && tool[field].trim()) return tool[field].trim();
+    }
+  }
+  for (const field of ['cwd', 'project_dir', 'projectDir', 'workspace']) {
+    const value = field === 'workspace' ? input?.workspace?.cwd : input?.[field];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return '';
+}
+
+function shellSegments(command) {
+  const tokens = String(command || '').match(/"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|&&|\|\||[;|\n]|&|[^\s;&|]+/g) || [];
+  const segments = [];
+  let current = [];
+  const flush = () => { if (current.length) segments.push(current); current = []; };
+  for (const token of tokens) {
+    if (['&&', '||', ';', '|', '\n'].includes(token) || (token === '&' && current.length)) {
+      flush();
+      continue;
+    }
+    current.push(token);
+  }
+  flush();
+  return segments;
+}
+
+function unquote(token) {
+  const value = String(token || '');
+  if (value.length >= 2 && ((value[0] === '"' && value.at(-1) === '"')
+    || (value[0] === "'" && value.at(-1) === "'"))) return value.slice(1, -1);
+  return value;
+}
+
+function executableName(token) {
+  return unquote(token).replaceAll('\\', '/').split('/').at(-1).toLowerCase();
+}
+
+function invocationOf(segment) {
+  let index = 0;
+  while (segment[index] === '&' || /^[A-Za-z_][A-Za-z0-9_]*=/.test(segment[index] || '')) index += 1;
+  const executable = executableName(segment[index]);
+  if (executable === 'git' || executable === 'git.exe' || executable === 'git.cmd') {
+    return { kind: 'git', args: segment.slice(index + 1).map(unquote) };
+  }
+  if (['rm', 'rm.exe', 'del', 'erase', 'remove-item', 'move-item', 'set-content', 'out-file', 'copy-item', 'new-item'].includes(executable)) {
+    return { kind: 'filesystem', args: segment.slice(index + 1).map(unquote) };
+  }
+  if (isPublicationInvocation(executable, segment.slice(index + 1).map(unquote))) {
+    return { kind: 'publication', args: segment.slice(index + 1).map(unquote) };
+  }
+  return null;
+}
+
+function firstNonOption(args) {
+  return args.find((arg) => !String(arg).startsWith('-'))?.toLowerCase() || '';
+}
+
+function isWendKeepPublication(args) {
+  const command = firstNonOption(args);
+  return command === 'publish' || command === 'release';
+}
+
+function isPublicationInvocation(executable, args) {
+  if (['npm', 'npm.cmd', 'pnpm', 'pnpm.cmd', 'yarn', 'yarn.cmd', 'bun', 'bun.exe'].includes(executable)) {
+    const command = firstNonOption(args);
+    if (command === 'publish') return true;
+    const commandIndex = args.findIndex((arg) => String(arg).toLowerCase() === command);
+    return command === 'run' && String(args[commandIndex + 1] || '').toLowerCase() === 'release';
+  }
+  if (executable === 'gh' || executable === 'gh.exe') {
+    const command = firstNonOption(args);
+    const commandIndex = args.findIndex((arg) => String(arg).toLowerCase() === command);
+    const operation = String(args[commandIndex + 1] || '').toLowerCase();
+    return command === 'release' && ['create', 'edit', 'upload', 'delete'].includes(operation);
+  }
+  if (executable === 'wendkeep' || executable === 'wendkeep.cmd' || executable === 'wk' || executable === 'wk.cmd') {
+    return isWendKeepPublication(args);
+  }
+  if (executable === 'npx' || executable === 'npx.cmd') {
+    const packageIndex = args.findIndex((arg) => ['wendkeep', 'wk'].includes(String(arg).toLowerCase()));
+    return packageIndex >= 0 && isWendKeepPublication(args.slice(packageIndex + 1));
+  }
+  if (executable === 'corepack' || executable === 'corepack.cmd') {
+    const packageIndex = args.findIndex((arg) => ['npm', 'pnpm', 'yarn'].includes(String(arg).toLowerCase()));
+    return packageIndex >= 0 && isPublicationInvocation(
+      String(args[packageIndex]).toLowerCase(),
+      args.slice(packageIndex + 1),
+    );
+  }
+  return false;
+}
+
+function commandInvocations(command) {
+  return shellSegments(command).map(invocationOf).filter(Boolean);
+}
+
+function firstGitSubcommand(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = String(args[index] || '');
+    if (arg === '--') return '';
+    if (arg === '-C' || arg === '--git-dir' || arg === '--work-tree' || arg === '--exec-path') {
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('-')) continue;
+    return arg.toLowerCase();
+  }
+  return '';
+}
+
+function gitAction(args) {
+  const subcommand = firstGitSubcommand(args);
+  if (!subcommand || SAFE_GIT_COMMANDS.has(subcommand)) return null;
+  if (subcommand === 'config') {
+    return args.some((arg) => ['--get', '--get-all', '--get-regexp', '--list', '-l', '--show-origin'].includes(arg))
+      ? null : 'git:destructive';
+  }
+  if (subcommand === 'remote') {
+    return args.some((arg) => ['-v', '--verbose', 'get-url', 'show'].includes(arg)) ? null : 'git:destructive';
+  }
+  if (subcommand === 'branch') {
+    return args.some((arg) => ['--show-current', '--list', '-a', '-r', '-vv'].includes(arg))
+      ? null : 'git:destructive';
+  }
+  if (subcommand === 'tag') return args.includes('-l') || args.includes('--list') ? null : 'git:destructive';
+  if (subcommand === 'worktree') return args[1] === 'list' ? null : 'git:destructive';
+  if (['add', 'commit', 'push', 'pull', 'fetch', 'merge', 'rebase', 'cherry-pick', 'stash'].includes(subcommand)) {
+    return `git:${subcommand}`;
+  }
+  if (['checkout', 'switch', 'reset', 'restore', 'revert', 'clean', 'rm', 'mv', 'update-index', 'init', 'clone'].includes(subcommand)) {
+    return 'git:destructive';
+  }
+  return 'git:destructive';
+}
+
+export function scopeActionForCommand(command) {
+  return scopeActionsForCommand(command)[0] || null;
+}
+
+export function scopeActionsForCommand(command) {
+  const actions = [];
+  for (const invocation of commandInvocations(command)) {
+    if (invocation.kind === 'git') actions.push(gitAction(invocation.args));
+    if (invocation.kind === 'filesystem') actions.push('filesystem:mutation');
+    if (invocation.kind === 'publication') actions.push('publish');
+  }
+  return [...new Set(actions.filter(Boolean))];
+}
+
+export function commandChangesDirectory(command) {
+  return shellSegments(command).some((segment) => {
+    const executable = executableName(segment[0]);
+    return ['cd', 'chdir', 'pushd', 'set-location', 'sl', 'set-location.exe'].includes(executable);
+  });
+}
+
+export function commandHasUnprovenTarget(command) {
+  if (commandChangesDirectory(command)) return true;
+  return commandInvocations(command).some((invocation) => invocation.kind === 'git'
+    && invocation.args.some((arg) => ['-C', '--git-dir', '--work-tree'].includes(arg)));
+}
+
+export function captureProjectScope({
+  input = {},
+  projectRoot = '',
+  projectId = '',
+  provider = '',
+  sessionId = '',
+  targetCwd = '',
+  spawn = spawnSync,
+} = {}) {
+  const envelopeCwd = input?.cwd || input?.project_dir || input?.projectDir || input?.workspace?.cwd || process.cwd();
+  const requested = targetCwd || requestedToolCwd(input) || envelopeCwd;
+  const target = isAbsolute(requested) ? requested : resolve(envelopeCwd, requested);
+  const repoRootRaw = optionalGit(target, ['rev-parse', '--show-toplevel'], spawn);
+  if (!repoRootRaw) {
+    return {
+      schemaVersion: 1,
+      complete: false,
+      errorCode: 'WENDKEEP_SCOPE_REPO_UNRESOLVED',
+      projectId: String(projectId || ''),
+      projectRoot: canonicalPath(projectRoot || target),
+      repoRoot: '',
+      remote: '',
+      branch: '',
+      worktree: '',
+      head: '',
+      provider: String(provider || ''),
+      sessionId: String(sessionId || ''),
+    };
+  }
+  const repoRoot = canonicalPath(repoRootRaw);
+  const head = optionalGit(repoRoot, ['rev-parse', '--verify', 'HEAD'], spawn);
+  const symbolicBranch = optionalGit(repoRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD'], spawn);
+  const branch = symbolicBranch || (head ? `detached:${head}` : '');
+  const gitDirRaw = optionalGit(repoRoot, ['rev-parse', '--git-dir'], spawn);
+  const worktree = gitDirRaw ? canonicalPath(isAbsolute(gitDirRaw) ? gitDirRaw : resolve(repoRoot, gitDirRaw)) : '';
+  const remote = normalizeRemote(optionalGit(repoRoot, ['config', '--get', 'remote.origin.url'], spawn));
+  const scope = {
+    schemaVersion: 1,
+    complete: Boolean(projectId && projectRoot && repoRoot && remote && branch && worktree && provider && sessionId),
+    projectId: String(projectId || ''),
+    projectRoot: canonicalPath(projectRoot || target),
+    repoRoot,
+    remote,
+    branch,
+    worktree,
+    head,
+    provider: String(provider || ''),
+    sessionId: String(sessionId || ''),
+  };
+  return scope;
+}
+
+const SCOPE_FIELDS = ['projectId', 'projectRoot', 'repoRoot', 'remote', 'branch', 'worktree', 'provider', 'sessionId'];
+
+export function compareProjectScopes(expected, actual) {
+  if (!expected || typeof expected !== 'object') return { ok: false, mismatches: ['scope.missing'] };
+  if (!actual || typeof actual !== 'object') return { ok: false, mismatches: ['scope.actual_missing'] };
+  const mismatches = [];
+  for (const field of SCOPE_FIELDS) {
+    const left = field.endsWith('Root') || field === 'worktree'
+      ? canonicalPath(expected[field]) : String(expected[field] || '');
+    const right = field.endsWith('Root') || field === 'worktree'
+      ? canonicalPath(actual[field]) : String(actual[field] || '');
+    if (!left || !right || left !== right) mismatches.push(`scope.${field}`);
+  }
+  if (expected.complete !== true || actual.complete !== true) mismatches.push('scope.incomplete');
+  return { ok: mismatches.length === 0, mismatches: [...new Set(mismatches)] };
+}
+
+function decision(host, reason) {
+  return {
+    permissionDecision: host === 'claude' ? 'ask' : 'deny',
+    permissionDecisionReason: reason,
+  };
+}
+
+function comparableScopeValue(scope, field) {
+  const value = scope?.[field];
+  if (!value) return '';
+  return field === 'repoRoot' || field === 'projectRoot' || field === 'worktree'
+    ? canonicalPath(value)
+    : String(value);
+}
+
+// The registry is the lease ledger, not just a display index. An active entry without a
+// project snapshot cannot prove that it is unrelated to the current mutation, so it is a
+// conservative blocker. Distinct worktrees are the one mechanically provable exception.
+export function concurrentScopeConflicts(expectedScope, activeSessions = [], currentSessionId = '') {
+  if (!expectedScope || typeof expectedScope !== 'object') return [];
+  const rows = Array.isArray(activeSessions)
+    ? activeSessions.map((entry, index) => Array.isArray(entry) && entry.length === 2
+      ? [entry[0], entry[1]]
+      : [entry?.sessionId || entry?.session_id || String(index), entry])
+    : Object.entries(activeSessions || {});
+  const current = currentSessionId || expectedScope.sessionId || '';
+  const conflicts = [];
+  for (const [sessionId, entry] of rows) {
+    if (!entry || String(sessionId) === String(current) || String(entry.sessionId || '') === String(current)) continue;
+    if (entry.status && entry.status !== 'active') continue;
+    const other = entry.project_scope || entry.projectScope || (entry.complete !== undefined ? entry : null);
+    if (!other || other.complete !== true) {
+      conflicts.push({ sessionId: String(sessionId), reason: 'scope-unavailable' });
+      continue;
+    }
+    const sameRepositoryBranch = ['repoRoot', 'remote', 'branch'].every((field) => {
+      const left = comparableScopeValue(expectedScope, field);
+      const right = comparableScopeValue(other, field);
+      return Boolean(left && right && left === right);
+    });
+    if (!sameRepositoryBranch) continue;
+    const leftWorktree = comparableScopeValue(expectedScope, 'worktree');
+    const rightWorktree = comparableScopeValue(other, 'worktree');
+    if (!leftWorktree || !rightWorktree || leftWorktree === rightWorktree) {
+      conflicts.push({ sessionId: String(sessionId), reason: 'same-repository-branch' });
+    }
+  }
+  return conflicts;
+}
+
+function toolIsMutable(input) {
+  const name = input?.tool_name || input?.toolName || '';
+  if (/^mcp__/i.test(name)) return true;
+  return MUTABLE_TOOL_NAMES.has(name) || /^mcp__.*(?:write|edit|delete|move|rename|apply)/i.test(name);
+}
+
+export function scopeDecision({
+  command = '',
+  input = {},
+  expectedScope = null,
+  actualScope = null,
+  host = 'codex',
+  commandTargetKnown = true,
+  activeSessions = [],
+  currentSessionId = '',
+} = {}) {
+  const actions = scopeActionsForCommand(command);
+  const action = actions[0] || (toolIsMutable(input) ? 'tool:mutation' : null);
+  if (!action) return null;
+  if (commandChangesDirectory(command) && !commandTargetKnown) {
+    return decision(host, 'WENDKEEP_SCOPE_DIRECTORY_UNKNOWN: a mutação tentou alterar o diretório sem prova da raiz final.');
+  }
+  if (!expectedScope || !actualScope) {
+    return decision(host, `WENDKEEP_SCOPE_MISSING: escopo ausente para ${actions.join(', ') || action}; selecione explicitamente o projeto antes da mutação.`);
+  }
+  if (expectedScope.conflict === true || expectedScope.project_scope_conflict === true) {
+    return decision(host, `WENDKEEP_SCOPE_CONFLICT: a sessão observou mais de um escopo de projeto; selecione explicitamente o projeto antes da mutação.`);
+  }
+  const comparison = compareProjectScopes(expectedScope, actualScope);
+  if (!comparison.ok) {
+    return decision(host, `WENDKEEP_SCOPE_MISMATCH: alvo fora do escopo reservado (${comparison.mismatches.join(', ')}).`);
+  }
+  const concurrent = concurrentScopeConflicts(expectedScope, activeSessions, currentSessionId);
+  if (concurrent.length) {
+    return decision(host, `WENDKEEP_SCOPE_CONFLICT: há ${concurrent.length} sessão(ões) ativa(s) com a mesma raiz Git/branch ou escopo não comprovado; use um worktree distinto ou selecione explicitamente o projeto para criar uma nova lease.`);
+  }
+  const authorized = Array.isArray(expectedScope.authorizedActions)
+    ? expectedScope.authorizedActions
+    : null;
+  const unauthorized = authorized
+    ? (actions.length ? actions : [action]).filter((candidate) => (
+      !authorized.includes(candidate) && !authorized.includes('git:write')
+    ))
+    : [];
+  if (unauthorized.length) {
+    return decision(host, `WENDKEEP_SCOPE_AUTH_REQUIRED: as capacidades ${unauthorized.join(', ')} não estão autorizadas nesta lease.`);
+  }
+  return null;
+}
+
+export function scopeForRegistry(scope, { authorizedActions } = {}) {
+  if (!scope || typeof scope !== 'object') return null;
+  return {
+    schemaVersion: 1,
+    projectId: scope.projectId || '',
+    projectRoot: displayPath(scope.projectRoot),
+    repoRoot: displayPath(scope.repoRoot),
+    remote: scope.remote || '',
+    branch: scope.branch || '',
+    worktree: displayPath(scope.worktree),
+    head: scope.head || '',
+    provider: scope.provider || '',
+    sessionId: scope.sessionId || '',
+    complete: scope.complete === true,
+    ...(Array.isArray(authorizedActions) ? { authorizedActions: [...new Set(authorizedActions)] } : {}),
+  };
+}
+
+export function projectScopePatch(existingScope, currentScope) {
+  if (!currentScope || typeof currentScope !== 'object') return {};
+  if (!existingScope || typeof existingScope !== 'object') {
+    return { project_scope: scopeForRegistry(currentScope) };
+  }
+  const comparison = compareProjectScopes(existingScope, currentScope);
+  if (comparison.ok) return {};
+  return {
+    project_scope_conflict: true,
+    project_scope_conflict_fields: comparison.mismatches,
+    project_scope_observed: scopeForRegistry(currentScope),
+  };
+}

package/hooks/session-backfill.mjs

@@ -137,7 +137,7 @@ export function backfillSessions({ vaultBase, write = false, limit = 0, session
           tx,
           vaultBase,
         );
-        if (inserted) {
+        if (inserted.result === 'inserted') {
           report.inserted += 1;
           sessionReport.inserted += 1;
         }

package/hooks/session-ensure.mjs

@@ -15,6 +15,7 @@ import {
   readControl,
   readHookInput,
   readSessionRegistry,
+  resolveVault,
   sessionFileName,
   sessionFolderRel,
   sessionSummaryFromInput,
@@ -34,6 +35,7 @@ import {
 import { resolveSessionIdentity } 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';
 
 function sessionIdFromInput(input) {
   return input.session_id || input.sessionId || input.codex_session_id || '';
@@ -265,7 +267,7 @@ function findSessionForInput(vaultBase, input, control) {
   return { sessionId, relPath: '', startedAt: '', fromRegistry: false };
 }
 
-function activateExistingSession({ vaultBase, relPath, startedAt, sessionId, input, now, identity }) {
+function activateExistingSession({ vaultBase, relPath, startedAt, sessionId, input, now, identity, scopePatch = {} }) {
   const sessionPath = join(vaultBase, relPath);
   if (!existsSync(sessionPath)) return false;
 
@@ -288,12 +290,13 @@ function activateExistingSession({ vaultBase, relPath, startedAt, sessionId, inp
     transcript_path: identity.transcriptPath,
     transcript_id: identity.transcriptId,
     provider: identity.provider,
+    ...scopePatch,
     ...causalTurnPatch(input, now),
   });
   return true;
 }
 
-function createSession({ vaultBase, sessionId, input, now, identity }) {
+function createSession({ vaultBase, sessionId, input, now, identity, scopePatch = {} }) {
   const summary = sessionSummaryFromInput(input);
   const { absPath, relPath } = allocateSessionPath(vaultBase, now, summary);
   const startedAt = formatLocalIso(now);
@@ -315,6 +318,7 @@ function createSession({ vaultBase, sessionId, input, now, identity }) {
     transcript_path: identity.transcriptPath,
     transcript_id: identity.transcriptId,
     provider: identity.provider,
+    ...scopePatch,
     ...causalTurnPatch(input, now),
   });
   return { relPath, startedAt };
@@ -363,6 +367,19 @@ function main() {
     return;
   }
 
+  const projectResolution = resolveVault(input);
+  const currentScope = captureProjectScope({
+    input,
+    projectRoot: projectResolution.projectRoot,
+    projectId: projectResolution.projectId,
+    provider: identity.provider,
+    sessionId,
+  });
+  const scopePatch = projectScopePatch(
+    readSessionRegistry(vaultBase).sessions?.[sessionId]?.project_scope,
+    currentScope,
+  );
+
   // Fast path: skip all writes if control file touched < 5 min ago and session matches
   try {
     const ctrlPath = controlPath(vaultBase);
@@ -381,6 +398,7 @@ function main() {
           transcript_path: identity.transcriptPath,
           transcript_id: identity.transcriptId,
           provider: identity.provider,
+          ...scopePatch,
           ...causalTurnPatch(input, now),
         });
         writeHookOutput({});
@@ -425,6 +443,7 @@ function main() {
         transcript_path: identity.transcriptPath,
         transcript_id: identity.transcriptId,
         provider: identity.provider,
+        ...scopePatch,
         ...causalTurnPatch(input, now),
       });
       writeHookOutput({});
@@ -436,7 +455,7 @@ function main() {
   const resolvedTarget = registered?.session_file
     ? { sessionId, relPath: registered.session_file, startedAt: registered.started_at || '' }
     : { sessionId, relPath: '', startedAt: '' };
-  if (resolvedTarget.relPath && activateExistingSession({ vaultBase, relPath: resolvedTarget.relPath, startedAt: resolvedTarget.startedAt, sessionId, input, now, identity })) {
+  if (resolvedTarget.relPath && activateExistingSession({ vaultBase, relPath: resolvedTarget.relPath, startedAt: resolvedTarget.startedAt, sessionId, input, now, identity, scopePatch })) {
     outputActiveContext({
       relPath: resolvedTarget.relPath,
       startedAt: resolvedTarget.startedAt || formatLocalIso(now),
@@ -446,7 +465,7 @@ function main() {
     return;
   }
 
-  const created = createSession({ vaultBase, sessionId, input, now, identity });
+  const created = createSession({ vaultBase, sessionId, input, now, identity, scopePatch });
   outputActiveContext({
     relPath: created.relPath,
     startedAt: created.startedAt,

package/hooks/session-iteration-outcome.mjs

@@ -0,0 +1,143 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { redactSecrets } from '../packages/integrations/src/prompt-content.mjs';
+import {
+  assertVaultPathSafe,
+  VAULT_LOCK_BUSY,
+  withVaultPathLock,
+  writeVaultFileAtomic,
+} from '../packages/vault/src/vault-path-safety.mjs';
+
+export const ITERATION_OUTCOME_LEDGER = '.brain/SESSION_ITERATION_OUTCOMES.jsonl';
+export const OUTCOME_RESULTS = Object.freeze([
+  'inserted', 'duplicate', 'ambiguous', 'aborted', 'skipped', 'busy', 'failed',
+  'published', 'degraded', 'stale', 'missing', 'conflict',
+]);
+
+const RESULT_SET = new Set(OUTCOME_RESULTS);
+const STAGES = new Set(['iteration', 'observability']);
+const LOCK_STATUSES = new Set(['acquired', 'busy', 'not_required', 'unknown']);
+
+function safeId(value, fallback = 'unknown') {
+  const clean = String(value ?? '')
+    .trim()
+    .replace(/[^A-Za-z0-9._:-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 160);
+  return clean || fallback;
+}
+function safeReason(value) {
+  return redactSecrets(String(value ?? ''))
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 240);
+}
+
+function safeTimestamp(value) {
+  const candidate = String(value ?? '').trim();
+  if (candidate && !Number.isNaN(Date.parse(candidate))) return new Date(candidate).toISOString();
+  return new Date().toISOString();
+}
+
+function safeInteger(value, fallback = 0) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+export function iterationOutcomePath(vaultBase) {
+  return join(vaultBase, ITERATION_OUTCOME_LEDGER);
+}
+
+export function outcomeKey(input = {}) {
+  return [
+    safeId(input.session_id),
+    safeId(input.turn_id),
+    STAGES.has(input.stage) ? input.stage : 'iteration',
+  ].join(':');
+}
+
+export function normalizeIterationOutcome(input = {}) {
+  const sessionId = safeId(input.session_id);
+  const turnId = safeId(input.turn_id);
+  const stage = STAGES.has(input.stage) ? input.stage : 'iteration';
+  const result = RESULT_SET.has(input.result) ? input.result : 'failed';
+  const lockStatus = LOCK_STATUSES.has(input.lock_status) ? input.lock_status : 'unknown';
+  const normalized = {
+    schema_version: 1,
+    outcome_id: `${sessionId}:${turnId}:${stage}`,
+    session_id: sessionId,
+    transcript_id: safeId(input.transcript_id, ''),
+    turn_id: turnId,
+    turn_sequence: safeInteger(input.turn_sequence),
+    hook: safeId(input.hook, 'Stop'),
+    stage,
+    result,
+    lock_status: lockStatus,
+    duration_ms: safeInteger(input.duration_ms),
+    occurred_at: safeTimestamp(input.occurred_at),
+    reason: safeReason(input.reason),
+  };
+  if (!normalized.transcript_id) delete normalized.transcript_id;
+  return normalized;
+}
+
+function readRawLedger(vaultBase) {
+  const path = iterationOutcomePath(vaultBase);
+  const checked = assertVaultPathSafe(vaultBase, path, {
+    expectedType: 'file', label: 'SESSION_ITERATION_OUTCOMES.jsonl',
+  });
+  return checked.exists ? readFileSync(checked.target, 'utf8') : '';
+}
+
+function parseLedger(raw) {
+  return String(raw || '').split('\n').filter(Boolean).flatMap((line) => {
+    try {
+      const value = JSON.parse(line);
+      return value && typeof value === 'object' ? [value] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+
+export function readIterationOutcomes(vaultBase) {
+  return parseLedger(readRawLedger(vaultBase));
+}
+
+function appendOnce(vaultBase, outcome, timeoutMs) {
+  const path = iterationOutcomePath(vaultBase);
+  const result = withVaultPathLock(vaultBase, path, () => {
+    const raw = readRawLedger(vaultBase);
+    const existing = parseLedger(raw);
+    const duplicate = existing.find((entry) => entry.outcome_id === outcome.outcome_id);
+    if (duplicate) {
+      return { written: false, result: 'duplicate', reason: 'already-recorded', outcome: duplicate };
+    }
+    const separator = raw && !raw.endsWith('\n') ? '\n' : '';
+    writeVaultFileAtomic(vaultBase, path, `${raw}${separator}${JSON.stringify(outcome)}\n`, 'utf8', {
+      label: 'SESSION_ITERATION_OUTCOMES.jsonl',
+    });
+    return { written: true, result: outcome.result, reason: 'ok', outcome };
+  }, { timeoutMs });
+  if (result === VAULT_LOCK_BUSY) return null;
+  return result;
+}
+
+export function appendIterationOutcome(vaultBase, input, {
+  timeoutMs = 50,
+  retries = 2,
+} = {}) {
+  const outcome = normalizeIterationOutcome(input);
+  const maxAttempts = Math.max(1, Number(retries) + 1);
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    const result = appendOnce(vaultBase, outcome, timeoutMs);
+    if (result) return result;
+  }
+  return {
+    written: false,
+    result: 'busy',
+    reason: 'ledger-lock-busy',
+    outcome: { ...outcome, result: 'busy', lock_status: 'busy' },
+  };
+}