# Meshia operating guide

Read only the sections needed for the approved task. Connection setup is at https://meshia.io/docs/agent-setup. The owner's agent remains the conductor. Follow their scope, host policies and existing authorizations; this guide does not grant access or spend permission.

## The installed experience

Meshia installs as one package per OS; the single installer and `meshia setup` are described at https://meshia.io/docs/agent-setup. Setup signs in once, connects this computer (files by default), writes the client's MCP entry and keeps everything updated. Rerun `meshia setup` to repair; it reuses sign-in, enrollment and grants. A workspace's generated attach command installs the same package and enrolls the device with no separate login or pairing-code prompt. Use `meshia status` for local account and mount state, `meshia account` to verify the account live and `meshia projects` to list projects. `meshia mount <workspace-id>` connects native files through the same installation. Device enrollment and user OAuth remain separate credentials: remote workspace tools must never receive the owner's account token.

`meshia setup --agent <client>` writes the stdio entry for claude, codex, cursor, claude-desktop, windsurf or gemini. For other desktop clients, `meshia mcp config` prints the same absolute executable configuration without tokens; it starts `meshia mcp serve`. Do not rewrite unrelated client configuration. Clients that cannot run local commands use the remote HTTP/OAuth endpoint below.

## Conversation and project continuity

For remote calls, use the selected project's returned `id` as `workspace_id`. In local `meshia --json status`, use `mcp_workspace_id`; the legacy `workspace_id` is a private filesystem-claim UUID, not a remote project ID. For a non-interactive Codex job that requires Meshia, add `-c 'mcp_servers.meshia.required=true'` to that `codex exec` invocation so MCP startup fails closed. Preserve host-native confirmations; never weaken tool annotations or bypass a refusal under `approval_policy=never`.

1. List projects and reuse the intended workspace. List `meshia_threads_list` and read the selected thread before continuing; do not mix unrelated host conversations in one thread.
2. After the owner has approved this conversation and whether tool records are included, save the user-visible conversation with `meshia_conversation_sync`: stable UUIDs, ordered user/assistant/tool messages, batches of at most 20. Include the owner's request, decisions, your replies and relevant tool results. Preserve the same IDs when resuming a partial sync. The tool returns exactly which messages were saved and which append is uncertain. Never sync private system/developer instructions, hidden reasoning, credentials, or unrelated chat history.
3. For Codex, install the integrated adapter with `meshia host install codex`, restart and accept host hook trust, then, only with approval of this conversation and its saved scope, link the selected conversation with `meshia host link <workspace-id> --session <Codex UUID> --include-tools`. Hooks automatically save visible conversation and tool records with durable resume. Omit --include-tools for text only. Use `meshia host status` to inspect progress. Do not also manually mirror messages when automatic sync is active. Other MCP hosts must explicitly export conversation via `meshia_conversation_sync` or `meshia sync`; never claim a full archive without that host integration.
4. Use `meshia_agent_turn` to ask the driving agent. Default `mode: "send"` waits behind a running runtime turn; it does not steer that turn. For an instruction needed during current work, explicitly use `mode: "steer"` with the intended `thread_id`. Steering enters at the runtime's next boundary, starts a turn if idle, and waits for the runtime during boot. `accepted: true` confirms durable acceptance only; `queue_status: "injected"` or `"sent"` and `delivery_complete: true` confirm delivery. Reuse a `client_message_id` only for the same content and mode; an uncertain response is not permission to enqueue a duplicate. Conversation persistence can lag, so inspect the exact queue receipt before resending. Use `meshia_swarm_run_create` for remote workers; a conversation thread alone does not start a worker. Independent workers can run concurrently; dependent work must follow completed inputs.
5. For ChatGPT Work with Cloud selected or dots, use MCP Events on the authenticated HTTP endpoint: discover with protocol `2026-07-28`, list events, and subscribe to `chat.finished`, `chat.idle`, `command.completed` or `command.failed` with `workspace_id` and an optional `thread_id` or `command_id`. The client supplies its HTTPS callback and signing secret; never ask the owner for these in chat. Subscriptions default to 24 hours, grant at most 7 days, and must refresh before `refreshBefore`. Delivery is durable, normally within one minute, with bounded retries and no replay cursor. Treat callbacks as receipts to read the authenticated workspace, preserve existing permissions, and stay quiet on non-actionable changes. For other clients, use `meshia_project_updates` with its returned cursor and `wait_seconds: 25`. Linked Codex conversations get native queued callbacks for 60 minutes by default, renewed with `meshia host renew --session <UUID> --watch-minutes 240`; unlink to stop. Other stdio clients can subscribe to `meshia://projects/<workspace-id>`; their notification support determines wake behavior.
6. Updates are bounded recent snapshots, not a lossless event stream. After a long disconnect, paginate `meshia_messages_list` and inspect individual runs before concluding that nothing happened. Remote work remains owned by Meshia when the client closes. Detaching a watch is not cancellation.
7. Present a small project receipt: workspace link, current phase, active workers, latest meaningful result, required user action, and saved-context scope. Prefer a compact receipt over dumping telemetry. Open artifacts in the host's existing file/browser preview when it supports them.

## Connected computers and custom apps

Use `meshia_connected_hosts_list` with `scope=account` to discover the owner's already-online computers. These are distinct from rented Meshia runtimes. Account credentials provide access to workspace mounts by default, without granting compute. To run research on a computer, the owner chooses **Workspace only** (`access_mode=limited`, `execution_scope=workspace`) or **Full computer access** (`access_mode=full`, `execution_scope=host`). Both modes run real native compute. Call `meshia_connected_host_attach` with the returned device id, generation, and accessRevision as host_id, generation, and expected_revision, plus the chosen mode and execution scope. An online device needs no new install command. If the response is uncertain, read `scope=workspace` to confirm the actual attachment mode, execution scope and revision before making another change.

Check `executionAvailable` and `executionDetail` before attaching compute. Workspace only additionally requires `workspaceExecutionAvailable`: it runs native programs with network access and installed runtimes/libraries, while the OS blocks personal files such as Desktop and Downloads and restricts writes to the workspace. Both access modes have native implementations on macOS, Linux and Windows; the device's measured readiness is authoritative. macOS compute requires 14.2 or later and the installer-provided native app. Linux workspace isolation requires bubblewrap, usable namespaces and Landlock ABI 6; Linux full access does not require Landlock. Windows workspace isolation uses a less privileged AppContainer and a private view of the selected workspace. macOS workspace only blocks host-named shared memory and semaphores; Linux provides private shared memory for Python and PyTorch workers. Full computer access runs as the installing OS user, using host files, installed programs, networking and available hardware. Neither mode needs Docker, a container image, or a fixed CPU/memory allocation. GPU/MPS workloads use the computer's installed drivers and libraries. Existing files-only or historical workspace execution grants require a new owner-approved compute choice; an upgrade never silently widens permission. `meshia compute status` reports native readiness.

`meshia_connected_hosts_list` with `scope=workspace` includes each host's `telemetry.latest` and up to 60 history samples over five minutes: whole-computer CPU percent and RAM bytes, plus separate measured GPU counters, updated about every five seconds; respect `telemetry.status` (`live`, `stale`, or `unavailable`) and treat null counters as unknown.

For a new device, `meshia_connected_host_connect` returns a copy-and-run command for Files. For Workspace only or Full computer access it returns `approval_url`: give the owner that link; they review the computer's exact access in Meshia, approve it and run the command shown there. The owner runs it on the intended computer. Native driver installation or first access can require an OS administrator/privacy prompt; there is no custom setup window. Signing and notarization are publisher steps. Never copy a pairing grant into logs or saved conversation context.

For either compute mode, use `meshia_connected_host_command_run` with an argv array. Workspace only requires a cwd relative to the shared workspace. Full computer access also permits an absolute host cwd and uses the installing user’s real HOME. Omitted cwd selects the shared workspace. Reuse the idempotency key after an uncertain response and poll `meshia_connected_host_command_get` to a terminal result. Trying a different command cannot widen access; a changed permission needs the owner-approved attachment update. Returning to `access_mode=files` cancels queued and running commands while keeping ordinary workspace mounts. Full access uses ordinary OS permissions, including any OS privacy prompts or administrator requirements. Neither mode inherits Meshia service credentials as environment variables. Command supervision stops owned descendants, including ordinary detached children; it cannot undo machine changes or independently installed OS services. An expired command claim is not automatically executed again. Process success does not itself prove file publication: verify written files through the normal MCP file tools before review or handoff. Edit shared files through the native mount or the normal MCP file tools; those use the same durable workspace. File reads may return base64 even for text when a byte range splits a UTF-8 character. Decode the stated encoding before reviewing content.

### Resident Link groups and Linux GUI apps

Inside the workspace's resident agent, use the shared Link tools for device groups and headless GUI windows. External CLI/MCP clients can call `meshia_app` directly; no resident model turn is needed. Copy the exact ready managed `compute_instance` runtime ID from `meshia_compute_snapshot`. Use its `workspace_id` and a new UUID `request_key` for each logical operation; reuse that key only with unchanged arguments when recovering the same request. Refresh the MCP tool catalog if the client has cached an older list.

- **Device groups:** describe `meshia_link` through `specialized_tools` with `{"action":"describe","name":"meshia_link"}`, then call the described schema, starting with `{"action":"call","name":"meshia_link","arguments":{"operation":"discover"}}`. Choose only `supported: true` targets. `connect` needs two to eight exact `runtime_kind`/`runtime_id` pairs, including the target marked `is_current`, plus a stable `request_key`; reuse that key after uncertain pairing. Retain the returned `group` and require `state: "ready"` before `send`/`watch`. Retain each watcher's `{epoch, after}` cursor. Close that same group and inspect any `cleanup_pending` receipt. Connected computers need a qualified installed Link channel; being online or attached for Files does not establish support or grant execution, capture or keyboard control. CLI `meshia link discover` lists local memberships instead.
- **Linux GUI windows:** call `meshia_app` with `operation: "capabilities"` and require `available: true` and `queued_deadline: true`. Then `open` with `argv: ["xterm"]` creates the private GUI and workspace tab without manual port registration. Retain the successful native result's `surface.id` and `surface.generation`; pass them as `surface` and `generation` to `observe`, `act`, `resize` and `close`. Click coordinates are relative to the observed PNG and must fit its current dimensions; copy its `geometry_epoch`. Observe again after resizing or input to confirm the actual effect. Verify browser pixels/input/resize separately. Close the original generation and require `closed: true`. Python's `await App.open(authorized_app_request, ["xterm"])` uses this same authorized bridge; its async context manager preserves identity and closes the app.

For the CLI, discover the schema with `meshia tools meshia_app`. After the capability check, save this as `app.json`, replacing the IDs and using a fresh request UUID:

```json
{"workspace_id":"<workspace UUID>","runtime_id":"<ready runtime UUID>","request_key":"<new request UUID>","operation":"open","argv":["xterm"]}
```

Run `meshia --json call meshia_app --file app.json`. Its successful receipt contains `status: "succeeded"` and `result.surface`; raw MCP exposes that surface at `structuredContent.result.result.surface`. A pending/202 receipt is not an App handle. Read its original `command_id` with `meshia_command_get`, using the same workspace and exact `target_runtime_kind: "compute_instance"` / `target_runtime_id`. Require terminal `succeeded`, exit code 0 and valid successful JSON in `stdout` before taking its surface/generation. Preserve the original key and arguments after uncertainty; never automatically replay `open` with a new key.

Workspace Ready does not establish App readiness; require actual capabilities. If that read-only check returns `APP_AUTHORITY_UNAVAILABLE`, its `authority_phase` names the failed boundary without exposing private diagnostics. A fresh read-only capability check is safe after an initial authority refusal. For an uncertain `open`, recover any returned original `command_id`; absence of an ID does not prove that nothing ran or authorize a new-key launch.

For several windows, check the actual capabilities' `max_surfaces` before opening more apps. The workspace automatically suspends hidden viewer demand as tabs change; hiding or detaching a viewer keeps its app running. This is viewer demand control, not per-stream bandwidth allocation, and `meshia_app` has no interest or priority operation. Resize each exact surface/generation, then observe its returned actual dimensions and `geometry_epoch` before clicking.

Closing an app or group does not stop its compute. Close each original app generation explicitly, then release owned compute separately as described under **Finish cleanly**; inspect uncertain launch/input outcomes before another action instead of automatically replaying them.

### HTTP web apps

For an ordinary web server or static report, the existing port/register workflow remains supported. Use `meshia_lab_apps_list` to inspect existing custom apps before reserving another port. Keep one stable `app_id` and the exact selected computer through its lifecycle:

- **Attached native computer:** read `meshia_connected_hosts_list` with `scope=workspace` and copy `host_id`, `host_generation` and `access_revision` from the active attachment. Require its current Full or Workspace-only compute grant and `connected_hosts.capabilities.app_protocol=http-stream-v1`. Include those fields, `workspace_id`, `app_id` and a distinct `idempotency_key` for each control operation. Call `meshia_lab_app_port_reserve`, then `meshia_lab_app_start` with `title`, `mode=proxy`, the reserved `lease.port` as `port`, and direct `launch_argv` that starts the server on that localhost port. Use `workspace_tab=true` for a visible workspace tab. Serve from `/`; `proxy_base_path` can only be `/`. The app runs under the same compute grant and ordinary OS permissions described above; `cwd` is workspace-relative in Workspace-only mode and may be an absolute host path in Full mode. Start owns and supervises the process. For a queued or uncertain response, poll any returned `command_id` with `meshia_connected_host_command_get` and inspect app state before proceeding; preserve the same key and arguments if a retry is needed. Do not replace it with a new launch or silently switch computers.
- **Managed runtime:** select the ready runtime from `meshia_compute_snapshot`. Reserve with `meshia_lab_app_port_reserve` and that `runtime_id`, launch on the reserved port using `meshia_command_run` with `target` set to that runtime ID, then call `meshia_lab_app_register` with the same `runtime_id` and `mode=proxy`. Use the returned `browser_base_path` for framework and relative asset/API URLs; set `proxy_base_path` if the upstream expects that prefix too. For a single HTML report on managed compute, `meshia_lab_app_publish` saves and registers a private workspace tab; larger static bundles use file upload and registration.

Read `meshia_lab_apps_list` again, adding the exact `host_id` for a native app, and inspect its status and returned `browser_url`. A reservation, queued command or registration alone does not prove the app works. Open the workspace or returned browser URL to authenticate the private preview and verify its page, assets and API behavior. Apps support fetch, EventSource and WebSocket on their isolated app origin; use the app's URL paths, never the daemon `/ws` endpoint, and verify reconnects if the app uses sockets.

When finished, call `meshia_lab_app_unregister`, inspect the cleanup receipt, then call `meshia_lab_app_port_release` for the same app and target. Native cleanup uses the current attachment's identity fields and a separate key per operation; read back changed authority before acting. Confirm `cleanup.owned_process_stopped` and inspect `cleanup.registry_updated` for native cleanup, then list apps to confirm removal. A released or already-released port alone does not prove process cleanup. Saved workspace files remain available.

Managed app mutations include `workspace_commit`: `pending` means the change is live and the workspace publisher is saving it to shared storage (Stop drains it first), while `local_only` means the runtime has no shared-store configuration. Native app receipts do not include this managed-runtime commit proof. Native file closes can precede background synchronization; confirm the remote file revision before depending on a cross-computer edit.

A connected host returns `LOCAL_ACCESS_REFUSED` without a current matching compute grant. Inspect the attachment mode and execution scope, and refresh the owner-approved choice if needed. A legacy workspace grant cannot enable native execution. Workspace-only file isolation failures must not fall back to full access.

## 4. Understand what the owner would genuinely value

Before proposing a project, inspect only context the owner has already made available to you:

- the current conversation and explicit goal;
- active repositories, documents, datasets, or plans in scope (including mounted workspace files);
- connected accounts and tools from `meshia_integration_accounts` (GitHub, Vercel, Supabase, Linear, Notion, PubMed, bioRxiv, ClinicalTrials, ChEMBL, OpenTargets) and online computers from `meshia_connected_hosts_list`;
- relevant Meshia workspace names, recent messages, artifacts, and run history;
- constraints such as deadlines, desired deliverables, privacy, budget, and review style.

Look for work that is currently limited by elapsed time, local compute, large data, parallel investigation, repeated experiments, or the need for a durable remote workspace. Combine connected integrations, local files, and Meshia compute when that saves the owner manual setup or glue work. Do not recommend GPU usage merely because it is available.

If the available context is thin, ask at most one narrow question that materially changes the recommendation. Otherwise make a useful inference, label it as an inference, and proceed.

## 5. Design the first-project proposal

Recommend one primary project, not a generic menu. It should feel surprising but obviously connected to the owner's actual work.

A strong first Meshia project:

- produces a valuable artifact, decision, benchmark, model, dataset, report, or working branch;
- uses only the time and compute that materially improve this task; attached compute stays up while the workspace is healthy and within its limits, so plan durable checkpoints for the owner rather than for a compute deadline;
- gives Meshia a real advantage over keeping the owner's laptop and foreground agent busy;
- has a few meaningful checkpoints the owner can inspect without babysitting;
- has measurable success criteria and a useful partial result if the final hypothesis fails;
- starts with a deferred no-spend workspace and conservative GPU, hourly, total-budget, and storage limits, plus explicit per-command timeouts;
- distinguishes project approval from later approval of the exact billable quote.

Present the proposal in 100-150 words: the artifact or decision, why it matters now, why Meshia helps, and the next action. Include a concrete first checkpoint and proposed spend boundary. Ask: “Shall I prepare this workspace and get a no-spend quote?”

Never invent a dataset, repository state, benchmark result, available GPU, duration guarantee, or price. Start with the smallest useful outcome; use a GPU or swarm only when it materially helps.

## 6. Prepare without spending

If the owner approves the project proposal:

1. Reuse a suitable workspace or create a new deferred workspace. Creation and resume must not attach a GPU.
2. Set conservative workspace limits before provisioning compute. Meshia's saved workspace-budget floor is $5.00 and the current bounded paid-compute launch floor is $10.00; do not request a smaller value and assume it was preserved. Read the limits back before quoting.
3. Upload or organize only the files required for the approved project. File bytes can transfer directly to signed storage URLs without running compute; an `object-*` ID alone does not identify the upload lane. Follow the prepared lane:

   - For a single signed PUT ticket, HTTP 2xx proves transfer only: skip `meshia_upload_status`, then call `meshia_upload_commit` with the exact `commit_tool_arguments` returned by `meshia_upload_prepare`. The required `sha256` must not be omitted. Verify the durable path and digest after commit.
   - For files **>=64 MiB**, compute the whole-file SHA-256 and ordered part digests locally. Include `parts_as_blocks_plan` in preparation: start with 4 MiB parts, double the part size until there are at most 8192 parts, and never exceed 64 MiB per part (512 GiB per file maximum). The final part may be shorter. Send metadata, not file bytes, through MCP.
   - For `lane=parts_as_blocks`, call `meshia_upload_block_tickets` with the unchanged ordered parts, `start_index`, and `count<=256`. PUT only missing parts with the exact signed headers; skip verified present parts. Continue bounded batches, then call `meshia_upload_commit_blocks` with the prepared plan and whole-file digest. Do not PUT the whole file to this lane or use the single-object commit tool.
   - During slow block transfers, call `meshia_upload_refresh` at least every 30 minutes, even within a batch. Replace only `upload_token` in subsequent tool arguments with the returned token. Refresh preserves the original upload identity and plan, including with stopped compute. If admission is expired, missing, settled, or conflicting, read back state and report the failure; never silently create a new upload/base to bypass it. Plain object/archive tickets do not have active admission renewal.

4. Write the run plan and checkpoints into the synchronized workspace messages so the Meshia UI and external agent share one durable ledger.
5. Inspect current capacity and request a no-spend compute quote.
   - For CPU-only work, call `meshia_compute_available` with `hardware_class=cpu`. Add `max_runtime_seconds=1200` for an explicitly bounded proof; omitting it preserves the normal healthy-compute policy and 30-day provider backstop. The bounded work window starts at admission, includes boot time, and has another 300 seconds for cleanup. Review the returned provider rate, runtime and cleanup estimates, and `start_tool_arguments_after_approval`.
   - For bounded GPU or CPU jobs that run to completion without interaction (quick GPU tests, evals, inference, sweeps, fan-out), and whenever resident GPU capacity is exhausted, quote a Modal batch: `compute_intent=agent_burst` with `compute_filter.provider_resource_types=["modal_function"]` and `lifecycle_scopes=["batch"]`. Modal starts in seconds and bills per second only while jobs run; after approval launch it with `meshia_compute_batch` (one job is `task_count=1`) and poll it with `launch=false`. Use resident GPUs for interactive shells, custom images, services or repeated iteration.
   - Availability may include a recent cached offer; the quote is the launch authority. If the quote returns `COMPUTE_CATALOG_INCOMPLETE` with `retry_after_seconds`, wait that interval and make one fresh quote attempt. Do not repeatedly poll, reconstruct a quote from availability, or treat a catalog cooldown as a stockout.
6. Show the owner the exact quoted hardware, rate, estimated bounded cost, limits, and expected runtime. The shared attach service manages compatible region/provider fallback under the sealed quote constraints. Explicit `compute_filter.providers` restrictions remain binding; `compute_filter.max_price_per_hour` and `compute_filter.max_transfer_usd` bound the initial and replacement quotes. Preserve the returned `attach_tool_arguments_after_approval` object exactly; do not reconstruct or trim its runtime plan.
   - The quote's `launch_admission_policy.max_runtime_seconds` is its provider-side safety window, separate from a command timeout and not configurable through workspace limits. Workspace limits govern customer charges: the hourly spend cap pauses chat, the GPU cap controls accelerator procurement, and the total budget stops the workspace at 100% with 7-day file retention. Subscription-included CPU provider costs do not consume that customer budget; its provider rate and selected runtime/cleanup window are a separate exposure estimate, excluding variable network costs. Show both with the quote, use a command timeout matched to the task, and release compute promptly when done.

Approval of the project is not approval to spend. Do not call `meshia_compute_attach` or `meshia_compute_start_cpu` until the owner explicitly approves the quote or an equally explicit covering rate and runtime envelope.

## 7. Execute after explicit compute approval

After the owner approves the quote:

1. Attach only the approved compute within the approved limits by passing the quote's `attach_tool_arguments_after_approval` object verbatim. Its `confirm_spend: true` is valid only after the owner has explicitly approved that exact quote or an equally explicit covering spend cap.
   - For CPU, pass the returned `start_tool_arguments_after_approval` unchanged to `meshia_compute_start_cpu`. Starting on the current deferred workspace preserves its identity and files. Repeated calls observe the existing allocation; they do not reset or shorten its deadline. Poll `meshia_workspace_status` and perform canonical cleanup before any replacement.
2. A `waiting_for_resources` attach response is a durable request owned by the shared attach service. Read `meshia_compute_snapshot` for progress; do not create another attach or run a separate re-quote loop. A healthy workspace CPU does not prevent accelerator fallback. If the request fails, read accelerator and cleanup state before requesting another no-spend quote. Re-show it when hardware, price, transfer estimate, limits, or the owner's approval basis changed; never repeat an ambiguous attach request blindly. Old attach objects containing `fallback_policy` are rejected before mutation: obtain a fresh quote with the approved constraints rather than removing that restriction from an old request.
3. Use direct commands for deterministic execution and Meshia swarm runs when parallel agents materially improve the work. Confirm `meshia_compute_snapshot` reports the selected runtime as commandable. For direct commands, `workspace_readiness.launch_ready=true` with `generation_fence=true` allows admission during background saving: the runtime waits for the command's required namespace generation before execution. Other runtimes and swarm creation require `fabric.localCommandReady=true`. The compact snapshot includes CPU targets in `cpu_runtimes` and accelerator targets in `accelerators`; keep the selected runtime identity unchanged. Running status and a fresh heartbeat alone do not establish file readiness. If the required readiness proof is false or missing, inspect the reported reason and wait within the approved deadline. A run in `waiting_for_compute` is durable but cannot make progress until compute is attached and ready.
4. For `orchestration_mode=external`, start only independent peer workers in the Meshia run. Poll them to terminal, read their artifacts, and then synthesize in the owner's agent or start a later dedicated synthesis run. Do not launch a synthesis worker beside peers whose outputs it needs; initial workers have no implicit dependency ordering.
5. When the run declares `inputs`, give every explicit worker a non-empty `input_paths` array containing the exact subset of those paths it must use. Do not assign a source by mentioning its filename only in the goal. Meshia verifies each input digest, turns PDFs into text-safe, page-marked source packets, and fails the worker instead of finalizing its artifact until it reads every assigned source.
6. Declare each required artifact with exactly one worker `producer`, using that worker's unique `key`. A worker is not successful until its assigned sources were read and its required paths exist. Afterward, the owner's conductor must read the artifacts and compare material claims against the durable source files; path and digest finality do not by themselves prove semantic correctness.
7. Omit worker `tool_allowlist` for ordinary research. The safe default grants standard workspace tools but excludes dependency and MCP installers. For file-only work, use `["file_read", "file_write"]`: worker capabilities use internal tool names, while `meshia_file_read` is the external MCP tool. Required inputs need `file_read`; file-only workers saving outputs also need `file_write`. Grant an installer tool explicitly only when the owner authorized environment mutation; do not hide `pip`, `uv`, `apt`, `npm`, or similar installation inside a shell or Python command.
8. Subagents have no lifetime token budgets. `est_tokens` is a planning estimate for admitting new work, not a ceiling on execution. Meshia retains each model's per-response output limit, provider spend admission and usage accounting across turns, retries and fallbacks. Workers continue until completion, cancellation, an explicit deadline or a terminal execution failure.
9. Prefer the default model routing, which is ordered from current live provider proof. Specify `model_preference` only when the project requires a particular model and the owner accepts the availability tradeoff.
10. Keep raw orchestration in the owner's agent when requested, while using Meshia tool calls for remote execution.
11. Append meaningful plans, assistant decisions, checkpoints, failures, and results to the Meshia workspace message ledger.
12. Poll swarm runs with the default compact detail and a bounded interval. Call `meshia_swarm_run_get` with only the required `workspace_id` and `run_id`, plus optional `detail_level`; do not infer or send fields that are not in the tool schema. The swarm terminal statuses are `done`, `failed`, and `cancelled`; `done` is the successful terminal value. Compact `tokens_used` is cumulative input + output accounting, including active provider checkpoints; it is not generated output. Worker `output_tokens` uses the same deduplicated provider telemetry as the browser. Its `output_tokens_scope: "available_events"` reflects bounded event history, not guaranteed lifetime coverage; `null` means no measured usage in that history, while `0` means measured zero. A later tool event must not erase active checkpoint usage. Report progress at checkpoints rather than emitting noisy low-level logs. Treat a terminal command as complete only after its durable status reports an exit code. For remote background commands, Meshia withholds terminal status until the final workspace flush commits the command's files, logs, and job manifest; do not release compute while the command is still `running`. If its compute disappears first, report the resulting terminal failure instead of waiting forever.
13. Pause for input when results change the plan or when a new cost, permission, external-message, or destructive boundary appears.

## 8. Finish cleanly

When work completes or is stopped:

1. Save final artifacts in the workspace and identify their exact paths.
2. Summarize results, limitations, compute time, and spend against the approved limits.
3. Release or stop billable compute promptly.
4. Keep durable storage unless the owner explicitly asks to delete it.
5. Confirm the final workspace state and any remaining running resources.

A retained Stop can return `flush_pending` while compute remains live and Resume reconnects the same runtime by canceling that Stop. Its `stop_flush.deadline_at` is an observation checkpoint, not permission to shut down a writer with unpublished files. The controller renews the same Stop's bounded 600-second local writer freeze while publication remains pending. Fresh completed publication or an independent budget/policy Stop permits terminal fencing; elapsed time alone does not. A lost controller's local freeze expires without proving the files durable or authorizing provider cleanup.

If compute release or workspace stop returns **cleanup_pending**, Meshia owns the accepted background teardown. Keep routine saving, draining, provider cleanup and billing-finality states internal; do not create cleanup-monitoring timers or status-only follow-ups. Use **meshia_workspace_status** when final confirmation is needed for the owner's task. Confirm the released runtime, active compute and provider cleanup have all reached zero before claiming shutdown is complete. Answer explicit shutdown-status questions in plain language, and surface failures that require the owner's action.

The workspace status accounting fields are deliberately separate: `compute_runtime_cost_cents` is customer compute charges, while `workspace_total_spend_cents` is the canonical all-resource ledger. `current_hour_spend_cents` is the canonical rolling-hour spend aggregate, not the latest five-minute chart bucket or committed hourly rate. Provider COGS are separate and can continue during cleanup after customer billing stops; these customer totals do not prove provider absence or final cost.

Never silently retry an ambiguous mutation. Read back durable state first. Never send team invitations, change roles, delete files, stop another active workspace, or remove durable storage without the confirmation required by the corresponding Meshia tool.

When creating a swarm, omit `client_request_id` and worker `id` unless you specifically need caller-owned idempotency identities. If supplied, each must be a UUID. For ordinary synchronized text checkpoints, call `meshia_message_append` with only `role` and `content`; omit `tool_calls` and `message_parts` unless replaying canonical structured assistant state.

## Troubleshooting

- **No browser opened:** surface the authorization URL from the MCP client and ask the owner to open it in a regular browser.
- **Connected but tools are missing:** for a direct remote connection, verify Streamable HTTP and the exact URL `https://meshia.io/api/mcp`. For installed stdio, rerun `meshia setup --agent <client>`, or use the executable and arguments printed by `meshia mcp config`. Reconnect the selected client, list tools, and read `meshia_account_get` to verify the connection.
- **Authorization loops:** revoke the exact client under Meshia Settings, reconnect, and finish the new browser flow once.
- **The client refuses a mutation before Meshia receives it:** this is usually a client-native approval policy, not an OAuth failure. Resume with normal interactive approvals and retry only the exact owner-approved action after a readback. Do not disable Meshia's safety annotations.
- **A large upload exceeds the MCP payload limit:** follow the lane-specific preparation, block-ticket, refresh, and commit steps above. Transfer bytes directly to signed URLs; keep only the bounded digest/size plan in MCP. A PUT receipt is not durable workspace publication.
- **No appropriate GPU is available:** keep the workspace deferred, report current availability, and do not substitute more expensive hardware without approval.
- **A cached offer is visible but quoting reports a catalog cooldown:** respect the returned `retry_after_seconds`, then make one fresh no-spend quote attempt. If it still fails, keep the workspace deferred and report the public `reason_code`; do not spin or attach from cached inventory.
- **A quote expires or its exact placement disappears:** read the compute snapshot before any retry. If nothing launched, request a fresh quote and follow the approval basis above; do not resubmit the revoked quote.
- **The planned task is shorter than the quote's maximum:** this is expected for the normal provider backstop. CPU proofs can explicitly select the 1200-second work window before starting; existing allocations keep their original deadline. Enforce the task with its command timeout and release compute promptly. Workspace limits bound customer charges, while included CPU provider costs use the separate rate/runtime envelope. The owner can change workspace limits at any time.
- **The owner declines the proposal:** do not create a workspace or attach compute. Offer to revise the project around the stated objection.