@piagent/platform 1.6.0 → 1.7.1

package/evals/runtime-conformance-v1/runner.mjs

@@ -0,0 +1,456 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  auditToolProtocol,
+  minimumContextSavingsTokens,
+  projectAdaptiveContext
+} from "../../packages/piagent-core/runtime/session/adaptive-context-governor.ts";
+import {
+  BoundedEmissionGuard,
+  runtimeEventEmissionCandidate
+} from "../../packages/piagent-core/runtime/inspection/bounded-emission-guard.ts";
+import { EditFreshnessGuard } from "../../packages/piagent-core/runtime/quality/edit-freshness-guard.ts";
+import {
+  SessionOperationLifecycle,
+  sessionOperationRetryPolicy
+} from "../../packages/piagent-webui/gateway/session-operation-lifecycle.ts";
+
+const laneRoot = path.dirname(fileURLToPath(import.meta.url));
+const lane = JSON.parse(fs.readFileSync(path.join(laneRoot, "lane.json"), "utf8"));
+const argumentsList = process.argv.slice(2);
+const option = (name) => {
+  const index = argumentsList.indexOf(name);
+  return index >= 0 ? argumentsList[index + 1] : undefined;
+};
+const outputArgument = option("--output");
+if (argumentsList.includes("--output") && !outputArgument) throw new Error("--output requires a path");
+const outputPath = outputArgument ? path.resolve(outputArgument) : null;
+const startedAtMs = Date.now();
+let timestamp = 1;
+
+function user(text) {
+  return { role: "user", content: text, timestamp: timestamp++ };
+}
+
+function toolRound(id, name, args, output) {
+  return [
+    {
+      role: "assistant",
+      content: [{ type: "toolCall", id, name, arguments: args }],
+      timestamp: timestamp++
+    },
+    {
+      role: "toolResult",
+      toolCallId: id,
+      toolName: name,
+      content: [{ type: "text", text: output }],
+      isError: false,
+      timestamp: timestamp++
+    }
+  ];
+}
+
+function task() {
+  return {
+    taskId: "runtime-conformance",
+    taskRunId: "runtime-conformance-run-1",
+    summary: "Implement a frontend contract without changing backend behavior.",
+    riskLane: "normal",
+    acceptanceCriteria: ["Preserve behavior", "Pass focused verification"],
+    scope: ["src/**"],
+    outOfScope: ["backend mutation"],
+    changedFiles: ["src/page.tsx"],
+    verifyCommands: ["node --test"],
+    trace: { outcome: "pending" }
+  };
+}
+
+function boundedCandidate(text, updateKey, reference) {
+  return {
+    channel: "reviewer",
+    identityKey: "runtime-conformance-reviewer",
+    updateKey,
+    text,
+    actionable: true,
+    reference
+  };
+}
+
+function finalMessageCandidate() {
+  return runtimeEventEmissionCandidate({
+    kind: "message.completed",
+    sessionRef: "runtime-conformance-session",
+    taskRunId: "runtime-conformance-run-1",
+    agentOperationId: "runtime-conformance-operation",
+    turnIndex: 1,
+    toolCallId: null,
+    revision: { runtimeRevision: "runtime-revision-1" },
+    payload: { role: "assistant", textPreview: "Final response remains visible." }
+  }, "message-final");
+}
+
+const results = [];
+const metrics = {
+  context: {
+    projections: 0,
+    noops: 0,
+    estimatedSavingsTokens: 0,
+    governorProviderCalls: 0,
+    toolProtocolOrphans: 0
+  },
+  operations: {
+    pristineRetriesAllowed: 0,
+    unsafeRetriesAllowed: 0,
+    unsafeRetriesAborted: 0,
+    terminalSettlements: 0,
+    duplicateTerminalSettlements: 0,
+    lateEventsIgnored: 0,
+    compactionRetryBudgetConsumed: 0
+  },
+  emissions: {
+    accepted: 0,
+    suppressed: 0,
+    retained: 0,
+    finalMessagesSuppressed: 0
+  },
+  edits: {
+    staleEvaluations: 0,
+    staleMutationsAllowed: 0,
+    freshRereadRecoveries: 0
+  }
+};
+
+function runCase(id, area, execute) {
+  const caseStartedAt = Date.now();
+  try {
+    const evidence = execute() ?? {};
+    results.push({ id, area, status: "passed", durationMilliseconds: Date.now() - caseStartedAt, evidence });
+  } catch (error) {
+    results.push({
+      id,
+      area,
+      status: "failed",
+      durationMilliseconds: Date.now() - caseStartedAt,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+}
+
+runCase("context-small-passthrough", "adaptive-context-governor", () => {
+  const messages = [user("Implement src/cart.ts"), ...toolRound("small-read", "read", { path: "src/cart.ts" }, "export const cart = true;")];
+  const projection = projectAdaptiveContext(messages, {
+    reportedTokens: 9_000,
+    contextWindow: 400_000,
+    task: task()
+  });
+  assert.equal(projection.decision.action, "passthrough");
+  assert.equal(projection.messages, messages);
+  assert.equal(projection.decision.accounting.billedTraffic.governorProviderCalls, 0);
+  metrics.context.governorProviderCalls += projection.decision.accounting.billedTraffic.governorProviderCalls;
+  return { action: projection.decision.action, originalMessages: messages.length };
+});
+
+runCase("context-insufficient-savings-noop", "adaptive-context-governor", () => {
+  const messages = [user("Continue the same implementation")];
+  for (let index = 0; index < 8; index += 1) {
+    messages.push(...toolRound(`noop-${index}`, "read", { path: `src/noop-${index}.ts` }, "x".repeat(6_000)));
+  }
+  const projection = projectAdaptiveContext(messages, {
+    reportedTokens: 250_000,
+    contextWindow: 400_000,
+    task: task()
+  });
+  assert.equal(projection.decision.action, "passthrough");
+  assert.equal(projection.decision.fallback, "insufficient-savings");
+  assert.equal(projection.messages, messages);
+  assert.ok(projection.decision.estimatedSavingsTokens < projection.decision.minimumSavingsTokens);
+  assert.equal(
+    projection.decision.minimumSavingsTokens,
+    minimumContextSavingsTokens(projection.decision.originalMessageTokens)
+  );
+  assert.equal(projection.decision.accounting.billedTraffic.governorProviderCalls, 0);
+  metrics.context.noops += 1;
+  metrics.context.governorProviderCalls += projection.decision.accounting.billedTraffic.governorProviderCalls;
+  return {
+    action: projection.decision.action,
+    fallback: projection.decision.fallback,
+    candidateSavingsTokens: projection.decision.estimatedSavingsTokens,
+    minimumSavingsTokens: projection.decision.minimumSavingsTokens
+  };
+});
+
+runCase("context-projection-protocol-safe", "adaptive-context-governor", () => {
+  const messages = [user("Scout the backend subscription contract")];
+  for (let index = 0; index < 14; index += 1) {
+    messages.push(...toolRound(
+      `project-${index}`,
+      "read",
+      { path: `backend/src/module-${index}.ts` },
+      `source-${index}\n${"x".repeat(5_000)}`
+    ));
+  }
+  messages.push(user("Proceed to implement the frontend subscription mapping"));
+  const projection = projectAdaptiveContext(messages, {
+    reportedTokens: 92_000,
+    contextWindow: 400_000,
+    task: task()
+  });
+  const protocol = auditToolProtocol(projection.messages);
+  assert.equal(projection.decision.action, "project");
+  assert.equal(projection.decision.reason, "semantic-boundary");
+  assert.equal(protocol.intact, true);
+  assert.equal(protocol.orphanCallIds.length + protocol.orphanResultIds.length, 0);
+  assert.ok(projection.decision.estimatedSavingsTokens >= projection.decision.minimumSavingsTokens);
+  assert.match(String(projection.messages.at(-1)?.content ?? ""), /implement the frontend subscription mapping/i);
+  assert.equal(projection.decision.accounting.billedTraffic.governorProviderCalls, 0);
+  metrics.context.projections += 1;
+  metrics.context.estimatedSavingsTokens += projection.decision.estimatedSavingsTokens;
+  metrics.context.governorProviderCalls += projection.decision.accounting.billedTraffic.governorProviderCalls;
+  metrics.context.toolProtocolOrphans += protocol.orphanCallIds.length + protocol.orphanResultIds.length;
+  return {
+    action: projection.decision.action,
+    reason: projection.decision.reason,
+    originalMessageTokens: projection.decision.originalMessageTokens,
+    projectedMessageTokens: projection.decision.projectedMessageTokens,
+    estimatedSavingsTokens: projection.decision.estimatedSavingsTokens,
+    savingsRatio: projection.decision.savingsRatio,
+    toolProtocolIntact: protocol.intact
+  };
+});
+
+runCase("context-orphan-protocol-fail-closed", "adaptive-context-governor", () => {
+  const messages = [user("Continue implementation")];
+  for (let index = 0; index < 8; index += 1) {
+    messages.push(...toolRound(`valid-${index}`, "read", { path: `src/valid-${index}.ts` }, "x".repeat(6_000)));
+  }
+  messages.push({
+    role: "toolResult",
+    toolCallId: "missing-call",
+    toolName: "read",
+    content: [{ type: "text", text: "orphan result" }],
+    timestamp: timestamp++
+  });
+  messages.push({
+    role: "assistant",
+    content: [{ type: "toolCall", id: "missing-result", name: "read", arguments: { path: "src/missing.ts" } }],
+    timestamp: timestamp++
+  });
+  const sourceProtocol = auditToolProtocol(messages);
+  const projection = projectAdaptiveContext(messages, {
+    reportedTokens: 250_000,
+    contextWindow: 400_000,
+    task: task()
+  });
+  assert.equal(sourceProtocol.intact, false);
+  assert.equal(projection.decision.action, "passthrough");
+  assert.equal(projection.decision.fallback, "unsafe-tool-protocol");
+  assert.equal(projection.messages, messages);
+  assert.ok(projection.decision.reasonCodes.includes("unsafe-tool-protocol"));
+  assert.equal(projection.decision.accounting.billedTraffic.governorProviderCalls, 0);
+  metrics.context.noops += 1;
+  metrics.context.governorProviderCalls += projection.decision.accounting.billedTraffic.governorProviderCalls;
+  return {
+    sourceOrphanCalls: sourceProtocol.orphanCallIds.length,
+    sourceOrphanResults: sourceProtocol.orphanResultIds.length,
+    projected: false,
+    fallback: projection.decision.fallback
+  };
+});
+
+runCase("operation-pristine-retry-bounded", "webui-operation-lifecycle", () => {
+  assert.deepEqual(sessionOperationRetryPolicy(), { maximumAttempts: 1, maximumDelayMs: 8_000 });
+  const lifecycle = new SessionOperationLifecycle({ operationRef: "operation-pristine" });
+  lifecycle.observe({ type: "agent_start", operationRef: "operation-pristine" });
+  const first = lifecycle.observe({
+    type: "auto_retry_start",
+    operationRef: "operation-pristine",
+    attempt: 1,
+    delayMs: 100
+  });
+  assert.equal(first.retry, "allowed");
+  metrics.operations.pristineRetriesAllowed += 1;
+  lifecycle.observe({ type: "auto_retry_end", operationRef: "operation-pristine", attempt: 1, success: false });
+  const second = lifecycle.observe({
+    type: "auto_retry_start",
+    operationRef: "operation-pristine",
+    attempt: 2,
+    delayMs: 100
+  });
+  assert.equal(second.retry, "abort");
+  assert.equal(second.reasonCode, "automatic-retry-attempt-limit");
+  return { maximumAttempts: lifecycle.retryPolicy.maximumAttempts, firstRetry: first.retry, secondRetry: second.retry };
+});
+
+runCase("operation-replay-unsafe-and-exactly-once", "webui-operation-lifecycle", () => {
+  const visible = new SessionOperationLifecycle({ operationRef: "operation-visible" });
+  visible.observe({ type: "agent_start" });
+  visible.observe({
+    type: "message_update",
+    message: { role: "assistant", content: [{ type: "text", text: "Visible output" }] },
+    assistantMessageEvent: { type: "text_delta", delta: "Visible output" }
+  });
+  const visibleRetry = visible.observe({ type: "auto_retry_start", attempt: 1, delayMs: 0 });
+  assert.equal(visibleRetry.retry, "abort");
+  assert.equal(visibleRetry.reasonCode, "automatic-retry-replay-unsafe");
+
+  const tool = new SessionOperationLifecycle({ operationRef: "operation-tool" });
+  tool.observe({ type: "agent_start" });
+  tool.observe({ type: "tool_execution_start", toolCallId: "write-1", toolName: "write" });
+  const toolRetry = tool.observe({ type: "auto_retry_start", attempt: 1, delayMs: 0 });
+  assert.equal(toolRetry.retry, "abort");
+  assert.equal(toolRetry.reasonCode, "automatic-retry-replay-unsafe");
+  metrics.operations.unsafeRetriesAborted += 2;
+
+  assert.equal(tool.markTerminal(), true);
+  metrics.operations.terminalSettlements += 1;
+  const duplicateTerminal = tool.markTerminal();
+  assert.equal(duplicateTerminal, false);
+  if (duplicateTerminal) metrics.operations.duplicateTerminalSettlements += 1;
+  const late = tool.observe({ type: "message_update", assistantMessageEvent: { type: "text_delta", delta: "late" } });
+  assert.equal(late.accepted, false);
+  assert.equal(late.reasonCode, "operation-event-after-settlement");
+  metrics.operations.lateEventsIgnored += 1;
+  return {
+    visibleRetry: visibleRetry.retry,
+    toolRetry: toolRetry.retry,
+    terminalSettlements: 1,
+    duplicateTerminalSettlements: 0,
+    lateEvent: late.reasonCode
+  };
+});
+
+runCase("operation-compaction-isolated", "webui-operation-lifecycle", () => {
+  const lifecycle = new SessionOperationLifecycle({ operationRef: "operation-compaction" });
+  lifecycle.observe({ type: "agent_start" });
+  const start = lifecycle.observe({ type: "compaction_start", reason: "overflow" });
+  assert.equal(start.phase, "compaction");
+  const summarization = lifecycle.observe({ type: "summarization_retry_scheduled", attempt: 1, delayMs: 5 });
+  assert.equal(summarization.accepted, true);
+  assert.equal(summarization.retry, "none");
+  const end = lifecycle.observe({ type: "compaction_end", reason: "overflow" });
+  assert.equal(end.phase, "running");
+  const providerRetry = lifecycle.observe({ type: "auto_retry_start", attempt: 1, delayMs: 5 });
+  assert.equal(providerRetry.retry, "allowed");
+  metrics.operations.pristineRetriesAllowed += 1;
+  return { compactionPhase: start.phase, summarizationRetry: summarization.retry, providerRetry: providerRetry.retry };
+});
+
+runCase("emission-bounded-final-preserved", "bounded-emission-guard", () => {
+  const guard = new BoundedEmissionGuard({ capacity: 2 });
+  const filler = guard.inspect(boundedCandidate("No issue; continue.", "update-0", "review-0"));
+  assert.equal(filler.reason, "filler");
+
+  const first = boundedCandidate("Potential race in queue.", "update-1", "review-1");
+  assert.equal(guard.inspect(first).accepted, true);
+  guard.recordAccepted(first);
+  assert.equal(guard.inspect(boundedCandidate("Potential race in queue.", "update-2", "review-2")).reason, "duplicate-exact");
+  assert.equal(guard.inspect(boundedCandidate("potential RACE in queue!", "update-3", "review-3")).reason, "duplicate-normalized");
+
+  const second = boundedCandidate("Mutation lacks a verifier.", "update-4", "review-4");
+  assert.equal(guard.inspect(second).accepted, true);
+  guard.recordAccepted(second);
+  const third = boundedCandidate("Late activity remains bounded.", "update-5", "review-5");
+  assert.equal(guard.inspect(third).accepted, true);
+  guard.recordAccepted(third);
+
+  const telemetry = guard.telemetry();
+  assert.equal(telemetry.retained, 2);
+  assert.equal(finalMessageCandidate(), null, "final assistant messages must bypass suppression");
+  metrics.emissions.accepted += telemetry.accepted;
+  metrics.emissions.suppressed += telemetry.suppressed;
+  metrics.emissions.retained = telemetry.retained;
+  return {
+    capacity: telemetry.capacity,
+    retained: telemetry.retained,
+    accepted: telemetry.accepted,
+    suppressed: telemetry.suppressed,
+    suppressedByReason: telemetry.suppressedByReason,
+    finalMessageBypassesGuard: true
+  };
+});
+
+runCase("edit-stale-blocked-until-reread", "edit-freshness-guard", () => {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "piagent-runtime-conformance-edit-"));
+  try {
+    fs.mkdirSync(path.join(cwd, "src"), { recursive: true });
+    const target = path.join(cwd, "src", "value.ts");
+    fs.writeFileSync(target, "export const value = 1;\n");
+    const ctx = { cwd, sessionManager: { getSessionId: () => "runtime-conformance-session" } };
+    const guard = new EditFreshnessGuard("enforce");
+    assert.deepEqual(guard.observe(ctx, "runtime-conformance-run-1", ["src/value.ts"], "read"), ["src/value.ts"]);
+    assert.equal(guard.evaluate(ctx, "runtime-conformance-run-1", ["src/value.ts"]).decision, "current");
+
+    fs.writeFileSync(target, "// concurrent change\nexport const value = 1;\n");
+    const beforeRejectedMutation = fs.readFileSync(target, "utf8");
+    const stale = guard.evaluate(ctx, "runtime-conformance-run-1", ["src/value.ts"]);
+    assert.equal(stale.decision, "stale");
+    assert.equal(stale.enforce, true);
+    assert.deepEqual(stale.stalePaths, ["src/value.ts"]);
+    assert.equal(fs.readFileSync(target, "utf8"), beforeRejectedMutation, "evaluation must not mutate stale content");
+    metrics.edits.staleEvaluations += 1;
+
+    guard.observe(ctx, "runtime-conformance-run-1", ["src/value.ts"], "read");
+    const recovered = guard.evaluate(ctx, "runtime-conformance-run-1", ["src/value.ts"]);
+    assert.equal(recovered.decision, "current");
+    metrics.edits.freshRereadRecoveries += 1;
+    return { staleDecision: stale.decision, stalePaths: stale.stalePaths, recoveredDecision: recovered.decision };
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+const completedAtMs = Date.now();
+const failed = results.filter((result) => result.status !== "passed");
+const configuredCaseIds = lane.cases.map((item) => item.id);
+const observedCaseIds = results.map((item) => item.id);
+const configuredCasesMatched = JSON.stringify(configuredCaseIds) === JSON.stringify(observedCaseIds);
+const gates = {
+  allCasesPass: failed.length === 0 && configuredCasesMatched,
+  providerCalls: metrics.context.governorProviderCalls === lane.releaseGates.providerCalls,
+  modelInputTokens: lane.releaseGates.modelInputTokens === 0,
+  modelOutputTokens: lane.releaseGates.modelOutputTokens === 0,
+  toolProtocolOrphans: metrics.context.toolProtocolOrphans === lane.releaseGates.toolProtocolOrphans,
+  unsafeRetriesAllowed: metrics.operations.unsafeRetriesAllowed === lane.releaseGates.unsafeRetriesAllowed,
+  duplicateTerminalSettlements: metrics.operations.duplicateTerminalSettlements === lane.releaseGates.duplicateTerminalSettlements,
+  finalMessagesSuppressed: metrics.emissions.finalMessagesSuppressed === lane.releaseGates.finalMessagesSuppressed,
+  staleMutationsAllowed: metrics.edits.staleMutationsAllowed === lane.releaseGates.staleMutationsAllowed
+};
+const passed = failed.length === 0 && configuredCasesMatched && Object.values(gates).every(Boolean);
+const report = {
+  schemaVersion: 1,
+  laneId: lane.id,
+  evidenceClass: "provider-free-runtime-conformance",
+  startedAt: new Date(startedAtMs).toISOString(),
+  completedAt: new Date(completedAtMs).toISOString(),
+  wallClockMilliseconds: completedAtMs - startedAtMs,
+  provider: {
+    required: lane.providerRequired,
+    used: false,
+    calls: 0,
+    modelInputTokens: 0,
+    modelOutputTokens: 0
+  },
+  summary: {
+    configuredCases: lane.cases.length,
+    executedCases: results.length,
+    passedCases: results.length - failed.length,
+    failedCases: failed.length,
+    passed
+  },
+  metrics,
+  gates,
+  cases: results,
+  claimBoundary: lane.claimBoundary
+};
+
+const serialized = `${JSON.stringify(report, null, 2)}\n`;
+if (outputPath) {
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, serialized);
+}
+process.stdout.write(serialized);
+if (!passed) process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -110,15 +110,18 @@
   "piagent": {
     "runtimeIntegrityEntrypoints": [
       "packages/piagent-webui/server/sidecar-main.ts",
+      "packages/piagent-core/extensions/acceptance-executor/worker.mjs",
+      "packages/piagent-core/extensions/acceptance-executor/package.json",
+      "packages/piagent-core/extensions/acceptance-executor/package-lock.json",
       "scripts/benchmark-runner-core.mjs",
       "scripts/register-typescript-loader.mjs",
       "scripts/typescript-loader.mjs"
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "0.84.1",
-    "@earendil-works/pi-coding-agent": "0.84.1",
-    "typebox": "1.3.7"
+    "@earendil-works/pi-ai": "0.86.1",
+    "@earendil-works/pi-coding-agent": "0.86.1",
+    "typebox": "1.3.27"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
@@ -132,6 +135,7 @@
     }
   },
   "dependencies": {
+    "@babel/parser": "7.29.8",
     "ws": "8.21.3"
   },
   "devDependencies": {
@@ -160,6 +164,7 @@
     "doctor": "bash scripts/team-doctor.sh",
     "benchmark": "node scripts/benchmark-runner.mjs",
     "benchmark:deep": "node scripts/benchmark-runner.mjs --deep --surfaces piagent,codex-cli --model openai-codex/gpt-5.6-luna --thinking medium --allow-pi-auth-writeback",
+    "benchmark:production-v2": "node scripts/benchmark-runner.mjs --suite production-v2 --allow-pi-auth-writeback",
     "benchmark:webui-parity": "node packages/piagent-webui/benchmark/parity-benchmark.mjs",
     "benchmark:redaction": "node scripts/redaction-benchmark.mjs",
     "audit:runtime": "bash scripts/audit-runtime-host.sh",

package/packages/piagent-core/README.md

@@ -22,8 +22,11 @@ Architecture boundaries and non-growth file budgets are enforced by `npm run arc
 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
+post-baseline mutations remain auditable. Task scope is an advisory retrieval
+and review focus rather than filesystem authority; Codex can follow repository
+evidence across packages and child repositories. Protected/read-only paths,
+destructive commands, and external actions remain governed. 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.
@@ -110,7 +113,7 @@ groups load only when requested.
 - `/workflow`: one launcher for task, scout, BE-to-FE, discuss, plan, review, commit, PR, platform-improve, and onboarding workflows.
 - `/usage`: runtime usage namespace for live snapshot, history hint, preflight, compact, compact-log captures, and context efficiency.
 - Pi native `/name`: set the current session name for Agent Watch/report mapping; Piagent observes the native rename event and keeps `/setname` as a compatibility alias.
-- `/fresh`: open a fresh governed session for `task`, `scout`, or `be-to-fe`.
+- `/fresh`: open a fresh governed session for any canonical `/workflow` option; `/fresh help` lists the current catalog.
 - `/context`: runtime context namespace for index/rebuild/search/pack/test-impact/efficiency, task preflight, and semantic compact.
 - `/permission`: runtime permission namespace for status/read-only/workspace-write/full-access.
 - `/onboard`: runtime onboarding namespace; `run` launches the first-read onboarding workflow.
@@ -130,10 +133,15 @@ When `pi-subagents` is installed, this package exposes:
 
 - `piagent-scout`
 - `piagent-planner`
-- `piagent-worker`
+- `piagent-worker` (compatibility metadata; disabled by Piagent config)
 - `piagent-reviewer`
 - `piagent-oracle`
 
+The parent model works directly. Helpers default to `off`; explicit opt-in still
+allows only one fresh read-only helper after a runtime-owned estimate proves at
+least 30% projected net token saving. Worker, parallel, nested, and retry paths
+remain disabled.
+
 ## Install
 
 ```bash
@@ -142,7 +150,7 @@ pi install git:github.com/Vt-mmm/piagent
 
 Use `git:github.com/Vt-mmm/piagent@vX.Y.Z` when pinning a reproducible project package source.
 
-Runtime support follows the root release matrix: Node.js `>=22.19.0`, Pi Coding Agent `0.84.1`, verified rollout on macOS Apple Silicon + Bash and Linux x64 + Bash, supported-target smoke verification for macOS Intel/Linux ARM64, no native Windows team rollout target yet, and WSL2 experimental.
+Runtime support follows the root release matrix: Node.js `>=22.19.0`, Pi Coding Agent `0.86.1` (SDK upgrade under local qualification; historical platform evidence below used `0.84.1`), verified rollout on macOS Apple Silicon + Bash and Linux x64 + Bash, supported-target smoke verification for macOS Intel/Linux ARM64, no native Windows team rollout target yet, and WSL2 experimental.
 
 ## Project profile
 
@@ -197,7 +205,8 @@ 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`.
+and match observed tool results. Changes beyond `task.scope` are retained as an
+auditable focus expansion and do not block source mutation or completion.
 
 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.
 

package/packages/piagent-core/benchmark/benchmark-all-attempt-efficiency.js

@@ -0,0 +1,55 @@
+import { atMostWithinFloatingPrecision, rounded } from "./benchmark-statistics.js";
+
+function surfaceFresh(accounting, surface) {
+  const bucket = accounting?.allAttempts?.bySurface?.[surface];
+  return {
+    attempts: Number.isSafeInteger(bucket?.attempts) ? bucket.attempts : 0,
+    freshTokens: Number.isSafeInteger(bucket?.tokens?.fresh) ? bucket.tokens.fresh : null
+  };
+}
+
+/**
+ * Net efficiency uses every accepted attempt plus every exact failed/retry
+ * attempt. It is deliberately pooled: no successful-only filtering, median,
+ * retry forgiveness, or subscription-credit conversion is applied.
+ */
+export function evaluateAllAttemptPooledFreshEfficiency({
+  tokenAccounting,
+  baselineSurface,
+  candidateSurface,
+  maximumRatio
+}) {
+  const required = Number.isFinite(maximumRatio);
+  const baseline = surfaceFresh(tokenAccounting, baselineSurface);
+  const candidate = surfaceFresh(tokenAccounting, candidateSurface);
+  const exact = tokenAccounting?.allAttempts?.complete === true;
+  const ratio = exact
+    && Number.isFinite(baseline.freshTokens) && baseline.freshTokens > 0
+    && Number.isFinite(candidate.freshTokens)
+      ? candidate.freshTokens / baseline.freshTokens
+      : null;
+  const passed = !required ? null : exact
+    && Number.isFinite(ratio)
+    && atMostWithinFloatingPrecision(ratio, maximumRatio);
+  return {
+    schemaVersion: 1,
+    required,
+    definition: "pooled-fresh-tokens-across-all-accepted-and-exact-failed-retry-attempts",
+    baselineSurface,
+    candidateSurface,
+    baseline,
+    candidate,
+    exact,
+    ledgerExact: tokenAccounting?.allAttempts?.ledgerExact === true,
+    ledgerIssues: Array.isArray(tokenAccounting?.allAttempts?.ledgerIssues)
+      ? tokenAccounting.allAttempts.ledgerIssues
+      : [],
+    unknownAttempts: Number(tokenAccounting?.allAttempts?.unknownAttempts ?? 0),
+    ratio: rounded(ratio, 6),
+    ratioRaw: ratio,
+    reductionPercent: Number.isFinite(ratio) ? rounded((1 - ratio) * 100, 2) : null,
+    maximumRatio: required ? maximumRatio : null,
+    passed,
+    subscriptionCredits: "excluded; see comparison.serviceTierEvidence.subscriptionCreditAccounting"
+  };
+}

package/packages/piagent-core/benchmark/benchmark-artifact-binding.js

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const SHA256 = /^[a-f0-9]{64}$/;
+const relativePath = (value) => typeof value === "string" && value.length <= 512
+  && /^[a-zA-Z0-9_.-]+(?:\/[a-zA-Z0-9_.-]+)*$/.test(value)
+  && !value.split("/").some((part) => [".", "..", ".git"].includes(part));
+
+export function benchmarkArtifactBindingShapeErrors(bindings) {
+  if (!Array.isArray(bindings) || bindings.length < 1 || bindings.length > 64) return ["artifact-bindings-invalid"];
+  const ids = new Set(), paths = new Set(), errors = [];
+  for (const item of bindings) {
+    if (!item || typeof item !== "object" || Array.isArray(item) || Object.keys(item).length !== 3
+      || typeof item.id !== "string" || !/^[a-z0-9][a-z0-9-]{0,79}$/.test(item.id)
+      || !relativePath(item.path) || typeof item.sha256 !== "string" || !SHA256.test(item.sha256)
+      || ids.has(item.id) || paths.has(item.path)) errors.push("artifact-binding-invalid");
+    else { ids.add(item.id); paths.add(item.path); }
+  }
+  return errors;
+}
+
+/** Checks current source only. A historical archive can never satisfy this gate. */
+export function benchmarkArtifactBindingErrors(bindings, sourceRoot) {
+  const errors = benchmarkArtifactBindingShapeErrors(bindings);
+  if (errors.length) return errors;
+  let root;
+  try {
+    if (typeof sourceRoot !== "string" || !path.isAbsolute(sourceRoot)) throw new Error("Invalid root");
+    root = fs.realpathSync.native(sourceRoot);
+    if (!fs.statSync(root).isDirectory()) throw new Error("Invalid root");
+  } catch { return ["artifact-source-root-unavailable"]; }
+  for (const item of bindings) {
+    let fd;
+    try {
+      const file = path.join(root, item.path);
+      if (fs.realpathSync.native(file) !== file) throw new Error("Symlinked artifact");
+      fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+      const before = fs.fstatSync(fd);
+      if (!before.isFile() || before.size < 1 || before.size > 2 * 1024 * 1024) throw new Error("Invalid artifact size/type");
+      const bytes = fs.readFileSync(fd), after = fs.fstatSync(fd);
+      if (bytes.length !== before.size || before.size !== after.size || before.mtimeMs !== after.mtimeMs
+        || before.ctimeMs !== after.ctimeMs) throw new Error("Artifact changed while reading");
+      if (createHash("sha256").update(bytes).digest("hex") !== item.sha256) errors.push(`artifact-digest-mismatch:${item.path}`);
+    } catch { errors.push(`artifact-unavailable-or-unsafe:${item.path}`); }
+    finally { if (fd !== undefined) fs.closeSync(fd); }
+  }
+  return errors;
+}