feat(orchestrator): forward per-item capability selection in DispatchExecutor.fire (#13a) (#142)

`DispatchWork.capabilities` and `.addCapabilities` have been in the core contract
since at least 0.4.0 — `dispatch.d.ts` is byte-identical between 0.4.0 and 0.5.0 —
but `fire()` forwarded eleven fields and neither of these, so the selection was
unreachable from a plan.

The consequence is not cosmetic. Without a per-item override, changing a worker's
workspace substrate requires re-registering the subagent, mutating a registration
shared by every plan that names it, so two runs against different workspace
snapshots cannot coexist. Sharper: `resolveLatest` resolves per DISPATCH, not per
run, so a re-registration mid-run can change worker identity between two items of
the same run — and nothing afterwards reports it, because each manifest is
internally consistent and the bundle still verifies intact.

Follows the shape-guard posture its two neighbouring carriers already use: a
non-array value is IGNORED rather than thrown, so one malformed field cannot fail
an item. Spread conditionally for a reason specific to this field — a
present-but-undefined `capabilities` reads as "replace the bound set with nothing"
rather than "not specified", which would be a silent capability strip.

TWO THINGS THE ISSUE ASKED FOR THAT TURNED OUT TO BE UNNECESSARY, both verified
rather than assumed:

1. "Accept the field in validateRun" is a no-op. `validateRun` never references
   `inputs` at all (grep count 0); `WorkItem.inputs` is `Record<string, unknown>`
   and nothing constrains its keys.

2. Shape validation does not strip it. `tick.ts:180` runs
   `shape.inputSchema.safeParse(fireItem.inputs)` but checks only `.success` and
   discards `parsed.data`, so the unstripped `fireItem.inputs` is what reaches the
   executor. Had it used `parsed.data`, a plain `z.object` would have silently
   dropped the new key and the forward would have been a no-op for every
   shape-validated item.

The audit trail needed no change: `DispatchExecutorManifest.capabilities` already
records the resolved {name, contentHash} set per dispatch, sealed via `canonEntry`.

Verified the omit-when-absent test BITES: making the spread unconditional makes it
fail. It passes before the fix too, so without that check it would have been
indistinguishable from a vacuous test.

818 orchestrator tests pass (103 files), `pnpm -r lint` and `pnpm -r typecheck`
clean.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: BrettNye

packages/pangolin-orchestrator/src/executors/dispatch.ts

@@ -73,6 +73,22 @@ export class DispatchExecutor implements Executor {
     const pipelineRef =
       typeof rawPipeline === 'string' && rawPipeline.length > 0 ? rawPipeline : undefined;
 
+    // Per-item capability selection. `capabilities` REPLACES the subagent's bound
+    // set, `addCapabilities` augments it — the core contract has carried both since
+    // 0.4.0; only this forward was missing, which made the selection unreachable
+    // from a plan and forced a subagent re-registration to change workspace
+    // substrate. Same shape-guard posture as the two carriers above: a non-array is
+    // IGNORED, never thrown, so one malformed field cannot fail an item.
+    //
+    // Spread conditionally: a present-but-undefined `capabilities` would read as
+    // "replace the bound set with nothing" rather than "not specified".
+    const capabilities = Array.isArray(item.inputs.capabilities)
+      ? (item.inputs.capabilities as DispatchWork['capabilities'])
+      : undefined;
+    const addCapabilities = Array.isArray(item.inputs.addCapabilities)
+      ? (item.inputs.addCapabilities as DispatchWork['addCapabilities'])
+      : undefined;
+
     // Pre-fire model resolution (authorization side): resolve the subagent's
     // latest def blob and read its pinned model; fall back to the executor's
     // configured defaultModel. Best-effort — any failure here yields just the
@@ -96,6 +112,8 @@ export class DispatchExecutor implements Executor {
       workerImage: this.opts.workerImage,
       secrets: this.opts.secrets,
       ...(requestedModel !== undefined ? { model: requestedModel } : {}),
+      ...(capabilities !== undefined ? { capabilities } : {}),
+      ...(addCapabilities !== undefined ? { addCapabilities } : {}),
       ...(inputRefs && Object.keys(inputRefs).length ? { inputRefs } : {}),
       ...(pipelineRef !== undefined ? { pipelineRef } : {}),
       ...(ctx?.runId ? { trace: { traceId: ctx.runId, runId: ctx.runId, itemId: item.id } } : {}),

packages/pangolin-orchestrator/test/executors/dispatch.test.ts

@@ -1895,4 +1895,83 @@ describe('DispatchExecutor', () => {
       finishedAt: new Date(1),
     });
   });
+
+  /**
+   * KNOWN-ISSUES 13a. `DispatchWork.capabilities` / `.addCapabilities` have been in
+   * the core contract since at least 0.4.0, but `fire()` never forwarded them, so
+   * the selection was unreachable from a plan. Without it, changing a worker's
+   * workspace substrate means re-registering the subagent — mutating a
+   * registration shared by every plan that names it, so two runs against different
+   * workspace snapshots cannot coexist.
+   */
+  function capabilityHarness() {
+    const { compute, resolveExit } = makeDeferredCompute();
+    const storage = makeMemoryStorage();
+    storage.seed('s', 'subagent', 'ns', 'sha256:s', { name: 's' });
+    // A bare-string capability resolves through resolveLatest, so it must exist —
+    // otherwise the client throws "capability not found" and the assertion below
+    // would be measuring the wrong failure.
+    storage.seed('ws-snapshot-1', 'capability', 'ns', 'sha256:ws1', { name: 'ws-snapshot-1' });
+    storage.seed('extra-tool', 'capability', 'ns', 'sha256:xt', { name: 'extra-tool' });
+    const client = new PangolinClient({
+      namespace: 'ns',
+      compute: { default: compute },
+      credentials: { default: makeCredentials() },
+      storage,
+      targets: { prod: { compute: 'default', credentials: 'default' } },
+    });
+    const captured = captureDispatchFire(client);
+    const executor = new DispatchExecutor({ client, target: 'prod', workerImage: 'img' });
+    const settle = () =>
+      resolveExit({
+        exitCode: 0,
+        stdout: '',
+        stderr: '',
+        startedAt: new Date(0),
+        finishedAt: new Date(1),
+      });
+    return { executor, captured, settle };
+  }
+
+  it('forwards inputs.capabilities to the dispatched work', async () => {
+    const { executor, captured, settle } = capabilityHarness();
+    await executor.fire(
+      { ...baseItem, inputs: { subagent: 's', capabilities: ['ws-snapshot-1'] } },
+      { runId: 'r1', actor: 'human:x' },
+    );
+    expect(captured.work?.capabilities).toEqual(['ws-snapshot-1']);
+    settle();
+  });
+
+  it('forwards inputs.addCapabilities to the dispatched work', async () => {
+    const { executor, captured, settle } = capabilityHarness();
+    await executor.fire(
+      { ...baseItem, inputs: { subagent: 's', addCapabilities: ['extra-tool'] } },
+      { runId: 'r1', actor: 'human:x' },
+    );
+    expect(captured.work?.addCapabilities).toEqual(['extra-tool']);
+    settle();
+  });
+
+  it('omits both capability fields entirely when the item declares neither', async () => {
+    const { executor, captured, settle } = capabilityHarness();
+    await executor.fire(baseItem, { runId: 'r1', actor: 'human:x' });
+    // Absent, not `undefined` — the conditional-spread posture its neighbours use.
+    // A present-but-undefined key would replace the subagent's bound set with nothing.
+    expect('capabilities' in captured.work!).toBe(false);
+    expect('addCapabilities' in captured.work!).toBe(false);
+    settle();
+  });
+
+  it('ignores a non-array capabilities value rather than throwing', async () => {
+    const { executor, captured, settle } = capabilityHarness();
+    // Shape guard, not a trust guard — matches how inputRefs and pipeline treat
+    // malformed carriers: ignored, never thrown, so one bad field cannot fail an item.
+    await executor.fire(
+      { ...baseItem, inputs: { subagent: 's', capabilities: 'not-an-array' } },
+      { runId: 'r1', actor: 'human:x' },
+    );
+    expect('capabilities' in captured.work!).toBe(false);
+    settle();
+  });
 });