@piagent/platform 1.2.8 → 1.2.10

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.2.10 - 2026-07-31
+
+### Security
+
+- `contextIndexV2Status` giờ yêu cầu `excludePatterns` tường minh như năm
+  Context Engine API còn lại. Status không còn báo `policyStale: false` khi
+  caller chưa cung cấp policy để đối chiếu, nên caller mới không thể vô tình bỏ
+  qua rebuild của index được tạo bằng luật yếu hơn.
+
+- Đã xóa fallback đọc exclusion list từ metadata cũ. Active policy luôn đến từ
+  caller đã resolve project policy; index metadata chỉ còn là giá trị stored để
+  so digest.
+
+- Context index storage giờ dùng directory mode `0700` và mode `0600` cho
+  SQLite database, WAL và SHM. Mỗi connection bật cả SQLite core
+  `secure_delete` lẫn FTS5 `secure-delete`, nên source bị xóa trong refresh bình
+  thường không còn nằm lại trong raw index bytes.
+
+- Exclusion policy version `2` buộc index cũ tự migrate một lần khi mở bằng
+  policy hiện hành. Migration dựng lại toàn bộ FTS index từ content table đã
+  lọc, checkpoint WAL rồi `VACUUM` để purge cả tombstone FTS và free-page bytes
+  được tạo bởi bản cũ. Digest mới và `purgePending: 1` được commit cùng nhau
+  trước pha purge; cờ chỉ clear sau khi toàn bộ chuỗi thành công. Nếu app hoặc
+  máy dừng giữa chừng, lần mở sau tự retry.
+
+- Full FTS rebuild và `VACUUM` chỉ chạy khi exclusion digest đổi hoặc một purge
+  cũ còn pending. Incremental rebuild cùng policy không nhận chi phí này.
+
+- Image path trong chat giờ chỉ được auto-attach khi target thật nằm trong
+  project hoặc `additionalReadRoots`, không khớp protected path, nằm trong
+  capability read scope hiện hành và có bytes đúng định dạng ảnh. Symlink ra
+  ngoài root, ảnh trong `.pi/piagent-state/**` và file giả đuôi `.png` đều bị
+  từ chối trước khi nội dung được đưa vào model.
+
+- MCP approval gate và `piagent-mcp doctor` giờ nhận diện cả `directTools` đặt
+  trên từng server. Repository server bật direct tool trong khi
+  `toolPrefix: "none"` sẽ fail-closed vì tên tool không còn mang server origin.
+
+- `piagent-reviewer` giờ là read-only thật: manifest chỉ cấp `read`, `grep`,
+  `find`, `ls`; autofix phải chuyển sang `piagent-worker`. Test package ghim
+  mọi subagent có `acceptanceRole: read-only` vào allowlist read-only.
+
+## v1.2.9 - 2026-07-31
+
+### Security
+
+- Context Engine CLI và runtime giờ dùng chung một policy resolver. Base policy,
+  profile `extends`, `protectedPaths`, `shellProtectedPaths`, `readOnlyPaths` và
+  custom context-index path cùng tạo ra một canonical exclusion list; context
+  search/pack không còn đọc một view khác với guard.
+
+- Context index metadata ghi versioned exclusion digest. Search, pack, impact và
+  auto-context rebuild incremental khi digest hiện hành khác digest đã build,
+  đồng thời lọc lại candidate ở read time. Index cũ tạo bằng luật yếu hơn vì vậy
+  tự loại nội dung protected trước khi model nhận context.
+
+- Context Engine từ chối source-shaped symlink và canonical path đi ra ngoài
+  project ở cả build, stale check và pack read.
+
+- API build, ensure, search, pack và impact giờ fail-closed nếu caller không
+  truyền `excludePatterns` tường minh. `[]` vẫn được hỗ trợ cho low-level tool
+  chủ ý chạy không loại trừ; caller mới không còn vô tình quay về permissive
+  default.
+
+### Fixed
+
+- `piagent-update --dry-run --project ...` báo trực tiếp khi helper thiếu project
+  migrator thay vì chạy Node rồi trả stack `MODULE_NOT_FOUND`.
+
+### Documentation
+
+- Tài liệu ghi rõ dynamic tools, auto context và Context Engine telemetry bật mặc
+  định; telemetry vẫn chỉ lưu metadata/hash đã redact, không lưu prompt hay tool
+  output thô.
+
 ## v1.2.8 - 2026-07-31
 
 ### Changed

package/README.md

@@ -74,10 +74,10 @@ Removal targets what is registered in Pi's settings rather than what the current
 - Runtime profile selection via `/profile`, plus select-style tech stack setup via `/profile setup` and `/profile tech`.
 - Runtime usage/session controls via `/usage`, `/name`, `/fresh`, plus Pi native `/session`.
 - Explicit project memory via `/memory` or `/memory-policy` and `piagent_memory_*` tools.
-- Local Context Engine controls via `/context`: incremental code index, hybrid search, token-budgeted packs, test impact, efficiency telemetry, and semantic compaction. Results remain advisory, not a security boundary or source of truth.
+- Local Context Engine controls via `/context`: incremental code index, hybrid search, token-budgeted packs, test impact, efficiency telemetry, and semantic compaction. Index storage is owner-only and securely purged when exclusion policy changes; results remain advisory, not a security boundary or source of truth.
 - MCP setup helpers for Context7, Chrome DevTools, GitHub, Playwright, and Figma.
 - Subagent setup helpers for read-only scouting, planning, implementation, review, and risk challenge.
-- Chat image-path intake: paste a local screenshot path into the Pi chat box and the guard attaches it as `[image1]` before the model sees the prompt.
+- Chat image-path intake: paste a screenshot path from the project or a granted `additionalReadRoots` directory and the guard attaches it as `[image1]` before the model sees the prompt.
 - Trusted-run wrapper: `piagent-auto` launches Pi with `--approve` for the current run while keeping piagent guardrails active.
 - Runtime policy tools:
   - `piagent_permission_status`
@@ -187,7 +187,7 @@ Short workflow aliases such as `/task`, `/scout`, `/be-to-fe`, `/commit`, and `/
 
 Git stays a capability rather than a `/git-*` namespace, so natural language works too. Broad staging — `git add .`, `git add -A`, `git add --all`, `git add -- .`, `git add :/` — requires confirmation, so unrelated or private files are not swept into a commit silently.
 
-Paste a local screenshot path straight into a task and the guard attaches it as `[image1]` before the model sees the prompt: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`, up to 4 images at 8 MB each. The guard also collapses pasted mandatory-flow boilerplate, so there is no need to paste a checklist into every task.
+Paste a screenshot path straight into a task and the guard attaches it as `[image1]` before the model sees the prompt: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`, up to 4 images at 8 MB each. The target must be inside the project or a directory listed in `additionalReadRoots`; protected paths, paths outside the resolved filesystem read scope, symlink escapes, and extension-only fake images are refused. The guard also collapses pasted mandatory-flow boilerplate, so there is no need to paste a checklist into every task.
 
 A spec that lives outside the project — the one just downloaded to `~/Downloads` — is read with `piagent_document_read` once its directory is listed in the profile's `additionalReadRoots`. The grant is read-only, covers `.md`, `.txt`, `.csv`, `.json`, `.yaml`, `.pdf`, and `.docx` only, and does not open anything `protectedPaths` covers. See [command reference](docs/command-reference-vietnamese.md).
 
@@ -291,7 +291,7 @@ This repository intentionally excludes:
 
 ## Maturity
 
-The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.2.8` or a reviewed commit.
+The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.2.10` or a reviewed commit.
 
 Ready for:
 

package/catalog/capabilities.json

@@ -89,8 +89,8 @@
           "path": "packages/piagent-core/subagents/piagent-planner.md"
         },
         {
-          "byteSize": 1601,
-          "digest": "sha256:be1ec2282db3038717c1e66e91e3890b8d0d665fed039c903cc1e4a3c427f69e",
+          "byteSize": 1604,
+          "digest": "sha256:ee050d70faba909a9b8f82d24a63d8bad90178380d266af0d071010538bc8d3c",
           "id": "piagent-reviewer",
           "kind": "subagents",
           "path": "packages/piagent-core/subagents/piagent-reviewer.md"

package/docs/command-reference-vietnamese.md

@@ -177,11 +177,14 @@ Alias `/commit` và `/pr` vẫn chạy. Commit workflow chỉ tạo local commit
 
 | Tình huống | Cách dùng | Kết quả |
 |---|---|---|
-| Chat box trả ra local path ảnh | `/workflow scout Check screenshot /var/folders/.../screenshot.png` | Platform attach ảnh và rewrite path thành `[image1]`. |
+| Chat box trả ra local path ảnh | `/workflow scout Check screenshot ~/Documents/team-screenshots/screenshot.png` | Platform attach ảnh nếu file ở trong project hoặc folder đã cấp bằng `additionalReadRoots`, rồi rewrite path thành `[image1]`. |
 | Nhiều ảnh trong cùng prompt | Dán tối đa 4 path ảnh | Prompt có `[image1]`, `[image2]`, ... |
 | Ảnh quá lớn | Dùng Pi `read` tool trên file ảnh hoặc resize ảnh trước | Tránh nhồi ảnh quá lớn vào chat input. |
 
-Định dạng hỗ trợ: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`. Giới hạn mặc định: 4 ảnh/input, 8 MB/ảnh.
+Định dạng hỗ trợ: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`. Giới hạn
+mặc định: 4 ảnh/input, 8 MB/ảnh. Protected path, symlink đi khỏi readable root,
+file ngoài capability read scope và file chỉ giả đuôi ảnh đều bị từ chối trước
+khi bytes được attach.
 
 Profile name nên biết:
 
@@ -465,8 +468,8 @@ Các lệnh này chạy ngoài Pi.
 | Command | Dùng khi nào |
 |---|---|
 | `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.2.8` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.8` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.10` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.10` | Cài pinned release khi cần reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
 | `piagent-update --check` | Báo version hiện tại vs version sẽ lên cho cả ba thành phần; không cài gì. |
 | `piagent-update` | Full update global một lệnh cho cả máy: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. |

package/docs/context-engine.md

@@ -34,7 +34,10 @@ task
   model, thinking, active-tool count, usage, retrieval confidence và đường dẫn
   tương đối đã được guard redaction.
 
-Rollback flags:
+Ba cơ chế `PIAGENT_DYNAMIC_TOOLS`, `PIAGENT_AUTO_CONTEXT` và
+`PIAGENT_CONTEXT_TELEMETRY` đều **bật mặc định** từ `v1.2.6`. Telemetry chỉ ghi
+operational metadata/hash như mô tả dưới đây, không ghi prompt hoặc tool output
+thô. Tắt riêng từng cơ chế cho một lần chạy bằng:
 
 ```bash
 PIAGENT_DYNAMIC_TOOLS=off pi
@@ -56,6 +59,25 @@ dụng record có `mtime` và size không đổi. `.gitignore`, binary, file qu
 secret file, protected paths, dependency/build output và toàn bộ guard state
 không được index.
 
+Index chứa source body của những file được phép index, không chỉ metadata. Vì
+vậy directory `context-engine/` được giữ mode `0700`; SQLite database, WAL và
+SHM được giữ mode `0600`. Đây là ranh giới giữa các OS account trên cùng máy,
+không chặn process khác đang chạy bằng chính account của operator.
+
+Mỗi SQLite connection bật cả core `secure_delete` và FTS5 `secure-delete`.
+Refresh cùng policy vì vậy xóa source cũ khỏi ordinary table lẫn full-text
+index mà không chạy full compaction. Khi exclusion digest đổi, policy version
+`2` commit digest mới cùng `purgePending: 1` trước khi dựng lại FTS index từ
+content table đã lọc, checkpoint WAL rồi chạy `VACUUM`. Cờ pending chỉ clear
+sau khi toàn bộ chuỗi thành công; app hoặc máy dừng giữa chừng thì lần mở tiếp
+theo tự retry.
+
+FTS rebuild và `VACUUM` chỉ chạy khi policy đổi hoặc purge trước còn pending,
+không chạy ở mỗi refresh. Trong lúc `VACUUM`, máy có thể cần tạm thời gần gấp
+đôi dung lượng file database. Xem mô tả chính thức về
+[FTS5 rebuild/secure-delete](https://www.sqlite.org/fts5.html) và
+[VACUUM](https://www.sqlite.org/lang_vacuum.html).
+
 Symbol layer hiện dùng parser adapter zero-dependency cho TypeScript/JavaScript,
 Python, Go, Rust, Java/Kotlin/C#, C/C++, Swift, Dart, Ruby, PHP, Elixir, Lua,
 SQL và Markdown. Schema parser-neutral để có thể thêm Tree-sitter sau này mà
@@ -82,6 +104,13 @@ Context pack tách repo map và source snippets, sau đó dừng cứng tại to
 budget. Index chỉ là navigation evidence; model phải đọc file hiện tại trước
 khi edit.
 
+Tất cả API chạm context index (`build`, `status`, `ensure`, `search`, `pack`,
+`impact`) bắt buộc caller truyền `excludePatterns` tường minh và fail-closed
+nếu thiếu. Runtime và CLI lấy danh sách này từ shared project policy resolver;
+low-level tool hoặc test chỉ dùng `[]` khi chủ ý chọn không loại trừ. Dù
+`status` không trả source content, nó vẫn cần policy để không báo false-negative
+`policyStale: false` rồi khiến caller bỏ qua rebuild.
+
 ## P2: compaction, finder và test impact
 
 - `/context impact` đi ngược import graph từ file thay đổi và tìm test liên quan.

package/docs/distribution-standard.md

@@ -14,9 +14,9 @@ Repo này phải chạy được cho nhiều project/domain khác nhau. Vì vậ
 
 | Use case | Package source |
 |---|---|
-| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.8` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.10` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.2.8` |
+| Registry distribution | `npm:@piagent/platform@1.2.10` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -26,7 +26,7 @@ Latest tiện cho máy cá nhân muốn nhận cập nhật nhanh. Pin tag/commi
 
 | Channel | Command | Target | Policy |
 |---|---|---|---|
-| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.8` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.10` | Install the Pi package matching the helper. |
 | `exact` | `bash scripts/install-global.sh --version vX.Y.Z --resolve-tag` | Requested tag resolved to commit SHA | Pi-package-only rollout, rollback, and incident recovery. |
 | `dev` | `bash scripts/install-global.sh --dev` | Moving Git source | Personal/sandbox only; do not commit into project settings. |
 | `local` | `bash scripts/install-global.sh --local` | Current checkout path | Platform development only. |
@@ -53,7 +53,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.2.8
+pi install git:github.com/Vt-mmm/piagent@v1.2.10
 ```
 
 Không cần biết internal folder `packages/piagent-core`. Source không pin chỉ dành cho personal/sandbox như bảng channel ở trên.
@@ -65,12 +65,12 @@ Team nên install global package một lần:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.8
+npm install -g --ignore-scripts @piagent/platform@1.2.10
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.2.8` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.2.8`.
+`pi install git:github.com/Vt-mmm/piagent@v1.2.10` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.2.10`.
 
 Support matrix hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy smoke trước rollout; native Windows chưa phải target rollout team; WSL2 experimental. Chi tiết và version runtime nằm trong [release/install policy](release-install-policy.md).
 
@@ -120,7 +120,7 @@ Nếu muốn commit sẵn `.pi/piagent-profile.json` vào repo hoặc bootstrap
 ```bash
 bash scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.2.8 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.10 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/mcp-and-tools.md

@@ -137,6 +137,13 @@ Vì vậy một config đặt `directTools: true` cùng `toolPrefix: "none"` là
 
 Adapter **merge `settings` của cả bốn layer thành một block cho cả session**, layer sau ghi đè theo từng key — không phải per-server. Nên `directTools` đặt ở file này và `toolPrefix: "none"` đặt ở file kia vẫn ra đúng tổ hợp đó, trong khi đọc riêng từng file thì không file nào có vấn đề. Platform đọc settings đã merge, và báo cả hai file, vì sửa file nào cũng đủ.
 
+Adapter cũng hỗ trợ `directTools: true` hoặc danh sách tool ngay trên từng server,
+và giá trị per-server override default trong `settings`. Platform vì vậy resolve
+effective server entry, không chỉ đọc settings: nếu một repository server có
+direct tool hiệu lực trong khi prefix là `none`, guard và
+`piagent-mcp doctor` cùng fail-closed. Khi prefix vẫn là `server`/`short`, direct
+tool đã approve tiếp tục chạy bình thường.
+
 ### `imports` — server không nằm trong bốn scope
 
 Adapter nhận thêm key `imports` trong config MCP, để kéo định nghĩa server từ config của công cụ khác. Server vào session theo đường này **không** xuất hiện ở scope nào trong bốn scope trên, nên trước đây gate không thấy chúng.

package/docs/operator-manual-vietnamese.md

@@ -18,12 +18,12 @@ Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 +
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.8
+npm install -g --ignore-scripts @piagent/platform@1.2.10
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.8`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.10`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
 
 Nếu đang ở source checkout của platform, dùng helper theo channel để preview trước khi đổi:
 
@@ -99,7 +99,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.8
+npm install -g --ignore-scripts @piagent/platform@1.2.10
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -282,7 +282,7 @@ Không phải daily default. Dùng khi muốn tạo sẵn `.pi` files cho projec
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.2.8 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.10 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -347,10 +347,20 @@ Input guard của platform cũng tự collapse prompt có full `Mandatory flow`
 
 ### Gửi ảnh/screenshot trong chat
 
-Nếu Pi/chat box không tạo native image attachment mà chỉ hiện local path kiểu `/var/folders/.../Ảnh màn hình ...png`, cứ để nguyên path trong prompt:
+Nếu Pi/chat box không tạo native image attachment mà chỉ hiện local path, dùng
+ảnh nằm trong project hoặc một folder đã cấp qua `additionalReadRoots`. Ví dụ
+lưu screenshot vào `~/Documents/team-screenshots` rồi thêm folder đó vào profile:
+
+```json
+{
+  "additionalReadRoots": ["~/Documents/team-screenshots"]
+}
+```
+
+Sau đó để nguyên path trong prompt:
 
 ```text
-/workflow scout Scout UI issue from screenshot /var/folders/.../screenshot.png
+/workflow scout Scout UI issue from screenshot ~/Documents/team-screenshots/screenshot.png
 ```
 
 Piagent guard sẽ xử lý trước khi model nhận input:
@@ -360,9 +370,15 @@ Piagent guard sẽ xử lý trước khi model nhận input:
 3. thay path trong prompt bằng marker `[image1]`;
 4. báo `Piagent image input: attached [image1]`.
 
-Hỗ trợ `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`. Giới hạn mặc định: tối đa 4 ảnh/input, 8 MB/ảnh.
+Hỗ trợ `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`. Giới hạn mặc định:
+tối đa 4 ảnh/input, 8 MB/ảnh. Guard resolve target thật trước khi đọc, giữ
+`protectedPaths` và filesystem read scope, đồng thời kiểm tra bytes đúng định
+dạng ảnh; đổi tên file text thành `.png` không đủ để attach.
 
-Nếu ảnh quá lớn, lưu ảnh nhỏ hơn hoặc yêu cầu agent dùng Pi `read` tool trên file ảnh để Pi resize. Không cần copy ảnh vào repo và không commit screenshot tạm.
+Nếu ảnh quá lớn, lưu ảnh nhỏ hơn hoặc yêu cầu agent dùng Pi `read` tool trên file
+ảnh để Pi resize. Không cần commit screenshot tạm. Với path ngoài project chưa
+được cấp root, file không được đọc hoặc attach; chuỗi path vẫn chỉ là text trong
+prompt.
 
 ### BE spec lên FE
 
@@ -894,8 +910,8 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts @piagent/platform@1.2.8` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.8` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.10` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.10` | Install pinned release cho reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Install latest platform package cho máy cá nhân/sandbox. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. Mỗi release pin một Pi host chính xác; lấy đúng version của release đang cài trong [release/install policy](release-install-policy.md). |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá lại dependency findings của host cũ trước khi hạ version. |
@@ -1002,7 +1018,7 @@ Mở lại Pi session sau khi install.
 Cài lại terminal helper đúng release rồi kiểm tra `PATH`:
 
 ```bash
-npm install -g --ignore-scripts @piagent/platform@1.2.8
+npm install -g --ignore-scripts @piagent/platform@1.2.10
 command -v piagent-install
 ```
 

package/docs/publishing-for-teams.md

@@ -61,6 +61,8 @@ pi install /path/to/piagent
 - `1.2.6`: Context Engine v2, dynamic tool loading, hard-budget retrieval, semantic compaction, Agent Watch telemetry/feedback và quality benchmark theo context efficiency.
 - `1.2.7`: refresh exact MCP/subagent add-on pins, loại dependency URL/static-server có advisory và chặn cả moderate advisory trong runtime release gate.
 - `1.2.8`: cài `pi-web-access@0.17.0` mặc định trong setup/update để researcher subagents có web/search/fetch thật; thêm `--no-web-access` cho máy không được phép browse.
+- `1.2.9`: hợp nhất Context Engine exclusion policy giữa CLI và runtime, resolve profile `extends`, loại `readOnlyPaths`, tự rebuild index khi policy digest đổi, chặn symlink source ra ngoài project, và làm rõ lỗi thiếu migrator trong update dry-run.
+- `1.2.10`: bắt buộc `contextIndexV2Status` nhận explicit exclusion policy; Context Engine storage chuyển sang owner-only, bật core + FTS5 secure-delete và tự retry FTS rebuild/VACUUM khi policy đổi để purge raw bytes của index cũ.
 
 ## Không publish
 

package/docs/release-install-policy.md

@@ -10,7 +10,7 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.82.0`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
 
-| Surface | Status for v1.2.8 | Rollout guidance |
+| Surface | Status for v1.2.10 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -33,7 +33,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.8` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.10` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -53,7 +53,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.8
+npm install -g --ignore-scripts @piagent/platform@1.2.10
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.2.8 (helper package version)
-tag: v1.2.8
+currentRelease: v1.2.10 (helper package version)
+tag: v1.2.10
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -79,7 +79,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.2.8
+pi install git:github.com/Vt-mmm/piagent@v1.2.10
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.

package/docs/security-threat-model.md

@@ -14,6 +14,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - protected guard, profile, settings, capability-lock, and evidence files;
 - external GitHub, HTTP, MCP, and provider resources that can be mutated;
 - release identity, installer sources, dependency pins, and package contents;
+- source bodies and retrieval metadata stored in the local Context Engine index;
 - observed verification evidence used to approve task completion.
 
 ## Trust assumptions
@@ -21,7 +22,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.2.8, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.2.10, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes
@@ -42,10 +43,15 @@ The final category is outside the containment capability of the Piagent guard. I
 | Direct or nested path-like tool input | Bounded recursive input inspection, protected-path precedence, repository boundary checks, filesystem capability scopes, and read-only profile paths | A new carrier or field name must be classified before it can be treated as controlled. Unknown/ambiguous tools fail closed where policy requires confirmation. |
 | Shell glob reaching a protected file | Glob candidates are read from the same expanded, resolved word list as every other check and matched against examples of each protected pattern, so a pattern assembled by an expansion (`{cat,.env*}`, `cat $({echo,.env*})`, `{bash,} -c 'cat .env*'`, `echo .env* | xargs cat`) is seen. This is the only check that can answer for a pattern at all, since `.env*` matches no protected literal. Whether a word is matched against filenames is decided per character, so a quoted metacharacter names a file instead (`{".env*",x}`). A redirection is read by the rule the shell uses — it opens its target only where that target expands to exactly one word, and is refused as an ambiguous redirect otherwise (`> "{.env,}"{,}`, `> {.env,other}`), while a word that can still disappear, an unset variable or a pattern under `nullglob`, leaves the count unknowable and keeps every candidate | Matching is against generated examples of each protected pattern, not against the filesystem, so a protected pattern whose examples do not represent every real name it covers can leave a matching file unnamed. Bounded expansion refuses rather than enumerates when a glob is too broad to expand. |
 | Encoding, case variation, traversal, or symbolic-link alias | Single percent decode, case-insensitive protected matching, canonical resolution for existing paths, traversal/repository escape rejection | Filesystem races and code executing outside observed tool paths require an OS boundary. |
+| Local image path introduced through chat or extension input | Auto-attachment resolves the canonical target through the same project and `additionalReadRoots` grants as document intake, checks both the requested symlink location and resolved target against protected paths, preserves capability read scope, sniffs image bytes, and opens the inspected device/inode with no-follow semantics before attaching | A deliberately broad `additionalReadRoots` grant exposes every supported image under that root. Processes running as the same OS account and files modified in place remain outside this application-level boundary. |
+| Context index built with weaker or stale path rules | CLI and runtime share one resolved exclusion policy covering base policy, adapter inheritance, protected, shell-protected, and read-only paths. Every index API, including status, requires an explicit exclusion list and fails closed when it is omitted. A versioned exclusion digest forces rebuild on policy drift; search/pack filter candidates again at read time, and source-shaped symlinks or canonical paths outside the project are refused. Policy drift also rebuilds FTS, checkpoints WAL, and vacuums the database before clearing a retryable `purgePending` marker. | An explicit empty exclusion list remains available to intentional low-level callers. A policy migration may temporarily require roughly twice the database size in free space; interruption leaves the marker pending and retries on the next ensure. |
+| Source residue or cross-account access to the local context index | Context Engine directory mode is `0700`; SQLite database, WAL, and SHM are `0600`. SQLite core and FTS5 secure-delete are both enabled for ordinary updates, while policy migrations rebuild FTS and vacuum legacy free pages. | Context Engine is still an application-level cache, not an OS sandbox. A process running as the same OS account, filesystem races, backups, snapshots, or storage below the filesystem layer require separate OS/device controls. |
 | Shell glob, brace, redirection, wrapper, assignment, or command composition | Static Bash operand/action analysis with bounded expansion and regression cases; protected input is denied and external mutation is confirmation-gated. A path the analysis cannot resolve — literal text concatenated with a substitution, as in `.en$(echo v)` — is refused rather than matched on its literal half | Runtime-generated interpreter payloads cannot be fully understood by static parsing. Sensitive output redaction is a backstop, not containment. |
 | Secret returned in tool output | Shared contextual redaction across guarded text/results and synthetic recall benchmark | High-entropy, novel secret formats, or transformed output such as base64-encoded content can evade pattern-based redaction. Never intentionally print real secrets. |
 | Malicious project profile or relaxed capability lock | Trust-aware profile loading, deterministic lock digest, base-policy/source integrity, protected self-state, and fail-closed verification | An already trusted malicious repository can execute code through mechanisms outside the guard. |
 | External GitHub/HTTP/MCP/provider mutation | Direct and proxied action classification plus explicit operator confirmation, including guarded shell carriers | Provider semantics and new tool schemas can change; new integrations require policy and regression review. |
+| Repository MCP direct tool loses server attribution | Guard and doctor share the merged MCP view. Both session-level and effective per-server `directTools` selections fail closed when `toolPrefix: "none"` removes server identity; approved direct tools remain usable with `server` or `short` prefixes | A future adapter naming mode or config layer must be added to the shared MCP resolver before rollout. |
+| Read-only subagent receives mutation-capable tools | Packaged read-only roles carry explicit `read`, `grep`, `find`, `ls` allowlists; CI checks every `acceptanceRole: read-only` manifest, while all shell/edit/write capability remains on the explicit writer role | User/project overrides and a compromised external subagent runtime can replace the packaged contract; inspect effective runtime configuration when accepting third-party roles. |
 | Destructive local action | Exec-policy classification and explicit confirmation; protected paths remain denied in every permission profile. A target written as a command substitution is evaluated only where its body is one plain command with literal operands and a format this renderer reproduces exactly, and confirmed otherwise — a separator, a nested substitution, a redirection, a variable, quoting, an escape, a `printf` option, or a `printf` conversion whose result this does not reproduce (`*`, `%q`, `%b`, the numeric conversions, `%%`) all make the body unreadable here. A constant width or precision and format reuse are reproduced, so a target built from those is refused rather than confirmed, and the rendered output is read as a path candidate as well as the format's literal text and its arguments — a name assembled across a conversion (`.e%.1sv nv` is `.env`) appears in none of the pieces. Brace expansion, ranges included, is performed once per segment before anything reads it, so the rules, the legacy patterns, the nested-interpreter scan, the pipeline producers and the destructive checks all see the word list the shell would build rather than the text as typed; the expansion produces a token stream, so a command and its arguments assembled from one brace word (`{cat,.env}`) are read as both; quoting is tracked per character, so a word holding a quoted group beside an expanding one (`"{.env,}"{,}`) expands exactly as far as the shell expands it — and a target that is nothing but an unresolved parameter expansion is confirmed rather than permitted, since it can hold any value including root. The same holds for reads: a word that is only an unresolved parameter expansion is confirmed wherever the command opens files (`cat ${HOME:+.env}`), including across a pipe into an `xargs` that opens them (`echo $F \| xargs cat`), while a command substitution in that position is left to the nested scan that classifies the command inside it, and two expansions with nothing between them count as a name being assembled just as literal text beside one does. Brace expansion, parameter expansion and command substitution are performed once per segment, in the order a shell performs them, and every reader takes that one word list — so a name assembled by an expansion (`r$(printf %s m) -rf /`, `xa$(printf %s rgs)`, `$(printf %s ba)$(echo -n sh) -c '...'`) is the command it becomes rather than the text it was typed as. A name that still cannot be resolved is treated as an unknown command rather than a known-harmless one: it is enough to bring the destructive checks, the interpreter scan and the file-operand net into play, since `${X:+r}m -rf /` and `${X:+cat} ${X:+.env}` are those commands whenever the variable is set. Differential cases are generated rather than enumerated, over the cross product the defects live in — expansion form, position in the command, and reader — with each spelling placed in the command name, the operand, a flag's argument, a redirection target, a pipeline producer, an `xargs` consumer and an interpreter payload; the corpus fails if any generated spelling produced no word list, so a batch that dies early cannot pass as coverage, and it asserts in both directions so a check that answers for everything fails too | Confirmation is not isolation. A trusted process outside the observed tool path retains OS authority. A target produced by any other command is knowable only at run time, so it is gated by confirmation rather than refused. |
 | Forged verification result | Observed Bash result ledger, command hash, task-start ordering, exit-code and verify-command matching | Compromise of the trusted Pi/process environment is outside this evidence model. |
 | Mutable or substituted release source | Exact team tags, stable tag-to-commit resolution, release-commit binding in tag CI, annotated-tag requirement, add-on integrity checks, and documented tag ruleset requirement | Bootstrap helper installation still relies on GitHub tag immutability; repository administrators must prevent tag update/deletion. Signed provenance remains future work. |

package/docs/subagents-and-multiagent.md

@@ -253,7 +253,7 @@ Platform package exposes these package-level agents:
 | `piagent-scout` | bounded repo mapping | no |
 | `piagent-planner` | implementation plan + verify gates | no |
 | `piagent-worker` | single-writer implementation | yes |
-| `piagent-reviewer` | review diff/policy/tests/scope | review-first, edit only if asked |
+| `piagent-reviewer` | review diff/policy/tests/scope | no |
 | `piagent-oracle` | second opinion/risk challenge | no |
 
 Default rule:

package/docs/team-onboarding.md

@@ -9,7 +9,7 @@ Một thành viên mới không cần biết local path của maintainer. Luồn
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.8
+npm install -g --ignore-scripts @piagent/platform@1.2.10
 piagent-install --stable
 cd /path/to/project
 pi
@@ -43,7 +43,7 @@ Mặc định team dùng stable helper:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.8
+npm install -g --ignore-scripts @piagent/platform@1.2.10
 piagent-install --stable --dry-run
 piagent-install --stable
 ```

package/docs-site/architecture.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.8 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.10 docs</span>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />

package/docs-site/commands.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.8 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.10 docs</span>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />

package/docs-site/content/context-engine.html

@@ -6,7 +6,7 @@
     </article>
     <article class="card">
       <h3 id="local-index">Index local</h3>
-      <p>FTS5, symbol và import graph nằm trong <span class="inline-code">.pi/piagent-state/context-engine/</span>. Protected paths và secret files không được index.</p>
+      <p>FTS5, symbol và import graph nằm trong <span class="inline-code">.pi/piagent-state/context-engine/</span>. Storage chỉ cho OS account hiện tại; policy đổi sẽ retry FTS rebuild và VACUUM đến khi purge xong.</p>
     </article>
     <article class="card">
       <h3 id="ranked-context">Context có xếp hạng</h3>
@@ -27,6 +27,13 @@
   </div>
 </section>
 
+<section class="section">
+  <div class="callout">
+    <strong>Index có chứa source body</strong>
+    <p>Protected paths và secret files không được index. Directory dùng mode <span class="inline-code">0700</span>; database, WAL và SHM dùng <span class="inline-code">0600</span>. Refresh bình thường dùng SQLite core + FTS5 secure-delete. Full FTS rebuild và VACUUM chỉ chạy khi exclusion policy đổi hoặc một purge trước bị gián đoạn, không chạy trên mỗi prompt hay mỗi refresh.</p>
+  </div>
+</section>
+
 <section class="section">
   <div class="command-grid">
     <article class="command-card">

package/docs-site/content/security.html

@@ -33,6 +33,7 @@
     <ul>
       <li>Có thể bị ảnh hưởng bởi symlink, encoding, nested payload, shell expansion hoặc tool mới chưa được policy hoá.</li>
       <li>Redaction là backstop giảm rò rỉ, không phải giấy phép để đưa secret thật vào prompt/output.</li>
+      <li>Context index là local cache có source body: mode owner-only giảm cross-account access, nhưng process chạy cùng OS account vẫn cần được tin cậy.</li>
       <li>Workload không tin cậy cần container/VM với giới hạn filesystem, process, network và credential.</li>
     </ul>
   </div>

package/docs-site/context-engine.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.8 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.10 docs</span>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
@@ -101,7 +101,7 @@
     </article>
     <article class="card">
       <h3 id="local-index">Index local</h3>
-      <p>FTS5, symbol và import graph nằm trong <span class="inline-code">.pi/piagent-state/context-engine/</span>. Protected paths và secret files không được index.</p>
+      <p>FTS5, symbol và import graph nằm trong <span class="inline-code">.pi/piagent-state/context-engine/</span>. Storage chỉ cho OS account hiện tại; policy đổi sẽ retry FTS rebuild và VACUUM đến khi purge xong.</p>
     </article>
     <article class="card">
       <h3 id="ranked-context">Context có xếp hạng</h3>
@@ -122,6 +122,13 @@
   </div>
 </section>
 
+<section class="section">
+  <div class="callout">
+    <strong>Index có chứa source body</strong>
+    <p>Protected paths và secret files không được index. Directory dùng mode <span class="inline-code">0700</span>; database, WAL và SHM dùng <span class="inline-code">0600</span>. Refresh bình thường dùng SQLite core + FTS5 secure-delete. Full FTS rebuild và VACUUM chỉ chạy khi exclusion policy đổi hoặc một purge trước bị gián đoạn, không chạy trên mỗi prompt hay mỗi refresh.</p>
+  </div>
+</section>
+
 <section class="section">
   <div class="command-grid">
     <article class="command-card">

package/docs-site/index.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.8 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.10 docs</span>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />

package/docs-site/mcp-approval.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.8 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.10 docs</span>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />