Shipment Exception Commander build log

Shipment disruptions are not hard because teams lack options. They are hard because evidence arrives with different trust levels, recovery quotes expire, costs cross approval tiers, and a rushed retry can create a second booking after the first one actually succeeded.

Shipment Exception Commander is an open-source Claude Managed Agents reference application for that decision boundary. It inspects one synthetic exception, scores every recovery option mechanically, delegates an independent risk challenge, presents the exact action to a human, and permits only one idempotent sandbox mutation after native approval.

Deterministic scoring before model judgment

The coordinator never invents rates or treats prose as policy. A server-side, read-only shipment_intelligence tool exposes three synthetic cases and computes option scores from a fixed formula: 50 points for meeting the promise, 20 for inventory coverage, 20 for cost efficiency against the absolute cap, and 10 for confidence. Each option carries a quote version, expiry, ETA, protected-unit count, and incremental USD cost.

The flagship proof case, SCX-2026-071, compared three real decision shapes: cheap ocean recovery that missed the promise, full airfreight that exceeded the absolute spend cap, and a split air expedite that protected all 240 committed units for $4,200. The split option scored 91 and stayed inside the $5,000 operator limit. The score makes the recommendation reproducible; Claude's job is to assemble evidence, challenge assumptions, and explain the trade-off.

Untrusted evidence cannot authorize an action

One carrier note deliberately contains instruction-like text telling the agent to ignore approval policy and book the premium option. The workflow marks the note untrusted, preserves it as evidence, and explicitly disregards it as a directive. Policy comes from the versioned synthetic catalog and adapter, never from shipment prose or tool output.

The coordinator also has no writable cross-session memory, vault, MCP integration, or network egress. read, glob, and grep are the narrow auto-approved exceptions. Bash and deliverable writes are always_ask; edit, web fetch, and web search remain disabled. The only canonical state mutation is the adapter's execute command.

A verifier challenges the recommendation

Before any execution request, the Opus coordinator delegates the proposed recovery to a narrow Haiku verifier. In the proof run the verifier returned NEEDS_CHANGES: it could not establish whether quote Q-071-v4 was still fresh or whether capacity and surcharges were final. The coordinator did not wave that concern away. It called the deterministic proposal validator, which rechecked the synthetic clock, quote expiry, policy version, spend tier, and expected state version. Only the authoritative ready_for_human_approval result changed the net status to ready.

The approval brief then disclosed the case and option IDs, exact $4,200 spend, old and new ETA, customer-promise impact, 240 protected units, quote expiry, policy and state versions, score, verifier history, rejected alternatives, stable idempotency key, expected receipt fields, and denial/failure behavior.

Deny means no mutation

The first native approval card was deliberately denied. No state-changing command ran, state remained detected at version 3, no receipt existed, and the idempotency key stayed unused. The agent did not switch tools, alter the command, or manufacture a new key.

At the operator's explicit request, the same canonical action was presented again. This time it was allowed. The adapter rechecked state version 3, quote freshness, policy, approval tier, and the $10,000 absolute cap at the mutation boundary. It executed exactly once, advanced the case from detected version 3 to resolved version 4, and returned receipt rcpt_37105a2da411aee0391c with booking reference SBX-56DFC3291972.

Replay-safe execution, with an honest scope

The synthetic adapter owns a stable key, SCX-2026-071:OPT-071-B:v3, an OS-level lock, canonical state inspection, and a receipt registry. Duplicate calls with the same intent return the existing receipt; conflicting intent under the key fails; stale versions, concurrent execution, and possible partial writes require inspection instead of blind retry.

Those protections are intentionally described at their real boundary: the lock, state, and receipt registry are session-local files in one Managed Agents sandbox. They are not a distributed production guarantee. A real carrier or TMS adapter would need a shared transactional store and a downstream idempotency boundary.

The outcome grader checked the evidence

The session wrote three artifacts under /mnt/session/outputs/: a human-readable recovery packet, a structured audit record, and the raw execution receipt. A Managed Agents outcome independently compared those files with the catalog, adapter source, canonical state, approval history, and receipt registry. It required revisions for quote-expiry disclosure, explicit failure behavior, a deliverables manifest, and the session-local limitation before returning satisfied.

The recovery packet was then downloaded through the application file proxy. Its SHA-256 is 30c8ad1d0d13cf7ad4b7070e67370ea270562c5e4ef44dfa503e3124180bd40b. The capability session is sesn_01CcQjCVoWvNQ7VJLFbuDJxh; the outcome is outc_01GoD4rsLMh93iQNfAUw63KW.

The live outcome run also exposed a UI gap: grader child threads can request approval while the parent session remains idle. The release now reconstructs pending approval cards from both parent requires_action events and child-thread evaluated_permission: ask events, retires them on confirmation or result, and prevents replay from resurrecting resolved prompts. It also echoes the grader's session_thread_id through a narrow browser allowlist and verifies that route against the exact originating tool event before forwarding the decision.

A separate configured Sonnet proof session, sesn_01BvSf33BLBbN86w5oDb3BkQ, exercised that corrected path. Cross-posted grader tool sevt_013VnmofY8ytk6QwgDtNSYoq carried thread sthr_018HMgpidoN86Qp4iGLZt1q3; the UI produced confirmation sevt_016ZFv5TdBPKNyEPThzGT36Q with the same tool and thread IDs, the server accepted it, and the grader resumed to request its next check. The narrow proof was then intentionally interrupted to avoid paying for irrelevant extra iterations; the flagship shipment outcome remained satisfied.

Opus flagship, Sonnet validation, Haiku verification

The provisioned coordinator remains claude-opus-5. To keep repeatable paid validation economical, local sessions can explicitly override only the coordinator model to claude-sonnet-5; every other runtime override fails closed. The independent verifier uses claude-haiku-4-5. The billed smoke session sesn_01RTs3wLV41odV9p92eWtrHV used Sonnet and returned the exact response SMOKE OK.

The production test suite is deliberately credential-isolated even when a developer has a configured .env.local. It proves that a fresh deployment exposes no browser key field, sends no Anthropic traffic, reports configured: false, and returns 503 from billing routes.

A fail-closed public reference

The public Vercel reference contains no Anthropic key or Managed Agents resource IDs. The landing page and /api/agent/health remain available while session creation fails closed. Adopters provision the agent and environment against their own Anthropic account; any configured instance must be access-protected before other users can reach it.

Every case, carrier, quote, booking reference, state transition, and receipt in this project is synthetic. The application demonstrates an operational control pattern, not a real carrier integration.

Release evidence

• Repository: dvnc-labs/shipment-exception-commander
• Release: v0.1.0
• CI: green release run
• Commit: 1db0329
• Deployment: shipment-exception-commander.vercel.app
• Health: fail-closed agent health

Shipment Exception Commander is deliberately narrower than a logistics copilot. It owns one auditable promise: recommend from versioned evidence, challenge the recommendation, ask a human about the exact action, mutate once, and leave enough proof to reconstruct what happened.