fluffy-context 0.6.0 → 0.7.2

package/README.md

@@ -1,10 +1,22 @@
-# Context Runtime
+# fluffy-context
 
-`fluffy-context` 正在从面向 AI 编程会话的本地 Context Runtime CLI，演进为 **Agent 无关的本地 Knowledge Runtime**。它负责自动捕获开发过程中产生的事件、候选共识、问题、不可达路径和分支工作状态，并向任意 Agent 注入有界、可验证的业务认知。
+`fluffy-context` 是一个本地优先、Agent 无关的 Context 与 Knowledge Runtime。它帮助 AI 编程 Agent 在新会话中恢复任务状态、检索已验证共识、避开已验证死路，并将结果编译成有界、可追溯的上下文。
 
-Git 仍然负责代码和真实文件变更，Issue 系统仍然负责任务，项目文档仍然负责设计；`fluffy-context` 补齐的是持续演进的项目认知层。最终架构是 `project → knowledge runtime → LLM`：CLI、MCP、Claude Hook 和未来 IDE/Agent 集成只是事件入口与信息注入适配器，而不是认知本体。
+```text
+项目代码与 Git → Context Runtime → Context Compiler → Agent / MCP / Hook
+```
+
+它不替代 Git、Issue 系统、项目文档、`CLAUDE.md`、`AGENTS.md` 或宿主 Skills：Git 仍是代码和文件变更的权威，文档仍负责设计，`fluffy-context` 只维护任务认知及其来源。
+
+## 你可以用它做什么
+
+- 保存和恢复进行中的任务、进度、待办、决策与风险。
+- 让 Agent 只读取已验证的 Knowledge 和 Deadend，减少重复试错。
+- 使用 `ctx compile` 生成带 provenance、纳入/排除原因和字符预算的 provider-neutral Manifest。
+- 通过 MCP 或 Claude Code Hook 在会话开始时注入有界上下文。
+- 可选记录经过 `.contextignored` 过滤的文件变化 metadata；默认关闭，不记录文件内容或 diff。
 
-0.6.0 在 branch-aware 注入闭环上补齐了可治理的确定性检索：迁移并启用 Runtime 后，Orient 从 v2 journal 的可重建索引检索已验证、适用的 Knowledge 与 Deadend，并返回有界的选择、排除与截断说明。v1 的 checkpoint、Note、Knowledge 与 Deadend 写入仍会最佳努力镜像为 v2 事件；Runtime 也会协调检测到的外部 v1 变更。自动产物默认仍仅进入 Candidate，Verified Knowledge 仍需治理确认。
+0.6.0 在 branch-aware 注入闭环上补齐了可治理的确定性检索：迁移并启用 Runtime 后，Orient 从 v2 journal 的可重建索引检索已验证、适用的 Knowledge 与 Deadend，并返回有界的选择、排除与截断说明。v1 的 checkpoint、Note、Knowledge 与 Deadend 写入仍会最佳努力镜像为 v2 事件；Runtime 也会协调检测到的外部 v1 变更。自动产物默认仍仅进入 Candidate，Verified Knowledge 仍需治理确认。0.6.6 已在此基础上完成无感 Runtime 生命周期的首个闭环：已迁移项目默认自动启动，Claude Hook、MCP 与 CLI Orient 可幂等唤醒 Runtime，显式 disable 仍保持永久禁用，启动失败继续 fail-open。
 
 ## 版本演进
 
@@ -16,8 +28,54 @@ Git 仍然负责代码和真实文件变更，Issue 系统仍然负责任务，
 | 0.4.0 | v2 事件 journal、v1 显式迁移、可重建投影、本地 Runtime、Git 观察 | v2 与 v1 并存；NDJSON hash chain 是 v2 权威；Runtime 仅监听 loopback 并记录分支、ref 与 HEAD 元数据。 |
 | 0.5.0 | branch-aware Orient、v1 写入镜像、Runtime 协调、宿主事件捕获 | Context 按当前 worktree/ref 选择，避免跨分支任务状态泄漏；稳定宿主 ID 才会写入限长、脱敏后的 session/prompt intent。 |
 | 0.6.0 | journal 派生的确定性检索、治理终态、可解释 Orient、显式使用反馈 | 启用 v2 后直接从可重建索引检索已验证且适用的共识；使用反馈只影响稳定排序，绝不自动验证或提升 Candidate。 |
+| 0.6.5 | Runtime 活跃度修复与 Hook 保活 | Git 真实状态变化、宿主 Hook 活动和认证 IPC 会刷新 Runtime；heartbeat 与无变化轮询不会伪装成活跃，Runtime 在不可用时保持 fail-open。 |
+| 0.6.6 | 无感 Runtime 生命周期 | 通过 `ensureRuntimeForSession()` 在已迁移项目的首次会话、Claude Hook、MCP 握手或 CLI Orient 时幂等拉起 Runtime；显式 disable 保持禁用，启动失败继续 fail-open。 |
+| 0.7.0 | Context Compiler 与文件活动基础能力 | 提供 `compileContext()`、`ctx compile`、provider-neutral `ContextManifest`、确定性候选排序、来源 provenance、纳入/排除说明、字符预算、v1/v2 来源和默认关闭的文件活动观察器。 |
+| 0.7.1 | Correctness hardening 与显式文件监听开关 | 强化 policy 校验、journal schema/hash/幂等性验证、Runtime 清理、候选 ID 稳定性，并提供 `ctx filesystem enable|disable|status`；文件观察严格复用 `.contextignored` 过滤规则。 |
+| 0.7.2 | 文件活动进入 Context Compiler | 将当前 branch/worktree/ref 的 `workspace.paths.changed` 活动作为有界 `activity` section 编译；支持 `--activity-limit`，再次执行 `.contextignored` 和内置敏感路径过滤，不记录内容或 diff。 |
+
+所有版本均保持本地优先、显式治理与 fail-open 集成原则。v1 数据不会在迁移过程中被重写；当 v2 未启用、不可用、损坏或尚未同步时，支持回退的读取接口会回退到兼容的 v1 行为。0.7.x 的 `ctx compile`、journal verify 和 Runtime 文件观察均保留明确的来源、验证或过滤边界。
+
+## 产品愿景与 1.0 前路线图
+
+`fluffy-context` 的目标不是成为另一套规则、Memory 或 Agent 能力系统，而是成为本地优先、Agent 无关的 **Context Orchestrator（上下文编排层）**：在理解当前任务、项目、worktree/ref、工作状态与 Token Budget 后，选择并编译最适合当前 Agent 的有界上下文。
+
+```text
+project → knowledge runtime → context compiler → LLM
+```
+
+Git 继续是代码与文件变更的权威，Issue 系统继续负责工作项，项目文档继续承载设计；`AGENTS.md`、`CLAUDE.md`、`.cursor/rules`、宿主 Memory、Skills 与 MCP 工具也继续由各自宿主和原生格式维护。`fluffy-context` 不复制、改写或同步这些外部主体；它只维护任务感知的选择所需元数据、引用与按输出需要截取的有界片段，并给出来源、优先级、纳入/排除原因与 Token 分配。
+
+CLI 是 Runtime 面向用户的 console pane / frontend：它用于初始化、检视、治理、诊断与调试编译结果，而非产品认知本体。Claude、Cursor、MCP 和未来 IDE/Agent 集成同样只是可选适配器，不应成为核心 Runtime 的依赖。
+
+| 计划版本 | 核心目标 | 主要能力 | 明确边界 |
+| --- | --- | --- | --- |
+| 0.7.0 | Context Compiler 基础 | 提供版本化 `ContextSourceDescriptor`、`ContextIntent`、`ContextManifest`，将当前 Context、checkpoint、Note、v2 journal 派生来源和已验证 Knowledge/Deadend 统一编译为可追溯输入；按字符预算确定性选择、排序、截断并生成纳入/排除理由。 | 不自动把原始事件提炼为 Verified Knowledge；不重写、合并或同步外部规则；不做模型调用、向量/Embedding、远程注册表或 provider-specific Renderer。 |
+| 0.8.0 | Decision Graph | 将 Decision 升级为可治理、可追溯的一等 journal 对象，记录结果、理由、备选方案、证据、适用性与生命周期；通过 `depends-on`、`supersedes`、`contradicts`、`supported-by`、`rejected-alternative`、`implemented-by` 等边构成确定性投影图；Compiler 只注入当前任务所需的有界决策子图。 | 不自动从代码或模型输出推断决策；不自动解决冲突；不自动提升 Candidate。 |
+| 0.9.0 | Knowledge Evolution | 以受治理事件支持 Knowledge 的合并、拆分、替代、适用范围收窄/扩展、退役、归档，以及作为新记录的复活；根据 Git/path 事件、source anchor、Decision Graph 依赖、重复/冲突和适用性漂移生成确定性的 `review-needed` 信号；Compiler 优先选择新鲜、适用且已验证的认知。 | 自动机制只能提出待审查候选，不能自动验证、降级、归档或作出真实性结论；不引入远程同步、团队权限、强制模型提供方或语义向量依赖。 |
+
+### 0.6.6 Runtime 生命周期
+
+0.6.6 的目标是消除用户反复执行 `ctx runtime start` 的负担。Runtime 已成为本地后台基础设施，而不是用户或 Agent 必须理解和操作的功能。核心 Runtime 保持 Agent 无关；Claude Code、MCP、CLI、IDE Extension 和其他宿主都只能通过可选 adapter 发出统一的活动信号。
+
+已迁移项目默认启用自动启动。首次会话、Claude Hook、MCP 握手或 CLI Orient 到达时，会通过幂等的 `ensureRuntimeForSession()` 检查 v2 policy 与有效 lease，复用启动锁避免重复进程，并在严格短超时内尽力拉起 Runtime。启动失败、宿主没有对应 hook 或 Runtime 暂时不可用时，宿主工作流仍继续，保持 fail-open；后续用户或 Agent 活动可再次唤醒，而不要求手动重复启动。显式执行 `ctx runtime disable` 会持久化禁用状态，直到再次执行 `ctx runtime enable`。
+
+当前 Runtime 使用 `active` 与 inactivity stop 的轻量模型：认证 IPC、Hook、MCP、CLI 和真实 Git 状态变化会刷新活跃度；heartbeat 与无变化轮询只维护健康状态，不会伪装成用户活动。更完整的 `limited`、`idle`、`sleep`、`destroyed` 生命周期状态机，以及统一的 session、tool、file 和 explicit-end 信号，属于后续版本设计。
+
+生命周期适配器不绑定某个 Agent 的内部实现：适配器只负责归一化宿主事件，Runtime 核心不把 inactivity 超时推断当作可靠的 agent-end 事实。当前可可靠捕获的 Claude 事件仍受宿主提供的 Hook 和稳定标识限制。
+
+低开销、隐私优先的 Git/file activity summary 仍属于后续版本范围：只记录经过过滤的相对路径、计数、状态变化和摘要 metadata，不记录原始命令、stdout、diff 或文件内容；事件必须 debounce/coalesce，并作为后续 Context Compiler 的候选证据，而不是自动验证的 Knowledge。
 
-所有版本均保持本地优先、显式治理与 fail-open 集成原则。v1 数据不会在迁移过程中被重写；当 v2 未启用、不可用、损坏或尚未同步时，读取接口会回退到兼容的 v1 行为。
+### 1.0 发布门槛
+
+1. **稳定契约**：Context Source Descriptor、Context Manifest/Compiler、Decision Graph、Knowledge Evolution、只读 MCP 与 Agent API 具有明确的版本化兼容契约。
+2. **正确性与恢复**：编译与 journal replay 可确定性复现；hash chain 验证、投影 rebuild/repair、迁移一致性、损坏回退与 Windows/macOS/Linux 支持完善。
+3. **治理与隐私**：外部来源始终保持原生权威；持久化和输出前均应用敏感信息过滤；每个注入的项目认知都可追溯、适用且具有受治理生命周期。
+4. **集成中立**：Claude、Cursor 与未来宿主均为可选适配器；核心不依赖特定模型、IDE、SaaS、网络或向量数据库。
+5. **运行质量**：延迟与存储有界，Runtime 健康状态可观测，选择与截断可解释，适配器不可用时保持 fail-open。
+6. **产品表达一致**：文档与 API 明确 `ctx` 是 Runtime 的前端；`fluffy-context` 是对上下文进行编排的 Runtime，而不是仓库规则、Memory、Skills 或 MCP 能力的替代品。
+
+上述路线图描述的是 `0.6.6` 及之后的演进方向。0.6.5 提供 Runtime 活跃度修复与 Hook 保活；0.6.6 已提供已迁移项目的无感自动启动与 fail-open 唤醒。更完整的生命周期状态机、Git/file activity summary 和被动学习仍属于后续版本范围。
 
 ## 适用场景
 
@@ -79,6 +137,39 @@ ctx orient
 ctx orient --context <context-id> --note-limit 10
 ```
 
+### 0.7.x Context Compiler
+
+`ctx orient` 面向快速恢复，`ctx compile` 面向需要结构化输入的 Agent 或适配器。Compiler 只读当前 Context、Snapshot、open Note、已验证 Knowledge/Deadend 及可用的 v2 来源，返回 JSON Manifest：
+
+```bash
+ctx compile "修复支付回调" --max-chars 4000
+ctx compile "验证签名逻辑" --scenario verification --paths src/auth.ts
+ctx compile "查看最近修改" --activity-limit 10 --max-chars 4000
+```
+
+Manifest 包含 `intent`、`selected`、`sections`、`excluded`、`provenance`、`budget` 和最终 `text`。`maxChars` 使用 JavaScript UTF-16 字符串长度；Compiler 不调用模型、不写入 Context 或 journal，重复输入会得到确定性结果。普通查询默认只纳入已验证 Knowledge 和 Deadend，Candidate、deprecated、rejected、obsolete 等记录会明确排除。
+
+0.7.2 新增的 `activity` section 来自已记录的 `workspace.paths.changed` 事件，只包含近期当前 branch/worktree/ref 的相对路径和有限 metadata。它表示“观察到文件发生变化”，不表示文件已被读取、理解或测试；不包含内容、diff、命令或输出。`--activity-limit 0` 可在单次编译中关闭 activity 候选，且不会修改 Runtime 的文件监听策略。v1 fallback 没有等价的文件活动来源，因此返回空的 `activity` section。
+
+### 文件变化观察
+
+文件监听是可选能力，默认关闭。要显式开启：
+
+```bash
+ctx filesystem enable
+ctx filesystem status
+```
+
+关闭监听：
+
+```bash
+ctx filesystem disable
+```
+
+如果 Runtime 已在运行，enable/disable 会自动按新策略重启 Runtime；如果 Runtime 尚未运行，只更新 policy。观察器只记录项目相对路径、文件类型、大小和修改时间等有限 metadata，不记录文件内容、diff、命令或输出。
+
+文件路径会经过与 Context 关联文件相同的 `.contextignored` 规则过滤。被 `.contextignored` 排除的文件，即使发生创建、修改或删除，也不会写入 `workspace.paths.changed` 事件；即使历史事件中存在这类路径，Compiler 也会再次过滤。内置保护规则仍然优先排除 `.context/`、`.git/`、依赖/构建目录、环境变量、密钥和越界路径。
+
 ## Agent 工作流
 
 推荐阶段：
@@ -132,7 +223,7 @@ ctx migrate v1 --apply
 ctx migrate verify
 ```
 
-只有完成迁移后才可启用 Runtime：
+迁移成功后，Runtime 默认已启用自动启动；以下命令用于显式诊断、手动控制或持久化选择退出：
 
 ```bash
 ctx runtime enable
@@ -144,9 +235,9 @@ ctx runtime disable
 
 Runtime 是单项目、按需启动的本地守护进程。它只绑定 `127.0.0.1` 的动态端口，并要求存储在项目本地 `.context/v2/runtime/secret` 中的能力令牌；令牌不会显示在 CLI 状态输出或写入事件日志。启动后，Runtime 持续观察当前 worktree 的 Git 状态：初始状态会记录 `git.state.observed`，分支/ref 切换记录 `git.branch.changed`，HEAD 更新记录 `git.head.changed`。这些事件会重建 branch workspace 投影，但不会自动创建 checkpoint 或将候选信息提升为已验证共识。
 
-完成迁移并显式 `ctx runtime enable` 后，`ctx orient`、MCP `context_orient` 与 Claude Hook 会优先选择当前 worktree/ref 的 v2 workspace；它不会借用其他分支的 Context。v2 可用时，Knowledge 与 Deadend 由 journal 重放出的确定性倒排索引直接检索，默认仅返回已验证且适用的记录；无匹配 workspace、v2 状态不可用、journal 损坏、v1 尚未同步或 Runtime 已禁用时，接口会安全回退到既有 v1 选择逻辑。Runtime 停止时仍可读取已验证的 v2 状态，但运行中的 Runtime 负责持续 Git 观察和 v1 写入镜像。
+完成迁移且未显式 disable 时，`ctx orient`、MCP `context_orient` 与 Claude Hook 会在严格短超时内幂等确保 Runtime 可用，并优先选择当前 worktree/ref 的 v2 workspace；它不会借用其他分支的 Context。v2 可用时，Knowledge 与 Deadend 由 journal 重放出的确定性倒排索引直接检索，默认仅返回已验证且适用的记录；无匹配 workspace、v2 状态不可用、journal 损坏、v1 尚未同步或 Runtime 已禁用时，接口会安全回退到既有 v1 选择逻辑。Runtime 停止时仍可读取已验证的 v2 状态，但运行中的 Runtime 负责持续 Git 观察和 v1 写入镜像。
 
-Claude Hook 仅在宿主提供稳定的 session 与 event 标识时记录 `host.session.started` 或 `host.prompt.submitted`。提示只保存按 `promptIntentMaxChars` 截断并经过敏感值脱敏后的 intent，绝不保存原始提示；缺少稳定标识时不写入事件。默认 Hook 不启动守护进程；将 v2 policy 的 `allowHookStartup` 设为 `true` 后，SessionStart 才会在严格超时内尽力启动 Runtime，失败仍会 fail open。UserPromptSubmit 不会启动 Runtime。
+Claude Hook 仅在宿主提供稳定的 session 与 event 标识时记录 `host.session.started` 或 `host.prompt.submitted`。提示只保存按 `promptIntentMaxChars` 截断并经过敏感值脱敏后的 intent，绝不保存原始提示；缺少稳定标识时不写入事件。SessionStart 与 UserPromptSubmit 都会在严格短超时内尽力确保已迁移、未显式 disable 的项目 Runtime 可用；稳定标识仅影响宿主事件是否写入。启动或读取失败始终 fail open，不阻塞宿主工作流。
 
 ### `ctx checkpoint` 和 `ctx resume`
 

package/dist/src/agent/index.d.ts

@@ -1,3 +1,5 @@
 export * from './api.js';
 export type { ContextOrientContext, ContextUseInput, ContextOrientExplanation, ContextOrientNoContextResult, ContextOrientOptions, ContextOrientReadyResult, ContextOrientResult, ContextOrientSnapshot, } from './types.js';
 export type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, ContextSearchHit, ContextSearchOptions, ContextSearchResult, } from '../runtime/types.js';
+export { compileContext } from '../compiler/compile.js';
+export type { ContextActivityRecord, ContextAnchor, ContextBudget, ContextBudgetReport, ContextCandidate, ContextCandidateSection, ContextCompileOptions, ContextExclusion, ContextExclusionReason, ContextIntent, ContextIntentSignal, ContextManifest, ContextProvenance, ContextScenario, ContextSourceDescriptor, ContextTruncation, } from '../compiler/types.js';

package/dist/src/agent/index.js

@@ -1 +1,2 @@
 export * from './api.js';
+export { compileContext } from '../compiler/compile.js';

package/dist/src/cli/main.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { checkpoint, resume } from '../runtime/runtime.js';
 import { contextOrient } from '../agent/api.js';
+import { compileContext } from '../compiler/compile.js';
 import { importV1, verifyV1Import } from '../cognition/migration-v1.js';
 import { recordUse } from '../cognition/feedback.js';
-import { readJournal } from '../cognition/journal.js';
+import { verifyJournal } from '../cognition/journal.js';
 import { projectEvents } from '../cognition/projections.js';
-import { disableRuntime, enableRuntime, runtimeStatus, serveRuntime, startRuntime, stopRuntime } from '../cognition/runtime.js';
+import { disableRuntime, enableRuntime, ensureRuntimeForSession, runtimeStatus, serveRuntime, setFilesystemEvents, startRuntime, stopRuntime } from '../cognition/runtime.js';
+import { loadRuntimePolicy } from '../cognition/policy.js';
 import { migrationReadiness } from '../cognition/readiness.js';
 import { runClaudeCodeHook } from '../hooks/claude-code.js';
 import { readGitWorktreeState } from '../git/git-adapter.js';
@@ -115,6 +117,21 @@ Options:
   --knowledge-limit <number> Maximum knowledge matches (default: 10)
   --deadend-limit <number>   Maximum deadend matches (default: 10)
   --note-limit <number>      Maximum open notes (default: 20)`,
+    compile: `usage: ctx compile [query] [options]
+
+Compile bounded, provider-neutral context with source provenance and selection explanations.
+
+Options:
+  --path <path>              Project path
+  --context <id>             Context ID
+  --scenario <scenario>      resume|implementation|debugging|verification|handoff|exploration|unknown
+  --scope <scope>            Exact consensus scope
+  --paths <paths>            Comma-separated project-relative paths
+  --max-chars <number>       Maximum compiled characters
+  --knowledge-limit <number> Maximum knowledge matches (default: 10)
+  --deadend-limit <number>   Maximum deadend matches (default: 10)
+  --note-limit <number>      Maximum open notes (default: 20)
+  --activity-limit <number>  Maximum recent activity groups (default: 20)`,
     agent: `usage: ctx agent serve
 
 Start an MCP stdio server for Agent integrations.
@@ -289,6 +306,18 @@ Options:
     runtime: `usage: ctx runtime enable|disable|start|stop|status [--path <path>]
 
 Control the local event-driven Knowledge Runtime after v1 migration verification.`,
+    filesystem: `usage: ctx filesystem enable|disable|status [--path <path>]
+
+Control whether the Runtime records filtered file metadata changes.`,
+    'filesystem enable': `usage: ctx filesystem enable [--path <path>]
+
+Enable filtered filesystem change observation and restart a running Runtime.`,
+    'filesystem disable': `usage: ctx filesystem disable [--path <path>]
+
+Disable filesystem change observation and restart a running Runtime.`,
+    'filesystem status': `usage: ctx filesystem status [--path <path>]
+
+Show the filesystem observation policy and Runtime status.`,
     'runtime status': `usage: ctx runtime status [--path <path>]
 
 Show the read-only runtime policy, migration and authenticated lease status.
@@ -312,7 +341,7 @@ Stop the local runtime through authenticated loopback IPC.`,
 Internal runtime daemon entry point.`,
 };
 function usage() {
-    return `usage: ctx init|checkpoint|resume|orient|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|feedback|journal [options]
+    return `usage: ctx init|checkpoint|resume|orient|compile|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|journal [options]
 
 Run \"ctx <command> --help\" for command details.`;
 }
@@ -340,7 +369,8 @@ function printHelp(args) {
         || (command === 'journal' && args[1] === 'verify')
         || (command === 'note' && ['add', 'list'].includes(args[1]))
         || (command === 'migrate' && ['v1', 'verify'].includes(args[1]))
-        || (command === 'runtime' && ['enable', 'disable', 'start', 'stop', 'status', 'serve'].includes(args[1]));
+        || (command === 'runtime' && ['enable', 'disable', 'start', 'stop', 'status', 'serve'].includes(args[1]))
+        || (command === 'filesystem' && ['enable', 'disable', 'status'].includes(args[1]));
     const key = nested ? `${command} ${args[1]}` : command;
     const nestedKey = key === 'integrate claude' && (args[2] === 'inspect' || args[2] === 'install') ? `${key} ${args[2]}` : key;
     const help = HELP[nestedKey];
@@ -405,6 +435,7 @@ async function run(args) {
             validateOptions(args.slice(1), valueOptions, valueOptions);
             const query = positionals(args.slice(1), valueOptions);
             validatePositionals(query, 1, HELP.orient);
+            await ensureRuntimeForSession(target, { source: 'cli', timeoutMs: 1_000 }).catch(() => undefined);
             print(await contextOrient(target, {
                 contextId: option(args, '--context'),
                 query: query[0],
@@ -416,6 +447,25 @@ async function run(args) {
             }));
             return;
         }
+        case 'compile': {
+            const valueOptions = ['--path', '--context', '--scenario', '--scope', '--paths', '--max-chars', '--knowledge-limit', '--deadend-limit', '--note-limit', '--activity-limit'];
+            validateOptions(args.slice(1), valueOptions, valueOptions);
+            const query = positionals(args.slice(1), valueOptions);
+            validatePositionals(query, 1, HELP.compile);
+            print(await compileContext(target, {
+                contextId: option(args, '--context'),
+                query: query[0],
+                scenario: enumOption(args, '--scenario', ['resume', 'implementation', 'debugging', 'verification', 'handoff', 'exploration', 'unknown']),
+                scope: option(args, '--scope'),
+                paths: listOption(args, '--paths'),
+                maxChars: numericOption(args, '--max-chars', 4000),
+                knowledgeLimit: numericOption(args, '--knowledge-limit', 10),
+                deadendLimit: numericOption(args, '--deadend-limit', 10),
+                noteLimit: numericOption(args, '--note-limit', 20),
+                activityLimit: numericOption(args, '--activity-limit', 20),
+            }));
+            return;
+        }
         case 'agent':
             if (args[1] !== 'serve')
                 throw new Error(HELP.agent);
@@ -511,13 +561,27 @@ async function run(args) {
             print(await recordUse(target, { entity: args[2], entityId: values[0], eventId: option(args, '--event-id') ?? '' }));
             return;
         }
+        case 'filesystem': {
+            if (!['enable', 'disable', 'status'].includes(args[1]))
+                throw new Error(HELP.filesystem);
+            validateOptions(args.slice(2), ['--path'], ['--path']);
+            validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP[`filesystem ${args[1]}`]);
+            if (args[1] === 'status') {
+                const status = await runtimeStatus(target);
+                print({ projectRoot: status.projectRoot, migrated: status.migrated, enabled: status.enabled, running: status.running, filesystemEventsEnabled: status.migrated ? (await loadRuntimePolicy(status.projectRoot)).filesystemEventsEnabled : false });
+            }
+            else {
+                print(await setFilesystemEvents(target, args[1] === 'enable'));
+            }
+            return;
+        }
         case 'journal': {
             if (args[1] !== 'verify')
                 throw new Error(HELP.journal);
             validateOptions(args.slice(2), ['--path'], ['--path']);
             validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP['journal verify']);
             const root = target ?? process.cwd();
-            const events = await readJournal(root);
+            const events = await verifyJournal(root);
             const projection = projectEvents(events);
             const last = events.at(-1);
             print({ verified: true, eventCount: events.length, cursor: { eventId: last?.eventId ?? null, hash: last?.hash ?? null }, counts: { contexts: Object.keys(projection.contexts).length, notes: Object.keys(projection.notes).length, knowledge: Object.keys(projection.knowledge).length, deadends: Object.keys(projection.deadends).length } });

package/dist/src/cognition/filesystem-observer.d.ts

@@ -0,0 +1,41 @@
+import type { CognitionGitAnchor } from './types.js';
+export type WatchCallback = (eventType: string, filename: string | Buffer | null) => void;
+export type WatchFactory = (projectRoot: string, callback: WatchCallback) => {
+    close(): void;
+};
+export interface FilesystemObserverOptions {
+    anchor?: () => CognitionGitAnchor;
+    debounceMs?: number;
+    maxPaths?: number;
+    maxPayloadBytes?: number;
+    watchFactory?: WatchFactory;
+    onChanged?: (result: FilesystemObservationResult) => void;
+}
+export interface FilesystemObservationResult {
+    changed: boolean;
+    paths: string[];
+}
+export declare class FilesystemObserver {
+    private readonly projectRoot;
+    private readonly debounceMs;
+    private readonly maxPaths;
+    private readonly maxPayloadBytes;
+    private readonly anchor;
+    private readonly watchFactory;
+    private readonly onChanged;
+    private readonly pendingPaths;
+    private readonly known;
+    private watcher;
+    private timer;
+    private pending;
+    private closed;
+    constructor(projectRoot: string, options?: FilesystemObserverOptions);
+    start(): void;
+    stop(): void;
+    observeNow(): Promise<FilesystemObservationResult>;
+    flush(): Promise<FilesystemObservationResult>;
+    drain(): Promise<void>;
+    close(): void;
+    private scheduleFlush;
+    private process;
+}

package/dist/src/cognition/filesystem-observer.js

@@ -0,0 +1,164 @@
+import { watch } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { filterPaths } from '../capture/context-filter.js';
+import { appendEvent } from './journal.js';
+const defaultDebounceMs = 250;
+const defaultMaxPaths = 100;
+const defaultMaxPayloadBytes = 16 * 1024;
+function defaultWatchFactory(projectRoot, callback) {
+    return watch(projectRoot, { recursive: true }, callback);
+}
+function normalizeCandidate(projectRoot, filename) {
+    if (filename === null)
+        return null;
+    const value = filename.toString().replaceAll('\\', '/').replace(/^\.\//, '');
+    if (!value || value.startsWith('/') || /^[A-Za-z]:\//.test(value))
+        return null;
+    const absolute = resolve(projectRoot, value);
+    const relative = absolute.slice(resolve(projectRoot).length).replaceAll('\\', '/').replace(/^\/+/, '');
+    return relative || null;
+}
+function metadataEqual(left, right) {
+    return left?.sizeBytes === right.sizeBytes && left.mtimeMs === right.mtimeMs;
+}
+function payloadSize(payload) {
+    return Buffer.byteLength(JSON.stringify(payload), 'utf8');
+}
+export class FilesystemObserver {
+    projectRoot;
+    debounceMs;
+    maxPaths;
+    maxPayloadBytes;
+    anchor;
+    watchFactory;
+    onChanged;
+    pendingPaths = new Map();
+    known = new Map();
+    watcher = null;
+    timer = null;
+    pending = Promise.resolve({ changed: false, paths: [] });
+    closed = false;
+    constructor(projectRoot, options = {}) {
+        this.projectRoot = projectRoot;
+        this.debounceMs = options.debounceMs ?? defaultDebounceMs;
+        this.maxPaths = options.maxPaths ?? defaultMaxPaths;
+        this.maxPayloadBytes = options.maxPayloadBytes ?? defaultMaxPayloadBytes;
+        this.anchor = options.anchor ?? (() => ({ worktreeId: null, branch: null, ref: null, head: null }));
+        this.watchFactory = options.watchFactory ?? defaultWatchFactory;
+        this.onChanged = options.onChanged;
+    }
+    start() {
+        if (this.closed || this.watcher)
+            return;
+        this.watcher = this.watchFactory(this.projectRoot, (eventType, filename) => {
+            const relative = normalizeCandidate(this.projectRoot, filename);
+            if (relative)
+                this.pendingPaths.set(relative, eventType);
+            this.scheduleFlush();
+        });
+    }
+    stop() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.watcher?.close();
+        this.watcher = null;
+        this.closed = true;
+    }
+    observeNow() {
+        return this.flush();
+    }
+    async flush() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        const paths = [...this.pendingPaths.entries()];
+        this.pendingPaths.clear();
+        if (paths.length === 0)
+            return { changed: false, paths: [] };
+        const operation = this.pending.then(() => this.process(paths), () => this.process(paths));
+        this.pending = operation;
+        return operation;
+    }
+    async drain() {
+        await this.pending;
+        if (this.pendingPaths.size > 0)
+            await this.flush();
+        await this.pending;
+    }
+    close() {
+        this.stop();
+    }
+    scheduleFlush(delay = this.debounceMs) {
+        if (this.timer || this.closed)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.flush().catch(() => undefined);
+        }, delay);
+    }
+    async process(paths) {
+        const filtered = await filterPaths(this.projectRoot, paths.map(([relative]) => relative));
+        const eventTypes = new Map(paths);
+        const changes = [];
+        for (const relative of filtered.slice(0, this.maxPaths)) {
+            const absolute = resolve(this.projectRoot, relative);
+            let current = null;
+            try {
+                const value = await stat(absolute);
+                if (!value.isFile())
+                    continue;
+                current = { sizeBytes: value.size, mtimeMs: value.mtimeMs };
+            }
+            catch {
+                current = null;
+            }
+            const previous = this.known.get(relative);
+            if (current && metadataEqual(previous, current))
+                continue;
+            if (!current && !previous)
+                continue;
+            if (current)
+                this.known.set(relative, current);
+            else
+                this.known.delete(relative);
+            changes.push({
+                path: relative,
+                kind: current ? (previous ? 'modified' : eventTypes.get(relative) === 'rename' ? 'created' : 'modified') : 'deleted',
+                fileType: 'file',
+                ...(current ? { sizeBytes: current.sizeBytes, mtimeMs: current.mtimeMs } : {}),
+            });
+        }
+        if (changes.length === 0)
+            return { changed: false, paths: [] };
+        const limitedChanges = changes.slice(0, this.maxPaths);
+        const basePayload = {
+            schemaVersion: 1,
+            paths: limitedChanges.map((change) => change.path),
+            changes: limitedChanges,
+            pathCount: limitedChanges.length,
+            coalesced: paths.length > 1,
+            truncated: filtered.length > limitedChanges.length || payloadSize({ changes: limitedChanges }) > this.maxPayloadBytes,
+        };
+        while (basePayload.changes.length > 1 && payloadSize(basePayload) > this.maxPayloadBytes) {
+            basePayload.changes.pop();
+            basePayload.paths.pop();
+            basePayload.pathCount = basePayload.changes.length;
+            basePayload.truncated = true;
+        }
+        if (basePayload.changes.length === 0 || payloadSize(basePayload) > this.maxPayloadBytes)
+            return { changed: false, paths: [] };
+        const result = await appendEvent(this.projectRoot, {
+            type: 'workspace.paths.changed',
+            source: { kind: 'fs-observer' },
+            idempotencyKey: `fs:paths:${basePayload.paths.join(',')}:${basePayload.changes.map((change) => `${change.kind}:${change.sizeBytes ?? ''}:${change.mtimeMs ?? ''}`).join(',')}`,
+            git: this.anchor(),
+            payload: basePayload,
+        });
+        const observation = { changed: result.appended, paths: basePayload.paths };
+        if (observation.changed)
+            this.onChanged?.(observation);
+        return observation;
+    }
+}

package/dist/src/cognition/git-observer.d.ts

@@ -4,6 +4,7 @@ export declare class GitObserver {
     private previous;
     private pending;
     constructor(projectRoot: string);
+    get current(): GitWorktreeState | null;
     observeNow(): Promise<{
         state: GitWorktreeState;
         changed: boolean;

package/dist/src/cognition/git-observer.js

@@ -1,6 +1,5 @@
 import { readGitWorktreeState } from '../git/git-adapter.js';
 import { appendEvent } from './journal.js';
-import { rebuildProjections } from './projections.js';
 function anchor(state) {
     return { worktreeId: state.worktreeId, branch: state.branch, ref: state.ref, head: state.commit };
 }
@@ -14,6 +13,9 @@ export class GitObserver {
     constructor(projectRoot) {
         this.projectRoot = projectRoot;
     }
+    get current() {
+        return this.previous;
+    }
     observeNow() {
         const observation = this.pending.then(() => this.observe());
         this.pending = observation.then(() => undefined, () => undefined);
@@ -55,7 +57,6 @@ export class GitObserver {
             });
         }
         this.previous = state;
-        await rebuildProjections(this.projectRoot);
         return { state, changed: true };
     }
 }

package/dist/src/cognition/journal.d.ts

@@ -17,7 +17,10 @@ export interface AppendEventInput<T = Record<string, unknown>> {
     payload: T;
 }
 export declare function eventHash<T>(event: Omit<CognitionEvent<T>, 'hash'>): string;
-export declare function readJournal(startPath?: string): Promise<CognitionEvent[]>;
+export declare function readJournal(startPath?: string, options?: {
+    allowPartialTail?: boolean;
+}): Promise<CognitionEvent[]>;
+export declare function verifyJournal(startPath?: string): Promise<CognitionEvent[]>;
 export declare function appendEvent<T>(startPath: string | undefined, input: AppendEventInput<T>): Promise<{
     event: CognitionEvent<T>;
     appended: boolean;