wf's consumption surface: what devlaunch-core must expose

[blooop]

Question

What must devlaunch-core expose for wf to consume it as a linked crate — concretely, not aspirationally?

The go decision's driving motive was reuse: blooop/wayfinder (Rust) reads and renders per-ticket workspace state and needs the typed model. Read wayfinder at HEAD and answer:

• What does wf shell out to dl/devpod for today? Every call site, with the data it parses back.
• What typed model does it reconstruct or wish it had (workspace state, launch context, cache freshness)? wayfinder's open maps (launch benchmarking dl --prune: remove clone directories no workspace references #159, launch-context Start claude with --dangerously-skip-permissions under aid; release 0.0.15 #121) may name wants that aren't in code yet — list those separately as anticipated, not required.
• What is the minimal first API surface that would let wf delete its parsing without waiting for the whole port?

Facts from wayfinder's code and tracker; the API design decision belongs to the architecture ticket.

[blooop]

Resolution

Full write-up with file:line citations (wayfinder at 7d0b9ea, wf 0.18.0; devlaunch at 54d8280, 0.0.27, as of 2026-08-18):
docs/research/wf-consumption-surface.md

Headline: wf never spawns devpod directly — every devpod fact (container state, workspace records) reaches it through dl. The seam devlaunch-core must cover is exactly the dl seam.

What wf shells out to dl for today (all of it)

Call	Parsed back	Where
dl --version	first digit-word → DlVersion triple → Absent/Unreadable/TooOld/Usable against DEVLAUNCH_FLOOR = 0.0.24; also gates how a missing unsaved is read	launch.rs:1348–1381
dl --ls --json	JSON array → Workspace { id, devlaunch, repo, branch, state, unsaved }; state is devpod's vocabulary (Running/Busy/Stopped/NotFound/null) hardcoded in two predicates; unsaved decoded from two wire generations (≤0.0.23 string-or-null; ≥0.0.24 wouldLose/couldNotTell/nothingToLose object) plus an unknown-forward arm. Two consumers: wf reap and the picker's background survey (reclaim hint + Running/Stalled liveness)	reap.rs:76–360, 1000–1018
dl <id> rm [--force]	exit status + stderr only; dl's unsaved-work refusal is load-bearing	reap.rs:1030, 1272
dl <ws> up (prewarm)	nothing — detached, output discarded; the verb that forced the floor	launch.rs:1190, 2082; app.rs:1002
dl <ws> -- '<cmd>' (launch)	nothing — wf execs it; wf encodes the spec owner/repo@wayfinder/<repo>-<n> and must POSIX-quote because after -- is a shell command, not an argv	launch.rs:1170, 1797–1908, 1972
env seam on the exec	writes DEVLAUNCH_HANDOFF_T0 / DEVLAUNCH_PREWARM_FIRED_AT ({secs}.{nanos:09}), scrubbed from every non-launch dl child	launch.rs:1460–1490, 1818

Production wf never reads ~/.cache/devlaunch or ~/.devpod (test scaffolding only), and never reads devcontainer.json contents (existence check only).

Required vs anticipated typed model

Required (in code): Workspace + the four-arm Unsaved sum, the devpod-state predicates, DlVersion/Devlaunch + two release constants, node_of ↔ node_workspace_name (the branch convention wayfinder/<repo>-<n>, computed independently on both sides of the seam), three argv builders + shell_quote, the handoff constants, and the version-conditional null-means-what rewrite. Skew cost is recorded, not hypothetical: wf 0.14.0 vs dl 0.0.23 (Unknown command 'up' in a detached process), wf 0.15.1 vs dl 0.0.25 (mutually unparseable unsaved), plus a four-environment live contract-test matrix maintained purely to hold fixtures against the real program.

Anticipated (tracker, not code): wf#159 — dl classifies prewarm hit/partial/miss from the stamps; hit-rate waits on dl's local launch-history file. wf#121 — a reliable unsaved guard (devlaunch#171), dl-side disk lifecycle (prune #88, image GC, idle-stop), postCreateCommand churn. wf#80 — chose dl as front door; its "dl stays Python, PATH dependency" posture is what devlaunch#53 reversed.

Minimal first API surface (facts; design → #251)

1. The typed listing — workspace id, dl-made flag, repo, branch, container state as an enum, unsaved as a sum. Alone deletes wf's largest parsing module (~300 lines of wire tolerance), both version constants, and the version-conditional semantics.
2. Typed remove(id, force) / up(ws) with the guard refusal as a typed error.
3. The workspace-spec/branch convention as shared code (spec construction + node↔workspace mapping).
4. The handoff env-var names/spelling as exported constants (devlaunch#194).
5. (Adjacent) the after--- quoting contract, pending devlaunch-core module architecture and data model #251's call on a real-argv launch API.

Not needed for the first cut: the launch exec itself (wf can keep exec'ing the dl bin while consuming the listing as a crate), devcontainer.json reading, any filesystem model of dl/devpod state.

[blooop]

Correction for the record (2026-08-19), ticket stays closed. This closure's "~300-line wire-tolerance layer" was re-measured during the owner-directed re-litigation (#261 comment): the deletable tolerance is ~100–200 lines of serde parse in wf's src/reap.rs plus one version-floor message; the rest of that file is deletion policy that survives linking, and wf's exec-into-dl launch path stays either way. The size of this win is now an input to decision ticket #266, which gates the #260 merge.