flyloft 0.2.2__tar.gz → 0.4.0__tar.gz

flyloft-0.4.0/.containerignore

@@ -0,0 +1,10 @@
+# The test agent image builds from the repository root (tests/fixtures/agent-test-image). Anything a test run writes
+# here would change the build context between workers and rebuild the image in each one.
+.git
+.venv
+**/__pycache__
+**/*.pyc
+.pytest_cache
+.ruff_cache
+test-results
+web/node_modules

flyloft-0.4.0/.github/dependabot.yml

@@ -0,0 +1,45 @@
+# Dependabot checks on the first of each month and proposes each ecosystem's minor and patch updates as one pull
+# request. A version must have been published for two weeks before it is proposed, so a release that is pulled in its
+# first days never reaches a pull request. Major versions are ignored: each is taken by hand, deliberately (this also
+# keeps a security fix that only ships in a new major from opening a pull request; its alert still shows).
+# Security updates are a repository setting and are not delayed by the cooldown.
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 14
+    groups:
+      minor-and-patch:
+        update-types: ["minor", "patch"]
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
+
+  - package-ecosystem: "npm"
+    directory: "/web"
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 14
+    groups:
+      minor-and-patch:
+        update-types: ["minor", "patch"]
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 14
+    groups:
+      minor-and-patch:
+        update-types: ["minor", "patch"]
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]

flyloft-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,130 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# One suite per pull request, on its latest commit. A push to main has no head_ref, so it falls back to its own run
+# id: every merge builds, and no merge cancels the one before it.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  FLYLOFT_DURATIONS: tests/durations.json # pytest starts the long tests first (tests/conftest.py)
+
+jobs:
+  lint:
+    runs-on: ${{ vars.CI_RUNS_ON && fromJSON(vars.CI_RUNS_ON) || 'ubuntu-latest' }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs reads the version from git tags
+      - uses: astral-sh/setup-uv@v10.3.3
+      - run: uv sync --locked --all-extras
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+
+  types:
+    runs-on: ${{ vars.CI_RUNS_ON && fromJSON(vars.CI_RUNS_ON) || 'ubuntu-latest' }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.3.3
+      - run: uv sync --locked --all-extras
+      - run: uv run ty check src
+
+  web:
+    runs-on: ${{ vars.CI_RUNS_ON && fromJSON(vars.CI_RUNS_ON) || 'ubuntu-latest' }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.3.3
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - run: uv sync --locked --all-extras
+      - run: npm ci
+        working-directory: web
+      - run: npm run typecheck
+        working-directory: web
+      - run: npm test
+        working-directory: web
+      - run: npm run types && git diff --exit-code src/api/types.ts
+        working-directory: web
+
+  tests:
+    runs-on: ${{ vars.CI_RUNS_ON && fromJSON(vars.CI_RUNS_ON) || 'ubuntu-latest' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # GitHub's runners: each job runs every fourth test, as a scenario's turns are CPU-bound on 2 cores. Self-hosted:
+        # one job (shard 0), so one worker pool balances the whole suite and setup runs once.
+        shard: ${{ fromJSON(contains(vars.CI_RUNS_ON || '', 'self-hosted') && '[0]' || '[1, 2, 3, 4]') }}
+    name: ${{ matrix.shard == 0 && 'tests' || format('tests ({0}/4)', matrix.shard) }}
+    services:
+      postgres:
+        # None on self-hosted runners, where the suite starts its own per worker on a port the host hands out: jobs share
+        # the host, and rootless Docker picks a published port without seeing the host's ports in use.
+        image: ${{ !contains(vars.CI_RUNS_ON || '', 'self-hosted') && 'postgres:18' || '' }}
+        env:
+          POSTGRES_PASSWORD: flyloft
+          POSTGRES_DB: flyloft_test
+        ports:
+          - 127.0.0.1:5432:5432 # loopback only, as on a host: a contained turn must not reach it
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      FLYLOFT_SHARD: ${{ matrix.shard != 0 && format('{0}/4', matrix.shard) || '' }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.3.3
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - run: uv sync --locked --all-extras
+      - run: npm ci
+        working-directory: web
+      - run: npm run build # the browser scenario serves it
+        working-directory: web
+      - run: uv run playwright install ${{ runner.environment == 'github-hosted' && '--with-deps' || '' }} chromium # self-hosted has the deps and no sudo
+      - run: uv run pytest -q -n ${{ runner.environment == 'github-hosted' && 'auto' || '24' }} --dist worksteal --tracing retain-on-failure --output test-results # auto would be every core of a shared host; worksteal lets an idle worker take tests queued behind a long one
+        env:
+          FLYLOFT_TEST_DATABASE_URL: ${{ runner.environment == 'github-hosted' && 'postgresql://postgres:flyloft@127.0.0.1:5432/flyloft_test' || '' }}
+      - uses: actions/upload-artifact@v7 # a failed browser test's trace: npx playwright show-trace trace.zip
+        if: failure()
+        with:
+          name: playwright-traces-${{ matrix.shard }}
+          path: test-results/
+          if-no-files-found: ignore
+          retention-days: 14
+
+  client:
+    runs-on: ${{ vars.CI_RUNS_ON && fromJSON(vars.CI_RUNS_ON) || 'ubuntu-latest' }}
+    strategy:
+      matrix:
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          cache-python: true # the matrix installs a managed 3.11 and 3.12 on every run
+      - run: uv venv client-venv --python ${{ matrix.python }} && uv pip install --python client-venv/bin/python .
+      - run: client-venv/bin/flyloft --help
+      - run: client-venv/bin/flyloft install --harness claude
+        env:
+          HOME: ${{ runner.temp }}/home # a self-hosted runner's home is shared by every job

{flyloft-0.2.2 → flyloft-0.4.0}/.github/workflows/python-publish.yaml

@@ -11,11 +11,11 @@ jobs:
       id-token: write # trusted publishing: PyPI accepts this workflow's OIDC token, no API token
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0 # hatch-vcs reads the version from the release tag
-      - uses: astral-sh/setup-uv@v6
-      - uses: actions/setup-node@v4
+      - uses: astral-sh/setup-uv@v10.3.3
+      - uses: actions/setup-node@v7
         with:
           node-version: 22
           cache: npm

{flyloft-0.2.2 → flyloft-0.4.0}/AGENTS.md

@@ -47,7 +47,8 @@ This branch is a fresh design. Documents stand alone and do not describe the sys
 ## Setup and tests
 
 - `uv sync` installs everything. Run commands as `uv run ...`.
-- `uv run pytest -n 4` runs tiers one and unit tests on four workers; each worker gets its own database. Scripted turns are CPU-bound, so use no more workers than cores (CI uses `-n auto`: two on its runner). It starts a PostgreSQL container with rootless Podman unless `FLYLOFT_TEST_DATABASE_URL` is set.
+- `uv run pytest -n 4` runs tiers one and unit tests on four workers; each worker gets its own database. Scripted turns are CPU-bound, so use no more workers than cores (CI on GitHub's runners uses `-n auto`, two per runner, in each of four jobs, and `FLYLOFT_SHARD=i/4` runs every fourth test; on the lab's self-hosted runners it is one job with `-n 24 --dist worksteal`. The repo variable `CI_RUNS_ON`, a JSON `runs-on` value, picks the runners; unset means `ubuntu-latest`). It starts a PostgreSQL container with rootless Podman unless `FLYLOFT_TEST_DATABASE_URL` is set.
+- Added or reshaped a scenario test? Make your full run before committing `FLYLOFT_RECORD_DURATIONS=1 uv run pytest -n 4`, and commit the `tests/durations.json` it updates; CI starts the long tests first by it, and a test the file lacks counts as 1 s.
 - `FLYLOFT_LIVE=1 uv run pytest -m live` runs tier two against the configured cluster and test repository.
 - `uv run flyloft --help` lists the client's commands; `uv run flyloft host --help` the host's.
 - The board: `npm ci` and `npm run build` in `web/` (Node 22+), then `uv run flyloft host web` serves it on `web_bind`. `npm run types` regenerates `web/src/api/types.ts` from the API; CI fails if it drifts.

{flyloft-0.2.2 → flyloft-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flyloft
-Version: 0.2.2
+Version: 0.4.0
 Summary: Agent swarms for empirical research on Slurm clusters
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27

{flyloft-0.2.2 → flyloft-0.4.0}/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # flyloft Architecture
 
-Status: approved 2026-09-21. Stage 1 complete on 2026-09-23 (see [design/stage-1.md](design/stage-1.md)); stage 2 complete on 2026-09-23 (tiers one, two, and three passed; see [design/stage-2.md](design/stage-2.md)); stage 3a complete (see [design/stage-3a.md](design/stage-3a.md)). Stage 3b complete (see [design/stage-3b.md](design/stage-3b.md)). Stage 4a complete on 2026-09-25 (tiers one, two, and three passed; see [design/stage-4a.md](design/stage-4a.md)). Stage 4b complete on 2026-09-25 (tiers one, two, and three passed; see [design/stage-4b.md](design/stage-4b.md)). Stage 5a complete on 2026-09-27 (tiers one, two, and three passed; see [design/stage-5a.md](design/stage-5a.md)). Stage 5b complete on 2026-09-27 (tiers one and three passed; see [design/stage-5b.md](design/stage-5b.md)). Stage 5c complete on 2026-09-28 (tiers one and three passed; see [design/stage-5c.md](design/stage-5c.md)). Stage 5d complete on 2026-09-28 (tiers one and three passed; see [design/stage-5d.md](design/stage-5d.md)). Stage 6a complete on 2026-09-29 (tiers one and three passed; see [design/stage-6a.md](design/stage-6a.md)). Stage 6b complete on 2026-09-30 (tiers one and three passed; see [design/stage-6b.md](design/stage-6b.md)). Stage 7 complete on 2026-09-30 (tiers one, two, and three passed; see [design/stage-7.md](design/stage-7.md)). Every staged part is built. The vision's revision of 2026-10-13 widens flyloft to two modes, investigate and optimize, with a lab-wide toolshed; what comes next is in §6, *What comes next*. The Projects rework's board flow and template repositories are built and closed on 2026-10-19 (tiers one, two, and three passed; see [design/projects.md](design/projects.md)); the investigate mode is next, in four parts, the first built (see [design/investigate.md](design/investigate.md)); then the agent interface, where the researcher's own coding agent starts work and the board is where they come back to (see [design/agent-interface.md](design/agent-interface.md)). A critic-judged campaign's 0-GPU runs go to its cluster's CPU partition, sized within a CPU-run limit (see [design/cpu-partition.md](design/cpu-partition.md)).
+Status: approved 2026-09-21. Stage 1 complete on 2026-09-23 (see [design/stage-1.md](design/stage-1.md)); stage 2 complete on 2026-09-23 (tiers one, two, and three passed; see [design/stage-2.md](design/stage-2.md)); stage 3a complete (see [design/stage-3a.md](design/stage-3a.md)). Stage 3b complete (see [design/stage-3b.md](design/stage-3b.md)). Stage 4a complete on 2026-09-25 (tiers one, two, and three passed; see [design/stage-4a.md](design/stage-4a.md)). Stage 4b complete on 2026-09-25 (tiers one, two, and three passed; see [design/stage-4b.md](design/stage-4b.md)). Stage 5a complete on 2026-09-27 (tiers one, two, and three passed; see [design/stage-5a.md](design/stage-5a.md)). Stage 5b complete on 2026-09-27 (tiers one and three passed; see [design/stage-5b.md](design/stage-5b.md)). Stage 5c complete on 2026-09-28 (tiers one and three passed; see [design/stage-5c.md](design/stage-5c.md)). Stage 5d complete on 2026-09-28 (tiers one and three passed; see [design/stage-5d.md](design/stage-5d.md)). Stage 6a complete on 2026-09-29 (tiers one and three passed; see [design/stage-6a.md](design/stage-6a.md)). Stage 6b complete on 2026-09-30 (tiers one and three passed; see [design/stage-6b.md](design/stage-6b.md)). Stage 7 complete on 2026-09-30 (tiers one, two, and three passed; see [design/stage-7.md](design/stage-7.md)). Every staged part is built. The vision's revision of 2026-10-13 widens flyloft to two modes, investigate and optimize, with a lab-wide toolshed; what comes next is in §6, *What comes next*. The Projects rework's board flow and template repositories are built and closed on 2026-10-19 (tiers one, two, and three passed; see [design/projects.md](design/projects.md)); the investigate mode followed, in four parts, the first built (see [design/investigate.md](design/investigate.md)), the second parked on 2026-10-22 (§8: a bar fixed at launch), so the toolshed is its next part; then the agent interface, where the researcher's own coding agent starts work and the board is where they come back to (see [design/agent-interface.md](design/agent-interface.md)). A critic-judged campaign's 0-GPU runs go to its cluster's CPU partition, sized within a CPU-run limit (see [design/cpu-partition.md](design/cpu-partition.md)). On a cluster that names an object storage `work_dir_archive`, each ended run's directory and each ended campaign's folder move to the bucket (see [design/run-storage.md](design/run-storage.md)). The toolshed is built and closed: tiers one, two, and three passed on 2026-10-27 (see [design/toolshed.md](design/toolshed.md)). A researcher's own agent runs one job on a cluster without a project or campaign, through `flyloft job` (see [design/direct-jobs.md](design/direct-jobs.md)).
 
 This document settles the shape of flyloft: the record that holds its state, the lifecycle and authority rules, the agent turn, the subsystem boundaries, and the stages by which the system grows. It fixes what is expensive to change later and leaves everything else to the design document of the stage that needs it. [VISION.md](VISION.md) says what flyloft is for; [AGENTS.md](../AGENTS.md) says how to work on it. This document is the bridge between them.
 
@@ -75,9 +75,9 @@ An assessment must link to the run whose result it judges. It exists so an agent
 
 Stage two changes the last step: a finding entry leaves the hypothesis in testing, and a critique that accepts the finding moves it to supported. Stage 4a inserts screened and admitted between proposed and testing, and merged beside them for a duplicate; replication before review is a rule at the finding, not a state. States are text and transitions are code, so this growth is not shape.
 
-**Run lifecycle.** preparing, queued, running, finished, failed, canceled, unknown. The application state is derived from observed scheduler state. A job missing from the queue is unknown until confirmed, never assumed finished. A finished job without its expected result files yields an incomplete result, not a conclusion.
+**Run lifecycle.** preparing, queued, running, finished, failed, canceled, interrupted, unknown. The application state is derived from observed scheduler state. A job missing from the queue is unknown until confirmed, never assumed finished. A finished job without its expected result files yields an incomplete result, not a conclusion. A preempted job is requeued by the cluster and waited on; it is interrupted when it is never requeued or its attempts have used twice its time limit. Interrupted is infrastructure, not a verdict, and is charged for the time it used ([design/preemption.md](design/preemption.md)).
 
-**Campaign lifecycle.** active, stopped, done. No campaign waits on a human (stage 5d): a failed turn is retried and, after three in a row, the agent is benched; a stall wakes the decision-maker and then finishes the campaign; a failed baseline stops it with its reason. Stopped means a human stopped new work, or the baseline failed; outstanding runs finish and are collected.
+**Campaign lifecycle.** active, stopped, done. No campaign waits on a human (stage 5d): a failed turn is retried and, after three in a row, the agent is benched; a stall wakes the decision-maker and then finishes the campaign; a baseline that does not finish stops it with its reason, an interrupted one naming the preemption. Stopped means a human stopped the campaign, or the baseline failed; its outstanding runs are canceled, since the hypotheses they serve are abandoned (2026-11-02; before, they finished and were collected).
 
 **Agent state.** idle, active, benched. The active state is the claim that prevents a second concurrent turn for the same agent. It lives on the agent, not the campaign.
 
@@ -103,7 +103,7 @@ A turn is one disposable process. The system assembles context, launches the age
 
 **Assembly** is a function of role, agent, and campaign that produces one rendered assignment, written to disk and referenced from the turn row. At stage one it renders the campaign's question, criterion, baseline, and constraints; the project's research brief from its repository; the submissions remaining; and the whole record so far: hypotheses with states, runs with results, findings, assessments, and steering. A single campaign's record fits in a turn's context, so there is no read tool. Run directories are on the same host, so the assignment names them and the agent reads logs from disk.
 
-**Tools.** The implementer's MCP server exposes five tools, one per entry kind it may post: propose, request_run, assess, post_finding, ask. Each validates its body against the kind's schema and returns errors in the turn, so the agent corrects mistakes before it exits. Two rules live in request_run: the worktree must be clean and HEAD is recorded as the tested commit; and one run may be outstanding per campaign. The tool records intent and returns a run identity. Staging and submission happen after the turn, and the agent learns the outcome from the result entry in its next turn. SSH latency and submission failures never enter the agent's process.
+**Tools.** The implementer's MCP server exposes five tools, one per entry kind it may post: propose, request_run, assess, post_finding, ask. Each validates its body against the kind's schema and returns errors in the turn, so the agent corrects mistakes before it exits. Two rules live in request_run: the agent's branch tip, fetched into the host's repository, is the tested commit (docs/design/agent-isolation.md §4a); and one run may be outstanding per campaign. The tool records intent and returns a run identity. Staging and submission happen after the turn, and the agent learns the outcome from the result entry in its next turn. SSH latency and submission failures never enter the agent's process.
 
 **Substrates.** A substrate executes a turn: run this assignment with these tools and report exit status. Two exist at stage one, which is what justifies the interface. The coding-harness substrate launches a harness headless in the worktree with the assignment as its prompt and the tool server configured. The scripted substrate, used in tests, connects to the same tool server and issues tool calls from a script. Every role runs in a coding harness or the scripted substrate; a role that does not edit code runs under a read-only tool policy. A native tool-calling loop is deferred until a role's harness overhead or a subscription's limits are observed to be a problem.
 
@@ -143,7 +143,7 @@ flowchart LR
     CLI --> PG[(PostgreSQL)]
     S[Service] <--> PG
     S -->|launch turn| H[Harness]
-    H -->|stdio| T[Tool server]
+    H -->|socket| T[Tool server]
     T --> PG
     H --> M[Model endpoint]
     S -->|ssh| C[Slurm clusters]
@@ -151,7 +151,7 @@ flowchart LR
 ```
 
 - **The service.** One long-running process whose tick wakes agents, launches turns, stages and submits runs, observes jobs, and publishes. A run waits in the record until its campaign has a free run slot; a free slot goes to integration runs first, then the root island's runs, then island test runs, first come first within each, so consolidation never queues behind exploration.
-- **Per-turn processes.** The harness, and the tool server it launches as a stdio subprocess with the agent and turn identity in its environment. The server writes entries through record.
+- **Per-turn processes.** The harness, in a container, and the tool server the service starts on the host behind a socket for that turn alone; the socket is the agent and turn identity. The server writes entries through record.
 - **The CLI.** Short-lived. It reads the record for status and posts steering entries.
 
 Two processes write to the record from the first turn, the service and the tool server, so PostgreSQL is a stage-one necessity rather than preparation.
@@ -169,7 +169,7 @@ Two processes write to the record from the first turn, the service and the tool
 5. UUID identities.
 6. Agents act only through the tool surface, with tool lists per role.
 7. A substrate interface, justified by two implementations.
-8. A worktree per agent.
+8. A worktree per agent, and in a campaign with a toolshed, a worktree of the shed beside it.
 9. PostgreSQL with numbered SQL migrations.
 10. What the researcher fixes at start is immutable: the question and, for an optimization, the baseline, metric, direction, and target, as campaign columns.
 11. Observed external state lives on entity rows with a last-observed timestamp.
@@ -181,7 +181,7 @@ Two processes write to the record from the first turn, the service and the tool
 
 **Stage 2: a critic.** A finding is a candidate until a critic, running in a harness under a read-only tool policy, accepts it or blocks it with its reason. Only accepted findings reach the pull request. Adds the critique kind, finding state, per-role harness and model selection, and role wake filters. First communication between roles through the record.
 
-**Stage 3: several implementers, in two parts.** 3a: hypotheses in flight in parallel, each on its own branch off the campaign branch, admitted up to a per-campaign slot count. An integrator merges accepted implementations and keeps the campaign branch runnable. The same question runs with one and several implementers, and a compare report gives verified improvement against cost: the first control arm. Adds the integration kind, run ownership, wake predicates with relevance, the cost ledger, a done state for exhausted campaigns, and an allowlisted harness environment. 3b: a read-only web view of the board. The HTTP tool server with per-turn tokens is deferred; the reason is in [design/stage-3a.md](design/stage-3a.md) §7.
+**Stage 3: several implementers, in two parts.** 3a: hypotheses in flight in parallel, each on its own branch off the campaign branch, admitted up to a per-campaign slot count. An integrator merges accepted implementations and keeps the campaign branch runnable. The same question runs with one and several implementers, and a compare report gives verified improvement against cost: the first control arm. Adds the integration kind, run ownership, wake predicates with relevance, the cost ledger, a done state for exhausted campaigns, and an allowlisted harness environment. 3b: a read-only web view of the board. The tool server's per-turn socket belongs to [agent isolation](design/agent-isolation.md).
 
 **Stage 4: a population, in two parts.** 4a: generators with distinct framings propose; proximity merges duplicates within the campaign; a coordinator admits under a posture set by the researchers; a finding needs the seeds the campaign demands. Adds the decision kind, the screened, admitted, and merged states, replication as a rule, and the control arm extended to the population. 4b: memory. A new campaign reads what the project's earlier campaigns settled, rendered from the record; proximity flags repeats of earlier work; revivals carry lineage as links; `memory = false` starts fresh. Adds the knowledge module. Read and search tools keep their trigger.
 
@@ -197,11 +197,11 @@ Two processes write to the record from the first turn, the service and the tool
 
 **The Compute page.** After campaign-level compute, its own change ([design/compute.md](design/compute.md)): a sidebar page where each cluster says what each GPU type its file lists has (free GPUs, flyloft's running and queued jobs, nodes, CPUs, memory, longest run, and most free on a node), cached for 30 seconds and asked per cluster over the runs module's SSH client; the launch page's GPU type select shows each type's free count.
 
-**What comes next.** The vision's revision of 2026-10-13 widens flyloft from optimization to two modes, investigate and optimize, and adds a toolshed shared across the lab. Stages 1 through 7 built the optimize mode. What follows is staged like everything before it, each part with its own scenario and a design document written when it begins: the Projects rework, which makes bringing a project one flow on the board and turns templates into GitHub template repositories registered with flyloft (see [design/projects.md](design/projects.md)); then the investigate mode, in four parts: a solo, exploratory investigation whose project may be only a brief ([design/investigate.md](design/investigate.md)); a test fixed in advance, making findings confirmed; the toolshed; and investigation at swarm size. Then the agent interface ([design/agent-interface.md](design/agent-interface.md)): the researcher's coding agent is flyloft's front door (sign-in from a laptop, `submit` of a brief that flyloft turns into a repository and a campaign, a `flyloft` client with every initiating action, a skill), the host's commands move under `flyloft host` and admin actions under `flyloft admin`, and the board becomes where people monitor and steer; its second part adds tasks, a third label on the investigation engine ([design/tasks.md](design/tasks.md)); both are built and closed (2026-10-22). Their mechanics are decided in their design documents, not here.
+**What comes next.** The vision's revision of 2026-10-13 widens flyloft from optimization to two modes, investigate and optimize, and adds a toolshed shared across the lab. Stages 1 through 7 built the optimize mode. What follows is staged like everything before it, each part with its own scenario and a design document written when it begins: the Projects rework, which makes bringing a project one flow on the board and turns templates into GitHub template repositories registered with flyloft (see [design/projects.md](design/projects.md)); then the investigate mode, in four parts: a solo, exploratory investigation whose project may be only a brief ([design/investigate.md](design/investigate.md)); a test fixed in advance, making findings confirmed; the toolshed; and investigation at swarm size. The second part was parked on 2026-10-22 (§8): the researcher's own agent is the front door, so what follows a campaign is decided there, from the three campaign types and the client's commands, and a bar the researcher already knows goes into the brief, which the critic judges against today. flyloft builds primitives any workflow can be assembled from, not the workflows; the toolshed is the next primitive, and it is built ([design/toolshed.md](design/toolshed.md)): a lab-owned, public repository of tools, each a self-contained image with a prose skill; a campaign's run may name a tool and runs inside its image, and a campaign that needs a tool the shed lacks builds it through the shed's pull request, its own test run of the candidate image, and the critic's review, with no human in the loop. Then the agent interface ([design/agent-interface.md](design/agent-interface.md)): the researcher's coding agent is flyloft's front door (sign-in from a laptop, `submit` of a brief that flyloft turns into a repository and a campaign, a `flyloft` client with every initiating action, a skill), the host's commands move under `flyloft host` and admin actions under `flyloft admin`, and the board becomes where people monitor and steer; its second part adds tasks, a third label on the investigation engine ([design/tasks.md](design/tasks.md)); both are built and closed (2026-10-22). Their mechanics are decided in their design documents, not here.
 
 Recovery is built when a stage loses work, most likely stage three, when a service restart first interrupts many turns at once. It is not scheduled.
 
-**Known stage-one limitation.** The tool server is a stdio subprocess launched by the harness, so database credentials are in the harness's environment and a misbehaving agent could bypass the tool surface. With one trusted agent on a lab host this is accepted. Stage 3a narrows it by allowlisting the harness environment, so cluster and GitHub credentials no longer reach agent processes; the database credential goes when the tool server moves to HTTP, deferred until a turn runs where that credential cannot be given to the process.
+**Agent isolation.** No agent process holds the database credential, and identity follows the turn's socket rather than a claim in its environment: a turn's tool server runs on the host behind a socket that exists for that turn alone, and the harness runs in a container that holds only its own campaign's repository and the model endpoint. See [design/agent-isolation.md](design/agent-isolation.md).
 
 ## 7. Testing
 
@@ -232,13 +232,20 @@ Ideas that have arrived before their stage. Adding a line here is how an impulse
 | Several critics with different framings per candidate finding | When one critic's acceptance proves a rubber stamp, expected by stage 4 |
 | Integrator role; run admission with per-campaign slots | Stage 3a |
 | Budget ledger for tokens, GPU-hours, and cost | Stage 3a; at 4a the coordinator reads the ledger in its assignment, so there is no query tool |
-| HTTP tool server with per-turn tokens | When a turn runs where the database credential cannot be given to the process: a remote executor, an external agent, a provider's hosted runtime |
 | Read-only web API and dashboard | Done at stage 3b: a JSON read API, one change stream per campaign, and a single-page application served by `flyloft host web` |
 | Steer, approve, and stop from the board | Done at stage 5b: `POST` routes on the board's one router calling `record/researcher.py`, which the CLI calls too; approve deleted at stage 5d, when decompositions open at once |
 | Starting or configuring a campaign from the board | Board part 3: registering projects and launching campaigns; see [design/board-3.md](design/board-3.md) |
 | Authentication for the board: GitHub sign-in through a GitHub App (or an OAuth App) whose token also lets flyloft push and open pull requests as the signed-in user; owners on campaigns; an allowlist with admins; an admin page for users and host health | Next: see [design/multi-user.md](design/multi-user.md) |
 | Refreshing GitHub App user tokens (eight hours, with a six-month refresh token), so a host can leave the app's token expiration on; today it must opt out | When a lab will not register an app with expiration off |
-| Agents run as a separate OS user who cannot read the host's configuration, `secrets.env`, or the database, so a prompt-injected agent cannot read stored GitHub tokens | When flyloft runs an untrusted model or harness, or a lab will not accept agents sharing the operator's account |
+| Egress filtering: a contained agent can still reach the internet and leak what it can read, its own campaign's code and the record entries in its assignment; the route is an allowlisting proxy through `HTTPS_PROXY` ([design/agent-isolation.md](design/agent-isolation.md) §11) | When a leak happens or a project holds data that must not leave |
+| A flyloft-scoped object storage key, kept out of runs' reach: archive jobs get Sarah's full-access key in their environment, and a run on the same node as the same user can read it | With runs isolated per campaign; already deferred by run storage |
+| A forced command on flyloft's cluster key, to limit what the key does if the service user itself is compromised | When the service user's compromise is a threat worth the command's upkeep; agents do not reach the key |
+| A per-turn model key, or a proxy that adds the key outside the container | If the shared key leaks or LiteLLM spend needs attributing per campaign |
+| Run credentials and per-user secrets (W&B and the like); anything a run can read, its agent can read, so the rule is lab-scoped keys in runs and personal keys used only on the host | When a project needs a key a run cannot hold |
+| Turn containers under a separate, agent-only OS user, so a container escape does not land as the service's user; not the shared `brineylab` account | When flyloft runs an untrusted model, or a Podman or crun escape relevant to the host is published |
+| Agents interfering within their own campaign: implementers of one campaign share its repository and can move one another's branches | When it is seen |
+| A campaign repository borrows objects from the project clone through alternates; pruning the project clone after a force-push to its base could break it | When seen |
+| A turn holds no database credential, but on podman 5 with pasta `host.containers.internal` reaches the host, so a service bound beyond loopback answers a turn | Tier two on partlow checks that the database and the board refuse a contained turn at `host.containers.internal` |
 | A better estimate of a run's cost than its time limit: a budgeted campaign reserves each next config at `time limit × GPUs`, so it ends far short of its cap when runs finish well inside the limit (toy-live c812fc9f: "budget spent" at 0.2 of 0.5 GPU-h, runs ~200 s against a 1200 s limit); reserving by the baseline's measured duration is the likely fix, and the ESM-2 project's 24-hour data-regime limit is the case that will show it | Done: see [design/budget-billing.md](design/budget-billing.md). A run is charged the GPU time it uses, new work starts while any budget is left, and planning reads the campaign's measured mean run |
 | Per-seed dots on the chart beside each config's mean | When a researcher misses them |
 | A margin or significance test before a config's mean beats its reference, the integrator's best of head, finding alone, and merged included | When promotions are seen on noise. Seen on ESM-2 f6b4591b at replication 1: the integrator replaced a head holding the accepted cosine schedule with a tree lacking it on 2.561 against 2.564, a 0.003-nat margin, and accepted steps of 0.004 to 0.009 rest on one seed each |
@@ -246,11 +253,16 @@ Ideas that have arrived before their stage. Adding a line here is how an impulse
 | The integrator's assignment names the verdict from its first integration run while the record judges its latest request; they diverge only if an integrator re-merges to a different tree and requests again | When a live integrator is refused that way |
 | The board's read layer computes each hypothesis's comparison per page more than once (O(hypotheses × runs) per request, re-run on every change event) | When a long campaign's page is seen slow with the board open |
 | The CLI as a client of the board's API, so anyone can use it from their own machine without the host's secrets; today the host's CLI acts as the operator who ran `flyloft host login` | Done: see [design/agent-interface.md](design/agent-interface.md) |
+| A launch field naming the campaign a follow-up builds on, with its location passed to jobs | When a follow-up needs it without an agent to find it, for example an optimization whose code must read an earlier campaign's data by path |
+| Runs isolated per campaign: every campaign's directory, its runs inside it, sits under `<owner>/<project>/` in one directory owned by the cluster's flyloft account, so a run's code can write any other campaign's; ownership enforced by per-campaign mounts from the cluster's prolog | When a campaign damages another's work |
+| Campaigns that write shared data | When a campaign needs to build a dataset in place |
+| Moving files from before the storage cutover into the new layout | When someone needs an old campaign's files |
+| Per-owner disk quotas | When one owner's files crowd out the lab's |
 | Per-user or locked project scope, or the compare page flagging that two campaigns' stored project configurations differ; today any user may edit a shared project | When a colleague's edit invalidates a comparison |
 | Transferring a campaign's ownership | When a user leaves mid-campaign and someone must publish for them |
 | Usage accounting on the admin page: GPU-hours and cost per user and per project | When a PI asks who spent what |
 | Editing clusters and harnesses on the board (they carry secrets) | When someone other than the operator needs to add a cluster |
-| Notifications: a Slack incoming webhook that posts each decision-maker's note | When campaigns run unattended long enough that checking the board misses notes; at stage 6b a promotion's new draft pull request already notifies the repository's watchers |
+| Notifications: a Slack incoming webhook that posts each decision-maker's note, and a role waiting on its model | When campaigns run unattended long enough that checking the board misses notes; at stage 6b a promotion's new draft pull request already notifies the repository's watchers |
 | Replication as the unit of judgment: a config is a tree measured at `replication` seeds in parallel; code compares paired means; nothing is measured twice; the integrator keeps the best of head, finding alone, and merged; one chart dot per config | Done in three plans, closed 2026-10-07: see [design/replication.md](design/replication.md) |
 | A Claude Code transcript on the turn page (`--output-format stream-json` in place of `json`, which writes only the final result) | When Claude Code runs live turns again; five of 2,663 live turns used it at board part 4 |
 | AG-UI as a second stream beside the board's change stream; the turn page reads a finished or open turn's transcript since board part 4 | When a live turn transcript is streamed to the board (the stage-5 campaign feed), or when a researcher needs to read a harness turn rather than its record entries |
@@ -275,7 +287,7 @@ Ideas that have arrived before their stage. Adding a line here is how an impulse
 | Replication policy | Done at stage 4a: a campaign's `replication` is the seeds a finding needs at one commit, enforced at `post_finding`; the job script exports `FLYLOFT_SEED` |
 | Replication beyond a seed count (a second dataset, a held-out split), and the coordinator ordering it | When a project's evaluation policy asks for more than seeds |
 | Replicating integration runs | With [design/replication.md](design/replication.md): a merged tree is measured at `replication` seeds |
-| A tool-builder role | With the toolshed (the vision's revision of 2026-10-13), where a tool-builder adds tools for every project |
+| A tool-builder role | Done: the critic-judged implementer builds tools for the shed (see [design/toolshed.md](design/toolshed.md)) |
 | The swarm map's island row scrolling horizontally, its rule and stubs with it | When a campaign opens more islands than fit across the map (four at the board's width) |
 | A run slot reserved for consolidation (integration and root-island runs), so they never wait for a running test to end | When consolidation is seen waiting a whole run's length for a slot on a project whose runs take hours |
 | Backpressure on exploration: no new admissions while a campaign's queue of waiting runs is deep | When queued test runs are seen going stale (their island has moved on) before a slot reaches them |
@@ -284,10 +296,8 @@ Ideas that have arrived before their stage. Adding a line here is how an impulse
 | Template changes reaching projects created from it, by merge or by a diff against the recorded template commit | When a template is changed that its projects need |
 | A list of the user's GitHub organizations for a new repository's owner (needs the `read:org` scope) | When a mistyped owner is seen |
 | A setup agent on the host that prepares a project's repository and brief from a researcher's description | When researchers' own agents, following the lab's guidance, prove too slow or too uneven; the vision leaves the brief to the researcher |
-| Different harnesses for different roles in a campaign launched from the board | When a campaign needs one; a campaign file already allows it |
 | Fixed island charters and raw role tables on the board's launch page | When a researcher needs them; a campaign file covers both |
 | The board laid out for phones: the sidebar and the campaign page's side column at a narrow width | When a researcher needs to read or steer a campaign from a phone; board part 5's tier three found it works on desktop and not on mobile |
-| Each harness's models listed by asking the harness or its provider, in place of the `models` list in its configuration file | When updating a harness's `models` list for a new model becomes a chore; not every harness can list its models |
 | A Compute page on the board: each cluster asked what it has, per GPU type its file lists, with flyloft's jobs on each, and free counts beside the launch page's GPU types | Done: see [design/compute.md](design/compute.md) |
 | Cluster health and usage by cluster user on the admin page (nodes down or drained, unreachable clusters, who holds which GPUs), toward user quotas | Next after the Compute page |
 | GPU types discovered from `sinfo` in place of the list in each cluster's file | When keeping the lists becomes a chore |
@@ -305,6 +315,7 @@ Ideas that have arrived before their stage. Adding a line here is how an impulse
 | A per-project smoke time limit (a validation's is 30 minutes) | When a project's smoke run needs longer |
 | Cancelling a validation | When one is seen holding a GPU it should not |
 | A launch refused without a passed validation (the verdict is shown: see [design/projects.md](design/projects.md)) | When launches on unvalidated projects are seen failing |
+| A run at a higher tier than the lab's lowest, for work that cannot be split under the preemption cap | When a campaign hits the cap on work that cannot be shortened or made to resume |
 | A run an outage kills mid-run (Slurm's NODE_FAIL) is a failed test run: it is charged, and its implementer may read a lost node as a refuted change; Slurm's `--requeue`, or flyloft resubmitting a NODE_FAIL run uncharged, are the likely fixes. The power outage under ESM-2 8427bd25 killed none: its jobs had finished, and the job script's `finished` marker recovered them | When an outage is seen killing runs |
 | An implementer whose request ran nothing because another line was measuring its tree is not woken if those runs fail: its hypothesis stays testing, unmeasured, with nothing in flight. The integrator in the same place re-requests the missing seeds at its verdict turn | When it is seen |
 | Two requests for one tree that arrive together both run: measure-once checks for a run in flight outside any lock, so concurrent requests each see none (budget billing's tier two: three seats requested one tree within 2 ms and all three ran, at three times the cost) | When the duplicate runs are seen costing a real campaign's budget |
@@ -337,7 +348,7 @@ Ideas that have arrived before their stage. Adding a line here is how an impulse
 | Artifact retention and garbage collection; W&B synchronization | When storage fills or a project asks |
 | Cost estimate on proposals | Done at stage 4a: the proposal's `cost` line, read by the coordinator |
 | Harness environment scrubbed of git and cluster credentials | Stage 3a, by allowlist |
-| Observation of pull request state, including merged or squash-merged promotion pull requests (stage 6b) | When something reads it |
+| Observation of pull request state, including merged or squash-merged promotion pull requests (stage 6b) | Done for tool builds: the checks on a build's pushed and merge commits (see [design/toolshed.md](design/toolshed.md)); a campaign's own pull requests when something reads them |
 | A chart of cost and the metric over time on the board | When stage 6b's cost-per-promotion table stops being enough to read a long campaign |
 | An `.flyloft/` export at each promotion, not only at the stop | When a researcher needs turn transcripts before an indefinite campaign stops |
 | Timeout for runs and validations in unknown | When one is encountered |
@@ -377,10 +388,29 @@ Ideas that have arrived before their stage. Adding a line here is how an impulse
 | Searching or filtering the template list in New project | When a lab has more templates than fit on a screen |
 | Memory reading investigations: an earlier investigation's account and findings in a later campaign's assignment (today memory skips investigations both ways) | When an optimize campaign follows an investigation on the same project |
 | A size cap on an investigation run's collected `out/` | When a run is seen copying something large back to the host |
+| Raising a running campaign's GPU-hour ceiling (the client, the host CLI, or the board; today it is set once at launch) | Done once by hand on the live database, 2026-10-23, for a task whose work outgrew its first estimate |
 | Computed completion for tasks: a checklist the ask is parsed into | When critics are seen accepting incomplete outputs |
 | Two campaigns writing a project's work directory at once | When two are seen colliding there |
 | An "Empty project" choice on New project that writes the brief on the board and creates the repository | Superseded by `flyloft submit`: see [design/agent-interface.md](design/agent-interface.md) |
-| The toolshed (part 3 of investigate) and a data equivalent: where the lab's datasets live, how they are versioned, what has been fetched and prepared | Near-term, after the agent interface; each its own design |
+| The toolshed (part 3 of investigate) and a data equivalent: where the lab's datasets live, how they are versioned, what has been fetched and prepared | The toolshed done (see [design/toolshed.md](design/toolshed.md)); the data equivalent its own design |
+| Two campaigns building the same tool at once | When a second campaign is seen submitting a name another's build holds |
+| Abandoning a failed or blocked tool build to start another in the same campaign | When an implementer is seen stuck on a tool it should give up on |
+| A tool whose test needs more than one GPU or 30 minutes | When one is built |
+| A private tool (a license that forbids redistribution): a squashfs on the cluster's shared storage | When one arrives |
+| A `toolshed` command for laptops that picks podman or docker and mounts the working directory | When the skill's `podman run` line proves insufficient |
+| A tool build whose branch falls behind the shed's `main` under its strict protection: the merge is refused and retried each tick with a log line | When seen: update the branch through GitHub's API, then the checks again |
+| User-specific credentials beyond the GitHub sign-in. The lab has no shared Claude or Codex account, only individual ones with their own budgets; runs should log to their owner's wandb; the local endpoints issue per-user tokens for usage statistics; and today `harnesses/claude.toml` names no `api_key_env`, so Claude Code finds the operator's login through `HOME` and every member's campaign spends the operator's subscription. An admin-owned catalogue in the configuration directory, `credentials/<NAME>.toml`, names each credential the lab uses: a label, how to get it, its kind (`token`, `login`, or `ssh_key`; the board asks for and accepts only that kind), and its scope, `host` (the default) or `runs`. Each user enters theirs on a Credentials page of the board, never through an agent, theirs or flyloft's: set, when, Replace, Remove, a value never shown again. Stored Fernet-encrypted like the GitHub token. A campaign uses its owner's credentials, the host's `secrets.env` filling a name the owner has not set: `host` ones reach turns' harness environment and tool builds, `runs` ones also reach runs on stdin at submission, as the archive key does; harness keys stay `host`. A harness's `api_key_env` names its key (`claude.toml` gets `CLAUDE_CODE_OAUTH_TOKEN`); launch is refused without it, and a turn never falls back to the operator's login. Only `token` is built first. Open: a CLI path, expiry warnings, how a `login` reaches a process | Designed: see [design/user-credentials.md](design/user-credentials.md) |
+| Reserved catalogue names: a name matching a secret the host holds (`GITHUB_CLIENT_SECRET`, `COREWEAVE_S3_*`, a cluster's `password_env`) is filled from the host's environment for every owner, exporting that secret to turns (and to runs when its scope is `runs`); the catalogue check would refuse them | When an admin is seen to do it |
+| Tool builds receiving the owner's credentials, such as a gated Hugging Face model | When the first build needs one |
+| A CLI setter for credentials, with a hidden prompt | When someone asks for it, perhaps as part of an onboarding flow |
+| Credential expiry: a lifetime in the catalogue, a warning on the Credentials page, and a credential marked refused when its service refuses it | When a credential expires on someone mid-campaign |
+| Per-user cluster identity: every cluster operation of a campaign (staging, sbatch, observation, scancel, archive jobs) runs as its owner, with the owner's own cluster login (`ssh_key` or `login` from the credentials catalogue). Required on CoreWeave SUNK, which allows no account not tied to a person; on slinky it puts campaigns under Slurm's existing per-user quotas and accounting. Each campaign already has its own directory under its owner; per-user logins were discussed for cluster storage and found unneeded for now. Open: whose identity observes and archives | After user-specific credentials, whose catalogue it uses; needs its own design |
+| Long-running services a campaign can call (a ColabFold MSA server with its terabyte of databases on shared storage, used by Boltz, Chai, and Protenix): first as lab infrastructure named in the cluster's config and exported to runs and assignments as a URL, the server itself a shed tool kept running; flyloft managing its lifecycle (start on demand, a lease, restart, stop when idle) only if keeping it up proves to be the pain | Brainstormed 2026-10-27; when the first campaign needs an MSA server |
+| Declared parameters per tool command | When agents are seen misusing commands from prose |
+| A tool's image per GPU architecture (Arm) | When an Arm partition is wanted |
+| `flyloft tools` and the catalogue in the researcher's skill | When a researcher's agent needs the shed's contents while writing a brief |
+| A tool run on a cluster without pyxis | When a cluster without it is configured |
+| A bar fixed at launch (what is measured, on what data, what counts as support) as a field of an investigation, and findings that answer it marked confirmed in place of exploratory; today the bar goes into the brief and the critic judges claims against it, without the label | When a researcher comes to a question knowing what settles it and wants the label |
 | A Claude Code plugin and marketplace for the flyloft skill (the skill's directory plus a manifest) | When a lab member wants it from a marketplace, or a hook or second component is needed |
 | The flyloft skill for Codex and OpenCode | Done 2026-10-22: `flyloft install` serves every harness found |
 | `flyloft logout`, several hosts per laptop, refreshing a session before it expires | When one is missed |
@@ -392,6 +422,22 @@ Ideas that have arrived before their stage. Adding a line here is how an impulse
 | A CPU budget ([design/cpu-partition.md](design/cpu-partition.md) §6) | When CPU work on the shared node needs a bound beyond run slots and the CPU-run limit |
 | Choosing a GPU type per run within a campaign; budgeting must then weigh the types ([design/cpu-partition.md](design/cpu-partition.md) §6) | When a campaign needs two GPU types |
 | The request and the render of a CPU run disagreeing when `cpu_partition` changes while a run is preparing; the fix is to key `_is_cpu_run` on `run.cpus is not None` | When it is observed |
+| Watching archive jobs: a failed one leaves its directory and log on the cluster and tells no one ([design/run-storage.md](design/run-storage.md) §6) | When a failed archive goes unnoticed |
+| An object storage key scoped to `flyloft/`, under a CoreWeave principal of flyloft's own, in place of Sarah's key ([design/run-storage.md](design/run-storage.md) §6) | When the lab wants the exposure closed |
+| A cap on the disk that live runs and campaigns hold on an archiving cluster ([design/run-storage.md](design/run-storage.md) §6) | When a campaign fills `/mnt/data` |
+| Archiving validations, whose directories stay on the cluster; object storage on-prem ([design/run-storage.md](design/run-storage.md) §6) | When either fills its volume |
+| A lab's own job-script settings: first extra `#SBATCH` directives per cluster and GPU type (`--qos`, `--constraint`, `--reservation`), then a host-side prologue before the srun step (module loads), then a container runtime other than pyxis; a full template override only if those fall short, checked by doctor against what flyloft relies on (the run directory's output with append, the single srun step that ignores TERM, the `finished` marker, the `FLYLOFT_*` variables) | When a lab or a cluster needs a directive or runtime flyloft does not write |
+| The archive's transfer per cluster (endpoint, tool, key names) in place of CoreWeave's s5cmd fork, `http://cwlota.com` and `COREWEAVE_S3_*` ([design/run-storage.md](design/run-storage.md) §2) | When a cluster outside CoreWeave needs a `work_dir_archive` |
+| Archiving a run interrupted at the preemption cap only once squeue no longer lists its job: today it is archived in the tick that cancels it, so a file written during the kill grace can fail the check (the directory then stays, marked archived) ([design/run-storage.md](design/run-storage.md)) | When a cap-interrupted run's archive is seen to fail |
+| GPT models through Codex on each user's own ChatGPT subscription ([design/harness-defaults.md](design/harness-defaults.md) §6), benched 2026-10-28: a contained Codex turn would need the agent image, the bridge, and the owner's Codex home mounted; the built-but-unmerged substrate is on branch `harness-defaults` (PR #82) | Revisit through OpenCode first: OpenAI models authenticated there may prove simpler |
+| TypeScript 7 for the board: `npm install -D typescript@7` and drop `baseUrl` from `web/tsconfig.json` (TS 7 removed it; `paths` is already relative); the board then typechecks clean | When openapi-typescript (`npm run types`) works with it: it builds `types.ts` through TypeScript's JavaScript compiler API, which TS 7 does not ship |
+| A wall-clock cap on OpenCode turns (`max_turns` caps only Claude Code); a GLM implementer kept a task turn open for hours with `sleep` polls after `pass_turn` (#91) | When a model keeps a turn open despite #91's wording and `pass_turn` reply |
+| `sleep` in the OpenCode bash deny list (`python -c` gets around it) | Only if a turn cap is not enough |
+| A per-user cap on direct cluster jobs (`flyloft job`, [design/direct-jobs.md](design/direct-jobs.md)): concurrent jobs or GPUs, refused at submit; at launch only a 24-hour time limit per job (#133) | When one user's direct jobs fill a queue that campaigns or other people are waiting on |
+| Direct jobs on the board: a researcher's jobs, their state, GPUs, and log tail, likely on the Compute page (#134) | When someone wants to see direct jobs outside their agent session |
+| Archiving ended direct-job directories to object storage, as runs are | When job directories are seen piling up on a cluster |
+| A direct job in a toolshed tool's image (`flyloft job submit --tool`), with the shed's tools listed in `flyloft options` (#135) | When a researcher's agent wants a direct job inside a tool |
+| A cancel that lands while the tick is staging the same direct job is overwritten to queued, and the job runs | When a canceled direct job is seen running |
 
 ## References
 

{flyloft-0.2.2 → flyloft-0.4.0}/docs/NEW_PROJECT.md

@@ -20,25 +20,32 @@ campaign's metric. A project is one GitHub repository plus one registration on t
 | `brief_path` | The brief, `BRIEF.md` by convention |
 | `run_command` | The command one run executes, from the repository root |
 | `results_path` | The JSON file that command writes, `results.json` by convention |
-| `environment_setup` | Shell lines run before the job enters the repository |
+| `environment_setup` | Shell lines run in the repository before the run command |
 
 Every run (a campaign's baseline, each test, a validation) is one Slurm job. Its script, as flyloft writes it (abridged:
-`--partition`, `--account`, `--cpus-per-task`, `--mem`, and `--container-mounts` appear when set):
+`--partition`, `--account`, `--cpus-per-task`, `--mem`, and `--container-mounts` appear when set, and the lines that
+pass a preemption's SIGTERM to the run command are left out):
 
 ```bash
 #!/bin/bash
 #SBATCH --job-name=flyloft
 #SBATCH --output=<run dir>/slurm-%j.out
+#SBATCH --open-mode=append              # a restarted run adds to the log
 #SBATCH --time=<the campaign's time limit; 00:30:00 for a validation>
 #SBATCH --gres=gpu:<count>              # with the GPU type's gres name, as the cluster's file says
-#SBATCH --container-image=<image>       # when the cluster runs jobs in a container
+srun --ntasks=1 --container-image=<image> bash -c '   # one step, in the cluster's container
 set -euo pipefail
+export FLYLOFT_CAMPAIGN="<the campaign's directory on the cluster>"
+export FLYLOFT_DATA="<the cluster's shared data directory>"      # only when the cluster sets one
+export FLYLOFT_SHARED="<the cluster's shared drive>"             # only when the cluster sets one
+cd "<run dir>/code"
 <environment_setup>
 export FLYLOFT_SEED=<seed>              # each replicate's seed; 0 for a validation
 export FLYLOFT_SMOKE=1                  # a validation only
-cd "<run dir>/code"
+export FLYLOFT_OUT="<run dir>/out"      # an investigation's or a task's own runs only
 <run_command>
 touch "<run dir>/finished"
+'
 ```
 
 What follows from it:
@@ -50,9 +57,13 @@ What follows from it:
   the packages the project uses in flyloft's `docs/environments/`, or ask the researcher; write against those, and list
   them in the README. A package the image lacks is vendored into the repository or asked of the researcher, never
   installed by the job.
-- **`environment_setup` runs before the `cd`.** Its paths are absolute, or values the command resolves after the
-  `cd`, such as `export DATA_DIR=data`.
+- **`environment_setup` runs in `<run dir>/code`.** It can run the repository's committed scripts, such as
+  `bash setup_env.sh "$FLYLOFT_CAMPAIGN/envs/main"`.
 - **One job is the whole run.** Training, evaluation, and writing results all happen inside the time limit.
+- **A run may restart.** Flyloft runs at the cluster's lowest tier, where a job running longer than 30 minutes can
+  be preempted and restarted from the top. The run command resumes from its own checkpoints, saved more often than
+  every 30 minutes, or starts over cleanly, writing outputs to a scratch path and moving them into place only when
+  complete. A preempted run gets SIGTERM five minutes before it is stopped, time enough to save a checkpoint.
 
 ## 2. The contract
 
@@ -89,10 +100,13 @@ creates the repository under the lab's organization, registers the project, and
 To register a repository by hand instead, use **My own repository** on **New project**, or `flyloft register <url>
 --name <name>`, leaving the run command and results path blank; there is nothing to validate. Launch it with
 **Investigate a question** or **Do a task**. Every job a critic-judged campaign runs has
-`$FLYLOFT_PROJECT_WORK`, the project's directory on the cluster, where environments, weights, and data stay for later
-campaigns, and `$FLYLOFT_OUT`, whose contents come back to the board. When the account recommends an optimization, add
-a run command that meets section 2, validate it, and launch **Optimize a metric** on the same project: what the
-investigation built is still in `$FLYLOFT_PROJECT_WORK`.
+`$FLYLOFT_CAMPAIGN`, the campaign's own directory on the cluster, where it builds environments, data, and the weights
+of models it trains; `$FLYLOFT_DATA` and `$FLYLOFT_SHARED`, when the cluster sets them, read and never written; and
+`$FLYLOFT_OUT`, whose contents come back to the board. A campaign's files are written only in its own directory; an
+earlier campaign's are read, or copied in first. When the account recommends an optimization, add a run command that
+meets section 2, validate it, and launch **Optimize a metric** on the same project. Its `environment_setup` builds
+the environment in `$FLYLOFT_CAMPAIGN/envs/` if it is missing, under `flock "$FLYLOFT_CAMPAIGN/envs/.lock"`, and
+activates it; the setup script is committed.
 
 The rest of this guide applies to projects with a run command.
 
@@ -186,6 +200,7 @@ Reading a validation's report:
 | passed | The job finished and wrote a flat object of numbers, which the report lists | The project runs: launch |
 | failed | The job exited with an error, ran out of time, or the cluster refused it; the report shows the log's last lines | A file nobody committed, a dependency the environment lacks, a wrong path, a crash in the evaluation |
 | incomplete | The job finished, but `results_path` is missing or is not a flat object of numbers | Results written somewhere else, a nested value, a metric written as a string |
+| interrupted | The cluster preempted the job and never restarted it; this says nothing about the project | Validate again |
 
 A failed or incomplete validation means fix the repository, push, and validate again; the report is written to be
 pasted back to you. A passed validation shows that the code runs at all, not that a campaign will succeed. A smoke
@@ -219,13 +234,13 @@ time = "01:00:00"             # HH:MM:SS, Slurm's limit for one run; a run is ch
                               # allow for replicate seeds sharing a node: they run in parallel
 
 [roles.implementer]
-harness = "claude"            # a file name under harnesses/, without .toml
+harness = "opencode"          # a file name under harnesses/, without .toml
 
 [roles.critic]
-harness = "claude"
+harness = "opencode"
 
 [roles.integrator]
-harness = "claude"
+harness = "opencode"
 ```
 
 A cluster's GPU types are the ones its file in the configuration directory lists. The operator writes them, each with