feat(memory): path-aware episode/skill provenance + human-gated promote

[jkyberneees]

Summary

Fixes the episode-memory dead-end: provenance tainted an episode if the session used read_file / search_files / multi_grep — by tool name alone. Those run in essentially every coding session, so almost every episode was born Untrusted, untrusted episodes are filtered out of recall, and nothing ever set UserApproved. Net result: episodes were extracted (an LLM call per session) and stored, but for normal work never recalled — the tier was dead weight.

This makes taint argument-aware and adds the missing human-gated escape hatch.

What changed

1. Path-aware taint (shared single source of truth)

New memory.ToolCallTaints(name, argsJSON) decides per call:

• Always untrusted: browser, http_batch, transcribe, any MCP tool (server__tool).
• Path-scoped: read_file / search_files / multi_grep taint only when their path argument resolves to a sensitive location — reusing the existing, tested danger.ClassifyPath (system_write/destructive: /etc, ~/.ssh, ~/.aws, …). Workspace and other non-sensitive local reads stay trusted. Malformed/absent path → conservative taint.

This precisely re-targets the original "covers /etc/, $HOME/.ssh" concern while letting ordinary sessions remain recallable. Because ClassifyPath resolves paths itself, DeriveProvenance keeps its (messages) signature — no cwd plumbing into the async session-end call sites.

2. Skills mirror

internal/skills/selfimprove.go now delegates to the same memory.ToolCallTaints, so learned skills stop being over-flagged for review too. Trust model stays unified.

3. Human-gated promote (CLI only)

odek memory list                    # episodes excluded from recall, with sources
odek memory promote <session_id>    # approve one after reviewing its summary

Deliberately not an agent tool — a prompt-injected agent must not be able to self-approve its own poisoned memory. Mirrors the existing skill promote pattern.

4. Doc/comment drift fixed

• docs/CONFIG.md: extract_on_end ("durable facts" → it extracts an episode summary).
• memory.go: FormatEpisodeContext comment ("recency-based ranker, no LLM" → it uses the configured, LLM-by-default ranker).
• docs/SECURITY.md §5/§6 updated for the new model.

Security rationale

The control still closes the persistence-injection vector: anything that ingests genuinely external content (web/http/MCP/audio) or reads sensitive system/credential paths is still untrusted and non-recallable until a human promotes it. Only the false-positive (workspace reads) is removed.

Verification

• go build ./..., go vet, gofmt clean.
• go test ./internal/memory/... ./internal/skills/... ./cmd/odek/... — all pass. New coverage:
  • path-aware taint: workspace read trusted; /etc/passwd & ~/.ssh/id_rsa tainted; default-path search trusted; malformed args conservatively taint; http_batch/transcribe always taint; ToolCallTaints table.
  • episode promote/pending lifecycle + on-disk persistence; promote error cases.
  • skills mirror test doubles as a guard that the llm.Message → LlmMessage conversion carries Arguments.
  • CLI command end to end.
• Manual binary smoke (temp HOME, seeded index): untrusted web episode listed as pending, clean workspace episode not flagged, promote makes it recallable, error cases exit 1 cleanly.

Note

Only new episodes get the refined provenance; existing on-disk tainted episodes stay as-is — odek memory promote is exactly how a user recovers those.

🤖 Generated with Claude Code

[jkyberneees]

Verification Protocol — remediation pass (commit c550d2d)

All findings from the prior certificate are closed and verified.

Finding	Sev	Status
D-03 macOS /private/etc|var read no longer tainted (regression)	HIGH	✅ Fixed — containment check resolves symlinks; ClassifyPath also strips /private. Verified read_file("/private/etc/master.passwd") → taints.
D-01 sibling whole-file readers (batch_read, json_query, head_tail, diff, …) bypass taint	HIGH	✅ Fixed — PathReadingTools broadened to all 16 file-readers; multi-path args (path_a/b, files[].path) extracted. batch_read{/etc/shadow} → taints.
D-02 home creds outside the hardcoded list (~/secrets.env) not tainted	MED	✅ Fixed — any read outside the workspace taints now.
D-05 session_search recalls prior transcripts untainted	MED	✅ Fixed — added to AlwaysExternalTools.
Coverage PromoteEpisode/PendingReviewEpisodes at 0%	LOW	✅ Fixed — now 100%.
Docs (2.9) SECURITY.md overstated coverage	—	✅ Rewritten to the containment model.

Design change: the taint check flipped from a sensitive-path denylist (ClassifyPath) to a workspace-containment allowlist — a path-reading call taints when any path argument resolves outside the workspace / sandbox /workspace / ~/.odek (symlink-resolved). Workspace reads stay trusted (original goal preserved); everything else taints. This closes the whole class of denylist-incompleteness bypasses rather than patching them one by one.

Re-scored axes

2.1 ✅ · 2.2 ✅ · 2.3 ✅ (was 🔴) · 2.4 ✅ · 2.5 ✅ · 2.6 ✅ · 2.7 ⚠️ (monoculture) · 2.8 ✅ (was 🔴) · 2.9 ✅

η ≈ 0.68 (signals improved: o≈0.75, b≈0.92, s≈0.90, t=1, d=1, f=1, m skipped/redistributed) · ρ = 0.21 (unchanged — single-model pipeline).

Verdict: 🟡 HumanReviewRequired — but now only on the correlation gate

No axis is 🔴 anymore; every substantive finding is fixed. The verdict stays at HumanReviewRequired solely because the pipeline is a monoculture (the author and all verifier roles are the same model/family → ρ=0.21 ∈ (0.20, 0.30], which also drags η below 0.80). Per §3.8 that is a hard cap a single model cannot clear by improving the code — a human reviewer or a genuinely independent second-provider verification is the remaining gate. That's the protocol working as designed: a model may not self-certify to AutoApprove.

Verification artifacts: deterministic tests now cover each closed bypass (TestToolCallTaints, broadened path-tool cases) and the manager wrappers.