@piagent/platform 1.2.10 → 1.2.11

package/scripts/install-global.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 usage() {
   cat <<'USAGE'
 Usage:
-  scripts/install-global.sh [--stable|--dev|--local|--channel <stable|dev|local>] [--version <tag>] [--resolve-tag] [--package-source <source>] [--dry-run] [--with-mcp|--no-mcp] [--mcp-preset <preset>] [--with-subagents|--no-subagents] [--subagents-preset <preset>] [--with-web-access|--no-web-access] [--with-herdr] [--model-scope <preset>]
+  scripts/install-global.sh [--stable|--dev|--local|--channel <stable|dev|local>] [--version <tag>] [--resolve-tag] [--package-source <source>] [--dry-run] [--with-mcp|--no-mcp] [--mcp-preset <preset>] [--with-subagents|--no-subagents] [--subagents-preset <preset>] [--with-web-access|--no-web-access] [--with-herdr] [--model-scope <preset>|--no-model-scope]
 
 Purpose:
   Install the piagent Pi package into the current user's global Pi settings.

package/scripts/migrate-project-state.mjs

@@ -7,6 +7,15 @@
 // the caller confirms removal, so an interrupted run is always recoverable.
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
+import { migrateTaskState, taskStateMigrationStatus } from "../packages/piagent-core/extensions/task-state.js";
+
+const TASK_CONTRACT_MIGRATION_ID = "task-contract-v2";
+const AGENTS_MANAGED_START = "<!-- piagent-managed:start -->";
+const AGENTS_MANAGED_END = "<!-- piagent-managed:end -->";
+const LEGACY_GENERATED_AGENTS_HASHES = new Set([
+  "571fbf7967ce36a0c28fbc703551b6e8ad113933e8de0ba745c69b971eb73fb1"
+]);
 
 const RENAMES = [
   { from: ".pi/company-profile.json", to: ".pi/piagent-profile.json" },
@@ -71,6 +80,38 @@ function rewriteText(text) {
   return output;
 }
 
+function sha256(text) {
+  return crypto.createHash("sha256").update(text).digest("hex");
+}
+
+function managedAgentsBlock(text) {
+  const start = text.indexOf(AGENTS_MANAGED_START);
+  const endStart = text.indexOf(AGENTS_MANAGED_END, start + AGENTS_MANAGED_START.length);
+  if (start < 0 || endStart < 0) return undefined;
+  return { start, end: endStart + AGENTS_MANAGED_END.length };
+}
+
+function currentAgentsTemplate() {
+  try {
+    return fs.readFileSync(path.resolve(import.meta.dirname, "../templates/project/AGENTS.md"), "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+function migrateAgentsText(text) {
+  const renamed = rewriteText(text);
+  const template = currentAgentsTemplate();
+  if (!template) return renamed;
+  if (LEGACY_GENERATED_AGENTS_HASHES.has(sha256(renamed))) return template;
+
+  const existingBlock = managedAgentsBlock(renamed);
+  const templateBlock = managedAgentsBlock(template);
+  if (!existingBlock || !templateBlock) return renamed;
+  const replacement = template.slice(templateBlock.start, templateBlock.end);
+  return `${renamed.slice(0, existingBlock.start)}${replacement}${renamed.slice(existingBlock.end)}`;
+}
+
 function copyRecursive(from, to) {
   const stat = fs.lstatSync(from);
   if (stat.isSymbolicLink()) return { skipped: from, reason: "symlink" };
@@ -110,12 +151,19 @@ for (const { from, to } of RENAMES) {
 // that no longer exist.
 const agentsPath = path.join(projectPath, "AGENTS.md");
 let agentsNeedsRewrite = false;
+let migratedAgentsText;
 if (fs.existsSync(agentsPath)) {
   const text = fs.readFileSync(agentsPath, "utf8");
-  agentsNeedsRewrite = rewriteText(text) !== text;
+  migratedAgentsText = migrateAgentsText(text);
+  agentsNeedsRewrite = migratedAgentsText !== text;
 }
 
-const nothingToDo = planned.length === 0 && alreadyMigrated.length === 0 && !agentsNeedsRewrite;
+const taskMigrationBefore = taskStateMigrationStatus(projectPath);
+const nothingToDo = planned.length === 0
+  && alreadyMigrated.length === 0
+  && !agentsNeedsRewrite
+  && taskMigrationBefore.legacy === 0
+  && taskMigrationBefore.unreadable.length === 0;
 
 if (nothingToDo) {
   console.log(JSON.stringify({ ok: true, projectPath, migrated: false, reason: "already on the current layout" }, null, 2));
@@ -129,6 +177,8 @@ if (!apply) {
     dryRun: true,
     wouldRename: planned,
     wouldRewrite: agentsNeedsRewrite ? ["AGENTS.md"] : [],
+    wouldMigrateTaskContracts: taskMigrationBefore.legacy,
+    taskStateWarnings: taskMigrationBefore.unreadable,
     alreadyMigrated,
     next: alreadyMigrated.length > 0 && planned.length === 0
       ? "re-run with --apply --remove-old to delete the originals"
@@ -137,6 +187,17 @@ if (!apply) {
   process.exit(0);
 }
 
+if (taskMigrationBefore.unreadable.length > 0) {
+  console.log(JSON.stringify({
+    ok: false,
+    projectPath,
+    migrated: false,
+    taskStateWarnings: taskMigrationBefore.unreadable,
+    reason: "invalid task state requires manual recovery; no project files were changed"
+  }, null, 2));
+  process.exit(2);
+}
+
 const renamed = [];
 for (const { from, to } of planned) {
   const result = copyRecursive(path.join(projectPath, from), path.join(projectPath, to));
@@ -148,7 +209,36 @@ for (const { from, to } of planned) {
 }
 
 if (agentsNeedsRewrite) {
-  fs.writeFileSync(agentsPath, rewriteText(fs.readFileSync(agentsPath, "utf8")));
+  fs.writeFileSync(agentsPath, migratedAgentsText);
+}
+
+const taskMigration = migrateTaskState(projectPath);
+if (taskMigration.warnings.length > 0) {
+  console.log(JSON.stringify({
+    ok: false,
+    projectPath,
+    migrated: false,
+    renamed,
+    taskMigration,
+    reason: "invalid task state requires manual recovery; old project paths were preserved"
+  }, null, 2));
+  process.exit(2);
+}
+if (taskMigration.migrated > 0) {
+  const migrationFile = path.join(projectPath, ".pi", "piagent-state", "migrations.json");
+  let migrationState = { schemaVersion: 1, applied: [] };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(migrationFile, "utf8"));
+    if (parsed && typeof parsed === "object" && Array.isArray(parsed.applied)) migrationState = parsed;
+  } catch {
+    // Missing or unreadable migration metadata is reconstructed from applied work.
+  }
+  const applied = migrationState.applied.filter((entry) => entry?.id !== TASK_CONTRACT_MIGRATION_ID);
+  applied.push({ id: TASK_CONTRACT_MIGRATION_ID, appliedAt: new Date().toISOString(), migrated: taskMigration.migrated });
+  fs.mkdirSync(path.dirname(migrationFile), { recursive: true, mode: 0o700 });
+  const temporary = `${migrationFile}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify({ schemaVersion: 1, applied }, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, migrationFile);
 }
 
 const removed = [];
@@ -168,6 +258,7 @@ console.log(JSON.stringify({
   renamed,
   alreadyMigrated,
   rewrote: agentsNeedsRewrite ? ["AGENTS.md"] : [],
+  taskMigration,
   skipped,
   removedOld: removed,
   next: pendingCleanup > 0

package/scripts/piagent-cli.mjs

@@ -10,7 +10,7 @@ const scriptByCommand = {
   "piagent-uninstall": "scripts/uninstall-global.sh",
   "piagent-init": "scripts/init-project.sh",
   "piagent-doctor": "scripts/team-doctor.sh",
-  "piagent-benchmark": "scripts/quality-benchmark.sh",
+  "piagent-benchmark": "scripts/benchmark-runner.mjs",
   "piagent-usage": "scripts/pi-session-stats.sh",
   "piagent-models": "scripts/pi-model-catalog.sh",
   "piagent-model-scope": "scripts/configure-model-scope.sh",

package/scripts/update-global.mjs

@@ -213,6 +213,16 @@ function binForPrefix(prefix) {
   return process.platform === "win32" ? prefix : path.join(prefix, "bin");
 }
 
+function npmPrefixForInstalledHelper(root) {
+  if (path.basename(root) !== "platform") return undefined;
+  const scopeRoot = path.dirname(root);
+  if (path.basename(scopeRoot) !== "@piagent") return undefined;
+  const nodeModulesRoot = path.dirname(scopeRoot);
+  if (path.basename(nodeModulesRoot) !== "node_modules") return undefined;
+  const parent = path.dirname(nodeModulesRoot);
+  return path.basename(parent) === "lib" ? path.dirname(parent) : parent;
+}
+
 function prependPath(directory) {
   process.env.PATH = `${directory}${path.delimiter}${process.env.PATH ?? ""}`;
 }
@@ -231,6 +241,23 @@ function resolveNpmInstallTarget(options, needsGlobalInstall) {
 
   const defaultPrefix = configuredNpmPrefix();
   const defaultRoot = npmRoot(defaultPrefix);
+  const activePrefix = runningFromGlobalInstall() ? npmPrefixForInstalledHelper(platformRoot) : undefined;
+  if (
+    needsGlobalInstall
+    && activePrefix
+    && path.resolve(activePrefix) !== path.resolve(defaultPrefix ?? "")
+  ) {
+    const activeRoot = npmRoot(activePrefix);
+    if (activeRoot && canWriteOrCreate(activeRoot)) {
+      return {
+        prefix: activePrefix,
+        root: activeRoot,
+        bin: binForPrefix(activePrefix),
+        reason: "active-install",
+        configuredPrefix: defaultPrefix
+      };
+    }
+  }
   if (!needsGlobalInstall || (defaultRoot && canWriteOrCreate(defaultRoot))) {
     return { prefix: undefined, root: defaultRoot, bin: undefined, reason: "default" };
   }
@@ -289,15 +316,17 @@ function summarizeMigration(report, dryRun) {
   const rewrote = report.rewrote?.length ?? report.wouldRewrite?.length ?? 0;
   const wouldRename = report.wouldRename?.length ?? 0;
   const alreadyMigrated = report.alreadyMigrated?.length ?? 0;
+  const wouldMigrateTasks = report.wouldMigrateTaskContracts ?? 0;
+  const migratedTasks = report.taskMigration?.migrated ?? 0;
 
   if (dryRun) {
-    const planned = wouldRename + rewrote + alreadyMigrated;
+    const planned = wouldRename + rewrote + alreadyMigrated + wouldMigrateTasks;
     return planned > 0
-      ? `project migration: would update legacy layout (${wouldRename} rename, ${rewrote} rewrite, ${alreadyMigrated} already copied)`
+      ? `project migration: would update legacy layout (${wouldRename} rename, ${rewrote} rewrite, ${alreadyMigrated} already copied, ${wouldMigrateTasks} task contract)`
       : "project migration: already current";
   }
   if (report.migrated === false) return "project migration: already current";
-  return `project migration: applied (${renamed} rename, ${rewrote} rewrite, ${removed} old path removed)`;
+  return `project migration: applied (${renamed} rename, ${rewrote} rewrite, ${removed} old path removed, ${migratedTasks} task contract)`;
 }
 
 function runProjectMigration(project, options, activePlatformRoot) {
@@ -315,6 +344,8 @@ function runProjectMigration(project, options, activePlatformRoot) {
   if ((report.skipped?.length ?? 0) > 0) {
     fail(`project migration skipped protected entries: ${report.skipped.map((entry) => `${entry.path} (${entry.reason})`).join(", ")}`);
   }
+  const stateWarnings = [...(report.taskStateWarnings ?? []), ...(report.taskMigration?.warnings ?? [])];
+  if (stateWarnings.length > 0) fail(`project migration found invalid task state: ${stateWarnings.join("; ")}`);
   console.log(`  ${summarizeMigration(report, options.dryRun)}`);
 }
 
@@ -407,6 +438,8 @@ function main() {
   if (npmTarget.bin) prependPath(npmTarget.bin);
   if (npmTarget.reason === "user-prefix") {
     console.log(`  npm:     default global root is not writable (${npmTarget.blockedRoot ?? "unknown"}); using ${npmTarget.prefix}`);
+  } else if (npmTarget.reason === "active-install") {
+    console.log(`  npm:     active helper is installed under ${npmTarget.prefix}; keeping host and helper in that prefix`);
   } else if (npmTarget.reason === "explicit") {
     console.log(`  npm:     using explicit global prefix ${npmTarget.prefix}`);
   }

package/scripts/verify-local.sh

@@ -53,9 +53,12 @@ required_files=(
   "$ROOT/packages/piagent-core/extensions/piagent-guard.ts"
   "$ROOT/packages/piagent-core/extensions/context-engine.js"
   "$ROOT/packages/piagent-core/extensions/context-index-policy.js"
+  "$ROOT/packages/piagent-core/extensions/local-state-path.js"
   "$ROOT/packages/piagent-core/extensions/policy-core.js"
   "$ROOT/packages/piagent-core/extensions/redaction-core.js"
   "$ROOT/packages/piagent-core/extensions/runtime-evidence.js"
+  "$ROOT/packages/piagent-core/extensions/state-retention.js"
+  "$ROOT/packages/piagent-core/extensions/task-state.js"
   "$ROOT/packages/piagent-core/security/sensitive-data.js"
   "$ROOT/packages/piagent-core/capabilities/capability-core.js"
   "$ROOT/packages/piagent-core/prompts/platform-improve.md"
@@ -162,6 +165,7 @@ required_files=(
   "$ROOT/scripts/team-doctor.sh"
   "$ROOT/scripts/link-project.sh"
   "$ROOT/scripts/profile-doctor.sh"
+  "$ROOT/scripts/benchmark-runner.mjs"
   "$ROOT/scripts/quality-benchmark.sh"
   "$ROOT/scripts/runtime-policy-smoke.sh"
   "$ROOT/scripts/pi-session-stats.sh"
@@ -177,6 +181,9 @@ required_files=(
   "$ROOT/tests/capability-core.test.mjs"
   "$ROOT/tests/piagent-guard-integration.test.mjs"
   "$ROOT/tests/context-engine.test.mjs"
+  "$ROOT/tests/benchmark-core.test.mjs"
+  "$ROOT/tests/benchmark-runner.test.mjs"
+  "$ROOT/tests/benchmark-suite.test.mjs"
   "$ROOT/tests/workflow-prompts.test.mjs"
   "$ROOT/tests/install-global.test.mjs"
   "$ROOT/tests/package-distribution.test.mjs"
@@ -185,6 +192,8 @@ required_files=(
   "$ROOT/tests/redaction-core.test.mjs"
   "$ROOT/tests/runtime-evidence.test.mjs"
   "$ROOT/tests/golden-enforcement.test.mjs"
+  "$ROOT/packages/piagent-core/benchmark/benchmark-core.js"
+  "$ROOT/benchmarks/core-v1/suite.json"
   "$ROOT/tests/capability-sources.test.mjs"
   "$ROOT/packages/piagent-core/capabilities/capability-sources.js"
   "$ROOT/packages/piagent-core/extensions/guard-shell-analysis.ts"
@@ -473,6 +482,7 @@ require_documented "piagent-task-trace" "$ROOT/packages/piagent-core/extensions/
 require_documented "piagent-source-cache" "$ROOT/packages/piagent-core/skills" "$ROOT/templates/project/AGENTS.md"
 require_documented "piagent_source_checkout" "$ROOT/packages/piagent-core"
 require_documented "scripts/setup.sh" "$ROOT/README.md" "$ROOT/docs"
+require_documented "piagent-benchmark" "$ROOT/README.md" "$ROOT/docs"
 require_documented "quality-benchmark.sh" "$ROOT/README.md" "$ROOT/docs"
 require_documented "piagent-capabilities" "$ROOT/README.md" "$ROOT/docs/capability-packs.md"
 require_documented ".pi-subagents/" "$ROOT/.gitignore" "$ROOT/docs/subagents-and-multiagent.md" "$ROOT/docs/distribution-standard.md" "$ROOT/scripts/init-project.sh"
@@ -547,14 +557,19 @@ fi
 node --check "$ROOT/packages/piagent-core/extensions/piagent-guard.ts" >/dev/null
 node --check "$ROOT/packages/piagent-core/extensions/context-engine.js" >/dev/null
 node --check "$ROOT/packages/piagent-core/extensions/context-index-policy.js" >/dev/null
+node --check "$ROOT/packages/piagent-core/extensions/local-state-path.js" >/dev/null
 node --check "$ROOT/packages/piagent-core/extensions/policy-core.js" >/dev/null
 node --check "$ROOT/packages/piagent-core/extensions/redaction-core.js" >/dev/null
 node --check "$ROOT/packages/piagent-core/extensions/runtime-evidence.js" >/dev/null
+node --check "$ROOT/packages/piagent-core/extensions/state-retention.js" >/dev/null
+node --check "$ROOT/packages/piagent-core/extensions/task-state.js" >/dev/null
+node --check "$ROOT/packages/piagent-core/benchmark/benchmark-core.js" >/dev/null
 node --check "$ROOT/packages/piagent-core/security/sensitive-data.js" >/dev/null
 node --check "$ROOT/packages/piagent-core/capabilities/capability-core.js" >/dev/null
 node --check "$ROOT/packages/piagent-core/capabilities/capability-sources.js" >/dev/null
 node --check "$ROOT/scripts/capability-catalog.mjs" >/dev/null
 node --check "$ROOT/scripts/piagent-cli.mjs" >/dev/null
+node --check "$ROOT/scripts/benchmark-runner.mjs" >/dev/null
 node --check "$ROOT/scripts/context-engine.mjs" >/dev/null
 node --check "$ROOT/scripts/pi-usage-history.mjs" >/dev/null
 node --check "$ROOT/scripts/migrate-project-state.mjs" >/dev/null

package/templates/project/.pi/task-contract.template.json

@@ -1,7 +1,16 @@
 {
-  "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",
+  "intakeMode": "runtime",
   "expectedOutput": "Replace with exact artifact or behavior expected.",
   "acceptanceCriteria": [
     "Replace with pass/fail criterion."
@@ -17,6 +26,7 @@
   "contextManifest": [],
   "memoryCitations": [],
   "mcpCapabilities": [],
+  "verifyGroup": "source",
   "verifyCommands": [
     "Replace with verify command."
   ],
@@ -66,9 +76,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/templates/project/AGENTS.md

@@ -1,29 +1,19 @@
 # Project Agent Instructions
 
+<!-- piagent-managed:start -->
 ## Operating model
 
 This project uses Pi Agent Platform.
 
-Before implementation:
-
-1. Load `.pi/piagent-profile.json` with `piagent_context`.
-2. If `.pi/project-context.md` still says "Generated: not yet", run `/onboard run` after login/model selection before the first implementation task.
-3. Check `.pi/context-index.json` with `/context index` or `piagent_context_index_status` when available; use it only as an advisory navigation map.
-4. Read `.pi/project-context.md` and required context files listed in the profile; use `piagent_context_budget` for large files.
-5. Check project memory with `piagent_memory_status` when relevant; memory is advisory, source files are authoritative.
-6. Start source-changing work with `piagent_task_start`.
-7. Respect protected paths.
-8. Use `piagent_exec_policy_check` before high-impact or complex shell commands.
-9. Use `piagent_tool_policy_check` before non-piagent MCP/app tools.
-10. Use MCP/tools only when declared in profile.
-11. Use `piagent_usage_snapshot` or `/usage` when the user asks about token/context usage or session follow-up.
-12. Record context/verify/trace with `piagent_context_record`, `piagent_verify_record`, and `piagent_trace_record`. Passing verify evidence must be the exact command from `task.verifyCommands`.
-13. Run `piagent_task_gate_check` before DONE.
-14. For unclear tasks, use `/workflow discuss` first; do not implement while requirements are unresolved.
-15. For external source repos, use `piagent-source-cache` and read targeted files only.
-16. For medium/large tasks, auto-delegate independent read-only scout/planning/review work to `piagent-scout`, `piagent-planner`, `piagent-reviewer`, or `piagent-oracle` when `pi-subagents` is available. Do not require the user to type `/run` for normal task orchestration.
-17. Keep implementation single-writer by default. Use parallel writers only with explicit user approval or safe worktree isolation and disjoint write sets.
-18. If the bundled `pi-subagents` parent skill is available, use it for delegation patterns, review loops, native supervisor coordination, and safety boundaries.
+For an ordinary source task:
+
+1. Runtime binds bounded source work to this Pi session before the model starts. If intake pauses for broad/high-risk/ambiguous scope, call `piagent_task_start` exactly once with project-relative path/glob scope and reuse the contract.
+2. Read the narrow target and nearest test. Use ordinary read/search/edit/bash tools and one writer.
+3. Complete intended source and focused regression-test edits, then run each exact runtime verifier. Rerun only after another mutation.
+4. Do not call Piagent management/diagnostic tools unless runtime or the operator asks. Report changed files, verification, and residual risk concisely.
+
+Runtime enforces protected paths, permissions, external/destructive confirmation, scope, current-tree evidence, and the final gate. Current source is authoritative; generated context is advisory. Use subagents only for independent read-only lanes.
+<!-- piagent-managed:end -->
 
 ## Review