Skip to content

feat(devforce-lab): the EM seat asks a person before it files (FIX-1666) - #2445

Merged
jhoffner merged 6 commits into
mainfrom
fix-1666-lab-ask
Sep 30, 2026
Merged

jhoffner merged 6 commits into
mainfrom
fix-1666-lab-ask

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 30, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

Nothing in the DevForce goal lab ever asked a person anything. App Lab's Inbox, pointed at it, stayed empty, so the closure's "Inbox → Approve & run" journey (FIX-1663, leg a1) had nothing to approve on the tree the epic pins.

What this does

When a host opens the lab with the ask turned on, the EM seat raises one approval in its own session, the same way every run and with no model: "File night-mode-toggle: … and start the coder seat on it?". Approve (through the engine's resume route, the one App Lab uses) files the row on the feature channel's board and starts the coder seat's run. Deny files nothing, and the EM says so. The ask is raised once per feature per store, even when two hosts open at the same moment. An answered ask is never re-raised; one that nobody decided (the run was interrupted or aborted) is raised again.

It is off unless a host asks for it. The other devforce-lab checks don't, and open exactly as before.

Today: opening the DevForce lab gives the EM two doors, a direct file action and a channel post, both of which file at once, and nothing ever asks a person. After: a third door, off by default, where the EM asks first; the ask sits in the EM's own session where Inbox reads, Approve files the row and hands it to the coder through the same board, Deny files nothing

What's asked of you

Nothing new. This implements the approved spec. Merging is yours.

Parts worth reviewing closely

  • lab/ask.mts → raiseAsk: the once-per-feature claim. Before it runs anything, the step claims devforce-lab-asks/<issue> with the resource-state store's create-if-absent write. The claim names the request id it then passes to runAction.
    • A later raise reads that request. If it is suspended, in_progress or completed, the feature stays held.
    • If it is anything else, nobody decided it, and the claim is taken over by compare-and-set.
    • One limit is documented in the header: a process killed between the claim and the request's first write leaves the feature held until the store is fresh.
  • lab/host.mts: durable: true only when ask is present. This is what keeps the other checks unchanged. Lab.door() sends a read or an answer through the same router and bearer the first check's leg 7 uses. Lab.state and Lab.ledger are what a host hands raiseAsk.
  • em.mts: the drain sits in the approved branch of the same durable request. The spec's POC settled this, and I re-ran it on this branch. addRow is still the only row writer for all three doors.

Spec: specs/issues/FIX-1666/ (spec PR #2437) · Linear: FIX-1666 · Epic FIX-1649 · This PR merges.

How to review this

How to review this. This implements an approved spec. The approach and the numbered decisions in its DECISIONS.md are already signed off by a human, so please review the code against that direction, not the direction itself. The canonical set is retained at specs/issues/FIX-1666/ on main. Linear links to it and to the original merged spec PR, which keeps the review history. Follow-up amendment PRs explain later direction changes. Current architecture docs remain the authority for shipped behavior (BP-037).

Most valuable here: correctness on the second path (the legacy shape, the null boundary, the concurrent case, the cancel path), anything deriving an auth or routing decision from caller-controllable input, and a behaviour the tests assert around rather than on.

Already settled upstream: the approach and every decision in the spec's DECISIONS.md (human-approved; if one is wrong, say so as a spec finding and it gets folded back rather than re-argued inline), and the conventions in docs/contributing/best-practices.md.

Engineering calls
  • Names. The action is askToFile, and ASK_ENTRY lives beside INSPECT_ENTRY in seat-config.mts. The option is ask. The step is raiseAsk, exported from lab/ask.mts with seatSessionId, which host.mts's sessionFor also uses.
  • The atomic claim uses a store primitive that already exists. It is resourceState.set with expectedVersion: 0, and a takeover sets on the claim's own version. Nothing new was added to L1. The store contract says the filesystem adapter's CAS is in-process only.
  • "Row exists" is read from the ledger the host hands the EM kind. After FIX-1667 that is the feature channel's org-scoped board, so this check and the EM file against the same declaration.
  • The EM seat is found by kind. openLab refuses, naming raiseAsk, unless exactly one hired seat is on the em kind.
  • AR-6 and AR-12 are legs of the goal check, not vitest. goals/ is not a vitest root.
  • S5 (the fsdev.config.mts lines) is not here. That config isn't on main, so FIX-1662's S12 carries durable: true plus a raiseAsk({ state, emSeat, feature, principal, ledger }) call.
Everything else

Verification (on b212e21, after merging main with FIX-1667)

The goal check is model-free and keyless. Every read goes through the lab's HTTP door with the verified bearer, and the answer goes through POST /eng.em/requests/:id/resume.

Check Result
it-waits-for-a-person-before-it-files PASS, all ten legs
same, GOAL_CONTROL=no-gate FAIL: "leg 1: a row existed before any approval: eng.feature.work/night-mode-toggle--implement"
it-wakes-the-seat-a-file-declared PASS
it-keeps-its-rows-on-the-channels-board PASS
it-commits-from-the-seats-own-file (model-backed) PASS
it-ships-an-artifact-a-person-can-open (model-backed) PASS (FIX-1667 carried the reread fix)

The review findings were each tested against the previous ask.mts, before the main merge, and each leg failed there:

  • Leg 8: "two concurrent raises raised 2 ask(s), wanted 1".
  • Leg 9: "a store refusal escaped without naming the step".
  • Leg 10: "after the first ask was interrupted / aborted, a reopen raised nothing".

Also passing: pnpm typecheck (includes goals and guard:control-shape), pnpm knip:ci, and validate-spec-folder.

Files

  • goals/devforce-lab/lab/workforce/flows/workers/em.mts: the askToFile durable action and the fileBeforeAsking control.
  • goals/devforce-lab/lab/ask.mts (new): raiseAsk with the atomic claim.
  • goals/devforce-lab/lab/seat-config.mts: ASK_ENTRY.
  • goals/devforce-lab/lab/host.mts: the ask option, the fileBeforeAsking control, and Lab.ask / state / ledger / door.
  • goals/devforce-lab/it-waits-for-a-person-before-it-files/: goal.md, run.mts and fixtures/input.json.
  • goals/devforce-lab/lab/README.md: now lists all five checks and has the ask section.
  • specs/issues/FIX-1666/poc/durable-drain/README.md: a pointer to the production shape.

Nothing under packages/, labs/ or apps/ changes. No changeset: goals are private (BP-022).

Cross-issue

🤖 Generated with Claude Code

https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq

A third door on the em kind: a durable action that suspends on a stock
human_approval naming the feature, then on approve files the row through
addRow and runs the board so the coder seat starts; on reject files
nothing and says so. raiseAsk (lab/ask.mts) raises it once per feature in
the EM seat's own session; openLab takes an ask option, absent by
default, that turns durable execution on and calls it.

New goal check it-waits-for-a-person-before-it-files: model-free and
keyless, reads through the lab's HTTP door, answers through the engine's
resume route. GOAL_CONTROL=no-gate fails on a row existing before any
approval.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
… ask section (FIX-1666)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
@vercel

vercel Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 30, 2026 7:42pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 30, 2026 7:42pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 30, 2026 7:42pm UTC

Request Review

@linear-code

linear-code Bot commented Sep 30, 2026

Copy link
Copy Markdown

FIX-1666

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-30T18:51:25.263024Z 4482e7c PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (FIX-1666)

Direction is the approved spec's, so this reviews shape and leverage, not the decision. Overall the approach is lean: one new durable action, one step module, and addRow stays the single row writer. Findings, most useful first. I read the diff and checked the claims against the branch. I did not re-run the goal checks.

Worth changing in this PR

  1. A second hand-rolled router door now sits in host.mts. The new door() (~L563) builds a Request, attaches the bearer, calls router[method], and parses the body. The inspect probe at ~L679 does the same, with the same bearer and the same { params: { path: segments } } call. The only difference is that the probe wants an SSE body. This PR is the natural moment to put the probe on door(), or to extract one private callRouter(method, segments, { headers, body }). Otherwise the next change to auth or path shape has to touch two places that must not drift. The probe's accept: text/event-stream header could be a door option.

  2. The once-per-feature guard reads the store, then writes. In raiseAsk, the request.list, the resourceState.get and the runAction are not atomic. Two hosts opening the same store concurrently, such as a restart overlapping the old process, both see "no ask" and both raise one. Lab-scale, so I would not add a lock. But the README says "once per feature, per store" flatly. Either soften that to "per open, sequentially", or key the request with a deterministic id if runAction accepts one, so the store enforces it.

  3. cancelled counts as "asked". The guard excludes only failed. If a person or a timeout cancels the pending request, the feature can never be asked again until the store is fresh. That may be intended ("denied stays denied"), but cancel is not deny, and the PR text and README only mention Approve and Deny. Please decide it and say so. Excluding cancelled alongside failed is the smaller surprise.

  4. Approved, then the drain fails: is the failed request retryable? The row is filed in fileApproved, then board.drain runs in the same request. If drain throws, the request is failed. The guard then allows a re-ask, but the row guard returns raised:false ("row already on the board"). That leaves a filed row that nothing drains, with no ask that can retry it. Either add a leg for this, or note that drain is the recovery path (DRAIN_ENTRY exists).

Type and contract looseness, cheap to tighten

  1. raiseAsk does emSeat as { actions?: … } and runAction({...} as never). The as never switches off checking on the whole argument object. It is the one place where the lab calls an engine entry that the router normally calls. A narrow local type for the args, or a comment naming which field would fail to type-check, is better than a blanket cast. Same for (ctx as { cap: Record<string, any> }).cap[BOARD_ID] in two handlers. Check how the existing file/post doors reach the board capability and reuse that accessor rather than a third cast.

  2. door() returns body: any, and the router is typed any. Fine in a goal lab, but unknown with callers narrowing would make the legs fail louder.

Architecture

  1. fileBeforeAsking is a red-state switch in the production-shaped flow definition (EmWorkerFlowOptions, prepareAsk). It is documented as control-only, and the other goal controls already live behind GOAL_CONTROL, so it conforms. It does mean the EM kind carries a branch that exists only to fail a check. If the lab already has a way to wrap or substitute a block at open time, the control could swap prepareAsk for a filing variant and leave the real flow branch-free. If it does not, leave it; I would not build one for this.

  2. Three doors now share addRow, but each door repeats { issue, goal, maxAttempts: defaultAttempts() } assembly. prepareAsk and fileApproved both build the same object. A one-line local helper removes the copy. Low priority.

  3. seatSessionId lives in ask.mts, but it is the seat's session convention, used by host.mts for file and drain too. ask.mts already depends on board.mts and phase.mts. A leaf module (or phase.mts) would avoid host.mts importing a session-naming rule from the feature that happens to add it first. Only worth doing if FIX-1667 or FIX-1662 will also need it, which the cross-issue notes suggest.

Not flagged

Off-by-default wiring (durable: true only with ask), the exactly-one-EM-seat refusal, and allow: ["approve","reject"] stated explicitly all look right. fileApproved tolerates an existing row ("already existed") rather than throwing, which is the correct second-path behaviour. The pre-existing it-ships-an-artifact-a-person-can-open failure is reported as reproducing on main, so I did not count it against this PR.

Rebase note

FIX-1667 (#2441) edits host.mts, board.mts, em.mts and the README. Item 1 will conflict with whatever it does in host.mts. If #2441 lands first, do item 1 on top of it.


Generated by Claude Code

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Problem

FIX-1666 needs the DevForce goal lab to raise a stock human_approval on the EM seat (no model), prove approve/deny through the same resume path App Lab uses, and leave the three existing checks untouched.

Verdict

Approve. I do not think the implementation overshot the problem. The split (ask.mts + third EM action + opt-in openLab({ ask })) matches the spec constraints: synchronous raise until suspended (HTTP 202 alone would weaken AR-6), raiseAsk callable outside openLab for App Lab / fsdev.config, and a separate door instead of a flag on file so older checks keep proving the same thing.

I ran goals/devforce-lab/it-waits-for-a-person-before-it-files/run.mts locally — PASS (~2s, keyless).

Simpler approaches (and why I’d keep this one)

Alternative Why it’s tempting Why it’s worse here
Only openLab + lab.door Fewer modules 202 before the gate; harder to fail open loudly; breaks hosts that don’t use openLab
file + waitForApproval input One action Mutates what the first check proves; rejected in spec
Idempotency only inside prepareAsk Shorter raiseAsk Spreads host vs action concerns; weaker “one host step” contract
Extract approval factory to packages/ DRY with kitchen-sink Explicitly out of scope; kitchen-sink approval-gate.ts is the right reference copy

Reusing engine runAction + stock suspension + orchestration board.drain is the right level of “don’t roll your own HITL.”

What I’d still trim (non-blocking)

  1. Duplicate JSDoc before addRow in em.mts — looks like a half-merged edit; drop the first block (inline).
  2. ask.mts → em.mts for ASK_ENTRY — host utility coupled to the worker flow file. If you want a small cleanup, mirror INSPECT_ENTRY and put action names in seat-config.mts (or similar). Optional; not worth blocking.
  3. FIX-1668 full spec set in this PR — no implementation creep (still goals/ only), but it widens review surface for a “1 PR” issue. If epic batching wasn’t intentional, a follow-up spec-only PR would narrow the diff; I’m not asking for that as a merge gate.
  4. specs/issues/FIX-1666/poc/durable-drain/ — production shape now lives in em.mts; a one-line README pointer avoids two sources of truth.

Performance / test shape

Goal check polling + many openLab() cycles is heavy but consistent with sibling devforce goals and buys isolation. Not a production hot path.

Skipped (would need your call)

  • Shared goals/lib suspension-door helpers — wait for a second consumer.
  • request.list filtering in the store API — only matters if request history grows large outside tests.
Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread goals/devforce-lab/lab/ask.mts Resolved

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Snob — already tight. No POC.

I read goals/devforce-lab/lab/ask.mts, goals/devforce-lab/lab/host.mts (the new door and the existing inspect probe), goals/devforce-lab/lab/workforce/flows/workers/em.mts, goals/devforce-lab/it-waits-for-a-person-before-it-files/run.mts, goal.md, and the README diff, against the pinned sketch in specs/issues/FIX-1666/PLAN.md.

The new door is that sketch: prepare, a stock human_approval, then tapIf onto the existing addRow and board.drain. raiseAsk is the one step the plan asked a host to call, and the goal check is the named legs, shorter than the sibling checks in this lab. That is the size of the contract. Inlining the step into the host, or collapsing the sequencer, would drop a shape the spec and the kitchen-sink approval gate already fixed.

The overlap that looks like a cut is Lab.door next to the inspect probe. Both build a Request, attach the lab bearer, and call router[method]. They then split: JSON in and JSON-or-text out, versus accept: text/event-stream and an event parse. A shared callRouter gives back about as many lines as it removes. fileInputSchema.pick({ issue: true, goal: true }) would shorten askInputSchema by a few lines and lose the ask-specific field text. The repeated board-capability cast matches the two doors already in em.mts. None of those is a smaller shape.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4482e7c845

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread goals/devforce-lab/lab/ask.mts Resolved
Comment thread goals/devforce-lab/lab/ask.mts Resolved
Comment thread goals/devforce-lab/lab/ask.mts Resolved
Drop the stale first JSDoc before addRow; move ASK_ENTRY beside
INSPECT_ENTRY in seat-config.mts so ask.mts no longer imports the worker
flow module; point the POC README at the production shape in em.mts.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
…efusals (FIX-1666)

raiseAsk now claims the feature with the resource-state store's
create-if-absent write before it runs, so two concurrent raises over one
store raise one ask. Only a pending, in-progress or answered request holds
the claim; an interrupted, aborted, failed or incomplete one is taken over
by compare-and-set and a fresh ask raised. Every store read goes through
the step's refusal, so a rejecting store fails naming raiseAsk (AR-6).

Goal-check legs 8-10 cover each; each fails on the previous ask.mts.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
Conflicts in host.mts and em.mts resolved so both survive: the EM kind
takes FIX-1667's channel ledger and this PR's fileBeforeAsking control.
raiseAsk now reads 'the row exists' from the ledger the host hands the EM
kind (org-scoped channel board) instead of the removed LEDGER_ID. Leg 6's
perturbed tree keeps its channel (now required) and drops only the EM.
README lists all five checks.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
…ror (FIX-1666)

raiseAsk released its claim when runAction threw but not when it returned
an error, so a claim naming a request that was never read back held the
feature and a reopen raised nothing. Goal-check leg 11 covers it and fails
on the previous ask.mts.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
* refuses, or the request ended in anything but a pending suspension. Every
* message starts with {@link RAISE_ASK_STEP}.
*/
export async function raiseAsk(options: RaiseAskOptions): Promise<RaiseAskResult> {

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feels like a core aspect of workforce, why is it in the lab

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's in the lab because the spec fenced FIX-1666 to the goal lab's tree. The framework gained no approval model, and the ask uses the stock human_approval suspension (DECISIONS "Considered and dropped": lifting kitchen-sink's ask API into a package was ruled out).

You're right that the general part is a Workforce concept: a seat asks a person before it files work, once per piece of work, and Approve files and starts it. It is now copied twice, here and in App Lab's DevForce config. Only a few pieces are genuinely the lab's: which seat asks, and turning it on when the lab opens.

My recommendation is to merge this as it is and file a follow-up that lifts "ask before filing" into Workforce as a seat option, built on the stock suspension. The lab and App Lab would then both use it. The alternative is to lift it in this PR first, which widens it and holds up #2449 and the task screen behind it.


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants