From 0d7661afde9e0a5c6e8d41343e85dc938d862cb4 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 19:44:05 +0000 Subject: [PATCH 1/2] docs(revamp): fix drift on serve auth, schedules, harness timeouts and workforce views (FIX-2696) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011UNkLDgoASyf9UVtdTpqJw --- .../contributing/docs-revamp/pages/build/deploy/docker.md | 2 +- .../docs-revamp/pages/build/deploy/docker.record.md | 2 ++ .../docs-revamp/pages/build/deploy/railway.md | 4 ++-- .../docs-revamp/pages/build/deploy/railway.record.md | 2 ++ .../docs-revamp/pages/catalog/harnesses/index.md | 4 ++-- .../docs-revamp/pages/catalog/harnesses/index.record.md | 2 ++ .../docs-revamp/pages/catalog/starters/shift-manager.md | 2 +- .../pages/catalog/starters/shift-manager.record.md | 2 ++ .../docs-revamp/pages/catalog/workforce/index.md | 4 ++-- .../docs-revamp/pages/catalog/workforce/index.record.md | 2 ++ .../docs-revamp/pages/concepts/background-work.md | 2 +- .../docs-revamp/pages/concepts/background-work.record.md | 2 ++ .../docs-revamp/pages/concepts/serving-flows.md | 8 ++++---- .../docs-revamp/pages/concepts/serving-flows.record.md | 2 ++ .../docs-revamp/pages/start/add-to-an-existing-app.md | 2 +- .../pages/start/add-to-an-existing-app.record.md | 2 ++ 16 files changed, 30 insertions(+), 14 deletions(-) diff --git a/docs/contributing/docs-revamp/pages/build/deploy/docker.md b/docs/contributing/docs-revamp/pages/build/deploy/docker.md index ea94662536..8f3ff6f235 100644 --- a/docs/contributing/docs-revamp/pages/build/deploy/docker.md +++ b/docs/contributing/docs-revamp/pages/build/deploy/docker.md @@ -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/`. 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. diff --git a/docs/contributing/docs-revamp/pages/build/deploy/docker.record.md b/docs/contributing/docs-revamp/pages/build/deploy/docker.record.md index d57ee4b8af..1cef2efb06 100644 --- a/docs/contributing/docs-revamp/pages/build/deploy/docker.record.md +++ b/docs/contributing/docs-revamp/pages/build/deploy/docker.record.md @@ -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[]'. 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 @@ -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 diff --git a/docs/contributing/docs-revamp/pages/build/deploy/railway.md b/docs/contributing/docs-revamp/pages/build/deploy/railway.md index ba7b3c61e1..87dfe29df4 100644 --- a/docs/contributing/docs-revamp/pages/build/deploy/railway.md +++ b/docs/contributing/docs-revamp/pages/build/deploy/railway.md @@ -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 @@ -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`. diff --git a/docs/contributing/docs-revamp/pages/build/deploy/railway.record.md b/docs/contributing/docs-revamp/pages/build/deploy/railway.record.md index b1e076eda2..a42a93e805 100644 --- a/docs/contributing/docs-revamp/pages/build/deploy/railway.record.md +++ b/docs/contributing/docs-revamp/pages/build/deploy/railway.record.md @@ -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 @@ -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 diff --git a/docs/contributing/docs-revamp/pages/catalog/harnesses/index.md b/docs/contributing/docs-revamp/pages/catalog/harnesses/index.md index d3d8a1ba6d..2a0ca43f96 100644 --- a/docs/contributing/docs-revamp/pages/catalog/harnesses/index.md +++ b/docs/contributing/docs-revamp/pages/catalog/harnesses/index.md @@ -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: @@ -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. ## Next diff --git a/docs/contributing/docs-revamp/pages/catalog/harnesses/index.record.md b/docs/contributing/docs-revamp/pages/catalog/harnesses/index.record.md index 3ce3f169ed..b7361d4b98 100644 --- a/docs/contributing/docs-revamp/pages/catalog/harnesses/index.record.md +++ b/docs/contributing/docs-revamp/pages/catalog/harnesses/index.record.md @@ -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. Page sha256 ae71ef9efe06. ## 5 · Fact check @@ -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 diff --git a/docs/contributing/docs-revamp/pages/catalog/starters/shift-manager.md b/docs/contributing/docs-revamp/pages/catalog/starters/shift-manager.md index cbfd233630..558f1d0618 100644 --- a/docs/contributing/docs-revamp/pages/catalog/starters/shift-manager.md +++ b/docs/contributing/docs-revamp/pages/catalog/starters/shift-manager.md @@ -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*. diff --git a/docs/contributing/docs-revamp/pages/catalog/starters/shift-manager.record.md b/docs/contributing/docs-revamp/pages/catalog/starters/shift-manager.record.md index b5e526cfae..79b37bb732 100644 --- a/docs/contributing/docs-revamp/pages/catalog/starters/shift-manager.record.md +++ b/docs/contributing/docs-revamp/pages/catalog/starters/shift-manager.record.md @@ -46,6 +46,7 @@ Written by `docs-writer` (sonnet), 1054 words. Scenario: none: a catalog page ca - After the loop (review): the reference links now go to `../../reference/`, the depth the sibling starter pages use, and the Next line no longer implies Settings holds more than MCP keys (flag 10). - After the loop (review): the hire and fire line no longer says a fire waits for approval; the stock `fire` tool deletes the worker at once (`packages/workforce/src/workers/hire-blocks.ts:249-258`), and only an app-added wrapper makes it wait. +- After the loop (review): drift fix: the Inbox also lists asks from the user's workers' runs with no conversation, answered on the card only, with the reply box disabled (packages/shift-manager/src/surfaces/Inbox.tsx:1-24, :54-55, :473; packages/shift-manager/src/gaps.ts:86). 936 words. Page sha256 7b44c818e60a. ## 5 · Fact check @@ -56,6 +57,7 @@ Checked against the code: the page as pass 4 read it after the draft, sha256 b3d - Reference row 4: Inventory: "An open inventory ... TEAMS, Roster and Inbox read it to find them. Without it, TEAMS says there is none and the other screens load." Untrue: Without the inventory, TEAMS shows a failure section carrying a "No inventory to read ..." message, not a statement that there is none. The other screens do not simply load. The Shift Coordinator view shows a failure in place of the conversation. Inbox's asks fail with "Asks are read from worker sessions, and the worker inventory did not load", and an ask's reply is blocked. Roster shows an inventory failure, and only a roster of the user's own workers can still be drawn. (/home/user/flow-state-dev/packages/shift-manager/src/lib/reads.ts:808-827,934-936; src/surfaces/Sidebar.tsx:553-554; src/surfaces/ShiftCoordinator.tsx:208-215; src/surfaces/Inbox.tsx:491; src/surfaces/Roster.tsx:176-179,238-240; page line 36) The row is recorded corrected. - Reference row 8: Which conversation with the Shift Coordinator opens: "newest of yours", and what starts a new one. Untrue: The conversation is a single session per user and worker at a derived address, not the newest of several. The first line opens it, and nothing in Shift Manager starts a second one. (/home/user/flow-state-dev/packages/shift-manager/src/lib/conversation.ts:43-47,119-123) The row is recorded corrected. - Re-run after the review edit: no wrong claim. The stock `fire` handler deletes the roster entry with no approval step (`packages/workforce/src/workers/hire-blocks.ts:249-260`); a wait comes only from an app-added wrapper (`packages/workforce/README.md:1402-1422`). +- Re-run after the review edit: a run with no conversation has no session to read or reply into, and its box is disabled (packages/shift-manager/src/surfaces/Inbox.tsx:20-24, :55, :473). ## 6 · Depth pass diff --git a/docs/contributing/docs-revamp/pages/catalog/workforce/index.md b/docs/contributing/docs-revamp/pages/catalog/workforce/index.md index 0ed9a28acf..05f667d929 100644 --- a/docs/contributing/docs-revamp/pages/catalog/workforce/index.md +++ b/docs/contributing/docs-revamp/pages/catalog/workforce/index.md @@ -179,8 +179,8 @@ Workforce opens these slots for other kits to fill. It fills none of its own. A view answers one question from stored data and never writes. -- On `workforce-roster`: `roster`, the user's workers, standard and their own; `workerUsage`, tokens each worker used, by model, over a number of days; `workstreamReport`, the latest report from a workstream a worker leads; and `routines`, the user's scheduled routines. -- On `agent`: `listTasks_tasks`, the conversation's task list. +- On `workforce-roster`: `roster`, the user's workers, standard and their own; `workerUsage`, tokens each worker used, by model, over a number of days; `workerSessions`, the user's conversations with a worker; `sessionTurns`, one conversation's turns, with status and times but not their words; `workerMessages`, a worker's open messages and their answers; `inbox`, what waits on the user across their conversations; `workstreamReport`, the latest report from a workstream a worker leads; and `routines`, the user's scheduled routines. +- On `agent`: `listTasks_tasks`, the conversation's task list; and `delegates`, the workers the conversation hands tasks to. `roster` answers for a user before their first conversation. From the browser, `rosterView` and `workerUsageView` come from `@flow-state-dev/workforce/browser`. diff --git a/docs/contributing/docs-revamp/pages/catalog/workforce/index.record.md b/docs/contributing/docs-revamp/pages/catalog/workforce/index.record.md index 38b9c4dd22..001b051fe1 100644 --- a/docs/contributing/docs-revamp/pages/catalog/workforce/index.record.md +++ b/docs/contributing/docs-revamp/pages/catalog/workforce/index.record.md @@ -39,6 +39,7 @@ Written by `docs-writer` (sonnet), 1258 words. Scenario: support.billing, a work - After revise round 3, page sha256 de2a311aacfc: exit 0. - After the loop (review): the page moved from `catalog/workforce.md` to `catalog/workforce/index.md`, where the loop's rule puts a folder slug (`catalog/workforce/`), with its two figures, so the section's `./index.md` links resolve; relative links gained a level. The cold-read gap is answered: a fired worker's past sessions stay readable and a new turn on one is refused, with the message quoted from `packages/workforce/src/workers/installation.ts:833`. - After the loop (PR review): the owner asked for the value of Workforce up front, so the opening was rewritten by docs-writer and passed through docs-editor (REVISE, four findings taken; "kind" in its suggested wording swapped for the glossary's word): the questions a multi-agent app hits, what Workforce gives, that the harnesses kit and every starter build on it, and a list linking what it unlocks. The PR review was also taken: the Tools paragraph names the control tools a `tools:` line does not fence, and the cutover comment is removed. Page sha256 6dacbc2d782b: the page check exits 0 and the brand lint has 0 findings. +- After the loop (review): drift fix: the roster flow's views list adds `workerSessions`, `sessionTurns`, `workerMessages` and `inbox` (packages/workforce/src/workers/roster-flow.ts:72-85), and the `agent` flow's list adds `delegates`, which a session board declares (packages/workforce/src/conversation-board/session-board.ts:278, packages/workforce/src/agent-worker-flow.ts:1076-1080, :1518). 1452 words. Page sha256 e301fecd4b13. ## 5 · Fact check @@ -48,6 +49,7 @@ Checked against the code: the page as pass 4 read it after the draft, sha256 862 - Reference row 4: Row 4: "Skill locations by level (org, team, worker) and the `/` activation rule" is stated as holding a skill costing nothing until activated, with each user's copy keeping its own skills. Untrue: A skill is reachable from three places: by a leading `/`, by the worker's always-on `skills.active` list, and by the model through the load tool, which is on by default for a worker that holds a skill. When the load tool is on, a listing of the held skills is added to every turn. Skills are read from `org/skills/`, `teams//skills/` and the worker's own `skills/` folder, and the worker draws only from the levels it can see, so two teams' skills stay apart. (/home/user/flow-state-dev/packages/workforce/src/agent-worker-flow.ts:549-566; /home/user/flow-state-dev/packages/workforce/src/loader/read-worker-skills.ts:1-12) The row is recorded corrected. - Reference row 13: Row 13 and the page's Views section: `workerUsage` is "tokens each worker used by model" ("usage as tokens per worker by model"). Untrue: The usage view reads a period of per-day records, one row per worker, with one entry per source. A source is either a model id (`kind: "model"`) or a harness run with its billing (`kind: "harness"`), so a coding worker's spend is listed by harness, not by model. The period defaults to 7 days and is capped at 90. Harness runs on an api-key bill can carry `costUsd`. A run that reported nothing is counted in `runs` and `unreported`, with no tokens. A worker gone from the roster is read back marked `gone`. (/home/user/flow-state-dev/packages/workforce/src/workers/worker-usage.ts:1-45 (header), 47-60 (`WORKER_USAGE_MAX_DAYS` 90, `WORKER_USAGE_DEFAULT_DAYS` 7, source `kind` of model or harness)) The row is recorded corrected. - Re-run after the review edit: the new opening and the Tools edit checked against the code, all true. The harnesses kit has `requires: [workforce]` and fills `workerFlows` with `coder` (`packages/harness-manager/src/kit/harnesses-kit.ts:88-105`); every starter lists `workforce(...)` in `kits`; a coordinator hands each message to a delegate by its routing policy (`packages/workforce/src/coordinator/coordinator-flow.ts:3-4`, so "takes", not "reads"); a message to a worker off the user's roster is refused `no_worker` (`messages/consult.ts:91-92`); a project and its workstream entries are shared and conversations are not (`projects/collections.ts:11,60`); the error reporter turns a failure that stayed failed into one report previewed before filing (`error-reporter/index.ts:3-6`); `Roster`, `BoardColumns` and `BoardList` come from `react/index.ts:11-30`. Control tools bypass `tools:`: `sendMessage` (`messages/message-tool.ts:163`), standing-rule tools on user turns (`standing-rules/rules-capability.ts:136`), the conversation board's task tools (`conversation-board/board.ts:1961`). +- Re-run after the review edit: view names `workerSessions`, `sessionTurns`, `workerMessages`, `inbox` (packages/workforce/src/workers/keys.ts:157-177) and `delegates` (packages/workforce/src/delegates/delegate-keys.ts:18); what each answers from its definition's doc comment (workers/session-views.ts:173-181, :224-232; messages/worker-messages-view.ts:70; workers/inbox-view.ts:141-145). ## 6 · Depth pass diff --git a/docs/contributing/docs-revamp/pages/concepts/background-work.md b/docs/contributing/docs-revamp/pages/concepts/background-work.md index d11e9fffd4..44a81d79ce 100644 --- a/docs/contributing/docs-revamp/pages/concepts/background-work.md +++ b/docs/contributing/docs-revamp/pages/concepts/background-work.md @@ -101,7 +101,7 @@ A session of its own is not a separate process. On a host (the server your app r ## Work that starts on its own -A flow cannot start itself. Something outside calls the server, and the host turns that call into a run. A webhook is one such call, an event another service posts. A schedule is the other. +Some runs start with no user behind them. A webhook is one, an event another service posts, which the host turns into a run. A schedule is the other. A schedule is a named entry on the flow with a cron string, say `daily-digest` at seven each morning. The app fires it itself: once a minute it checks what is due, the schedules on the flow and the ones stored while it runs, and runs each one once per scheduled time. If several servers share one database, one of them does the checking. On a serverless host such as Vercel, where nothing stays running, one cron route does the check instead. Each firing is a fresh run that no user started, not the continuation of the last. The fields and the endpoint are in the [schedules reference](../reference/schedules.md), and the serverless setup is in [Run on a schedule with Vercel Cron](../build/schedules/vercel-cron.md). diff --git a/docs/contributing/docs-revamp/pages/concepts/background-work.record.md b/docs/contributing/docs-revamp/pages/concepts/background-work.record.md index db13ccf241..516100bd39 100644 --- a/docs/contributing/docs-revamp/pages/concepts/background-work.record.md +++ b/docs/contributing/docs-revamp/pages/concepts/background-work.record.md @@ -61,6 +61,7 @@ Closed after the loop: pass 7 findings 1 to 3, both suspected inaccuracies, and - After the loop (review): job-queue rename: the queued-run sentence and example use `bullmqJobQueue` and the `jobQueue` option of `createFlowState`. The example type-checks in apps/kitchen-sink/zz-jobqueue, deleted afterwards: only the planted error. 1061 words. Page sha256 14a07dfadc35. - After the loop (review): owner request: 2 action entries that set only `block` now name the block directly. 1440 words. Page sha256 cb90abf3dc63. - Post-merge edit (the app fires its own schedules): the schedule paragraph says the app checks once a minute, one server of several does it, and on a serverless host one cron route does. Page sha256 f9011f5e74d3: check-docs-page.mjs exits 0. +- After the loop (review): drift fix: "A flow cannot start itself. Something outside calls the server" contradicted the schedule tick the app runs itself each minute in a serving process (packages/engine/src/execution/schedule-tick.ts:1-35, packages/engine/src/flowstate/types.ts:420-423). The paragraph now opens on runs with no user behind them, a webhook and a schedule. 1079 words. Page sha256 fea0e30a5384. ## 5 · Fact check @@ -73,6 +74,7 @@ Checked against the code: the page as pass 4 read it after the draft, sha256 8d5 - Re-run after the review edit: `bullmqJobQueue` export (packages/bullmq/src/index.ts:9) and `jobQueue` option (packages/engine/src/flowstate/types.ts:374-383); default mode `colocated`, so the web process takes and runs the jobs (packages/bullmq/src/flowstate-adapter.ts:95; packages/engine/src/flowstate/createFlowState.ts:1124-1132). All true. - Re-run after the review edit: an action entry is a block or `{ block, ... }` (packages/core/src/types/flow.ts:749). - Post-merge edit, checked against the code: once a minute (`SCHEDULE_TICK_INTERVAL_MS = 60_000`, `engine/src/execution/schedule-tick.ts:35`); the flow's schedules and the stored ones (`schedules.static` and `index.claimDue`, `schedule-tick.ts:101`, `:112`); one server of several, through the store lease (`engine/src/execution/local-scheduler.ts:71`); on Vercel one cron route runs the tick (`packages/vercel/src/scheduler.ts:61`). +- Re-run after the review edit: the tick fires every static and dynamic schedule of every registered flow (packages/engine/src/execution/schedule-tick.ts:3-16) at a one-minute interval (:35). ## 6 · Depth pass diff --git a/docs/contributing/docs-revamp/pages/concepts/serving-flows.md b/docs/contributing/docs-revamp/pages/concepts/serving-flows.md index 3691dc4f6b..07bbd726ba 100644 --- a/docs/contributing/docs-revamp/pages/concepts/serving-flows.md +++ b/docs/contributing/docs-revamp/pages/concepts/serving-flows.md @@ -51,16 +51,16 @@ The flows do not change with the host. What changes is the file that mounts the import { serve } from "@flow-state-dev/node"; import flowstate from "../fsdev.config"; -await serve(flowstate); +await serve(flowstate, { host: "127.0.0.1" }); ``` -`serve` starts a long-lived server for the app. It binds every network interface and does not check that your flows have a resolver. `fsdev serve` does the same from the terminal, using `fsdev.config.ts`, and refuses to bind a network address while a flow has none; with `serve`, pass `host: "127.0.0.1"` until one is set. [Runtime options](../reference/runtime.md) has the port, health check and shutdown behaviour. +`serve` starts a long-lived server for the app. It runs the same check as `fsdev serve`, which does this from the terminal using `fsdev.config.ts`: on any host but loopback, it refuses to start while a flow has no resolver, and refuses calls to a flow registered later without one. `allowUnauthenticated: true` turns the check off. With no `host`, `serve` binds every network interface, so the sample binds `127.0.0.1` until a resolver is set. [Runtime options](../reference/runtime.md) has the port, health check and shutdown behaviour. ## Other ways in HTTP is the built-in door. From a terminal, `fsdev run support reply -i '{"message":"hi"}'` calls the action directly, with the stores and models from `fsdev.config.ts`. -MCP, webhooks and schedules are adapters you add to `createFlowState` with `adapters`. Each one hands the app the same kind of request. +MCP and webhooks are adapters you add to `createFlowState` with `adapters`. Each one hands the app the same kind of request. Schedules need no adapter. **MCP.** The Model Context Protocol is how clients such as Claude Desktop use outside tools. With the MCP adapter, the actions of `support` become tools, and an MCP call is an action call. See [MCP server](../reference/mcp-server.md). @@ -95,7 +95,7 @@ A delivery with a bad signature is refused with `401` and nothing runs. A verifi With no `sessionId` on the binding, each event runs in its own fresh session. Derive one from the payload, as in ``sessionId: (e) => `customer-${e.payload.data.object.customer}` ``, and one customer's invoices share a session while another customer gets a separate one. No end user is involved, so the run uses `defaultUserId: "system"`, with `requireUser: false`. Those two fields name the user the run acts as; they do not authenticate anyone. `verify` guards the webhook route; the app's other routes need a resolver. See [Webhooks](../reference/webhooks.md) and the [Stripe recipe](../build/webhooks/stripe.md). -**A schedule.** A schedule is a name and a cron string on the flow, with the block to run. The app keeps the clock: when the time comes it calls a URL the schedule adapter serves for that schedule, and the adapter runs the block. On a serverless host, one cron route wakes the app to do it. It is not an action call either. See [Schedules](../reference/schedules.md). +**A schedule.** A schedule is a name and a cron string on the flow, with the block to run. The app keeps the clock: when the time comes it calls that schedule's dispatch route, which every app serves under `/api/flows`, and the route runs the block. On a serverless host, one cron route wakes the app to do it. It is not an action call either. See [Schedules](../reference/schedules.md). ## What it gets you diff --git a/docs/contributing/docs-revamp/pages/concepts/serving-flows.record.md b/docs/contributing/docs-revamp/pages/concepts/serving-flows.record.md index d2a26e6b84..1bc235a5ea 100644 --- a/docs/contributing/docs-revamp/pages/concepts/serving-flows.record.md +++ b/docs/contributing/docs-revamp/pages/concepts/serving-flows.record.md @@ -39,6 +39,7 @@ Written by `docs-writer` (sonnet), 802 words. Scenario: The support desk: `suppo - After the loop: the SQLite example's filename is `support.db`, in the working directory. better-sqlite3 does not create parent directories (`store-sqlite/src/registry.ts:60` passes the filename straight to it), so a path under a missing folder stopped the server from starting. - Post-merge edit (the app fires its own schedules): the schedule paragraph says the app keeps the clock, and on a serverless host one cron route wakes it. Page sha256 1e65923ef8c0: check-docs-page.mjs exits 0. +- After the loop (review): drift fix: `serve()` now runs the same network-bind check as `fsdev serve`, refusing a non-loopback host while a flow has no resolver and refusing calls to a flow registered later (packages/node/src/serve.ts:192-196, packages/node/src/bind-guard.ts:80-87). The sample passes `{ host: "127.0.0.1" }` and the text names the `allowUnauthenticated: true` override. Schedules are dropped from the adapters sentence and the schedule paragraph names the dispatch route every app serves under `/api/flows`, since the router mounts it itself (packages/engine/src/transports/scheduled/createScheduledEndpointAdapter.ts:1-14, packages/engine/src/routes/createFlowApiRouter.ts:609). Type-check in apps/kitchen-sink/zz-drift, deleted afterwards: only the planted error, plus missing `@flow-state-dev/engine/host` exports from the stale local engine build. 1012 words. Page sha256 fca9f7eb8ec6. ## 5 · Fact check @@ -50,6 +51,7 @@ Checked against the code: the page as pass 4 read it after the draft, sha256 f5c - Post-review edit, checked: `flowAuthenticates` needs a non-default `resolvePrincipal` (`engine/src/routes/instance-caller.ts:91-95`); `serve` defaults to host `0.0.0.0` (`node/src/serve.ts:54-55`); the bind guard runs only in `fsdev serve`/`fsdev dev` (`fsdev/src/commands/serve.ts:109`, `dev.ts:371`). - Post-merge edit, checked against the code: the tick calls the schedule's dispatch URL through the app's own router, or over the network when a cron route gave it the deployment's address (`engine/src/flowstate/createFlowState.ts`, `#tick`, `scheduleDispatchRequest` then `router.POST` or `fetch`); the cron route is `vercelScheduler().route` (`packages/vercel/src/scheduler.ts:61`). +- Re-run after the review edit: `serve` awaits `assertNetworkBindIsAuthenticated` and installs a per-request guard off loopback unless `allowUnauthenticated` (packages/node/src/serve.ts:192-198); loopback and the override return early (packages/node/src/bind-guard.ts:84); default host `0.0.0.0` (packages/node/src/serve.ts:145); the scheduled endpoint is mounted on every router (packages/engine/src/routes/createFlowApiRouter.ts:609) and serves `POST …/schedules/*scheduleId/dispatch` and `GET …/schedules` (createScheduledEndpointAdapter.ts:31-40). ## 6 · Depth pass diff --git a/docs/contributing/docs-revamp/pages/start/add-to-an-existing-app.md b/docs/contributing/docs-revamp/pages/start/add-to-an-existing-app.md index 798e05bbfc..7bd94a1927 100644 --- a/docs/contributing/docs-revamp/pages/start/add-to-an-existing-app.md +++ b/docs/contributing/docs-revamp/pages/start/add-to-an-existing-app.md @@ -88,7 +88,7 @@ import flowstate from "../fsdev.config"; await serve(flowstate, { host: "127.0.0.1" }); ``` -`serve` binds every network interface unless you pass `host`, and it does not check who is calling. It does not read `.env.local` either, so start it with the file loaded: +`serve` binds every network interface unless you pass `host`. On any host but loopback it refuses to start while a flow has no way to check who is calling (`authentication.resolvePrincipal`), so this one binds `127.0.0.1`. It does not read `.env.local`, so start it with the file loaded: ```bash title="Terminal" npx tsx --env-file=.env.local src/server.ts diff --git a/docs/contributing/docs-revamp/pages/start/add-to-an-existing-app.record.md b/docs/contributing/docs-revamp/pages/start/add-to-an-existing-app.record.md index 2c6ab6a01a..0ab907a5e0 100644 --- a/docs/contributing/docs-revamp/pages/start/add-to-an-existing-app.record.md +++ b/docs/contributing/docs-revamp/pages/start/add-to-an-existing-app.record.md @@ -41,12 +41,14 @@ Written by `docs-writer` (sonnet), 621 words. Scenario: One flow `support` with - After the loop: the pass-9 miss is answered. The "Every call says who is calling" paragraph now says a call without a `userId` is refused (the client throws `userId is required`, `client/src/internal/http.ts:89-93`, `client/test/client.test.ts:53`; the default resolver answers 400, `engine/test/transports/http-adapter.test.ts:226-240`). - After the loop (review): the page's form clears its text only once `sendAction` resolves and shows `session.error`, since a refused send rejects and records the error (`packages/react/src/hooks/useSession.ts:441-445` and its catch, which calls `setError` and rethrows). It type-checks. - After the loop (review): the Node path now starts the server with `tsx --env-file=.env.local`, since `serve` and `createFlowState` load no env file and provider detection reads `process.env` (`packages/node/src/serve.ts`; `packages/core/src/models/providerDetection.ts`). +- After the loop (review): drift fix: the sentence after the Node sample no longer says `serve` does not check who is calling; on a non-loopback host it refuses to start while a flow has no `authentication.resolvePrincipal`, and the sample's `127.0.0.1` is exempt (packages/node/src/serve.ts:192-196, packages/node/src/bind-guard.ts:84). The Next sample is untouched. 660 words. Page sha256 8788b33c0f8a. ## 5 · Fact check Checked against the code: the page as pass 4 read it after the draft, sha256 932d1f9708e8, and the 10 Reference row(s) pass 6 moved. No untrue claim found. +- Re-run after the review edit: loopback hosts are `localhost`, 127.0.0.0/8 and `::1` (packages/node/src/bind-guard.ts:31-36); the guard returns early for them (:84); default host `0.0.0.0` (packages/node/src/serve.ts:145). ## 6 · Depth pass From b190411cec40297716e8552bdf959b94f9e4081d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 19:48:25 +0000 Subject: [PATCH 2/2] docs(revamp): the harness run figure names idleTimeoutMs as the run's limit (FIX-2696) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011UNkLDgoASyf9UVtdTpqJw --- .../docs-revamp/pages/catalog/harnesses/figures/one-run.svg | 2 +- docs/contributing/docs-revamp/pages/catalog/harnesses/index.md | 2 +- .../docs-revamp/pages/catalog/harnesses/index.record.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing/docs-revamp/pages/catalog/harnesses/figures/one-run.svg b/docs/contributing/docs-revamp/pages/catalog/harnesses/figures/one-run.svg index 912c5e46e5..6bb75db99b 100644 --- a/docs/contributing/docs-revamp/pages/catalog/harnesses/figures/one-run.svg +++ b/docs/contributing/docs-revamp/pages/catalog/harnesses/figures/one-run.svg @@ -23,7 +23,7 @@ its own git branch -limit: runTimeoutMs +limit: idleTimeoutMs set up apart from your tree diff --git a/docs/contributing/docs-revamp/pages/catalog/harnesses/index.md b/docs/contributing/docs-revamp/pages/catalog/harnesses/index.md index 2a0ca43f96..6b56f0001e 100644 --- a/docs/contributing/docs-revamp/pages/catalog/harnesses/index.md +++ b/docs/contributing/docs-revamp/pages/catalog/harnesses/index.md @@ -81,7 +81,7 @@ The body is the worker's instructions in the run's brief. [Harness runs](../../r ### Where a run works -
+
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. diff --git a/docs/contributing/docs-revamp/pages/catalog/harnesses/index.record.md b/docs/contributing/docs-revamp/pages/catalog/harnesses/index.record.md index b7361d4b98..2d36986996 100644 --- a/docs/contributing/docs-revamp/pages/catalog/harnesses/index.record.md +++ b/docs/contributing/docs-revamp/pages/catalog/harnesses/index.record.md @@ -41,7 +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. Page sha256 ae71ef9efe06. +- 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