fix(agent): define lifecycle error outcomes

[xz-dev]

Summary

• distinguish rejected Agent invocations from failures after an Agent session has been accepted
• expose accepted provider/runtime, max-turn, and stop results through a stable model-visible lifecycle outcome
• prevent failed calls and terminal outcomes from encouraging duplicate replacement Agents
• sanitize bounded public error causes and keep errors separate from genuine partial output
• honor caller cancellation before a child prompt or tool can execute
• make top-level and nested worktree guidance explicit: existing Git + valid HEAD only, omit isolation for read-only/non-Git work, and never initialize or commit solely to enable Agent isolation
• classify Git/worktree prerequisite and infrastructure failures so only confirmed non-Git or unborn-HEAD calls are told to retry once without isolation; indeterminate/path/add failures preserve strict isolation

Contract

Boundary	Pi tool result	Agent ID	Recovery
Invalid invocation or foreground startup failure before session acceptance	error (isError: true)	none retained or exposed	correct the request/environment and start fresh
Delayed background startup failure after an ID was issued	successful lifecycle result	retained	correct the cause and start fresh
Provider/runtime failure after session acceptance	successful lifecycle result	retained	resume the same Agent
Hard max-turn termination	successful lifecycle result	retained	resume the same Agent
User/caller stop	successful lifecycle result	retained	no automatic replacement Agent

Accepted results include a stable model-visible block such as:

Agent outcome:
  status: error
  phase: run
  category: provider
  retryable: false
  recovery: resume_same_agent
  fresh_spawn: forbidden
  agent_id: ...

The same fields are mirrored in structured result/notification details for UI and extension consumers.

Details

• Foreground pre-session failures remove the provisional record and output transcript and suppress completion events, persistence, and notifications before throwing through Pi's real tool-error channel.
• Background jobs that already returned an ID retain that record and report truthful startup recovery.
• Top-level full/compact descriptions, the top-level schema, the example template, and the nested Agent schema state the Git/HEAD prerequisite and safe omission rule.
• Confirmed non-Git or unborn-HEAD failures direct one corrected retry without isolation and forbid unchanged retry or Git initialization solely for Agent.
• Git probe, path-resolution, and git worktree add infrastructure failures instead require fixing Git and retrying with isolation; they never recommend silently falling back to the shared working tree.
• Conclusive Git probes distinguish expected non-repository/unborn-HEAD states from missing Git, timeout, permission/safe-directory, corrupt-repository, malformed-output, path-resolution, and worktree-add failures without exposing raw unbounded stderr.
• resume_same_agent is emitted only when an actual session exists.
• Empty failures no longer appear as No output or as fabricated partial output.
• Public causes use only a sanitized message: ANSI/control characters are removed, common credential forms are redacted, and output is capped at 512 Unicode code points.
• A signal that is already aborted stops the real child session before extension binding, prompting, or tool execution.
• Session initialization failure disposes the unaccepted child and removes only a newly created, invocation-owned persisted session artifact.
• Existing unknown top-level subagent_type fallback behavior is preserved.

Verification

• npm run lint
• npm run typecheck
• npm run test -- --maxWorkers=1 — 793 passed, 5 skipped
• npm run build
• npm run test:e2e -- --maxWorkers=1 — 55 passed, 5 skipped
• focused lifecycle, manager, runner, notification, transcript, status, and RPC suites
• real top-level and nested Agent schema/description checks, real non-Git foreground/background isError: true, confirmed non-Git/unborn-HEAD recovery, and infrastructure-failure isolation-preservation regressions
• independent final review: no blocking, high, or medium findings

Fixes #179

[xz-dev]

Added a follow-up commit for #196 because the structured worktree failure taxonomy and recovery guidance are introduced by this PR.

The new commit:

• forces only bounded Git classification probes to the stable C locale;
• proves non-repository and genuinely unborn HEAD states structurally before recommending one unisolated retry;
• keeps corrupt, dangling, non-commit, unreadable, or otherwise ambiguous metadata fail-closed as git_probe_failed;
• supports valid bare repositories as worktree bases;
• states across README, full/compact/custom descriptions, top-level schema, and nested schema that isolation uses the parent session cwd and prompt paths cannot select another repository.

Verification: lint, typecheck, build, 874 passed / 5 skipped, E2E passed; independent review C0/I0/M0.