Originally created by: aosbandia-stack
Hi — I'm integrating 5dive as a bounded executor behind a caller that has to keep its own
canonical, auditable record of every attempt. Reading the source at 4f6eaa29
(2026-09-18; also checked at e2a5e511 and 0f9bc089, same findings), two properties
make that binding impossible today. Both look like deliberate design choices on 5dive's
side rather than defects, so this is a proposal for one small addition, not a bug report.
1. Submission is not bound to a run identity. src/cmd_run.sh describes 5dive run
as a "Read-mostly view over runs/run_events/run_usage", with run retry the only writer
and append-only. No verb submits work and returns a run. And src/lib/runs.sh states:
EVERY WRITER HERE IS BEST-EFFORT AND NEVER FAILS ITS CALLER. Runs are evidence ABOUT the
work, never part of it … Every function returns 0.
So run rows are advisory by design and may silently not exist. A caller cannot bind an
attempt to one, and cannot distinguish "no run row" from "work never admitted".
2. Delivery is terminal injection. src/cmd_agent_runtime.sh sends work with
sudo -u "$user" tmux send-keys -t "agent-${name}" -l -- "$payload" followed by a separate
Enter; src/cmd_agent_create.sh confirms the helper does "ONLY a LITERAL tmux
inject". The source itself records the failure modes: injection before the input box
exists, and bracketed-paste interaction on large or multiline payloads (DIVE-147).
That design is coherent on its own terms — runs are bookkeeping, and injection suits an
interactive agent. The mismatch is with a caller that must hold a canonical execution
record, which is a different requirement.
One verb. Not a queue, not a scheduler, not a planner.
5dive run submit --agent=<name> --work-order=<file|-> [--idempotency-key=<key>] --json
| Property | Requirement | Why |
|---|---|---|
| Delivery | Hands the payload to exactly one named agent without traversing an interactive TUI | Removes injection timing and bracketed-paste as correctness factors |
| Identity | Returns a durable run id synchronously, on stdout as bounded JSON | Binds the caller's attempt to a concrete run |
| Durability | The run row write is not best-effort; if it cannot be written, the call fails and no work is delivered | Absence of an identity must mean "not admitted", never "admitted but unrecorded" |
| Atomicity | Delivery and run creation succeed together or neither happens | Otherwise a delivered-but-unrecorded run is exactly today's failure |
| Idempotency | With --idempotency-key, a repeat returns the existing run rather than creating a second |
A retry after a timeout must not double-submit |
| Failure | Non-zero exit with a machine-readable reason; never partial success | Callers should not have to parse prose |
Explicitly out of scope, so the change stays small and reviewable: no scheduling, no
task selection, no dependency-graph expansion, no reviewer triggering, no changes to
existing verbs. It adds one path; it removes nothing.
Not smaller. Either half alone is insufficient. A run identity over injected delivery
still cannot prove where the work landed. Non-injecting delivery without a durable identity
still cannot be correlated to evidence. Both gaps are the same gap seen from two ends.
Not larger. Everything else a caller like mine needs — isolation, cancellation,
revocation, evidence retrieval — becomes testable once an attempt has an identity to test
against. Proposing more before that would be designing against unmeasured behaviour.
Would you accept a PR for this? Happy to write it against whatever shape you'd prefer
(a new verb under run, a flag on agent send, or something else), and to keep it
strictly additive. If the answer is that runs are meant to stay advisory, that's a useful
answer too — I'd rather know than work around it.
Originally posted by: lodar
Thanks for this. You read our source correctly on both counts, and sorry for the slow reply.
Yes, we would take this, with one property changed.
Do not return a run id. A run opens when a seat claims work, so "a run row exists" currently
means "an attempt began", and reclaim and idle accounting depend on that. Submission should return an
admission identity instead:
Three states rather than one: admitted (durable, idempotent, fail-closed, synchronous — this is
your binding), activated (a run opens when a seat starts), evidence (still best-effort). You
keep exactly what you asked for, a durable identity a retry re-resolves instead of duplicating. It
just is not called a run.
Build on
src/lib/durable.shrather than a new table. It already implements the durable,idempotent, fail-closed claim you specified: a unique lease key derived from what the action does —
no pid, no timestamp, no nonce — and a claim that returns claimed, replay, or in-flight. It is a
plain library call, not welded to the one path using it today.
On delivery, precisely. A non-injecting path exists, but it is not the seat pulling its own work:
the heartbeat flushes the spool from outside the seat, and only when it observes the seat idle.
Delivery is still an inject — a deferred one, not an atomic one. Atomic delivery into a running agent
is not something we can engineer away, and we would rather say so than design around it: admission
can be atomic, arrival cannot. We think admission is the property your caller actually needs — if
that is wrong for your case, say so, because it changes the design.
Shape it under
runrather than as a flag onagent send.Happy to review a draft PR or an interface sketch first, whichever you prefer.