@piagent/platform 1.6.0 → 1.7.1

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

@@ -1,18 +1,15 @@
-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 { uncertainSendRuntimeIntake } from "../session/uncertain-send-continuation.ts";
 import { compileCriterionGraph, criterionGraphContextSelection, criterionGraphContextSelectionDetails, criterionGraphGuidance, criterionGraphMode } from "../../extensions/criterion-graph.js";
 import { captureTaskStartBaseline } from "../inspection/task-baseline-start-capture.ts";
-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";
-type ExtensionContext = any; type TaskContract = any; type TaskStartParameters = any;
+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"; import { automaticTaskExpectedOutput, conditionalMutationPreTaskContext, taskStartLifecycleGuidance } from "./task-start-conditional-mutation.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,
@@ -20,12 +17,13 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
     applyRuntimeLifecycleObservation, automaticAcceptanceCriteria, automaticReadOnlyTaskScope, automaticReviewLenses, automaticTaskIntakeMode, automaticTaskMutationPolicy, automaticTaskRiskLane, automaticTaskScope,
     acceptanceBaselineGuidance, acceptanceLanguageAdapterForPath, acceptanceProofGuidance, bindSessionTask, buildAcceptanceReceipt, compactTaskDetails, contextBudgetConfig, createTaskRunId,
     currentSessionName, defaultWorkPlan, effectiveProtectedPaths, hasGitEvidenceRoot, hasOperatorSessionName,
-    isAcceptanceTestPath, loadProfileFromContext, matchesProtectedPath, normalizeReviewLenses, normalizeWorkPlanSteps, nowIso, policy,
+    isAcceptanceTestPath, loadProfileFromContext, matchesAnyPath, matchesProtectedPath, normalizeReviewLenses, normalizeWorkPlanSteps, nowIso, policy,
     priorTaskAttempts, recordTaskStartCheckpoint, redactText, redactTextArray, registerRuntimeTool,
-    repositoryFileManifest, repositoryFileManifestDetails, resolveOrchestrationPolicy, resolveTaskScopePatterns, runtimeLifecycleMode, runtimeState, safeTaskId, selectVerificationPlan,
+    repositoryFileManifest, resolveOrchestrationPolicy, resolveTaskScopePatterns, runtimeLifecycleMode, runtimeState, safeTaskId, selectVerificationPlan,
     summarizeAttempt, telemetry, validTaskScopePattern, validateNewWorkPlan, verifierCommandInstructions, workingTreeEvidenceDigest, workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence,
     writeTask
   } = deps;
+  const repositoryManifestProvider = resolveTaskStartRepositoryManifestProvider(deps);
   const taskStartTool = {
     name: "piagent_task_start",
     label: "Piagent Task Start",
@@ -33,27 +31,27 @@ 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 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.",
+      "Use source-change for project verifier execution or edits. Set mutationPolicy=required when a task-local diff is mandatory, allowed when verification/review may conditionally repair findings but zero delta is valid, and forbidden when source mutation is prohibited; 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 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." })),
+      mutationPolicy: Type.Optional(StringEnum(["required", "allowed", "forbidden"] as const, { description: "Required demands a final diff; allowed accepts zero or scoped source changes while retaining exact verification and mutation guards; forbidden 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."
+        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))),
@@ -74,12 +72,13 @@ 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);
@@ -135,12 +134,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
         };
       }
@@ -155,24 +154,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);
@@ -189,7 +179,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
         };
       }
@@ -197,7 +187,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
         };
       }
@@ -238,8 +228,10 @@ 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 };
+      const mutationPolicy = changeMode === "read-only" || params.mutationPolicy === "forbidden"
+        ? "forbidden"
+        : params.mutationPolicy === "allowed" ? "allowed" : "required";
+      if (changeMode === "read-only" && params.mutationPolicy !== undefined && params.mutationPolicy !== "forbidden") return { content: [{ type: "text", text: "Task start refused: read-only tasks must forbid 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." }],
@@ -260,11 +252,11 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       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;
@@ -287,16 +279,20 @@ 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 projectManifest = repositoryFileManifestDetails(ctx.cwd), projectFiles = projectManifest.files;
+      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 observedContext = criterionGraphContextSelection(undefined, [], conditionalMutationPreTaskContext(runtimeState.preTaskContext(ctx), resolvedScope,
+        params.intakeMode === "runtime" && mutationPolicy === "allowed", matchesAnyPath), maxManifestFiles);
       const task: TaskContract = {
         schemaVersion: 2,
         taskRunId,
@@ -309,6 +305,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         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),
@@ -331,7 +328,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
         },
@@ -355,11 +352,11 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         ? acceptanceBaselineGuidance(written, { cwd: ctx.cwd })
         : [];
       const exactOutputGuidance = mutationPolicy === "forbidden"
-        ? exactFinalOutputGuidance(written.summary)
+        ? exactFinalOutputGuidance(written)
         : [];
       const criticalProof = taskCriticalProofSection(
-        written, plannedContext, projectFiles, acceptanceProofGuidance, isAcceptanceTestPath, acceptanceLanguageAdapterForPath
-      );
+        written, plannedContext, projectFiles, acceptanceProofGuidance, isAcceptanceTestPath, acceptanceLanguageAdapterForPath,
+        taskPerformanceAssurance(written).requiresReview);
       bindSessionTask(ctx.cwd, sessionId, sessionName, written);
       runtimeState.cacheTaskIdentity(ctx, written);
       if (written.intakeMode !== "runtime") {
@@ -370,8 +367,8 @@ 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", 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, 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, observedContext: observedContext.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 {
@@ -379,7 +376,13 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
           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).",
@@ -397,16 +400,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
             ...(baselineGuidance.length > 0
               ? [["Existing public contract:", ...baselineGuidance.map((item: string) => `- ${item}`)].join("\n")]
               : []),
-            lifecycleMode === "automatic-readonly"
-              ? "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"
-                    ? `Runtime records objective evidence automatically; after verification, complete only step \`review\` with piagent_task_progress using taskId \`${written.taskId}\` and stepId \`review\`.`
-                    : "Use the active progress/recovery tools for the custom or high-risk checkpoints."
+            taskStartLifecycleGuidance(lifecycleMode, mutationPolicy, written.taskId)
           ].join("\n")
         }],
         details: compactTaskDetails(written)
@@ -414,31 +408,36 @@ 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; plannedContext?: Array<{ path: string; reason: string }>; plannedContextComplete?: boolean } | undefined> {
+  async function maybeStartAutomaticTask(prompt: string, ctx: ExtensionContext): Promise<{ started: boolean; text: string; task?: TaskContract; plannedContext?: Array<{ path: string; reason: string }>; plannedContextComplete?: boolean; continuation?: "terminal-uncertain-send" } | undefined> {
+    const active = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined,
+      uncertainSend = uncertainSendRuntimeIntake(ctx.cwd, active, prompt, ctx.sessionManager.getSessionId());
+    if (uncertainSend) {
+      if (uncertainSend.task) { appendTrace(ctx.cwd, uncertainSend.trace); appendSessionTrace(pi, uncertainSend.trace); }
+      telemetry(ctx, uncertainSend.trace); return uncertainSend.intake;
+    }
     const profile = loadProfileFromContext(ctx);
     const readProtectedPaths = effectiveProtectedPaths(policy, profile).readProtectedPaths;
     const intakeMode = automaticTaskIntakeMode(prompt, readProtectedPaths);
     if (!intakeMode) return undefined;
-    const mutationPolicy = automaticTaskMutationPolicy(prompt, intakeMode), active = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
+    const mutationPolicy = automaticTaskMutationPolicy(prompt, intakeMode);
     if (active?.trace.outcome === "pending") return undefined;
     const summary = redactText(automaticTaskSummary(prompt));
     const sessionName = currentSessionName(ctx);
-    const projectManifest = repositoryFileManifestDetails(ctx.cwd), projectFiles = projectManifest.files;
+    const projectManifest = repositoryManifestProvider.read(ctx.cwd), projectFiles = projectManifest.files;
     const scope = intakeMode === "read-only"
       ? automaticReadOnlyTaskScope(prompt, runtimeState.preTaskContext(ctx))
-      : automaticTaskScope(prompt, runtimeState.preTaskContext(ctx), projectFiles);
+      : automaticTaskScope(prompt, runtimeState.preTaskContext(ctx), projectFiles, active);
     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,
         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, mutationPolicy === "forbidden" ? "read-only" : intakeMode),
+        expectedOutput: automaticTaskExpectedOutput(mutationPolicy),
+        acceptanceCriteria: automaticAcceptanceCriteria(prompt, mutationPolicy === "forbidden" ? "read-only" : intakeMode, mutationPolicy),
         scope,
         outOfScope: ["Unrelated files and behavior outside the operator request."],
         reviewLenses: automaticReviewLenses(prompt)
@@ -469,9 +468,10 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
     const baselineGuidance = task.changeMode === "source-change" && task.mutationPolicy !== "forbidden"
       ? acceptanceBaselineGuidance(task, { cwd: ctx.cwd })
       : [];
-    const exactOutputGuidance = task.changeMode === "read-only" || task.mutationPolicy === "forbidden" ? exactFinalOutputGuidance(task.summary) : [];
+    const exactOutputGuidance = task.changeMode === "read-only" || task.mutationPolicy === "forbidden" ? exactFinalOutputGuidance(task) : [];
     const criticalProof = taskCriticalProofSection(
-      task, plannedContext, projectFiles, acceptanceProofGuidance, isAcceptanceTestPath, acceptanceLanguageAdapterForPath
+      task, plannedContext, projectFiles, acceptanceProofGuidance, isAcceptanceTestPath, acceptanceLanguageAdapterForPath,
+      assurance.requiresReview
     );
     return {
       started: true,
@@ -479,7 +479,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       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"}).`,
         ...criticalProof,