Skip to content

FIX-2320: the harness session flow and the scripted harness move to harness-manager; the Teammates divider stays on screen - #4265

Merged
jhoffner merged 3 commits into
mainfrom
fix/FIX-2320-layering-leaks
Oct 30, 2026
Merged

jhoffner merged 3 commits into
mainfrom
fix/FIX-2320-layering-leaks

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 30, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

Three pieces of framework code live where a second app can't reach them:

  • Kitchen Sink's harness session flow. This is the flow that lets a user talk to a coding harness over many turns of one session. It sits in apps/kitchen-sink/lib. Another app that wants a coding chat has to copy it.
  • The scripted harness (harness-stub.mts). Fifteen goals and ten Shift Manager tests import it out of the devteam team's folder by a relative path.
  • The Teammates lab's history divider. It drops off the screen while the newest turn has no history mark yet: a turn that just started, or one that read no history. FIX-2154: the Teammates lab remembers past its history window, and draws the divider (with FIX-1613) #4124's own second look found this (finding 3), and it was not fixed before that PR merged.

What this does

  • harnessSessionFlow is now in @flow-state-dev/harness-manager. The host gives it two things: where each session works (workspace: provision, locate, branch) and the harness block (agent). The flow does the rest, the same as before. Kitchen Sink's lib/harness-session-flow.ts is now wiring: its per-session worktrees, and its goal controls, each wrapped around one feed.
  • harnessStub is now in @flow-state-dev/harness-manager. The only devteam-specific part was the workforce capability that the MCP notice reads through. That is now the caller's option (mcpUses), so harness-manager takes no workforce dependency.
  • The divider reads the latest turn that has a history mark. The window only moves forward, so the previous turn's mark is still correct while the newest one has none.

What's asked of you

Nothing here is yours to decide. The new harness-manager surface (harnessSessionFlow, its schema, harnessStub) is the move Jake approved in epic FIX-2316: "move the Kitchen Sink harness-session flow to package level, move the devteam harness stub out of devteam".

Parts worth reviewing closely

  • Goal controls are now feed wrappers (apps/kitchen-sink/lib/harness-session-flow.ts). no-resume now hands the harness null after the package records the bound id as asked. Before, asked was recorded as null. The goal legs still fail (the harness starts a new conversation), but the turn record differs under the control. no-backstop is now workspace.branch returning null.
  • mcpUses on the stub (packages/harness-manager/src/harness-stub.ts). It is held only when the slot is handed mcpTools, which is the old conditional. Three callers relay MCP servers and now pass it: teams/devteam/harness.mts, test/mcp-servers.test.ts, and the error-reporter goal. A caller that relays MCP servers and leaves it out gets no notice.
  • Where I'm unsure: the stub's block name and source are now harness-stub and harness-manager/stub (they were devforce-lab-…). No test or goal reads either.

Not here, as follow-ups:

FIX-2320 · epic FIX-2316 · draft, merges when Jake approves

How to review this — altitude, what's in scope, what's deliberately unsettled

How to review this. The contract for this change is a one-screen agent brief on the
issue, not a spec — the work was small and local enough that a full spec would have been a
document round-trip. So no approach was signed off upstream, and this PR is the only gate:
the design is in scope alongside the code.

Most valuable here: whether the change is actually as small and local as the brief
assumed — a brief-backed change that turns out to touch a contract, add public surface, or
need a migration was mis-routed and should have been specced (here, approved by the epic; see above). Then the second path (the
legacy shape, the null boundary, the concurrent case, the cancel path).

In scope to challenge: the approach, the scope, and whether this earned its place at all.

Engineering calls
  • harness-manager, not core or testing. Core can't hold the flow, because the flow needs @flow-state-dev/workspace, which depends on core. @flow-state-dev/testing can't hold the stub: workforce dev-depends on testing, so a workforce import there makes a cycle. harness-manager already owns "the harness as a slot". A new package would be a new mechanism.
  • The package names are package names. titleOf, MODEL_REQUIRED and FAILED_OUTCOME_ERROR are now harnessSessionTitle, HARNESS_SESSION_MODEL_REQUIRED and HARNESS_SESSION_FAILED_OUTCOME. HarnessFeeds is now HarnessSessionFeeds, because the manager already exports a HarnessFeeds. There are no aliases: every import site moved.
  • The turn-record schema moved with the flow. lib/harness-turn.ts keeps the page helpers and imports the types with import type, so it stays browser-safe.
  • The Lab's harness option is now typed by the Lab's own HarnessFeeds, not by borrowing HarnessStub["slot"].
  • The mechanism list: no row moves or retires. The flow and the stub were not rows: they lived in an app and a team, and apps are not rows. The harness-manager row's job now names both, and its builtOn adds harness-steering. The classifier maps the new exports to that row by directory, so it proposes no new row. Builds on: harness-manager, harness-steering, coding-harness, workspace.
  • FIX-2154: the Teammates lab remembers past its history window, and draws the divider (with FIX-1613) #4124 / FIX-2154: FIX-2154: the Teammates lab remembers past its history window, and draws the divider (with FIX-1613) #4124 merged on 2026-10-29, after FIX-2320 was filed. It drew the divider, so "draw the divider" was already done. This PR fixes the one defect its second look left open (finding 3). It does not touch windowMarkOf.
Everything else

Verification

  • Divider, red then green: labs/teammates/test/window-read.test.ts. With the extracted windowReadOf still using the old logic, "stays on the last turn that read one while the newest has no mark yet" failed: expected {} to deeply equal { historyStart: 'r3' }. It passes after the fix.
  • Package flow: packages/harness-manager/test/session-flow.spec.ts takes over Kitchen Sink's title test and adds the turn-end check. With if (branch === null) return; removed, the no-branch case fails.
  • Kitchen Sink behaviour: the existing session, parity, model and per-mode suites run the package flow through the new wiring.
  • Typecheck: harness-manager, kitchen-sink, shift-manager, teammates, goals.
  • Tests: harness-manager, kitchen-sink, shift-manager, teammates.
  • Checks: node scripts/check-mechanism-anchors.mjs, node --test scripts/mechanisms.test.mjs, node scripts/validate-changeset-refs.mjs, node scripts/check-retired-terms.mjs, eslint on the changed sources, and the pre-push hook.
  • Flaky under load: labs/teammates/test/screen.test.tsx ("shows a coding run as plain steps") times out when other suites run at the same time. I ran it against main's adapter.ts and it failed there as well. It doesn't use windowReadOf. Shift Manager's task-screen.test.tsx and Kitchen Sink's codex-session.test.ts timed out the same way under load, and both pass when run alone.
  • Not run: the Kitchen Sink and devforce-lab goals, because they need a served app or signed-in harnesses. The goal controls are checked by typecheck and by reading only.

Prose changed (for a docs-editor pass): packages/harness-manager/README.md (new "A scripted harness for checks" and "A harness as a session" sections, plus the export-surface line), packages/shift-manager/teams/devteam/README.md (one line), apps/kitchen-sink/CLAUDE.md (one layout bullet), and the changeset.

Changeset: @flow-state-dev/harness-manager minor (new public exports).


https://claude.ai/code/session_01DME8pzA4e4Rc7fRLGsYavW


Generated by Claude Code

jhoffner and others added 2 commits October 30, 2026 20:55
- Kitchen Sink's harness session flow moves into @flow-state-dev/harness-manager
  as harnessSessionFlow. The host supplies where sessions work (workspace) and
  the harness block (agent). Kitchen Sink keeps its worktrees and goal controls
  as wiring around the package flow.
- The devteam scripted harness moves into harness-manager as harnessStub. The
  workforce-specific MCP read is now the caller's mcpUses option.
- The Teammates lab divider no longer drops out while the newest turn has no
  history mark yet: it reads the latest turn that has one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DME8pzA4e4Rc7fRLGsYavW
…k reads as a retired term

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DME8pzA4e4Rc7fRLGsYavW
@vercel

vercel Bot commented Oct 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 Oct 30, 2026 9:09pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 30, 2026 9:09pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 30, 2026 9:09pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 30, 2026

Copy link
Copy Markdown

FIX-2320

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: issue-desk-0930
kind: reply

@codex review

Unsure about:

  1. harnessSessionFlow moved from Kitchen Sink into @flow-state-dev/harness-manager with the app supplying workspace and agent. Any behaviour the app relied on that didn't survive the seam — in particular the GOAL_CONTROL=no-resume path, where the turn record now stores the bound id as asked instead of null.
  2. harnessStub's MCP notice now reads through a caller-supplied mcpUses instead of a workforce capability. Any caller that relays MCP servers but doesn't pass it, so the notice silently disappears?
  3. windowReadOf picks the latest answering turn with a history mark — any case where that picks a stale turn and draws the divider in the wrong place?

Generated by Claude Code

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 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-10-30T21:24:16.474666Z 63f0793 Draft marked ready
ℹ️ 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.

@github-actions

Copy link
Copy Markdown
Contributor

Mechanism check (advisory, never blocks)

Rows from docs/mechanisms/mechanisms.yaml · labels: none

New export Package Mechanism
harnessSessionFlow @flow-state-dev/harness-manager harness-manager
harnessSessionFeeds @flow-state-dev/harness-manager harness-manager
harnessSessionTitle @flow-state-dev/harness-manager harness-manager
harnessStub @flow-state-dev/harness-manager harness-manager

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 🎉

Reviewed commit: 549f989f64

ℹ️ 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".

… session flow and the stub

Docs-editor pass: the stub's MCP notice says where it shows and what a missing
mcpUses does; a refused conversation says how to recover; state.turns says what
it holds and what it is for; the example passes detached: true, as Kitchen Sink
does; the feed list says it is the session flow's own set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DME8pzA4e4Rc7fRLGsYavW
@jhoffner
jhoffner marked this pull request as ready for review October 30, 2026 21:22

@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.

Simplify / layering review (FIX-2320)

Verdict: The move of the interactive harness session flow and scripted stub into @flow-state-dev/harness-manager is the cleaner direction for this repo. Kitchen Sink becomes ~90 lines of host wiring (workspace + goal controls), goals/shift-manager/devteam stop importing app-local paths, and behavior is lifted rather than rewritten. I do not see a materially simpler approach that still fixes the layering leak without either duplicating the flow or spinning up a second package.

Did the approach go too far?

Mostly no — with one packaging trade-off to name explicitly.

Alternative Why I would not prefer it here
Leave the full defineFlow in Kitchen Sink, extract types only Goals and shift-manager already needed the stub and session semantics; the leak would remain.
New @flow-state-dev/harness-session package Cleaner semver story long term, but extra package overhead while the session factory and manager already share workspace PR backstop patterns. Reasonable follow-up if more hosts ship harness modes, not task-board workers.
Push session flow into core Wrong layer: steering, serverOwned session fields, turn records, and branch PR backstop are host/flow policy, not core contracts.

Where complexity did increase: harness-manager now exports two related but distinct products — the task-board manager (HarnessFeeds, slot for supervised runs) and the interactive session factory (HarnessSessionFeeds, long-lived person ↔ harness chat). The index.ts section headers help; the README still reads manager-first for most of the file. That is documentation/naming debt, not a reason to revert the extract.

What landed well

  • HarnessSessionWorkspace injection — host owns worktree/repo; flow owns conversation binding, steering, turn records, PR backstop. Matches the "second app would need this too" test.
  • harnessStub consolidation — one scripted slot for goals, DevTeam, and package tests instead of scattered copies.
  • Teammates divider (windowReadOf) — orthogonal to harness layering, but a good simplification: filter to turns that actually have a historyStart, keep the previous mark while the newest turn is still starting, plus focused unit tests. Worth keeping in this PR.

Optional follow-ups (not blocking)

These are suggestions, not merge gates:

  1. harnessSessionFeeds + default harnessSteering() — exporting feed construction with a default steering instance is a footgun if a host hand-rolls defineFlow and wires steer to a different instance than onSteerable. harnessSessionFlow does the right thing; consider JSDoc "use harnessSessionFlow" or a subpath export for advanced hosts.
  2. Two feed interfaces in one package (HarnessFeeds vs HarnessSessionFeeds) — drift risk; shift-manager already aliases locally. A shared harness-contract.ts or clearer public names would help future readers.
  3. Kitchen Sink workspace.branch — readHarnessWorkspace() is consulted again after repository() already validated ok; tiny duplicate work per turn-end branch resolution.
  4. Package tests — several harness-manager specs still use inline fake harness handlers; migrating slot tests to harnessStub().slot where appropriate would eat duplication the PR introduced at the product layer but not yet in tests.
  5. failureWordsOf cast — repeated (handle as { failureMessage?: unknown }); a core-typed optional field or helper would dedupe (upstream, not introduced by this move).

Performance

No material regressions from the move: same turn-end existsSync + recordBranchPullRequests, same bounded withTurn sort, stub pause remains timer-based.


Net: behavior-preserving extract with clearer ownership. Approve.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread packages/harness-manager/src/index.ts Resolved
Comment thread labs/teammates/src/adapter.ts 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. Head 63f07933bdf436a542f764a5aa44d77b0ae62810.

I read the move, not the import churn:

  • packages/harness-manager/src/session-flow.ts and apps/kitchen-sink/lib/harness-session-flow.ts
  • packages/harness-manager/src/harness-stub.ts against the old devteam stub
  • packages/harness-manager/test/session-flow.spec.ts against the deleted title test
  • labs/teammates/src/adapter.ts (windowReadOf) and labs/teammates/test/window-read.test.ts
  • the new README sections, the index exports, and the three mode call sites

A rewrite does not shrink this contract:

  • The kitchen-sink file is one conditional per goal control. cwd and worktree share main-checkout; a helper is the same length. resume has to call the package feed first so asked is still recorded, which this PR already changed on purpose.
  • harnessStub's mcpUses and the one-method HarnessStubMcpTools are what drops the workforce import. Defaulting the capability inside the stub puts that import back.
  • windowReadOf is a filter plus a reduce. The second historyStart check is the narrowing; a type-predicate filter is longer. The five tests match window-mark.test.ts.
  • The session-flow spec's session literal is there because createCheck refuses a session with no model and runAction takes no initial state. testFlow would add a devDependency to delete that one line. The two branch tests are the new branch: null seam.
  • Schemas moved with the flow, names have no aliases, and harness-worktree.ts / the hard-coded historySummary name are the follow-ups this PR already split off.

Left those alone.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@jhoffner
jhoffner merged commit 350e0e3 into main Oct 30, 2026
21 of 22 checks passed
@jhoffner
jhoffner deleted the fix/FIX-2320-layering-leaks branch October 30, 2026 21:31
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.

1 participant