Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/contributing/docs-revamp/pages/build/deploy/docker.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ curl -X POST http://localhost:3000/api/flows/support/sessions \
# {"session":{"id":"sess_...", ...}}
```

`/healthz` returns `200` once the stores are open and `503` while they open. An orchestrator should probe that path and wait through the `503`. The `node:22-slim` image has no `curl`, so probe from outside the container or install it in the image.
`/healthz` returns `200` once the stores are open. The server opens them before it listens, so until then the port refuses connections; only with `--allow-unauthenticated` does it listen at once and answer `503` while they open. An orchestrator should probe that path and wait until it answers `200`. The `node:22-slim` image has no `curl`, so probe from outside the container or install it in the image.

To check persistence, run the `POST` above and copy the `id` from its response. Then run `docker restart support-app` and fetch it with `curl -H "authorization: Bearer $TOKEN" http://localhost:3000/api/flows/sessions/<id>`. The same session comes back. Remove the container and start a new one with the same `-v`, and the data is there too. Without the volume, the file lives on the container's own disk and goes with it.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ Skipped: B-10 is kept in the sitemap, and the page was already at `docker.md`.
- After the page as it was kept, page sha256 4655cbebde77: exit 1. Failed: node scripts/check-docs-page.mjs docs/contributing/docs-revamp/pages/build/deploy/docker.md: FAIL docs/contributing/docs-revamp/pages/build/deploy/docker.md (recipe, 580 words). One failure: 13 em-dashes (limit 2). The script does not print line numbers. A grep finds em-dashes on these lines. Prose: 15 (Prerequisites, 'not Next.js — see Railway guide'), 323-326 (the four 'critical directives' bullets), 375-381 (all seven production-checklist bullets) and 393 ('don't — let Docker install them'). Code comments in server.ts: 93 ('SQLite on a Docker volume — survives...') and 134 ('handleFlowRequest — same bridge function...'). That is 14 prose lines against the script's count of 13. The script likely leaves code out and counts one of these lines differently. Budget, banned words, code titles and fences raised nothing. · Type-check of TypeScript examples (src/server.ts, the page's only TS block) in apps/kitchen-sink/.docs-tc-B-10 against workspace packages: exit 2. As extracted: (1) src/server.ts(4,20) TS2307 Cannot find module './flows/my-flow/flow.js'. The page imports a flow file it never shows. (2) src/server.ts(11,12) TS2353 'myFlow' does not exist in type 'readonly FlowInstance<any, any>[]'. createFlowState expects `flows` to be an array of flow instances, so `flows: { myFlow }` should be `flows: [myFlow]`. I re-ran with a stub flow file at src/flows/my-flow/flow.ts to see whether anything else fails. Only error (2) remained. The imports from @flow-state-dev/engine (createFlowState, decodePathSegments) and @flow-state-dev/store-sqlite (sqliteStores), and the rest of the file, type-check. The scratch folder is deleted..
- After revise round 1, page sha256 a912682b31a7: exit 0.
- After revise round 2, page sha256 ca6235442744: exit 0.
- After the loop (review): drift fix: under `fsdev serve` with the authentication check on, the stores open before the port listens, so the port refuses connections until they open; `/healthz` answers `503` only with `--allow-unauthenticated` (packages/node/src/bind-guard.ts:67-72, packages/node/src/serve.ts:182-184). 701 words. Page sha256 464052078396.

## 5 · Fact check

Expand All @@ -44,6 +45,7 @@ Checked against the code: the page as pass 4 read it after the page as it was ke
- Reference row 9: Row 9: startup failure causes include 'a model call with no provider key set fails resolution' Untrue: Model resolution fails when the call is made, not at startup. It is a runtime request error and is not a cause of the process failing to start. (packages/core/src/models/createModelResolver.ts:1222-1231) The row is recorded corrected.
- Reference row 6: Row 6: the SQLite store needs the runtime library libsqlite3 in the image Untrue: better-sqlite3 bundles SQLite in its native addon. What the runtime needs is the native module built for the runtime's platform, not a system libsqlite3. (packages/store-sqlite/package.json:67) The row is recorded corrected.
- Reference row 7: Row 7: SQLite store requirement is the runtime library libsqlite3, the same row as the native-module requirement Untrue: There is no libsqlite3 runtime requirement, because better-sqlite3 statically bundles SQLite. (packages/store-sqlite/package.json:67) The row is recorded corrected.
- Re-run after the review edit: the guard resolves the router before the bind (packages/node/src/bind-guard.ts:86); `fsdev serve` calls `serve()` with `allowUnauthenticated` (packages/fsdev/src/commands/serve.ts:107-109); the 503-until-init health check is the loopback and opt-out path (packages/node/src/serve.ts:182-184).

## 6 · Depth pass

Expand Down
4 changes: 2 additions & 2 deletions docs/contributing/docs-revamp/pages/build/deploy/railway.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ aptPkgs = ["build-essential", "python3"]

`fsdev serve` refuses to bind a network address when a flow has no `authentication.resolvePrincipal`, because the server would trust any `userId` a caller sends. Configure authentication on your flows. To deploy without it, use `fsdev serve --allow-unauthenticated`.

To own the entry file instead, call `serve(flowState)` from `@flow-state-dev/node`. It does not run the authentication check.
To own the entry file instead, call `serve(flowState)` from `@flow-state-dev/node`. It refuses the same way; pass `allowUnauthenticated: true` to override.

## 3. Set variables

Expand Down Expand Up @@ -103,7 +103,7 @@ The path is `/healthz`, not `/health`. What comes back:
| Response | Meaning |
| --- | --- |
| `200` `{"status":"ok"}` | The server is ready and the stores are open. |
| `503` `{"status":"initializing"}` | The port is bound but the stores are opening. The server answers the platform's health check during a cold start, so this is normal for a moment. Retry. |
| `503` `{"status":"initializing"}` | Only with the authentication check overridden: the port is bound but the stores are opening, so this is normal for a moment. Retry. With the check on, the stores open before the port listens, and until then connections are refused. |
| `500` | Store initialization failed for good. The process is up but requests error, and the deploy fails fast. Read the service logs. |

Under `fsdev serve`, an initialization failure exits the process with code `3` instead of returning `500`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ Skipped: B-09 is kept in the sitemap, and the page was already at `railway.md`.
- After revise round 2, page sha256 79696c585405: exit 0.
- After revise round 3, page sha256 04901962a47d: exit 1. Failed: node scripts/check-docs-page.mjs docs/contributing/docs-revamp/pages/build/deploy/railway.md.
- After the loop (review): Pass 4 banned word: the 503 row reads 'the stores are opening', without 'still'. The old-site deployment link points at Choose where to deploy (../deploy.md). 562 words. Page sha256 a01068c641b2: the page check exits 0 and the brand lint has 0 findings.
- After the loop (review): drift fix: `serve(flowState)` now refuses a network bind like `fsdev serve`, overridden by `allowUnauthenticated: true` (packages/node/src/serve.ts:192-196). The `503` health row now holds only with the check overridden: with it on, the stores open before the port listens, so connections are refused until then (packages/node/src/bind-guard.ts:67-72). 577 words. Page sha256 b436cbd98284.

## 5 · Fact check

Expand All @@ -51,6 +52,7 @@ Checked against the code: the page as pass 4 read it after the page as it was ke
- Reference row 8: Row 8: SQLite is single-writer, so concurrent replicas' writes fail. Untrue: SQLite allows one writer at a time, but connections set `busy_timeout = 5000` with WAL, so a second writer waits and fails only after the timeout. The filesystem store's data is per-process disk, so it is not shared across replicas. (/home/user/flow-state-dev/packages/store-sqlite/src/schema.ts:4-5,718-721) The row is recorded corrected.
- Reference row 10: Row 10: filesystem store rootDir (default shown `.flow-state-data`). Untrue: `rootDir` is a required option with no default. `.flow-state-data` is only the value the page's example passes. (/home/user/flow-state-dev/packages/engine/src/stores/index.ts:136-138) The row is recorded corrected.
- Re-run after the review edit: no new claim; the 503 row's meaning is unchanged (fact sheet section 2, SERVE:178-182), and the link target is B-07 in the sitemap.
- Re-run after the review edit: network binds await the guard, which resolves the router and opens the stores, before listening (packages/node/src/bind-guard.ts:67-72, :86); loopback and the override bind at once and answer `/healthz` 503 until init (packages/node/src/serve.ts:182-184); `fsdev serve` passes `allowUnauthenticated` through to `serve()` (packages/fsdev/src/commands/serve.ts:107-109).

## 6 · Depth pass

Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ export default createFlowState({

`workspace` is the one required key. Its `root` is the directory every checkout is made under, and its `source` says where each run's files come from. Here every run is cut from `/work/acme-shop`.

`codingDrainBudgetMs` takes the same `checks`, `project`, `judge` and `runTimeoutMs` you give `harnesses`, so a shutdown waits long enough for a full run. [Harness runs](../../reference/harness-runs.md) has the default.
`codingDrainBudgetMs` takes the same `checks`, `project`, `judge`, `idleTimeoutMs` and `runTimeoutMs` you give `harnesses`, so a shutdown waits long enough for a full run. [Harness runs](../../reference/harness-runs.md) has the default.

A worker becomes a coding worker with two lines in its file:

Expand All @@ -81,7 +81,7 @@ The body is the worker's instructions in the run's brief. [Harness runs](../../r

### Where a run works

<Figure svg={OneRun} caption="One run, with the kit's config keys" description={"Three boxes from left to right. The task fix-cart-test, with goal cart.test.ts passes, worker engineering.coder and harness claude-code, is on the board and has a hatched top because it outlives the request. An arrow leads to the run, claude-code in its own checkout, cut from workspace, on its own git branch and limited by runTimeoutMs. An arrow leads to the verdict: checks pnpm test, judge reads the goal, and review off unless set. The last row, then the task completes, is highlighted. A dashed arrow runs from the verdict back to the task, labelled not done. Three notes say the run starts in a checkout made from workspace, that checks, judge and review decide in that order, and that not done sends the task back to the board with the reason."} />
<Figure svg={OneRun} caption="One run, with the kit's config keys" description={"Three boxes from left to right. The task fix-cart-test, with goal cart.test.ts passes, worker engineering.coder and harness claude-code, is on the board and has a hatched top because it outlives the request. An arrow leads to the run, claude-code in its own checkout, cut from workspace, on its own git branch and stopped by idleTimeoutMs when it goes quiet. An arrow leads to the verdict: checks pnpm test, judge reads the goal, and review off unless set. The last row, then the task completes, is highlighted. A dashed arrow runs from the verdict back to the task, labelled not done. Three notes say the run starts in a checkout made from workspace, that checks, judge and review decide in that order, and that not done sends the task back to the board with the reason."} />

Each task gets a git worktree on its own branch, such as `conductor/fix-cart-test-3fa9c1`, in a folder under `root`. A retry lands in the same directory. The checkout is where the agent is pointed, not a jail: Claude Code as installed above can run shell commands as the server's user. [Harness runs](../../reference/harness-runs.md) has the checkout layout, setup commands, sandboxes and the run timeout.

Expand Down Expand Up @@ -190,7 +190,7 @@ The `harnesses` flow serves one view, `readiness`: a row per agent filled, reada

## Change it

Besides `workspace`, the kit takes `defaultHarness`, `review`, `pullRequests`, `judge` (on by default), `checks`, `project`, `runTimeoutMs` and `logReadiness`. An unknown key is refused. [Harness runs](../../reference/harness-runs.md) has each key's default, which option wins when a worker's file and the kit disagree, and how to replace the `coder` flow with your own.
Besides `workspace`, the kit takes `defaultHarness`, `review`, `pullRequests`, `judge` (on by default), `checks`, `project`, `idleTimeoutMs`, `runTimeoutMs` and `logReadiness`. An unknown key is refused. `idleTimeoutMs` stops a run after 20 minutes with no output from its agent. `runTimeoutMs` is an optional cap on a run's total time, 4 hours by default; `0` turns it off. [Harness runs](../../reference/harness-runs.md) has each key's default, which option wins when a worker's file and the kit disagree, and how to replace the `coder` flow with your own.
Comment thread
gitar-bot[bot] marked this conversation as resolved.
Resolved

## Next

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ Written by `docs-writer` (sonnet), 1396 words. Scenario: fix-cart-test, filed fo
- After the loop (review): the two cold-read gaps are answered on the page. A task whose agent is not ready fails at once with the reason and remedy and never moves to another agent; a `harness:` line naming an unfilled agent stops the app at start (the readiness check and refusal, `packages/harness-manager/src/readiness.ts:26,172`; the Codex and Cursor pages give each remedy). A waiting review keeps the task in progress on the same attempt; `revise` runs again in the same coding session and comes back for review; a passed deadline completes it as `review: "deadline"`, never as accepted (`packages/harness-manager/src/manager.ts:580-590,988`).
- After the loop (PR review): the PR review was taken: the install line adds the Claude Agent SDK peer and `@flow-state-dev/orchestration` (the review example imports its `inbox` subpath); the Codex `fill` line names the `@openai/codex-sdk@0.164.0` peer, says its `workspace` is the project section's module and adds `project: true`, which that module's `projectWorkspace()` source needs; the cutover comment is removed. Page sha256 5e41448bf829: the page check exits 0, the brand lint has 0 findings, and the edited examples type-check.
- After the loop (security review): the security review was taken: the verdict paragraph says the judge holds a task only at 70% confidence or more, that a judge that errors leaves the checks to decide, and that an open pull request holds the task even on not done. Page sha256 2b8205b1168b: the page check exits 0, the brand lint has 0 findings, and the edited examples type-check.
- After the loop (review): drift fix: the kit's key list adds `idleTimeoutMs`, which stops a run after 20 minutes with no output, and says `runTimeoutMs` is an optional cap on total run time, 4 hours by default, `0` off (packages/harness-manager/src/kit/harnesses-kit.ts:62-64, packages/harness-manager/src/kit/coder-flow.ts:99-102, packages/harness-manager/src/run-stops.ts:24, :31, :40-43). `codingDrainBudgetMs` takes `idleTimeoutMs` too (packages/harness-manager/src/kit/coder-flow.ts:166-178). 1220 words. The One run figure's label and description now name `idleTimeoutMs` as the run's limit, not `runTimeoutMs` (Gitar review). Page sha256 e1b963c179f2.

## 5 · Fact check

Expand All @@ -52,6 +53,7 @@ Checked against the code: the page as pass 4 read it after the draft, sha256 e3a
- Reference row 16: "Besides `workspace`, the kit takes these keys. An unknown key is refused." followed by a four-key table (`defaultHarness`, `review`, `checks`, `project`). Untrue: The kit's strict config also accepts `pullRequests` (default true: a task whose run opened a pull request waits for it to merge or close), `judge` (default true), `runTimeoutMs` (default 20 minutes) and `logReadiness` (default false). The table, introduced as the kit's keys, omits `pullRequests` and `logReadiness` entirely. The page's own step 4 depends on `pullRequests` being on by default but never names the key. (/home/user/flow-state-dev/packages/harness-manager/src/kit/harnesses-kit.ts:46-62; /home/user/flow-state-dev/packages/harness-manager/src/kit/coder-flow.ts:73-90) The row is recorded corrected.
- Re-run after the review edit: the review edit checked against the code, all true. `@anthropic-ai/claude-agent-sdk` is an optional peer of `@flow-state-dev/claude-code` (`packages/claude-code/package.json:57-64`) and `@openai/codex-sdk` 0.164.0 of `@flow-state-dev/codex` (`packages/codex/package.json:60-67`); `@flow-state-dev/orchestration` exports `./inbox` (`packages/orchestration/package.json:44`) and Workforce does not re-export it (`packages/workforce/package.json:26-59`).
- Re-run after the review edit: the review edit checked against the code, true. A not-done or ask under the floor counts as done (`packages/harness-manager/src/manager.ts:483-486`, `GOAL_JUDGE_FLOOR = 0.7` at `goal-judge.ts:35`); a judge that throws or times out gives no verdict and the run settles on its checks (`manager.ts:3550-3585`); a run that opened a pull request settles on it, a not-done included (`manager.ts:625-627,3742-3745`).
- Re-run after the review edit: `DEFAULT_IDLE_TIMEOUT_MS` is 20 minutes (packages/harness-manager/src/run-stops.ts:24); unset cap is 4 hours and `0` turns it off (run-stops.ts:31, :40-43); the kit schema accepts `idleTimeoutMs` positive and `runTimeoutMs` nonnegative and is strict (harnesses-kit.ts:62-67); `codingDrainBudgetMs` picks `idleTimeoutMs` (coder-flow.ts:167, :174).

## 6 · Depth pass

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Shift Manager builds nothing for the Lab, so the config has to default-export a

Shift Manager is research software. Several screens are placeholders that say what will fill them.

**Inbox** lists every approval and question a worker is waiting on you for, oldest first. Answer on the card, or reply to the worker beneath it. It lists asks in sessions you started and the runs those started, never another user's.
**Inbox** lists every approval and question a worker is waiting on you for, oldest first. Answer on the card, or reply to the worker beneath it. It lists asks in sessions you started and the runs those started, never another user's. It also lists asks from your workers' runs with no conversation; those you answer on the card alone, with no reply box.

**Tasks** lists every row on every board that isn't done, grouped by state, worker or workstream. Queued rows sit behind a toggle. Open one to see that worker's run as it happens, stop it with Interrupt, or follow it into the DevTool with *Open trace*.

Expand Down
Loading
Loading