crew-runner 0.1.0 → 0.2.2

package/README.md

@@ -5,6 +5,10 @@ Runs your CrewCortex assistants on your own computer (Mac or Windows), using the
 CrewCortex never asks for your Claude or ChatGPT login or token.
 Runs go through the Agent Client Protocol (ACP), so one code path drives both apps.
 
+## Local video studio pilot (unreleased)
+
+`crew-runner studio` is a separate opt-in local editing session. It does not enable media access for ordinary queued runs. See [STUDIO.md](STUDIO.md) for explicit project consent, typed plans, fixed animated graphics, downloaded Higgsfield-asset provenance, caps and the remote-only acceptance recipe. This pilot has not been published to npm.
+
 ## Setup
 
 Needs Node.js 20 or later (https://nodejs.org).
@@ -59,9 +63,56 @@ Press Ctrl+C (or close the window) to stop the runner. Notes for Windows:
 - Only the old `CREW_RUNNER_PROTOCOL=legacy` path has limits on a `.cmd` file: an instruction with a line break fails there.
   The default ACP path has no such limit.
 
+## Computer mode (@mac, owner only)
+
+`crew-runner start --computer` serves only your own **@mac** computer agent, never your ordinary assistants (a plain
+`start` never receives @mac work). It uses Claude Code with its own file, terminal and web tools, on this computer:
+
+- It saves its work in `~/CrewCortex/<workspace>` (created with owner-only permissions) and may also use `~/Downloads` and
+  `~/.cursor/dev projects`. Another workspace's folder under `~/CrewCortex` is always refused. Claude Code itself runs in an
+  empty, read-only scratch folder that is removed after the run, so every read, search and command touching your folders
+  comes to the runner first; none is approved by Claude Code on its own.
+- Simple read-only commands on full paths in those folders (`ls ~/Downloads`, `cat ~/CrewCortex/<workspace>/notes.md`) run
+  without asking; a relative path asks, because the shell may have moved. The runner never
+  auto-allows `git`, because a repository's own settings can run code. Leaving plan mode, steps too
+  long to show in full on a card, and Claude Code's own settings and history are refused. Opening a web page or search, deleting, `git push`, sending (mail, `curl`, `ssh`, AppleScript and
+  similar), paying, changing files outside those folders, and any command the runner cannot read with certainty (pipes,
+  `$(...)`, redirects, unknown programs) wait for your yes on a card in CrewCortex. No answer within the run is a no.
+- Reading a public web page runs without a card when it is one plain `curl` that only downloads: a GET of one `http(s)`
+  address on a public name (no login, port, local or numeric address, no redirects), printed or saved with `-o` to a new
+  file inside `~/CrewCortex/<workspace>`, with no data, headers, uploads, cookies or config file (`~/.curlrc` makes every curl ask).
+  This holds only until the run has read files on this computer (other than pages it downloaded): after that a download
+  asks, because its address could carry what was read. The address still leaves your computer, as with any web page,
+  and a public name can point at a private address. `wget`, `-L`, pipes and other programs ask.
+- On a card for a web request that sends only what its own command line shows, **Allow for this task** also lets later
+  requests of the same kind in the same run go ahead without a card: web searches, page reads from that one host, or curl
+  requests with that one method to that one host (with or without data or headers, and redirects, as on the card). It ends with the run, never covers uploads of local files, deletes,
+  pushes or anything else, and each step it covers is in the action log with the card that allowed it.
+- It never changes Claude Code settings (`.claude` folders, `~/.claude.json`), and refuses to start in a workspace folder that has them.
+- Claude Code's own files under `~/.claude` (settings, other sessions' history, task lists) and `~/.claude.json` are denied
+  to it by permission rules that Claude Code checks before anything it would allow by itself, and every tool that reads,
+  writes, runs or fetches is set to ask, so its built-in read-only lists never skip the runner. Skills are off.
+- A step whose paths resolve into another folder in `~/CrewCortex` is refused, also when written with quotes, `$HOME` or `..`;
+  a step the runner cannot read for certain goes to a card that shows the whole request (one too large to show in full is
+  refused), so read the card before saying yes.
+- `~/Downloads` and `~/.cursor/dev projects` are shared by every workspace's @mac runs: what one run saves there, a run for
+  another workspace can read. Keep client files in that client's `~/CrewCortex/<workspace>` folder.
+- Only the tools the runner knows exist in the run (shell, files, web, planning and plain subagents); agent teams and
+  skills are off.
+- A step is allowed only once its line in the action log is saved; if the log cannot be written, the step is refused.
+- Channel messages, files, web pages and command output are data, never instructions. Only your own message instructs it.
+- It has no CrewCortex tools. Its reply is posted in the channel where you tagged it.
+- Every allowed and refused step is in the run's action log, which only you can see.
+
+A linked device belongs to one workspace. For several workspaces, link and start one runner per workspace, each with its own
+`CREW_RUNNER_HOME`, for example `CREW_RUNNER_HOME=~/.crew-runner-calyx npx crew-runner@latest login` then
+`CREW_RUNNER_HOME=~/.crew-runner-calyx npx crew-runner@latest start --computer`. Press Ctrl+C to stop it; switching @mac off
+in CrewCortex stops new requests and also stops the one in progress within a few seconds (its open cards can no longer be
+approved).
+
 ## What the apps can do during a run
 
-Each run happens in an empty temporary folder, and the only tool is CrewCortex itself. For Codex the run
+Each run happens in an empty temporary folder, and the only tool is CrewCortex itself (computer mode above is the one opt-in exception). For Codex the run
 uses a read-only sandbox, ignores your own Codex config and rules, and turns off the shell, browser,
 computer, image, web search, plugin and sub-agent tools. The run token is passed through an environment
 variable, never on the command line.

package/STUDIO.md

@@ -0,0 +1,128 @@
+# Local video studio pilot (unreleased)
+
+An account-independent local media CLI and an opt-in media-only MCP bridge. No ordinary `crew-runner start` behavior changes. This is not the cloud studio UI and is not published to npm.
+
+## Local member journey
+
+Install FFmpeg and ffprobe yourself using a trusted OS/package source. The pilot requires MP4 input, an H.264 encoder (`libx264`), AAC and drawtext with working local fonts. There are no runtime binary/model downloads. Check `capabilities` first. Hardware encoders advertised by the installed binary are listed, but this pilot always uses CPU and never claims verified GPU acceleration.
+
+Select a dedicated canonical absolute project directory, place only the media you intend to expose inside it, and pass both flags each time:
+
+```sh
+node packages/runner/bin/crew-runner.mjs studio --project /absolute/my-project --allow-local-media capabilities
+node packages/runner/bin/crew-runner.mjs studio --project /absolute/my-project --allow-local-media inspect source.mp4
+node packages/runner/bin/crew-runner.mjs studio --project /absolute/my-project --allow-local-media render plan.json
+node packages/runner/bin/crew-runner.mjs studio --project /absolute/my-project --allow-local-media preview plan.json
+```
+
+No CrewCortex login is needed for these commands. Preview is a separate 640x360 MP4, not an HTTP server; export is 1280x720. Source aspect ratio is preserved with letterboxing. Original audio is cut alongside the corresponding frames, normalised to stereo 48 kHz AAC. Silent sources receive silence, never cloned/generated speech. Original MP4s are never overwritten. Each successful job returns a new `.crew-studio/job-<uuid>/export.mp4` and `manifest.json` containing source SHA-256, selected cuts and imported-asset provenance. Partial jobs are removed on cancellation/error; completed versions survive subsequent failures. Ctrl+C/TERM cancels a CLI render.
+
+Plan times are seconds. Caption/callout times refer to the finished timeline, not the source. Callouts use a fixed dark panel, mint brand stripe and large sliding/fading typography, not arbitrary FFmpeg filters or HTML. The supporting asset is appended after the original cuts.
+
+```json
+{
+  "source": "source.mp4",
+  "cuts": [{ "start": 0, "end": 3 }, { "start": 5, "end": 8 }],
+  "captions": [{ "start": 0, "end": 2.8, "text": "Your supplied transcript text" }],
+  "callouts": [{ "start": 0.3, "end": 2.6, "text": "ORIGINAL VOICE + FOOTAGE" }]
+}
+```
+
+Supply a typed plan/timed transcript. `transcribe source.mp4` fails clearly because no speech model is installed or downloaded. Plain one-line text supports letters/numbers and a small punctuation set, up to 80 characters per entry. Split longer captions. Rendering human likeness or editorial quality is not proven by a synthetic fixture.
+
+## Explicit Higgsfield handoff, no rebilling
+
+1. In the existing CrewCortex browser UI, download an already-authorized clean Higgsfield MP4 through its normal file download. Do not generate a new video for this pilot.
+2. Explicitly copy/select that downloaded file into the approved project. The CLI never downloads it, reads browser cookies or obtains presigned URLs.
+3. Import it with a human-supplied file/job reference:
+
+```sh
+node packages/runner/bin/crew-runner.mjs studio --project /absolute/my-project --allow-local-media import support.mp4 higgsfield existing-file-or-job-reference
+```
+
+4. Add the returned `id` to the plan as `"supportingAsset": { "id": "returned-uuid", "start": 0, "end": 2 }`.
+
+The import records declared origin, reference, byte hash, `verifiedByProvider: false` and `charged: false`. This is a provenance declaration, not provider attestation. It does not call the generation API or reserve/settle credits. If the local file changes after import, rendering fails until explicitly imported again. Use origin `local` for fixtures and other local assets. Never label fixture footage as Higgsfield-generated. Existing supplied-cloud Higgsfield billing/provider data are unchanged.
+
+## Source-coordinate long-form slice (version 2, CLI only)
+
+The existing `render` / `preview` CLI also accepts an explicit version-2 plan. This is an offline engine contract, **not a channel-to-Runner integration**. The existing media MCP plan schema still exposes only the legacy short-plan format pending contract review. `inspect` and asset import retain the legacy 120-second/100 MiB limits; long-source admission/strict decoding occurs inside a version-2 render.
+
+```json
+{
+  "version": 2,
+  "source": "selected-recording.mp4",
+  "sourceDuration": 4326,
+  "remove": [{ "start": 0, "end": 48 }],
+  "mute": [{ "start": 3591, "end": 3598 }],
+  "holds": [{ "start": 3591, "end": 3601, "frame": 3590 }],
+  "crop": { "x": 0, "y": 0, "width": 1280, "height": 720 },
+  "intro": "brand/intro.mp4"
+}
+```
+
+All times here are **original source seconds**, on a 30fps output grid. `remove` deletes picture and sound together; `mute` removes only audio content, replacing it with silence **without ripple**, so later speech stays aligned with picture. This is an explicit editing mode, not an interpretation of an ambiguous client request. Holds must name start, end and a source-frame seek time; no automatic freeze-to-end. The selected picture is the first frame decoded at/after that seek, not an invented prior frame. Crop uses even source-pixel coordinates and must fit the decoded source dimensions. Input arrays must be ordered/non-overlapping within each track, at most 32 entries each. SourceDuration is checked against the selected file. Unknown fields, output paths, arbitrary filters and commands are refused. Preserve the raw human request separately; this schema does not parse natural-language timestamps or approve a crop/hold.
+
+Source/output times are distinct in `manifest.json.mapping`; deletions are applied once in source space. Fixed 30fps output and exact frame counts are checked on every video-only unit and final encode, alongside final picture/audio duration and strict decode. V2 reads source audio once in the final pass, resamples to 48kHz with timestamp-aware source placement (`aresample=48000:async=1:min_hard_comp=0.001:first_pts=0`), partitions it into exact 1600-sample blocks on the validated 30fps source grid, mutes/selects those blocks in original-source coordinates and assigns continuous sample timestamps. Holds never split the audio. Timestamp placement fills source gaps/positive starts with silence and drops overlapping or pre-zero samples before block selection; `async=1` enables placement, not soft clock stretching (`min_hard_comp=0.001` gives a 1ms hard-correction threshold). It never repairs concatenated per-unit AAC padding: the units have no audio. AAC is encoded **once**, not per unit. swresample can allocate an entire timestamp gap as PCM before the trim. V2 therefore refuses unsafe source clocks **before snapshot or rendering**, using the admission below; the fill/drop filter stays in its correct pre-trim position. There is no full-source PCM cache, split/concat audio buffering, or final timeline truncation to hide padding gaps. Silent sources use a fixed bounded silence input. Legacy v1 keeps its existing segment-AAC/concat path and short-form contract; this repair does not claim sample-exact joins for arbitrary legacy cuts.
+
+The broadband-audio regression covers continuous 65-second outputs at 30 and 29.97fps, 44.1kHz source resampling, original-source A/V removal with mute/hold boundaries, and a 305-second/11-unit output. It checks correlation lag before/after every non-mute seam (delta <=48 samples, absolute offset <=1024 samples), near-silent runs <=48 samples at non-mute joins, source-picture frame offset zero, final-pass cancellation and retained versions/budgets. A separate silent-source case checks fractional-grid cuts. Four source-clock cases use an independent decoded-frame PTS scatter reference (not the production resampler/block filter): a 0.5s timestamp gap, an actual +40ms decoded audio start, a negative input offset normalized by MP4 edit-list trimming, and a 40ms timestamp overlap. They require absolute lag <=48 samples before/after the discontinuity and both 30s seams, gap-interior silence, one final audio stream, all 1950 picture frames and no missing audio beyond ordinary final AAC rounding. This is synthetic mechanical sync evidence, not human speech quality or full-length throughput. The late-window public-CLI pilot still keeps 12s from a 72m6s source and checks held pixels and tone/silence/tone.
+
+V2 source-audio admission is deliberately narrower than legacy: no audio, or **one AAC-LC stream**, with a standard rate of 8/11.025/12/16/22.05/24/32/44.1/48/64/88.2/96kHz and 1-8 channels. Other codecs/profiles, multiple audio streams and midstream decoded format/rate/channel changes are refused with a named reason, not silently transcoded as a fallback. This restriction supplies an explicit bounded-frame contract (float-planar PCM, 1-1024 samples/frame); it does **not** restrict legacy inspect/import/render codecs. The existing strict source decode now streams `asettb=1/28224000,ashowinfo` metadata through the existing owned command/cancellation helper, with no resampling or silence injection. The common integer timebase represents each admitted rate exactly. Admission sums **positive adjacent decoded-frame gaps plus a positive initial offset**, never subtracts overlaps, and adds two ticks per frame to conservatively cover timebase rounding. The total must stay within **2 seconds**, including that reserve. Priming and MP4 edit-list skips are already reflected in the actual decoded frames; `nb_frames * 1024` or a NET duration estimate is not trusted. A 100s positive gap with an offsetting run of repeated/overlapping timestamps is still denied. At most 600,000 decoded frames, 192 MiB of streamed log bytes and 8192 characters per line are inspected, without retaining the scan; only the 16kB stderr tail and bounded line buffer survive. Missing/nonfinite/unsafe clocks and incomplete/unsupported records fail closed. The scan shares the existing <=10-minute strict-source-decode limit and <=15-minute consent-bound job deadline, not a new budget. Source identity/size/mtime/ctime are checked across admission and the hashed snapshot. This bounds gap-silence expansion, not total FFmpeg RSS or decoder-library behavior; FFmpeg is not an OS memory sandbox.
+
+Admission regressions prove refusal before the snapshot or video units for a real 120s/100s-gap source, the same-duration/sample-count gap-plus-overlap bypass, and ALAC (with a retained legacy ALAC render control). Real 8kHz mono and 96kHz/8-channel controls pass. Parser tests cover profile/channel/rate/clock/frame/count boundaries and cumulative gaps; owned-child tests cover empty scans, oversized lines/bytes, cancellation, consent expiry and lock cleanup.
+
+Bounds: source <=3 hours, <=6 GiB, 1-120fps, <=3840x2160; each sequential render unit <=30 seconds, <=576 units; aggregate intermediate files <=512 MiB, final export <=512 MiB. Disk admission requires snapshot size + both 512 MiB budgets +256 MiB reserve. Snapshot uses a 1 MiB streaming buffer and hashes copied bytes; originals are not loaded wholesale into memory. Consent and the entire job share a <=15-minute deadline, source/final decode or final encoding <=10 minutes, individual segments <=90 seconds. Decoder/encoder/filter threads stay at 2. These are conservative admission limits, not a promise that every admitted 4K recording finishes within the deadline. Source metadata/decode must succeed before source-frame EOF display padding (at most one source-frame interval) is applied. FFmpeg is not an OS memory sandbox.
+
+The existing project lock, cancellation and fail-closed crash recovery remain. Per-segment `progress.json` is a bounded checkpoint, not resumable authorization: process death can leave lock/private partial files; inspect owned processes before human cleanup, never automatically rerun a lost acknowledgement. Successful UUID versions have source/output SHA-256 plus plan/mapping, and earlier versions survive failed edits. Export files remain local. No automatic transfer, scanned upload, hosted version registration or publication exists here.
+
+Intro prepending: an optional `"intro": "brand/intro.mp4"` names ONE existing project MP4 that the member chose (for example a workspace's saved usual intro or a file they supplied with the request). The engine never picks, generates or scores an intro; choosing which file, and showing that choice for approval, belongs to the caller. The intro is snapshotted and hashed like the source, then admitted before the source with the same strict v2 decode and audio-clock rules (one AAC-LC stream or none, positive gaps <=2s), at most 120 seconds (checked from metadata before any full decode) and 100 MiB; its copy is disk-checked before it is written, and an edited programme plus intro over 3 hours is refused before the source is opened. Its picture is letterboxed/pillarboxed into the export frame (never stretched or cropped; the source crop does not apply to it) and resampled to the 30fps grid; only its whole 30fps frames are used, in <=30s video-only units. Its audio is placed by PTS, converted to 48kHz stereo with FFmpeg's standard rematrix (mono goes to both channels at -3 dB, as for sources without an intro; multichannel is downmixed), padded with silence or trimmed to exactly 1600 samples per intro frame and joined once before the unchanged source chain; an intro with no audio contributes silence, never music. Source mapping keeps original-source times; `manifest.json.intro` records path, sha256, frames and output span, and every `mapping` outputStart is shifted by the intro's whole frames. Regression: a 1080p 25fps mono 44.1kHz intro and a 31s silent portrait intro both give exact frame counts, the intro picture to the last intro frame, source frame 5.000s as the first programme frame and 0-sample source lag after the seam. Legacy `supportingAsset` still appends and is not an intro. Ripple-audio deletion remains a separate slice. Actual source, hold duration/frame, crop and intro must be reviewed before editing private client footage.
+
+Remote reproduction (owned Linux checkout only):
+
+```sh
+bash scripts/ci-ffmpeg.sh /owned/tools
+PATH=/owned/tools:$PATH CREW_STUDIO_MEDIA_TESTS=1 pnpm --filter crew-runner test --maxWorkers=1
+PATH=/owned/tools:$PATH node packages/runner/test/studio-source-pilot.mjs /owned/synthetic-project
+```
+
+## Hosted webinar edits (render image Studio mode)
+
+The `crew-render` image also runs this engine for hosted webinar edits, one job per disposable Fly machine (`infra/render/studio.mjs`, chosen when the machine gets `RENDER_STUDIO_URL`). The image owns the FFmpeg 7.1 static digest pin, which `scripts/ci-ffmpeg.sh` reads from `infra/render/Dockerfile`; it is installed at `/opt/ffmpeg-7.1`, first on PATH for Studio mode only; the motion-video modes keep the distribution FFmpeg. The engine source is copied unchanged and run by Node's type stripping.
+
+The machine downloads the approved source and optional intro from short-lived URLs, refusing more bytes than the worker declared and checking Drive's md5 when one was given. It fills `sourceDuration` from ffprobe on the 30fps grid, so the approved edit lists (source seconds) are the only plan input. It calls `openStudio(grant, limits)` with hosted limits instead of `LOCAL_LIMITS`: a job deadline of at most `HOSTED_MAX_JOB_MS` (four hours, downloads included), longer per-unit and decode/final windows, more encoder threads, a 1080p export and intermediate budgets of up to `HOSTED_EXPORT_BYTES` (4 GiB) and `HOSTED_INTERMEDIATE_BYTES` (16 GiB). When the export budget could bind for the programme's length, the final encode gets a peak video rate (`-maxrate`, 2x `-bufsize`) sized so the whole export fits (90% of the budget less 200 kbit/s for audio and container); short and local exports keep their exact argv. A dropped or stalled download resumes with an HTTP Range request (up to five attempts, 90 s stall timeout) and the md5 covers the whole stream. Measured on performance-4x (4 dedicated CPUs, 8 GB): a 75-minute 1080p30 webinar-like source rendered in 37 minutes (about half real time), with a 1.42 GB export. The local CLI and MCP bridge always use `LOCAL_LIMITS` (15-minute job, 90s units, two threads, 720p), so their behaviour and pilot outputs are unchanged. It uploads the export and a JPEG still, then writes a status JSON (bytes, SHA-256, duration, size, render time, peak memory) or a failure reason.
+
+Real-media check, inside the built image: `node --test /app/studio.test.mjs` with `/opt/ffmpeg-7.1` first on PATH (synthetic 1080p 25fps source, 44.1kHz intro, a cut and a mute; md5 and size refusals; edit past the end refused).
+
+## Supported subscription planning path
+
+Opt-in is a standalone, member-authored local session, not a blanket attachment to queued/shared cloud tasks:
+
+```sh
+node packages/runner/bin/crew-runner.mjs studio --project /absolute/my-project --allow-local-media agent --cli claude --prompt 'Inspect source.mp4 and render a short edit with the supplied captions ...'
+# Same interface: --cli codex
+```
+
+The normal installed Claude Code/Codex app must already be signed in by the member. No vendor credential files are read, exported or copied, and no sign-in bypass is implemented. Planning uses the member's supported subscription account and quota, not unlimited/free inference. Local processing is a separate CPU operation. **The provider receives the prompt, selected tool metadata and timed caption/plan text during planning.** Do not use sensitive footage/transcripts without approving that provider audience. The bridge does not return original video/audio bytes to the model, but metadata can still be sensitive.
+
+The adapter retains an empty temporary cwd, disabled built-in filesystem/shell/terminal tools, read-only Codex sandbox and disabled member MCP servers. Codex studio sessions refuse a pre-existing member `crew_studio` entry (even disabled): rename that member server first, because recursive config merging could otherwise inherit its environment or working directory. Studio-only sessions explicitly disable `crew` rather than omitting it. Only `probe`, `capabilities`, `render`, `preview` and `cancel` are added under `crew_studio`. Permissions use exact tool names and expiry; `import`, network, upload and arbitrary shell tools are not model-exposed. Root and expiry are captured by the host before the model starts and cannot be set through tool inputs. Consent defaults to 30 minutes and cannot exceed one hour. The `stdio` entrypoint is private local plumbing using the maintained MCP SDK. Claude and Codex config/permission paths have deterministic tests, not live subscription-account acceptance.
+
+## Boundaries and caps
+
+- MP4-only filename, actual `ftyp` bytes plus ffprobe metadata validation; URLs, protocols, absolute/traversal paths, symlinks and nonregular files denied. Relative subdirectories are allowed.
+- Maximum input/output file 100 MiB, media/timeline 120 seconds, source 3840x2160, 8 streams, 12 original cuts, 24 captions and 24 callouts. Plan file max64 kB. Every segment and final export is stat-checked, strictly decoded and compared against the requested video/audio duration before publication. FFmpeg's zero exit or `-fs` limit alone is not completion. Exact 120-second video is allowed with bounded frame/AAC packet mux rounding, not extra timeline seconds.
+- One render per project via an atomic filesystem lock, 2 encode/filter threads and 90-second timeout per media subprocess, also bounded by consent expiry. Fixed codecs, fixed filter expressions, fixed output dimensions, no user command/filter/script/HTML options. FFmpeg protocols restricted to local file reads. Output processes inherit the owning adapter's process group so abrupt group shutdown cannot orphan an encoder.
+- This is not an OS security sandbox against a hostile same-user process replacing directories concurrently. Put the project on trusted local storage, outside a shared writable folder. Decoder libraries remain an untrusted-media surface: use a current trusted FFmpeg installation. Windows/macOS media execution has not been exercised by this Linux-only acceptance.
+- A crash/SIGKILL can leave a partial private job and lock. It fails closed on next render. After verifying no owned encoder is running, the member may remove only that project's `.crew-studio/lock` and abandoned job. No automatic stale-lock takeover or duplicate work.
+- No HTTP listener, auto download/upload, social publish/schedule, provider key export, new generation billing, changes to ordinary runs or automatic cloud-to-local exchange. Any later upload must use the existing untrusted-upload scanning and limits, not bypass them. Authoritative run/output audience scope (PR529) remains a prerequisite for automatic exchange.
+
+## Remote-only reproducible evidence
+
+On an authorized isolated Linux checkout, install as the runner user with a real own `node_modules` (never a cache symlink). Put existing isolated FFmpeg binaries on PATH. No tests/install/build/devserver/render on Haydo's Mac.
+
+```sh
+CREW_STUDIO_MEDIA_TESTS=1 pnpm --filter crew-runner test --maxWorkers=2
+pnpm --filter crew-runner typecheck
+node packages/runner/test/studio-pilot.mjs /owned/new-pilot-project
+```
+
+The media tests are opt-in because ordinary CI hosts do not include FFmpeg. They execute real encoding, preserved-source hashing, asset insertion, active cancellation/process exit, abrupt-owner termination and denial controls. Ordinary CI runs the policy/SDK/ACP tests without external binaries. The fixture script exercises the public CLI and creates source MP4, a **local, not Higgsfield-generated** supporting fixture, real export/preview, 32-frame chronological contact sheet, ffprobe JSON, source hashes and audio-volume log. Sine audio proves retention of an audio signal, not authentic human voice. Genuine user footage, actual downloaded Higgsfield asset, nominated GPU and live subscription acceptance remain separate human/provider gates.

package/bin/crew-studio.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { register } from "tsx/esm/api";
+register();
+const { studioMain } = await import("../src/studio-cli.ts");
+process.exitCode = await studioMain(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crew-runner",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "Runs a CrewCortex assistant on your own computer using the Claude Code or Codex app you already signed in to.",
   "keywords": [
@@ -20,6 +20,7 @@
     "src/**/*.ts",
     "!src/**/*.test.ts",
     "README.md",
+    "STUDIO.md",
     "LICENSE"
   ],
   "engines": {
@@ -32,8 +33,10 @@
   "dependencies": {
     "@agentclientprotocol/codex-acp": "^2.1.1",
     "@agentclientprotocol/sdk": "^1.7.0",
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "@zed-industries/claude-agent-acp": "^0.23.1",
-    "tsx": "^4.20.0"
+    "tsx": "^4.20.0",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/node": "^26.6.3",

package/src/acp.ts

@@ -9,8 +9,35 @@ import { fileURLToPath } from "node:url";
 import * as acp from "@agentclientprotocol/sdk";
 import type { Claimed, RunEvent } from "./api.ts";
 import { promptFrom, type Outcome } from "./claude.ts";
+import { CLAUDE_DISALLOWED, CLAUDE_ENV, CLAUDE_PERMISSIONS, CLAUDE_TOOLS } from "./computer.ts";
 import { DISABLED_FEATURES } from "./codex.ts";
 import { claudeExecutable, killTree } from "./spawn.ts";
+import { assertGrant, openStudio, type StudioGrant } from "./studio.ts";
+import { MEDIA_TOOLS } from "./studio-mcp.ts";
+
+const STUDIO_NAME = "crew_studio";
+function studioServer(grant: StudioGrant): acp.McpServerStdio {
+  assertGrant(grant);
+  return { name: STUDIO_NAME, command: process.execPath, args: [fileURLToPath(new URL("../bin/crew-studio.mjs", import.meta.url)), "stdio", "--project", grant.root, "--expires", String(grant.expiresAt), "--allow-local-media"], env: [] };
+}
+export function mediaPermission(agent: AgentName, p: acp.RequestPermissionRequest, calls: ReadonlyMap<string, SeenCall>, grant?: StudioGrant): boolean {
+  if (!grant) return false;
+  try { assertGrant(grant); } catch { return false; }
+  if (agent === "claude") return MEDIA_TOOLS.some((tool) => p.toolCall.title === `mcp__${STUDIO_NAME}__${tool}`);
+  if (field(p._meta, "is_mcp_tool_approval") !== true || (p.toolCall.kind && p.toolCall.kind !== "execute")) return false;
+  const seen = calls.get(p.toolCall.toolCallId);
+  const raw = seen ? seen.rawInput : p.toolCall.rawInput;
+  const server = field(raw, seen ? "server" : "serverName");
+  return server === STUDIO_NAME && MEDIA_TOOLS.some((tool) => field(raw, "tool") === tool);
+}
+export function studioCodexConfig(pkg: RunPkg, memberServers: readonly string[], grant: StudioGrant): Record<string, unknown> {
+  // Codex recursively merges member settings. Do not re-enable an existing entry:
+  // inherited env/env_vars/cwd could execute member code in our owned stdio bridge.
+  if (memberServers.includes(STUDIO_NAME)) throw new Error("Rename the member crew_studio MCP server before enabling studio");
+  const cfg = codexConfig(pkg, memberServers);
+  const bridge = studioServer(grant);
+  return { ...cfg, mcp_servers: { ...(cfg.mcp_servers as Record<string, unknown>), [STUDIO_NAME]: { enabled: true, command: bridge.command, args: bridge.args } } };
+}
 
 // One Agent Client Protocol client for both vendors. We spawn a small adapter (claude-agent-acp or codex-acp) that
 // wraps the member's own signed-in app. The adapter holds the login. We never read the vendors' files, never call
@@ -84,9 +111,10 @@ const LIST_TIMEOUT_MS = 20_000;
 export function memberMcpNames(listJson: string): string[] {
   const list: unknown = JSON.parse(listJson);
   if (!Array.isArray(list)) throw new Error("codex mcp list returned no list");
-  // Already-off servers are left alone: some have no config entry, and a bare { enabled } entry would not load.
+  // Already-off servers stay off, except our reserved name: even a disabled
+  // entry can carry inherited stdio settings and must be detected as a collision.
   return list
-    .filter((s) => field(s, "enabled") !== false)
+    .filter((s) => field(s, "enabled") !== false || field(s, "name") === STUDIO_NAME)
     .map((s) => field(s, "name"))
     .filter((n): n is string => typeof n === "string" && n !== MCP_NAME);
 }
@@ -162,7 +190,10 @@ export function decide(
   p: acp.RequestPermissionRequest,
   calls: ReadonlyMap<string, SeenCall> = new Map(),
 ): { allowed: boolean; optionId: string | null } {
-  const allowed = spec.allowTool(p, calls);
+  return optionFor(p, spec.allowTool(p, calls));
+}
+
+export function optionFor(p: acp.RequestPermissionRequest, allowed: boolean): { allowed: boolean; optionId: string | null } {
   const pick = (kinds: string[], ids: string[]): Option | undefined =>
     p.options.find((o) => kinds.includes(o.kind)) ?? p.options.find((o) => ids.includes(o.optionId));
   // Always the one-shot option, never "always": the next call is judged on its own.
@@ -178,6 +209,20 @@ export type RunAcpOptions = {
   bin?: string;
   // Abort = run cancelled: session/cancel first, kill after a short grace.
   signal?: AbortSignal;
+  // Explicit host-selected project only. Never read this authority from a cloud task/model.
+  studio?: StudioGrant;
+  // Standalone member-authored local session: no cloud tools or events.
+  studioOnly?: boolean;
+  // Computer mode (@mac, Claude Code only): Claude Code's own tools, from a scratch folder the caller owns, every tool request
+  // judged by `decide` (which may wait for the owner's card). No CrewCortex MCP server: the reply is the only output.
+  computer?: ComputerSession;
+};
+
+export type ComputerSession = {
+  cwd: string;
+  additionalDirectories: string[];
+  systemPrompt: string;
+  decide: (p: acp.RequestPermissionRequest, calls: ReadonlyMap<string, SeenCall>) => Promise<boolean>;
 };
 
 type Sink = (events: RunEvent[]) => Promise<void>;
@@ -185,16 +230,31 @@ type Sink = (events: RunEvent[]) => Promise<void>;
 const failed = (error: string, inputTokens = 0, outputTokens = 0): Outcome => ({ status: "failed", text: "", inputTokens, outputTokens, error });
 
 export async function runAcp(agent: AgentName, pkg: Claimed, sink: Sink, opts: RunAcpOptions): Promise<Outcome> {
-  const spec = AGENTS[agent];
+  const originalSpec = AGENTS[agent];
+  const grant = opts.studio ? Object.freeze({ ...opts.studio }) : undefined;
+  const spec = grant ? { ...originalSpec, allowTool: (p: acp.RequestPermissionRequest, calls: ReadonlyMap<string, SeenCall>) =>
+    (!opts.studioOnly && originalSpec.allowTool(p, calls)) || mediaPermission(agent, p, calls, grant) } : originalSpec;
+  if (opts.computer && (agent !== "claude" || grant)) return failed("runner_failed");
+  const computer = opts.computer;
   // Empty temp directory: even if a built-in tool were somehow on, there is nothing of the member's to touch.
-  const cwd = await mkdtemp(join(tmpdir(), "crew-run-"));
+  // Computer mode works in the caller's scratch folder instead, which the caller removes.
+  const cwd = computer ? computer.cwd : await mkdtemp(join(tmpdir(), "crew-run-"));
   let child: ReturnType<typeof spawn> | undefined;
   let timer: NodeJS.Timeout | undefined;
+  let ended = false;
   let flushTimer: NodeJS.Timeout | undefined;
   let graceTimer: NodeJS.Timeout | undefined;
   let onAbort: (() => void) | undefined;
   try {
+    if (grant) await openStudio(grant);
+    if (opts.studioOnly && !grant) throw new Error("Local studio consent required");
     const launch = opts.launch ?? spec.launch(pkg, { bin: opts.bin });
+    if (agent === "codex" && grant) {
+      const config = studioCodexConfig(pkg, listCodexMcp(), grant);
+      // Absence would merge the member's enabled `crew` back into Codex settings.
+      if (opts.studioOnly) (config.mcp_servers as Record<string, unknown>)[MCP_NAME] = { enabled: false };
+      launch.env = { ...launch.env, CODEX_CONFIG: JSON.stringify(config) };
+    }
     // POSIX: detached makes the adapter lead a process group, so killTree ends it and the app it started. Windows uses taskkill.
     child = spawn(launch.command, launch.args, { cwd, stdio: ["pipe", "pipe", "ignore"], detached: process.platform !== "win32", windowsHide: true, env: { ...process.env, ...launch.env } });
     const proc = child;
@@ -203,10 +263,34 @@ export async function runAcp(agent: AgentName, pkg: Claimed, sink: Sink, opts: R
       proc.on("close", () => reject(new Error("runner_failed")));
     });
     exited.catch(() => undefined);
+    // The run clock. It stops while a computer-mode request waits on `decide` (the owner's card, which expires on its own timer),
+    // so time the owner takes to answer never counts toward the run limit. Claude Code may ask about parallel tool calls at once,
+    // hence a count of pending decisions rather than a flag. Computer mode has no MCP server, so no run token can lapse meanwhile.
+    let left = opts.timeoutMs;
+    let since = 0;
+    let waiting = 0;
+    let expire: () => void = () => undefined;
     const timedOut = new Promise<never>((_, reject) => {
-      timer = setTimeout(() => reject(new Error("runner_timeout")), opts.timeoutMs);
+      expire = () => reject(new Error("runner_timeout"));
     });
     timedOut.catch(() => undefined);
+    const resume = () => {
+      if (ended) return; // a decision that outlived the run
+      since = Date.now();
+      timer = setTimeout(expire, left);
+    };
+    const paused = async <T>(work: () => Promise<T>): Promise<T> => {
+      if (waiting++ === 0) {
+        clearTimeout(timer);
+        left -= Date.now() - since;
+      }
+      try {
+        return await work();
+      } finally {
+        if (--waiting === 0) resume();
+      }
+    };
+    resume();
 
     // Serialised sink, text coalesced so a token stream is not one HTTP call per chunk.
     let chain: Promise<void> = Promise.resolve();
@@ -260,8 +344,8 @@ export async function runAcp(agent: AgentName, pkg: Claimed, sink: Sink, opts: R
 
     const session = acp
       .client({ name: "crew-runner" })
-      .onRequest(acp.methods.client.session.requestPermission, (ctx) => {
-        const d = decide(spec, ctx.params, calls);
+      .onRequest(acp.methods.client.session.requestPermission, async (ctx) => {
+        const d = computer ? optionFor(ctx.params, await paused(() => computer.decide(ctx.params, calls)).catch(() => false)) : decide(spec, ctx.params, calls);
         return { outcome: d.optionId ? { outcome: "selected" as const, optionId: d.optionId } : { outcome: "cancelled" as const } };
       })
       .connectWith(stream, async (ctx) => {
@@ -272,8 +356,16 @@ export async function runAcp(agent: AgentName, pkg: Claimed, sink: Sink, opts: R
         });
         const request: acp.NewSessionRequest = {
           cwd,
-          mcpServers: spec.acpMcp ? [{ type: "http", name: MCP_NAME, url: pkg.mcp_url, headers: [{ name: "Authorization", value: `Bearer ${pkg.token}` }] }] : [],
-          _meta: spec.sessionMeta(pkg),
+          mcpServers: computer ? [] : spec.acpMcp ? [
+            ...(!opts.studioOnly ? [{ type: "http" as const, name: MCP_NAME, url: pkg.mcp_url, headers: [{ name: "Authorization", value: `Bearer ${pkg.token}` }] }] : []),
+            ...(grant ? [studioServer(grant)] : []),
+          ] : [],
+          _meta: computer
+            ? { systemPrompt: computer.systemPrompt, claudeCode: { options: {
+              settingSources: [], strictMcpConfig: true, additionalDirectories: computer.additionalDirectories,
+              settings: { permissions: CLAUDE_PERMISSIONS }, tools: CLAUDE_TOOLS, disallowedTools: CLAUDE_DISALLOWED, env: CLAUDE_ENV,
+            } } }
+            : spec.sessionMeta(pkg),
         };
         const active = await ctx.buildSession(request).start();
         try {
@@ -314,11 +406,12 @@ export async function runAcp(agent: AgentName, pkg: Claimed, sink: Sink, opts: R
   } catch {
     return failed("runner_failed");
   } finally {
+    ended = true;
     clearTimeout(timer);
     clearTimeout(flushTimer);
     clearTimeout(graceTimer);
     if (onAbort) opts.signal?.removeEventListener("abort", onAbort);
     if (child) killTree(child);
-    await rm(cwd, { recursive: true, force: true });
+    if (!computer) await rm(cwd, { recursive: true, force: true });
   }
 }

package/src/api.ts

@@ -1,3 +1,4 @@
+import { CARD_DETAIL_MAX } from "./computer.ts";
 import type { Stored } from "./store.ts";
 
 export type Claimed = {
@@ -6,8 +7,14 @@ export type Claimed = {
   messages: { role: string; content: unknown }[];
   mcp_url: string;
   token: string;
+  // Only on a computer-mode claim (crew-runner start --computer): the workspace whose folder the run uses.
+  computer?: { workspace_slug: string };
 };
 
+export type ClaimMode = "default" | "computer";
+// "approved_task": approved with "Allow for this task" (the server sends status approved, scope task).
+export type CardAnswer = "pending" | "approved" | "approved_task" | "rejected" | "expired";
+
 export type RunEvent =
   | { type: "text"; text: string }
   | { type: "step"; kind: "model" | "tool"; name?: string; input?: unknown; output?: unknown };
@@ -35,19 +42,46 @@ export function createApi(cfg: Stored, fetchImpl: typeof fetch = fetch) {
       return (await call("ping", {})).ok;
     },
     // null = no work (204). Throws on auth or server errors so the loop can back off.
-    async claim(signal?: AbortSignal): Promise<Claimed | null> {
-      const res = await call("claim", {}, signal);
+    async claim(signal?: AbortSignal, mode: ClaimMode = "default"): Promise<Claimed | null> {
+      const res = await call("claim", mode === "computer" ? { mode } : {}, signal);
       if (res.status === 204) return null;
       if (!res.ok) throw new Error(`claim failed (${res.status})`);
       return (await res.json()) as Claimed;
     },
+    // Throws when the server did not take them (computer mode then refuses the step it could not record).
     async events(runId: string, events: RunEvent[]): Promise<void> {
       if (events.length === 0) return;
-      await call("events", { run_id: runId, events });
+      const res = await call("events", { run_id: runId, events });
+      if (!res.ok) throw new Error(`events failed (${res.status})`);
     },
     async complete(body: Complete): Promise<void> {
       await call("complete", body);
     },
+    // Computer mode: a confirmation card for the owner. Null when it could not be asked (the step is then refused).
+    // `grant`: the card may offer "Allow for this task" for later steps of the same kind in this run.
+    async askOwner(runId: string, category: string, detail: string, grant?: string): Promise<string | null> {
+      // The policy refuses anything longer than a card shows; never cut what the owner approves.
+      if (detail.length > CARD_DETAIL_MAX) return null;
+      const res = await call("approval", { run_id: runId, category, detail, ...(grant ? { grant } : {}) });
+      if (!res.ok) return null;
+      const body = (await res.json()) as { approval_id?: unknown };
+      return typeof body.approval_id === "string" ? body.approval_id : null;
+    },
+    async ownerAnswer(runId: string, approvalId: string): Promise<CardAnswer | null> {
+      const res = await call("approval/status", { run_id: runId, approval_id: approvalId });
+      if (!res.ok) return null;
+      const body = (await res.json()) as { status?: unknown; scope?: unknown };
+      if (body.status === "approved" && body.scope === "task") return "approved_task";
+      return body.status === "pending" || body.status === "approved" || body.status === "rejected" || body.status === "expired" ? body.status : null;
+    },
+    // Computer mode: is this run still running? false only when the server says so (the owner's off switch); null when
+    // it could not tell (network, an older server), which never stops a run.
+    async alive(runId: string): Promise<boolean | null> {
+      const res = await call("alive", { run_id: runId });
+      if (!res.ok) return null;
+      const body = (await res.json()) as { running?: unknown };
+      return typeof body.running === "boolean" ? body.running : null;
+    },
     async revoke(): Promise<boolean> {
       return (await call("revoke", {})).ok;
     },

package/src/cli.ts

@@ -1,10 +1,12 @@
 import { createHash, randomBytes } from "node:crypto";
 import { spawn } from "node:child_process";
-import { createApi } from "./api.ts";
+import { createApi, type ClaimMode, type RunnerApi } from "./api.ts";
 import { runAcp } from "./acp.ts";
+import { runComputer } from "./computer-run.ts";
 import { checkClaude, runClaude, type Check } from "./claude.ts";
 import { checkCodex, runCodex } from "./codex.ts";
 import { loop, RUN_TIMEOUT_MS, type Runner } from "./loop.ts";
+import { pairConfirmationCode } from "./pair-code.ts";
 import * as store from "./store.ts";
 
 const DEFAULT_APP_URL = "https://app.crewcortex.com";
@@ -35,6 +37,7 @@ async function login(appUrlArg: string | undefined): Promise<number> {
   const code = createHash("sha256").update(token).digest("hex");
   const url = `${appUrl}/runner/link?code=${code}`;
   console.log(`Open this page, sign in and confirm this computer:\n${url}`);
+  console.log(`\nConfirmation code: ${pairConfirmationCode(code)}\nOnly approve if the page shows this exact code. If it differs, or you did not run this command, close the page.`);
   openBrowser(url);
   const api = createApi({ appUrl, token });
   const until = Date.now() + LINK_WAIT_MS;
@@ -103,24 +106,45 @@ async function start(args: string[]): Promise<number> {
     console.error("Not linked. Run `npx crew-runner@latest login` first.");
     return 1;
   }
+  if (args.includes("--computer")) return startComputer(cfg);
   const chosen = await chooseCli(args);
   if ("error" in chosen) {
     console.error(chosen.error);
     return 1;
   }
+  const cli = CLIS[chosen.name];
+  return serve(cfg, [`Ready. ${cli.label} ${chosen.version}. Waiting for runs. Press Ctrl+C to stop.`], () => cli.runner(cli.bin()), "default");
+}
+
+// Computer mode: only this member's @mac runs, with Claude Code's own tools in the allowed folders. An ordinary
+// `start` never receives them. Claude Code only (Codex is not supported here).
+async function startComputer(cfg: store.Stored): Promise<number> {
+  const bin = CLIS.claude.bin();
+  const check = await CLIS.claude.check(bin);
+  if (!check.ok) {
+    console.error(check.message);
+    return 1;
+  }
+  return serve(cfg, [
+    `Computer mode. Claude Code ${check.version}. Works in ~/CrewCortex/<workspace>, ~/Downloads and ~/.cursor/dev projects.`,
+    "Deletes, git push, sends, payments and changes outside those folders wait for your yes in CrewCortex. Press Ctrl+C to stop.",
+  ], (api) => (pkg, sink, signal) => runComputer(api, pkg, sink, { bin, timeoutMs: RUN_TIMEOUT_MS, signal }), "computer");
+}
+
+// Both modes: check the device, then claim and run until Ctrl+C (or SIGTERM, or SIGBREAK on Windows).
+async function serve(cfg: store.Stored, banner: string[], runnerFor: (api: RunnerApi) => Runner, mode: ClaimMode): Promise<number> {
   const api = createApi(cfg);
   if (!(await api.ping().catch(() => false))) {
     console.error("The server did not accept this device. Run `npx crew-runner@latest login` again.");
     return 1;
   }
-  const cli = CLIS[chosen.name];
-  console.log(`Ready. ${cli.label} ${chosen.version}. Waiting for runs. Press Ctrl+C to stop.`);
+  for (const line of banner) console.log(line);
   const ac = new AbortController();
   process.once("SIGINT", () => ac.abort());
   process.once("SIGTERM", () => ac.abort());
   // Windows sends SIGBREAK (Ctrl+Break, closing the console window) instead of SIGTERM.
   if (process.platform === "win32") process.once("SIGBREAK", () => ac.abort());
-  await loop(api, cli.runner(cli.bin()), ac.signal, (m) => console.log(m));
+  await loop(api, runnerFor(api), ac.signal, (m) => console.log(m), mode);
   return 0;
 }
 
@@ -152,10 +176,11 @@ async function logout(): Promise<number> {
 
 export async function main(argv: string[]): Promise<number> {
   const [cmd, arg] = argv;
+  if (cmd === "studio") return (await import("./studio-cli.ts")).studioMain(argv.slice(1));
   if (cmd === "login") return login(arg);
   if (cmd === "start") return start(argv.slice(1));
   if (cmd === "status") return status();
   if (cmd === "logout") return logout();
-  console.log("Usage: crew-runner <login [app url] | start [--cli claude|codex] | status | logout>");
+  console.log("Usage: crew-runner <login [app url] | start [--cli claude|codex] | start --computer | status | logout>");
   return cmd ? 2 : 0;
 }