@piagent/platform 1.2.9 → 1.2.11

package/packages/piagent-core/extensions/context-engine.js

@@ -8,7 +8,9 @@ import {
   contextIndexExcludePolicyVersion,
   normalizeContextIndexExcludePatterns
 } from "./context-index-policy.js";
-import { matchesProtectedPath } from "./policy-core.js";
+import { matchesAnyPath, matchesProtectedPath } from "./policy-core.js";
+import { appendJsonlBounded, readJsonlTail } from "./state-retention.js";
+import { ensurePrivateStateDirectory, resolveLocalStatePath } from "./local-state-path.js";
 
 const INDEX_SCHEMA_VERSION = 2;
 const TELEMETRY_SCHEMA_VERSION = 1;
@@ -18,6 +20,7 @@ const DEFAULT_MAX_FILES = 8_000;
 const DEFAULT_PACK_TOKENS = 6_000;
 const MAX_TELEMETRY_EVENTS = 50_000;
 const MAX_TELEMETRY_READ_BYTES = 32 * 1024 * 1024;
+const MAX_TELEMETRY_FILE_BYTES = 32 * 1024 * 1024;
 const SOURCE_EXTENSIONS = new Set([
   ".c", ".cc", ".cpp", ".cs", ".css", ".dart", ".ex", ".exs", ".go", ".h", ".hpp",
   ".html", ".java", ".js", ".jsx", ".kt", ".kts", ".lua", ".m", ".md", ".mdx",
@@ -47,7 +50,8 @@ const STOP_TERMS = new Set([
   "about", "after", "agent", "before", "build", "change", "check", "code", "could", "file",
   "from", "have", "into", "just", "make", "need", "please", "project", "should", "task",
   "that", "them", "then", "there", "these", "this", "through", "update", "using", "want",
-  "what", "when", "where", "which", "with", "would"
+  "what", "when", "where", "which", "with", "would",
+  "anh", "cho", "cua", "em", "giup", "lam", "minh", "muon", "nay", "trong", "voi"
 ]);
 
 let sqliteModulePromise;
@@ -79,7 +83,17 @@ function requireExplicitExcludePatterns(options, operation) {
 }
 
 export function estimateContextTokens(value) {
-  return Math.max(0, Math.ceil(String(value ?? "").length / 4));
+  const text = String(value ?? "");
+  let asciiChars = 0;
+  let nonAsciiBytes = 0;
+  for (const character of text) {
+    if (character.codePointAt(0) <= 0x7f) asciiChars += 1;
+    else nonAsciiBytes += Buffer.byteLength(character, "utf8");
+  }
+  // ASCII prose/code averages close to four characters per token. UTF-8 text
+  // is estimated more conservatively so Vietnamese, CJK, and emoji packs do not
+  // silently exceed the provider budget.
+  return Math.max(0, Math.ceil(asciiChars / 4 + nonAsciiBytes / 2.5));
 }
 
 export function contextEnginePaths(cwd) {
@@ -92,6 +106,21 @@ export function contextEnginePaths(cwd) {
   };
 }
 
+function hardenContextDatabaseArtifacts(cwd) {
+  const database = resolveLocalStatePath(cwd, contextEnginePaths(cwd).database, { label: "Context index database" });
+  for (const artifact of [database, `${database}-wal`, `${database}-shm`]) {
+    try {
+      const stat = fs.lstatSync(artifact);
+      if (!stat.isFile()) {
+        throw new Error(`Context index storage path must be a regular file: ${artifact}`);
+      }
+      fs.chmodSync(artifact, 0o600);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+  }
+}
+
 async function loadSqlite() {
   if (!sqliteModulePromise) {
     sqliteModulePromise = (async () => {
@@ -116,54 +145,91 @@ async function loadSqlite() {
 
 async function openDatabase(cwd, { create = true } = {}) {
   const paths = contextEnginePaths(cwd);
-  if (!create && !fs.existsSync(paths.database)) return undefined;
-  fs.mkdirSync(paths.root, { recursive: true });
+  const database = resolveLocalStatePath(cwd, paths.database, { label: "Context index database" });
+  if (!create && !fs.existsSync(database)) return undefined;
+  if (create) ensurePrivateStateDirectory(cwd, paths.root, "Context index storage root");
+  else {
+    const existingRoot = resolveLocalStatePath(cwd, paths.root, { label: "Context index storage root", kind: "directory" });
+    try {
+      fs.chmodSync(existingRoot, 0o700);
+    } catch {
+      // Best effort on filesystems that do not expose POSIX modes.
+    }
+  }
+  hardenContextDatabaseArtifacts(cwd);
+  const descriptor = fs.openSync(
+    database,
+    fs.constants.O_RDWR
+      | (create ? fs.constants.O_CREAT : 0)
+      | (fs.constants.O_NOFOLLOW ?? 0),
+    0o600
+  );
+  try {
+    fs.fchmodSync(descriptor, 0o600);
+  } finally {
+    fs.closeSync(descriptor);
+  }
   const { DatabaseSync } = await loadSqlite();
-  const db = new DatabaseSync(paths.database);
-  db.exec(`
-    PRAGMA journal_mode = WAL;
-    PRAGMA synchronous = NORMAL;
-    PRAGMA foreign_keys = ON;
-    CREATE TABLE IF NOT EXISTS metadata (
-      key TEXT PRIMARY KEY,
-      value TEXT NOT NULL
-    );
-    CREATE TABLE IF NOT EXISTS files (
-      path TEXT PRIMARY KEY,
-      hash TEXT NOT NULL,
-      bytes INTEGER NOT NULL,
-      mtime_ms REAL NOT NULL,
-      language TEXT NOT NULL,
-      indexed_at TEXT NOT NULL
-    );
-    CREATE TABLE IF NOT EXISTS symbols (
-      id INTEGER PRIMARY KEY,
-      file_path TEXT NOT NULL REFERENCES files(path) ON DELETE CASCADE,
-      name TEXT NOT NULL,
-      kind TEXT NOT NULL,
-      line INTEGER NOT NULL,
-      end_line INTEGER NOT NULL,
-      signature TEXT NOT NULL
-    );
-    CREATE INDEX IF NOT EXISTS symbols_name_idx ON symbols(name);
-    CREATE INDEX IF NOT EXISTS symbols_file_idx ON symbols(file_path);
-    CREATE TABLE IF NOT EXISTS imports (
-      id INTEGER PRIMARY KEY,
-      file_path TEXT NOT NULL REFERENCES files(path) ON DELETE CASCADE,
-      specifier TEXT NOT NULL,
-      target_path TEXT,
-      line INTEGER NOT NULL
-    );
-    CREATE INDEX IF NOT EXISTS imports_file_idx ON imports(file_path);
-    CREATE INDEX IF NOT EXISTS imports_target_idx ON imports(target_path);
-    CREATE VIRTUAL TABLE IF NOT EXISTS file_fts USING fts5(
-      path UNINDEXED,
-      body,
-      symbol_names,
-      tokenize = 'unicode61 remove_diacritics 2'
-    );
-  `);
-  return db;
+  const db = new DatabaseSync(database);
+  try {
+    db.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA synchronous = NORMAL;
+      PRAGMA foreign_keys = ON;
+      PRAGMA secure_delete = ON;
+      CREATE TABLE IF NOT EXISTS metadata (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS files (
+        path TEXT PRIMARY KEY,
+        hash TEXT NOT NULL,
+        bytes INTEGER NOT NULL,
+        mtime_ms REAL NOT NULL,
+        language TEXT NOT NULL,
+        indexed_at TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS symbols (
+        id INTEGER PRIMARY KEY,
+        file_path TEXT NOT NULL REFERENCES files(path) ON DELETE CASCADE,
+        name TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        line INTEGER NOT NULL,
+        end_line INTEGER NOT NULL,
+        signature TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS symbols_name_idx ON symbols(name);
+      CREATE INDEX IF NOT EXISTS symbols_file_idx ON symbols(file_path);
+      CREATE TABLE IF NOT EXISTS imports (
+        id INTEGER PRIMARY KEY,
+        file_path TEXT NOT NULL REFERENCES files(path) ON DELETE CASCADE,
+        specifier TEXT NOT NULL,
+        target_path TEXT,
+        line INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS imports_file_idx ON imports(file_path);
+      CREATE INDEX IF NOT EXISTS imports_target_idx ON imports(target_path);
+      CREATE VIRTUAL TABLE IF NOT EXISTS file_fts USING fts5(
+        path UNINDEXED,
+        body,
+        symbol_names,
+        tokenize = 'unicode61 remove_diacritics 2'
+      );
+    `);
+    const ftsSecureDelete = db.prepare(`
+      SELECT v
+      FROM file_fts_config
+      WHERE k = 'secure-delete'
+    `).get();
+    if (Number(ftsSecureDelete?.v) !== 1) {
+      db.exec("INSERT INTO file_fts(file_fts, rank) VALUES('secure-delete', 1)");
+    }
+    hardenContextDatabaseArtifacts(cwd);
+    return db;
+  } catch (error) {
+    db.close();
+    throw error;
+  }
 }
 
 function metadataMap(db) {
@@ -408,18 +474,30 @@ function resolveImportTarget(sourcePath, specifier, files) {
   return candidates.map(normalizeRelative).find((candidate) => files.has(candidate));
 }
 
+function foldSearchSignal(value) {
+  return String(value ?? "")
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .replace(/[đĐ]/g, (character) => character === "Đ" ? "D" : "d")
+    .toLowerCase();
+}
+
 function tokenizeQuery(query) {
   const expanded = String(query ?? "")
     .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
     .replaceAll("_", " ")
     .replaceAll("-", " ");
-  const terms = expanded.match(/[A-Za-z][A-Za-z0-9]{1,63}/g) ?? [];
-  return [...new Set(terms.map((term) => term.toLowerCase()).filter((term) => !STOP_TERMS.has(term)))].slice(0, 16);
+  const terms = expanded.match(/[\p{L}][\p{L}\p{N}]{1,63}/gu) ?? [];
+  return [...new Set(terms
+    .map((term) => term.toLowerCase())
+    .filter((term) => !STOP_TERMS.has(foldSearchSignal(term))))].slice(0, 16);
 }
 
 function queryPathCandidates(query) {
-  const values = String(query ?? "").match(/(?:^|[\s"'`(])((?:\.{0,2}\/)?[A-Za-z0-9_.@-]+(?:\/[A-Za-z0-9_.@-]+)+|[A-Za-z0-9_.@-]+\.[A-Za-z0-9]{1,8})(?=$|[\s"'`),:])/g) ?? [];
-  return values.map((value) => normalizeRelative(value.trim().replace(/^["'`(]+|["'`),:]+$/g, ""))).filter(Boolean);
+  const pattern = /(?:^|[\s"'`(])((?:\.{0,2}\/)?[\p{L}\p{N}_.@-]+(?:\/[\p{L}\p{N}_.@-]+)+|[\p{L}\p{N}_.@-]+\.[\p{L}\p{N}]{1,8}|\.[\p{L}\p{N}_@-]{1,32})(?=$|[\s"'`),:])/gu;
+  return [...String(query ?? "").matchAll(pattern)]
+    .map((match) => normalizeRelative(match[1]))
+    .filter(Boolean);
 }
 
 function ftsQuery(terms) {
@@ -441,18 +519,20 @@ function gitChangedFiles(cwd) {
 export function classifyContextTask(prompt) {
   const text = String(prompt ?? "").trim();
   const lower = text.toLowerCase();
+  const folded = foldSearchSignal(text);
   const paths = queryPathCandidates(text);
   const terms = tokenizeQuery(text);
   let workflow = "task";
   if (/^\/?(?:scout|review|plan|discuss)\b/.test(lower)) workflow = lower.match(/^\/?([a-z-]+)/)?.[1] ?? "task";
-  if (/\b(onboard|profile setup|first-read)\b/.test(lower)) workflow = "onboard";
-  if (/\b(commit|pull request|\bpr\b|release|publish|deploy)\b/.test(lower)) workflow = "release";
+  if (/\b(onboard|profile setup|first-read|cau hinh profile|khoi tao project)\b/.test(folded)) workflow = "onboard";
+  if (/\b(commit|pull request|pr|release|publish|deploy|phat hanh|trien khai)\b/.test(folded)) workflow = "release";
   const usageIntent = /^\/?(?:usage|session)\b/.test(lower)
     || /\b(?:show|check|view|report|current|session|how many)\b.{0,48}\b(?:usage|tokens?|cost|context stats|efficiency)\b/.test(lower)
-    || /\b(?:usage|tokens?|cost|context stats|efficiency)\b.{0,48}\b(?:show|check|view|report|current|session)\b/.test(lower);
+    || /\b(?:usage|tokens?|cost|context stats|efficiency)\b.{0,48}\b(?:show|check|view|report|current|session)\b/.test(lower)
+    || /\b(?:xem|kiem tra|bao cao|hien tai|phien)\b.{0,48}\b(?:usage|token|chi phi|context)\b/.test(folded);
   if (usageIntent) workflow = "usage";
-  const highRisk = /\b(auth|authorization|credential|database|deploy|encryption|migration|payment|permission|production|release|secret|security|token)\b/.test(lower);
-  const tiny = text.length < 220 && (paths.length > 0 || /\b(rename|typo|label|copy|one line|small)\b/.test(lower));
+  const highRisk = /\b(auth|authorization|credential|database|deploy|encryption|migration|payment|permission|production|release|secret|security|token|bao mat|phan quyen|xac thuc|du lieu|co so du lieu|thanh toan|ma hoa|trien khai|phat hanh)\b/.test(folded);
+  const tiny = text.length < 220 && (paths.length > 0 || /\b(rename|typo|label|copy|one line|small|doi ten|sua chu|nhan|mot dong|nho)\b/.test(folded));
   return {
     workflow,
     lane: highRisk ? "high-risk" : tiny ? "tiny" : "normal",
@@ -465,6 +545,7 @@ export function classifyContextTask(prompt) {
 
 export async function buildContextIndexV2(cwd, options = {}) {
   const excludePatterns = requireExplicitExcludePatterns(options, "buildContextIndexV2");
+  const excludeDigest = contextIndexExcludeDigest(excludePatterns);
   const startedAt = Date.now();
   const projectRoot = fs.realpathSync.native(cwd);
   const directoryCache = new Map();
@@ -473,7 +554,10 @@ export async function buildContextIndexV2(cwd, options = {}) {
   const listed = gitFileList(cwd) ?? walkedFileList(cwd, maxFiles);
   const candidates = listed.filter((file) => shouldIndexPath(file, { ...options, excludePatterns })).slice(0, maxFiles).sort();
   const db = await openDatabase(cwd);
+  const previousMetadata = metadataMap(db);
   const existing = new Map(db.prepare("SELECT path, hash, bytes, mtime_ms FROM files").all().map((row) => [row.path, row]));
+  const purgeStaleContent = Boolean(previousMetadata.builtAt || existing.size > 0)
+    && (previousMetadata.purgePending === "1" || previousMetadata.excludeDigest !== excludeDigest);
   const current = new Set();
   const currentHashes = new Map();
   const changed = [];
@@ -525,8 +609,10 @@ export async function buildContextIndexV2(cwd, options = {}) {
   }
 
   const removed = [...existing.keys()].filter((file) => !current.has(file));
-  db.exec("BEGIN IMMEDIATE");
+  let transactionOpen = false;
   try {
+    db.exec("BEGIN IMMEDIATE");
+    transactionOpen = true;
     const deleteFile = db.prepare("DELETE FROM files WHERE path = ?");
     const deleteFts = db.prepare("DELETE FROM file_fts WHERE path = ?");
     for (const relativePath of [...removed, ...changed.map((item) => item.relativePath)]) {
@@ -574,12 +660,28 @@ export async function buildContextIndexV2(cwd, options = {}) {
       importCount: counts.imports,
       maxFileBytes,
       excludePatterns: JSON.stringify(excludePatterns),
-      excludeDigest: contextIndexExcludeDigest(excludePatterns),
+      excludeDigest,
       excludePolicyVersion: contextIndexExcludePolicyVersion(),
+      purgePending: purgeStaleContent ? 1 : 0,
       skippedPaths: JSON.stringify(skippedPaths)
     });
     db.exec("COMMIT");
-    db.close();
+    transactionOpen = false;
+    if (purgeStaleContent) {
+      if (typeof options.onPurgeStart === "function") await options.onPurgeStart();
+      db.exec("INSERT INTO file_fts(file_fts) VALUES('rebuild')");
+      db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+      db.exec("VACUUM");
+      db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+      db.exec("BEGIN IMMEDIATE");
+      transactionOpen = true;
+      setMetadata(db, {
+        purgePending: 0,
+        purgedAt: nowIso()
+      });
+      db.exec("COMMIT");
+      transactionOpen = false;
+    }
     return {
       schemaVersion: INDEX_SCHEMA_VERSION,
       builtAt: indexedAt,
@@ -590,26 +692,26 @@ export async function buildContextIndexV2(cwd, options = {}) {
       removed: removed.length,
       skippedLarge,
       skippedBinary,
+      purgedStaleContent: purgeStaleContent,
       ...counts
     };
   } catch (error) {
-    db.exec("ROLLBACK");
-    db.close();
+    if (transactionOpen) db.exec("ROLLBACK");
     throw error;
+  } finally {
+    db.close();
+    hardenContextDatabaseArtifacts(cwd);
   }
 }
 
 export async function contextIndexV2Status(cwd, options = {}) {
+  const expectedExcludePatterns = requireExplicitExcludePatterns(options, "contextIndexV2Status");
+  const expectedExcludeDigest = contextIndexExcludeDigest(expectedExcludePatterns);
   const paths = contextEnginePaths(cwd);
   const projectRoot = fs.realpathSync.native(cwd);
   const directoryCache = new Map();
-  const expectedExcludePatterns = options.excludePatterns === undefined
-    ? undefined
-    : normalizeContextIndexExcludePatterns(options.excludePatterns);
-  const expectedExcludeDigest = expectedExcludePatterns
-    ? contextIndexExcludeDigest(expectedExcludePatterns)
-    : undefined;
-  if (!fs.existsSync(paths.database)) {
+  const database = resolveLocalStatePath(cwd, paths.database, { label: "Context index database" });
+  if (!fs.existsSync(database)) {
     return {
       schemaVersion: INDEX_SCHEMA_VERSION,
       exists: false,
@@ -617,6 +719,7 @@ export async function contextIndexV2Status(cwd, options = {}) {
       stale: false,
       policyStale: false,
       expectedExcludeDigest,
+      purgePending: false,
       warnings: ["index-v2 missing"]
     };
   }
@@ -628,20 +731,14 @@ export async function contextIndexV2Status(cwd, options = {}) {
     const symbols = Number(db.prepare("SELECT COUNT(*) count FROM symbols").get().count);
     const imports = Number(db.prepare("SELECT COUNT(*) count FROM imports").get().count);
     const indexedPaths = new Set(fileRows.map((row) => row.path));
-    let storedExcludePatterns = [];
-    try {
-      const parsed = JSON.parse(metadata.excludePatterns ?? "[]");
-      if (Array.isArray(parsed)) storedExcludePatterns = normalizeContextIndexExcludePatterns(parsed);
-    } catch {
-      storedExcludePatterns = [];
-    }
-    const activeExcludePatterns = expectedExcludePatterns ?? storedExcludePatterns;
     const storedExcludeDigest = metadata.excludeDigest;
-    const policyStale = expectedExcludeDigest !== undefined
-      && (typeof storedExcludeDigest !== "string" || storedExcludeDigest !== expectedExcludeDigest);
+    const purgePending = metadata.purgePending === "1";
+    const excludeDigestStale = typeof storedExcludeDigest !== "string"
+      || storedExcludeDigest !== expectedExcludeDigest;
+    const policyStale = purgePending || excludeDigestStale;
     const statChanged = [];
     for (const row of fileRows) {
-      if (!shouldIndexPath(row.path, { excludePatterns: activeExcludePatterns })) continue;
+      if (!shouldIndexPath(row.path, { excludePatterns: expectedExcludePatterns })) continue;
       const file = projectFileInfo(cwd, row.path, projectRoot, directoryCache);
       if (
         !file
@@ -660,11 +757,12 @@ export async function contextIndexV2Status(cwd, options = {}) {
     }
     const listed = gitFileList(cwd);
     const newlyVisible = listed
-      ? listed.filter((file) => !indexedPaths.has(file) && !skippedPaths.has(file) && shouldIndexPath(file, { excludePatterns: activeExcludePatterns }))
+      ? listed.filter((file) => !indexedPaths.has(file) && !skippedPaths.has(file) && shouldIndexPath(file, { excludePatterns: expectedExcludePatterns }))
       : [];
     const stalePaths = [...new Set([...statChanged, ...newlyVisible])];
     const warnings = [];
-    if (policyStale) warnings.push("context index exclusion policy changed");
+    if (purgePending) warnings.push("context index storage purge pending");
+    if (excludeDigestStale) warnings.push("context index exclusion policy changed");
     if (stalePaths.length > 0) warnings.push(`${stalePaths.length} changed file(s) since the last index build`);
     return {
       schemaVersion: Number(metadata.schemaVersion ?? INDEX_SCHEMA_VERSION),
@@ -676,6 +774,7 @@ export async function contextIndexV2Status(cwd, options = {}) {
       imports,
       stale: policyStale || stalePaths.length > 0,
       policyStale,
+      purgePending,
       excludePolicyVersion: metadata.excludePolicyVersion,
       excludeDigest: storedExcludeDigest,
       expectedExcludeDigest,
@@ -755,9 +854,9 @@ function personalizedPageRank(importRows, seeds, iterations = 8) {
 }
 
 function retrievalFeedback(cwd) {
-  const target = contextEnginePaths(cwd).telemetry;
   let signature = "missing";
   try {
+    const target = resolveLocalStatePath(cwd, contextEnginePaths(cwd).telemetry, { label: "Context telemetry" });
     const stat = fs.statSync(target);
     signature = `${stat.size}:${stat.mtimeMs}`;
   } catch {
@@ -958,27 +1057,39 @@ export async function buildContextPack(cwd, query, options = {}) {
   const excludePatterns = requireExplicitExcludePatterns(options, "buildContextPack");
   const budgetTokens = clampInteger(options.budgetTokens, DEFAULT_PACK_TOKENS, 200, 50_000);
   const includeCode = options.includeCode !== false;
+  if (options.includePatterns !== undefined && !Array.isArray(options.includePatterns)) {
+    throw new TypeError("buildContextPack includePatterns must be an array when provided");
+  }
+  const includePatterns = options.includePatterns === undefined
+    ? undefined
+    : [...new Set(options.includePatterns.map((value) => String(value).trim()).filter(Boolean))];
   const projectRoot = fs.realpathSync.native(cwd);
   const directoryCache = new Map();
   const search = await searchContextIndexV2(cwd, query, {
     limit: clampInteger(options.limit, 16, 1, 50),
     excludePatterns
   });
+  const rankedResults = includePatterns === undefined
+    ? search.results
+    : search.results.filter((result) => matchesAnyPath(result.path, includePatterns));
+  const confidence = rankedResults.length > 0 ? search.confidence : "none";
   const selected = [];
   const mapBudget = Math.min(1_200, Math.max(40, Math.trunc(budgetTokens * 0.2)));
   const mapLines = [];
-  for (const result of search.results) {
+  for (const result of rankedResults) {
     const symbolNames = result.symbols.slice(0, 5).map((symbol) => `${symbol.kind} ${symbol.name}`).join(", ");
     const line = `- ${result.path}${symbolNames ? `: ${symbolNames}` : ""} [${result.sources.join("+")}]`;
     const cost = estimateContextTokens(line);
     if (estimateContextTokens(mapLines.join("\n")) + cost > mapBudget) break;
     mapLines.push(line);
   }
-  const footer = "Use this as navigation evidence. Re-read current files before editing; index hits are advisory.";
+  const footer = options.currentSnapshot === true
+    ? "Current-turn source snapshot: content was read from current non-protected project files after index freshness checks. Use it for the first edit; re-read only when a needed region is absent or an edit reports a mismatch."
+    : "Use this as navigation evidence. Re-read current files before editing; index hits are advisory.";
   const renderHeader = () => [
       "Pi Context Pack v2",
       `queryHash: ${sha256(String(query)).slice(0, 12)}`,
-      `confidence: ${search.confidence}`,
+      `confidence: ${confidence}`,
       `index: ${search.status.files ?? 0} files / ${search.status.symbols ?? 0} symbols${search.status.stale ? " / stale" : ""}`,
       "",
       "Repository map:",
@@ -996,7 +1107,7 @@ export async function buildContextPack(cwd, query, options = {}) {
     header = renderHeader();
   }
 
-  for (const result of search.results) {
+  for (const result of rankedResults) {
     let text;
     try {
       const file = projectFileInfo(cwd, result.path, projectRoot, directoryCache);
@@ -1031,13 +1142,13 @@ export async function buildContextPack(cwd, query, options = {}) {
   const text = renderPack(selected);
   return {
     queryHash: sha256(String(query)),
-    confidence: search.confidence,
+    confidence,
     status: search.status,
-    candidates: search.results.length,
+    candidates: rankedResults.length,
     selected: selected.map(({ text: _text, ...item }) => item),
     estimatedTokens: estimateContextTokens(text),
-    finderRecommended: search.confidence === "none" || search.confidence === "low",
-    finderRequest: search.confidence === "none" || search.confidence === "low"
+    finderRecommended: confidence === "none" || confidence === "low",
+    finderRequest: confidence === "none" || confidence === "low"
       ? `Run one bounded read-only finder pass for: ${String(query).slice(0, 600)}. Return only paths, symbols, line ranges, evidence, and unknowns.`
       : undefined,
     text
@@ -1094,44 +1205,21 @@ export async function buildTestImpact(cwd, changedFiles = [], options = {}) {
 
 export function appendContextTelemetry(cwd, event) {
   const paths = contextEnginePaths(cwd);
-  fs.mkdirSync(paths.root, { recursive: true });
   const record = {
     schemaVersion: TELEMETRY_SCHEMA_VERSION,
     source: "piagent",
     recordedAt: nowIso(),
     ...event
   };
-  fs.appendFileSync(paths.telemetry, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+  appendJsonlBounded(paths.telemetry, record, { maxBytes: MAX_TELEMETRY_FILE_BYTES, mode: 0o600, projectRoot: cwd });
   return record;
 }
 
 export function readContextTelemetry(cwd, options = {}) {
   const target = contextEnginePaths(cwd).telemetry;
-  if (!fs.existsSync(target)) return [];
   const limit = clampInteger(options.limit, MAX_TELEMETRY_EVENTS, 1, MAX_TELEMETRY_EVENTS);
   const maxBytes = clampInteger(options.maxBytes, MAX_TELEMETRY_READ_BYTES, 64 * 1024, 256 * 1024 * 1024);
-  const stat = fs.statSync(target);
-  const start = Math.max(0, stat.size - maxBytes);
-  const length = stat.size - start;
-  const buffer = Buffer.allocUnsafe(length);
-  const descriptor = fs.openSync(target, "r");
-  try {
-    fs.readSync(descriptor, buffer, 0, length, start);
-  } finally {
-    fs.closeSync(descriptor);
-  }
-  let text = buffer.toString("utf8");
-  if (start > 0) text = text.slice(Math.max(0, text.indexOf("\n") + 1));
-  const lines = text.split(/\r?\n/).filter(Boolean);
-  const events = [];
-  for (const line of lines.slice(-limit)) {
-    try {
-      events.push(JSON.parse(line));
-    } catch {
-      // Ignore one incomplete tail record after an interrupted append.
-    }
-  }
-  return events;
+  return readJsonlTail(target, { limit, maxBytes, projectRoot: cwd });
 }
 
 function ratio(numerator, denominator) {
@@ -1233,8 +1321,9 @@ export function buildContextEfficiencyReport(cwd, options = {}) {
     recommendations
   };
   const paths = contextEnginePaths(cwd);
-  fs.mkdirSync(paths.root, { recursive: true });
-  fs.writeFileSync(paths.report, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
+  ensurePrivateStateDirectory(cwd, paths.root, "Context report directory");
+  const reportPath = resolveLocalStatePath(cwd, paths.report, { label: "Context efficiency report" });
+  fs.writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
   return report;
 }
 

package/packages/piagent-core/extensions/context-index-policy.js

@@ -6,7 +6,7 @@ import { resolveProjectProfileDocument } from "../capabilities/project-profile.j
 
 const DEFAULT_CONTEXT_INDEX_PATH = ".pi/context-index.json";
 const CONTEXT_ENGINE_STATE_PATTERN = ".pi/piagent-state/**";
-const EXCLUDE_POLICY_VERSION = 1;
+const EXCLUDE_POLICY_VERSION = 2;
 
 function stringArray(value) {
   return Array.isArray(value)

package/packages/piagent-core/extensions/guard-types.ts

@@ -179,8 +179,20 @@ export type WorkPlanStep = {
   title: string;
   role: OrchestrationRole;
   mode: "read-only" | "single-writer" | "review";
-  status: "pending" | "in-progress" | "done" | "skipped";
+  status: "pending" | "in-progress" | "done" | "skipped" | "failed";
   dependsOn?: string[];
+  note?: string;
+  updatedAt?: string;
+};
+
+export type TaskAttemptSummary = {
+  taskRunId: string;
+  attempt: number;
+  outcome: "pending" | "completed" | "blocked" | "partial" | "failed";
+  failedAt?: "research" | "plan" | "execute" | "verify" | "review";
+  reason?: string;
+  ruledOut?: string;
+  recordedAt: string;
 };
 
 export type OrchestrationPolicySettings = {
@@ -250,9 +262,18 @@ export type ProjectOnboardingSnapshot = {
 };
 
 export type TaskContract = {
+  schemaVersion: 2;
+  taskRunId: string;
   taskId: string;
+  sessionId: string;
+  sessionName?: string;
+  changeMode: "source-change" | "read-only";
+  attempt: number;
+  maxAttempts: number;
+  previousAttempts: TaskAttemptSummary[];
   summary: string;
   riskLane: "tiny" | "normal" | "high-risk";
+  intakeMode?: "model" | "runtime";
   expectedOutput: string;
   acceptanceCriteria: string[];
   scope: string[];
@@ -262,9 +283,10 @@ export type TaskContract = {
   contextManifest: Array<{ path: string; reason: string }>;
   memoryCitations: Array<{ path: string; reason: string }>;
   mcpCapabilities: string[];
+  verifyGroup?: string;
   verifyCommands: string[];
-  workPlan?: WorkPlanStep[];
-  reviewLenses?: ReviewLens[];
+  workPlan: WorkPlanStep[];
+  reviewLenses: ReviewLens[];
   orchestration?: {
     mode: OrchestrationMode;
     subagents: "not-used" | "optional" | "used";
@@ -272,6 +294,11 @@ export type TaskContract = {
     fieldGuidePath?: string;
     modelRoles?: Record<"planner" | "worker" | "reviewer" | "watchdog", string>;
   };
+  baselineChangedFiles: string[];
+  baselineFileDigests: Record<string, string>;
+  observedChangedFiles: string[];
+  finalWorkingTreeFiles: string[];
+  finalFileDigests: Record<string, string>;
   changedFiles: string[];
   verifyEvidence: Array<{
     command: string;
@@ -282,6 +309,7 @@ export type TaskContract = {
     observedAt?: string;
     isError?: boolean;
     matchedProfileCommand?: boolean;
+    workingTreeDigest?: string;
   }>;
   trace: {
     outcome: "pending" | "completed" | "blocked" | "partial" | "failed";
@@ -289,6 +317,10 @@ export type TaskContract = {
     notes?: string;
     recordedAt?: string;
   };
+  failedAt?: "research" | "plan" | "execute" | "verify" | "review";
+  failureReason?: string;
+  ruledOut?: string;
+  migratedFromSchemaVersion?: number;
   createdAt: string;
   updatedAt: string;
 };