@piagent/platform 1.4.0 → 1.5.1

package/packages/piagent-core/runtime/inspection/document-workspace-projection.ts

@@ -0,0 +1,276 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+import {
+  DOCUMENT_EXTENSIONS,
+  extractDocument,
+  resolveDocumentPath,
+  resolveDocumentRoots,
+  type DocumentRoot
+} from "../../extensions/document-intake.ts";
+
+// Opening documents in the browser.
+//
+// The tool `piagent_document_read` already answers "read this path" for the
+// model. This answers "what is there to read, and show me one" for the operator,
+// and it is deliberately built on the same three functions: the roots come from
+// `resolveDocumentRoots`, every path is decided by `resolveDocumentPath`, and the
+// bytes are turned into text by `extractDocument`. A second implementation of
+// containment or of the extension gate would be a second thing to keep correct,
+// and the one that drifted would be this one, because it is the one nobody runs
+// from a terminal.
+//
+// Two rules the listing adds on top:
+//
+// A name is not an authority. The browser never sends a path — it sends an
+// opaque ref, and the ref is resolved by re-listing and matching. A path that
+// stopped being listable between the listing and the read is simply not found,
+// which is the same answer as a path that was never listed.
+//
+// The walk does not follow links. Containment is decided on the canonical path
+// at read time, so a link out of a root could never be *read*, but following one
+// during the walk would still put its target's name in front of the operator.
+
+export const DOCUMENT_WORKSPACE_LIMITS = Object.freeze({
+  documents: 2000,
+  // A shared budget spent in root order lets a large project consume all of it
+  // and leave a granted directory — the one the operator added on purpose —
+  // showing nothing at all. Each root gets its own slice instead, with a floor
+  // so a small grant is never squeezed to nothing by a big one.
+  documentsPerRootFloor: 250,
+  depth: 8,
+  entriesPerDirectory: 4096,
+  text: 400_000
+});
+
+// Directories that are large, uninteresting, and present in almost every
+// project. Walking them costs seconds and returns vendored copies of documents
+// the operator did not write.
+const SKIPPED_DIRECTORIES = new Set([
+  "node_modules", ".git", ".hg", ".svn", "dist", "build", "out", "coverage",
+  ".next", ".nuxt", ".turbo", ".cache", ".venv", "venv", "__pycache__",
+  "target", "vendor", ".gradle", ".idea", ".tmp", ".playwright"
+]);
+
+const EXTENSIONS = new Set(DOCUMENT_EXTENSIONS);
+
+export type DocumentWorkspaceEntry = {
+  documentRef: string;
+  rootRef: string;
+  name: string;
+  relativePath: string;
+  extension: string;
+  sizeBytes: number;
+  modifiedAt: string;
+};
+export type DocumentWorkspaceRoot = { rootRef: string; path: string; source: DocumentRoot["source"]; documentCount: number };
+export type DocumentWorkspaceListing = {
+  schemaVersion: 1;
+  version: "piagent-webui-document-workspace-v1";
+  messageType: "listing";
+  generatedAt: string;
+  state: "ready" | "unavailable";
+  roots: DocumentWorkspaceRoot[];
+  documents: DocumentWorkspaceEntry[];
+  truncated: boolean;
+  reasonCode: string | null;
+};
+export type DocumentWorkspaceDocument = {
+  schemaVersion: 1;
+  version: "piagent-webui-document-workspace-v1";
+  messageType: "document";
+  generatedAt: string;
+  documentRef: string;
+  state: "ready" | "unavailable";
+  // Null wherever the document could not be identified at all. A document that
+  // was found but could not be read still names itself, so the operator sees
+  // which file the refusal is about.
+  name: string | null;
+  relativePath: string | null;
+  rootRef: string | null;
+  format: "text" | "docx" | "pdf" | null;
+  text: string | null;
+  sizeBytes: number | null;
+  truncated: boolean;
+  redacted: boolean;
+  reasonCode: string | null;
+};
+
+export type DocumentWorkspaceInput = {
+  cwd: string;
+  profileRoots?: unknown;
+  environmentRoots?: string | undefined;
+  home?: string | undefined;
+  isProtectedPath?: (candidate: string) => boolean;
+  now?: () => Date;
+};
+
+function ref(prefix: string, value: string): string {
+  return `${prefix}.${createHash("sha256").update(value).digest("hex")}`;
+}
+
+// A control character in a name would sit inside a JSON string safely enough,
+// but this text is also rendered, copied and logged. Stripping is cheaper than
+// auditing every place it lands.
+function displayName(value: string): string {
+  return value.replace(/[\u0000-\u001F\u007F]/g, " ").trim();
+}
+
+function timestamp(value: Date): string {
+  return new Date(Math.floor(value.getTime() / 1000) * 1000).toISOString();
+}
+
+function extensionOf(name: string): string | undefined {
+  const extension = path.extname(name).toLowerCase().replace(/^\./, "");
+  return EXTENSIONS.has(extension) ? extension : undefined;
+}
+
+// Only regular files and real directories are considered, and both are judged by
+// lstat so a link is seen as a link rather than as whatever it points at.
+function walkRoot(root: DocumentRoot, budget: { remaining: number }, isProtected: (relative: string, absolute: string) => boolean,
+  paths: Map<string, string>): DocumentWorkspaceEntry[] {
+  const rootRef = ref("document-root", root.path), found: DocumentWorkspaceEntry[] = [];
+  const queue: Array<{ directory: string; depth: number }> = [{ directory: root.path, depth: 0 }];
+  while (queue.length > 0 && budget.remaining > 0) {
+    const current = queue.shift()!;
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(current.directory, { withFileTypes: true }); }
+    catch { continue; }
+    // A directory with more entries than this is a data directory, not a place
+    // an operator keeps documents, and reading all of it is what makes a listing
+    // take seconds.
+    if (entries.length > DOCUMENT_WORKSPACE_LIMITS.entriesPerDirectory) continue;
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      if (budget.remaining <= 0) break;
+      // A Dirent already reports a link as a link, so the isFile and isDirectory
+      // tests below reject one on their own. This says so out loud, because a
+      // later refactor to stat-based checks would silently start following them.
+      if (entry.isSymbolicLink()) continue;
+      const absolute = path.join(current.directory, entry.name);
+      const relative = path.relative(root.path, absolute).split(path.sep).join("/");
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith(".") || SKIPPED_DIRECTORIES.has(entry.name)) continue;
+        if (current.depth + 1 > DOCUMENT_WORKSPACE_LIMITS.depth) continue;
+        if (isProtected(relative, absolute)) continue;
+        queue.push({ directory: absolute, depth: current.depth + 1 });
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const extension = extensionOf(entry.name);
+      if (!extension || isProtected(relative, absolute)) continue;
+      let stat: fs.Stats;
+      try { stat = fs.statSync(absolute); }
+      catch { continue; }
+      if (!stat.isFile() || stat.size <= 0) continue;
+      budget.remaining -= 1;
+      const documentRef = ref("document", absolute);
+      // The projected name is stripped for display. Resolution must run on the
+      // path as it exists on disk, so the exact bytes are kept beside the ref
+      // and never rebuilt from what the browser was shown.
+      paths.set(documentRef, absolute);
+      found.push({ documentRef, rootRef, name: displayName(entry.name),
+        relativePath: displayName(relative), extension, sizeBytes: stat.size, modifiedAt: timestamp(stat.mtime) });
+    }
+  }
+  return found;
+}
+
+function protectedPredicate(input: DocumentWorkspaceInput): (relative: string, absolute: string) => boolean {
+  const custom = input.isProtectedPath;
+  if (!custom) return () => false;
+  // Protected patterns are project-relative and anchored at the first segment, so
+  // an absolute candidate only ever matches a `**/`-prefixed one. Checking a
+  // single form would let every anchored entry through, the same way the document
+  // tool checks both.
+  return (relative, absolute) => custom(absolute) || custom(relative);
+}
+
+// The listing and the raw paths behind it, produced together. Only the listing
+// crosses to the browser; the paths stay here so a read never has to rebuild one
+// from projected text.
+function collectDocuments(input: DocumentWorkspaceInput): { listing: DocumentWorkspaceListing; roots: DocumentRoot[]; paths: Map<string, string> } {
+  const now = (input.now ?? (() => new Date()))();
+  const base = { schemaVersion: 1 as const, version: "piagent-webui-document-workspace-v1" as const,
+    messageType: "listing" as const, generatedAt: timestamp(now) };
+  const empty = (reasonCode: string) => ({ listing: { ...base, state: "unavailable" as const, roots: [], documents: [],
+    truncated: false, reasonCode }, roots: [] as DocumentRoot[], paths: new Map<string, string>() });
+  let roots: DocumentRoot[];
+  try {
+    roots = resolveDocumentRoots({ cwd: input.cwd, profileRoots: input.profileRoots,
+      environmentRoots: input.environmentRoots, home: input.home });
+  } catch { return empty("document-roots-unavailable"); }
+  if (roots.length === 0) return empty("no-readable-root");
+
+  const isProtected = protectedPredicate(input);
+  const perRoot = Math.max(DOCUMENT_WORKSPACE_LIMITS.documentsPerRootFloor,
+    Math.floor(DOCUMENT_WORKSPACE_LIMITS.documents / roots.length));
+  const paths = new Map<string, string>();
+  const documents: DocumentWorkspaceEntry[] = [], projected: DocumentWorkspaceRoot[] = [];
+  let truncated = false;
+  for (const root of roots) {
+    const budget = { remaining: Math.min(perRoot, Math.max(0, DOCUMENT_WORKSPACE_LIMITS.documents - documents.length)) };
+    const found = walkRoot(root, budget, isProtected, paths);
+    truncated ||= budget.remaining <= 0;
+    projected.push({ rootRef: ref("document-root", root.path), path: displayName(root.path), source: root.source, documentCount: found.length });
+    documents.push(...found);
+  }
+  return { listing: { ...base, state: "ready", roots: projected, documents, truncated, reasonCode: null }, roots, paths };
+}
+
+export function projectDocumentWorkspaceListing(input: DocumentWorkspaceInput): DocumentWorkspaceListing {
+  return collectDocuments(input).listing;
+}
+
+export function projectDocumentWorkspaceDocument(input: DocumentWorkspaceInput & { documentRef: string }): DocumentWorkspaceDocument {
+  const now = (input.now ?? (() => new Date()))();
+  const base = { schemaVersion: 1 as const, version: "piagent-webui-document-workspace-v1" as const,
+    messageType: "document" as const, generatedAt: timestamp(now), documentRef: input.documentRef };
+  const unavailable = (reasonCode: string): DocumentWorkspaceDocument => ({ ...base, state: "unavailable", name: null, relativePath: null,
+    rootRef: null, format: null, text: null, sizeBytes: null, truncated: false, redacted: false, reasonCode });
+
+  // The ref is matched against a listing taken now, so opening a document proves
+  // it is still listable rather than trusting a ref the browser has been holding.
+  const { listing, roots, paths } = collectDocuments(input);
+  if (listing.state !== "ready") return unavailable(listing.reasonCode ?? "document-roots-unavailable");
+  const entry = listing.documents.find((candidate) => candidate.documentRef === input.documentRef);
+  const absolute = paths.get(input.documentRef);
+  if (!entry || !absolute) return unavailable("document-not-listed");
+
+  // Resolution runs against the same roots the walk used, so the extension gate,
+  // the size cap, the symlink canonicalisation and the containment check are the
+  // ones the document tool applies — including the identity that extractDocument
+  // re-proves when it opens the file.
+  const resolved = resolveDocumentPath(absolute, roots, { cwd: input.cwd, home: input.home });
+  if (resolved.status === "error") return unavailable("document-unavailable");
+  // The walk above already dropped protected documents, so a protected ref fails
+  // to match a listing entry before it reaches here. Both of the next two checks
+  // are the invariant stated rather than assumed: they hold the guarantee in
+  // place if the listing filter is ever loosened or the ref scheme changes.
+  const isProtected = protectedPredicate(input);
+  const relative = path.relative(resolved.root.path, resolved.absolutePath).split(path.sep).join("/");
+  if (isProtected(relative, resolved.absolutePath)) return unavailable("document-protected");
+  // Roots are canonical and the walk never traverses a link, so the listed path
+  // is already the canonical one and this equality holds by construction. It is
+  // re-derived anyway: the cost is a hash, and what it protects is the rule that
+  // the browser can only ever name a document the listing chose to expose.
+  if (ref("document", resolved.absolutePath) !== input.documentRef) return unavailable("document-changed");
+
+  const extracted = extractDocument(resolved);
+  if (extracted.status === "error") {
+    return { ...unavailable(extracted.reason.includes("needs OCR") ? "document-needs-ocr"
+      : extracted.reason.includes("pdftotext") ? "document-converter-unavailable" : "document-unreadable"),
+    name: entry.name, relativePath: entry.relativePath, rootRef: entry.rootRef };
+  }
+  // The same redaction the document tool applies before the model sees a file.
+  // The operator can open the original in an editor; what crosses this boundary
+  // is a projection, and projections in this read model do not carry secrets.
+  const safe = redactSensitiveText(extracted.text);
+  const capped = safe.text.length > DOCUMENT_WORKSPACE_LIMITS.text
+    ? { text: safe.text.slice(0, DOCUMENT_WORKSPACE_LIMITS.text), truncated: true }
+    : { text: safe.text, truncated: false };
+  return { ...base, state: "ready", name: entry.name, relativePath: entry.relativePath, rootRef: entry.rootRef,
+    format: extracted.kind, text: capped.text, sizeBytes: entry.sizeBytes,
+    truncated: extracted.truncated || capped.truncated, redacted: safe.redacted, reasonCode: null };
+}

package/packages/piagent-core/runtime/inspection/project-runtime-inspection.ts

@@ -13,19 +13,34 @@ function readRequiredJsonObject(file: string): Record<string, unknown> {
   return value as Record<string, unknown>;
 }
 
-export function runtimeProtectedPaths(packageRoot: string, cwd: string): string[] {
-  const policy = readRequiredJsonObject(path.join(packageRoot, "packages", "piagent-core", "policies", "base-policy.json"));
+// A project profile is operator-supplied and may be missing, malformed, a
+// symlink, or enormous. Every reader of it needs the same refusal, so both
+// callers below go through this one.
+function safeProjectProfile(packageRoot: string, cwd: string): Record<string, unknown> {
   const profileFile = path.join(cwd, ".pi", "piagent-profile.json");
-  let profile: Record<string, unknown> = {};
   try {
     const stat = fs.lstatSync(profileFile);
     if (stat.isFile() && !stat.isSymbolicLink() && stat.size <= 1_048_576) {
-      profile = readProjectProfileDocument(packageRoot, profileFile).profile ?? {};
+      return readProjectProfileDocument(packageRoot, profileFile).profile ?? {};
     }
   } catch {
     // Missing or unsafe project profiles never remove the platform policy.
   }
-  return effectiveProtectedPaths(policy, profile).readProtectedPaths;
+  return {};
+}
+
+export function runtimeProtectedPaths(packageRoot: string, cwd: string): string[] {
+  const policy = readRequiredJsonObject(path.join(packageRoot, "packages", "piagent-core", "policies", "base-policy.json"));
+  return effectiveProtectedPaths(policy, safeProjectProfile(packageRoot, cwd)).readProtectedPaths;
+}
+
+// Directories the operator granted for reading documents outside the project.
+// Returned raw: resolveDocumentRoots is what decides which of them exist and
+// canonicalises them, and duplicating that judgement here would let the two
+// answers drift.
+export function runtimeDocumentReadRoots(packageRoot: string, cwd: string): string[] {
+  const granted = safeProjectProfile(packageRoot, cwd).additionalReadRoots;
+  return Array.isArray(granted) ? granted.filter((item): item is string => typeof item === "string") : [];
 }
 
 export function runtimeConnectionDefinitions(cwd: string): {

package/packages/piagent-core/runtime/inspection/session-identity.ts

@@ -0,0 +1,20 @@
+// The identity and revision shape a Pi session is addressed by.
+//
+// Both the in-session bridge and the Gateway have to speak it: the bridge
+// because it owns one live session, the Gateway because it synthesises the same
+// shape from an inspection snapshot for the many sessions it drives. The layer
+// rules let extension and gateway each import server, and neither import the
+// other, so this is the one place both can agree on.
+
+type NullableRef = string | null;
+
+export type BridgeIdentity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string | null;
+  taskRunId: string | null; agentOperationId: string | null; toolCallId: null };
+
+export type BridgeRevisions = { runtimeRevision: string; taskRevision: NullableRef; controlRevision: NullableRef;
+  workspaceRevision: NullableRef; indexRevision: NullableRef; approvalRevision: NullableRef;
+  sessionOptionRevision: NullableRef; queueRevision: NullableRef };
+
+export type BridgeSnapshot = { state: "unbound" | "ready" | "replacement-pending" | "shutdown";
+  identity: BridgeIdentity | null; revisions: BridgeRevisions | null; liveness: "idle" | "running" | "unknown";
+  taskState: "none" | "active" | "pause-requested" | "paused" | "terminal" | "unknown"; eventSequence: number };

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

@@ -7,6 +7,9 @@ import type { HelperRequest, HelperRole } from "./role-policy.ts";
 import { validateHelperRequest } from "./role-policy.ts";
 
 export const OWNED_WORK_BUDGET_VERSION = "owned-work-budget-v1" as const;
+// `maxRepairPasses` is declared for the repair lane, which reserves no helper
+// role here, so this mechanism never reads it. It is named rather than removed
+// because the repair lane is bounded elsewhere; nothing in this file enforces it.
 export type OwnedWorkCeilings = Readonly<{ maxConcurrentHelpers: number; maxTotalHelpers: number; maxScoutPasses: number; maxPlannerPasses: number; maxReviewPasses: number; maxOracleCalls: number; maxRepairPasses: number; maxWriters: number }>;
 export const DEFAULT_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({ maxConcurrentHelpers: 2, maxTotalHelpers: 3, maxScoutPasses: 1, maxPlannerPasses: 1, maxReviewPasses: 1, maxOracleCalls: 1, maxRepairPasses: 1, maxWriters: 1 });
 export const AUTOMATIC_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({ ...DEFAULT_OWNED_WORK_CEILINGS, maxConcurrentHelpers: 1, maxTotalHelpers: 1 });
@@ -26,7 +29,27 @@ function statePath(cwd: string, taskRunId: string): string { return path.join(cw
 function lockPath(cwd: string, taskRunId: string): string { return `${statePath(cwd, taskRunId)}.lock`; }
 function empty(request: HelperRequest, now: string): BudgetState { return { version: OWNED_WORK_BUDGET_VERSION, taskId: request.taskId, taskRunId: request.taskRunId, terminal: false, reservations: [], updatedAt: now }; }
 function active(state: BudgetState): OwnedWorkReservation[] { return state.reservations.filter((item) => item.status === "active"); }
-function roleLimit(role: HelperRole): number { return role === "scout" || role === "retriever" || role === "researcher" ? 1 : role === "planner" ? 1 : role === "reviewer" ? 1 : role === "oracle" ? 1 : role === "worker" ? 1 : 0; }
+// The per-role ceiling, read from the ceilings the caller passed rather than
+// from constants written here. These limits were real but fixed at one apiece,
+// so `OwnedWorkCeilings` advertised six numbers that nothing ever read: a
+// profile could raise `maxScoutPasses` and be silently ignored, while the two
+// neighbouring fields in the same object did take effect. Half-honoured
+// configuration is worse than none, because the half that works teaches the
+// reader to trust the half that does not.
+//
+// Every default is one, so this changes no behaviour under the shipped
+// ceilings; it makes the object mean what it says.
+function roleLimit(role: HelperRole, ceilings: OwnedWorkCeilings): number {
+  switch (role) {
+    case "scout": case "retriever": case "researcher": return ceilings.maxScoutPasses;
+    case "planner": return ceilings.maxPlannerPasses;
+    case "reviewer": return ceilings.maxReviewPasses;
+    case "oracle": return ceilings.maxOracleCalls;
+    case "worker": return ceilings.maxWriters;
+    // An unknown role reserves nothing rather than defaulting to a limit.
+    default: return 0;
+  }
+}
 
 function read(cwd: string, request: HelperRequest, now: string): BudgetState {
   const target = statePath(cwd, request.taskRunId); if (!fs.existsSync(target)) return empty(request, now);
@@ -136,7 +159,7 @@ export class OwnedWorkBudgetController {
       const duplicate = state.reservations.find((item) => item.deduplicationKey === request.deduplicationKey && ["active", "succeeded"].includes(item.status));
       if (duplicate) return { decision: "duplicate", reason: "equivalent-helper-already-owned", reservationId: duplicate.id, recoveredOrphans };
       if (active(state).length >= ceilings.maxConcurrentHelpers || state.reservations.length >= ceilings.maxTotalHelpers) return { decision: "blocked", reason: "helper-budget-exhausted", reservationId: null, recoveredOrphans };
-      if (state.reservations.filter((item) => item.role === request.role).length >= roleLimit(request.role)) return { decision: "blocked", reason: `${request.role}-ceiling-reached`, reservationId: null, recoveredOrphans };
+      if (state.reservations.filter((item) => item.role === request.role).length >= roleLimit(request.role, ceilings)) return { decision: "blocked", reason: `${request.role}-ceiling-reached`, reservationId: null, recoveredOrphans };
       if (request.authority === "single-writer" && active(state).some((item) => item.authority === "single-writer")) return { decision: "blocked", reason: "single-writer-already-owned", reservationId: null, recoveredOrphans };
       const id = digest(`${request.taskRunId}:${request.deduplicationKey}:${state.reservations.length}`).slice(0, 32);
       state.reservations.push({ id, deduplicationKey: request.deduplicationKey, role: request.role, authority: request.authority, status: "active", reservedAt: now, expiresAt: new Date(Date.parse(now) + request.ceilings.timeSeconds * 1000).toISOString(), completedAt: null, usageRef: null });

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

@@ -0,0 +1,139 @@
+// What to do about a refusal.
+//
+// A blocked tool call is the only conversation most operators ever have with
+// this policy, and for most of them it was one-sided: the guard states 74
+// distinct refusals and three of them said what to do next. The rest ended at
+// "no", which leaves the reader guessing at a rule they cannot see.
+//
+// Remedies are attached in one place rather than at the 29 sites that build a
+// refusal, for the reason this codebase keeps arriving at: a rule applied at
+// every call site is a rule that will be missed at the next one. Every decision
+// leaves through `registerToolCallHook`, so it is enough to answer there, and a
+// refusal added tomorrow is answered without anyone remembering to.
+
+// Matched against the refusal text in order; the first match wins, so put the
+// narrower phrase above the broader one it would otherwise be swallowed by.
+const REMEDIES: Array<{ match: RegExp; remedy: string }> = [
+  {
+    // `grep glob targeting` and `find pattern targeting` are the same refusal
+    // reached through a different tool, and matching only the shell wording left
+    // two thirds of this family answering nothing.
+    match: /glob can target protected path|glob targeting protected path|pattern targeting protected path/i,
+    remedy: "Name the exact file instead of a pattern: a pattern is refused when any name it can match is protected."
+      + " `piagent explain '<command>'` shows which name it matched."
+  },
+  {
+    match: /builds a filename this guard cannot resolve/i,
+    // This refusal already carries its own guidance, so it only gains the
+    // pointer to the tool that shows the whole chain.
+    remedy: "`piagent explain '<command>'` shows every step that ran and what each one saw."
+  },
+  {
+    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."
+  },
+  {
+    match: /write to read-only path/i,
+    remedy: "The active profile marks this path read-only. Change `readOnlyPaths` in `.pi/piagent-profile.json`"
+      + " if the project really should allow writes here, then reapply the profile."
+  },
+  {
+    match: /outside resolved filesystem scope/i,
+    remedy: "Work inside the project, or widen the filesystem scope in the active profile and reapply it."
+  },
+  {
+    match: /cannot mutate paths outside its declared scope|semantic repair must stay inside its declared task scope/i,
+    remedy: "Start a new attempt with `piagent_task_start` listing this path in the scope; a running task cannot widen its own."
+  },
+  {
+    match: /Task Implementation Contract is required/i,
+    remedy: "Call `piagent_task_start` once with explicit project-relative scope, then retry."
+  },
+  {
+    match: /Capability lock is (missing|unreadable)|does not match what this project agreed to/i,
+    remedy: "Reapply the project profile to rebuild the lock: `piagent-init <project> --force-profile`."
+  },
+  {
+    match: /runtime changed during this session/i,
+    remedy: "Restart the Pi session. The lock is re-verified and re-pinned at session start, never mid-session."
+  },
+  {
+    match: /Permission profile read-only blocked/i,
+    remedy: "This session is read-only. Change the access level in Settings, or start it with a writable permission profile."
+  },
+  {
+    match: /Tool (is not registered|registry is disabled|registry blocked)/i,
+    remedy: "Enable the tool group for this profile, or use a tool the profile already allows."
+  },
+  {
+    match: /lifecycle control blocks tool start|resume is blocked|could not enter an audited repair phase/i,
+    remedy: "Resolve the task lifecycle first — resume, repair, or close the current attempt — then retry."
+  },
+  {
+    match: /path traverses symbolic link|path resolves outside the project|path component cannot be inspected/i,
+    remedy: "Use the real path inside the project. A link that leaves the project is refused rather than followed."
+  },
+  {
+    match: /requires confirmation|requires explicit operator approval/i,
+    remedy: "Approve it in the session when prompted; this is a decision the operator makes, not a defect."
+  },
+  {
+    // The whole session is refused here, so this is the refusal most in need of
+    // a next step -- and the one the narrower MCP wording used to miss.
+    match: /Blocked every tool call/i,
+    remedy: "Every tool call is refused while a repository config can reach an ungated server."
+      + " Run `piagent-mcp doctor` to see which config stopped the session, then approve or remove those servers."
+  },
+  {
+    match: /MCP (proxy|shell carrier|command|server)/i,
+    remedy: "Check the server with `piagent-mcp doctor`, and approve it explicitly if the project should reach it."
+  },
+  {
+    match: /is read-only; .*cannot mutate|read-only inspection allowlist/i,
+    remedy: "This task was started read-only. Start a source-change task with `piagent_task_start` when the work needs to write."
+  },
+  {
+    match: /opaque shell mutation whose write target is not statically bounded/i,
+    remedy: "Use the edit, write, or apply-patch tools so the target is named, instead of a shell command that computes it."
+  },
+  {
+    match: /Context budget blocked editing large file/i,
+    remedy: "Edit a narrower range of the file, or split the change, so the edit stays inside the context budget."
+  },
+  {
+    match: /Approval became stale/i,
+    remedy: "Ask for the action again; an approval is bound to the state it was granted for and does not survive a change to it."
+  },
+  {
+    match: /Missing capability|Capability validation failed/i,
+    remedy: "Add the pack that provides it to the project profile, then reapply the profile."
+  },
+  {
+    match: /nesting exceeds inspection depth|unsafe scope pattern/i,
+    remedy: "Flatten the tool input or narrow the scope pattern: anything the guard cannot finish inspecting is refused rather than guessed at."
+  },
+  {
+    match: /start a new attempt or a fresh task/i,
+    remedy: "Start the next attempt with `piagent_task_start`; a closed attempt cannot keep mutating the project."
+  }
+];
+
+// Kept out of the appended text when the refusal already ends by saying what to
+// do, so a reader is never given the same instruction twice in one line.
+const ALREADY_GUIDED = /Write the path out|Reapply the project profile|Restart the session|then retry\.$|Start the task first/i;
+
+export function remedyForReason(reason: string): string | undefined {
+  if (typeof reason !== "string" || reason.trim().length === 0) return undefined;
+  const found = REMEDIES.find((entry) => entry.match.test(reason));
+  if (!found) return undefined;
+  if (ALREADY_GUIDED.test(reason) && !/glob can target|cannot resolve/i.test(reason)) return undefined;
+  return found.remedy;
+}
+
+export function withRemedy<T extends { block: true; reason: string }>(decision: T): T {
+  const remedy = remedyForReason(decision.reason);
+  if (!remedy || decision.reason.includes(remedy)) return decision;
+  return { ...decision, reason: `${decision.reason.replace(/\s+$/, "")} → ${remedy}` };
+}

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

@@ -44,10 +44,11 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
   const taskStartTool = {
     name: "piagent_task_start",
     label: "Piagent Task Start",
-    description: "Create a Task Implementation Contract for the current project before editing.",
-    promptSnippet: "Start a governed implementation task and persist the task contract.",
+    description: "Create a Task Implementation Contract before governed project inspection, command execution, or source changes.",
+    promptSnippet: "Start a governed project task and persist the task contract.",
     promptGuidelines: [
       "Call this exactly once before source edits in a project managed by Pi Agent Platform.",
+      "Use source-change for project command execution, including tests, builds, lint, typecheck, verification, and package dry-runs, even when the operator requires source files to remain unchanged. Read-only intentionally blocks shell execution.",
       "Do not call context, status, policy, evidence-recording, trace, or gate tools first; runtime hooks provide those checks automatically.",
       "Use tiny for a bounded low-risk change, normal for ordinary multi-file work, and high-risk for security, data, release, migration, or external-impact work.",
       "Every scope entry must be a project-relative path or glob such as src/file.ts, src/**, or test/**; never put prose in scope.",
@@ -58,7 +59,9 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       taskId: Type.Optional(Type.String({ minLength: 1 })),
       summary: Type.String({ minLength: 10 }),
       riskLane: StringEnum(["tiny", "normal", "high-risk"] as const),
-      changeMode: Type.Optional(StringEnum(["source-change", "read-only"] as const)),
+      changeMode: Type.Optional(StringEnum(["source-change", "read-only"] as const, {
+        description: "Use source-change for project command execution as well as edits; use read-only only for inspection that needs no shell execution."
+      })),
       maxAttempts: Type.Optional(Type.Number({ minimum: 1, maximum: 10 })),
       expectedOutput: Type.String({ minLength: 10 }),
       acceptanceCriteria: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 12 }),
@@ -103,15 +106,8 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       const migrationRetry = active?.taskId === taskId
         && active?.workingTreeDigestMigration?.status === "new-attempt-required";
       const authorityRetry = active?.taskId === taskId && activeAuthorityReplacement?.required === true;
-      if (active && !migrationRetry && !authorityRetry) {
+      if (active?.trace.outcome === "pending" && !migrationRetry && !authorityRetry) {
         if (active.taskId === taskId) {
-          if (active.trace.outcome !== "pending") {
-            return {
-              content: [{ type: "text", text: `Session already belongs to terminal task ${active.taskId} (${active.trace.outcome}). Start a fresh Pi session for a retry or new task.` }],
-              details: active,
-              isError: true
-            };
-          }
           const manifest = repositoryFileManifest(ctx.cwd);
           const currentScopeResolution = resolveTaskScopePatterns(active.scope, manifest);
           const proposedScopeResolution = Array.isArray(params.scope)
@@ -151,7 +147,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
           };
         }
         return {
-          content: [{ type: "text", text: `Session already belongs to task ${active.taskId} (${active.taskRunId}, ${active.trace.outcome}). Use one Pi session per task and start a fresh session before another task.` }],
+          content: [{ type: "text", text: `Session already has pending task ${active.taskId} (${active.taskRunId}). Complete or stop it before starting another task in this conversation.` }],
           details: active,
           isError: true
         };
@@ -428,7 +424,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
     const started = await taskStartTool.execute(
       `runtime-intake-${ctx.sessionManager.getSessionId()}`,
       {
-        taskId: hasOperatorSessionName(sessionName) ? sessionName : summary,
+        taskId: active && active.trace.outcome !== "pending" ? summary : hasOperatorSessionName(sessionName) ? sessionName : summary,
         summary,
         riskLane: automaticTaskRiskLane(prompt),
         intakeMode: "runtime",

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

@@ -8,7 +8,7 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
     buildUsageSnapshot, commandArgs, emitProfileStatus, emitProfileTechStatus, emitRuntimeMessage,
     fs, loadProfileFromContext, prefixCompletions, projectContextFilePath, projectProfilePath,
     registerRuntimeCommand, resolveMemorySettings, runProfileTechWizard, selectRuntimeAction, sendWorkflowFollowUp,
-    shortTaskLabel, techStackPath
+    freshRequestParts, shortTaskLabel, techStackPath
   } = deps;
   type WorkflowCommandName = "task" | "scout" | "be-to-fe" | "discuss" | "plan" | "review" | "platform-improve" | "commit" | "pr" | "onboard";
 
@@ -377,17 +377,18 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
   });
 
   async function startFreshWorkflow(workflow: "task" | "scout" | "be-to-fe", args: string, ctx: any) {
-    const request = String(args ?? "").trim();
+    const parsed = freshRequestParts(String(args ?? ""));
+    const request = parsed.request;
     if (!request) {
       ctx.ui.notify(`Usage: /fresh ${workflow} <request>`, "warning");
       return;
     }
 
-    const label = shortTaskLabel(request);
+    const label = parsed.sessionTitle ?? shortTaskLabel(request);
     const command = `/${workflow} ${request}`;
     const result = await ctx.newSession({
       withSession: async (nextCtx) => {
-        pi.setSessionName(`pi:${workflow}:${label}`);
+        pi.setSessionName(`pi:${label}`);
         await nextCtx.sendUserMessage(command);
       }
     });