@piagent/platform 1.5.5 → 1.6.1

package/packages/piagent-core/runtime/registration/task-start-tool.ts

@@ -1,46 +1,28 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { exactFinalOutputGuidance } from "../quality/exact-output-contract.ts";
-import { taskPerformanceAssurance } from "../quality/performance-assurance.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; import { exactFinalOutputGuidance } from "../quality/exact-output-contract.ts"; import { taskPerformanceAssurance } from "../quality/performance-assurance.ts";
 import { automaticTaskSummary, boundedRuntimeIntakeMessage } from "../workflows/task-intake.ts";
 import { WORKING_TREE_DIGEST_ALGORITHM } from "../../extensions/working-tree-digest.js";
+import { TASK_ACCEPTANCE_CRITERIA_MAX, TASK_ACCEPTANCE_CRITERION_MAX_CHARS, TASK_EXPECTED_OUTPUT_MAX_CHARS, TASK_SUMMARY_MAX_CHARS, operatorRequestDigest } from "../../extensions/task-state.js";
 import { createEnvironmentBoundTaskAuthority } from "../policy/task-authority-runtime.ts";
 import { authorityReplacementState } from "../policy/authority-resume-policy.ts";
-import { compileCriterionGraph, criterionGraphContextSelection, criterionGraphGuidance, criterionGraphMode } from "../../extensions/criterion-graph.js";
+import { compileCriterionGraph, criterionGraphContextSelection, criterionGraphContextSelectionDetails, criterionGraphGuidance, criterionGraphMode } from "../../extensions/criterion-graph.js";
 import { captureTaskStartBaseline } from "../inspection/task-baseline-start-capture.ts";
-type ExtensionContext = any;
-type TaskContract = any;
-type TaskStartParameters = any;
-function sameStringRecord(left: Record<string, string>, right: Record<string, string>): boolean {
-  const leftEntries = Object.entries(left).sort(([a], [b]) => a.localeCompare(b));
-  const rightEntries = Object.entries(right).sort(([a], [b]) => a.localeCompare(b));
-  return leftEntries.length === rightEntries.length
-    && leftEntries.every(([key, value], index) => rightEntries[index]?.[0] === key && rightEntries[index]?.[1] === value);
-}
-function satisfiesAuthorityReplacement(task: TaskContract, state: ReturnType<typeof authorityReplacementState>): boolean {
-  if (!task.authoritySnapshot) return false;
-  if (state.reason === "mechanical-rollback-requested") {
-    return task.authoritySnapshot.profile === "mechanical-only";
-  }
-  if (state.reason === "capability-kill-switch-requested") {
-    return state.killedCapabilities.length > 0 && state.killedCapabilities.every((capabilityId) => (
-      task.authoritySnapshot.capabilities.some((entry: any) => entry.id === capabilityId && entry.authority === "off")
-    ));
-  }
-  return true;
-}
+import { sameStringRecord, satisfiesAuthorityReplacement } from "./task-start-retry-helpers.ts"; import { automaticTaskExecutionGuidance, EXACT_VERIFIER_EXECUTION_GUIDANCE, RUNTIME_SOURCE_REUSE_GUIDANCE, taskCriticalProofSection } from "./task-start-guidance.ts";
+import { resolveTaskStartRepositoryManifestProvider } from "./task-start-manifest.ts"; import { boundedOperatorRequest, latestOperatorRequest } from "./operator-request-intake.ts";
+type ExtensionContext = any; type TaskContract = any; type TaskStartParameters = Record<string, any> & { operatorRequest?: string }; function taskReferenceDetails(task: TaskContract, reasonCode: string): Record<string, unknown> { const scope = Array.isArray(task.scope) ? task.scope.slice(0, 50) : []; return { reasonCode, taskId: task.taskId, taskRunId: task.taskRunId, outcome: task.trace?.outcome, attempt: task.attempt, ...(reasonCode === "task-already-active" ? { scope, scopeTruncated: scope.length < task.scope.length } : {}) }; }
 export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any>): any {
   const {
     DEFAULT_MAX_TASK_ATTEMPTS, ORCHESTRATION_ROLES, REVIEW_LENSES, StringEnum, Type,
     activateToolGroups, activeSessionTask, activeTaskToolGroups, appendSessionTrace, appendTrace,
-    applyRuntimeLifecycleObservation, automaticAcceptanceCriteria, automaticReadOnlyTaskScope, automaticReviewLenses, automaticTaskIntakeMode, automaticTaskRiskLane, automaticTaskScope,
-    acceptanceBaselineGuidance, acceptanceProofGuidance, bindSessionTask, buildAcceptanceReceipt, compactTaskDetails, contextBudgetConfig, createTaskRunId,
+    applyRuntimeLifecycleObservation, automaticAcceptanceCriteria, automaticReadOnlyTaskScope, automaticReviewLenses, automaticTaskIntakeMode, automaticTaskMutationPolicy, automaticTaskRiskLane, automaticTaskScope,
+    acceptanceBaselineGuidance, acceptanceLanguageAdapterForPath, acceptanceProofGuidance, bindSessionTask, buildAcceptanceReceipt, compactTaskDetails, contextBudgetConfig, createTaskRunId,
     currentSessionName, defaultWorkPlan, effectiveProtectedPaths, hasGitEvidenceRoot, hasOperatorSessionName,
-    loadProfileFromContext, matchesProtectedPath, normalizeReviewLenses, normalizeWorkPlanSteps, nowIso, policy,
+    isAcceptanceTestPath, loadProfileFromContext, matchesProtectedPath, normalizeReviewLenses, normalizeWorkPlanSteps, nowIso, policy,
     priorTaskAttempts, recordTaskStartCheckpoint, redactText, redactTextArray, registerRuntimeTool,
     repositoryFileManifest, resolveOrchestrationPolicy, resolveTaskScopePatterns, runtimeLifecycleMode, runtimeState, safeTaskId, selectVerificationPlan,
-    summarizeAttempt, validTaskScopePattern, validateNewWorkPlan, verifierCommandInstructions, workingTreeEvidenceDigest, workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence,
+    summarizeAttempt, telemetry, validTaskScopePattern, validateNewWorkPlan, verifierCommandInstructions, workingTreeEvidenceDigest, workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence,
     writeTask
   } = deps;
+  const repositoryManifestProvider = resolveTaskStartRepositoryManifestProvider(deps);
   const taskStartTool = {
     name: "piagent_task_start",
     label: "Piagent Task Start",
@@ -48,27 +30,28 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
     promptSnippet: "Start a governed project task and persist the task contract.",
     promptGuidelines: [
       "Call this exactly once before source edits in a project managed by Pi Agent Platform.",
-      "Use source-change for project command execution, including tests, builds, lint, typecheck, verification, and package dry-runs, even when the operator requires source files to remain unchanged. Read-only intentionally blocks shell execution.",
+      "Use source-change for project verifier execution or edits. For an assessment, report, or plan with no source changes, set mutationPolicy=forbidden; use read-only when no project verifier needs to execute.",
       "Do not call context, status, policy, evidence-recording, trace, or gate tools first; runtime hooks provide those checks automatically.",
       "Use tiny for a bounded low-risk change, normal for ordinary multi-file work, and high-risk for security, data, release, migration, or external-impact work.",
-      "Every scope entry must be a project-relative path or glob such as src/file.ts, src/**, or test/**; never put prose in scope.",
+      "Every scope entry is an initial retrieval/review focus and must be a project-relative path or glob such as src/file.ts, src/**, or test/**; it is not a source-mutation boundary.",
       "Leave workPlan unset for ordinary tiny/normal tasks so runtime automation stays active; pass a custom workPlan only when the operator explicitly requests custom subagent or checkpoint orchestration.",
       "Tiny tasks use automatic lifecycle evidence; normal tasks retain one explicit review step; high-risk/custom plans keep manual checkpoints."
     ],
     parameters: Type.Object({
       taskId: Type.Optional(Type.String({ minLength: 1 })),
-      summary: Type.String({ minLength: 10 }),
+      summary: Type.String({ minLength: 10, maxLength: TASK_SUMMARY_MAX_CHARS }),
       riskLane: StringEnum(["tiny", "normal", "high-risk"] as const),
       changeMode: Type.Optional(StringEnum(["source-change", "read-only"] as const, {
-        description: "Use source-change for project command execution as well as edits; use read-only only for inspection that needs no shell execution."
+        description: "Use source-change for project verifier execution or edits; use read-only for bounded inspection."
       })),
+      mutationPolicy: Type.Optional(StringEnum(["required", "forbidden"] as const, { description: "Required demands a final diff; forbidden allows exact verification, rejects source mutation, and requires a zero task delta." })),
       maxAttempts: Type.Optional(Type.Number({ minimum: 1, maximum: 10 })),
-      expectedOutput: Type.String({ minLength: 10 }),
-      acceptanceCriteria: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 12 }),
+      expectedOutput: Type.String({ minLength: 10, maxLength: TASK_EXPECTED_OUTPUT_MAX_CHARS }),
+      acceptanceCriteria: Type.Array(Type.String({ minLength: 1, maxLength: TASK_ACCEPTANCE_CRITERION_MAX_CHARS }), { minItems: 1, maxItems: TASK_ACCEPTANCE_CRITERIA_MAX }),
       scope: Type.Array(Type.String({
         minLength: 1,
-        description: "Project-relative path or glob only (for example src/file.ts, src/**, or test/**); do not use prose."
-      }), { minItems: 1 }),
+        description: "Advisory retrieval/review focus as a project-relative path or glob (for example src/file.ts, src/**, or test/**); source changes may follow repository evidence beyond it."
+      }), { minItems: 1, maxItems: 2000 }),
       outOfScope: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
       reviewLenses: Type.Optional(Type.Array(StringEnum(REVIEW_LENSES))),
       workPlan: Type.Optional(Type.Array(Type.Object({
@@ -88,13 +71,20 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       _onUpdate: ((update: unknown) => void) | undefined,
       ctx: ExtensionContext
     ) {
-      const profile = loadProfileFromContext(ctx);
-      const createdAt = nowIso();
-      const safeSummary = redactText(params.summary);
+      const profile = loadProfileFromContext(ctx), createdAt = nowIso();
+      const operatorRequest = typeof params.operatorRequest === "string"
+        ? params.operatorRequest
+        : latestOperatorRequest(ctx);
+      const safeSummary = redactText(params.summary), safeOperatorRequest = boundedOperatorRequest(operatorRequest, redactText);
       const taskId = safeTaskId(redactText(params.taskId ?? params.summary));
-      const sessionId = ctx.sessionManager.getSessionId();
-      const sessionName = currentSessionName(ctx);
+      const sessionId = ctx.sessionManager.getSessionId(), sessionName = currentSessionName(ctx);
       const active = activeSessionTask(ctx.cwd, sessionId) as TaskContract | undefined;
+      if (active && active.trace.outcome !== "pending" && runtimeState.taskIdentity(ctx)?.taskRunId === active.taskRunId) {
+        runtimeState.clearTaskBoundary(ctx, active.taskRunId);
+      } else if (!active) {
+        const cachedTask = runtimeState.taskIdentity(ctx);
+        if (cachedTask) runtimeState.clearTaskBoundary(ctx, cachedTask.taskRunId);
+      }
       const activeAuthorityReplacement = active ? authorityReplacementState(ctx.cwd, active) : undefined;
       if (activeAuthorityReplacement && !activeAuthorityReplacement.enforcementSafe) {
         return {
@@ -143,12 +133,12 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
           }
           return {
             content: [{ type: "text", text: `Task already active in this session: ${active.taskId} (${active.taskRunId}). Reusing it instead of overwriting state.` }],
-            details: compactTaskDetails(active)
+            details: taskReferenceDetails(active, "task-already-active")
           };
         }
         return {
           content: [{ type: "text", text: `Session already has pending task ${active.taskId} (${active.taskRunId}). Complete or stop it before starting another task in this conversation.` }],
-          details: active,
+          details: taskReferenceDetails(active, "session-task-already-pending"),
           isError: true
         };
       }
@@ -163,24 +153,15 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         };
       }
       const scopeResolution = resolveTaskScopePatterns(params.scope, repositoryFileManifest(ctx.cwd));
-      if (scopeResolution.ambiguous.length > 0) {
-        const details = scopeResolution.ambiguous
-          .map((item) => `${item.input}: ${item.candidates.join(", ")}`)
-          .join("; ");
-        return {
-          content: [{ type: "text", text: `Task start refused: scope is ambiguous (${details}). Use one exact project-relative candidate for each ambiguous entry.` }],
-          details: scopeResolution,
-          isError: true
-        };
-      }
-      if (scopeResolution.unmatched.length > 0) {
-        return {
-          content: [{ type: "text", text: `Task start refused: scope entries do not identify an existing repository path (${scopeResolution.unmatched.join(", ")}). Use an exact project-relative path for a new file, such as src/name.ts, instead of a basename or guessed top-level alias.` }],
-          details: scopeResolution,
-          isError: true
-        };
-      }
-      const resolvedScope = scopeResolution.scope;
+      // Scope guides context selection and review; it is not filesystem
+      // authority. Keep unresolved focus entries instead of preventing work in
+      // a parent workspace where several child repositories share names such
+      // as src/, app/, tests/, or package.json.
+      const unresolvedFocus = [
+        ...scopeResolution.ambiguous.map((item) => item.input),
+        ...scopeResolution.unmatched
+      ];
+      const resolvedScope = [...new Set([...scopeResolution.scope, ...unresolvedFocus])];
       const priorAttempts = priorTaskAttempts(ctx.cwd, taskId) as TaskContract[];
       const authorityStates = new Map(priorAttempts.map((task) => [task.taskRunId, authorityReplacementState(ctx.cwd, task)]));
       const unsafeAuthorityState = [...authorityStates.entries()].find(([, state]) => !state.enforcementSafe);
@@ -197,7 +178,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       if (pendingElsewhere) {
         return {
           content: [{ type: "text", text: `Task ${taskId} is already active in session ${pendingElsewhere.sessionName ?? pendingElsewhere.sessionId} (${pendingElsewhere.taskRunId}).` }],
-          details: pendingElsewhere,
+          details: taskReferenceDetails(pendingElsewhere, "task-active-in-another-session"),
           isError: true
         };
       }
@@ -205,7 +186,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       if (latestCompleted) {
         return {
           content: [{ type: "text", text: `Task ${taskId} already completed as ${latestCompleted.taskRunId}. Use a distinct taskId for new work instead of replacing its evidence.` }],
-          details: latestCompleted,
+          details: taskReferenceDetails(latestCompleted, "task-already-completed"),
           isError: true
         };
       }
@@ -246,6 +227,8 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       }
       const orchestration = resolveOrchestrationPolicy(profile, policy);
       const changeMode = params.changeMode === "read-only" ? "read-only" : "source-change";
+      const mutationPolicy = changeMode === "read-only" || params.mutationPolicy === "forbidden" ? "forbidden" : "required";
+      if (changeMode === "read-only" && params.mutationPolicy === "required") return { content: [{ type: "text", text: "Task start refused: read-only tasks cannot require source mutation." }], isError: true };
       if (changeMode === "source-change" && !hasGitEvidenceRoot(ctx.cwd)) {
         return {
           content: [{ type: "text", text: "Task start refused: source-change tasks require a Git working tree, or a workspace parent with direct child Git repositories, so changed-file evidence cannot silently disappear. Initialize Git, open the parent that contains the repos, or use read-only mode." }],
@@ -263,14 +246,14 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       const reviewLenses = normalizeReviewLenses(params.reviewLenses, orchestration.defaultReviewLenses);
       const providedWorkPlan = normalizeWorkPlanSteps(params.workPlan);
       const defaultPlanLane = params.intakeMode === "runtime" && params.riskLane === "normal" ? "tiny" : params.riskLane;
-      const workPlan = providedWorkPlan.length ? providedWorkPlan : defaultWorkPlan(safeSummary, defaultPlanLane, changeMode);
+      const workPlan = providedWorkPlan.length ? providedWorkPlan : defaultWorkPlan(safeSummary, defaultPlanLane, changeMode, mutationPolicy);
       const workPlanError = validateNewWorkPlan(workPlan);
       if (workPlanError) {
-        return { content: [{ type: "text", text: `Task start refused: ${workPlanError}.` }], details: workPlan, isError: true };
+        return { content: [{ type: "text", text: `Task start refused: ${workPlanError}.` }], details: { reasonCode: "invalid-work-plan" }, isError: true };
       }
       const firstReady = workPlan.find((step) => (step.dependsOn ?? []).length === 0);
       if (!firstReady) {
-        return { content: [{ type: "text", text: "Task start refused: work plan has no dependency-ready first step." }], details: workPlan, isError: true };
+        return { content: [{ type: "text", text: "Task start refused: work plan has no dependency-ready first step." }], details: { reasonCode: "work-plan-has-no-ready-step" }, isError: true };
       }
       firstReady.status = "in-progress";
       firstReady.updatedAt = createdAt;
@@ -293,12 +276,19 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         expectedOutput: redactText(params.expectedOutput),
         acceptanceCriteria: redactTextArray(params.acceptanceCriteria),
         changeMode,
+        mutationPolicy,
+        outOfScope: redactTextArray(params.outOfScope),
+        protectedPaths: profile.protectedPaths ?? [],
         source: params.intakeMode === "runtime" ? "runtime" : "model",
         generatedAt: createdAt
       });
       const criterionGraph = compileCriterionGraph({ acceptanceCriteria: acceptance.acceptanceCriteria, scope: resolvedScope,
         verifyCommands: verifyPlan.commands, changeMode, mode: criterionGraphMode(), createdAt });
-      const seededContext = criterionGraphContextSelection(criterionGraph, repositoryFileManifest(ctx.cwd), runtimeState.observedContext(ctx), contextBudgetConfig(policy).maxManifestFiles);
+      const projectManifest = repositoryManifestProvider.read(ctx.cwd), projectFiles = projectManifest.files;
+      const maxManifestFiles = contextBudgetConfig(policy).maxManifestFiles;
+      const plannedSelection = criterionGraphContextSelectionDetails(criterionGraph, projectFiles, [], maxManifestFiles, projectManifest.complete, resolvedScope);
+      const plannedContext = plannedSelection.entries;
+      const observedContext = criterionGraphContextSelection(undefined, [], runtimeState.preTaskContext(ctx), maxManifestFiles);
       const task: TaskContract = {
         schemaVersion: 2,
         taskRunId,
@@ -306,10 +296,12 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         sessionId,
         sessionName,
         changeMode,
+        mutationPolicy,
         attempt,
         maxAttempts,
         previousAttempts: priorAttempts.filter((task) => task.trace.outcome !== "pending").slice(0, 10).reverse().map(summarizeAttempt),
         summary: safeSummary,
+        ...(safeOperatorRequest ? { operatorRequest: safeOperatorRequest, operatorRequestDigest: operatorRequestDigest(safeOperatorRequest) } : {}),
         riskLane: params.riskLane,
         intakeMode: params.intakeMode === "runtime" ? "runtime" : "model",
         expectedOutput: redactText(params.expectedOutput),
@@ -319,7 +311,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         outOfScope: redactTextArray(params.outOfScope),
         protectedPaths: profile.protectedPaths ?? [],
         requiredContext: profile.requiredContext ?? [],
-        contextManifest: seededContext,
+        contextManifest: observedContext,
         memoryCitations: [],
         mcpCapabilities: profile.mcpCapabilities ?? [],
         verifyGroup: verifyPlan.group,
@@ -332,7 +324,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         orchestration: {
           mode: orchestration.defaultMode,
           subagents: "not-used",
-          reason: "Task starts in solo-first mode; use bounded subagents only for independent scout, planning, or review work.",
+          reason: "Parent works directly by default. One fresh read-only helper is eligible only with two independent lanes and at least 30% projected net token savings; workers and retries are disabled.",
           fieldGuidePath: orchestration.fieldGuide.enabled ? orchestration.fieldGuide.path : undefined,
           modelRoles: orchestration.roleModelGuidance
         },
@@ -347,16 +339,20 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         createdAt,
         updatedAt: createdAt
       };
-      if (changeMode === "read-only" && seededContext.length > 0) {
+      if (mutationPolicy === "forbidden" && observedContext.length > 0) {
         applyRuntimeLifecycleObservation(task, "context-complete", createdAt);
       }
       const written = writeTask(ctx.cwd, task);
-      const baselineGuidance = changeMode === "source-change"
+      runtimeState.promotePreTaskContext(ctx, written.taskRunId, observedContext);
+      const baselineGuidance = changeMode === "source-change" && mutationPolicy === "required"
         ? acceptanceBaselineGuidance(written, { cwd: ctx.cwd })
         : [];
-      const exactOutputGuidance = changeMode === "read-only"
-        ? exactFinalOutputGuidance(written.summary)
+      const exactOutputGuidance = mutationPolicy === "forbidden"
+        ? exactFinalOutputGuidance(written)
         : [];
+      const criticalProof = taskCriticalProofSection(
+        written, plannedContext, projectFiles, acceptanceProofGuidance, isAcceptanceTestPath, acceptanceLanguageAdapterForPath,
+        taskPerformanceAssurance(written).requiresReview);
       bindSessionTask(ctx.cwd, sessionId, sessionName, written);
       runtimeState.cacheTaskIdentity(ctx, written);
       if (written.intakeMode !== "runtime") {
@@ -367,18 +363,28 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       }
       const lifecycleMode = runtimeLifecycleMode(written);
       const scopeMappings = scopeResolution.mappings.map((item) => `${item.from} -> ${item.to}`);
-      appendTrace(ctx.cwd, { taskId, taskRunId, sessionId, sessionName, attempt, event: "task_start", summary: task.summary, riskLane: params.riskLane, intakeMode: task.intakeMode, changeMode: task.changeMode, lifecycleMode, criterionGraphMode: written.criterionGraph.mode, criterionGraphDigest: written.criterionGraph.graphDigest, authorityProfile: written.authoritySnapshot.profile, authoritySnapshotDigest: written.authoritySnapshot.snapshotDigest, scopeMappings, seededContext: seededContext.map((item) => item.path) });
-      appendSessionTrace(pi, { taskId, taskRunId, sessionId, sessionName, attempt, event: "task_start", summary: task.summary, riskLane: params.riskLane, intakeMode: task.intakeMode, changeMode: task.changeMode, lifecycleMode, criterionGraphMode: written.criterionGraph.mode, criterionGraphDigest: written.criterionGraph.graphDigest, authorityProfile: written.authoritySnapshot.profile, authoritySnapshotDigest: written.authoritySnapshot.snapshotDigest, scopeMappings, seededContext: seededContext.map((item) => item.path) });
+      appendTrace(ctx.cwd, { taskId, taskRunId, sessionId, sessionName, attempt, event: "task_start", turnId: runtimeState.currentTurn(ctx)?.turnId, summary: task.summary, riskLane: params.riskLane, intakeMode: task.intakeMode, changeMode: task.changeMode, mutationPolicy: task.mutationPolicy, lifecycleMode, criterionGraphMode: written.criterionGraph.mode, criterionGraphDigest: written.criterionGraph.graphDigest, authorityProfile: written.authoritySnapshot.profile, authoritySnapshotDigest: written.authoritySnapshot.snapshotDigest, scopeMappings, plannedContext: plannedContext.map((item) => item.path), plannedContextComplete: plannedSelection.complete, plannedContextCandidateCount: plannedSelection.candidateCount, repositoryManifestProvider: projectManifest.provider, repositoryManifestCompatibilityReason: projectManifest.compatibilityReason, observedContext: observedContext.map((item) => item.path) });
+      appendSessionTrace(pi, { taskId, taskRunId, sessionId, sessionName, attempt, event: "task_start", turnId: runtimeState.currentTurn(ctx)?.turnId, summary: task.summary, riskLane: params.riskLane, intakeMode: task.intakeMode, changeMode: task.changeMode, mutationPolicy: task.mutationPolicy, lifecycleMode, criterionGraphMode: written.criterionGraph.mode, criterionGraphDigest: written.criterionGraph.graphDigest, authorityProfile: written.authoritySnapshot.profile, authoritySnapshotDigest: written.authoritySnapshot.snapshotDigest, scopeMappings, plannedContext: plannedContext.map((item) => item.path), plannedContextComplete: plannedSelection.complete, plannedContextCandidateCount: plannedSelection.candidateCount, repositoryManifestProvider: projectManifest.provider, repositoryManifestCompatibilityReason: projectManifest.compatibilityReason, observedContext: observedContext.map((item) => item.path) });
+      telemetry(ctx, { event: "turn_task_bound", turnId: runtimeState.currentTurn(ctx)?.turnId, taskRunId });
       recordTaskStartCheckpoint(ctx, written, firstReady.id, lifecycleMode);
       return {
         content: [{
           type: "text",
           text: [
             `Task ${taskId} started (${params.riskLane}, ${lifecycleMode}; attempt ${attempt}/${maxAttempts}).`,
-            ...(scopeMappings.length > 0 ? [`Canonical scope: ${scopeMappings.join("; ")}.`] : []),
+            ...(scopeMappings.length > 0 ? [`Initial focus mapping: ${scopeMappings.join("; ")}.`] : []),
+            ...(scopeResolution.ambiguous.length > 0
+              ? [`Ambiguous focus retained as advisory: ${scopeResolution.ambiguous.map((item) => item.input).join(", ")}.`]
+              : []),
+            ...(scopeResolution.unmatched.length > 0
+              ? [`Unmatched focus retained for discovery or new files: ${scopeResolution.unmatched.join(", ")}.`]
+              : []),
             written.verifyCommands.length > 0
               ? ["Exact verifier commands:", ...verifierCommandInstructions(written.verifyCommands)].join("\n")
               : "Verify: none (read-only).",
+            ...(written.verifyCommands.length > 0
+              ? [EXACT_VERIFIER_EXECUTION_GUIDANCE]
+              : []),
             written.acceptanceCriteria.length > 0
               ? ["Acceptance focus:", ...written.acceptanceCriteria.map((criterion, index) => `${index + 1}. ${criterion}`)].join("\n")
               : "Acceptance focus: not recorded.",
@@ -386,9 +392,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
               ? [["Execution map (planning only; verifier remains authoritative):", ...criterionGraphGuidance(written.criterionGraph).map((line: string) => `- ${line}`)].join("\n")]
               : []),
             ...exactOutputGuidance,
-            ...(changeMode === "source-change" && acceptanceProofGuidance(written).length > 0
-              ? [["Critical behavioral proof:", ...acceptanceProofGuidance(written).map((item: string) => `- ${item}`), "Map every proof item above to a live focused assertion or explicit test matrix before the verifier; happy-path coverage and prose claims are insufficient."].join("\n")]
-              : []),
+            ...criticalProof,
             ...(baselineGuidance.length > 0
               ? [["Existing public contract:", ...baselineGuidance.map((item: string) => `- ${item}`)].join("\n")]
               : []),
@@ -396,6 +400,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
               ? "Runtime records targeted reads and final completion automatically. Stay read-only and report cited evidence."
               : lifecycleMode === "assisted-readonly"
                 ? "Runtime records read-only evidence automatically; complete only the explicit evidence-review step before handoff."
+                : mutationPolicy === "forbidden" ? "Runtime permits bounded inspection and exact configured verifier commands only. Source mutation is blocked, and completion requires a zero task delta."
                 : lifecycleMode === "automatic"
               ? "Runtime will record reads, changes, exact verifier results, and final completion automatically. Continue with ordinary read/edit/bash work."
                   : lifecycleMode === "assisted"
@@ -408,31 +413,31 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
     }
   };
   registerRuntimeTool(pi, taskStartTool);
-  async function maybeStartAutomaticTask(prompt: string, ctx: ExtensionContext): Promise<{ started: boolean; text: string; task?: TaskContract } | undefined> {
+  async function maybeStartAutomaticTask(prompt: string, ctx: ExtensionContext): Promise<{ started: boolean; text: string; task?: TaskContract; plannedContext?: Array<{ path: string; reason: string }>; plannedContextComplete?: boolean } | undefined> {
     const profile = loadProfileFromContext(ctx);
     const readProtectedPaths = effectiveProtectedPaths(policy, profile).readProtectedPaths;
     const intakeMode = automaticTaskIntakeMode(prompt, readProtectedPaths);
     if (!intakeMode) return undefined;
-    const active = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
+    const mutationPolicy = automaticTaskMutationPolicy(prompt, intakeMode), active = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
     if (active?.trace.outcome === "pending") return undefined;
     const summary = redactText(automaticTaskSummary(prompt));
     const sessionName = currentSessionName(ctx);
-    const projectFiles = repositoryFileManifest(ctx.cwd);
+    const projectManifest = repositoryManifestProvider.read(ctx.cwd), projectFiles = projectManifest.files;
     const scope = intakeMode === "read-only"
-      ? automaticReadOnlyTaskScope(prompt, runtimeState.observedContext(ctx))
-      : automaticTaskScope(prompt, runtimeState.observedContext(ctx), projectFiles);
+      ? automaticReadOnlyTaskScope(prompt, runtimeState.preTaskContext(ctx))
+      : automaticTaskScope(prompt, runtimeState.preTaskContext(ctx), projectFiles);
     const started = await taskStartTool.execute(
       `runtime-intake-${ctx.sessionManager.getSessionId()}`,
       {
         taskId: active && active.trace.outcome !== "pending" ? summary : hasOperatorSessionName(sessionName) ? sessionName : summary,
-        summary,
+        summary, operatorRequest: prompt,
         riskLane: automaticTaskRiskLane(prompt),
         intakeMode: "runtime",
         changeMode: intakeMode,
-        expectedOutput: intakeMode === "read-only"
-          ? "The requested read-only investigation is answered from observed project evidence without mutating files."
+        mutationPolicy,
+        expectedOutput: mutationPolicy === "forbidden" ? "The requested read-only investigation is answered from observed project evidence without mutating files."
           : "The requested bounded change is implemented and passes the configured verification.",
-        acceptanceCriteria: automaticAcceptanceCriteria(prompt, intakeMode),
+        acceptanceCriteria: automaticAcceptanceCriteria(prompt, mutationPolicy === "forbidden" ? "read-only" : intakeMode),
         scope,
         outOfScope: ["Unrelated files and behavior outside the operator request."],
         reviewLenses: automaticReviewLenses(prompt)
@@ -458,22 +463,26 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       };
     }
     const assurance = taskPerformanceAssurance(task);
-    const baselineGuidance = task.changeMode === "source-change"
+    const plannedSelection = criterionGraphContextSelectionDetails(task.criterionGraph, projectFiles, [], contextBudgetConfig(policy).maxManifestFiles, projectManifest.complete, task.scope);
+    const plannedContext = plannedSelection.entries;
+    const baselineGuidance = task.changeMode === "source-change" && task.mutationPolicy !== "forbidden"
       ? acceptanceBaselineGuidance(task, { cwd: ctx.cwd })
       : [];
-    const exactOutputGuidance = task.changeMode === "read-only"
-      ? exactFinalOutputGuidance(task.summary)
-      : [];
+    const exactOutputGuidance = task.changeMode === "read-only" || task.mutationPolicy === "forbidden" ? exactFinalOutputGuidance(task) : [];
+    const criticalProof = taskCriticalProofSection(
+      task, plannedContext, projectFiles, acceptanceProofGuidance, isAcceptanceTestPath, acceptanceLanguageAdapterForPath,
+      assurance.requiresReview
+    );
     return {
       started: true,
       task,
+      plannedContext,
+      plannedContextComplete: plannedSelection.complete,
       text: boundedRuntimeIntakeMessage([
-        `Piagent runtime task: ${task.taskId}; scope: ${task.scope.join(", ")}.`,
+        `Piagent runtime task: ${task.taskId}; initial focus (advisory): ${task.scope.join(", ")}.`,
         "The complete operator request above is the authoritative acceptance contract; runtime keeps its full criteria, so do not restate or re-scout it.",
         `Assurance: ${assurance.tier} (${assurance.reasonCodes.join(", ") || "bounded-runtime"}).`,
-        ...(task.changeMode === "source-change" && acceptanceProofGuidance(task).length > 0
-          ? [["Critical behavioral proof:", ...acceptanceProofGuidance(task).map((item: string) => `- ${item}`), "Map every proof item above to a live focused assertion or explicit test matrix before the verifier; happy-path coverage is insufficient."].join("\n")]
-          : []),
+        ...criticalProof,
         ...(baselineGuidance.length > 0
           ? [["Existing public contract:", ...baselineGuidance.map((item: string) => `- ${item}`)].join("\n")]
           : []),
@@ -481,15 +490,11 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         "Exact verifier commands:",
         ...(task.verifyCommands.length > 0 ? verifierCommandInstructions(task.verifyCommands) : ["none"]),
         ...(criterionGraphGuidance(task.criterionGraph).length > 0 ? [["Execution map (planning only):", ...criterionGraphGuidance(task.criterionGraph).map((line: string) => `- ${line}`)].join("\n")] : []),
+        RUNTIME_SOURCE_REUSE_GUIDANCE,
         "Root project instructions are loaded. Do not re-read root AGENTS.md or inspect Piagent/platform files; work directly in relevant source/tests with ordinary tools.",
-        task.changeMode === "read-only"
-          ? "Stay read-only. Runtime records targeted reads and completion evidence; do not call task-management tools."
-          : task.criterionGraph?.mode === "criterion-graph"
-            ? "Follow the execution map: batch context reads by target, implement dependency-ready criteria, then run the exact verifier once; rerun only after a later mutation. The map plans work but never overrides the operator request or verifier."
-            : "Before mutating, privately map every operator criterion to implementation and focused-test coverage; batch independent reads or writes. Finish intended edits and one criterion-by-criterion self-review, then run the exact verifier once; rerun only after a later mutation. Runtime records evidence and completion; do not call task-management tools."
+        automaticTaskExecutionGuidance(task)
       ].join("\n"))
     };
   }
-
   return maybeStartAutomaticTask;
 }

package/packages/piagent-core/runtime/runtime-limits.ts

@@ -6,10 +6,24 @@ export const CONTEXT_COMPACT_PERCENT = 70;
 export const CONTEXT_FRESH_PERCENT = 82;
 export const LONG_INPUT_CHARS = 8000;
 export const MAX_INLINE_COLLAPSED_TASK_CHARS = 2200;
-export const RUNTIME_INTAKE_MESSAGE_MAX_CHARS = 6_000;
-export const SEMANTIC_COMPACTION_MAX_CHARS = 8_000;
+export const RUNTIME_INTAKE_COMPACT_CHARS = 3_500;
+export const RUNTIME_INTAKE_MESSAGE_MAX_CHARS = 3_500;
+export const SEMANTIC_COMPACTION_MAX_CHARS = 12_000;
 export const CONTEXT_PACK_MAX_TOKENS = 900;
 
+// The host's default compaction reserve is primarily an overflow guard. Piagent's
+// governor acts earlier because repeatedly replaying a valid 200k+ context can
+// burn substantially more tokens than the task itself. These are working-set
+// limits, not capability limits: high-value task truth is carried forward while
+// stale tool transcripts remain in the durable session history.
+export const CONTEXT_PROVIDER_PROMPT_CEILING_TOKENS = 240_000;
+export const CONTEXT_GOVERNOR_PRESSURE_TOKENS = 160_000;
+export const CONTEXT_GOVERNOR_TARGET_MESSAGE_TOKENS = 72_000;
+export const CONTEXT_GOVERNOR_RECENT_MESSAGE_TOKENS = 40_000;
+export const CONTEXT_GOVERNOR_SEMANTIC_BOUNDARY_TOKENS = 48_000;
+export const CONTEXT_GOVERNOR_TOOL_ROUND_LIMIT = 24;
+export const CONTEXT_GOVERNOR_LEDGER_MAX_CHARS = 12_000;
+
 export const TOOL_RESULT_COMPACT_CHAR_THRESHOLD = 12_000;
 export const TOOL_RESULT_COMPACT_LINE_THRESHOLD = 180;
 export const TOOL_RESULT_PREVIEW_HEAD_LINES = 24;