stage-11-agentics/c11/c11-hotload

c11 hotload

How to build, reload, and tail a c11 dev instance.

Default: build on Atlas

From a provisioned delegator worktree on the laptop:

./scripts/remote-build.sh --tag <your-branch-slug>

This runs no local xcodebuild. It bundles the exact parent/submodule commits, overlays tracked modifications and untracked non-ignored files with content hashes, and retrieves the tagged Debug app plus logs and result.json under build-remote/<invocation>/. Tracked deletions, executable modes and symlinks are preserved. Dirty submodules are refused: commit and pin their changes first. Initialize the required submodules with git submodule update --init --recursive ghostty vendor/bonsplit; do not run setup.sh on the laptop to build GhosttyKit.

Staging uploads only the commits Atlas lacks: Atlas keeps one mirror per repository (~/c11-builds/mirrors/), and each bundle excludes everything reachable from a head the mirror holds, so a head whose parent was built before sends a few KB; with no shared base it falls back to a full bundle. The client prints staged <MB> in <s>; bundles: … per run, and Atlas checks out the requested SHAs from the mirror and verifies them before building.

Atlas uses process-scoped Xcode 26.3 (/Applications/Xcode-26.3.app/Contents/Developer) and Zig 0.15.2 (~/zig-0.15.2). C11_REMOTE_HOST defaults to atlas; --host overrides it. C11_REMOTE_DEVELOPER_DIR and C11_REMOTE_ZIG_DIR override paths but the versions are checked. No global Xcode selection or credential provisioning happens.

The Atlas route has two slots with separate per-tag caches: slot 1 is reserved for the PR Swift poller; owner gates and all other Atlas builds share slot 2, one at a time. At normal load, one poller build and one fleet build may overlap. After one-minute load stays above 40 for 60 seconds, starts serialize: a fleet build takes slot 2 only while slot 1 is idle, then holds slot 1 as a guard; a poller build takes slot 1 only while slot 2 is idle, then holds slot 2 as a guard. Both slots stay held through the build, so new builds wait; builds admitted before load rises may finish. Same-tag requests serialize. The ordinary laptop with-build-lock.sh remains single-slot. Atlas builds outside this route must be coordinated with its capacity.

GitHub's native CI for main runs on the free GitHub-hosted macos-15 runner. PRs keep the cheap Ubuntu lane. ci-hourly.yml ("CI main (macOS)") runs on an hourly schedule and by dispatch. One build runs at a time, never cancelled, with one pending run that each newer request replaces. An admitted run tests the ref's tip at that moment, not its trigger. A pass posts a CI main (macOS) commit status on the tested commit; a run whose tip already has one skips. A failed tip lookup fails the run; a failed green-record lookup builds. The independent Atlas main backstop posts c11/main-atlas, shares slot 1 with the PR poller, and yields to PR work. See docs/c11-main-backstop.md for its gated install and lifecycle commands. ci-macos-compat.yml and build-ghosttykit.yml run hourly/manual against main. Each heavy workflow command uses scripts/with-build-lock.sh; the process-scoped Xcode/Zig setup does not install into /usr/local or change global Xcode state. No self-hosted runner is registered or used in this PR. An access-restricted runner is a follow-up that requires Atin to decide the repository, trigger, and network boundary.

For landing, the Merge Captain gates the exact PR head with fresh review, the cheap PR checks, and an Atlas exact-head remote build for every Swift or native change after the branch includes current origin/main. Worktrees share refs, so a fetch from any worktree moves origin/main under a gate in progress: after the gate, run git merge-base --is-ancestor origin/main HEAD again before reporting the head as current. (1.7.8 run: a lesson of the mailbox-pickup seat.) A docs-only change is exempt only when the diff is limited to documentation or prose and contains no Swift, native workflow, script, project, submodule, test, or build-input change. The main backstop result is the post-merge authority; red main is fixed forward. For Ghostty pointer changes, manually dispatch Build GhosttyKit on the internal bump branch, wait for its prerelease non-latest artifact and bot checksum commit, refresh PR checks at that bot-created head, then run the exact-head Atlas gate before landing. The workflow keys on the ghostty SHA, so a Bonsplit-only pointer bump needs no dispatch.

Remote failure returns nonzero, retrieves available logs, and preserves the previous local app without launching it. The default stages only; it never launches or restarts c11. Successful Debug retrieval rewrites only the app's host-specific daemon/repository paths and ad-hoc signs it; result.json records both Atlas and client executable hashes. Launch with QA startup dialogs suppressed only when a launch is authorized:

./scripts/launch-tagged-automation.sh <tag> --qa fresh
# Equivalent convenience on an authorized client:
./scripts/remote-build.sh --tag <tag> --launch

Atlas appends one completed owner-gate measurement to ~/c11-builds/gates.jsonl. Its started timestamp includes the local timezone offset and precedes slot admission; test_args records the effective selectors and automatic skips.

In the c11 1.0 run, packaged-app validation and computer use run on Atlas only. The laptop receives the app but does not launch it. On Atlas, launch the retained tagged app using its source checkout's launch-tagged-automation.sh. Never launch an untagged c11 DEV app.

Tagged builds can run behind production during socket work: c11 holds a user-initiated activity while a socket client is connected and for 60 seconds after the last disconnect. Shell telemetry sends a socket report every 45 seconds, so an open shell keeps the activity held and the idle release rarely fires; the activity still allows system idle sleep.

A command for Atlas that is more than one step goes in a file, run as ssh atlas bash -s < file. A quoted multi-command string (ssh atlas "cd … && rm … && python3 …") cannot be checked by the permission prompt, so the seat stalls on a prompt nobody answers. (1.7.8 run: a seat sat blocked on a quoted remote `sh -c`.) Guest commands follow the same rule through the shared folder; see Guest hygiene in the c11-computer-use skill.

Live proofs that need real agent panels (Claude Code, Codex, Grok receiving mail or running hooks) run in an Atlas sandbox guest: scripts/sandbox-up.sh <run-id> <tagged.app> --agents claude,codex,grok, then scripts/sandbox-agent.sh <run-id> launch|c11|screen …, then sandbox-down and sandbox-agent.sh <run-id> verify-clean. The retained Atlas copy of a remote build is under ~/c11-builds/<tag>/artifacts/<invocation>/; running the sandbox scripts on Atlas with C11_SANDBOX_HOST=local against it skips the upload from the laptop. Details: the c11-computer-use skill.

Fresh-process initialization check

When changing hostless Workspace/Ghostty initialization or the test bootstrap, run a fresh, narrowed invocation as well as the broader suite. Another test may have initialized AppKit before the affected class in a combined run:

./scripts/remote-build.sh --tag <seat> --mode test -- -only-testing:c11LogicTests/PanelLivenessDeriverTests

Isolate activity-history validation

C11_ACTIVITY_HISTORY_DIRECTORY=/absolute/owned/path is a validation hook, not a user storage setting. Pass it at launch with launch-tagged-automation.sh <tag> --qa fresh --env C11_ACTIVITY_HISTORY_DIRECTORY=/absolute/owned/path. The app, Messages, mailbox receipts and offline readers share that path; relative values are ignored. The environment is captured once per process. Use synthetic fixtures and preserve production history. Details and evidence requirements: docs/validation/c11-349/README.md.

Remote variants

Test selection uses the safe per-PID socket wrapper. Pass -resultBundlePath <relative-path>.xcresult to retrieve an xcresult. Signing/notarization for publication remains in GitHub Actions, with named approval of exact signed bytes; this route does not copy credentials. For c11Tests and c11LogicTests test runs, remote-build.sh reads scripts/host-test-quarantine.tsv and automatically skips both all and atlas rows, logging each scope. An exact quarantined method named in -only-testing:<target>/<Class>/testMethod runs without the automatic skip. Use --no-host-quarantine to disable automatic skips.

The c11-logic scheme uses eight parallel workers through remote-build.sh. scripts/test-unit-local.sh enables parallel testing when C11_TEST_PARALLEL_WORKERS is set; the Atlas route sets it to eight. ci-hourly.yml uses three workers on macos-15.

Existing on-Atlas entry points

A person working on Atlas may use ./scripts/reload.sh --tag <tag> to build and launch Debug, or ./scripts/reloads.sh --tag <tag> for staging. For coordinated builds prefer the remote route, including from an SSH client. Both scripts support --no-launch to stage and sign without CLI-shim/socket writes, quits or launches. Their default remains launch. Never run reloadp.sh over another agent's session: it terminates the running production app.

A clean quit preserves agent resume; do not pre-kill the app before a reload. Use QA fresh/resume deliberately for validation.

Driving a Release/staging build over the socket

A Release/staging build launched by reloads.sh binds its own socket in automation mode, so a CLI in another local shell can write to it when pointed at C11_SOCKET_PATH=/tmp/c11-<slug>.sock, where the slug is the tag lowercased with every non-alphanumeric run collapsed to a hyphen (--tag rel-v0.65.2 binds /tmp/c11-rel-v0-65-2.sock; the script prints the exact path at launch). The script also clears the launching panel's inherited c11 identity before opening the app. For socket-level validation during development, a tagged Debug build uses the same externally reachable automation mode via C11_SOCKET=/tmp/c11-debug-<tag>.sock.

QA / automation launch (suppress the startup dialogs)

When a change needs the operator to see or try it, launch the tagged build yourself (./scripts/launch-tagged-automation.sh <tag> --qa fresh), seed it with whatever the check needs through its socket, and report that it is open. Don't ask permission to launch a tagged build.

A normal launch can present three blocking dialogs before the GUI is usable: the Agent Skills install/update sheet, the "Resume previous session?" picker (shown only when Settings > On Launch is "Ask which workspaces to resume" or Option is held at launch; the default resumes silently), and, when notifications are already off, the "Turn on notifications for c11" sheet. For automated QA they're just modals in the way. The C11_QA_LAUNCH env var suppresses all three and makes the resume decision deterministic: