feat(coven): send Phase 2 lifecycle commands as spec envelopes

[BunsDev]

Part of #80, Phase 2: low-risk lifecycle commands, over the producer's spec command envelope (OpenCoven/coven#1176).

The maintainer explicitly authorized this step. It ends the SDK transport's read-only posture that the #40 review relied on, but only through a separate hook that is strictly limited to four commands.

What

• Four methods. automations.activate, pause, disable and tombstone take (automationId, expectedRevision, context, options?).
  • context is { adoptionKey, intent, principalId, correlationId? }.
  • options is { reason?, signal?, timeoutMs?, observer? }, and tombstone takes no reason.
  • Every field is validated against the spec patterns and bounds before any I/O; a bad value fails with invalid_options.
• Capability gating. A command is sent only when the producer advertises both coven.automations.command.v1 and the specific command action. Otherwise it fails with capability_unsupported.
• A new optional sendCommand transport hook.
  • The built-in Unix and Windows transports implement it with commandBytes. That rebuilds and serializes exactly the four lifecycle envelopes, refuses every other command, extra fields and non-sdk channels, and never serializes caller objects.
  • The existing readDefinitions hook stays read-only.
  • A transport without sendCommand cannot mutate; the call fails with unsupported_operation.
• Typed result. The result is committed (with revision, result and eventRef), replayed (with replay.firstCommittedAt), or rejected (with the typed error.code, retryable, and currentRevision where applicable). Producer messages are not copied.
• Unknown outcome. Any failure after the request is handed to the transport throws outcome_unknown with retryable: true. That covers a dropped connection, the deadline passing mid-flight, and a response that doesn't prove what happened. The README says to resend with the same adoptionKey, which the producer replays instead of re-applying. Cancellation before sending never reports outcome_unknown.
• Authority. principalId is recorded, not an authority grant; the producer accepts mutations only over owner-local IPC.
• Not included. createDraft and revise wait on producer rich-definition persistence. Phase 3 (run, cancel, retry, approval) waits on coven#857.
• README, API baseline and a minor Changeset are included.

Verification

• pnpm verify passed: 3092 tests, typecheck, contracts, package, coverage, stress and lint.
• New coven-automations-commands.spec.ts covers:
  • the exact frozen envelope and all four commands;
  • replay and typed rejection, with no message leak;
  • a gate refusal before the envelope, returned as a rejection;
  • 13 invalid-input cases before I/O;
  • capability gating;
  • a transport without sendCommand;
  • five unknown-outcome causes;
  • a deadline expiring mid-flight, reported as unknown;
  • an abort before sending, reported as not unknown.
• Direct sendCommand refuses seven non-lifecycle or malformed requests before I/O.
• Unix and Windows parity: an exact wire envelope, and a 409 typed rejection decoded.
• Mutation checks: disabling the in-flight unknown-outcome handling fails the deadline test, and dropping the per-command capability check fails the gating test.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Input validation, response-envelope verification, and replay result typing have correctness gaps.

Review effort: Balanced
Findings: 3 · 1

Open (4)

• Count Unicode code points for schema string limits · New
• Validate control-action wrapper state before decoding outcomes · New
• Reject unknown options keys before capability I/O · New
• Discriminate committed and replayed result union members · New

What changed in this PR

Adds Phase 2 Coven automation lifecycle commands using constrained, capability-gated command envelopes.

Changes:

• Adds activate, pause, disable, and tombstone APIs.
• Implements validated serialization, response decoding, and unknown-outcome handling.
• Adds documentation, API baselines, and transport/platform tests.

File	Description
.changeset/​coven-lifecycle-commands.md	Records the minor feature release.
api-baselines/​coven.d.ts	Updates the public API baseline.
packages/​coven/​README.md	Documents lifecycle commands and recovery.
packages/​coven/​src/​automations-commands.ts	Defines command contracts, validation, serialization, and decoding.
packages/​coven/​src/​automations-socket.ts	Sends command envelopes over local IPC.
packages/​coven/​src/​automations.ts	Exposes lifecycle methods and capability gating.
packages/​coven/​src/​index.ts	Exports command types.
tests/​coven-automations-commands.spec.ts	Tests command behavior and failure handling.
tests/​coven-automations-platforms.spec.ts	Tests Unix/Windows wire parity.
tests/​coven-automations.spec.ts	Tests direct transport rejection.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.