# Workcell

Workcell is a local CLI that lets coding agents coordinate exclusive access to a scarce, stateful, physical, licensed, or expensive engineering capability. Commands using different gate keys continue in parallel.

Use Workcell for physical test devices, one GPU node, a hardware-in-the-loop rig, an FPGA lab board, one build host, or a limited floating license seat. Do not serialize commands that are already safe to run concurrently.

## Install a precompiled binary

The installer detects macOS or Linux and arm64 or amd64, downloads the matching binary from this site, verifies its SHA-256 checksum, and installs it under `~/.local/bin` by default.

```sh
curl -fsSL https://workcell-137.pages.dev/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
```

Override the install directory when needed:

```sh
curl -fsSL https://workcell-137.pages.dev/install.sh | \
  WORKCELL_INSTALL_DIR="$HOME/bin" sh
```

Direct static assets:

```text
https://workcell-137.pages.dev/downloads/workcell-darwin-arm64
https://workcell-137.pages.dev/downloads/workcell-darwin-amd64
https://workcell-137.pages.dev/downloads/workcell-linux-arm64
https://workcell-137.pages.dev/downloads/workcell-linux-amd64
https://workcell-137.pages.dev/downloads/SHA256SUMS
```

## Run the reproducible sleep demo

```sh
curl -fsSL https://workcell-137.pages.dev/demo.sh | sh
```

The demo downloads and verifies a temporary Workcell binary without installing it. Agents A, B, and C share `demo-gpu`; B and C use `--wait` and hold FIFO positions behind A. Agent D uses `demo-rig` and finishes while `demo-gpu` is still occupied. A live pane for each of the four agents shows the exact CLI shape and changes among `RUNNING`, `WAITING #n`, and `DONE`. The script verifies FIFO handoff, same-resource exclusion, and different-resource concurrency before deleting its temporary files.

## Run a protected command

The CLI calls a gate key a `resource`. The value is an opaque string chosen by the team.

```sh
workcell run gpu:a100-node-01 --session agent-a -- \
  sh -c 'run-model-evaluation'
```

Wait for the same gate key instead of exiting busy:

```sh
workcell run gpu:a100-node-01 --wait --session agent-b -- \
  sh -c 'run-cuda-benchmark'
```

The resource is the only exclusion and queue key. Session is the stable identity of the agent task that owns or waits for it. It appears in owner status and is preserved by `next_action.wait_argv`, allowing a caller to distinguish its own in-flight work from another task before choosing whether to wait or continue unrelated work. Set `WORKCELL_SESSION` once per agent task when passing `--session` on every command would be repetitive.

`--wait` callers receive FIFO tickets. Only the head waiter can acquire the resource. New callers cannot jump the queue. If a waiting process dies, its ticket becomes stale and is removed automatically.

Different gate keys run concurrently:

```sh
workcell run gpu:a100-node-01 --wait --session model-eval -- sh -c 'sleep 10' &
workcell run rig:firmware-hil --wait --session power-cycle-test -- sh -c 'sleep 5' &
wait
```

Example gate keys:

```text
macos-xcode
device:iphone-15-pro
device:ipad-air-m2
gpu:a100-node-01
rig:firmware-hil
fpga-lab:board-01
license:eda-seat-01
```

## Agent JSON contract

Agents should request JSON:

```sh
workcell run <resource> --json -- <command...>
```

Behavior:

- `--json` is capture mode: Workcell waits for completion, writes the wrapped command's combined stdout and stderr to a private log, and emits exactly one final JSON object on stdout.
- Normally wait for Workcell to return. Do not read routine successful output into context.
- On failure, inspect the completed result's `log_path`.
- To monitor a long-running command, call `workcell status <resource> --json`, read `owner.log_path`, and follow that file only while useful.
- Human mode streams command output live and tees it to the same log. Workcell lifecycle messages use stderr so wrapped stdout stays clean.
- Wrapped commands inherit stdin in both modes.
- Exit `0`, or the wrapped command's exit code, after acquisition and completion.
- Exit `75` with `decision: "busy"` when a non-waiting caller cannot acquire.
- A busy result includes `owner` when available, `queue_ahead`, executable `next_action.wait_argv`, and `duration_estimate` after the first completed run for that gate key.
- Compare `owner.elapsed_seconds` with `duration_estimate.average_seconds`. `duration_estimate.sample_count` reports how many recent runs support the average, and `estimated_remaining_seconds` is the average minus the current runtime, clamped at zero.
- Duration estimates use the latest 32 completed runs for that gate key. Completed results and free status retain the average and sample count without a remaining-time field.
- Run `next_action.wait_argv` to join the FIFO queue with the same command and session.
- `workcell status <resource> --json` reports the current owner or `free`.
- Complete command output is written to `log_path`; stdout and stderr are combined in that log.
- Never bypass Workcell, terminate the owner, or delete state files to force acquisition.

Session identity is selected in this order: `--session`, `WORKCELL_SESSION`, `ACE_SESSION_ID`, then `user@host:pid`.

State is host-local under `~/.local/state/workcell/` by default. Set `WORKCELL_STATE_DIR` to choose another shared host-local state root. All cooperating callers for one gate key must use the same host filesystem and state root.

## Minimal agent policy

1. Identify commands that use a scarce or stateful capability.
2. Assign each capability one stable gate key.
3. Run `workcell run <key> --json -- <command...>`.
4. If the decision is busy, execute `next_action.wait_argv` when the task should wait. Otherwise continue work using another gate key.
5. Let Workcell return without reading the log unless the command fails, appears stalled, or live detail is required.
6. Report the resource, session, reservation ID, exit code, and log path when complete.

Copy this policy into `AGENTS.md` or equivalent project instructions:

```text
Commands using a scarce, physical, licensed, expensive, or stateful capability must run through Workcell.
Run: workcell run <resource> --json -- <command...>
If the decision is busy, use next_action.wait_argv when waiting is appropriate; otherwise continue work using a different resource key.
Do not bypass Workcell or terminate the current owner.
At completion, report the resource, session, reservation ID, exit code, and log path.
```

## Project

- Site: https://workcell-137.pages.dev/
- Installer source: https://workcell-137.pages.dev/install.sh
- Demo source: https://workcell-137.pages.dev/demo.sh