@piagent/platform 1.8.0 → 1.9.1

package/packages/piagent-core/runtime/hooks/input-hook.ts

@@ -5,34 +5,12 @@ import { matchesProtectedPath } from "../../extensions/policy-core.js";
 import type { TaskContract } from "../../extensions/guard-types.js";
 import { attachLocalImagesFromText, extractLocalImagePathCandidates } from "../input/chat-images.ts";
 import type { ChatImageAccessPolicy } from "../input/chat-images.ts";
-import { LONG_INPUT_CHARS } from "../runtime-limits.ts";
 import type { AuthorityResumeDecision } from "../policy/authority-resume-policy.ts";
-import { buildHandoffProjection, writeHandoffProjection } from "../recovery/handoff-projection.ts";
-import {
-  isUncertainSendContinuation,
-  terminalUncertainSendReceipt
-} from "../session/uncertain-send-continuation.ts";
-import { buildContextPreflight, buildUsageSnapshot } from "../session/usage.ts";
 import { registerAdaptiveContextGovernor } from "../session/adaptive-context-governor.ts";
-import { activeTaskToolGroups, toolGroupsForPrompt, PIAGENT_TOOL_NAMES, PIAGENT_TOOL_ORDER, PIAGENT_TOOL_GROUPS } from "../tools/tool-groups.ts";
+import { toolGroupsForPrompt, PIAGENT_TOOL_NAMES, PIAGENT_TOOL_ORDER, PIAGENT_TOOL_GROUPS } from "../tools/tool-groups.ts";
 import type { PiagentToolGroup } from "../tools/tool-groups.ts";
 import type { RuntimeSessionState } from "../session/runtime-state.ts";
 import { observeHostWireInput } from "../session/runtime-state.ts";
-import {
-  buildFreshCommand,
-  agentStartTaskRequest,
-  chooseFreshWorkflow,
-  extractTaskRequest,
-  isFreshOrUtilityInput,
-  isPiagentWorkflowInput,
-  looksLikeGovernedBoilerplate,
-  trimTaskForInline
-} from "../workflows/input-routing.ts";
-import {
-  automaticTaskIntakeMode,
-  isLightweightNonAuthorizingChangeContinuation,
-  manualTaskIntakeEligible
-} from "../workflows/task-intake.ts";
 
 type InputHookDependencies = {
   state: RuntimeSessionState;
@@ -54,191 +32,52 @@ export function projectPiagentWireInput(input: {
   const blocked = (reason: string) => ({ disposition: "blocked", reason });
   if (input.activeTask === undefined || !Array.isArray(input.readProtectedPaths)
     || typeof input.replacementIntake !== "boolean" || typeof input.dynamicToolsEnabled !== "boolean") return blocked("input-state-unfrozen");
-  const text = input.text.trim();
+  const text = input.text;
   if (input.hasImages !== false || extractLocalImagePathCandidates(text, "/").length > 0) return blocked("input-images-unprojected");
-  if (!text || isFreshOrUtilityInput(text) || /^\/piagent-workflow\b/i.test(text)) return blocked("input-transform-unprojected");
+  if (!text.trim()) return blocked("input-empty");
   if (!["rpc", "interactive", "extension"].includes(input.source)) return blocked("input-source-unfrozen");
-  if (input.source !== "extension" && (looksLikeGovernedBoilerplate(text) || isPiagentWorkflowInput(text)
-    || text.length >= LONG_INPUT_CHARS)) return blocked("input-preflight-unfrozen");
-  const signal = classifyContextTask(text), activeTask = input.activeTask?.trace.outcome === "pending" ? input.activeTask : undefined;
-  const onlyProtected = signal.paths.length > 0 && signal.paths.every((p) => matchesProtectedPath(p, input.readProtectedPaths));
-  const runtimeMode = !activeTask ? automaticTaskIntakeMode(text, input.readProtectedPaths) : undefined;
-  const manual = !activeTask && !runtimeMode && manualTaskIntakeEligible(text, input.readProtectedPaths);
-  const groups = onlyProtected ? [] : toolGroupsForPrompt(text).filter((group) => !runtimeMode || group !== "intake" && group !== "task");
-  if (manual && !groups.includes("intake")) groups.push("intake");
-  const selectedGroups = activeTask ? [...groups.filter((group) => input.replacementIntake || group !== "intake"),
-    ...(input.replacementIntake ? ["intake" as const] : activeTaskToolGroups(activeTask))] : groups;
+  const signal = classifyContextTask(text);
+  const protectedOnly = signal.paths.length > 0 && signal.paths.every((p) => matchesProtectedPath(p, input.readProtectedPaths));
+  const groups = protectedOnly ? [] : toolGroupsForPrompt(text).filter((g) => !["intake", "task", "recovery"].includes(g));
   const builtins = input.currentTools.filter((name) => !PIAGENT_TOOL_NAMES.has(name));
   if (builtins.includes("apply_patch")) {
-    const firstWriter = builtins.findIndex((name) => name === "edit" || name === "write");
-    if (firstWriter >= 0) { builtins.splice(builtins.indexOf("apply_patch"), 1); builtins.splice(builtins.findIndex((name) => name === "edit" || name === "write"), 0, "apply_patch"); }
+    const writer = builtins.findIndex((n) => n === "edit" || n === "write");
+    if (writer >= 0) { builtins.splice(builtins.indexOf("apply_patch"), 1); builtins.splice(builtins.findIndex((n) => n === "edit" || n === "write"), 0, "apply_patch"); }
   }
   const selectedTools = input.dynamicToolsEnabled ? [...builtins, ...PIAGENT_TOOL_ORDER.filter((name) =>
-    selectedGroups.some((group) => PIAGENT_TOOL_GROUPS[group].includes(name as never)))] : [...input.currentTools];
+    groups.some((group) => PIAGENT_TOOL_GROUPS[group].includes(name as never)))] : [...input.currentTools];
   if (selectedTools.some((name) => !input.availableToolNames.includes(name))) return blocked("tool-definition-missing");
-  const query = agentStartTaskRequest(input.expandedPrompt ?? text), querySignal = classifyContextTask(query);
-  const protectedQuery = querySignal.paths.length > 0 && querySignal.paths.every((p) => matchesProtectedPath(p, input.readProtectedPaths));
-  const agentStartRuntimeMode = !activeTask ? automaticTaskIntakeMode(query, input.readProtectedPaths) : undefined;
-  if (runtimeMode || agentStartRuntimeMode || input.replacementIntake) return blocked("automatic-task-state-unprojected");
-  if (activeTask && !input.phase) return blocked("current-task-phase-unfrozen");
-  return { disposition: "known", reason: null, groups: selectedGroups, selectedTools,
-    compactMode: protectedQuery ? "protected" : activeTask?.intakeMode === "runtime" ? "automatic" : null,
-    taskPresence: activeTask ? "current" : "none", phase: activeTask ? input.phase : null,
+  return { disposition: "known", reason: null, groups, selectedTools,
+    compactMode: protectedOnly ? "protected" : null, taskPresence: "none", phase: null,
     inputHash: signal.promptHash, inputText: text };
+
 }
 
 export function registerInputHook(pi: ExtensionAPI, dependencies: InputHookDependencies): void {
-  registerAdaptiveContextGovernor(pi, {
-    activeTask: dependencies.activeTask,
-    telemetry: dependencies.telemetry
-  });
-
+  registerAdaptiveContextGovernor(pi, { activeTask: () => undefined, telemetry: dependencies.telemetry });
   pi.on("input", async (event, ctx) => {
-    const text = event.text.trim();
-    if (!text || isFreshOrUtilityInput(text)) return { action: "continue" };
-    if (/^\/piagent-workflow\b/i.test(text)) {
-      return { action: "transform", text: text.replace(/^\/piagent-workflow\b/i, "/workflow") };
-    }
-
-    const taskSignal = classifyContextTask(text);
-    const sessionTask = dependencies.activeTask(ctx);
-    const uncertainSendContinuation = (!Array.isArray(event.images) || event.images.length === 0)
-      && isUncertainSendContinuation(text);
-    const terminalReceipt = uncertainSendContinuation
-      ? terminalUncertainSendReceipt(ctx.cwd, sessionTask)
-      : undefined;
-    if (terminalReceipt && event.source !== "extension") {
-      dependencies.telemetry(ctx, {
-        event: "uncertain_send_terminal_receipt_reemitted",
-        source: event.source,
-        promptHash: taskSignal.promptHash,
-        taskId: terminalReceipt.details.taskId,
-        taskRunId: terminalReceipt.details.taskRunId,
-        outcome: terminalReceipt.details.outcome,
-        completionApproved: terminalReceipt.details.completionApproved,
-        replacementTaskStarted: false,
-        replayed: false,
-        modelTurnStarted: false
-      });
-      pi.sendMessage(
-        {
-          customType: terminalReceipt.customType,
-          content: terminalReceipt.content,
-          display: true,
-          details: terminalReceipt.details
-        },
-        { triggerTurn: false }
-      );
-      return { action: "handled" };
-    }
-    if (!uncertainSendContinuation) {
-      if (sessionTask && sessionTask.trace.outcome !== "pending") dependencies.state.clearTaskBoundary(ctx, sessionTask.taskRunId);
-      else if (!sessionTask) {
-        const cachedTask = dependencies.state.taskIdentity(ctx);
-        if (cachedTask) dependencies.state.clearTaskBoundary(ctx, cachedTask.taskRunId);
-      }
-    }
-    const activeTask = sessionTask?.trace.outcome === "pending" ? sessionTask : undefined;
-    const turn = dependencies.state.beginTurn(ctx, taskSignal.promptHash, {
-      lightweightNonAuthorizingChange: isLightweightNonAuthorizingChangeContinuation(text)
-    });
-    observeHostWireInput(ctx.cwd, ctx.sessionManager.getSessionId(), { turnId: turn.turnId,
-      promptHash: taskSignal.promptHash, text, source: event.source,
-      hasImages: Boolean(event.images?.length || extractLocalImagePathCandidates(text, ctx.cwd).length) });
-    const authorityPolicy = activeTask?.trace.outcome === "pending" ? dependencies.authorityPolicy(ctx, activeTask) : undefined;
-    let authorityHandoffReady = false;
-    if (activeTask && authorityPolicy?.disposition === "new-attempt-required") {
-      try {
-        writeHandoffProjection(ctx.cwd, buildHandoffProjection(ctx.cwd, activeTask, {
-          gate: { decision: "fail", missing: [`authority policy handoff: ${authorityPolicy.reason}`], missingVerifyCommands: [] },
-          recovery: null
-        }));
-        authorityHandoffReady = true;
-      } catch (error) {
-        ctx.ui.notify(`Piagent authority-policy handoff could not be written: ${error instanceof Error ? error.message : String(error)}`, "warning");
-      }
-    }
-    const replacementIntake = Boolean(activeTask && (
-      activeTask.workingTreeDigestMigration?.status === "new-attempt-required" || authorityHandoffReady
-    ));
-    const readProtectedPaths = dependencies.readProtectedPaths(ctx);
-    const protectedTarget = taskSignal.paths.some((candidate) => matchesProtectedPath(candidate, readProtectedPaths));
-    const protectedOnlyTarget = taskSignal.paths.length > 0
-      && taskSignal.paths.every((candidate) => matchesProtectedPath(candidate, readProtectedPaths));
-    const runtimeIntakeMode = !activeTask ? automaticTaskIntakeMode(text, readProtectedPaths) : undefined;
-    const runtimeIntake = Boolean(runtimeIntakeMode);
-    const manualIntake = !activeTask && !runtimeIntake && manualTaskIntakeEligible(text, readProtectedPaths);
-    const promptGroups = protectedOnlyTarget
-      ? []
-      : toolGroupsForPrompt(text).filter((group) => (
-          runtimeIntake ? group !== "intake" && group !== "task" : true
-        ));
-    if (manualIntake && !promptGroups.includes("intake")) promptGroups.push("intake");
-    dependencies.activateToolGroups(ctx, activeTask?.trace.outcome === "pending"
-      ? [...promptGroups.filter((group) => replacementIntake || group !== "intake"), ...(replacementIntake ? ["intake" as const] : activeTaskToolGroups(activeTask))]
-      : promptGroups);
-    dependencies.telemetry(ctx, {
-      event: "user_input",
-      turnId: turn.turnId,
-      source: event.source,
-      promptHash: taskSignal.promptHash,
-      promptChars: taskSignal.promptChars,
-      workflow: taskSignal.workflow,
-      riskLane: taskSignal.lane,
-      intakeMode: runtimeIntake ? "runtime" : "model",
-      taskMode: runtimeIntakeMode,
-      protectedTarget,
-      protectedOnlyTarget,
-      manualIntake,
-      explicitPathCount: taskSignal.paths.length,
-      termCount: taskSignal.terms.length
+    // Preserve the actual message, including whitespace and slash-like text.
+    // Session/run lifecycle belongs to the host, not to prompt rewriting.
+    const text = event.text;
+    if (!text.trim()) return { action: "continue" };
+    const signal = classifyContextTask(text);
+    const cached = dependencies.state.taskIdentity(ctx);
+    if (cached) dependencies.state.clearTaskBoundary(ctx, cached.taskRunId);
+    const turn = dependencies.state.beginTurn(ctx, signal.promptHash);
+    observeHostWireInput(ctx.cwd, ctx.sessionManager.getSessionId(), {
+      turnId: turn.turnId, promptHash: signal.promptHash, text, source: event.source,
+      hasImages: Boolean(event.images?.length || extractLocalImagePathCandidates(text, ctx.cwd).length)
     });
-
-    const imageAttachment = attachLocalImagesFromText(
-      text,
-      event.images,
-      ctx.cwd,
-      () => dependencies.imageAccess(ctx)
-    );
-    if (imageAttachment?.attached.length) {
-      ctx.ui.notify(`Piagent image input: attached ${imageAttachment.attached.map((item) => item.marker).join(", ")}`, "info");
-    } else if (imageAttachment?.skipped.length) {
-      ctx.ui.notify(`Piagent image input: skipped ${imageAttachment.skipped.length} local image path(s)`, "warning");
-    }
-
-    const inputText = imageAttachment?.text ?? text;
-    const canRewriteWorkflow = event.source !== "extension";
-    const snapshot = buildUsageSnapshot(ctx, String(pi.getThinkingLevel()));
-    const preflight = buildContextPreflight(snapshot, chooseFreshWorkflow(inputText, inputText), inputText.length);
-    const hasBoilerplate = looksLikeGovernedBoilerplate(inputText);
-    const shouldFreshen = canRewriteWorkflow
-      && preflight.recommendation === "fresh-session"
-      && (hasBoilerplate || isPiagentWorkflowInput(inputText) || inputText.length >= LONG_INPUT_CHARS);
-    const shouldCollapseBoilerplate = canRewriteWorkflow
-      && hasBoilerplate
-      && inputText.length >= dependencies.boilerplateCollapseChars;
-    const outgoingImages = [
-      ...(Array.isArray(event.images) ? event.images : []),
-      ...(imageAttachment?.images ?? [])
-    ];
-
-    if (!shouldFreshen && !shouldCollapseBoilerplate) {
-      if (imageAttachment?.attached.length) return { action: "transform", text: inputText, images: outgoingImages };
-      return { action: "continue" };
-    }
-
-    const task = extractTaskRequest(inputText);
-    const workflow = chooseFreshWorkflow(inputText, task);
-    const reason = shouldFreshen
-      ? "Current session is near context limits; use a fresh governed session."
-      : "Mandatory flow boilerplate is already part of the platform; collapse it to the task request.";
-    const command = shouldFreshen
-      ? buildFreshCommand(ctx.cwd, workflow, inputText, reason)
-      : `/${workflow} ${trimTaskForInline(task)}`;
-
-    ctx.ui.notify(`Piagent preflight: ${reason}`, "warning");
-    return outgoingImages.length > 0
-      ? { action: "transform", text: command, images: outgoingImages }
-      : { action: "transform", text: command };
+    const protectedPaths = dependencies.readProtectedPaths(ctx);
+    const protectedOnly = signal.paths.length > 0 && signal.paths.every((p) => matchesProtectedPath(p, protectedPaths));
+    dependencies.activateToolGroups(ctx, protectedOnly ? [] : toolGroupsForPrompt(text)
+      .filter((group) => !["intake", "task", "recovery"].includes(group)));
+    dependencies.telemetry(ctx, { event: "user_input", turnId: turn.turnId, source: event.source,
+      promptHash: signal.promptHash, promptChars: text.length, inputMode: "freeform" });
+    const attachment = attachLocalImagesFromText(text, event.images, ctx.cwd, () => dependencies.imageAccess(ctx));
+    if (attachment?.attached.length) return { action: "transform", text: attachment.text,
+      images: [...(event.images ?? []), ...attachment.images] };
+    if (attachment?.skipped.length) ctx.ui.notify(`Skipped ${attachment.skipped.length} inaccessible image(s)`, "warning");
+    return { action: "continue" };
   });
 }

package/packages/piagent-core/runtime/hooks/session-start-hook.ts

@@ -5,6 +5,7 @@ import { contextIndexV2Status } from "../../extensions/context-engine.js";
 import { resolveExecutionBackend } from "../../extensions/execution-backend.js";
 import type { ProjectProfile, TaskContract } from "../../extensions/guard-types.js";
 import { pruneCaptureFiles } from "../../extensions/state-retention.js";
+import { ensureStateRootIgnored } from "../../extensions/local-state-path.js";
 import { migrateTaskState, readSessionTaskBinding } from "../../extensions/task-state.js";
 import {
   pruneTaskJournal
@@ -71,6 +72,7 @@ type SessionStartHookDependencies = {
 
 export function registerSessionStartHook(pi: ExtensionAPI, dependencies: SessionStartHookDependencies): void {
   pi.on("session_start", async (_event, ctx) => {
+    ensureStateRootIgnored(ctx.cwd);
     dependencies.activateToolGroups(ctx, []);
     const projectTrusted = ctx.isProjectTrusted();
     const explicitProfile = Boolean(process.env.PIAGENT_PROFILE?.trim());

package/packages/piagent-core/runtime/inspection/approval-broker.ts

@@ -210,7 +210,15 @@ export class PiApprovalBroker {
   #action(binding: Binding, draft: ApprovalActionDraft, cwd: string): Record<string, unknown> {
     const command = draft.commandPreview === null || draft.commandPreview === undefined ? null : safe(draft.commandPreview, 4_000);
     const parameter = safe(draft.parameterPreview ?? "No additional parameters", 4_000);
-    const targetPaths = (draft.targetPaths ?? []).slice(0, 32).map((item) => safe(item, 500)).filter((item) => item.text).map((item) => item.text);
+    // Shown to the member: a path inside the project is written relative to it
+    // ("." is the project folder itself), so the card does not repeat the
+    // home directory; a path outside the project stays absolute.
+    const shown = (item: string) => {
+      if (!path.isAbsolute(item)) return item;
+      const relative = path.relative(cwd, item);
+      return relative === "" ? "." : !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : item;
+    };
+    const targetPaths = (draft.targetPaths ?? []).slice(0, 32).map((item) => safe(shown(item), 500)).filter((item) => item.text).map((item) => item.text);
     const targetSummaries = (draft.targetSummaries ?? []).slice(0, 32).map((item) => safe(item, 500)).filter((item) => item.text).map((item) => item.text);
     const removed = [command, parameter].filter((item) => item?.redacted).length;
     const truncated = Boolean(command?.truncated || parameter.truncated || (draft.targetPaths?.length ?? 0) > 32 || (draft.targetSummaries?.length ?? 0) > 32);

package/packages/piagent-core/runtime/managed-failure.d.mts

@@ -0,0 +1,10 @@
+export type ManagedFailure = { role: "main" | "scout" | "research" | "verify" | "review"; code: string; kind: string; requestId: string | null; local: boolean };
+export function failureKind(code: string): string;
+export function failureIsLocal(code: string): boolean;
+export function failureCode(raw: unknown): string;
+export function describeFailure(role: string, raw: unknown): string;
+export function parseFailure(raw: unknown): ManagedFailure | null;
+export function failureIsAdmissionRefusal(code: string): boolean;
+export function failureReason(code: string): string;
+export function unnamedFailureText(raw: unknown): string | null;
+export function failureIsBriefRefusal(code: string): boolean;

package/packages/piagent-core/runtime/managed-failure.mjs

@@ -0,0 +1,166 @@
+// Why a company request failed, as one stable code and one sentence a member
+// can act on. Studio answers with a machine code; the broker and this runtime
+// have their own. The Terminal shows the sentence, the WebUI maps the code to
+// its own copy, and nothing here names the harness model.
+//
+// Kinds: refused (the model's provider declined the request under its usage
+// policy), quota (this key's token budget), provider-limit (the company's model
+// account), account (that account must sign in again), busy (retry shortly),
+// trial-limit (Studio's live-test ceiling), key (import the key again),
+// policy (model or thinking not allowed),
+// new-session (this conversation cannot continue), rejected (the request
+// itself), unreachable (no connection to Studio), service (Studio answered
+// but its model gateway failed), config-changed (key or harness changed while
+// running), update (this Piagent is too old for the harness), tool (a tool's
+// own failure), failed (anything else).
+import { redactSensitiveText } from '../security/sensitive-data.js';
+
+const CODES = {
+  token_quota_exhausted: ['quota', "this key's token quota is used up"],
+  upstream_rate_limited: ['provider-limit', "the company's model account is rate limited or out of usage at the provider"],
+  account_capacity_unavailable: ['provider-limit', 'no company model account has capacity for this model right now'],
+  concurrency_limit: ['busy', 'this key already runs its maximum number of requests'],
+  request_rate_limit: ['busy', 'this key sends requests too fast'],
+  helper_capacity_exhausted: ['busy', 'this key already runs its maximum number of subagents'],
+  connector_busy: ['busy', "Studio's model gateway is at capacity"],
+  operation_unavailable: ['busy', 'Studio could not check this request in time'],
+  account_recovering: ['busy', 'the company model account is being checked after an earlier failure'],
+  session_account_busy_retry_later: ['busy', "this conversation's model account is busy"],
+  session_account_not_ready_retry_later: ['busy', "this conversation's model account is not ready yet"],
+  live_trial_limit_reached: ['trial-limit', "Studio's live-test request ceiling is used up; an administrator has to raise it"],
+  authentication_required: ['key', 'the company key is no longer valid'],
+  invalid_run_grant: ['key', 'the company key or this run is no longer valid'],
+  run_grant_required: ['key', 'this key only works through Agent Watch'],
+  policy_denied: ['policy', 'this key may not use this model, thinking level or output size'],
+  thinking_level_unavailable: ['policy', 'this thinking level is not available for the harness'],
+  harness_model_unsupported: ['policy', 'the harness uses a model Studio cannot run'],
+  harness_profile_unavailable: ['policy', 'the team has no usable harness'],
+  execution_capability_unavailable: ['policy', 'no company model account can run this model'],
+  session_account_unavailable_start_new_session: ['new-session', "this conversation's model account is gone"],
+  run_state_conflict: ['config-changed', 'this run was closed or replaced'],
+  run_recovery_pending_usage: ['busy', "an earlier request of this run is still being accounted"],
+  invalid_request: ['rejected', 'Studio rejected the request as invalid'],
+  upstream_request_rejected: ['rejected', 'the model rejected the request (too long or not valid for it)'],
+  upstream_policy_refusal: ['refused', "the model's provider declined this request under its usage policy"],
+  request_too_large: ['rejected', 'the conversation is larger than Studio accepts in one request (4 MiB)'],
+  execution_precondition_failed: ['service', 'the chosen company model account changed before the request started'],
+  connector_unavailable: ['service', "Studio's model gateway is not available"],
+  connector_execution_failed: ['service', "Studio's model gateway failed"],
+  inference_unavailable: ['service', 'Studio could not run the request'],
+  managed_service_unavailable: ['service', 'Studio could not start the run'],
+  upstream_interrupted: ['service', 'the model response was interrupted'],
+  upstream_incomplete: ['service', 'the model returned no response'],
+  upstream_timeout: ['service', 'the model did not answer in time'],
+  upstream_unavailable: ['service', 'the model provider is not answering'],
+  upstream_auth_required: ['account', "the company's model account has to sign in again in Studio"],
+  'studio-unreachable': ['unreachable', 'Studio could not be reached'],
+  'managed-broker:offline': ['unreachable', 'Agent Watch could not reach Studio'],
+  'managed-broker-timeout': ['unreachable', 'Agent Watch did not answer in time'],
+  'managed-broker-disconnected': ['unreachable', 'the Agent Watch helper stopped'],
+  'managed-broker:serverUnavailable': ['service', 'Studio could not start the run'],
+  'managed-broker:upstreamUnavailable': ['service', 'Studio could not start the run'],
+  'managed-broker:invalidKey': ['key', 'the company key is no longer valid'],
+  'managed-broker:permissionDenied': ['key', 'Agent Watch no longer holds a usable company key'],
+  'managed-broker:keychainApprovalRequired': ['key', 'macOS has not allowed Agent Watch to read the company key'],
+  'managed-broker:quotaExceeded': ['quota', "this key's token quota is used up"],
+  'managed-broker:rateLimited': ['busy', 'Studio is limiting this key right now'],
+  'managed-broker:identityChanged': ['config-changed', 'the key, harness or run changed in Studio'],
+  'managed-broker:invalidResponse': ['config-changed', 'Studio refused to start the run with the current harness'],
+  'managed-route-changed': ['config-changed', 'the harness model changed while this run was active'],
+  'managed-grant-invalid': ['config-changed', 'the harness changed and this conversation still has the old one'],
+  'managed-configuration-unavailable': ['config-changed', 'the key has no usable harness'],
+  'managed-main-model-unavailable': ['policy', 'the harness main model is not available to this key'],
+  'managed-native-catalog-update-required': ['update', 'this Piagent does not know the harness model; update Piagent'],
+  'managed-session-scope-changed': ['new-session', 'this conversation belongs to another member or another Studio'],
+  'managed-run-required': ['config-changed', 'no company run is active'],
+  'managed-helper-unavailable': ['busy', 'this subagent is already running'],
+  'managed-helper-used': ['tool', 'this subagent already ran for this message; each runs once per message'],
+  'managed-helper-not-configured': ['tool', 'the company Harness does not enable this subagent'],
+  'managed-helper-limit': ['tool', 'this subagent already ran 8 times for this message'],
+  helper_run_limit_reached: ['tool', 'this subagent already ran 8 times for this message'],
+  'managed-helper-cancelled': ['tool', 'the subagent was stopped'],
+  'managed-helper-failed': ['failed', 'the subagent ended without an answer'],
+  'web-search-empty': ['tool', 'the search returned nothing'],
+  'managed-web-search-unavailable': ['tool', 'web search runs only on a Claude or Codex model; use web_fetch with a known address'],
+  search_unavailable: ['tool', 'no web search provider answered right now; try again shortly or use web_fetch with a known address'],
+  'managed-session-open-elsewhere': ['new-session', 'this conversation is running in the Piagent WebUI; continue it there or start a new one'],
+  'managed-session-lease-unavailable': ['failed', 'Piagent could not record which process runs this conversation'],
+  'managed-plan-required': ['tool', 'for a complex task the Harness asks for a checklist (update_plan) before the first file edit'],
+  'managed-plan-invalid': ['tool', 'the checklist was not in the expected form'],
+  'managed-request-failed': ['failed', 'the request could not be sent'],
+  'studio-request-failed': ['failed', 'Studio answered with an error'],
+};
+const ROLES = { main: 'main agent', scout: 'scout subagent', research: 'research subagent', verify: 'verify subagent', review: 'review subagent' };
+const REQUEST = /\b([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/;
+const NETWORK = /fetch failed|econnrefused|econnreset|enotfound|ehostunreach|etimedout|socket hang up|network|connection error|terminated|timed? ?out|aborted due to timeout/i;
+
+export function failureKind(code) { return CODES[code]?.[0] ?? 'failed'; }
+// Studio said no at admission, before any model account was asked: the same
+// request can be asked again later, and nothing reaches the model twice. A
+// failure after admission (the model's own error, an interrupted answer) is
+// never in this list: replaying it could repeat billed work.
+const ADMISSION_REFUSALS = new Set(['session_account_busy_retry_later', 'session_account_not_ready_retry_later',
+  'concurrency_limit', 'account_capacity_unavailable', 'request_rate_limit']);
+export function failureIsAdmissionRefusal(code) { return ADMISSION_REFUSALS.has(code); }
+// Refused before the model did any work, for a reason that passes in seconds:
+// the account's sign-in was being renewed (the provider refused the old one)
+// or changed just before the request started, or the run's two-minute grant
+// lapsed under the request (after the Mac slept, Studio's clock catches up
+// at once), or Studio could not check the request's grant in its 5 s (many
+// requests of one member at once); each ask renews the grant first. Asked
+// again a few times only: an account that really has to sign in again, or a
+// run that was closed, still says so.
+const BRIEF_REFUSALS = new Set(['execution_precondition_failed', 'upstream_auth_required', 'invalid_run_grant', 'operation_unavailable']);
+export function failureIsBriefRefusal(code) { return BRIEF_REFUSALS.has(code); }
+// The words of a failure no code names, redacted, for a record nobody is
+// shown; null for a named failure.
+export function unnamedFailureText(raw) {
+  return ['managed-request-failed', 'studio-request-failed'].includes(failureCode(raw)) ? redactSensitiveText(String(raw ?? '')).text.slice(0, 600) : null;
+}
+// The sentence alone, for a status line that already says who is waiting.
+export function failureReason(code) { return (CODES[code] ?? CODES['managed-request-failed'])[1]; }
+// A failure Studio never saw: nothing was sent, so it is not a model request.
+export function failureIsLocal(code) { return code.startsWith('managed-') || code === 'studio-unreachable'; }
+
+function known(code) { return typeof code === 'string' && Object.hasOwn(CODES, code) ? code : null; }
+
+// The stable code inside any error text this runtime can produce or receive.
+export function failureCode(raw) {
+  const text = String(raw ?? '');
+  const tagged = /\[([A-Za-z0-9_:.-]{1,80})\](?: \(request [0-9a-f-]{36}\))?\s*$/.exec(text)?.[1];
+  if (known(tagged)) return tagged;
+  const studio = /"code"\s*:\s*"([a-z0-9_]{1,80})"/.exec(text)?.[1] ?? /web-search-failed: ([a-z0-9_-]{1,80})/.exec(text)?.[1];
+  if (studio === 'initial_request_limit_reached') return 'live_trial_limit_reached';
+  if (known(studio)) return studio;
+  const local = /(managed-broker:[A-Za-z_]{1,80}|managed-[a-z-]{1,80}|web-search-empty)/.exec(text)?.[1];
+  if (known(local)) return local;
+  if (studio || /\bAPI error \(\d{3}\)|^\d{3} \{/.test(text)) return 'studio-request-failed';
+  // The provider declined the request itself (its usage policy), not Studio:
+  // the same request is declined again, so it is said in words.
+  if (/usage policy|violative|refusals-and-fallback/i.test(text)) return 'upstream_policy_refusal';
+  // The provider library's words for an answer stream that ended empty: Studio
+  // admitted the request and nothing came back. It is not asked again.
+  if (/stream ended without a (terminal event|stop reason)|response has no body/i.test(text)) return 'upstream_incomplete';
+  if (NETWORK.test(text)) return 'studio-unreachable';
+  return 'managed-request-failed';
+}
+
+// "Agent Watch main agent: <what failed> [code] (request <id>)". The role says
+// who failed; the model behind it is the harness's business, not the reader's.
+export function describeFailure(role, raw) {
+  const code = failureCode(raw), request = REQUEST.exec(String(raw ?? ''))?.[1];
+  return `Agent Watch ${ROLES[role] ?? ROLES.main}: ${CODES[code][1]} [${code}]${request && !failureIsLocal(code) ? ` (request ${request})` : ''}`;
+}
+
+// What a reader of a stored error message needs: who, what kind, which code
+// and Studio's request id when there is one. Null when it is not a company
+// failure this module recognises the shape of.
+export function parseFailure(raw) {
+  const text = String(raw ?? '');
+  if (!text.trim()) return null;
+  const code = failureCode(text);
+  const role = /^Agent Watch (main agent|(?:scout|research|verify|review) subagent): /.exec(text)?.[1]?.split(' ')[0]
+    ?? /(scout|research|verify|review) subagent/.exec(text)?.[1] ?? 'main';
+  const request = failureIsLocal(code) ? null : REQUEST.exec(text)?.[1] ?? null;
+  return { role, code, kind: failureKind(code), requestId: request, local: failureIsLocal(code) };
+}

package/packages/piagent-core/runtime/orchestration/minimal-delegation-policy.ts

@@ -1,12 +1,11 @@
-export const MINIMAL_DELEGATION_POLICY_VERSION = "minimal-delegation-v1" as const;
+export const MINIMAL_DELEGATION_POLICY_VERSION = "bounded-delegation-v2" as const;
 
 export const MINIMAL_DELEGATION_LIMITS = Object.freeze({
-  maxConcurrentHelpers: 1,
-  maxTotalHelpers: 1,
+  maxConcurrentHelpers: 2,
+  maxTotalHelpers: 2,
   maxRetries: 0,
   maxHelperCalls: 8,
-  maxTransferTokens: 2_048,
-  minimumProjectedSavingsRatio: 0.3
+  maxTransferTokens: 2_048
 });
 
 export type MinimalDelegationEvidence = {
@@ -30,29 +29,11 @@ function boundedInteger(value: unknown, minimum: number, maximum: number): value
   return Number.isInteger(value) && Number(value) >= minimum && Number(value) <= maximum;
 }
 
-function validWorkstreams(value: unknown): value is string[] {
-  return Array.isArray(value)
-    && value.length >= 2
-    && value.length <= 8
-    && new Set(value).size === value.length
-    && value.every((item) => typeof item === "string" && /^[a-z0-9][a-z0-9:._/-]{0,127}$/i.test(item));
-}
-
-/**
- * Helpers are an optimization, not a default reasoning layer. A helper is only
- * eligible when the runtime can show two genuinely independent lanes, a fresh
- * minimal handoff, and at least 30% projected token savings after merge cost.
- * The estimate is advisory, while the one-helper ledger below is enforcing.
- */
+/** Estimates are telemetry only. Actual role, context and concurrency budgets enforce delegation. */
 export function assessMinimalDelegation(evidence?: MinimalDelegationEvidence): MinimalDelegationAssessment {
-  if (!evidence) return { eligible: false, projectedSavingsRatio: null, reasonCodes: ["delegation-evidence-missing", "parent-direct-default"] };
+  if (!evidence) return { eligible: true, projectedSavingsRatio: null, reasonCodes: ["delegation-estimate-unavailable"] };
 
   const reasons: string[] = [];
-  if (evidence.source !== "runtime-estimate") reasons.push("delegation-estimate-not-runtime-owned");
-  if (!validWorkstreams(evidence.independentWorkstreams)) reasons.push("independent-workstreams-not-proven");
-  if (evidence.canRunWithoutParentOutput !== true) reasons.push("helper-depends-on-parent-output");
-  if (!boundedInteger(evidence.estimatedSoloTokens, 1, 100_000_000)
-    || !boundedInteger(evidence.estimatedTotalTokensWithHelper, 1, 100_000_000)) reasons.push("delegation-token-estimate-invalid");
   if (!boundedInteger(evidence.transferTokens, 0, MINIMAL_DELEGATION_LIMITS.maxTransferTokens)) reasons.push("helper-context-transfer-too-large");
   if (evidence.inheritedParentTokens !== 0) reasons.push("parent-history-inheritance-forbidden");
   if (evidence.retryOfDeterministicFailure !== false) reasons.push("deterministic-helper-retry-forbidden");
@@ -61,11 +42,9 @@ export function assessMinimalDelegation(evidence?: MinimalDelegationEvidence): M
     && boundedInteger(evidence.estimatedTotalTokensWithHelper, 1, 100_000_000)
     ? (evidence.estimatedSoloTokens - evidence.estimatedTotalTokensWithHelper) / evidence.estimatedSoloTokens
     : null;
-  if (projectedSavingsRatio === null || projectedSavingsRatio < MINIMAL_DELEGATION_LIMITS.minimumProjectedSavingsRatio) {
-    reasons.push("projected-token-savings-below-30pct");
-  }
+
 
   return reasons.length
     ? { eligible: false, projectedSavingsRatio, reasonCodes: [...new Set(reasons), "parent-direct-default"] }
-    : { eligible: true, projectedSavingsRatio, reasonCodes: ["independent-workstreams-proven", "projected-token-savings-at-least-30pct", "isolated-minimal-context"] };
+    : { eligible: true, projectedSavingsRatio, reasonCodes: ["bounded-helper-eligible", "isolated-minimal-context"] };
 }

package/packages/piagent-core/runtime/orchestration/owned-work-budget.ts

@@ -10,7 +10,7 @@ export const OWNED_WORK_BUDGET_VERSION = "owned-work-budget-v1" as const;
 // Keep the complete ceiling shape for persisted/operator projections, but clamp
 // every caller to one read-only helper and zero retries/writers below.
 export type OwnedWorkCeilings = Readonly<{ maxConcurrentHelpers: number; maxTotalHelpers: number; maxScoutPasses: number; maxPlannerPasses: number; maxReviewPasses: number; maxOracleCalls: number; maxRepairPasses: number; maxWriters: number }>;
-export const ABSOLUTE_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({ maxConcurrentHelpers: 1, maxTotalHelpers: 1, maxScoutPasses: 1, maxPlannerPasses: 1, maxReviewPasses: 1, maxOracleCalls: 1, maxRepairPasses: 0, maxWriters: 0 });
+export const ABSOLUTE_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({ maxConcurrentHelpers: 2, maxTotalHelpers: 2, maxScoutPasses: 1, maxPlannerPasses: 1, maxReviewPasses: 1, maxOracleCalls: 1, maxRepairPasses: 0, maxWriters: 0 });
 export const DEFAULT_OWNED_WORK_CEILINGS: OwnedWorkCeilings = ABSOLUTE_OWNED_WORK_CEILINGS;
 export const AUTOMATIC_OWNED_WORK_CEILINGS: OwnedWorkCeilings = ABSOLUTE_OWNED_WORK_CEILINGS;
 const LOCK_WAIT_MS = 5;

package/packages/piagent-core/runtime/policy/block-remedy.ts

@@ -30,9 +30,11 @@ const REMEDIES: Array<{ match: RegExp; remedy: string }> = [
   },
   {
     match: /(touches|resolves to) protected path|access to protected path|write to protected path/i,
-    remedy: "Use an approved `piagent-context` projection if one is available. Direct access requires the operator"
-      + " to change the protected-path policy; task scope alone does not override it."
-      + " `piagent explain '<command>'` shows which pattern matched."
+    // Models repeated "an approved piagent-context projection" to members, who
+    // could not act on it. Say what the member can do instead.
+    remedy: "This file is protected because it can hold credentials; do not look for another way to read it."
+      + " Tell the user it is protected: they can open it themselves or paste the non-secret part they need."
+      + " Only the operator can change the protected-path policy. `piagent explain '<command>'` shows which pattern matched."
   },
   {
     match: /write to read-only path/i,

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

@@ -446,7 +446,7 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
           content: [
             `mode: ${orchestration.defaultMode}`,
             `helpersMode: ${helpersMode()}`,
-            `helpers: max ${orchestration.maxConcurrentSubagents} fresh read-only total; requires >=30% projected net token saving`,
+            `helpers: max ${orchestration.maxConcurrentSubagents} fresh read-only total; no token-saving threshold`,
             `lenses: ${orchestration.defaultReviewLenses.join(", ")}`,
             `fieldGuide: ${orchestration.fieldGuide.enabled ? `${fieldGuidePath} (${fieldGuideExists ? "exists" : "missing"})` : "off"}`,
             "writer: parent only; helper workers and retries are disabled"

package/packages/piagent-core/runtime/registration/knowledge-tools.ts

@@ -12,10 +12,10 @@ export function registerKnowledgeTools(pi: ExtensionAPI, deps: Record<string, an
     name: "piagent_orchestration_policy",
     label: "Piagent Orchestration Policy",
     description: "Return parent-direct helper limits, review lenses, model-role, and Field Guide policy for the current project.",
-    promptSnippet: "Use this before planning medium/large tasks so the parent stays direct and helper use remains a measured token optimization.",
+    promptSnippet: "Read the enabled helper roles, limits and scope when delegation would help.",
     promptGuidelines: [
-      "Default to the parent model working directly; review quality alone does not justify another model run.",
-      "Use at most one fresh read-only helper only with two independent lanes and at least 30% projected total token savings; never delegate implementation or retry a deterministic failure.",
+      "Work directly by default; delegate focused research or patch review when useful.",
+      "Use at most two fresh read-only helpers; never delegate writes, nest helpers, or retry a deterministic failure.",
       "Treat Field Guide memory as advisory and verify it against current repository files."
     ],
     parameters: Type.Object({
@@ -45,9 +45,9 @@ export function registerKnowledgeTools(pi: ExtensionAPI, deps: Record<string, an
           path: fieldGuidePath,
           exists: fieldGuideExists
         },
-        helperBudget: "1-readonly-total/0-retries/0-writers",
-        minimumProjectedNetSaving: 0.3,
-        stance: "parent-direct; one fresh read-only helper only when runtime-measured net token savings justify it"
+        helperBudget: "2-readonly-total/0-retries/0-writers",
+        minimumProjectedNetSaving: null,
+        stance: "main owns implementation; research and review are optional, bounded and read-only"
       };
       const text = params.detail === "full"
         ? JSON.stringify(payload, null, 2)
@@ -56,7 +56,7 @@ export function registerKnowledgeTools(pi: ExtensionAPI, deps: Record<string, an
           `maxConcurrentSubagents: ${payload.maxConcurrentSubagents}`,
           `helpersMode: ${payload.helpersMode}`,
           `helperBudget: ${payload.helperBudget}`,
-          `minimumProjectedNetSaving: ${Math.round(payload.minimumProjectedNetSaving * 100)}%`,
+          "tokenSavingsRequirement: none",
           `reviewLenses: ${payload.defaultReviewLenses.join(", ")}`,
           `fieldGuide: ${payload.fieldGuide.enabled ? `${payload.fieldGuide.path} (${payload.fieldGuide.exists ? "exists" : "missing"})` : "off"}`,
           `fieldGuidePolicy: ${payload.fieldGuide.writePolicy}, maxLines=${payload.fieldGuide.maxLines}`,