Invocation dry-run / simulation: fixture replay, ctx.log capture, Cloud-compatible run shape (#1783 follow-up)

[kjgbot]

Context

Cloud issue AgentWorkforce/cloud#1783 shipped the hosted run observability side (PR AgentWorkforce/cloud#1788): per-run history/detail API for deployed agents (status, exitCode, error, summary, stdout/stderr/mountLogTail, failure class) plus an agent-consumable compact shape (?format=compact), with a run origin field reserved for future local_dry_run / cloud_simulation ingestion.

Per #1783's division of labor, the simulation/dry-run half belongs in workforce. This issue tracks it.

Current state (from the #1783 investigation)

• packages/deploy/src/deploy.ts / packages/cli/src/deploy-command.ts: --dry-run validates persona/deploy config only, then exits — it does NOT simulate an invocation.
• packages/runtime/src/types.ts: WorkforceCtx.log(level, message, attrs?) exists and handlers use it.
• packages/runtime/src/runner.ts: emits runner.started, runner.handler.ok, runner.handler.error lifecycle events.
• Missing: a way to ask “if this agent received this event, what would happen?” with captured ctx.log(...), summary, and predicted side effects in a safe inspection mode.

Scope

1. True invocation dry-run / simulation path — execute the handler against an event with side-effect controls (no external writes, or recorded-not-executed), distinct from the existing deploy-preflight --dry-run.
2. Event fixture / replay contract — e.g. workforce invoke --fixture event.json --dry-run and/or workforce deployments simulate <agent> --event ….
3. Safe side-effect controls for simulation mode.
4. Machine-readable run record — preserve ctx.log(...) emissions + invocation summary in a shape compatible with Cloud's hosted run model (runId/status/exitCode/summary/error/timings/trigger/logs + origin: "local_dry_run"), so Cloud can later ingest/display simulated runs alongside hosted ones without redesign.

Acceptance

• A developer can simulate an invocation locally with a fixture event and see captured ctx.log output, summary, and predicted side effects.
• Simulation never executes real side effects unless explicitly opted in.
• The emitted run record matches Cloud's run shape with origin: local_dry_run.
• Docs/README cover the new commands and distinguish them from deploy-preflight --dry-run.

Refs: AgentWorkforce/cloud#1783, AgentWorkforce/cloud#1788.

[kjgbot]

Closed by #187 (simulation runtime) + #188 (workforce invoke CLI). All four acceptance criteria met: fixture-based simulation with captured ctx.log/summary/recorded side effects; no real side effects without opt-in; Cloud-compatible run record with origin:"local_dry_run" (mirrors cloud#1788's compact shape + failureClass union); docs distinguish deploy --dry-run (validate-only) from invoke (simulated execution). Cloud-side ingestion can land whenever wanted — the origin field + record shape are ready.