@piagent/platform 1.2.17 → 1.3.0-ie.9

package/packages/piagent-core/runtime/solver/task-features.ts

@@ -0,0 +1,119 @@
+import crypto from "node:crypto";
+
+import { classifyContextTask } from "../../extensions/context-engine.js";
+import { redactSensitiveText } from "../../security/sensitive-data.js";
+import type { TaskFeatures, WorkflowIntent } from "./solver-types.ts";
+import { validateTaskFeatures } from "./solver-types.ts";
+
+export type TaskFeatureInput = {
+  request: string;
+  workflowIntent?: WorkflowIntent;
+  changeMode?: TaskFeatures["changeMode"];
+  riskLane?: TaskFeatures["riskLane"];
+  riskSignals?: string[];
+  ambiguity?: TaskFeatures["ambiguity"];
+  scopeEstimate?: TaskFeatures["scopeEstimate"];
+  profileMode?: string | null;
+  projectShape?: string[];
+  gitReady?: boolean | null;
+  dirtyTree?: boolean | null;
+  verifierReady?: boolean | null;
+  contextPressure?: number | null;
+  activeTaskState?: TaskFeatures["activeTaskState"];
+  runtimeSnapshotDigest?: string | null;
+  runtimeCapabilitiesKnown?: boolean;
+  userPinnedProvider?: string | null;
+  userPinnedModel?: string | null;
+  userPinnedEffort?: string | null;
+  protectedTarget?: boolean;
+};
+
+function intent(request: string): WorkflowIntent {
+  const value = request.toLowerCase().replace(/(?:^|\s)(?:[.\w-]+\/)+[\w.-]+/g, " ");
+  const lead = value.split(/[.!?\n]/, 1)[0];
+  const primary = lead.trim();
+  if (/^(?:review|audit)\b|^(?:đánh giá|kiểm tra code|rà soát)/u.test(primary)) return "review";
+  if (/^(?:plan|planning)\b|^(?:lập kế hoạch|kế hoạch)/u.test(primary)) return "plan";
+  if (/^(?:diagnos(?:e|is)|investigate|debug|read[- ]only)\b|^(?:chẩn đoán|điều tra|phân tích lỗi|chỉ đọc)/u.test(primary)) return "diagnose";
+  if (/^(?:scout|research|inspect|explore)\b|^(?:khảo sát|nghiên cứu|xem xét)/u.test(primary)) return "scout";
+  if (/^(?:implement|fix|repair|correct|replace|build|add|change|update|refactor|create|make|erase)\b|^(?:sửa|xây|thêm|đổi|cập nhật|triển khai)/u.test(primary)) return "implement";
+  if (/\b(review|audit)\b|(?:đánh giá|kiểm tra code|rà soát)/u.test(lead)) return "review";
+  if (/\b(plan|planning)\b|(?:lập kế hoạch|kế hoạch)/u.test(lead)) return "plan";
+  if (/\b(diagnos(?:e|is)|investigate|debug|root cause|read[- ]only)\b|(?:chẩn đoán|điều tra|phân tích lỗi|chỉ đọc)/u.test(lead)) return "diagnose";
+  if (/\b(scout|research|inspect|explore)\b|(?:khảo sát|nghiên cứu|xem xét)/u.test(lead)) return "scout";
+  if (/\b(implement|fix|repair|correct|replace|build|add|change|update|refactor|create|make|erase)\b|(?:sửa|xây|thêm|đổi|cập nhật|triển khai)/u.test(lead)) return "implement";
+  return "unknown";
+}
+
+function normalizedNames(values: readonly unknown[] | undefined, max = 16): string[] {
+  return [...new Set((values ?? []).map((value) => {
+    const redacted = redactSensitiveText(String(value ?? "").trim());
+    return (redacted.redacted ? "redacted" : redacted.text).toLowerCase().replace(/[^a-z0-9._:/-]+/g, "-");
+  }).filter(Boolean))]
+    .sort()
+    .slice(0, max);
+}
+
+function nullableName(value: unknown): string | null {
+  const redacted = redactSensitiveText(String(value ?? "").trim());
+  const clean = (redacted.redacted ? "redacted" : redacted.text).replace(/[^a-z0-9._:/-]+/gi, "-").replace(/^-+|-+$/g, "").slice(0, 128);
+  return clean || null;
+}
+
+function stableHash(value: Record<string, unknown>): string {
+  return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+export function extractTaskFeatures(input: TaskFeatureInput): TaskFeatures {
+  const request = String(input.request ?? "");
+  const signal = classifyContextTask(request);
+  const workflowIntent = input.workflowIntent ?? intent(request);
+  const lower = request.toLowerCase();
+  const externalAction = /\b(push|publish|deploy|release|open (?:a )?pr|create (?:an )?issue|send|upload)\b|\b(?:phát hành|triển khai production|gửi ra ngoài)\b/u.test(lower);
+  const destructiveAction = /\b(rm\s+-rf|reset\s+--hard|drop\s+(?:table|database)|delete all|destroy|wipe|erase|remove every trace)\b|(?:xóa hết|xoá hết|hủy dữ liệu)/u.test(lower);
+  const permissionExpansion = /\b(grant|elevate|permission expansion|widen permissions?)\b|(?:cấp quyền|mở rộng quyền)/u.test(lower);
+  const riskSignals = normalizedNames([
+    ...(input.riskSignals ?? []),
+    ...(externalAction ? ["external-action"] : []),
+    ...(destructiveAction ? ["destructive-action"] : []),
+    ...(permissionExpansion ? ["permission-expansion"] : []),
+    ...(input.protectedTarget ? ["protected-target"] : []),
+    ...(signal.lane === "high-risk" ? ["classifier-high-risk"] : [])
+  ]);
+  const explicitPathCount = Math.min(1000, signal.paths.length);
+  const inferredAmbiguity: TaskFeatures["ambiguity"] = /\b(anything|whatever|somehow|figure it out|everywhere)\b|\b(?:tùy|không rõ|mọi nơi)\b/u.test(lower)
+    ? "high"
+    : explicitPathCount > 0 ? "low" : workflowIntent === "unknown" ? "high" : "medium";
+  const inferredScope: TaskFeatures["scopeEstimate"] = /\b(entire|whole|all (?:files|services)|repo-wide|platform-wide)\b|\b(?:toàn bộ|cả repo)\b/u.test(lower)
+    ? "broad"
+    : explicitPathCount === 1 ? "tiny" : explicitPathCount > 1 && explicitPathCount <= 4 ? "bounded" : explicitPathCount > 4 ? "broad" : "unknown";
+  const changeMode = input.changeMode ?? (workflowIntent === "plan" ? "plan-only" : ["review", "diagnose", "scout"].includes(workflowIntent) ? "read-only" : workflowIntent === "implement" ? "source-change" : "unknown");
+  const payload = {
+    schemaVersion: 1 as const,
+    workflowIntent,
+    changeMode,
+    riskLane: input.riskLane ?? (riskSignals.length > 0 ? "high-risk" as const : signal.lane === "tiny" ? "tiny" as const : "normal" as const),
+    riskSignals,
+    ambiguity: input.ambiguity ?? inferredAmbiguity,
+    explicitPathCount,
+    scopeEstimate: input.scopeEstimate ?? inferredScope,
+    profileMode: nullableName(input.profileMode),
+    projectShape: normalizedNames(input.projectShape),
+    gitReady: input.gitReady ?? null,
+    dirtyTree: input.dirtyTree ?? null,
+    verifierReady: input.verifierReady ?? null,
+    contextPressure: typeof input.contextPressure === "number" && Number.isFinite(input.contextPressure)
+      ? Math.max(0, Math.min(1, input.contextPressure)) : null,
+    activeTaskState: input.activeTaskState ?? "unknown" as const,
+    runtimeSnapshotDigest: input.runtimeSnapshotDigest ?? null,
+    runtimeCapabilitiesKnown: input.runtimeCapabilitiesKnown ?? false,
+    userPinnedProvider: nullableName(input.userPinnedProvider),
+    userPinnedModel: nullableName(input.userPinnedModel),
+    userPinnedEffort: nullableName(input.userPinnedEffort),
+    protectedTarget: input.protectedTarget ?? false,
+    externalAction,
+    destructiveAction,
+    permissionExpansion
+  };
+  return validateTaskFeatures({ ...payload, featureHash: stableHash(payload) });
+}

package/packages/piagent-core/runtime/tools/phase-tool-runtime.ts

@@ -0,0 +1,133 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { TrajectorySyncResult } from "../trajectory/trajectory-runtime.ts";
+import type { TrajectoryState } from "../trajectory/trajectory-types.ts";
+import { PIAGENT_TOOL_NAMES } from "./tool-groups.ts";
+import { PIAGENT_DIAGNOSTIC_TOOLS, PIAGENT_OPERATOR_TOOLS, phaseToolPolicy } from "./phase-tools.ts";
+
+export type PhaseToolMode = "off" | "shadow" | "on";
+export type PhaseMutationInput = {
+  projectMutation: boolean;
+  exactSourceVerifier?: boolean;
+  verificationCarrier?: boolean;
+};
+
+const MANAGED_HOST_TOOL_ORDER = Object.freeze(["read", "grep", "find", "ls", "edit", "write", "apply_patch", "bash", "shell", "exec"]);
+
+function phaseHostToolName(toolName: string): string {
+  return toolName === "shell" || toolName === "exec" ? "bash" : toolName;
+}
+
+export function phaseToolModeFromEnvironment(input: string | undefined): PhaseToolMode {
+  const normalized = input?.trim().toLowerCase();
+  return normalized === "off" || normalized === "on" || normalized === "shadow" ? normalized : "shadow";
+}
+
+export function intendedPhaseTools(current: string[], available: string[], state: TrajectoryState): string[] {
+  const policy = phaseToolPolicy(state.currentPhase, state.changeMode);
+  const availableSet = new Set([...available, ...current]);
+  const preserved = current.filter((tool) => !PIAGENT_TOOL_NAMES.has(tool) && !MANAGED_HOST_TOOL_ORDER.includes(tool));
+  const host = MANAGED_HOST_TOOL_ORDER.filter((tool) => availableSet.has(tool) && policy.requiredHostTools.includes(phaseHostToolName(tool)));
+  const piagent = policy.modelVisiblePiagentTools.filter((tool) => availableSet.has(tool));
+  return [...new Set([...preserved, ...host, ...piagent])];
+}
+
+type PhaseToolHost = Pick<ExtensionAPI, "getActiveTools" | "getAllTools" | "setActiveTools">;
+type Telemetry = (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
+type DigestMigrationStatus = (ctx: ExtensionContext) => string | undefined;
+type AuthorityMode = (ctx: ExtensionContext) => PhaseToolMode | undefined;
+
+export class PhaseToolRuntime {
+  private readonly states = new Map<string, TrajectoryState>();
+  private readonly observations = new Map<string, string>();
+  private readonly pi: PhaseToolHost;
+  private readonly telemetry: Telemetry;
+  private readonly digestMigrationStatus: DigestMigrationStatus;
+  private readonly authorityMode: AuthorityMode;
+  readonly mode: PhaseToolMode;
+
+  constructor(pi: PhaseToolHost, mode: PhaseToolMode, telemetry: Telemetry, digestMigrationStatus: DigestMigrationStatus = () => undefined, authorityMode: AuthorityMode = () => undefined) {
+    this.pi = pi;
+    this.mode = mode;
+    this.telemetry = telemetry;
+    this.digestMigrationStatus = digestMigrationStatus;
+    this.authorityMode = authorityMode;
+  }
+
+  private effectiveMode(ctx: ExtensionContext): PhaseToolMode { return this.authorityMode(ctx) ?? this.mode; }
+
+  private key(ctx: ExtensionContext): string {
+    return `${ctx.cwd}\0${ctx.sessionManager.getSessionId()}`;
+  }
+
+  private activate(ctx: ExtensionContext, state: TrajectoryState): void {
+    const mode = this.effectiveMode(ctx); if (mode === "off") return;
+    const current = this.pi.getActiveTools();
+    const available = this.pi.getAllTools().map((tool) => tool.name);
+    const intended = intendedPhaseTools(current, available, state);
+    const changed = current.length !== intended.length || intended.some((tool, index) => tool !== current[index]);
+    const added = intended.filter((tool) => !current.includes(tool));
+    const removed = current.filter((tool) => !intended.includes(tool));
+    const observation = JSON.stringify([state.taskRunId, state.sequence, state.currentPhase, current, intended]);
+    if (changed && this.observations.get(this.key(ctx)) !== observation) {
+      this.observations.set(this.key(ctx), observation);
+      this.telemetry(ctx, { event: "phase_tool_activation", mode, taskId: state.taskId, taskRunId: state.taskRunId, phase: state.currentPhase, sequence: state.sequence, currentCount: current.length, intendedCount: intended.length, added, removed, applied: mode === "on", enforcement: mode === "on" ? "tool-call-guard" : "shadow" });
+    }
+    // Keep the provider-visible tool schema cache-stable for the whole task.
+    // On mode enforces phase policy at tool-call time via `toolDecision` rather
+    // than replacing schemas after each trajectory transition.
+  }
+
+  toolDecision(ctx: ExtensionContext, toolName: string): { block: true; reason: string } | undefined {
+    if (this.effectiveMode(ctx) !== "on") return undefined;
+    if (toolName === "piagent_task_start" && this.digestMigrationStatus(ctx) === "new-attempt-required") return undefined;
+    const state = this.states.get(this.key(ctx));
+    if (!state) return undefined;
+    const policy = phaseToolPolicy(state.currentPhase, state.changeMode);
+    if (MANAGED_HOST_TOOL_ORDER.includes(toolName) && !policy.requiredHostTools.includes(phaseHostToolName(toolName))) {
+      return { block: true, reason: `Phase ${state.currentPhase} does not allow host tool ${toolName}; allowed host tools: ${policy.requiredHostTools.join(", ") || "none"}.` };
+    }
+    if (
+      PIAGENT_TOOL_NAMES.has(toolName)
+      && !PIAGENT_OPERATOR_TOOLS.has(toolName)
+      && !PIAGENT_DIAGNOSTIC_TOOLS.has(toolName)
+      && !policy.modelVisiblePiagentTools.includes(toolName)
+    ) {
+      return { block: true, reason: `Phase ${state.currentPhase} does not allow ${toolName}; allowed Piagent tools: ${policy.modelVisiblePiagentTools.join(", ") || "none"}.` };
+    }
+    return undefined;
+  }
+
+  mutationDecision(ctx: ExtensionContext, input: PhaseMutationInput): { block: true; reason: string } | undefined {
+    if (this.effectiveMode(ctx) !== "on") return undefined;
+    if (this.digestMigrationStatus(ctx) === "verification-refresh-required" && (input.projectMutation || input.verificationCarrier)) return input.exactSourceVerifier ? undefined : { block: true, reason: "Digest migration permits only the exact configured verifier under a pre/post tree invariant until current-tree evidence is refreshed." };
+    const state = this.states.get(this.key(ctx));
+    if (!state || (!input.projectMutation && !input.exactSourceVerifier)) return undefined;
+    if (state.changeMode === "read-only") {
+      return { block: true, reason: `Task ${state.taskId} is read-only; project mutation and source verification are not authorized.` };
+    }
+    if (input.exactSourceVerifier) {
+      if (["execute", "verify", "repair"].includes(state.currentPhase)) return undefined;
+      return { block: true, reason: `Phase ${state.currentPhase} does not authorize the exact source verifier; verification is allowed only in execute, verify, or repair.` };
+    }
+    if (input.projectMutation) {
+      if (state.currentPhase === "execute" || state.currentPhase === "repair") return undefined;
+      return { block: true, reason: `Phase ${state.currentPhase} does not authorize project mutation; mutation is allowed only in execute or repair.` };
+    }
+    return undefined;
+  }
+
+  apply<T extends TrajectorySyncResult | undefined>(ctx: ExtensionContext, result: T): T {
+    if (this.effectiveMode(ctx) === "off" || !result?.enforcementSafe || !result.state) return result;
+    this.states.set(this.key(ctx), result.state);
+    while (this.states.size > 128) this.states.delete(this.states.keys().next().value as string);
+    while (this.observations.size > 128) this.observations.delete(this.observations.keys().next().value as string);
+    this.activate(ctx, result.state);
+    return result;
+  }
+
+  reapply(ctx: ExtensionContext): void {
+    const state = this.states.get(this.key(ctx));
+    if (state) this.activate(ctx, state);
+  }
+}

package/packages/piagent-core/runtime/tools/phase-tools.ts

@@ -0,0 +1,140 @@
+import type { TrajectoryPhase } from "../trajectory/trajectory-types.ts";
+import { PIAGENT_TOOL_NAMES, PIAGENT_TOOL_ORDER } from "./tool-groups.ts";
+
+export const PHASE_TOOL_GROUPS = Object.freeze(["intake", "retrieval", "planning", "mutation", "verification", "review", "recovery", "handoff", "operator"] as const);
+export type PhaseToolGroup = typeof PHASE_TOOL_GROUPS[number];
+
+export const PIAGENT_PRIMARY_TOOL_GROUP = Object.freeze({
+  piagent_tools: "operator",
+  piagent_task_start: "intake",
+  piagent_context: "intake",
+  piagent_context_preflight: "intake",
+  piagent_task_progress: "mutation",
+  piagent_context_record: "recovery",
+  piagent_verify_record: "verification",
+  piagent_trace_record: "handoff",
+  piagent_task_gate_check: "review",
+  piagent_permission_status: "operator",
+  piagent_exec_policy_check: "operator",
+  piagent_tool_policy_check: "operator",
+  piagent_context_engine: "retrieval",
+  piagent_context_budget: "retrieval",
+  piagent_context_index_status: "retrieval",
+  piagent_context_index_search: "retrieval",
+  piagent_memory_status: "retrieval",
+  piagent_memory_search: "retrieval",
+  piagent_memory_citation_record: "review",
+  piagent_document_read: "retrieval",
+  piagent_source_checkout: "retrieval",
+  piagent_orchestration_policy: "planning",
+  piagent_profile_options: "operator",
+  piagent_profile_apply: "operator",
+  piagent_profile_tech_options: "operator",
+  piagent_profile_tech_apply: "operator",
+  piagent_profile_tech_context_record: "operator",
+  piagent_project_onboarding_record: "operator",
+  piagent_context_index_record: "operator",
+  piagent_memory_note: "operator",
+  piagent_usage_snapshot: "operator"
+} satisfies Record<string, PhaseToolGroup>);
+
+export const PIAGENT_OPERATOR_TOOLS = new Set<string>(Object.entries(PIAGENT_PRIMARY_TOOL_GROUP)
+  .filter(([, group]) => group === "operator").map(([tool]) => tool));
+export const PIAGENT_DIAGNOSTIC_TOOLS = new Set<string>([
+  "piagent_context_preflight", "piagent_permission_status", "piagent_exec_policy_check", "piagent_tool_policy_check",
+  "piagent_context_budget", "piagent_context_index_status", "piagent_memory_status", "piagent_usage_snapshot"
+]);
+export const PIAGENT_MUTATION_CAPABLE_TOOLS = new Set<string>([
+  "piagent_context_engine", "piagent_source_checkout", "piagent_profile_apply", "piagent_profile_tech_apply",
+  "piagent_profile_tech_context_record", "piagent_project_onboarding_record", "piagent_context_index_record", "piagent_memory_note"
+]);
+export const PIAGENT_SEQUENTIAL_TOOLS = new Set<string>([
+  ...PIAGENT_MUTATION_CAPABLE_TOOLS, "piagent_tools", "piagent_task_start", "piagent_task_progress", "piagent_context_record",
+  "piagent_verify_record", "piagent_trace_record", "piagent_memory_citation_record"
+]);
+
+const PHASE_GROUP_POLICY: Record<TrajectoryPhase, PhaseToolGroup[]> = {
+  intake: ["intake", "retrieval"],
+  scout: ["retrieval", "mutation", "recovery"],
+  plan: ["retrieval", "planning", "mutation", "recovery"],
+  execute: ["retrieval", "mutation"],
+  verify: ["retrieval", "verification", "recovery"],
+  repair: ["retrieval", "mutation", "verification", "recovery"],
+  review: ["retrieval", "mutation", "verification", "review"],
+  handoff: ["verification", "review", "handoff"],
+  terminal: []
+};
+
+const REQUIRED_HOST_TOOLS: Record<TrajectoryPhase, string[]> = {
+  intake: ["read", "grep", "find", "ls"],
+  scout: ["read", "grep", "find", "ls"],
+  plan: ["read", "grep", "find", "ls"],
+  execute: ["read", "grep", "find", "ls", "edit", "write", "apply_patch", "bash"],
+  verify: ["read", "bash"],
+  repair: ["read", "grep", "find", "ls", "edit", "write", "apply_patch", "bash"],
+  // Review needs a bounded read-only shell for git diff/status and similar
+  // current-tree inspection. Mutation authorization remains carrier-aware in
+  // PhaseToolRuntime.mutationDecision; exposing bash here does not authorize
+  // project writes.
+  review: ["read", "grep", "find", "ls", "bash"],
+  handoff: ["read"],
+  terminal: []
+};
+
+const PHASE_TOOL_ALLOW: Record<TrajectoryPhase, string[]> = {
+  intake: [],
+  scout: ["piagent_task_progress", "piagent_context_index_search", "piagent_document_read"],
+  plan: ["piagent_task_progress", "piagent_orchestration_policy"],
+  execute: ["piagent_task_progress"],
+  // Runtime hooks own context, verifier, gate, and handoff evidence. Keeping
+  // their record tools model-visible duplicates work and creates false manual
+  // choreography in otherwise automatic tasks.
+  verify: [],
+  repair: ["piagent_task_progress", "piagent_context_index_search"],
+  review: ["piagent_task_progress"],
+  handoff: [],
+  terminal: []
+};
+
+export type PhaseToolPolicy = {
+  phase: TrajectoryPhase;
+  changeMode: "source-change" | "read-only";
+  primaryGroups: PhaseToolGroup[];
+  modelVisiblePiagentTools: string[];
+  requiredHostTools: string[];
+  operatorTools: string[];
+  diagnosticTools: string[];
+};
+
+export function phaseToolPolicy(phase: TrajectoryPhase, changeMode: PhaseToolPolicy["changeMode"]): PhaseToolPolicy {
+  const primaryGroups = PHASE_GROUP_POLICY[phase];
+  const readOnlySurface = changeMode === "read-only" || phase === "review";
+  const modelVisiblePiagentTools = PIAGENT_TOOL_ORDER.filter((tool) => {
+    const group = PIAGENT_PRIMARY_TOOL_GROUP[tool as keyof typeof PIAGENT_PRIMARY_TOOL_GROUP];
+    return PHASE_TOOL_ALLOW[phase].includes(tool)
+      && primaryGroups.includes(group)
+      && !PIAGENT_OPERATOR_TOOLS.has(tool)
+      && !PIAGENT_DIAGNOSTIC_TOOLS.has(tool)
+      && (!readOnlySurface || !PIAGENT_MUTATION_CAPABLE_TOOLS.has(tool));
+  });
+  const requiredHostTools = REQUIRED_HOST_TOOLS[phase].filter((tool) => !(readOnlySurface && ["edit", "write", "apply_patch"].includes(tool)));
+  return {
+    phase,
+    changeMode,
+    primaryGroups: [...primaryGroups],
+    modelVisiblePiagentTools,
+    requiredHostTools,
+    operatorTools: PIAGENT_TOOL_ORDER.filter((tool) => PIAGENT_OPERATOR_TOOLS.has(tool)),
+    diagnosticTools: PIAGENT_TOOL_ORDER.filter((tool) => PIAGENT_DIAGNOSTIC_TOOLS.has(tool))
+  };
+}
+
+export function phaseToolPolicyErrors(): string[] {
+  const errors: string[] = [];
+  const classified = Object.keys(PIAGENT_PRIMARY_TOOL_GROUP);
+  for (const tool of PIAGENT_TOOL_ORDER) if (!(tool in PIAGENT_PRIMARY_TOOL_GROUP)) errors.push(`missing primary group: ${tool}`);
+  for (const tool of classified) if (!PIAGENT_TOOL_NAMES.has(tool)) errors.push(`unknown classified tool: ${tool}`);
+  if (new Set(classified).size !== classified.length) errors.push("primary tool classification contains duplicates");
+  for (const group of PHASE_TOOL_GROUPS) if (!Object.values(PIAGENT_PRIMARY_TOOL_GROUP).includes(group)) errors.push(`primary group has no tool: ${group}`);
+  return errors;
+}

package/packages/piagent-core/runtime/trajectory/trajectory-observability.ts

@@ -0,0 +1,38 @@
+import crypto from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { TrajectorySyncResult } from "./trajectory-runtime.ts";
+
+const reportedRecovery = new Set<string>();
+
+export function observeTrajectorySync(
+  ctx: ExtensionContext,
+  result: TrajectorySyncResult | undefined,
+  telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void
+): void {
+  if (!result) return;
+  if (!result.enforcementSafe) {
+    const warning = result.warnings[0] ?? "Trajectory state is corrupt; phase enforcement is disabled.";
+    const key = crypto.createHash("sha256").update(`${ctx.cwd}\0${warning}`).digest("hex");
+    if (!reportedRecovery.has(key)) {
+      reportedRecovery.add(key);
+      while (reportedRecovery.size > 100) reportedRecovery.delete(reportedRecovery.values().next().value as string);
+      ctx.ui.notify(`Piagent trajectory needs recovery; phase enforcement is disabled: ${warning}`, "warning");
+    }
+    return;
+  }
+  for (const transition of result.transitions) {
+    telemetry(ctx, {
+      event: "trajectory_transition",
+      taskId: transition.taskId,
+      taskRunId: transition.taskRunId,
+      eventId: transition.eventId,
+      sequence: transition.sequence,
+      from: transition.from,
+      to: transition.to,
+      cause: transition.cause,
+      sourceHook: transition.sourceHook,
+      skippedPhases: transition.skippedPhases
+    });
+  }
+}

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

@@ -0,0 +1,235 @@
+import crypto from "node:crypto";
+
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { runtimeAutomaticSourceExecutionReady, sourceExecutionAuthorized, sourcePlanningAuthorized } from "../../extensions/task-lifecycle.js";
+import { latestObservedVerification, verificationEvidenceProvesStableTree } from "../../extensions/verification-intelligence.js";
+import { workingTreeEvidenceDigest } from "../../extensions/working-tree-digest.js";
+import { createTrajectoryState, createTrajectoryTransition, reduceTrajectory, trajectoryPath } from "./trajectory-state.ts";
+import { appendTrajectoryTransition, readTrajectoryStore, writeTrajectoryState } from "./trajectory-store.ts";
+import type { TrajectoryRecommendationRef, TrajectorySourceHook, TrajectoryState, TrajectoryTransitionEvent } from "./trajectory-types.ts";
+import type { SolverDecision } from "../solver/solver-types.ts";
+
+export type TrajectorySyncOptions = {
+  sourceHook: TrajectorySourceHook;
+  observedAt?: string;
+  verificationStarted?: boolean;
+  contextObserved?: boolean;
+  handoffObserved?: boolean;
+  recoveryMutationAllowed?: boolean;
+  recoveryRequested?: boolean;
+  recommendationRef?: TrajectoryRecommendationRef | null;
+};
+
+export type TrajectorySyncResult = {
+  status: "ok" | "corrupt";
+  initialized: boolean;
+  enforcementSafe: boolean;
+  state?: TrajectoryState;
+  transitions: TrajectoryTransitionEvent[];
+  warnings: string[];
+};
+
+export type TrajectoryStatus = { taskRunId: string | null; phase: TrajectoryState["currentPhase"] | null; enforcementSafe: boolean; warnings: string[] };
+
+function digest(value: unknown): string {
+  return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+export function trajectoryRecommendationRef(decision: SolverDecision): TrajectoryRecommendationRef {
+  return {
+    solverPolicyVersion: decision.policyVersion,
+    featureHash: decision.featureHash,
+    route: decision.route,
+    decisionDigest: digest(decision)
+  };
+}
+
+function latestVerification(task: TaskContract): TaskContract["verifyEvidence"][number] | undefined {
+  return latestObservedVerification(task.verifyEvidence) ?? undefined;
+}
+
+function stepObserved(task: TaskContract, ids: string[]): boolean {
+  return task.workPlan.some((step) => ids.includes(step.id) && step.status !== "pending");
+}
+
+function phaseObservation(
+  task: TaskContract,
+  phase: string,
+  options: TrajectorySyncOptions,
+  currentTreeDigest?: string | null
+): TrajectoryTransitionEvent["cause"] | undefined {
+  const latest = latestVerification(task);
+  if (phase === "scout" && (options.contextObserved === true || task.contextManifest.length > 0 || stepObserved(task, ["scope", "challenge", "scout"]))) return "context-observed";
+  if (phase === "plan" && stepObserved(task, ["plan"])) return "plan-observed";
+  if (phase === "execute") {
+    if (sourceExecutionAuthorized(task)) return "execution-authorized";
+    if (task.observedChangedFiles.length > 0) return "mutation-observed";
+  }
+  if (phase === "verify") {
+    if (options.verificationStarted === true) return "verification-started";
+    if (verificationEvidenceProvesStableTree(latest, currentTreeDigest)) return "verification-passed";
+  }
+  if (phase === "review" && stepObserved(task, ["review"])) return "review-observed";
+  if (phase === "handoff" && options.handoffObserved === true) return "handoff-observed";
+  return undefined;
+}
+
+function treeDigest(task: TaskContract): string | null {
+  const snapshot = task.finalFileDigests ?? {};
+  return Object.keys(snapshot).length > 0 ? workingTreeEvidenceDigest(snapshot) : null;
+}
+
+function recordTransition(cwd: string, state: TrajectoryState, event: TrajectoryTransitionEvent): TrajectoryState {
+  const next = reduceTrajectory(state, event);
+  appendTrajectoryTransition(cwd, event);
+  return writeTrajectoryState(cwd, next);
+}
+
+export class TrajectoryRuntime {
+  status(cwd: string, taskRunId: string | undefined): TrajectoryStatus {
+    if (!taskRunId) return { taskRunId: null, phase: null, enforcementSafe: true, warnings: [] };
+    const stored = readTrajectoryStore(cwd, taskRunId);
+    return { taskRunId, phase: stored.state?.currentPhase ?? null, enforcementSafe: stored.enforcementSafe, warnings: stored.warnings };
+  }
+
+  syncOptional(cwd: string, sessionId: string, task: TaskContract | undefined, options: TrajectorySyncOptions): TrajectorySyncResult | undefined {
+    return task ? this.sync(cwd, sessionId, task, options) : undefined;
+  }
+
+  sync(cwd: string, sessionId: string, task: TaskContract, options: TrajectorySyncOptions): TrajectorySyncResult {
+    const stored = readTrajectoryStore(cwd, task.taskRunId);
+    if (!stored.enforcementSafe) return { status: "corrupt", initialized: false, enforcementSafe: false, transitions: [], warnings: stored.warnings };
+    let initialized = false;
+    let state = stored.state;
+    if (!state) {
+      state = createTrajectoryState({
+        taskId: task.taskId,
+        taskRunId: task.taskRunId,
+        sessionId,
+        changeMode: task.changeMode,
+        riskLane: task.riskLane,
+        recommendationRef: options.recommendationRef ?? null,
+        createdAt: task.createdAt
+      });
+      state = writeTrajectoryState(cwd, state);
+      initialized = true;
+    } else if (stored.recoveredEvents > 0) {
+      state = writeTrajectoryState(cwd, state);
+    }
+    if (state.recommendationRef === null && options.recommendationRef) {
+      state = writeTrajectoryState(cwd, { ...state, recommendationRef: options.recommendationRef });
+    }
+    const transitions: TrajectoryTransitionEvent[] = [];
+    const observedAt = options.observedAt ?? new Date().toISOString();
+    const taskDigest = digest(task), currentTreeDigest = treeDigest(task);
+    const latest = latestVerification(task);
+    if (state.currentPhase === "intake" && sourcePlanningAuthorized(task)) {
+      const path = trajectoryPath(state.changeMode, state.riskLane);
+      const planIndex = path.indexOf("plan");
+      const skippedPhases = planIndex > 1 ? path.slice(1, planIndex) : [];
+      if (skippedPhases.length > 0) {
+        const event = createTrajectoryTransition(state, {
+          to: "plan",
+          cause: "explicit-skip",
+          sourceHook: options.sourceHook,
+          taskDigest,
+          treeDigest: currentTreeDigest,
+          skippedPhases,
+          skipReason: "The persisted work plan starts with a manual plan checkpoint and defines no separate scout checkpoint.",
+          observedAt
+        });
+        state = recordTransition(cwd, state, event);
+        transitions.push(event);
+      }
+    }
+    if (state.currentPhase === "intake" && runtimeAutomaticSourceExecutionReady(task)) {
+      const path = trajectoryPath(state.changeMode, state.riskLane);
+      const executeIndex = path.indexOf("execute");
+      const skippedPhases = executeIndex > 0 ? path.slice(1, executeIndex) : [];
+      const event = createTrajectoryTransition(state, {
+        to: "execute",
+        cause: "execution-authorized",
+        sourceHook: options.sourceHook,
+        taskDigest,
+        treeDigest: currentTreeDigest,
+        skippedPhases,
+        skipReason: skippedPhases.length > 0
+          ? "Runtime-owned automatic work plan has no manual plan checkpoint and its contract, scope, and exact verifier are ready."
+          : null,
+        observedAt
+      });
+      state = recordTransition(cwd, state, event);
+      transitions.push(event);
+    }
+    if (
+      options.recoveryRequested === true
+      && options.recoveryMutationAllowed === true
+      && ["execute", "verify", "review"].includes(state.currentPhase)
+    ) {
+      const event = createTrajectoryTransition(state, {
+        to: "repair",
+        cause: "recovery-requested",
+        sourceHook: options.sourceHook,
+        taskDigest,
+        treeDigest: currentTreeDigest,
+        observedAt
+      });
+      state = recordTransition(cwd, state, event);
+      transitions.push(event);
+    }
+    const verificationFailed = Boolean(latest && latest.observed === true && (latest.isError === true || latest.exitCode !== 0));
+    if (verificationFailed && options.recoveryMutationAllowed !== false && ["execute", "verify", "review"].includes(state.currentPhase)) {
+      const event = createTrajectoryTransition(state, { to: "repair", cause: "verification-failed", sourceHook: options.sourceHook, taskDigest, treeDigest: currentTreeDigest, observedAt });
+      state = recordTransition(cwd, state, event);
+      transitions.push(event);
+    }
+    const passingVerifierAfterRepair = verificationEvidenceProvesStableTree(latest, currentTreeDigest)
+      && Date.parse(String(latest?.observedAt ?? latest?.recordedAt)) >= Date.parse(state.updatedAt);
+    if (state.currentPhase === "repair" && (options.verificationStarted || passingVerifierAfterRepair)) {
+      const event = createTrajectoryTransition(state, { to: "verify", cause: "verification-started", sourceHook: options.sourceHook, taskDigest, treeDigest: currentTreeDigest, observedAt });
+      state = recordTransition(cwd, state, event);
+      transitions.push(event);
+    }
+    const path = trajectoryPath(state.changeMode, state.riskLane);
+    while (state.currentPhase !== "terminal") {
+      const currentIndex = path.indexOf(state.currentPhase);
+      const next = currentIndex >= 0 ? path[currentIndex + 1] : undefined;
+      const cause = next && next !== "terminal" ? phaseObservation(task, next, options, currentTreeDigest) : undefined;
+      if (!next || next === "terminal" || !cause) break;
+      const event = createTrajectoryTransition(state, { to: next, cause, sourceHook: options.sourceHook, taskDigest, treeDigest: currentTreeDigest, observedAt });
+      state = recordTransition(cwd, state, event);
+      transitions.push(event);
+    }
+    if (task.trace.outcome !== "pending" && state.currentPhase !== "terminal") {
+      const currentIndex = path.indexOf(state.currentPhase);
+      const skippedPhases = currentIndex >= 0 ? path.slice(currentIndex + 1, -1) : [];
+      const terminalRef = { taskRunId: task.taskRunId, taskUpdatedAt: task.updatedAt, taskDigest };
+      const event = createTrajectoryTransition(state, {
+        to: "terminal",
+        cause: "task-terminal",
+        sourceHook: options.sourceHook,
+        taskDigest,
+        treeDigest: currentTreeDigest,
+        skippedPhases,
+        skipReason: skippedPhases.length > 0 ? "Task Contract reached a terminal outcome before remaining trajectory phases." : null,
+        observedAt,
+        terminalTaskOutcomeRef: terminalRef
+      });
+      state = recordTransition(cwd, state, event);
+      transitions.push(event);
+    }
+    return { status: "ok", initialized, enforcementSafe: true, state, transitions, warnings: stored.warnings };
+  }
+
+  syncToolCall(cwd: string, sessionId: string, task: TaskContract, event: { toolName: string; input?: unknown }, observedAt?: string): TrajectorySyncResult {
+    const input = event.input && typeof event.input === "object" && !Array.isArray(event.input) ? event.input as Record<string, unknown> : {};
+    const command = String(input.command ?? input.cmd ?? "").trim();
+    const verificationStarted = command.length > 0 && task.verifyCommands.some((candidate) => candidate.trim() === command);
+    const handoffObserved = event.toolName === "piagent_trace_record";
+    return this.sync(cwd, sessionId, task, { sourceHook: "tool-call", observedAt, verificationStarted, handoffObserved });
+  }
+
+  syncOptionalToolCall(cwd: string, sessionId: string, task: TaskContract | undefined, event: { toolName: string; input?: unknown }, observedAt?: string): TrajectorySyncResult | undefined {
+    return task ? this.syncToolCall(cwd, sessionId, task, event, observedAt) : undefined;
+  }
+}