@piagent/platform 1.6.1 → 1.7.1

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

@@ -4,10 +4,11 @@ import { WORKING_TREE_DIGEST_ALGORITHM } from "../../extensions/working-tree-dig
 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";
-import { resolveTaskStartRepositoryManifestProvider } from "./task-start-manifest.ts"; import { boundedOperatorRequest, latestOperatorRequest } from "./operator-request-intake.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 {
@@ -16,7 +17,7 @@ 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, resolveOrchestrationPolicy, resolveTaskScopePatterns, runtimeLifecycleMode, runtimeState, safeTaskId, selectVerificationPlan,
     summarizeAttempt, telemetry, validTaskScopePattern, validateNewWorkPlan, verifierCommandInstructions, workingTreeEvidenceDigest, workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence,
@@ -30,7 +31,7 @@ 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 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.",
@@ -44,7 +45,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       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, 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 }),
@@ -227,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." }],
@@ -288,7 +291,8 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       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,
@@ -396,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)
@@ -413,19 +408,25 @@ 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 = 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()}`,
       {
@@ -435,9 +436,8 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         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)

package/packages/piagent-core/runtime/registration/workflow-commands.ts

@@ -1,94 +1,52 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  WORKFLOW_OPTIONS,
+  type WorkflowId,
+  resolveWorkflowId,
+  workflowCommandNames,
+  workflowHelpLines,
+  workflowOption
+} from "../workflows/webui-workflow.ts";
+import { buildOnboardingWorkflowPrompt, buildWorkflowFollowUp } from "../workflows/workflow-follow-up.ts";
+
+import type { TaskContract } from "../../extensions/guard-types.js";
+import { activeSessionTask } from "../../extensions/task-state.js";
+import { isUncertainSendContinuation, terminalUncertainSendReceipt } from "../session/uncertain-send-continuation.ts";
 
 type ExtensionContext = any;
 
 export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string, any>): any {
   const {
-    FRESH_COMMAND_ACTIONS, FRESH_COMMAND_HELP, ONBOARDING_COMMAND_ACTIONS, WORKFLOW_COMMAND_EXCLUSIONS, buildContextIndexStatus,
+    ONBOARDING_COMMAND_ACTIONS, WORKFLOW_COMMAND_EXCLUSIONS, buildContextIndexStatus,
     buildUsageSnapshot, commandArgs, emitProfileStatus, emitProfileTechStatus, emitRuntimeMessage,
     fs, loadProfileFromContext, prefixCompletions, projectContextFilePath, projectProfilePath,
     registerRuntimeCommand, resolveMemorySettings, runProfileTechWizard, selectRuntimeAction, sendWorkflowFollowUp,
     freshRequestParts, shortTaskLabel, techStackPath
   } = deps;
-  type WorkflowCommandName = "task" | "scout" | "be-to-fe" | "discuss" | "plan" | "review" | "platform-improve" | "commit" | "pr" | "onboard";
-
-  const WORKFLOW_ALIASES: Record<string, WorkflowCommandName> = {
-    task: "task",
-    implement: "task",
-    scout: "scout",
-    audit: "scout",
-    "be-to-fe": "be-to-fe",
-    befe: "be-to-fe",
-    discuss: "discuss",
-    clarify: "discuss",
-    plan: "plan",
-    review: "review",
-    "platform-improve": "platform-improve",
-    platform: "platform-improve",
-    commit: "commit",
-    pr: "pr",
-    onboard: "onboard",
-    "onboard-project": "onboard"
-  };
-
   function workflowChoices(): Array<{ value: string; label: string; description: string; recommended?: boolean }> {
     return [
-      { value: "task", label: "Task", description: "Implement a bounded task", recommended: true },
-      { value: "scout", label: "Scout", description: "Read-only audit/research" },
-      { value: "be-to-fe", label: "BE to FE", description: "Backend read-only, frontend implementation" },
-      { value: "discuss", label: "Discuss", description: "Clarify before planning/editing" },
-      { value: "plan", label: "Plan", description: "Create an implementation plan" },
-      { value: "review", label: "Review", description: "Review diff/source read-only" },
-      { value: "commit", label: "Commit", description: "Guarded local commit workflow" },
-      { value: "pr", label: "PR", description: "Guarded pull request preparation" },
-      { value: "onboard", label: "Onboard", description: "First-read project onboarding scout" },
-      { value: "platform-improve", label: "Platform", description: "Improve Pi Agent Platform itself" },
+      ...WORKFLOW_OPTIONS.map((option) => ({
+        value: option.id,
+        label: option.label,
+        description: option.description,
+        ...(option.id === "task" ? { recommended: true } : {})
+      })),
       { value: "help", label: "Help", description: "Show typed workflow forms" }
     ];
   }
 
-  function buildOnboardingWorkflowPrompt(focus: string): string {
-    return [
-      "Run the Pi Agent Platform first-read onboarding workflow for this repository.",
-      "",
-      `Optional focus: ${focus.trim() || "whole repository"}`,
-      "",
-      "Preconditions:",
-      "- The operator has logged in and selected the intended model/thinking level.",
-      "- Stay read-only except writing Piagent onboarding state through piagent tools.",
-      "",
-      "Mandatory flow:",
-      "1. Call piagent_context with detail=full.",
-      "2. If the project is unprofiled, call piagent_profile_options, do a lightweight root scout, recommend a profile, and use piagent_profile_apply only after the operator choice is clear.",
-      "3. Prefer /profile setup or piagent_profile_tech_options + piagent_profile_tech_apply for tech stack selection.",
-      "4. Re-call piagent_context after profile/tech changes.",
-      "5. Call piagent_memory_status and treat memory as advisory.",
-      "6. Read AGENTS.md, README/package/build config, required context, docs/architecture files, source map, and verify command definitions. Do not ingest the whole repo.",
-      "7. Identify project purpose, stack/runtime, ownership boundaries, high-risk areas, protected paths, verify commands, MCP/tool capabilities, selected tech stack, memory policy, and conventions.",
-      "8. Write a concise .pi/project-context.md snapshot and record it with piagent_project_onboarding_record so .pi/context-index.json is generated.",
-      "9. Call piagent_context_index_status and report pending/stale warnings.",
-      "",
-      "Final output: profile, tech stack, context files read, verification matrix, high-risk areas, context-index status, memory status, and any missing operator decisions."
-    ].join("\n");
-  }
-
   function emitWorkflowHelp(ctx: ExtensionContext): void {
-    emitRuntimeMessage(ctx, "piagent-workflow-help", [
-      "namespace: /workflow",
-      "daily: /workflow task <request>",
-      "readOnly: /workflow scout <area/spec/risk>",
-      "beToFe: /workflow be-to-fe <BE spec/change + FE outcome>",
-      "clarify: /workflow discuss <rough idea>",
-      "plan: /workflow plan <goal>",
-      "review: /workflow review <target or diff>",
-      "git: /workflow commit [message] | /workflow pr [title]",
-      "onboard: /workflow onboard [focus]",
-      "aliases still work: /task, /scout, /be-to-fe, /commit, /pr"
-    ].join("\n"), { workflows: workflowChoices().map((choice) => choice.value) });
+    emitRuntimeMessage(ctx, "piagent-workflow-help", workflowHelpLines().join("\n"), {
+      workflows: WORKFLOW_OPTIONS.map((option) => option.id)
+    });
   }
 
   async function runWorkflowNamespace(raw: string, ctx: ExtensionContext): Promise<void> {
     const { action, rest } = commandArgs(raw);
+    if (action === "help") {
+      emitWorkflowHelp(ctx);
+      return;
+    }
     if (!action) {
       const chosen = await selectRuntimeAction(ctx, "Piagent workflow", workflowChoices(), "task");
       if (!chosen || chosen === "help") {
@@ -107,8 +65,8 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
       ].join("\n"), { workflow: chosen });
       return;
     }
-    const workflow = WORKFLOW_ALIASES[action];
-    if (!workflow || workflow === undefined) {
+    const workflow = resolveWorkflowId(action);
+    if (!workflow) {
       emitRuntimeMessage(ctx, "piagent-workflow-error", `unknown workflow: ${action}\nRun /workflow help`, { action }, { message: `Unknown workflow: ${action}`, level: "warning" });
       return;
     }
@@ -117,7 +75,7 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
       ctx.ui.notify("Workflow launched: onboard", "info");
       return;
     }
-    if (!rest.trim()) {
+    if (!rest.trim() && workflowOption(workflow)?.requestRequired !== false) {
       emitRuntimeMessage(ctx, "piagent-workflow-needs-request", [
         `workflow: ${workflow}`,
         `run: /workflow ${workflow} <request>`,
@@ -125,7 +83,13 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
       ].join("\n"), { workflow });
       return;
     }
-    sendWorkflowFollowUp(`/${workflow} ${rest}`);
+    // Namespace commands run before the input hook. Recover a current durable
+    // receipt here so their deferred extension prompt cannot open a model turn.
+    if (isUncertainSendContinuation(rest) && ctx.isIdle()) {
+      const receipt = terminalUncertainSendReceipt(ctx.cwd, activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined);
+      if (receipt) { emitRuntimeMessage(ctx, receipt.customType, receipt.content, receipt.details); return; }
+    }
+    sendWorkflowFollowUp(buildWorkflowFollowUp(workflow, rest));
     ctx.ui.notify(`Workflow launched: ${workflow}`, "info");
   }
 
@@ -150,20 +114,16 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
     const sections: Record<string, string[]> = {
       overview: [
         "Piagent command surface:",
-        "runtime: /workflow | /piagent-inspector | /usage | /context | /permission | /commands | /profile | /memory | /onboard | /fresh",
+        "runtime: /workflow | /piagent-inspector | /usage | /context | /permission | /fast | /commands | /profile | /memory | /onboard | /fresh",
         "native: /model | /name | /session | /resume | /compact | /mcp",
-        "workflow: /workflow task|scout|be-to-fe|review|commit|pr <request>",
+        `workflow: /workflow ${WORKFLOW_OPTIONS.map((option) => option.id).join("|")} <request>`,
         "mcp: /mcp is Pi native; governed MCP checks stay at /piagent-mcp to avoid collision",
         "legacy: /piagent-* commands still work where they existed",
         "principle: runtime commands run immediately; workflows intentionally launch an agent turn"
       ],
       workflow: [
         "Workflow entrypoint:",
-        "/workflow",
-        "/workflow task <request>",
-        "/workflow scout <read-only request>",
-        "/workflow be-to-fe <BE spec/change + FE outcome>",
-        "/workflow onboard [focus]"
+        ...workflowHelpLines()
       ],
       usage: [
         "Usage/session:",
@@ -171,7 +131,7 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
         "/piagent-inspector",
         "/usage history",
         "Pi native: /name <task name>",
-        "/fresh task|scout|be-to-fe <request>",
+        `/fresh ${WORKFLOW_OPTIONS.map((option) => option.id).join("|")} <request>`,
         "native: /session | /resume"
       ],
       context: [
@@ -193,8 +153,16 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
         "Model:",
         "/model or Ctrl+L opens Pi native selector",
         "/model-options shows local Piagent model guidance",
+        "/fast status|on|off controls the OpenAI Codex Fast service tier without changing model/thinking",
         "Ctrl+P cycles model scope; Shift+Tab cycles thinking"
       ],
+      fast: [
+        "Fast service tier:",
+        "/fast status",
+        "/fast on",
+        "/fast off",
+        "Fast is a zero-model-turn session setting; model/thinking stay unchanged and provider quota or pricing may differ"
+      ],
       memory: [
         "Memory:",
         "/memory",
@@ -240,6 +208,7 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
       { value: "context", label: "Context", description: "Index/search/preflight/compact" },
       { value: "permission", label: "Permission", description: "Read/write/full access controls" },
       { value: "model", label: "Model", description: "Native model selector and thinking" },
+      { value: "fast", label: "Fast mode", description: "Status and OpenAI Codex Fast service tier control" },
       { value: "mcp", label: "MCP", description: "Governed MCP commands" },
       { value: "subagents", label: "Subagents", description: "Health, fleet, cost" },
       { value: "terminal", label: "Terminal", description: "piagent-* helpers" }
@@ -339,7 +308,7 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
   registerRuntimeCommand(pi, "workflow", {
     description: "One menu for Piagent task, scout, review, git, and onboarding workflows",
     getArgumentCompletions: (prefix: string) => prefixCompletions(
-      Object.keys(WORKFLOW_ALIASES).filter((name) => !WORKFLOW_COMMAND_EXCLUSIONS.includes(name)),
+      workflowCommandNames().filter((name) => !WORKFLOW_COMMAND_EXCLUSIONS.includes(name)),
       prefix
     ),
     handler: async (args, ctx) => {
@@ -376,16 +345,16 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
     handler: async (args, ctx) => runOnboardingCommand(String(args ?? ""), ctx)
   });
 
-  async function startFreshWorkflow(workflow: "task" | "scout" | "be-to-fe", args: string, ctx: any) {
+  async function startFreshWorkflow(workflow: WorkflowId, args: string, ctx: any) {
     const parsed = freshRequestParts(String(args ?? ""));
     const request = parsed.request;
-    if (!request) {
+    if (!request && workflowOption(workflow)?.requestRequired !== false) {
       ctx.ui.notify(`Usage: /fresh ${workflow} <request>`, "warning");
       return;
     }
 
-    const label = parsed.sessionTitle ?? shortTaskLabel(request);
-    const command = `/${workflow} ${request}`;
+    const label = parsed.sessionTitle ?? shortTaskLabel(request || workflow);
+    const command = [`/${workflow}`, request].filter(Boolean).join(" ");
     const result = await ctx.newSession({
       withSession: async (nextCtx) => {
         pi.setSessionName(`pi:${label}`);
@@ -398,18 +367,20 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
   }
 
   registerRuntimeCommand(pi, "fresh", {
-    description: "Open a fresh governed session for task, scout, or BE-to-FE work",
-    getArgumentCompletions: (prefix: string) => prefixCompletions(FRESH_COMMAND_ACTIONS, prefix),
+    description: "Open a fresh governed session for any Piagent workflow",
+    getArgumentCompletions: (prefix: string) => prefixCompletions([...workflowCommandNames({ aliases: false }), "help"], prefix),
     handler: async (args, ctx) => {
       const { action, rest } = commandArgs(String(args ?? ""));
       if (!action || action === "help") {
-        emitRuntimeMessage(ctx, "piagent-fresh-help", FRESH_COMMAND_HELP.join("\n"));
+        emitRuntimeMessage(ctx, "piagent-fresh-help", [
+          "namespace: /fresh",
+          ...WORKFLOW_OPTIONS.map((option) => `/fresh ${option.id} ${option.argumentHint}`)
+        ].join("\n"));
         return;
       }
-      const workflow = action === "be-to-fe" ? "be-to-fe" : action === "scout" ? "scout" : "task";
-      const request = action === "task" || action === "scout" || action === "be-to-fe"
-        ? rest
-        : [action, rest].filter(Boolean).join(" ");
+      const resolved = resolveWorkflowId(action);
+      const workflow = resolved ?? "task";
+      const request = resolved ? rest : [action, rest].filter(Boolean).join(" ");
       await startFreshWorkflow(workflow, request, ctx);
     }
   });

package/packages/piagent-core/runtime/session/completion-signals.ts

@@ -0,0 +1,23 @@
+function normalizeLanguageSignal(text: string): string {
+  // Preserve the Vietnamese progressive phrase before removing tone marks.
+  // Without this, both "đang làm" (still working) and "đáng làm" (worth doing)
+  // collapse to `dang lam`, so a perfectly final heading such as
+  // "Các ứng dụng đáng làm" is misclassified as an incomplete handoff.
+  const progressive = text.normalize("NFC").toLowerCase().replace(/đang\s+làm/gu, " piagent_in_progress ");
+  return progressive
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .replaceAll("đ", "d");
+}
+
+export function looksLikeIncompleteHandoff(text: string): boolean {
+  const normalized = normalizeLanguageSignal(text);
+  return /\b(?:not done|not complete|not finished|still working|blocked|cannot complete|unable to complete|need clarification|tests? (?:fail|failed|failing)|verification (?:fail|failed|failing)|chua xong|chua hoan tat|chua hoan thanh|piagent_in_progress|(?:van|piagent|agent|em|toi|minh|chung toi) dang (?:lam|xu ly)|bi chan|can lam them|test (?:loi|fail))\b/.test(normalized);
+}
+
+export function looksLikeCompletionClaim(text: string): boolean {
+  const normalized = normalizeLanguageSignal(text);
+  if (!normalized.trim() || normalized.includes("[piagent completion gate:")) return false;
+  if (looksLikeIncompleteHandoff(text)) return false;
+  return /\b(?:done|completed|complete|finished|fixed|implemented|resolved|shipped|all tests pass(?:ed)?|tests? pass(?:ed)?|da xong|da sua|da fix|da hoan tat|da hoan thanh|da trien khai|test da pass|kiem tra da pass|ready\b[\s\S]{0,48}\b(?:test|review|use|ship)|san sang\b[\s\S]{0,48}\b(?:test|kiem tra|su dung))\b/.test(normalized);
+}

package/packages/piagent-core/runtime/session/message-signals.ts

@@ -1,5 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+export { looksLikeCompletionClaim, looksLikeIncompleteHandoff } from "./completion-signals.ts";
+
 export function assistantMessageText(message: unknown): string {
   if (!message || typeof message !== "object" || (message as { role?: unknown }).role !== "assistant") return "";
   const content = (message as { content?: unknown }).content;
@@ -15,28 +17,10 @@ export function assistantMessageHasToolCall(message: unknown): boolean {
   return Array.isArray(content) && content.some((item) => item && typeof item === "object" && (item as { type?: unknown }).type === "toolCall");
 }
 
-function normalizeLanguageSignal(text: string): string {
-  // Preserve the Vietnamese progressive phrase before removing tone marks.
-  // Without this, both "đang làm" (still working) and "đáng làm" (worth doing)
-  // collapse to `dang lam`, so a perfectly final heading such as
-  // "Các ứng dụng đáng làm" is misclassified as an incomplete handoff.
-  const progressive = text.normalize("NFC").toLowerCase().replace(/đang\s+làm/gu, " piagent_in_progress ");
-  return progressive
-    .normalize("NFKD")
-    .replace(/\p{M}/gu, "")
-    .replaceAll("đ", "d");
-}
-
-export function looksLikeIncompleteHandoff(text: string): boolean {
-  const normalized = normalizeLanguageSignal(text);
-  return /\b(?:not done|not complete|not finished|still working|blocked|cannot complete|unable to complete|need clarification|tests? (?:fail|failed|failing)|verification (?:fail|failed|failing)|chua xong|chua hoan tat|chua hoan thanh|piagent_in_progress|(?:van|piagent|agent|em|toi|minh|chung toi) dang (?:lam|xu ly)|bi chan|can lam them|test (?:loi|fail))\b/.test(normalized);
-}
-
-export function looksLikeCompletionClaim(text: string): boolean {
-  const normalized = normalizeLanguageSignal(text);
-  if (!normalized.trim() || normalized.includes("[piagent completion gate:")) return false;
-  if (looksLikeIncompleteHandoff(text)) return false;
-  return /\b(?:done|completed|complete|finished|fixed|implemented|resolved|shipped|all tests pass(?:ed)?|tests? pass(?:ed)?|da xong|da sua|da fix|da hoan tat|da hoan thanh|da trien khai|test da pass|kiem tra da pass)\b/.test(normalized);
+export function prependAssistantNotice<T extends { content?: unknown }>(message: T, notice: string) {
+  const content = Array.isArray(message.content) ? [{ type: "text" as const, text: notice }, ...message.content]
+    : [{ type: "text" as const, text: `${notice}${typeof message.content === "string" ? message.content : assistantMessageText(message)}` }];
+  return { ...message, content };
 }
 
 export function modelLabel(ctx: ExtensionContext): string {