@piagent/platform 1.2.9 → 1.2.11

package/docs/usage-observability.md

@@ -131,6 +131,11 @@ Hoặc đổi tên phiên đang mở trong Pi:
 
 Alias ngắn `/setname ABC-123 Short task name` vẫn chạy. Nếu tắt nhầm terminal/app, vào lại project rồi dùng `pi --continue` cho phiên gần nhất, hoặc `pi --resume` để chọn theo session name/id. Trong Pi có thể gõ `/resume` để xem reminder ngắn.
 
+Task Contract v2 lưu cả `sessionId`, `sessionName`, `taskId` và `taskRunId`, nên
+Agent Watch/report có thể map usage vào đúng attempt kể cả session đã resume hoặc
+được đổi tên sau khi bắt đầu. Một session không được tái sử dụng cho task khác;
+retry dùng session mới và giữ liên kết qua cùng `taskId`.
+
 Mặc định history mode **bao gồm subagent session files** vì đó là usage thật của máy. Dùng `--no-subagents` khi chỉ muốn parent/main sessions.
 
 Format hỗ trợ:
@@ -169,18 +174,20 @@ Nếu user paste full mandatory-flow boilerplate, platform input guard sẽ coll
 
 Tool output dài cũng bị compact theo cùng triết lý: chat giữ preview, audit/report giữ capture local. Nếu verify fail và preview chưa đủ, chạy lại command targeted hơn thay vì đổ full log vào session.
 
+Trace, observed-bash, telemetry và capture đều bounded và owner-only. Rotation
+không cần UI polling realtime, dùng lock liên process để nhiều Pi session/subagent
+không ghi đè nhau. Capture mặc định giữ tối đa 500 file, 128 MiB và 30 ngày.
+
 ## Khi nào ghi benchmark
 
 Sau một task cần so sánh workflow/model bằng số liệu:
 
 ```bash
-bash scripts/quality-benchmark.sh /path/to/project --record \
-  --scenario bounded-source-fix \
-  --surface pi \
-  --result pass \
-  --tokens <total-from-piagent-usage> \
-  --cost <cost-from-piagent-usage> \
-  --verify "<verify-command>"
+piagent-benchmark --dry-run
+piagent-benchmark --model <provider/model> --thinking high
 ```
 
-Không dùng ước lượng ký tự để claim tiết kiệm token. Dùng `/session`, RPC `get_session_stats`, hoặc `piagent-usage`.
+Automatic runner lấy exact usage từ session JSONL và so median trên các cặp cùng
+pass. Không dùng ước lượng ký tự để claim tiết kiệm token. Với một task ngoài
+suite, vẫn dùng `/session`, RPC `get_session_stats`, `piagent-usage`, hoặc legacy
+`piagent-benchmark <project> --record ...`.

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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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/runtime.html

@@ -25,6 +25,16 @@ piagent-install --version vX.Y.Z --resolve-tag</code></pre>
       <header><span>Doctor</span><button class="clip-btn" data-clip="piagent-doctor /path/to/project">Lấy lệnh</button></header>
       <pre><code>piagent-doctor /path/to/project</code></pre>
     </article>
+    <article class="command-card">
+      <header><span>Automatic benchmark</span><button class="clip-btn" data-clip="piagent-benchmark --dry-run&#10;piagent-benchmark">Lấy lệnh</button></header>
+      <pre><code>piagent-benchmark --dry-run
+piagent-benchmark</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Compare codex-cli</span><button class="clip-btn" data-clip="piagent-benchmark --surfaces piagent,codex-cli --model openai-codex/gpt-5.6-sol --thinking xhigh">Lấy lệnh</button></header>
+      <pre><code>piagent-benchmark --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol --thinking xhigh</code></pre>
+    </article>
     <article class="command-card">
       <header><span>Trusted run</span><button class="clip-btn" data-clip="piagent-auto --full-access -p &quot;Run the trusted local benchmark suite.&quot;">Lấy lệnh</button></header>
       <pre><code>piagent-auto --read-only -p "Scout payment mapping. Do not edit source."

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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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-auth.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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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-servers.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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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.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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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/permissions.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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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/profiles.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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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/quickstart.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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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/runtime.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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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" />
@@ -120,6 +120,16 @@ piagent-install --version vX.Y.Z --resolve-tag</code></pre>
       <header><span>Doctor</span><button class="clip-btn" data-clip="piagent-doctor /path/to/project">Lấy lệnh</button></header>
       <pre><code>piagent-doctor /path/to/project</code></pre>
     </article>
+    <article class="command-card">
+      <header><span>Automatic benchmark</span><button class="clip-btn" data-clip="piagent-benchmark --dry-run&#10;piagent-benchmark">Lấy lệnh</button></header>
+      <pre><code>piagent-benchmark --dry-run
+piagent-benchmark</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Compare codex-cli</span><button class="clip-btn" data-clip="piagent-benchmark --surfaces piagent,codex-cli --model openai-codex/gpt-5.6-sol --thinking xhigh">Lấy lệnh</button></header>
+      <pre><code>piagent-benchmark --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol --thinking xhigh</code></pre>
+    </article>
     <article class="command-card">
       <header><span>Trusted run</span><button class="clip-btn" data-clip="piagent-auto --full-access -p &quot;Run the trusted local benchmark suite.&quot;">Lấy lệnh</button></header>
       <pre><code>piagent-auto --read-only -p "Scout payment mapping. Do not edit source."

package/docs-site/scope.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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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/security.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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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" />
@@ -128,6 +128,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/team.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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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/workflows.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.9 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.11 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/evals/fixtures/task-contract.invalid.json

@@ -1,4 +1,10 @@
 {
+  "schemaVersion": 2,
+  "taskRunId": "task-0001-20260731120000-a1b2c3d4e5",
+  "changeMode": "source-change",
+  "attempt": 4,
+  "maxAttempts": 3,
+  "previousAttempts": [],
   "summary": "Replace with one-sentence task outcome.",
   "riskLane": "normal",
   "expectedOutput": "Replace with exact artifact or behavior expected.",
@@ -16,6 +22,7 @@
   "contextManifest": [],
   "memoryCitations": [],
   "mcpCapabilities": [],
+  "verifyGroup": "source",
   "verifyCommands": [
     "Replace with verify command."
   ],
@@ -65,9 +72,16 @@
       "watchdog": "Use a strong model only for final risk review, security, release, or high-impact changes."
     }
   },
+  "baselineChangedFiles": [],
+  "baselineFileDigests": {},
+  "observedChangedFiles": [],
+  "finalWorkingTreeFiles": [],
+  "finalFileDigests": {},
   "changedFiles": [],
   "verifyEvidence": [],
   "trace": {
     "outcome": "pending"
-  }
+  },
+  "createdAt": "2026-07-31T12:00:00.000Z",
+  "updatedAt": "2026-07-31T12:00:00.000Z"
 }

package/evals/fixtures/task-contract.valid.json

@@ -1,5 +1,13 @@
 {
-  "taskId": "TASK-0001",
+  "schemaVersion": 2,
+  "taskRunId": "task-0001-20260731120000-a1b2c3d4e5",
+  "taskId": "task-0001",
+  "sessionId": "pi-session-example",
+  "sessionName": "TASK-0001 Example task",
+  "changeMode": "source-change",
+  "attempt": 1,
+  "maxAttempts": 3,
+  "previousAttempts": [],
   "summary": "Replace with one-sentence task outcome.",
   "riskLane": "normal",
   "expectedOutput": "Replace with exact artifact or behavior expected.",
@@ -17,6 +25,7 @@
   "contextManifest": [],
   "memoryCitations": [],
   "mcpCapabilities": [],
+  "verifyGroup": "source",
   "verifyCommands": [
     "Replace with verify command."
   ],
@@ -66,9 +75,16 @@
       "watchdog": "Use a strong model only for final risk review, security, release, or high-impact changes."
     }
   },
+  "baselineChangedFiles": [],
+  "baselineFileDigests": {},
+  "observedChangedFiles": [],
+  "finalWorkingTreeFiles": [],
+  "finalFileDigests": {},
   "changedFiles": [],
   "verifyEvidence": [],
   "trace": {
     "outcome": "pending"
-  }
+  },
+  "createdAt": "2026-07-31T12:00:00.000Z",
+  "updatedAt": "2026-07-31T12:00:00.000Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.2.9",
+  "version": "1.2.11",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -30,6 +30,7 @@
     "SECURITY.md",
     ".gitattributes",
     "adapters/",
+    "benchmarks/",
     "catalog/",
     "docs/",
     "!docs/journals/",
@@ -113,7 +114,7 @@
     "install-global": "bash scripts/install-global.sh",
     "init-project": "bash scripts/init-project.sh",
     "doctor": "bash scripts/team-doctor.sh",
-    "benchmark": "bash scripts/quality-benchmark.sh",
+    "benchmark": "node scripts/benchmark-runner.mjs",
     "benchmark:redaction": "node scripts/redaction-benchmark.mjs",
     "audit:runtime": "bash scripts/audit-runtime-host.sh",
     "release:identity": "node scripts/verify-release-identity.mjs",

package/packages/piagent-core/README.md

@@ -6,13 +6,23 @@ Shared Pi package for reusable project workflows.
 
 - `extensions/piagent-guard.ts`: runtime guard tools and policy hooks.
 - `prompts/*.md`: workflow aliases that intentionally launch an agent turn.
-- `skills/piagent-ops/SKILL.md`: operating guidance for implementation tasks.
+- `skills/piagent-ops/SKILL.md`: operator-invoked reference for manual intake, recovery, and high-risk controls; routine runtime-managed tasks do not advertise or load it.
 - `skills/piagent-source-cache/`: local cache for user-provided external source repositories.
 - `subagents/*.md`: piagent roles for `pi-subagents`.
+- `benchmark/benchmark-core.js`: deterministic suite validation, evidence scoring, usage comparison, and report rendering for `piagent-benchmark`.
 - `policies/base-policy.json`: default runtime policy, including protected path and shell protected path defaults.
 - input hook support for local screenshot/image paths pasted into chat; supported images are attached as `[image1]`, `[image2]`, ...
 - compact tool-result rendering: oversized redacted output is previewed in Pi and captured under `.pi/piagent-state/tool-results/` for offline audit/reporting.
-- local Context Engine v2: incremental FTS5/symbol/import index, hybrid retrieval, token-budgeted packs, test-impact mapping, dynamic Piagent tools, and Agent Watch compatible telemetry.
+- local Context Engine v2: incremental FTS5/symbol/import index, hybrid retrieval, token-budgeted packs, bounded current-turn source/test snapshots, test-impact mapping, dynamic Piagent tools, and Agent Watch compatible telemetry.
+
+The root package exposes `piagent-benchmark` for an automatic paired Piagent
+steady-state benchmark against Raw Pi or the `codex-cli` surface. Treatment
+onboarding/context preparation happens before measured model usage;
+post-baseline mutations remain scope violations. Codex runs through a strict
+streaming JSONL adapter and defaults to controlled ephemeral execution with an
+isolated temporary Codex home. Run
+`piagent-benchmark --dry-run` before starting billed model sessions; see
+`docs/quality-benchmark.md` for score and verdict rules.
 
 ## Trusted run wrapper
 
@@ -70,12 +80,20 @@ Legacy aliases still work: `/permission-status`, `/read-only`, `/workspace-write
 - `piagent_profile_tech_context_record`
 - `piagent_project_onboarding_record`
 - `piagent_task_start`
+- `piagent_task_progress`
 - `piagent_source_checkout`
 - `piagent_document_read` — reads `.md`/`.txt`/`.csv`/`.json`/`.yaml`/`.pdf`/`.docx` from the project or a granted `additionalReadRoots` directory; read-only, and `protectedPaths` still wins
 - `piagent_context_record`
 - `piagent_verify_record` — records verify evidence only after matching an observed bash tool result after task start
 - `piagent_trace_record`
 
+These tools are registered capabilities, not a per-task call sequence. Runtime
+starts bounded source tasks directly and exposes no Piagent management schema
+to the model. Broad, high-risk, or ambiguous intake activates
+`piagent_task_start`; lifecycle hooks still collect context, changes,
+current-tree verification, trace and final-gate evidence. Diagnostic/recovery
+groups load only when requested.
+
 ## Runtime commands and workflow recipes
 
 - `/commands`: runtime menu/help for terminal, Pi, MCP, model, memory, session, context, permission, and subagent commands.
@@ -132,6 +150,7 @@ If no trusted profile is available, the extension still applies baseline secret
 Runtime task tools write local state to:
 
 - `.pi/piagent-state/tasks/*.json`
+- `.pi/piagent-state/session-tasks/*.json`
 - `.pi/project-context.md`
 - `.pi/tech-stack.json`
 - `.pi/tech-context/*.json`
@@ -147,10 +166,30 @@ Runtime task tools write local state to:
 
 Project-local state belongs in `.pi/.gitignore`.
 
-Passing final gates require an observed exit `0` command that exactly matches one entry in `task.verifyCommands`. Other observed commands are traceable but advisory.
+Task files use schema v2 and bind one unique `taskRunId` to one Pi `sessionId`.
+They record attempt/max-attempt history, dependency-safe work-plan progress,
+Git baseline/final digests, observed changes, all exact verify results and final
+trace. A terminal task is immutable; retry starts in a fresh session and carries
+the prior failure/ruled-out evidence. Legacy v1 state is migrated and archived
+without requiring project onboarding again.
+
+Local state directories are owner-only. Task state, context telemetry, trace,
+bash evidence and captures refuse ancestor symlinks out of the project. JSONL
+files rotate under a cross-process lock; compacted tool captures are pruned by
+age, count and aggregate bytes.
+
+The Context Engine SQLite index contains allowed source bodies. Its directory is
+kept at mode `0700`, with database/WAL/SHM at `0600`; core and FTS5 secure-delete
+cover normal refreshes, while exclusion-policy changes trigger a retryable FTS
+rebuild and database vacuum before the new policy is considered clean.
+
+Passing source final gates require an observed exit `0` result for every
+meaningful entry in `task.verifyCommands`. Other observed commands are traceable
+but advisory. Declared changed files must also differ from the task baseline,
+match observed tool results and remain inside `task.scope`.
 
 Raw path-like tool access to protected paths is blocked before execution. This includes Pi built-ins (`read`, `write`, `edit`, `grep`, `find`, `ls`) and custom/MCP tools with nested path-like strings, arrays, or `file://` URIs. Path-like strings are percent-decoded once, and input nesting above `MAX_TOOL_INPUT_INSPECTION_DEPTH=32` fails closed. Known content fields such as `content`, `query`, `pattern`, `text`, and `command` are excluded from generic extraction. `grep.glob` and `find.pattern` are checked when they explicitly target protected paths, while broad `grep`, `find`, and `ls` results are filtered so protected content lines or path metadata are redacted before reaching the model.
 
 Raw `bash` access to protected paths is blocked through shell path extraction. `.pi/piagent-state/**` and `.pi/piagent-profile.json` are self-protected; use `piagent_context` and piagent task tools for governed access.
 
-The input hook also detects local image paths in chat prompts. Supported formats are `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, and `.bmp`, including macOS screenshot paths under `/var/folders/...`. Up to 4 images are attached per input, with an 8 MB per-image cap. Oversized images should be read through Pi's `read` tool so Pi can resize them.
+The input hook also detects local image paths in chat prompts. Supported formats are `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, and `.bmp`. The canonical target must be inside the project or a directory granted through `additionalReadRoots`/`PIAGENT_ADDITIONAL_READ_ROOTS`; protected paths and project files outside the resolved filesystem read scope remain blocked. File bytes are sniffed before attachment, and the checked file identity must still match when opened. Up to 4 images are attached per input, with an 8 MB per-image cap. Oversized images should be read through Pi's `read` tool so Pi can resize them.