@baochunli/flakes 0.0.5 → 0.0.6

package/dist/node_modules/@flakes/console/.output/server/_ssr/{documentation-C91gfyy0.mjs → documentation-BnxmM-Yo.mjs}

@@ -1,11 +1,11 @@
-//#region node_modules/.nitro/vite/services/ssr/assets/documentation-C91gfyy0.js
+//#region node_modules/.nitro/vite/services/ssr/assets/documentation-BnxmM-Yo.js
 var cli_default = "---\ntitle: Installing and Authorizing the CLI\ndescription: Installing and authorizing the Flakes CLI.\n---\n\nYou may start by signing up for a new account and signing in to the [Flakes console](https://flakes.dev/console). Once you are signed in, the console is where you review runs, watch task activity, inspect workpads and artifacts, respond to permission requests, and send live input.\n\nTo install the Flakes CLI, run:\n\n```sh\nnpm install -g @baochunli/flakes\n```\n\nOr if you use `bun`:\n\n```sh\nbun install -g @baochunli/flakes\n```\n\nThen authorize the CLI using your Flakes account:\n\n```sh\nflakes auth login\n```\n\nThe command starts a device authorization flow. Approve the request in the browser while signed in to the console. After approval, the CLI stores your Flakes credential locally for future use.\n\nCheck the stored CLI credential:\n\n```sh\nflakes auth status\n```\n\nRun, task, artifact, and host setup commands use that stored CLI credential\nautomatically. You should not need to handle a raw hosted API credential during\nnormal first-run setup.\n\n## Next: Create A Project\n\nProjects are first-class work namespaces. Every new run belongs to exactly one\nactive Project, and host workspace placement is configured against that Project\nas an explicit product field.\n\nCreate a Project before creating runs:\n\n```sh\nflakes projects create --key alpha --name \"Alpha\"\n```\n\nCreate runs with an explicit Project:\n\n```sh\nflakes runs create --project alpha --key release-notes --name \"Draft release notes\"\n```\n\nIf you need to connect user-supplied host capacity for that Project, continue to\n[Connecting Your Hosts](/docs/connect-a-host). Run the host once so it advertises pool keys, then bind the\nProject with `flakes projects bind-host alpha --host <host-id> --pool <pool-key>`.\n";
 var concepts_default = "---\ntitle: Concepts\ndescription: Core vocabulary for Projects, runs, hosts, pools, sandboxes, and task outputs.\n---\n\nThis page defines the terms used across the hosted-console documentation. It is\nfor product users, host operators, and workflow authors, not a protocol or\nstorage reference.\n\nFor parent-task authoring, see [Harnesses](/docs/harnesses).\n\n## Terms\n\n### Project\n\nA **Project** is a first-class, owner-scoped work namespace. Every new run is\ncreated inside one active Project. A Project also names the host-local workspace\ndirectory used for execution when the Project is bound to a host.\n\nProject keys are stable, path-safe names such as `alpha` or `release-notes`.\nWhen a host project root is `/srv/flakes/projects`, Project `alpha` maps to the\nhost path `/srv/flakes/projects/alpha` after the binding is configured and the\nhost validates it.\n\n### Run\n\nA **run** is the durable container for related work inside a Project. A run\nholds the tasks you save, the tasks admitted for execution, and the history\nneeded to inspect what happened later. Close a run when no more top-level tasks\nshould be added.\n\n### Task\n\nA **task** is one unit of work inside a run. It has instructions, target\nexecution requirements, optional inputs and outputs, and a final result.\nTasks can be created directly by a user or integrator, or spawned by a running\nparent task.\n\n### Group\n\nA **group** is a durable phase owned by a running parent task. The parent opens\nthe group, spawns fresh child tasks into it, closes the child set, and waits\nfor the group to settle. Harnesses use groups for phases such as draft, review,\nrevise, and promote.\n\n### Assignment\n\nAn **assignment** is Flakes saying that one sandbox currently owns one task.\nWhen a task reports activity, output, or a final result, Flakes checks that the\nreport comes from the current assignment. That keeps stale retries or late\nupdates from replacing newer task state.\n\n### Host\n\nA **host** is the runner identity and lifecycle for a Linux or Mac machine that\nruns the Flakes host agent. The host connects user-supplied capacity to Flakes\nand keeps credentials, paths, mounts, and tool details on that machine.\n\nHost = runner identity/lifecycle. Pool = capacity/resource/adapter constraints. Project = work namespace and workspace root mapping.\n\n### Pool\n\nA **pool** is a host-local capacity definition. Pools describe which adapter can\nrun, how much concurrency is available, which capabilities are advertised, and\nwhich local MatchLock image, executable paths, mounts, environment, and resource\nbounds the host uses. Pools do not select the Project directory. Project\nplacement is managed by setting a host project root and binding Projects to\nallowed pools.\n\n### Sandbox\n\nA **sandbox** is the execution environment where assigned tasks run. It may be a\nVM, container, local environment, or another isolated runtime started from host\ncapacity. The sandbox is what Flakes schedules for task execution.\n\n### Thread\n\nA **thread** is one active task execution inside a sandbox. It includes the\ntask's running agent process, task-local files, session record, messages, and\nresult handling for the current assignment.\n\n### Workpad\n\nA **workpad** is the durable Markdown note attached to a task. Humans and\nagents use it for plans, progress, decisions, and handoffs. It is saved with\nversion checks so a stale update does not overwrite newer edits.\n\n### Transcript\n\nA **transcript** is the saved agent session record for a task. Use it when you\nneed to inspect what the agent saw, said, and did during execution. A transcript\nis evidence, not the task result by itself.\n\n### Artifact\n\nAn **artifact** is an optional managed file or blob that a task consumes or\nproduces. Use artifacts for concrete deliverables such as reports, logs,\ndatasets, images, or archives. A task can still be useful without declaring an\nartifact when the result is captured by status, workpad, activity, or a\nworkspace handle.\n\n### Workspace Handle\n\nA **workspace handle** is an immutable, git-backed reference to bounded paths in\na run workspace. Harnesses use workspace handles to pass repo-shaped state to\nchildren and to receive bounded candidate changes back from them. The handle is\na reference to committed state, not a shared mutable directory.\n\n## Project, Host, Pool, Sandbox, And Task Thread\n\nThese terms often appear together, but they are different layers.\n\n| Question | Project | Host | Pool | Sandbox | Task thread |\n| --- | --- | --- | --- | --- | --- |\n| What is it? | The work namespace for runs and workspace placement. | The runner identity and lifecycle for a machine. | Capacity and adapter constraints on a host. | The environment that can run assigned tasks. | One active task execution inside that environment. |\n| What owns it? | The account owns Projects. | The host owns its credential and lifecycle. | The host owns local capacity config. | Flakes schedules sandboxes from host capacity. | The task thread is the running attempt for one assignment. |\n| Who cares most? | Users and workflow authors. | Host operators. | Host operators and workflow authors. | Host operators and workflow authors. | Workflow authors and users inspecting task detail. |\n| What is visible in the product? | Project list, runs, and host placement. | Host status and advertised capacity. | Adapter, capabilities, concurrency, and binding availability. | Task placement and runtime capability. | Task activity, workpad changes, transcripts, artifacts, and results. |\n| What should not be mixed up? | A Project is not a run tag or metadata blob. | A host is not the task itself. | A pool is not a Project directory. | A sandbox is not a whole run. | A thread is not durable workflow state by itself. |\n\nThe practical rule: create Projects for work namespaces, connect and operate\nhosts, bind Projects to compatible pools, let Flakes schedule sandboxes, and\ninspect task threads when you need to understand a specific running or completed\ntask.\n";
 var connect_a_host_default = "---\ntitle: Connecting Your Hosts\ndescription: Connecting your own hosts to Flakes, configuring pools, and binding Projects.\n---\n\nConnect a host when you want Flakes to run Project work on compute you provide.\nThe setup path starts from a hosted account, creates a host directly from the\nauthenticated CLI, writes credentials locally on the host, configures Project\nplacement, and then keeps a host agent connected to `https://flakes.dev`.\n\n## Prerequisites\n\nYou can connect a physical Linux or Mac machine that can start and run MatchLock sandboxes.\n\nYou need:\n\n- MatchLock available on the host machine.\n- A Project created with `flakes projects create`.\n- A host-local project root directory, such as `/srv/flakes/projects`, with one\n  child directory for each Project key you plan to run.\n\nHost setup is a CLI/direct user auth flow. Do not route raw host credentials\nthrough the browser console, and do not assume the web console can display host\nsecrets. The setup route returns the raw host credential exactly once to the\nCLI so the host can persist it locally.\n\n## Project Placement Model\n\nHost = runner identity/lifecycle. Pool = capacity/resource/adapter constraints. Project = work namespace and workspace root mapping.\n\nHost TOML declares identity, credentials, state, and pools. Pools describe only\nthe local capacity the host can advertise: adapter, resource limits,\ncapabilities, MatchLock image, executable paths, mounts, and environment. The\nProject root is set through the API, CLI, or console. A Project is then bound\nto one or more host pools, and the host validates the derived local path\n`<project-root>/<project-key>` before Flakes schedules work there.\n\n## 1. Authorize The CLI\n\nAuthorize the CLI on the host machine against the hosted API:\n\n```sh\nflakes auth login\nflakes auth status\n```\n\n`flakes host setup` uses this stored CLI credential. If no valid credential is\navailable, setup can start the same device authorization flow before creating\nthe host.\n\n## 2. Create The Host\n\nRun setup on the host machine:\n\n```sh\nflakes host setup --config <host.toml>\n```\n\nSetup calls the direct host setup API using CLI user auth. The server creates\nthe host and its first host-scoped credential in one transaction, then returns\nthe raw credential exactly once so the CLI can write it to a protected local\ncredential file. Command output and browser console responses should expose\ncredential summaries, not the secret value.\n\nBy default, setup writes under the user's Flakes config directory. Passing\n`--config`, `--credential-file`, and `--state-dir` lets you choose explicit host\npaths.\n\n## 3. Add Pools To The Host Config\n\n`flakes host setup` writes the host identity and credential reference first. Add\none or more `[[pools]]` entries before starting the host agent:\n\n```toml\ncontrolPlaneUrl = \"https://flakes.dev\"\nhostId = \"host_...\"\ncredentialFile = \"/home/flakes/.config/flakes/host.credential\"\nstateDir = \"/home/flakes/.config/flakes/state\"\n\n[[pools]]\npoolKey = \"local-pi\"\nmatchlockImage = \"registry.example.com/flakes/pi:latest\"\nadapter = \"pi\"\nmaxInstances = 2\nmaxConcurrency = 1\nadvertisedCapabilities = [\"pi\"]\n\n[pools.executablePaths]\nmatchlock = \"/usr/local/bin/matchlock\"\n\n[pools.resourceBounds]\ncpus = 4\nmemoryMb = 8192\n```\n\nPool config is host-local. The host uses values such as `matchlockImage`,\n`credentialFile`, `stateDir`, executable paths, mounts, and environment values\nlocally. When the host connects, Flakes receives a sanitized pool advertisement:\npool key, provider, adapter, capacity limits, advertised capabilities, and safe\nresource bounds.\n\nDo not add `workspace` under `[[pools]]`. Project directories are configured\nafter setup with `flakes host project-root set`, then Projects are bound to pool\nkeys after the host has advertised those pools.\n\n## 4. Set The Project Root\n\nCreate the host-local directories that should back each Project key. For a\nProject named `alpha` and a root of `/srv/flakes/projects`, the host validates\n`/srv/flakes/projects/alpha`.\n\nStore the root on the hosted control plane:\n\n```sh\nflakes host project-root set --config <host.toml> --path /srv/flakes/projects\n```\n\n## 5. Run The Host And Discover Pools\n\nStart the host process:\n\n```sh\nflakes host run --config <host.toml>\n```\n\nKeep this process running on the host. It connects to the hosted control plane,\nadvertises sanitized pool capacity, validates active Project bindings, claims\nmatching launch work, starts MatchLock only after the control plane accepts the\nclaim, and reports lifecycle results back to Flakes.\n\nThe host status moves through `created`, `offline`, `online`, and `disabled`.\nPools become schedulable only after the running host connects and Flakes\nacknowledges the pool snapshot.\n\nIn another terminal, confirm the remote host and pool snapshot:\n\n```sh\nflakes host status --config <host.toml> --json\n```\n\nThe command checks that the credential file is private, the host config is\nvalid, and the configured pools can be advertised. When the CLI has a valid\nstored user credential, it also reads remote host, pool, and credential\nsummaries for the same account. `flakes host status` does not report Project\nbinding availability.\n\n## 6. Bind The Project To Discovered Pools\n\nAfter the target pool key is visible in host status or the console host page,\nbind the Project to one or more pools from this host:\n\n```sh\nflakes projects bind-host alpha --host <host-id> --pool local-pi\n```\n\nYou can get the host ID from `flakes host setup` output, `flakes host status`,\nor the console host detail page. The binding controls which pools can launch\nwork for that Project; it does not edit the host TOML file. If you bind before\nthe host has advertised pools, the control plane rejects the request with\n`unknown_host_pool_keys`.\n\nA Project becomes schedulable on that host only after its binding validates\nsuccessfully for at least one allowed pool. Inspect binding availability in the\nconsole host placement panel or with\n`GET /v1/hosts/:hostId/project-bindings`.\n\n## Credential Handling\n\nHost credentials are separate from user CLI credentials:\n\n- `flakes auth login` stores a user CLI\n  credential for the hosted API.\n- `flakes host setup` uses that user credential to create a host and first\n  host-scoped credential, then writes the raw host credential only to the local\n  credential file.\n- `flakes host run` reads the host credential file and uses the host-scoped\n  credential to connect as that host.\n- `flakes host rotate --config <host.toml>` rotates the host-scoped credential\n  through direct CLI user auth, writes the new raw host credential only to the\n  credential file, and requires restarting `flakes host run` before claiming new\n  launch work.\n\nThe web console in the browser is for operating and observing Flakes. It should\nnot expose raw host credential setup or rotation flows.\n";
 var harnesses_default = "---\ntitle: Harnesses\ndescription: Author durable parent tasks that spawn, wait for, and resume child work.\n---\n\nA harness is a TypeScript task that coordinates other tasks. Use one when a\nworkflow needs durable fan-out, review/revise loops, staged workspace handoffs,\nor a parent task that can pause while children run and later resume from saved\nstate.\n\nFor vocabulary used here, see [Concepts](/docs/concepts).\n\n## When To Use A Harness\n\nUse the Harness SDK when the parent task needs to make decisions while work is\nrunning:\n\n- split a larger job into child tasks and collect their declared outputs;\n- run phases such as draft, review, revise, and promote;\n- wait for a group of children without keeping a local process alive;\n- pass repo-shaped state through workspace handles;\n- rebuild its next step after a yielded wait, retry, or sandbox change.\n\nDo not use a harness for a single prompt, a static dependency graph, or a job\nthat only needs ordinary task creation from the console or CLI. In those cases,\nsave normal tasks and dependencies as described in [Running Workflows](/docs/run-work).\n\n## Where Harness Code Runs\n\nHarness code runs only when a task using the `harness` adapter is assigned to a\nsandbox. It does not run in the console, the CLI, the host process, or as a\nprivileged control-plane script.\n\nThe product path is:\n\n1. You write and check a harness module.\n2. You submit it as an ordinary task with `--adapter harness`.\n3. Flakes schedules that task onto a sandbox that can run the harness adapter.\n4. The harness opens groups, spawns children, waits, resumes, and returns a\n   normal task result.\n\nThe main package name a harness author needs is `@flakes/harness-sdk`, used for\nthe `defineHarness(...)` import in the module source.\n\n## Start From A Template\n\nCreate a starter harness, then run the checker before submitting it:\n\n```bash\nflakes harness init --template paper --dir harnesses\nflakes harness check harnesses/paper-writer.ts\n```\n\nThe current CLI starter templates are:\n\n- `paper`\n- `review-revise`\n- `fanout-fanin`\n- `autowrite`\n- `autoresearch`\n\nThe SDK source also includes `fix-review-live.ts` for live implementer/reviewer\nloops. Use it only when the child adapter advertises live task round support.\n\nIf a template uses `ctx.pi(...)` without explicit child agent IDs, provide\nchecker defaults:\n\n```bash\ncat > harnesses/defaults.json <<'JSON'\n{ \"agents\": { \"pi\": \"agent_pi_writer\" } }\nJSON\n\nflakes harness check harnesses/paper-writer.ts \\\n  --defaults harnesses/defaults.json\n```\n\nSubmit a checked module as a normal task:\n\n```bash\nflakes tasks save \\\n  --run paper-run \\\n  --key paper-planner \\\n  --title \"Paper planner\" \\\n  --adapter harness \\\n  --harness-file harnesses/paper-writer.ts \\\n  --tool-grant flakes.tasks.spawn \\\n  --tool-grant flakes.groups.open \\\n  --tool-grant flakes.groups.close \\\n  --tool-grant flakes.groups.wait \\\n  --tool-grant flakes.workspace.commit \\\n  --tool-grant flakes.workspace.resolve \\\n  --tool-grant flakes.workspace.promote \\\n  --tool-grant flakes.childOutputs.read\n\nflakes tasks admit --run paper-run paper-planner\n```\n\n## Groups, Spawn, Wait, And Resume\n\nHarnesses build around durable groups. A group is one named phase owned by the\nrunning parent task. In code, `ctx.group(...)` opens the group, lets you call\n`group.spawn(...)` for children, closes the child set, and waits for the group\nto settle.\n\n```ts\nimport { defineHarness } from \"@flakes/harness-sdk\";\n\nexport default defineHarness(async (ctx) => {\n  const draft = await ctx.group(\n    \"draft-sections\",\n    { join: \"all_success\", maxChildren: 2 },\n    (group) => {\n      group.spawn(\n        \"intro\",\n        ctx.pi({\n          title: \"Draft introduction\",\n          prompt: \"Write the introduction and publish notes.\",\n          outputs: {\n            notes: ctx.output.json({ required: true }),\n          },\n        }),\n      );\n    },\n  );\n\n  ctx.requireGroupSuccess(draft);\n  const notes = await ctx.outputs.readJson(draft, \"intro\", \"notes\");\n  return ctx.succeeded({ data: { notes } });\n});\n```\n\nIf the group is not terminal yet, Flakes can yield the current assignment. The\nlogical parent task is scheduled again after the wait condition is satisfied.\nResume is reconstruction, not a live JavaScript continuation: use stable group\nkeys, child keys, output keys, workspace labels, and promotion labels, then\nrebuild decisions from durable group status, child outputs, workpad snapshots,\nand promotion records.\n\n## Workspace Handles\n\nWorkspace handles are immutable, git-backed references to bounded paths in a\nrun workspace. Use them for repo-shaped handoffs instead of copying directories\nor sharing a mutable worktree.\n\nThe normal pattern is:\n\n1. Commit bounded parent paths with `ctx.workspace.commit(...)`.\n2. Pass the returned handle to children in their `inputs`.\n3. Require children to publish bounded workspace outputs.\n4. Read a child candidate with `ctx.outputs.workspace(...)`.\n5. Review and promote selected paths with `ctx.workspace.promote(...)`.\n\n```ts\nconst base = await ctx.workspace.commit(\"paper-base\", {\n  paths: [\"paper\", \".harness/plan.json\"],\n  message: \"Base paper state\",\n});\n\nconst draft = await ctx.group(\"draft\", { join: \"all_success\" }, (group) => {\n  group.spawn(\n    \"intro\",\n    ctx.pi({\n      title: \"Draft intro\",\n      prompt: \"Edit work/paper/intro.md and publish a candidate.\",\n      inputs: { \"work/\": base },\n      outputs: {\n        candidate: ctx.output.workspace({\n          paths: [\"work/paper/intro.md\"],\n          required: true,\n        }),\n      },\n    }),\n  );\n});\n\nctx.requireGroupSuccess(draft);\nconst candidate = await ctx.outputs.workspace(draft, \"intro\", \"candidate\");\n\nawait ctx.workspace.promote(\"promote-intro\", {\n  base,\n  candidate,\n  paths: [\"paper/intro.md\"],\n  mode: \"replace_bounded_paths\",\n  conflictPolicy: \"fail\",\n});\n```\n\nSmall settings can go in child `input` or in bounded workspace files written by\nthe parent before commit. Use workspace handles for source trees, papers,\nexperiment folders, and other state where history and path boundaries matter.\n\n## Current MVP Boundaries\n\nThe current Harness SDK MVP supports direct child group orchestration, yielded\nwait/resume, declared terminal child outputs, child workpad snapshots, live\nround helpers for supported child adapters, and workspace handles.\n\nIt does not support broad child browsing, spawned child `inputArtifacts`,\nshared mutable worktrees, arbitrary npm dependencies, unbounded loops without a\nclear budget, or control-plane-side TypeScript execution.\n\nKeep harnesses deterministic. Group keys, child keys, output keys, workspace\nlabels, and promotion labels should come from stable workflow input, not random\nvalues or current time.\n";
 var docs_default = "---\ntitle: Overview\ndescription: What is Flakes?\n---\n\n[Flakes](https://flakes.dev) is a hosted harness runtime for distributed agent workflows. Workflows run within sandbox environments, and across hosts that are supplied by the user. The [console](https://flakes.dev/console) is the primary user interface for interacting with Flakes: use it to review runs, inspect task state, read transcripts and artifacts, respond to permission requests, and steer running tasks.\n\nFlakes keeps all the transcripts, inputs, outputs and artifacts _durable_ in its control plane console. and _observable_ using its console, while workflows run on hosts you provide. A user-supplied host advertises one or more _pools_, which represents the capabilities and resources, such as GPUs, that the host supports. Flakes then matches ready tasks to compatible capabilities, and the console is the place for the user to observe what happened even when machines, sandboxes, or task runners disconnect (and return later).\n\nStart with [Installing and Authorizing the CLI](/docs/cli). To bring your own hosts, continue to [Connecting Your Hosts](/docs/connect-a-host).\n";
 var observe_and_steer_default = "---\ntitle: Observing And Steering\ndescription: Inspecting workflow runs in the console, read task history, and send live input.\n---\n\nUse the console at `https://flakes.dev/console` to watch durable work, inspect\nwhat an agent did, and send live input while a task is running.\n\nThe important boundary: durable task state is the source of truth. Status,\ndependencies, workpads, activity, artifacts, and transcript pointers live in\nthe control plane. A transient agent process, sandbox assignment, or local\nsession can end and be replaced without erasing that durable task state.\n\n## Runs\n\nThe Runs page lists every run your account can read, newest first. Use the\nstate filters for all, running, succeeded, or failed runs. Each row shows the\nrun name, run id, current state, task progress, creation time, and last update.\nOpen a row to inspect the run.\n\nQueued work is visible here as a running run whose task progress has not moved\nto terminal states yet. If a run remains active longer than expected, open the\nrun and check whether tasks are waiting for capacity, waiting for dependencies,\nrunning on a sandbox, or blocked on input.\n\n## Run Detail\n\nRun detail starts with the run state, elapsed time, task terminal count, and a\ndownload action for the run history. The Overview tab has three views:\n\n- Map: shows the task graph and dependency shape.\n- Timeline: shows queue time and execution time for each task.\n- By Sandbox: groups tasks by the sandbox that ran or is running them.\n\nThe Tasks table is the operational list. It shows task number, task name,\nstatus, workpad version, sandbox, dependencies, accepted time, finished time,\nand a Task button that opens task detail.\n\nOther run tabs show declared artifacts, metrics, and active file reservations.\nDelete is available only after the run is terminal; it removes finished run\nhistory and is not a control for stopping active work.\n\n## Task Detail\n\nOpen a task from the run map, timeline, sandbox view, or Tasks table. Task\ndetail shows the task brief, acceptance criteria, adapter, live round state when\npresent, dependencies, sandbox, attempt, accepted time, heartbeat, and finished\ntime.\n\nThe Workpad panel is the durable task note. Use it for current plan, progress,\nfindings, and handoff notes. The console saves with a version check, so if\nsomeone else updated the workpad first, your edit is rejected instead of\nsilently overwriting newer text.\n\nThe Activity panel is the short timeline for product events. It can show\nworkpad edits, human input, live round events, `permission.requested`, and\n`permission.responded`. Activity is not a full transcript and does not replace\nthe workpad.\n\nThe Agent transcript panel shows the saved Pi session when the task uses the\nPi adapter. Use Parsed for a readable conversation and tool view. Use Raw when\nyou need the underlying session record. A transcript is evidence of what the\nagent did; it is not how Flakes decides whether the task succeeded.\n\n## Steer Running Work\n\nThe task transcript includes live input controls while the task is running:\n\n- Follow up: add information or answer a question from the agent.\n- Steer: nudge direction without replacing the task definition.\n\nThe console queues the message and sends it to the active running task. The\nmessage is accepted only while the task is running on a connected sandbox. If\nthe task has already finished, is waiting, or its sandbox is offline, the\ncomposer is disabled or the send fails and you can retry only after there is an\nactive running assignment again.\n\nLive input does not edit the saved task. It is an event delivered to the\ncurrent agent process. The durable record is the task state, activity entry,\nworkpad, and transcript update that follow.\n\n## Permission Requests\n\nWhen an adapter needs human approval, it can create a durable permission\nrequest. The task activity shows `permission.requested`; after a response is\naccepted it shows `permission.responded` with the decision.\n\nIf your console deployment renders an inline permission prompt, answer it from\nthe task page by approving or denying the request and include a reason when the\nprompt asks for one. A permission request accepts only one response. Flakes\ndelivers the answer only to the active assignment for that task, so stale\nagents cannot receive answers for work they no longer own.\n\nPermission requests are always visible as durable activity events. Some\ndeployments or integrations may also render an inline approval prompt in the\nconsole, but do not assume every task page has a general approve or deny\ncontrol. When no control is visible, answer the request through the integration\nor API client that surfaced it, then use the console activity and transcript to\nconfirm the response was recorded and delivered.\n\n## What To Do By State\n\n| State | What it means | What you can do |\n| --- | --- | --- |\n| queued | The task is admitted but has not started. | Check dependencies, required capabilities, and connected host capacity. Usually the right action is to wait for capacity or connect capacity that advertises the needed adapter and capabilities. |\n| running | A sandbox currently owns the task. | Watch heartbeat, activity, workpad, and transcript. Send a follow-up or steer message if the agent needs more context. |\n| waiting | The task yielded because a durable wait condition is not satisfied. | Inspect the group or dependency that must settle. Do not expect the old process to resume; Flakes resumes the logical task from durable state when the wait condition resolves. |\n| failed | The task reached a terminal failure. | Open task detail, read the activity and transcript, inspect the workpad, and decide whether to create follow-up work in a new or still-open run. |\n| blocked on input | The task needs a human answer, such as a permission decision or missing context. | Use the visible prompt or live follow-up control when available. If no permission control is visible, respond through the client or integration that owns the prompt and verify `permission.responded` in activity. |\n\nFor scheduling issues, start with the run Timeline and By Sandbox views. For\nagent behavior, start with task Activity, Workpad, and Agent transcript. For\nhuman intervention, use Follow up, Steer, and the permission response path\navailable in your deployment.\n";
-var reference_default = "---\ntitle: Reference\ndescription: CLI commands, host configuration, selected API routes, and integrator exports for hosted Flakes.\n---\n\nUse this page after you understand the main workflows. It is a lookup for the\nhosted console at `https://flakes.dev`, the `flakes` CLI, user-supplied hosts,\nand selected integration surfaces.\n\nFor first-run steps, start with [Installing and Authorizing the CLI](/docs/cli).\nFor host setup, see [Connecting Your Hosts](/docs/connect-a-host).\n\n## CLI Command Reference\n\nCLI commands target the hosted control plane at `https://flakes.dev`. Most\ncommands use the stored credential from `flakes auth login`; commands that also\naccept `--token` are mainly for trusted automation.\n\n### Auth\n\n| Command | Use |\n| --- | --- |\n| `flakes auth login` | Start device authorization, open the browser approval page, and save the CLI credential. |\n| `flakes auth login --no-open` | Print the verification URL and user code without opening a browser. Useful on remote shells. |\n| `flakes auth login --timeout-ms 600000` | Wait longer for browser approval. |\n| `flakes auth login --json` | Emit the device-code and authenticated records as newline-delimited JSON for automation. |\n| `flakes auth status` | Show whether the stored CLI credential is authenticated, expired, or missing. |\n| `flakes auth status --json` | Emit structured credential status. |\n| `flakes auth logout` | Remove the stored CLI credential. |\n| `flakes auth logout --json` | Emit structured logout output. |\n\n### Local Runtime And Config\n\nThese commands are mostly for local development, smoke checks, or authoring\nruntime config files. The hosted path usually starts with auth and host setup.\n\n| Command | Use |\n| --- | --- |\n| `flakes server --config <server.toml>` | Validate config, open the PostgreSQL store, and start the control-plane server. `-c` is also accepted. |\n| `flakes server --config <server.toml> --host 127.0.0.1 --port 7733 --dry-run` | Validate server config and print a redacted JSON summary without starting the daemon. |\n| `flakes sandbox --config <sandbox.toml>` | Validate config, load adapters, and start the sandbox daemon. `-c` is also accepted. |\n| `flakes sandbox --config <sandbox.toml> --dry-run` | Validate sandbox config and print the daemon descriptor without opening a control-plane stream. |\n| `flakes down --session flakes --dry-run --json` | Stop or preview stopping a local tmux runtime session. |\n| `flakes config schema` | Print annotated TOML examples for server and sandbox config. |\n| `flakes config schema server` | Print only the server config example. `sandbox` is also supported. |\n\n### Projects\n\n| Command | Use |\n| --- | --- |\n| `flakes projects create --key <project-key> --name <name>` | Create or idempotently read an active Project namespace for new runs. |\n| `flakes projects list` | List Projects owned by the authenticated account, including archived Projects. |\n| `flakes projects archive <project-key>` | Archive a Project so new runs and host bindings cannot use it. Existing history remains visible. |\n| `flakes projects bind-host <project-key> --host <host-id> --pool <pool-key>` | Bind a Project to a host pool. Repeat `--pool` to allow more than one pool on the same host. |\n\nProject keys are lowercase path-safe names. They are used for hosted identity\nand for the host-local directory under each configured project root.\n\n### Host Setup And Operation\n\n| Command | Use |\n| --- | --- |\n| `flakes host setup --config <host.toml>` | Create a host and first host-scoped credential through direct CLI user auth, then write the host config. |\n| `flakes host setup --config <host.toml> --credential-file <path> --state-dir <dir> --host-name <name>` | Override the credential file, state directory, or displayed host name. |\n| `flakes host setup --config <host.toml> --no-open --timeout-ms 600000` | Run setup on a remote shell and let the embedded device-login flow wait longer for approval. |\n| `flakes host setup --config <host.toml> --json` | Emit structured setup output with redacted host and credential summaries. The raw credential is not printed. |\n| `flakes host rotate --config <host.toml>` | Request a new host credential, write it to the configured credential file, and retire the replaced credential. Restart the host process afterward. |\n| `flakes host rotate --config <host.toml> --json` | Emit structured rotation output, including the new credential summary and next steps. The raw credential is not printed. |\n| `flakes host project-root set --config <host.toml> --path <absolute-root>` | Store the host-local project root on the hosted control plane. The server stores the path but does not inspect the host filesystem. |\n| `flakes host run --config <host.toml>` | Start the host runtime and connect capacity to Flakes. This process should stay running. |\n| `flakes host status --config <host.toml>` | Validate local config and, when a CLI credential is available, read remote host, pool, and credential status. |\n| `flakes host status --config <host.toml> --json` | Emit structured local and remote status. |\n\nSetup writes new files only when the target config and credential file do not\nalready exist. Setup and rotation require an authenticated CLI user credential\nfor the same hosted origin; they are direct user bearer auth flows, not console\nproxy flows.\n\n### Runs\n\n| Command | Use |\n| --- | --- |\n| `flakes runs create --project <project-key> --key <run-key> --name \"Release notes\"` | Create or reuse a run identified by a stable run key inside an active Project. |\n| `flakes runs create --project <project-key> --key <run-key> --name \"Release notes\" --token <token>` | Create a run using an explicit automation bearer token instead of the stored CLI credential. `-t` is also accepted. |\n| `flakes runs close <run-key>` | Close the run so no more top-level tasks can be admitted. |\n| `flakes runs close <run-key> --wait --timeout-ms 600000` | Close the run and poll until the run reaches a terminal state or the timeout expires. |\n| `flakes runs close <run-key> --token <token>` | Close a run using an explicit automation bearer token. `-t` is also accepted. |\n| `flakes inspect <run-id-or-key>` | Read a run. A non-`run_` value is treated as a run key. |\n| `flakes inspect <task-id> --task` | Read a task explicitly. |\n| `flakes logs <task-id> --after <cursor> --limit <n>` | Read bounded task logs. |\n| `flakes metrics <run-id>` | Read run metrics. |\n\n`runs`, `inspect`, `logs`, and `metrics` accept `--token <token>` or `-t\n<token>` when trusted automation should bypass the stored CLI credential.\n\n### Tasks\n\n| Command | Use |\n| --- | --- |\n| `flakes tasks save --run <run-key> --key <task-key> --title \"Draft\" --adapter pi --body \"Write the draft.\"` | Save or update a not-yet-admitted task. |\n| `flakes tasks save --run <run-key> --key <task-key> --title \"Draft\" --adapter pi --body-file prompt.md --required-capability pi --depends-on outline` | Save a task with a file body, capability requirement, and dependency. |\n| `flakes tasks save --run <run-key> --key <task-key> --title \"Plan\" --adapter harness --harness-file harnesses/paper-writer.ts --tool-grant flakes.tasks.spawn` | Submit a harness module as a normal task. |\n| `flakes tasks admit --run <run-key> <task-key>` | Admit specific saved tasks for scheduling. |\n| `flakes tasks admit --run <run-key> --all` | Admit all saved tasks that are ready for admission. |\n\nTask save accepts `--acceptance`, `--depends-on`, `--required-capability`, and\n`--tool-grant` more than once. `--harness-file` requires `--adapter harness`.\nTask commands that call the hosted API accept `--token <token>` or `-t <token>`\nfor trusted automation.\n\n### Workpads And File Reservations\n\n| Command | Use |\n| --- | --- |\n| `flakes tasks workpad show <task-id>` | Read a task workpad as JSON. |\n| `flakes tasks workpad show <task-id> --raw` | Print only the Markdown body. |\n| `flakes tasks workpad save <task-id> --file <workpad.md> --base-version <version>` | Save a workpad with an optimistic version check. `-f` is also accepted for `--file`. |\n| `flakes tasks workpad template <task-id> --output <workpad.md>` | Create a local Markdown template for editing. `-o` is also accepted. |\n| `flakes tasks workpad pull` | Inside a running Flakes task, pull the assignment-local workpad into the thread state directory. |\n| `flakes tasks workpad push` | Inside a running Flakes task, push the assignment-local workpad with its saved base version. |\n| `flakes tasks files reserve <path...> --reason \"editing\" --json` | Inside a running task, reserve assignment-scoped file paths before editing. |\n| `flakes tasks files reserve <path...> --prefix --json` | Reserve path prefixes instead of exact paths. |\n| `flakes tasks files release <path...> --json` | Release assignment-scoped file reservations. |\n| `flakes tasks files release <path...> --prefix --json` | Release prefix reservations instead of exact-path reservations. |\n| `flakes tasks files release --all --json` | Release all reservations owned by the current assignment. |\n| `flakes tasks files list --json` | List current assignment file reservations. |\n| `flakes tasks files check <path...> --json` | Check whether paths conflict with existing reservations. |\n| `flakes tasks files check <path...> --prefix --json` | Check prefix selectors for conflicts. |\n\nThe `pull`, `push`, and `files` commands are attached to a running task through\nthread-local environment variables. They fail outside a running Flakes task.\n\n### Messages And Permissions\n\nMessages and permission responses do not have standalone top-level CLI commands.\nUse the console controls when available, or call the selected API routes:\n\n| Route | Use |\n| --- | --- |\n| `POST /v1/tasks/:taskId/messages` | Send a `follow_up` or `steer` message to a running task. |\n| `POST /v1/tasks/:taskId/permissions/:permissionRequestId/respond` | Answer a task permission request with `approved` or `denied`. |\n\nBoth routes require the task to be running on a connected sandbox. See\n[Observing And Steering](/docs/observe-and-steer) for user-facing behavior.\n\n### Harness Checks\n\n| Command | Use |\n| --- | --- |\n| `flakes harness init --template paper --dir harnesses` | Create a starter harness module. |\n| `flakes harness init --template review-revise --dir harnesses --file review.ts --force` | Write a specific template and overwrite the target file. |\n| `flakes harness check harnesses/paper-writer.ts` | Typecheck and validate a harness module before submission. |\n| `flakes harness check harnesses/paper-writer.ts --defaults harnesses/defaults.json --json` | Check with adapter/agent defaults and emit structured diagnostics. |\n\nCurrent template names are `paper`, `review-revise`, `fanout-fanin`,\n`autowrite`, and `autoresearch`.\n\n### Artifacts\n\n| Command | Use |\n| --- | --- |\n| `flakes artifacts create --file artifact.json` | Create artifact metadata, optionally with inline bytes in the JSON payload. `-f` is also accepted. |\n| `flakes artifacts get <artifact-id>` | Read artifact metadata. |\n| `flakes artifacts fetch <artifact-id> --location-id <location-id>` | Fetch a specific artifact location when more than one location is available. |\n| `flakes artifacts fetch <artifact-id> --output <file>` | Fetch artifact bytes to a file. `-o` is also accepted. |\n| `flakes artifacts fetch <artifact-id> --raw` | Write exact artifact bytes to stdout. |\n\nArtifact commands accept `--token <token>` or `-t <token>` for trusted\nautomation.\n\n## Host Config Reference\n\n`flakes host setup` writes a starter Host config TOML file. Add at least one\npool before running `flakes host run`.\n\nHost config TOML describes host identity, credentials, state, and capacity\npools. Host TOML pools do not contain `workspace`; the project workspace root\nis stored in the control plane with `flakes host project-root set`.\nThe project workspace root is stored in the control plane, not in Host TOML.\n\n```toml\ncontrolPlaneUrl = \"https://flakes.dev\"\nhostId = \"host_abc123\"\ncredentialFile = \"/Users/me/.config/flakes/host.credential\"\nstateDir = \"/Users/me/.config/flakes/state\"\n\n[[pools]]\npoolKey = \"mac-coding\"\nmatchlockImage = \"registry.example/flakes/macos:latest\"\nmounts = [\"/Users/me/.cache/flakes:/cache\"]\nadapter = \"pi\"\nmaxInstances = 2\nmaxConcurrency = 1\nadvertisedCapabilities = [\"pi\", \"node\", \"mac\"]\n\n[pools.resourceBounds]\nmemoryMb = 8192\ncpus = 4\n\n[pools.env]\nEXAMPLE = \"value\"\n\n[pools.executablePaths]\nmatchlock = \"/usr/local/bin/matchlock\"\nflakes = \"/usr/local/bin/flakes\"\n```\n\n### Top-Level Fields\n\n| Field | Required | Meaning |\n| --- | --- | --- |\n| `controlPlaneUrl` | Yes | Hosted API origin. Host setup writes `https://flakes.dev`. |\n| `hostId` | Yes | Host identity returned by setup. It must be a non-empty identifier. |\n| `credentialFile` | Yes | Absolute path to the host-scoped credential file. `credentialFile must be an absolute path`; it must be a regular file owned by the current user, not a symlink, with `0600` permissions. |\n| `stateDir` | No | Absolute private directory for host runtime state. When omitted, it defaults beside the credential file. The runtime also creates a generated sandbox config directory under this state directory. |\n| `pools` | Yes | One to 64 pool definitions. A config with no pools is invalid for `flakes host run`. |\n\n### Pool Fields\n\n| Field | Required | Meaning |\n| --- | --- | --- |\n| `poolKey` | Yes | Stable pool identifier advertised to Flakes. Must be unique within the host config. |\n| `provider` | Implied | The current provider is `matchlock`. It is advertised as `provider: \"matchlock\"`; it is not a required TOML field. |\n| `matchlockImage` | Yes | Local MatchLock image or template used by the host to launch sandboxes. This is local-only and is not sent in the sanitized pool advertisement. |\n| `mounts` | No | Local mount strings passed to the provider. These stay on the host. |\n| `adapter` | Yes | Adapter the sandbox should run, such as `pi` or `harness`. This is advertised for scheduling. |\n| `maxInstances` | Yes | Positive integer limit for provider instances in the pool. |\n| `maxConcurrency` | Yes | Positive integer limit for concurrent work in each advertised sandbox config. |\n| `advertisedCapabilities` | Yes | Up to 64 scheduling capability strings, such as `pi`, `node`, or `mac`. These become advertised as `capabilities`. |\n| `resourceBounds` | No | Small sanitized record for scheduler-facing bounds, such as CPU or memory. Oversized or unsafe records are rejected. |\n| `env` | No | Local environment variables for provider startup. These are local-only and are not advertised. |\n| `executablePaths.matchlock` | Yes | Absolute path to the MatchLock executable. It must exist, be a file, be executable, and not be a symlink. |\n| `executablePaths.<name>` | No | Additional executable paths, for example `flakes`. These are local-only. |\n\n### Sanitized Pool Advertisement\n\nThe host sends only a sanitized pool advertisement to the control plane:\n\n- `poolKey`\n- `provider`\n- `adapter`\n- `maxInstances`\n- `maxConcurrency`\n- `capabilities`\n- sanitized `resourceBounds`, when present\n\nLocal-only fields stay on the host: `matchlockImage`, `mounts`, `env`,\n`credentialFile`, `stateDir`, `executablePaths`, and the derived Project\nworkspace paths. Do not rely on those fields appearing in the console or API\npool responses.\n\n`workspace` is rejected inside `[[pools]]`. Configure Project placement with\n`PUT /v1/hosts/:hostId/project-workspace-root` or\n`flakes host project-root set`, then bind Projects to allowed pool keys.\n\n## Selected API Reference\n\nThis section is for integrators. Ordinary users should prefer the console and\nCLI workflows above. Unless noted otherwise, routes use `/v1`, require a user\nbearer credential for the same hosted origin, and are scoped to the authenticated\nowner.\n\n### Projects\n\n| Route | Use |\n| --- | --- |\n| `GET /v1/projects` | List owned Projects. Archived Projects remain visible unless a client filters them. |\n| `PUT /v1/projects/:projectKey` | Create or idempotently read a Project. Body includes `projectKey`, `name`, and optional user metadata. |\n| `GET /v1/projects/:projectKey` | Read one owned Project by key. |\n| `PATCH /v1/projects/:projectKey` | Update safe Project display fields such as `name` and user metadata. The key is immutable. |\n| `POST /v1/projects/:projectKey/archive` | Archive an owned Project. Archived Projects cannot be used for new run creation or new host bindings. |\n\nProject DTOs include `projectId`, `projectKey`, `name`, `status`, timestamps,\nand user metadata. Project identity is stored as Project fields on runs and\ntasks; do not encode it into a generic metadata value.\n\n### Runs And Tasks\n\n| Route | Use |\n| --- | --- |\n| `PUT /v1/runs/:runKey` | Create or idempotently read a Project-scoped run by stable key. Body includes `name` and either `projectKey` or `projectId`. |\n| `GET /v1/runs?projectKey=<project-key>&state=<state>&cursor=<cursor>&limit=<n>` | List owned runs, optionally filtered by Project key and state. |\n| `GET /v1/runs/:runId` | Read one owned run by run ID. |\n| `DELETE /v1/runs/:runId` | Delete an owned run after cancel delivery is attempted for live tasks. |\n| `POST /v1/runs/:runKey/close` | Close a run so no more top-level work can be admitted. |\n| `GET /v1/runs/:runId/tasks` | List tasks with workpad metadata for console task overview screens. |\n| `PUT /v1/runs/:runKey/tasks/:taskKey` | Save a task before admission. Body includes task metadata, target adapter, input, dependencies, capabilities, and grants. |\n| `POST /v1/runs/:runKey/tasks/admit` | Admit selected task keys or all saved tasks. |\n| `GET /v1/tasks/:taskId` | Read one task. |\n| `POST /v1/tasks/:taskId/cancel` | Request cancellation for a live task and record task state. |\n| `GET /v1/tasks/:taskId/logs` | Read bounded task logs. |\n| `GET /v1/tasks/:taskId/activity` | Read activity events such as workpad updates, human input, and permission events. |\n\n### Workpads, Messages, And Permissions\n\n| Route | Use |\n| --- | --- |\n| `GET /v1/tasks/:taskId/workpad` | Read the current task workpad. |\n| `PUT /v1/tasks/:taskId/workpad` | Save Markdown with `bodyMarkdown` and `baseVersion`. A stale version returns `workpad_version_conflict` with the current workpad. Workpads are limited to 512 KiB. |\n| `POST /v1/tasks/:taskId/messages` | Queue `follow_up` or `steer` input for a running task. Messages must be non-empty and at most 20000 characters. |\n| `POST /v1/tasks/:taskId/permissions/:permissionRequestId/respond` | Send `approved` or `denied` for a permission request. A request accepts only one answer and must still belong to the active assignment. |\n| `GET /v1/tasks/:taskId/rounds/:roundKey/outputs/:outputKey/fetch` | Read a bounded JSON or text live-round output. |\n| `GET /v1/tasks/:taskId/rounds/:roundKey/outputs/:outputKey/workspace` | Resolve a live-round workspace output handle. |\n\n### Hosts\n\n| Route | Use |\n| --- | --- |\n| `GET /v1/hosts` | List owned hosts. |\n| `POST /v1/hosts` | Create a host record directly for integrator workflows that do not need the CLI to mint a local host credential. |\n| `POST /v1/hosts/setup` | Create a host and its first host-scoped credential in one transaction. Requires direct user bearer auth and returns the raw credential exactly once for CLI persistence. |\n| `GET /v1/hosts/:hostId` | Read one owned host. |\n| `PATCH /v1/hosts/:hostId` | Update safe display fields and user metadata. Runtime, adapter, path, env, image, provider, and status metadata keys are rejected. |\n| `PUT /v1/hosts/:hostId/project-workspace-root` | Store an absolute host-local Project root. The control plane stores the string and does not perform filesystem checks. |\n| `PUT /v1/hosts/:hostId/project-bindings/:projectKey` | Bind an active owned Project to one or more existing pool keys on the owned host. Body includes `poolKeys`. |\n| `GET /v1/hosts/:hostId/project-bindings` | List Project bindings for the host, including derived `workspacePath`, allowed `poolKeys`, availability, and validation reason. |\n| `POST /v1/hosts/:hostId/disable` | Disable a host. Disabled hosts cannot claim new work. |\n| `DELETE /v1/hosts/:hostId` | Delete a host only when active lifecycle state no longer blocks deletion. |\n| `GET /v1/hosts/:hostId/pools` | Read pools synced from the running host. There is no user-facing pool write route; edit host TOML and restart or reconnect the host. |\n| `GET /v1/hosts/:hostId/credentials` | List redacted host credential summaries. |\n| `GET /v1/hosts/:hostId/credentials/:hostCredentialId` | Read one redacted host credential summary. |\n| `POST /v1/hosts/:hostId/credentials/rotate` | Rotate a host credential. Requires direct user bearer auth and returns the raw replacement credential once. |\n| `POST /v1/hosts/:hostId/credentials/:hostCredentialId/revoke` | Revoke a host credential. |\n\nHost setup and credential rotation require direct user bearer auth. Do not send\nthose requests through the browser console proxy.\n\n### Artifacts And Run Outputs\n\n| Route | Use |\n| --- | --- |\n| `POST /v1/artifacts` | Create artifact metadata and optional inline bytes. |\n| `GET /v1/artifacts/:artifactId` | Read artifact metadata. |\n| `GET /v1/artifacts/:artifactId/fetch` | Fetch artifact bytes. |\n| `GET /v1/runs/:runId/artifacts` | List artifacts associated with a run. |\n| `GET /v1/runs/:runId/history.jsonl` | Export redacted run history as JSONL. |\n| `GET /v1/runs/:runId/file-reservations` | List file reservations visible for the run. |\n| `GET /v1/runs/:runId/metrics` | Read evaluation metrics for the run. |\n\nSandbox-scoped workspace, group, and live-round routes are runtime surfaces for\nadapters and harness execution. Integrators should normally use the CLI,\nselected client routes, or Harness SDK helpers instead of calling those routes\ndirectly.\n\n## Relevant Exports\n\nThe hosted API and CLI are the primary user boundary. These exports are useful\nonly for integrations, harness modules, adapters, or repository-local tooling.\n\n| Export | Use |\n| --- | --- |\n| `@flakes/harness-sdk` | Harness authors import `defineHarness`, use `HarnessContext`, and call helpers such as `ctx.group(...)`, `ctx.groups.open(...)`, `ctx.output.json(...)`, `ctx.outputs.readJson(...)`, `ctx.workpads.read(...)`, `ctx.workspace.commit(...)`, `ctx.workspace.promote(...)`, and `ctx.liveTasks.send(...)`. |\n| `@flakes/core` | Integrators that build typed payloads can reuse schemas and types for run/task IDs, saved tasks, task metadata, task groups, task spawn requests, workpads, file reservations, and workspace handles. Common names include `WorkspaceHandle`, `WorkspaceHandleSchema`, `TaskProductMetadataSchema`, and `TaskWorkpadPutRequestSchema`. |\n| `@flakes/protocol` | Runtime implementers can parse and validate sandbox and host stream messages with protocol schemas and safe parse helpers. Ordinary API clients do not need these types. |\n| `@flakes/cli` | Test harnesses or wrappers can call `runCli(...)` with injected IO and transport dependencies instead of shelling out. The installed binary remains `flakes`. |\n\nDo not treat this table as a package architecture guide. It lists only the\nexports a user, harness author, or integrator might reasonably need.\n";
+var reference_default = "---\ntitle: Reference\ndescription: CLI commands, host configuration, selected API routes, and integrator exports for hosted Flakes.\n---\n\nUse this page after you understand the main workflows. It is a lookup for the\nhosted console at `https://flakes.dev`, the `flakes` CLI, user-supplied hosts,\nand selected integration surfaces.\n\nFor first-run steps, start with [Installing and Authorizing the CLI](/docs/cli).\nFor host setup, see [Connecting Your Hosts](/docs/connect-a-host).\n\n## CLI Command Reference\n\nCLI commands target the hosted control plane at `https://flakes.dev`. Most\ncommands use the stored credential from `flakes auth login`; commands that also\naccept `--token` are mainly for trusted automation.\n\n### Auth\n\n| Command | Use |\n| --- | --- |\n| `flakes auth login` | Start device authorization, open the browser approval page, and save the CLI credential. |\n| `flakes auth login --no-open` | Print the verification URL and user code without opening a browser. Useful on remote shells. |\n| `flakes auth login --timeout-ms 600000` | Wait longer for browser approval. |\n| `flakes auth login --json` | Emit the device-code and authenticated records as newline-delimited JSON for automation. |\n| `flakes auth status` | Show whether the stored CLI credential is authenticated, expired, or missing. |\n| `flakes auth status --json` | Emit structured credential status. |\n| `flakes auth logout` | Remove the stored CLI credential. |\n| `flakes auth logout --json` | Emit structured logout output. |\n\n### Local Runtime And Config\n\nThese commands are mostly for local development, smoke checks, or authoring\nruntime config files. The hosted path usually starts with auth and host setup.\n\n| Command | Use |\n| --- | --- |\n| `flakes server --config <server.toml>` | Validate config, open the PostgreSQL store, and start the control-plane server. `-c` is also accepted. |\n| `flakes server --config <server.toml> --host 127.0.0.1 --port 7733 --dry-run` | Validate server config and print a redacted JSON summary without starting the daemon. |\n| `flakes sandbox --config <sandbox.toml>` | Validate config, load adapters, and start the sandbox daemon. `-c` is also accepted. |\n| `flakes sandbox --config <sandbox.toml> --dry-run` | Validate sandbox config and print the daemon descriptor without opening a control-plane stream. |\n| `flakes down --session flakes --dry-run --json` | Stop or preview stopping a local tmux runtime session. |\n| `flakes config schema` | Print annotated TOML examples for server and sandbox config. |\n| `flakes config schema server` | Print only the server config example. `sandbox` is also supported. |\n\n### Projects\n\n| Command | Use |\n| --- | --- |\n| `flakes projects create --key <project-key> --name <name>` | Create or idempotently read an active Project namespace for new runs. |\n| `flakes projects list` | List Projects owned by the authenticated account, including archived Projects. |\n| `flakes projects archive <project-key>` | Archive a Project so new runs and host bindings cannot use it. Existing history remains visible. |\n| `flakes projects bind-host <project-key> --host <host-id> --pool <pool-key>` | Bind a Project to a host pool. Repeat `--pool` to allow more than one pool on the same host. |\n\nProject keys are lowercase path-safe names. They are used for hosted identity\nand for the host-local directory under each configured project root.\n\n### Host Setup And Operation\n\n| Command | Use |\n| --- | --- |\n| `flakes host setup --config <host.toml>` | Create a host and first host-scoped credential through direct CLI user auth, then write the host config. |\n| `flakes host setup --config <host.toml> --credential-file <path> --state-dir <dir> --host-name <name>` | Override the credential file, state directory, or displayed host name. |\n| `flakes host setup --config <host.toml> --no-open --timeout-ms 600000` | Run setup on a remote shell and let the embedded device-login flow wait longer for approval. |\n| `flakes host setup --config <host.toml> --json` | Emit structured setup output with redacted host and credential summaries. The raw credential is not printed. |\n| `flakes host rotate --config <host.toml>` | Request a new host credential, write it to the configured credential file, and retire the replaced credential. Restart the host process afterward. |\n| `flakes host rotate --config <host.toml> --json` | Emit structured rotation output, including the new credential summary and next steps. The raw credential is not printed. |\n| `flakes host project-root set --config <host.toml> --path <absolute-root>` | Store the host-local project root on the hosted control plane. The server stores the path but does not inspect the host filesystem. |\n| `flakes host run --config <host.toml>` | Start the host runtime and connect capacity to Flakes. This process should stay running. |\n| `flakes host status --config <host.toml>` | Validate local config and, when a CLI credential is available, read remote host, pool, and credential status. |\n| `flakes host status --config <host.toml> --json` | Emit structured local and remote status. |\n\nSetup writes new files only when the target config and credential file do not\nalready exist. Setup and rotation require an authenticated CLI user credential\nfor the same hosted origin; they are direct user bearer auth flows, not console\nproxy flows.\n\n### Runs\n\n| Command | Use |\n| --- | --- |\n| `flakes runs create --project <project-key> --key <run-key> --name \"Release notes\"` | Create or reuse a run identified by a stable run key inside an active Project. |\n| `flakes runs create --project <project-key> --key <run-key> --name \"Release notes\" --token <token>` | Create a run using an explicit automation bearer token instead of the stored CLI credential. `-t` is also accepted. |\n| `flakes runs close <run-key>` | Close the run so no more top-level tasks can be admitted. |\n| `flakes runs close <run-key> --wait --timeout-ms 600000` | Close the run and poll until the run reaches a terminal state or the timeout expires. |\n| `flakes runs close <run-key> --token <token>` | Close a run using an explicit automation bearer token. `-t` is also accepted. |\n| `flakes inspect <run-id-or-key>` | Read a run. A non-`run_` value is treated as a run key. |\n| `flakes inspect <task-id> --task` | Read a task explicitly. |\n| `flakes logs <task-id> --after <cursor> --limit <n>` | Read bounded task logs. |\n| `flakes metrics <run-id>` | Read run metrics. |\n\n`runs`, `inspect`, `logs`, and `metrics` accept `--token <token>` or `-t\n<token>` when trusted automation should bypass the stored CLI credential.\n\n### Tasks\n\n| Command | Use |\n| --- | --- |\n| `flakes tasks save --run <run-key> --key <task-key> --title \"Draft\" --adapter pi --body \"Write the draft.\"` | Save or update a not-yet-admitted task. |\n| `flakes tasks save --run <run-key> --key <task-key> --title \"Draft\" --adapter pi --body-file prompt.md --required-capability pi --depends-on outline` | Save a task with a file body, capability requirement, and dependency. |\n| `flakes tasks save --run <run-key> --key <task-key> --title \"Plan\" --adapter harness --harness-file harnesses/paper-writer.ts --tool-grant flakes.tasks.spawn` | Submit a harness module as a normal task. |\n| `flakes tasks admit --run <run-key> <task-key>` | Admit specific saved tasks for scheduling. |\n| `flakes tasks admit --run <run-key> --all` | Admit all saved tasks that are ready for admission. |\n\nTask save accepts `--acceptance`, `--depends-on`, `--required-capability`, and\n`--tool-grant` more than once. `--harness-file` requires `--adapter harness`.\nTask commands that call the hosted API accept `--token <token>` or `-t <token>`\nfor trusted automation.\n\n### Workpads And File Reservations\n\n| Command | Use |\n| --- | --- |\n| `flakes tasks workpad show <task-id>` | Read a task workpad as JSON. |\n| `flakes tasks workpad show <task-id> --raw` | Print only the Markdown body. |\n| `flakes tasks workpad save <task-id> --file <workpad.md> --base-version <version>` | Save a workpad with an optimistic version check. `-f` is also accepted for `--file`. |\n| `flakes tasks workpad template <task-id> --output <workpad.md>` | Create a local Markdown template for editing. `-o` is also accepted. |\n| `flakes tasks workpad pull` | Inside a running Flakes task, pull the assignment-local workpad into the thread state directory. |\n| `flakes tasks workpad push` | Inside a running Flakes task, push the assignment-local workpad with its saved base version. |\n| `flakes tasks files reserve <path...> --reason \"editing\" --json` | Inside a running task, reserve assignment-scoped file paths before editing. |\n| `flakes tasks files reserve <path...> --prefix --json` | Reserve path prefixes instead of exact paths. |\n| `flakes tasks files release <path...> --json` | Release assignment-scoped file reservations. |\n| `flakes tasks files release <path...> --prefix --json` | Release prefix reservations instead of exact-path reservations. |\n| `flakes tasks files release --all --json` | Release all reservations owned by the current assignment. |\n| `flakes tasks files list --json` | List current assignment file reservations. |\n| `flakes tasks files check <path...> --json` | Check whether paths conflict with existing reservations. |\n| `flakes tasks files check <path...> --prefix --json` | Check prefix selectors for conflicts. |\n\nThe `pull`, `push`, and `files` commands are attached to a running task through\nthread-local environment variables. They fail outside a running Flakes task.\n\n### Messages And Permissions\n\nMessages and permission responses do not have standalone top-level CLI commands.\nUse the console controls when available, or call the selected API routes:\n\n| Route | Use |\n| --- | --- |\n| `POST /v1/tasks/:taskId/messages` | Send a `follow_up` or `steer` message to a running task. |\n| `POST /v1/tasks/:taskId/permissions/:permissionRequestId/respond` | Answer a task permission request with `approved` or `denied`. |\n\nBoth routes require the task to be running on a connected sandbox. See\n[Observing And Steering](/docs/observe-and-steer) for user-facing behavior.\n\n### Harness Checks\n\n| Command | Use |\n| --- | --- |\n| `flakes harness init --template paper --dir harnesses` | Create a starter harness module. |\n| `flakes harness init --template review-revise --dir harnesses --file review.ts --force` | Write a specific template and overwrite the target file. |\n| `flakes harness check harnesses/paper-writer.ts` | Typecheck and validate a harness module before submission. |\n| `flakes harness check harnesses/paper-writer.ts --defaults harnesses/defaults.json --json` | Check with adapter/agent defaults and emit structured diagnostics. |\n\nCurrent template names are `paper`, `review-revise`, `fanout-fanin`,\n`autowrite`, and `autoresearch`.\n\n### Artifacts\n\n| Command | Use |\n| --- | --- |\n| `flakes artifacts create --file artifact.json` | Create artifact metadata, optionally with inline bytes in the JSON payload. `-f` is also accepted. |\n| `flakes artifacts get <artifact-id>` | Read artifact metadata. |\n| `flakes artifacts fetch <artifact-id> --location-id <location-id>` | Fetch a specific artifact location when more than one location is available. |\n| `flakes artifacts fetch <artifact-id> --output <file>` | Fetch artifact bytes to a file. `-o` is also accepted. |\n| `flakes artifacts fetch <artifact-id> --raw` | Write exact artifact bytes to stdout. |\n\nArtifact commands accept `--token <token>` or `-t <token>` for trusted\nautomation.\n\n## Host Config Reference\n\n`flakes host setup` writes a starter Host config TOML file. Add at least one\npool before running `flakes host run`.\n\nHost config TOML describes host identity, credentials, state, and capacity\npools. Host TOML pools do not contain `workspace`; the project workspace root\nis stored in the control plane with `flakes host project-root set`.\nThe project workspace root is stored in the control plane, not in Host TOML.\n\n```toml\ncontrolPlaneUrl = \"https://flakes.dev\"\nhostId = \"host_abc123\"\ncredentialFile = \"/Users/me/.config/flakes/host.credential\"\nstateDir = \"/Users/me/.config/flakes/state\"\n\n[[pools]]\npoolKey = \"mac-coding\"\nmatchlockImage = \"registry.example/flakes/macos:latest\"\nmounts = [\"/Users/me/.cache/flakes:/cache\"]\nadapter = \"pi\"\nmaxInstances = 2\nmaxConcurrency = 1\nadvertisedCapabilities = [\"pi\", \"node\", \"mac\"]\n\n[pools.resourceBounds]\nmemoryMb = 8192\ncpus = 4\n\n[pools.env]\nEXAMPLE = \"value\"\n\n[pools.executablePaths]\nmatchlock = \"/usr/local/bin/matchlock\"\nflakes = \"/usr/local/bin/flakes\"\n```\n\n### Top-Level Fields\n\n| Field | Required | Meaning |\n| --- | --- | --- |\n| `controlPlaneUrl` | Yes | Hosted API origin. Host setup writes `https://flakes.dev`. |\n| `hostId` | Yes | Host identity returned by setup. It must be a non-empty identifier. |\n| `credentialFile` | Yes | Absolute path to the host-scoped credential file. `credentialFile must be an absolute path`; it must be a regular file owned by the current user, not a symlink, with `0600` permissions. |\n| `stateDir` | No | Absolute private directory for host runtime state. When omitted, it defaults beside the credential file. The runtime also creates a generated sandbox config directory under this state directory. |\n| `pools` | Yes | One to 64 pool definitions. A config with no pools is invalid for `flakes host run`. |\n\n### Pool Fields\n\n| Field | Required | Meaning |\n| --- | --- | --- |\n| `poolKey` | Yes | Stable pool identifier advertised to Flakes. Must be unique within the host config. |\n| `provider` | Implied | The current provider is `matchlock`. It is advertised as `provider: \"matchlock\"`; it is not a required TOML field. |\n| `matchlockImage` | Yes | Local MatchLock image or template used by the host to launch sandboxes. This is local-only and is not sent in the sanitized pool advertisement. |\n| `mounts` | No | Local mount strings passed to the provider. These stay on the host. |\n| `adapter` | Yes | Adapter the sandbox should run, such as `pi` or `harness`. This is advertised for scheduling. |\n| `maxInstances` | Yes | Positive integer limit for provider instances in the pool. |\n| `maxConcurrency` | Yes | Positive integer limit for concurrent work in each advertised sandbox config. |\n| `advertisedCapabilities` | Yes | Up to 64 scheduling capability strings, such as `pi`, `node`, or `mac`. These become advertised as `capabilities`. |\n| `resourceBounds` | No | Small sanitized record for scheduler-facing bounds, such as CPU or memory. Oversized or unsafe records are rejected. |\n| `env` | No | Local environment variables for provider startup. These are local-only and are not advertised. |\n| `executablePaths.matchlock` | Yes | Absolute path to the MatchLock executable. It must exist, be a file, be executable, and not be a symlink. |\n| `executablePaths.<name>` | No | Additional executable paths, for example `flakes`. These are local-only. |\n\n### Sanitized Pool Advertisement\n\nThe host sends only a sanitized pool advertisement to the control plane:\n\n- `poolKey`\n- `provider`\n- `adapter`\n- `maxInstances`\n- `maxConcurrency`\n- `capabilities`\n- sanitized `resourceBounds`, when present\n\nLocal-only fields stay on the host: `matchlockImage`, `mounts`, `env`,\n`credentialFile`, `stateDir`, `executablePaths`, and the derived Project\nworkspace paths. Do not rely on those fields appearing in the console or API\npool responses.\n\n`workspace` is rejected inside `[[pools]]`. Configure Project placement with\n`PUT /v1/hosts/:hostId/project-workspace-root` or\n`flakes host project-root set`, then bind Projects to allowed pool keys.\n\n## Selected API Reference\n\nThis section is for integrators. Ordinary users should prefer the console and\nCLI workflows above. Unless noted otherwise, routes use `/v1`, require a user\nbearer credential for the same hosted origin, and are scoped to the authenticated\nowner.\n\n### Projects\n\n| Route | Use |\n| --- | --- |\n| `GET /v1/projects` | List owned Projects. Archived Projects remain visible unless a client filters them. |\n| `PUT /v1/projects/:projectKey` | Create or idempotently read a Project. Body includes `projectKey`, `name`, and optional user metadata. |\n| `GET /v1/projects/:projectKey` | Read one owned Project by key. |\n| `PATCH /v1/projects/:projectKey` | Update safe Project display fields such as `name` and user metadata. The key is immutable. |\n| `POST /v1/projects/:projectKey/archive` | Archive an owned Project. Archived Projects cannot be used for new run creation or new host bindings. |\n\nProject DTOs include `projectId`, `projectKey`, `name`, `status`, timestamps,\nand user metadata. Project identity is stored as Project fields on runs and\ntasks; do not encode it into a generic metadata value.\n\n### Runs And Tasks\n\n| Route | Use |\n| --- | --- |\n| `PUT /v1/runs/:runKey` | Create or idempotently read a Project-scoped run by stable key. Body includes `name` and either `projectKey` or `projectId`. |\n| `GET /v1/runs?projectKey=<project-key>&state=<state>&cursor=<cursor>&limit=<n>` | List owned runs, optionally filtered by Project key and state. |\n| `GET /v1/runs/:runId` | Read one owned run by run ID. |\n| `DELETE /v1/runs/:runId` | Delete an owned run after cancel delivery is attempted for live tasks. |\n| `POST /v1/runs/:runKey/close` | Close a run so no more top-level work can be admitted. |\n| `GET /v1/runs/:runId/tasks` | List tasks with workpad metadata for console task overview screens. |\n| `PUT /v1/runs/:runKey/tasks/:taskKey` | Save a task before admission. Body includes task metadata, target adapter, input, dependencies, capabilities, and grants. |\n| `POST /v1/runs/:runKey/tasks/admit` | Admit selected task keys or all saved tasks. |\n| `GET /v1/tasks/:taskId` | Read one task. |\n| `POST /v1/tasks/:taskId/cancel` | Request cancellation for a live task and record task state. |\n| `GET /v1/tasks/:taskId/logs` | Read bounded task logs. |\n| `GET /v1/tasks/:taskId/activity` | Read activity events such as workpad updates, human input, and permission events. |\n\n### Workpads, Messages, And Permissions\n\n| Route | Use |\n| --- | --- |\n| `GET /v1/tasks/:taskId/workpad` | Read the current task workpad. |\n| `PUT /v1/tasks/:taskId/workpad` | Save Markdown with `bodyMarkdown` and `baseVersion`. A stale version returns `workpad_version_conflict` with the current workpad. Workpads are limited to 512 KiB. |\n| `POST /v1/tasks/:taskId/messages` | Queue `follow_up` or `steer` input for a running task. Messages must be non-empty and at most 20000 characters. |\n| `POST /v1/tasks/:taskId/permissions/:permissionRequestId/respond` | Send `approved` or `denied` for a permission request. A request accepts only one answer and must still belong to the active assignment. |\n| `GET /v1/tasks/:taskId/rounds/:roundKey/outputs/:outputKey/fetch` | Read a bounded JSON or text live-round output. |\n| `GET /v1/tasks/:taskId/rounds/:roundKey/outputs/:outputKey/workspace` | Resolve a live-round workspace output handle. |\n\n### Hosts\n\n| Route | Use |\n| --- | --- |\n| `GET /v1/hosts` | List owned hosts. |\n| `POST /v1/hosts` | Create a host record directly for integrator workflows that do not need the CLI to mint a local host credential. |\n| `POST /v1/hosts/setup` | Create a host and its first host-scoped credential in one transaction. Requires direct user bearer auth and returns the raw credential exactly once for CLI persistence. |\n| `GET /v1/hosts/:hostId` | Read one owned host. |\n| `PATCH /v1/hosts/:hostId` | Update safe display fields and user metadata. Runtime, adapter, path, env, image, provider, and status metadata keys are rejected. |\n| `PUT /v1/hosts/:hostId/project-workspace-root` | Store an absolute host-local Project root. The control plane stores the string and does not perform filesystem checks. |\n| `PUT /v1/hosts/:hostId/project-bindings/:projectKey` | Bind an active owned Project to one or more existing pool keys on the owned host. Body includes `poolKeys`. |\n| `GET /v1/hosts/:hostId/project-bindings` | List Project bindings for the host, including derived `workspacePath`, allowed `poolKeys`, availability, and validation reason. |\n| `POST /v1/hosts/:hostId/disable` | Disable a host. Disabled hosts cannot claim new work. |\n| `DELETE /v1/hosts/:hostId` | Delete a host only when active lifecycle state no longer blocks deletion. |\n| `GET /v1/hosts/:hostId/pools` | Read pools synced from the running host. There is no user-facing pool write route; edit host TOML and restart or reconnect the host. |\n| `GET /v1/hosts/:hostId/credentials` | List redacted host credential summaries. |\n| `GET /v1/hosts/:hostId/credentials/:hostCredentialId` | Read one redacted host credential summary. |\n| `POST /v1/hosts/:hostId/credentials/rotate` | Rotate a host credential. Requires direct user bearer auth and returns the raw replacement credential once. |\n| `POST /v1/hosts/:hostId/credentials/:hostCredentialId/revoke` | Revoke a host credential. |\n\nHost setup and credential rotation require direct user bearer auth. Do not send\nthose requests through the browser console proxy.\n\n### Sandbox Fleet\n\n| Route | Use |\n| --- | --- |\n| `GET /v1/sandboxes` | List owned fleet entries, including lifecycle status and retained sandbox liveness status when present. |\n| `GET /v1/sandboxes/:sandboxId` | Read one owned fleet entry. Missing and wrong-owner sandboxes return `404`. |\n| `DELETE /v1/sandboxes/:sandboxId` | Delete a stale owned entry immediately when no provider resource remains, or queue provider cleanup when one does. Returns `deleted`, `cleanup_queued`, `404`, or `409 sandbox_delete_blocked`. |\n| `POST /v1/sandboxes/:sandboxId/drain` | Mark an owned running entry as draining and clear unaccepted assignments. |\n| `POST /v1/sandboxes/:sandboxId/stop` | Start the stop path for an owned provider-backed entry. |\n\nDelete is intentionally owner-scoped. A stale entry can be deleted when it has\nno live sandbox stream and no accepted running work. Entries in unsafe lifecycle\nstates return `409 sandbox_delete_blocked` with displayable blockers. If the\nentry still has a provider resource, Flakes marks it `deleting` and queues\nprovider cleanup; the Console keeps the row visible as `Cleanup queued` until\nthe cleanup succeeds and the durable row is removed.\n\nImmediate delete response:\n\n```json\n{\n  \"status\": \"deleted\",\n  \"sandboxId\": \"sandbox_123\",\n  \"instanceId\": \"managed_instance_123\",\n  \"clearedAssignments\": 0\n}\n```\n\nQueued cleanup response:\n\n```json\n{\n  \"status\": \"cleanup_queued\",\n  \"sandboxId\": \"sandbox_123\",\n  \"instanceId\": \"managed_instance_123\",\n  \"clearedAssignments\": 0\n}\n```\n\n### Artifacts And Run Outputs\n\n| Route | Use |\n| --- | --- |\n| `POST /v1/artifacts` | Create artifact metadata and optional inline bytes. |\n| `GET /v1/artifacts/:artifactId` | Read artifact metadata. |\n| `GET /v1/artifacts/:artifactId/fetch` | Fetch artifact bytes. |\n| `GET /v1/runs/:runId/artifacts` | List artifacts associated with a run. |\n| `GET /v1/runs/:runId/history.jsonl` | Export redacted run history as JSONL. |\n| `GET /v1/runs/:runId/file-reservations` | List file reservations visible for the run. |\n| `GET /v1/runs/:runId/metrics` | Read evaluation metrics for the run. |\n\nSandbox-scoped workspace, group, and live-round routes are runtime surfaces for\nadapters and harness execution. Integrators should normally use the CLI,\nselected client routes, or Harness SDK helpers instead of calling those routes\ndirectly.\n\n## Relevant Exports\n\nThe hosted API and CLI are the primary user boundary. These exports are useful\nonly for integrations, harness modules, adapters, or repository-local tooling.\n\n| Export | Use |\n| --- | --- |\n| `@flakes/harness-sdk` | Harness authors import `defineHarness`, use `HarnessContext`, and call helpers such as `ctx.group(...)`, `ctx.groups.open(...)`, `ctx.output.json(...)`, `ctx.outputs.readJson(...)`, `ctx.workpads.read(...)`, `ctx.workspace.commit(...)`, `ctx.workspace.promote(...)`, and `ctx.liveTasks.send(...)`. |\n| `@flakes/core` | Integrators that build typed payloads can reuse schemas and types for run/task IDs, saved tasks, task metadata, task groups, task spawn requests, workpads, file reservations, and workspace handles. Common names include `WorkspaceHandle`, `WorkspaceHandleSchema`, `TaskProductMetadataSchema`, and `TaskWorkpadPutRequestSchema`. |\n| `@flakes/protocol` | Runtime implementers can parse and validate sandbox and host stream messages with protocol schemas and safe parse helpers. Ordinary API clients do not need these types. |\n| `@flakes/cli` | Test harnesses or wrappers can call `runCli(...)` with injected IO and transport dependencies instead of shelling out. The installed binary remains `flakes`. |\n\nDo not treat this table as a package architecture guide. It lists only the\nexports a user, harness author, or integrator might reasonably need.\n";
 var run_work_default = "---\ntitle: Running Workflows\ndescription: Launching workflows, saving tasks, admitting ready work, and closing durable workflows.\n---\n\nThis section covers the Flakes workflow for creating and launching distributed\nagent workflows. Use it after you can sign in at `https://flakes.dev/console`,\nauthorize the CLI, create a Project, and see enough connected host capacity\nbound to that Project for the adapter you want to use.\n\n## The Model\n\nA Project is the work namespace for related runs and the host workspace root\nmapping used by task execution. Every new run belongs to exactly one active\nProject. Project identity is a first-class run field, not run metadata.\n\nA run is the durable container for one job inside a Project. It holds saved\ntasks, admitted tasks, dependencies, task status, workpads, activity, artifacts,\nand history. That durable task state lives in Flakes even if an agent process\nexits, a sandbox disconnects, or a transient agent process starts again on\nanother assignment.\n\nA saved task is a draft definition inside an open run. Save tasks while you are\nstill shaping the graph: title, Markdown body, acceptance criteria, target\nadapter, dependencies, required capabilities, and any grants needed by a\nplanner or harness. Saved tasks are not schedulable yet.\n\nAdmission turns saved tasks into durable runtime work. After a task is\nadmitted, treat it as immutable user intent: do not expect to edit, delete, or\nrewire it. Add another saved task before admission, or have an authorized\nrunning task append children through its granted runtime tools.\n\nClosing a run means no more top-level saved tasks should be admitted by the\nclient. Close does not stop work that is already admitted. With `--wait`, the\nCLI waits for the run to reach a terminal state or until the timeout expires.\nIf the timeout expires, the run can still continue in the console.\n\n## Create A Run\n\nThis example uses the hosted user-auth flow. It assumes the CLI is already\ninstalled and host capacity has been connected by you or your host operator.\n\n```bash\nflakes auth login\n\nflakes projects create --key alpha --name \"Alpha\"\n\nflakes runs create --project alpha --key release-notes --name \"Draft release notes\"\n\nflakes tasks save \\\n  --run release-notes \\\n  --key draft \\\n  --title \"Draft release notes\" \\\n  --adapter pi \\\n  --body \"Read the shipped changes and draft concise release notes for users.\" \\\n  --acceptance \"Notes describe user-visible changes\" \\\n  --acceptance \"Open questions are listed at the end\" \\\n  --required-capability pi\n\nflakes tasks save \\\n  --run release-notes \\\n  --key review \\\n  --title \"Review release notes\" \\\n  --adapter pi \\\n  --body \"Review the draft for accuracy, missing risks, and unclear wording.\" \\\n  --depends-on draft \\\n  --acceptance \"Review comments are actionable\" \\\n  --required-capability pi\n\nflakes tasks admit --run release-notes --all\nflakes runs close release-notes --wait --timeout-ms 600000\n```\n\nThe first command authorizes the CLI against `https://flakes.dev`. The Project\nis created under your account. The run is created inside that Project, the two\ntasks are saved under stable keys, and the `review` task depends on `draft`.\nAdmission makes both tasks part of the durable graph. The close command tells\nFlakes there is no more top-level work to add and then waits for the graph to\nsettle.\n\n## Shape The Graph\n\nUse dependencies only for real ordering requirements. A task with unsatisfied\ndependencies is not ready, even if capacity is available. In the example above,\n`review` waits until `draft` is terminal according to the dependency policy\nbefore it can run.\n\nUse required capabilities to keep work on compatible capacity. A task that\nrequires `pi` should only be assigned to connected capacity that advertises the\n`pi` capability and the matching adapter. The run Project must also be bound to\nthe host pool. If no connected host capacity can satisfy the Project, adapter,\nand required capabilities, the task stays queued.\n\nAcceptance criteria should be short, observable checks. The agent receives the\ntask title, body, and acceptance criteria as its brief, and the console shows\nthe same user-facing context on the task page.\n\n## Scheduling\n\nFlakes schedules admitted, ready tasks to connected host capacity. A host\nadvertises sanitized pool capacity: adapter, capabilities, and concurrency,\nnot local paths, secrets, mounts, or private execution details. The scheduler\nmatches each queued task against its Project, ready dependencies, required\ncapabilities, and available concurrency.\n\nQueued work usually means one of three things:\n\n- a dependency has not finished;\n- no connected host capacity currently matches the Project binding, adapter, or\n  required capabilities;\n- matching capacity exists, but all concurrency is busy.\n\nWhen capacity appears, Flakes can assign the task to a sandbox. The task then\nmoves through running status as the sandbox accepts the assignment and starts\nthe agent process. The process and its local session are transient. The task\nrecord, status, workpad, activity, artifacts, and transcript pointers are the\ndurable state.\n\n## Dynamic Work\n\nA trusted client should use `flakes tasks save` and `flakes tasks admit` for the\ninitial graph. A running planner or harness can append children only when its\nadmitted task includes the needed grants, such as `flakes.tasks.spawn` and the\ntask-group grants documented in [Harnesses](/docs/harnesses).\n\nSpawned children are appended to the same run. They do not edit existing\naccepted tasks, and they do not inherit broad graph-editing powers unless the\nparent explicitly grants the runtime tools the workflow needs.\n\n## Close And Wait\n\nClose a run when the client has admitted all intended top-level work. Keep the\nrun open while a planner is expected to add children. Close it after the\nplanner has created the work you want the scheduler to drain.\n\n`flakes runs close RUN_KEY --wait` is useful for scripts and handoffs. It\nreturns the latest run body after the wait completes or times out, while the\nconsole remains the best place to inspect detailed task state.\n\n`WAITING` is different from queued capacity. A task in `WAITING` has yielded its\ncurrent assignment because it is waiting on durable state, such as a closed\ntask group. It is not schedulable until the wait condition is satisfied. When\nthe condition resolves, Flakes can resume the logical task from durable state\nwith a fresh assignment.\n";
 var troubleshooting_default = "---\ntitle: Troubleshooting\ndescription: Diagnose hosted-console, CLI auth, host setup, scheduling, and task input failures.\n---\n\nStart with the surface that failed: console sign-in, CLI auth, Project setup,\nhost setup, host runtime, task scheduling, or task interaction. Most failures\nare caused by a missing credential, an invalid host config, a missing Project\nbinding, no matching host capacity, or a running task that no longer has a\nconnected sandbox.\n\n## Authentication And Device Login\n\n### Device authorization does not finish\n\nSymptoms include:\n\n- `device authorization timed out`\n- `device authorization denied`\n- `device authorization expired`\n\nA browser page that no longer accepts the code is the same class of problem.\n\nRun a fresh login:\n\n```bash\nflakes auth login\n```\n\nFor remote shells, print the URL and code instead of opening a browser:\n\n```bash\nflakes auth login --no-open\n```\n\nIf approval normally takes longer than five minutes, pass a longer timeout:\n\n```bash\nflakes auth login --timeout-ms 600000\n```\n\nUse the same Flakes account in the browser that started the device request. If\nthe request was denied or expired, start over; old device codes are not\nrecoverable.\n\n### CLI commands cannot find credentials\n\nCommon error text:\n\n- `No CLI credential found`\n- `Stored CLI credential expired`\n- `Stored CLI credential has invalid expiry metadata`\n\nCheck the current status:\n\n```bash\nflakes auth status\n```\n\nThen log in again:\n\n```bash\nflakes auth login\n```\n\nIf you intentionally changed accounts, remove the old local credential first:\n\n```bash\nflakes auth logout\nflakes auth login\n```\n\n## Projects And Host Placement\n\n### Run creation fails with a Project error\n\nEvery new run requires an active Project. Common error text includes\n`runs create requires --project`, `runs create requires projectKey or\nprojectId`, `project_not_found`, or `project_archived`.\n\nCreate or choose an active Project, then create the run with `--project`:\n\n```bash\nflakes projects create --key alpha --name \"Alpha\"\nflakes runs create --project alpha --key release-notes --name \"Draft release notes\"\n```\n\nArchived Projects remain visible for history, but they cannot accept new runs\nor new host bindings. Create a new Project key for new work.\n\n### Project is not schedulable on a host\n\nIf a run exists but tasks stay queued, first confirm that the host has connected\nand advertised the pool key you want to use:\n\n```bash\nflakes host status --config <host.toml> --json\n```\n\nIf the pool key is present, bind the Project to that discovered pool:\n\n```bash\nflakes host project-root set --config <host.toml> --path /srv/flakes/projects\nflakes projects bind-host alpha --host <host-id> --pool local-pi\n```\n\nInspect binding availability in the console host placement panel or with\n`GET /v1/hosts/:hostId/project-bindings`. `flakes host status` reports host,\npool, and credential state; it does not report Project binding availability.\n\nCommon API errors:\n\n- `host_project_workspace_root_required`: set the host Project root before\n  binding a Project to that host.\n- `unknown_host_pool_keys`: bind only pool keys currently advertised by the\n  host. Start `flakes host run --config <host.toml>` and wait for the pool to\n  appear in host status or the console before retrying.\n- `project_archived`: bind only active Projects.\n\nThe control plane stores the Project root path as host metadata. The running\nhost validates the derived local Project directory, such as\n`/srv/flakes/projects/alpha`, and reports whether the binding is available.\n\n## Host Setup And Config\n\n### Host setup fails before writing files\n\n`flakes host setup` refuses to overwrite an existing config or credential file.\nMove the existing file, or pass new paths:\n\n```bash\nflakes host setup \\\n  --config <host.toml> \\\n  --credential-file <host.credential> \\\n  --state-dir <host-state>\n```\n\nThe config path, credential file path, and state directory must be distinct.\nThey cannot point at the same file or nest inside each other in a way that\nmakes setup ambiguous.\n\n### Host setup request fails\n\nCommon error text includes `host setup failed with HTTP ...`,\n`host setup requires direct user bearer auth`,\n`direct_user_auth_required`, or `host_credentials_not_configured`.\n\nRecover by checking these items:\n\n- Run `flakes auth status`; if it is not\n  authenticated, run `flakes auth login`.\n- Run setup directly from the CLI. The setup request requires direct user bearer\n  auth and should not be sent through the browser console proxy.\n- If setup failed after the server created a credential but before local files\n  were written, the CLI attempts to revoke that newly created credential. Remove\n  partial local files and rerun setup.\n\n### Host config is invalid\n\n`flakes host status --config <host.toml>` reports `host config is invalid` when\nthe runtime cannot load or validate the config. The most common causes are:\n\n- `controlPlaneUrl` is missing, malformed, or uses plaintext HTTP. Host control\n  URLs must use HTTPS.\n- `hostId` is missing or not a valid identifier.\n- `credentialFile` is missing, is not absolute, is a symlink, is not owned by\n  the current user, or `credentialFile must have 0600 permissions`.\n- `stateDir` is not an absolute private directory.\n- `at least one pool is required`.\n- `workspace` appears inside a `[[pools]]` entry. Remove it, set the host\n  Project root with `flakes host project-root set`, and bind Projects with\n  `flakes projects bind-host`.\n- `executablePaths.matchlock` is missing, is not absolute, is a symlink, or is\n  not executable.\n- `maxInstances` or `maxConcurrency` is not a positive integer.\n\nValidate the local and remote view:\n\n```bash\nflakes host status --config <host.toml> --json\n```\n\nIf local validation passes but remote status is not checked, the hosted CLI user\ncredential is missing or expired. Run `flakes auth status`, then re-run\n`flakes auth login` if needed. Remote host status uses the hosted control plane\nand the `hostId` from the local config.\n\n### Host rotation succeeds but work does not launch\n\n`flakes host rotate --config <host.toml>` writes a new host credential and\nretires the replaced credential. Restart the host process after rotation:\n\n```bash\nflakes host rotate --config <host.toml>\nflakes host run --config <host.toml>\n```\n\nOld active streams cannot claim new launch work after the replaced credential\nis retired. A restart makes the host reconnect with the new credential.\n\n## Scheduling And Runtime\n\n### No matching host capacity\n\nIf the console shows `No matching host capacity` or tasks stay `queued`, compare\nthe task requirements with the connected host pools:\n\n```bash\nflakes host status --config <host.toml> --json\n```\n\nCheck:\n\n- The host is `online`, not `offline` or `disabled`.\n- The run was created with the expected Project, such as\n  `flakes runs create --project alpha --key <run-key> --name <name>`.\n- Host status or the console shows the expected pool key from the running host.\n- The console host placement panel or\n  `GET /v1/hosts/:hostId/project-bindings` shows the Project bound to this host\n  with at least one allowed pool.\n- The host has a configured Project root and the derived Project directory\n  exists locally.\n- At least one pool advertises the task adapter, such as `pi` or `harness`.\n- The pool advertises every `--required-capability` used by the task.\n- The pool is not already at its `maxInstances` or `maxConcurrency` limit.\n- `flakes host run --config <host.toml>` is still running.\n- A sandbox has connected back and become schedulable after startup.\n\nSaved tasks do not run until they are admitted. If a task is only saved, run:\n\n```bash\nflakes tasks admit --run <run-key> <task-key>\n```\n\n### Queued tasks do not start\n\nA queued task is waiting for prerequisites. Common causes:\n\n- The run has saved tasks that were never admitted.\n- The task depends on another task that has not finished successfully.\n- The task requests capabilities that no online pool advertises.\n- The run was closed after admission but no matching capacity is available.\n- The host process exited or lost connectivity.\n\nUse the run and task views in the console first. From the CLI, inspect the run\nor task and read logs for a running task:\n\n```bash\nflakes inspect <run-id-or-key>\nflakes inspect <task-id> --task\nflakes logs <task-id>\n```\n\n### Offline sandboxes block messages or permissions\n\nWhen a task interaction returns `sandbox_offline` or `task sandbox is not\nconnected`, the task record still points at a sandbox but the sandbox stream is\nnot connected.\n\nRecover by:\n\n- Checking whether the host is still running.\n- Reading host status and pool status with `flakes host status --config\n  <host.toml> --json`.\n- Restarting `flakes host run --config <host.toml>` if the process exited.\n- Waiting for the scheduler to retry if the task is retryable.\n- Creating follow-up work in a new task if the original task reached a\n  terminal state.\n\n## Task Input And Permissions\n\n### Follow-up or steer input is rejected\n\nThe task messages API accepts only running tasks on connected sandboxes.\nMessages must be non-empty, at most 20000 characters, and use mode `follow_up`\nor `steer`.\n\nIf the console input box is disabled, check the task state:\n\n- `queued`: wait for capacity or fix host matching.\n- `running`: the task can receive input only while its sandbox is connected.\n- `waiting`: the task is waiting on durable workflow state; use the harness or\n  wait condition instead of sending arbitrary input.\n- terminal states: create follow-up work in a new task or run.\n\n### Permission prompt cannot be answered\n\nPermission responses require a running task, a connected sandbox, and an\nunanswered request that still belongs to the active assignment.\n\nCommon API errors:\n\n- `permission_already_responded`: someone already answered this request. Read\n  task activity for the accepted response.\n- `permission_stale_assignment`: the request belonged to older work and cannot\n  be answered for the current assignment.\n- `task_not_running`: the task is no longer running on an active sandbox.\n- `sandbox_offline`: the task sandbox is not connected.\n\nUse the console prompt when it is visible. If no prompt is visible but activity\nshows `permission.requested`, answer through the integration that owns the\nprompt or wait for the task to fail and create follow-up work.\n\n### Workpad save conflicts\n\n`workpad_version_conflict` means another user or agent saved a newer workpad\nafter your base version. Pull or read the latest workpad, merge your changes,\nand save again with the latest version:\n\n```bash\nflakes tasks workpad show <task-id>\nflakes tasks workpad save <task-id> --file <workpad.md> --base-version <latest-version>\n```\n\nInside a running task, `flakes tasks workpad push` writes the latest conflicting\nbody and version to `workpad.current.md` and `workpad.current.version`. Merge\nthose changes before retrying.\n";
 var meta_default$1 = {

package/dist/node_modules/@flakes/console/.output/server/_ssr/{documentation-C69e9_eF.mjs → documentation-Cgyr3VKK.mjs}

@@ -1,8 +1,8 @@
 import { c as require_jsx_runtime } from "../_libs/@radix-ui/react-arrow+[...].mjs";
 import { i as useLocation, s as Outlet } from "../_libs/@tanstack/react-router+[...].mjs";
-import { t as defaultDocumentationPath } from "./documentation-C91gfyy0.mjs";
-import { t as DocumentationPage } from "./DocumentationPage-0I9oWWJT.mjs";
-//#region node_modules/.nitro/vite/services/ssr/assets/documentation-C69e9_eF.js
+import { t as defaultDocumentationPath } from "./documentation-BnxmM-Yo.mjs";
+import { t as DocumentationPage } from "./DocumentationPage-BR2KosFz.mjs";
+//#region node_modules/.nitro/vite/services/ssr/assets/documentation-Cgyr3VKK.js
 var import_jsx_runtime = require_jsx_runtime();
 function DocumentationRouteComponent() {
 	if (trimTrailingSlash(useLocation().pathname) !== "/documentation") return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Outlet, {});

package/dist/node_modules/@flakes/console/.output/server/_ssr/{hooks-DrgN35zn.mjs → hooks-CsVtQ1m-.mjs}

@@ -1,54 +1,7 @@
 import { i as getServerFnById, n as createServerFn, t as TSS_SERVER_FUNCTION } from "./ssr.mjs";
 import { n as normalizeConsolePath } from "./paths-AqD9h5Fe.mjs";
 import { i as useQuery, n as useMutation, o as useQueryClient, t as useInfiniteQuery } from "../_libs/tanstack__react-query.mjs";
-//#region node_modules/.nitro/vite/services/ssr/assets/hooks-DrgN35zn.js
-function hostProjectWorkspaceRootPath(hostId) {
-	return `/v1/hosts/${encodeURIComponent(hostId)}/project-workspace-root`;
-}
-function hostProjectBindingsPath(hostId) {
-	return `/v1/hosts/${encodeURIComponent(hostId)}/project-bindings`;
-}
-function hostProjectBindingPath(hostId, projectKey) {
-	return `${hostProjectBindingsPath(hostId)}/${encodeURIComponent(projectKey)}`;
-}
-function hostProjectWorkspacePath(projectWorkspaceRoot, projectKey) {
-	const separator = projectWorkspaceRoot.includes("\\") && !projectWorkspaceRoot.includes("/") ? "\\" : "/";
-	return projectWorkspaceRoot.endsWith("/") || projectWorkspaceRoot.endsWith("\\") ? `${projectWorkspaceRoot}${projectKey}` : `${projectWorkspaceRoot}${separator}${projectKey}`;
-}
-function bindingValidationView(binding) {
-	if (binding === void 0) return {
-		tone: "idle",
-		label: "Not bound",
-		detail: "No host binding has been saved for this project."
-	};
-	if (binding.availability === "available") return {
-		tone: "available",
-		label: "Available",
-		detail: `Validated ${binding.lastValidatedAt ?? binding.updatedAt}.`
-	};
-	if (binding.availability === "unavailable") return {
-		tone: "unavailable",
-		label: "Unavailable",
-		detail: binding.validationReason ?? `Last rejected ${binding.lastValidatedAt ?? binding.updatedAt}.`
-	};
-	return {
-		tone: "pending",
-		label: "Pending validation",
-		detail: "Waiting for the host runtime to validate this binding."
-	};
-}
-function poolChoicesForBinding(pools, binding) {
-	const selected = new Set(binding?.poolKeys ?? []);
-	return pools.map((pool) => {
-		const status = pool.status ?? "available";
-		return {
-			poolKey: pool.poolKey,
-			selected: selected.has(pool.poolKey),
-			status,
-			statusLabel: status
-		};
-	});
-}
+//#region node_modules/.nitro/vite/services/ssr/assets/hooks-CsVtQ1m-.js
 var createSsrRpc = (functionId, importer) => {
 	const url = "/console/_serverFn/" + functionId;
 	const serverFnMeta = { id: functionId };
@@ -146,8 +99,8 @@ async function apiError(response, path) {
 	let message = `${path} failed (${response.status})`;
 	try {
 		details = await response.clone().json();
-		if (isRecord(details) && typeof details.message === "string") message = details.message;
-		else if (isRecord(details) && typeof details.error === "string") message = details.error;
+		if (isRecord$1(details) && typeof details.message === "string") message = details.message;
+		else if (isRecord$1(details) && typeof details.error === "string") message = details.error;
 	} catch {
 		try {
 			const text = await response.clone().text();
@@ -162,9 +115,104 @@ function unwrapResult(result) {
 	if (result.status === 404) throw new NotFoundError(result.message);
 	throw new ApiError(result.message, result.status, result.details);
 }
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null;
+}
+var deletableStatuses = new Set([
+	"running",
+	"draining",
+	"stopping",
+	"stopped",
+	"failed",
+	"expired",
+	"cancelled"
+]);
+var blockerText = {
+	unsafe_status: "sandbox is not in a stale lifecycle state",
+	live_sandbox: "sandbox is live",
+	accepted_running_assignments: "sandbox has accepted running assignments",
+	provider_cleanup_required: "provider cleanup is required"
+};
+function canRequestManagedSandboxDelete(sandbox) {
+	return sandbox.sandboxStatus !== "active" && deletableStatuses.has(sandbox.status);
+}
+function managedSandboxDeleteAction(sandbox, pending, confirming) {
+	if (pending) return "pending";
+	if (!canRequestManagedSandboxDelete(sandbox)) return "hidden";
+	return confirming ? "confirm" : "request";
+}
+function applyManagedSandboxDeleteResult(sandboxes, result) {
+	if (result.status === "deleted") return sandboxes.filter((sandbox) => sandbox.sandboxId !== result.sandboxId);
+	return sandboxes.map((sandbox) => sandbox.sandboxId === result.sandboxId ? {
+		...sandbox,
+		status: "deleting"
+	} : sandbox);
+}
+function managedSandboxDeleteErrorMessage(error) {
+	if (error instanceof NotFoundError) return "Sandbox is unavailable or already deleted.";
+	if (error instanceof ApiError && error.status === 409) {
+		const blockers = deleteBlockers(error.details);
+		if (blockers.length > 0) return `Delete blocked: ${blockers.map(blockerMessage).join("; ")}.`;
+	}
+	return error instanceof Error ? error.message : "Failed to delete sandbox.";
+}
+function deleteBlockers(details) {
+	if (!isRecord(details) || !Array.isArray(details.blockers)) return [];
+	return details.blockers.filter((blocker) => typeof blocker === "string");
+}
+function blockerMessage(blocker) {
+	return blockerText[blocker] ?? blocker.replaceAll("_", " ");
+}
 function isRecord(value) {
 	return typeof value === "object" && value !== null;
 }
+function hostProjectWorkspaceRootPath(hostId) {
+	return `/v1/hosts/${encodeURIComponent(hostId)}/project-workspace-root`;
+}
+function hostProjectBindingsPath(hostId) {
+	return `/v1/hosts/${encodeURIComponent(hostId)}/project-bindings`;
+}
+function hostProjectBindingPath(hostId, projectKey) {
+	return `${hostProjectBindingsPath(hostId)}/${encodeURIComponent(projectKey)}`;
+}
+function hostProjectWorkspacePath(projectWorkspaceRoot, projectKey) {
+	const separator = projectWorkspaceRoot.includes("\\") && !projectWorkspaceRoot.includes("/") ? "\\" : "/";
+	return projectWorkspaceRoot.endsWith("/") || projectWorkspaceRoot.endsWith("\\") ? `${projectWorkspaceRoot}${projectKey}` : `${projectWorkspaceRoot}${separator}${projectKey}`;
+}
+function bindingValidationView(binding) {
+	if (binding === void 0) return {
+		tone: "idle",
+		label: "Not bound",
+		detail: "No host binding has been saved for this project."
+	};
+	if (binding.availability === "available") return {
+		tone: "available",
+		label: "Available",
+		detail: `Validated ${binding.lastValidatedAt ?? binding.updatedAt}.`
+	};
+	if (binding.availability === "unavailable") return {
+		tone: "unavailable",
+		label: "Unavailable",
+		detail: binding.validationReason ?? `Last rejected ${binding.lastValidatedAt ?? binding.updatedAt}.`
+	};
+	return {
+		tone: "pending",
+		label: "Pending validation",
+		detail: "Waiting for the host runtime to validate this binding."
+	};
+}
+function poolChoicesForBinding(pools, binding) {
+	const selected = new Set(binding?.poolKeys ?? []);
+	return pools.map((pool) => {
+		const status = pool.status ?? "available";
+		return {
+			poolKey: pool.poolKey,
+			selected: selected.has(pool.poolKey),
+			status,
+			statusLabel: status
+		};
+	});
+}
 var POLL_MS = 1e3;
 function useRuns(input) {
 	const state = typeof input === "string" ? input : input?.state;
@@ -211,6 +259,24 @@ function useHostPools(hostId) {
 		refetchInterval: POLL_MS
 	});
 }
+function useSandboxFleet() {
+	return useQuery({
+		queryKey: ["sandbox-fleet"],
+		queryFn: () => apiGet("/v1/sandboxes"),
+		refetchInterval: POLL_MS
+	});
+}
+function useDeleteManagedSandbox() {
+	const queryClient = useQueryClient();
+	return useMutation({
+		mutationFn: (sandboxId) => apiDelete(`/v1/sandboxes/${encodeURIComponent(sandboxId)}`),
+		onSuccess: async (result) => {
+			queryClient.setQueryData(["sandbox-fleet"], (current) => current ? { sandboxes: applyManagedSandboxDeleteResult(current.sandboxes, result) } : current);
+			if (result.status === "deleted") queryClient.removeQueries({ queryKey: ["managed-sandbox", result.sandboxId] });
+			await Promise.all([queryClient.invalidateQueries({ queryKey: ["sandbox-fleet"] }), queryClient.invalidateQueries({ queryKey: ["managed-sandbox", result.sandboxId] })]);
+		}
+	});
+}
 function useHostProjectBindings(hostId, enabled = true) {
 	return useQuery({
 		queryKey: ["host-project-bindings", hostId],
@@ -374,4 +440,4 @@ function requireHostId(hostId, hookName) {
 	return hostId;
 }
 //#endregion
-export { useTaskWorkpad as C, useTaskPiSessionRaw as S, useSaveTaskWorkpad as _, poolChoicesForBinding as a, useTaskActivity as b, useHostProjectBindings as c, useRun as d, useRunArtifacts as f, useRuns as g, useRunTasks as h, hostProjectWorkspacePath as i, useHosts as l, useRunMetrics as m, bindingValidationView as n, useDeleteRun as o, useRunFileReservations as p, downloadFile as r, useHostPools as s, ApiError as t, useProjects as u, useSendTaskMessage as v, useUpsertHostProjectBinding as w, useTaskPiSession as x, useSetHostProjectWorkspaceRoot as y };
+export { useSetHostProjectWorkspaceRoot as C, useTaskWorkpad as D, useTaskPiSessionRaw as E, useUpsertHostProjectBinding as O, useSendTaskMessage as S, useTaskPiSession as T, useRunMetrics as _, managedSandboxDeleteAction as a, useSandboxFleet as b, useDeleteManagedSandbox as c, useHostProjectBindings as d, useHosts as f, useRunFileReservations as g, useRunArtifacts as h, hostProjectWorkspacePath as i, useDeleteRun as l, useRun as m, bindingValidationView as n, managedSandboxDeleteErrorMessage as o, useProjects as p, downloadFile as r, poolChoicesForBinding as s, ApiError as t, useHostPools as u, useRunTasks as v, useTaskActivity as w, useSaveTaskWorkpad as x, useRuns as y };

package/dist/node_modules/@flakes/console/.output/server/_ssr/{projects-lJ2tIIPj.mjs → projects-R9sxR_t4.mjs}

@@ -1,5 +1,5 @@
 import { o as __toESM } from "../_runtime.mjs";
 import { u as require_react } from "../_libs/@floating-ui/react-dom+[...].mjs";
-var ProjectsPage = (0, (/* @__PURE__ */ __toESM(require_react())).lazy)(() => import("./ProjectsPage-CGj9V2Of.mjs").then((module) => ({ default: module.ProjectsPage })));
+var ProjectsPage = (0, (/* @__PURE__ */ __toESM(require_react())).lazy)(() => import("./ProjectsPage-BUrep1wl.mjs").then((module) => ({ default: module.ProjectsPage })));
 //#endregion
 export { ProjectsPage as component };

package/dist/node_modules/@flakes/console/.output/server/_ssr/{router-DHxFQ03L.mjs → router-CobdI6gO.mjs}

@@ -5,25 +5,25 @@ import { u as require_react } from "../_libs/@floating-ui/react-dom+[...].mjs";
 import { t as QueryClient } from "../_libs/tanstack__query-core.mjs";
 import { a as QueryClientProvider } from "../_libs/tanstack__react-query.mjs";
 import { D as LoaderCircle } from "../_libs/lucide-react.mjs";
-import { a as getDocumentationPage, s as normalizeDocumentationPath, t as defaultDocumentationPath } from "./documentation-C91gfyy0.mjs";
-import { t as Route } from "../_-_ST9QYWn.mjs";
-import { t as Route$10 } from "../_runId-WZmbo654.mjs";
-import { t as Route$11 } from "../_taskId-CBo95z-s.mjs";
+import { a as getDocumentationPage, s as normalizeDocumentationPath, t as defaultDocumentationPath } from "./documentation-BnxmM-Yo.mjs";
+import { t as Route } from "../_-DtPMXzt0.mjs";
+import { t as Route$10 } from "../_runId-P1u-vfcm.mjs";
+import { t as Route$11 } from "../_taskId-Cz9xwj5L.mjs";
 import { o as initTheme } from "./auth-redirect-BI2bC7qX.mjs";
-import { t as App } from "./App-CUx8Ftit.mjs";
+import { t as App } from "./App-C-XaVKoO.mjs";
 import { t as Route$12 } from "./device-DqXiEFpN.mjs";
 import { t as Route$13 } from "./forgot-password-SqIDRm9P.mjs";
 import { t as Route$14 } from "./reset-password-DEWN29hA.mjs";
 import { t as authRouteHandlers } from "../_chunks/auth-Dx90FyZz.mjs";
 import { t as Route$15 } from "./signup-nYA7O7Q8.mjs";
 import { t as Route$16 } from "./signin-BQPwlbp1.mjs";
-import { t as Route$17 } from "./sandboxes-v28LJQM3.mjs";
-import { t as Route$18 } from "./runs-dnPfp9dt.mjs";
-//#region node_modules/.nitro/vite/services/ssr/assets/router-DHxFQ03L.js
+import { t as Route$17 } from "./sandboxes-B2z_9JyU.mjs";
+import { t as Route$18 } from "./runs-D8MHe3QU.mjs";
+//#region node_modules/.nitro/vite/services/ssr/assets/router-CobdI6gO.js
 var import_jsx_runtime = require_jsx_runtime();
 var import_react = /* @__PURE__ */ __toESM(require_react());
 var favicon_default = "data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2024%2024'%20fill='none'%3e%3ctitle%3eFlakes%3c/title%3e%3cdefs%3e%3ccircle%20id='n'%20cx='12'%20cy='4.2'%20r='1.9'%20fill='%2310b981'/%3e%3c/defs%3e%3cuse%20href='%23n'/%3e%3cuse%20href='%23n'%20transform='rotate(60%2012%2012)'/%3e%3cuse%20href='%23n'%20transform='rotate(120%2012%2012)'/%3e%3cuse%20href='%23n'%20transform='rotate(180%2012%2012)'/%3e%3cuse%20href='%23n'%20transform='rotate(240%2012%2012)'/%3e%3cuse%20href='%23n'%20transform='rotate(300%2012%2012)'/%3e%3ccircle%20cx='12'%20cy='12'%20r='2.4'%20fill='%2310b981'/%3e%3c/svg%3e";
-var styles_default = "/console/assets/styles-DtA2wbW8.css";
+var styles_default = "/console/assets/styles-B8OXOvkO.css";
 var Route$9 = createRootRoute({
 	head: () => ({
 		meta: [
@@ -83,9 +83,9 @@ function createConsoleQueryClient() {
 		refetchIntervalInBackground: true
 	} } });
 }
-var $$splitComponentImporter$3 = () => import("./projects-lJ2tIIPj.mjs");
+var $$splitComponentImporter$3 = () => import("./projects-R9sxR_t4.mjs");
 var Route$8 = createFileRoute("/projects")({ component: lazyRouteComponent($$splitComponentImporter$3, "component") });
-var $$splitComponentImporter$2 = () => import("./documentation-C69e9_eF.mjs");
+var $$splitComponentImporter$2 = () => import("./documentation-Cgyr3VKK.mjs");
 var Route$7 = createFileRoute("/documentation")({
 	validateSearch: (search) => typeof search.doc === "string" ? { doc: search.doc } : {},
 	beforeLoad: ({ search }) => {
@@ -115,7 +115,7 @@ var Route$5 = createFileRoute("/")({ beforeLoad: () => {
 		replace: true
 	});
 } });
-var $$splitComponentImporter$1 = () => import("./account-D5y9vkAc.mjs");
+var $$splitComponentImporter$1 = () => import("./account-Cp0s_IQK.mjs");
 var Route$4 = createFileRoute("/account/")({ component: lazyRouteComponent($$splitComponentImporter$1, "component") });
 var Route$3 = createFileRoute("/api/download")({ server: { handlers: { GET: async ({ request }) => {
 	const url = new URL(request.url);

package/dist/node_modules/@flakes/console/.output/server/_ssr/{runs-dnPfp9dt.mjs → runs-D8MHe3QU.mjs}

@@ -1,6 +1,6 @@
 import { c as lazyRouteComponent, l as createFileRoute } from "../_libs/@tanstack/react-router+[...].mjs";
-//#region node_modules/.nitro/vite/services/ssr/assets/runs-dnPfp9dt.js
-var $$splitComponentImporter = () => import("./runs-BWxEGKO_.mjs");
+//#region node_modules/.nitro/vite/services/ssr/assets/runs-D8MHe3QU.js
+var $$splitComponentImporter = () => import("./runs-mTxbc_pm.mjs");
 var Route = createFileRoute("/runs")({
 	validateSearch: (search) => {
 		const state = search.state;

package/dist/node_modules/@flakes/console/.output/server/_ssr/{runs-BWxEGKO_.mjs → runs-mTxbc_pm.mjs}

@@ -2,10 +2,10 @@ import { o as __toESM } from "../_runtime.mjs";
 import { c as require_jsx_runtime } from "../_libs/@radix-ui/react-arrow+[...].mjs";
 import { f as useNavigate, i as useLocation, s as Outlet } from "../_libs/@tanstack/react-router+[...].mjs";
 import { u as require_react } from "../_libs/@floating-ui/react-dom+[...].mjs";
-import { t as Route } from "./runs-dnPfp9dt.mjs";
-//#region node_modules/.nitro/vite/services/ssr/assets/runs-BWxEGKO_.js
+import { t as Route } from "./runs-D8MHe3QU.mjs";
+//#region node_modules/.nitro/vite/services/ssr/assets/runs-mTxbc_pm.js
 var import_jsx_runtime = require_jsx_runtime();
-var RunsPage = (0, (/* @__PURE__ */ __toESM(require_react())).lazy)(() => import("./RunsPage-BifKogQE.mjs").then((module) => ({ default: module.RunsPage })));
+var RunsPage = (0, (/* @__PURE__ */ __toESM(require_react())).lazy)(() => import("./RunsPage-iTNYVwL0.mjs").then((module) => ({ default: module.RunsPage })));
 function RunsRouteComponent() {
 	const { project, state } = Route.useSearch();
 	const location = useLocation();

package/dist/node_modules/@flakes/console/.output/server/_ssr/{sandboxes-v28LJQM3.mjs → sandboxes-B2z_9JyU.mjs}

@@ -1,6 +1,6 @@
 import { c as lazyRouteComponent, l as createFileRoute } from "../_libs/@tanstack/react-router+[...].mjs";
-//#region node_modules/.nitro/vite/services/ssr/assets/sandboxes-v28LJQM3.js
-var $$splitComponentImporter = () => import("./sandboxes-hxFINxDS.mjs");
+//#region node_modules/.nitro/vite/services/ssr/assets/sandboxes-B2z_9JyU.js
+var $$splitComponentImporter = () => import("./sandboxes-r0y6Ihg6.mjs");
 var Route = createFileRoute("/sandboxes")({
 	validateSearch: (search) => ({ runId: typeof search.runId === "string" ? search.runId : void 0 }),
 	component: lazyRouteComponent($$splitComponentImporter, "component")

package/dist/node_modules/@flakes/console/.output/server/_ssr/{sandboxes-hxFINxDS.mjs → sandboxes-r0y6Ihg6.mjs}

@@ -2,10 +2,10 @@ import { o as __toESM } from "../_runtime.mjs";
 import { c as require_jsx_runtime } from "../_libs/@radix-ui/react-arrow+[...].mjs";
 import { f as useNavigate } from "../_libs/@tanstack/react-router+[...].mjs";
 import { u as require_react } from "../_libs/@floating-ui/react-dom+[...].mjs";
-import { t as Route } from "./sandboxes-v28LJQM3.mjs";
-//#region node_modules/.nitro/vite/services/ssr/assets/sandboxes-hxFINxDS.js
+import { t as Route } from "./sandboxes-B2z_9JyU.mjs";
+//#region node_modules/.nitro/vite/services/ssr/assets/sandboxes-r0y6Ihg6.js
 var import_jsx_runtime = require_jsx_runtime();
-var SandboxesPage = (0, (/* @__PURE__ */ __toESM(require_react())).lazy)(() => import("./SandboxesPage-DGji_OdB.mjs").then((module) => ({ default: module.SandboxesPage })));
+var SandboxesPage = (0, (/* @__PURE__ */ __toESM(require_react())).lazy)(() => import("./SandboxesPage-C1Z6dVce.mjs").then((module) => ({ default: module.SandboxesPage })));
 function SandboxesRouteComponent() {
 	const { runId } = Route.useSearch();
 	const navigate = useNavigate();

package/dist/node_modules/@flakes/console/.output/server/_ssr/ssr.mjs

@@ -3819,7 +3819,7 @@ function getResponse() {
 	return getH3Event().res;
 }
 async function getStartManifest(matchedRoutes) {
-	const { tsrStartManifest } = await import("../_tanstack-start-manifest_v-DfwuEzTr.mjs");
+	const { tsrStartManifest } = await import("../_tanstack-start-manifest_v-DpAwCFK9.mjs");
 	const startManifest = tsrStartManifest();
 	const rootRoute = startManifest.routes[rootRouteId] = startManifest.routes["__root__"] || {};
 	rootRoute.assets = rootRoute.assets || [];
@@ -4276,7 +4276,7 @@ var entriesPromise;
 var baseManifestPromise;
 var cachedFinalManifestPromise;
 async function loadEntries() {
-	const routerEntry = await import("./router-DHxFQ03L.mjs");
+	const routerEntry = await import("./router-CobdI6gO.mjs");
 	return {
 		startEntry: await import("./start-rVEVzFV_.mjs"),
 		routerEntry