Review v0.5.65 capability-owned delegation

[seanzqliang]

Review status

This is a review-only PR for the v0.5.65 candidate. The base branch is pinned to v0.5.64 so reviewers can inspect the exact release diff.

Do not merge this PR into review/v0.5.65-base. Affan's review and approval are required before tagging, publishing the GitHub Release/npm packages, publishing the starter image, or performing any production rollout.

Why this PR exists

PilotSwarm currently allows an ad hoc spawn_agent(task=...) child to inherit the parent's toolNames while removing the parent's named-agent binding. For package-provided tools, that separates the executable tool from the agent definition that owns it.

The failure was reproduced in a real delegated workflow:

1. A parent needed a package capability and spawned a task-only specialist.
2. The child inherited the package tool name, but not the owning agent's prompt, skills, package identity, or startup tool contract.
3. initialRequiredTool could not repair this because it only applies after a named agent has already been bound.
4. The child therefore ran with a detached package capability and lacked the instructions required to use it correctly.

This is a generic orchestration defect, not a domain-specific prompt problem. Prompt guidance alone cannot guarantee package ownership across delegation, shared/private package shadowing, worker movement, or session rehydration.

Problems solved

1. Deterministic capability routing

spawn_agent now accepts required_tool.

• required_tool="x" resolves the unique caller-visible, user-creatable agent that declares x.
• Resolution uses the caller's package visibility and private-over-shared shadowing rules.
• The selected agent's complete definition is bound: prompt layering, complete tool list, identity, package copy, metadata, and bootstrap required-tool contract.
• Missing or ambiguous owners fail closed with deterministic guidance.
• agent_name + required_tool is an ownership assertion. It fails if that named agent does not declare the tool; it never attaches the capability to another agent.

This lets orchestration ask for a capability without hard-coding a package-specific agent name while preserving the ownership boundary.

2. Exact package-copy identity across workers

A bound child now carries the exact resolved package ID through durable creation config. Every worker revalidates that package copy against the session owner before applying its prompt, MCP configuration, or handlers.

This prevents a session selected from a private/shared shadow set from silently rebinding to a different copy after worker movement or rehydration.

3. No package or role leakage into ad hoc children

Custom task-only children no longer inherit:

• boundAgentName or package ID
• agent identity
• crawler/harvester privilege roles
• executable package handlers detached from an owner definition

Inherited package tool names are dropped. Package tool names explicitly requested through tool_names are rejected with a non-retryable ownership error. Legacy direct SDK sessions retain their existing behavior; the stricter policy is attached to delegated custom children.

4. Reserved-name quarantine

Package installation rejects tool names that collide with Copilot-native tools, PilotSwarm control tools, or deployment-registered tools. A package cannot impersonate spawn_agent, filesystem tools, or another platform capability and then become its apparent owner.

5. Replay-safe orchestration upgrade

The new caller-aware resolution activity changes the durable yield sequence, so released orchestration 1.0.73 is frozen in its own module tree. New sessions use 1.0.74; in-flight sessions continue replaying against 1.0.73.

Deterministic package-binding failures are returned as retryable: false rather than entering activity retry loops.

6. Windows snapshot hydration reliability

The full unit suite exposed transient Windows directory-handle failures during atomic snapshot replacement. Snapshot hydration now retries only EACCES, EBUSY, ENOTEMPTY, and EPERM, with eight bounded attempts and increasing 20 ms backoff. Other errors still fail immediately.

Security and compatibility properties

• Private package agents remain invisible to other owners.
• A caller's private copy shadows the shared copy of the same logical agent.
• Ambiguous visible owners do not resolve by registry order.
• Package handlers cannot execute detached from their owning definition in delegated custom children.
• The exact selected package copy survives durable serialization and is reauthorized on the executing worker.
• Existing released orchestration history keeps its original 1.0.73 handler.
• Existing direct SDK sessions are not globally forced into the delegated-child policy.

Validation completed

Build and dependency graph

• npm ci from the synchronized 0.5.65 lockfile: passed
• npm run build: passed
  • pilotswarm-sdk TypeScript build
  • pilotswarm-horizon-store TypeScript build
  • portal/Vite production build
  • MCP TypeScript build
• VS Code diagnostics across SDK source and tests: 0 errors
• git diff --check: passed

Complete pure SDK suite

• npm run test:unit --workspace=packages/sdk
• Result: 802 passed, 0 failed, 0 skipped

Focused ownership, persistence, replay, and storage tests

The focused pure-unit run covered:

• caller-visible capability-owner resolution
• private/shared copy shadowing
• missing and ambiguous owner failures
• exact package pin reauthorization
• detached package-tool drop/reject behavior
• reserved tool-name quarantine
• durable creation-config projection
• orchestration 1.0.73 freeze and 1.0.74 registration
• bounded Windows snapshot rename retry

Result: 45 passed, 0 failed.

Focused inline and durable delegation tests

The focused Vitest run covered:

• model-visible required_tool schema and forwarding
• inline and durable child creation
• full named-agent definition binding
• agent_name + required_tool ownership assertion
• custom-child package/role stripping
• raw caller session ID at the CMS authorization boundary
• deterministic non-retry package errors
• orchestration schedule fingerprints

Result: 78 passed, 0 failed across 5 files.

Packaging

All three npm pack --dry-run --json checks passed:

• pilotswarm-sdk@0.5.65 — 1,260 entries
• pilotswarm-horizon-store@0.5.65 — 72 entries
• pilotswarm@0.5.65 — 303 entries; app prepack rebuilt portal and MCP successfully

GitHub checks

• PR deploy-script check: passed
• Mandatory PostgreSQL-backed full suite: not run yet
  • Feature-branch run 34516426858 was rejected before runner allocation because the protected copilot environment allows only main; no test step executed.
  • Main run 34517057279 targets candidate commit f0b36a27 and is currently waiting for Affan's protected-environment approval.

Pending before release

• Affan reviews this PR.
• Affan approves protected test run 34517057279.
• The full PostgreSQL-backed suite passes.
• Only then may v0.5.65 be tagged and the GitHub Release be published.
• Publishing that Release will also trigger npm publication and the starter Docker workflow under current repository wiring.
• No live canary or production rollout has been performed.

Release topology note

The release candidate is already present on main as the required single squash commit f0b36a27 because the protected full-test environment accepts only main. This PR uses the temporary review/v0.5.65-base branch solely to preserve the exact v0.5.64 -> v0.5.65 review diff. Approval of this PR is a review gate, not an instruction to merge the temporary base.