Skip to content
atrinikPublic

About

Atrinik multi-repository development workspace and component coordinator

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

32 stars

Watchers

10 watching

Forks

Repository files navigation

Atrinik development workspace

Coverage

This repository is a small, MIT-licensed coordinator for Atrinik's physical repositories and logical components. Each checkout remains a normal Git repository with its own branches, remotes, commits, and worktrees. A logical component may occupy that checkout's root or a declared source directory. The coordinator keeps the MIT replacement stack and the opt-in playable classic stack as explicit, coherent sets. It supplies one command for safe initialization and synchronization, composes worktrees into stack-aware review profiles, builds components whose contracts are available, and shares persistent server state safely.

No checkout is a submodule. Primary repositories are ignored, independent Git checkouts directly beside this README (./client, ./server, ./classic, ./observatory, ./deploy-control, ./web-platform, ./pathfinder, and so on). The atrinik/classic checkout at ./classic contains the logical classic-client, classic-server, classic-editor, classic-libatrinik, and classic-protocol source roots. Generated worktrees, builds, profiles, and default state live under the ignored workspace/ directory.

Shared tooling and Classic support

Shared renderer, world toolkit and editor development belongs to Seraphina Studios' Tilewright projects. Atrinik owns its game rules, content and adapters. Classic remains an active development and release target while later server/client migration is prepared. See ownership and reconciliation for transferred repositories, crate compatibility and the staged migration work.

Source changes and pull requests

Use source delivery for new code, tests and guidance: an owned worktree, scoped collision checks, applicable validation and independent review. The start/resume helper supports known interrupted source edits; a bounded PR watcher reports check changes without repeated manual polling. Broken delivery tooling can be repaired against isolated fixtures without admitting live resources. Existing bound deliveries and managed build/runtime operations retain their original helper, lease and recovery contracts.

Requirements

  • Python 3.11 or newer and Git
  • Native Windows support uses Python's Windows path handling and PowerShell or Command Prompt; WSL and the devcontainer are not required for the supported wrapper surface below
  • The GitHub CLI (gh) authenticated for GitHub operations
  • CMake, Ninja, and the dependencies required by the selected component when building the classic native stack
  • Node.js 20 or newer when building metaserver-worker

Native Windows wrapper support

The coordinator can be invoked directly from a native Windows checkout with python .\atrinik .... The supported Windows surface includes CLI import and help, manifest/provenance/supply-chain validation, replacement or Classic initialization and synchronization, repository status, profile inspection and publication, path resolution, and worktree inventory. For example:

python .\atrinik manifest validate
python .\atrinik init --with classic
python .\atrinik status --json
python .\atrinik profile show classic --json

Native Windows locks use the kernel LockFileEx API, and child Git processes receive the active lock handles. JSON publication uses an atomic replacement and FlushFileBuffers; path and junction components are rejected. Windows does not expose the POSIX descriptor-relative directory and process-identity facilities used by the wrapper's supervised topology, build publication, cleanup, migration, state, scenario, and direct-run workflows. Those commands return a stable capability diagnostic naming Linux/WSL2 or the documented Windows package workflow rather than weakening locking, cleanup, or topology isolation. The complete support matrix is maintained in docs/ARCHITECTURE.md.

Windows host and pinned-container workflow

Use an owned native Linux worktree for development and delivery coordination. Short-lived pinned containers supply the build toolchains; windows-cross is only the Classic Windows toolchain, and native Windows supplies final D3D12 execution. Do not mix the replacement/default and Classic providers.

Surface Shell and working directory Owns Proof or handoff
Native Windows host PowerShell; native checkout for repository-only commands Native git and gh authentication, optional SSH signing, commits/pushes, supported repository-management wrapper commands, and final Windows execution GitHub state and native runtime evidence; never the authoritative delivery ledger
Owned native Linux worktree (execution contract) POSIX shell; exact bound local worktree; actual passwd user Coordinator probe, Git/review, delivery ledger/leases/CAS and source edits native-linux after complete live proof
Short-lived pinned Linux build worker POSIX shell; same absolute source/worktree paths Compilation and toolchain tests with isolated reusable caches Build evidence only; no delivery authority
Pinned windows-cross devcontainer (.devcontainer/windows-cross/devcontainer.json) POSIX shell; /workspaces/atrinik; vscode Classic Windows cross-build and package commands only; no delivery ledger, worktree authority, or GUI Windows review ZIP plus SHA-256; not runtime proof
Native Windows runtime PowerShell; a new private extracted bundle directory Package hash verification, the existing package-smoke script, D3D12 qualification, bounded logs/evidence, and exact-run cleanup Native Windows package/GPU result; not a Linux-client result

The host may commit or push only from its exact owned source worktree, or the delivery-bound worktree reported by ./atrinik worktree list for an existing bound delivery; never use the primary checkout for a delivery edit or commit. Never mount a private signing key into a container. Do not run native CMake, Ninja, MSVC, or a graphical client as part of a pinned-container delivery. Conversely, do not run Linux-only build, topology, state, scenario, cleanup, or ledger operations from PowerShell. A Windows-only package uses its packaged Classic server/client and does not configure a Linux client unless that Linux client is explicitly selected for a separate test.

Select and initialize

On a native Windows checkout, use only the supported repository-management surface for host inspection:

Set-Location D:\Dev\atrinik
python .\atrinik --help
python .\atrinik manifest validate
python .\atrinik init --with classic
python .\atrinik status --json

For bound delivery or Linux-only resource coordination, use the owned native Linux worktree and continue only when the probe reports native-linux with authoritative: true:

python3 scripts/atrinik_coordinator_context.py --json
./atrinik manifest validate
./atrinik init --with classic
./atrinik status --json
./atrinik profile show classic --json

Build, test, and capture bounded logs

Run the Classic build and tests in a short-lived pinned CPU worker, using the exact planned profile and resource intent:

./atrinik build all --profile classic --test

For an isolated supervised run, use one exact topology/state coordinate and bounded output; do not use --follow for automated evidence:

./atrinik ps REVIEW_TOPOLOGY --json
./atrinik logs REVIEW_TOPOLOGY server --tail 100

Cross-package and hand off to Windows

The selected Classic state must be stopped and must have been started at least once. Run this in the ordinary coordinator or directly in windows-cross:

./atrinik down REVIEW_TOPOLOGY
./atrinik package windows \
  --profile REVIEW_PROFILE \
  --state REVIEW_STATE \
  --output build/packages/review-windows.zip \
  --json
sha256sum build/packages/review-windows.zip

Copy the ZIP and its printed digest to Windows through a private handoff. The ZIP contains server data, credentials, and the private QUIC identity; never upload it to an issue, pull request, CI artifact, or release.

$Package = (Resolve-Path -LiteralPath .\review-windows.zip).Path
$ExpectedSha256 = "COPY_SHA256_FROM_PACKAGE_OUTPUT"
$ActualSha256 = (Get-FileHash -Algorithm SHA256 -LiteralPath $Package).Hash.ToLowerInvariant()
if ($ActualSha256 -ne $ExpectedSha256) { throw "Review ZIP digest mismatch" }
$ArtifactRoot = Join-Path $env:TEMP ("atrinik-review-" + [Guid]::NewGuid().ToString("N"))
$EvidenceRoot = Join-Path $ArtifactRoot "evidence"
New-Item -ItemType Directory -Path $EvidenceRoot -Force | Out-Null
New-Item -ItemType Directory -Path (Join-Path $EvidenceRoot "commands") -Force | Out-Null
New-Item -ItemType Directory -Path (Join-Path $EvidenceRoot "logs") -Force | Out-Null
Expand-Archive -LiteralPath $Package -DestinationPath $ArtifactRoot

Run native Windows smoke and evidence validation

Keep the matching Classic source checkout at the selected revision for the existing smoke and qualification scripts. The package smoke is authoritative for the packaged server/client lifecycle; a Linux graphical run is not a substitute:

$Revision = "BUNDLE_MANIFEST_REVISION"
$ClassicRoot = "MATCHING_CLASSIC_SOURCE_ROOT"
$Smoke = Join-Path $ClassicRoot "tools\ci\smoke_windows_review_bundle.ps1"
& $Smoke -Package $Package -Revision $Revision `
  1> (Join-Path $EvidenceRoot "commands\native-package-smoke.stdout") `
  2> (Join-Path $EvidenceRoot "commands\native-package-smoke.stderr")
$SmokeExitCode = $LASTEXITCODE
if ($SmokeExitCode -ne 0) { throw "Native Windows package smoke failed" }

Run the existing D3D12 qualification path from docs/WINDOWS_GPU_PREFLIGHT.md, retain only sanitized, bounded stdout/stderr and redacted client/server logs, and validate the six-command evidence record:

python3 scripts/validate_windows_gpu_evidence.py `
  (Join-Path $ArtifactRoot "evidence.json") `
  --root $ArtifactRoot
if ($LASTEXITCODE -ne 0) { throw "Evidence contract rejected the preflight" }

The evidence paths remain relative to evidence/; the validator enforces the bounded, secret-free contract. Keep Linux-only coordinator failures separate from an independently passed native Windows package/runtime result.

Preview cleanup and troubleshooting

The wrapper cleanup commands are maintenance previews, not process containment. Never use --apply as part of this handoff. After the smoke and qualification paths have stopped and contained both packaged processes, remove only the exact private extraction directory when process ownership is certain:

./atrinik cleanup --scope all --older-than 7 --dry-run --json
./atrinik cleanup --scope topologies --older-than 7 --dry-run --json
if (Test-Path -LiteralPath $ArtifactRoot) {
  Remove-Item -LiteralPath $ArtifactRoot -Recurse -Force
}
Symptom Bounded next action
.\atrinik is denied or treated as a script Use python .\atrinik ... for the supported native Windows wrapper surface.
CMake/Ninja/MSVC is missing on the host Use the pinned CPU build worker; use windows-cross for the Classic Windows package.
The coordinator probe reports native-windows, windows-cross, or unknown-or-unsafe Do not acquire delivery authority there; use the supported native Linux delivery host and rerun the probe.
Linux SDL/display or graphical launch fails Record a Linux-only diagnostic and use the Windows ZIP plus the existing native smoke/qualification path; do not relabel it as a Windows runtime failure.
Docker cannot safely mount the source or cache Preserve the unsafe path and diagnose the exact Docker source/cache namespace; never substitute an arbitrary primary or stale session path.
Package hash, manifest, process, or log evidence is missing Stop, retain the exact private run directory, and repeat the matching-revision preflight with bounded redacted evidence.

Related coordination: Docker volume/cache I/O (#538), Windows package separation (#535), tooling ledger (#536), and native Windows GPU preflight (#539).

Build plans and interrupted resource intent

Initialize the selected workspace with ./atrinik status --json before planning. Use ./atrinik build server --profile classic --test --plan --json to obtain the actual future build_root, source-generation paths, and plan_sha256 without publishing source generations or build output. Use build topology when the planned build must select the same complete client/server dependency closure and build key as a normal paired up:

./atrinik build topology --profile classic --plan --json
./atrinik build topology --profile classic \
  --expected-plan RETURNED_PLAN_SHA256

Record the returned identity in the delivery ledger before execution, then run the same build options with --expected-plan RETURNED_SHA256. Changed source bytes, Git identities, profile, manifest, providers, dependencies, or build options refuse before publication. Planning recognizes exact Git LFS pointer and hydrated payload bytes without running clean filters; custom clean filters are unsupported and fail closed. Topology summaries describe current selections; use the returned build plan, not a summary path, to reserve execution identity before the fenced build.

For an interrupted delivery with unbound build/state/topology plans, use the resource recovery procedure. The helper's explicit bound-wrapper resource_context selector supports resources in that worktree's default workspace while preserving its separate storage roots. Recovery preserves original intent, registered state, and proven residual output as nonreusable evidence. It does not initialize data, adopt output, or remove anything. Existing state data requires an exact prior named registration; unregistered directories remain uncertain and recovery refuses them. Retained reservations also block overlapping new resource slots and cleanup. Mutable build/state/topology admission also refuses retained coordinates; ledger release/archive remains unavailable while those reservations require preservation. New work uses fresh names and a fresh recorded build plan.

Bound issue/PR delivery coordinator

This section covers existing bound deliveries and operations that use the stateful delivery helpers. New source work follows source delivery.

Develop, run Git/GitHub, review and coordinate delivery in an owned native Linux worktree under the execution contract. Native Windows supports repository commands and D3D12 validation; it has no Linux delivery-ledger authority. Before initializing or mutating delivery evidence, run:

python3 scripts/atrinik_coordinator_context.py --json

New bound native delivery requires native-linux with authoritative: true, actual passwd identity, private Codex state, authenticated ownership and a dedicated safe worktree. Keep HOME unchanged and authentication selectors unset; use umask 077 for native delivery processes. The probe's entry_mode is diagnostic; markers never replace filesystem, worktree, ledger/CAS or lease proofs. native-windows, windows-cross and unknown-or-unsafe grant no delivery authority.

Application builds and toolchain-dependent checks use short-lived pinned CPU workers with isolated reusable caches. Worker exit preserves native delivery ownership. Reconnect re-proves context, actor, complete inventory, exact clean worktree, ledger/CAS and leases. Parallel deliveries use distinct worktree, cache, port and mutable-state coordinates; never adopt foreign or uncertain dirty work.

Already-bound historical containers retain only their existing compatibility contract, including canonical-linux proof and their exact image/mount/worktree/ledger identities. Copied or stale session markers are corroboration only. Preserve their resources; do not replace, remount or transfer a delivery implicitly. Codex never launches or controls VS Code, its executable/URI or GUI automation, and never nests a coordinator. A proposed authority change cannot authorize live resource operations.

Linux image upgrades

The ordinary Linux workspace uses the LLVM SDK in linux-build:1.18.0 from devcontainer revision 4af130578df18a1944880cd279c7f23afe9cc668. The immutable pin in .devcontainer/devcontainer.json is ghcr.io/atrinik/linux-build:1.18.0@sha256:613cf43ab07634db005a28462a009c4c28c90dccb1b5175e13e8072b6dfe8d72. The SDK release workflows 38155790600 and 38155792661 passed release metadata checks. Installed SDK collector and native artifact review remain separate acceptance evidence for this producer.

The corresponding Classic build input is ghcr.io/atrinik/classic-build:1.18.0@sha256:86d3c4182dc786db8ace56d9d8dc57ff4f14c1c4f517b728547626f576280449; the general Windows cross-build composition uses ghcr.io/atrinik/windows-build:1.18.0@sha256:01065f081cdf843a6591abf25f2b27734103ab385c5aa003b2eeb9a3a1ca0e5a. The separately pinned portable producer uses the fixed SDK 1.22.0 release, ghcr.io/atrinik/classic-portable-build@sha256:74761e930f5d57face2d81efb0dc50dd4ce32ce1204810e56580bf68a5972ebc, from producer eb1f6af78216adb4375826cdb70ef78a61ab403a for Classic bd5317a03cdc82f029105c5dc26428b09fcd54b3. Collector run 38513888428 establishes installed identity and trusted hosted filesystem equality. Its final_portable_cohort receipt remains false; actual export, relocation, native graphics and audible playback retain separate acceptance checks.

Historical SDK 1.17 acceptance remains recorded by collector run 38161442404 against producer 0571f500ede75e7661b508d8bb40354256113223 and image ghcr.io/atrinik/linux-build:1.17.0@sha256:4ca8e921b616d20b18fcef901bd554488b4d5a68a7c4304268dedef23723a3bf. That review accepted the installed LLVM tool roles for that image. Installed SDK verification establishes build inputs; live coordinator authority, portable export, native graphics and audio qualification retain their separate checks. Independently pinned sound and portable images retain their own release contracts.

Each new build worker must use the exact image pin and verified source/cache mounts. Historical bound containers retain their original image and recovery contract; a tag or previous probe never proves the running image.

Before initializing LFS-backed sources, verify Git LFS and its required filters in the selected source environment:

git lfs version
git config --get filter.lfs.process
git config --get filter.lfs.required

The filter process must be git-lfs filter-process and required must be true. Check materialized payloads after clone, checkout and linked-worktree creation. These checks do not establish runtime export or media hydration.

Shared host GitHub authentication

Native delivery uses the actual passwd user's standard private ~/.config/gh, with authentication selectors unset throughout. Complete host capability preflight before genesis or resume. Build workers receive no credentials, Codex state or signing agents. Historical bound coordinators retain their exact read-only host-auth bind; workers never log in, refresh, log out or switch accounts against it. Authentication grants no additional task authority.

One-session project delivery

Use atrinik-project-delivery for multi-issue work. Copy the complete goal launcher, select the real parent/repository scope, and let one coordinator launch and manage workers. It schedules independent lanes against actual worker capacity, retains foreign deliveries, and routes each writing leaf by source or retained-resource scope. New source work needs no scheduler/ledger admission. The operator protocol defines retained-state commands, recovery, scoped tracking and acceptance. Legacy program delivery and individual issue delivery remain available; there is no implicit migration.

Routine authorized local development and minor project tracking do not need repeated approvals. Merges, deployments, expanded scope and uncertain ownership remain gates. A resumed coordinator refreshes live merge evidence, updates dependants and verifies acceptance before authorized parent closure; GitHub child counts alone do not close the project. The helper schedules and journals; actual worker spawning and evidence assessment use the agent runtime, not a background daemon. Its ignored state never substitutes for a leaf ownership ledger.

Shared local agent ledgers

The ignored build/agent-process-improvements.md and build/agent-tooling-issues.md files are optional local, human-readable diagnostics. Routine reads, updates and response status lines are unnecessary; malformed files or reporting contention never block work, validation or PR readiness. Delivery ownership ledgers remain authoritative and retain their gates. Update either diagnostic only through the wrapper's schema-aware transaction:

./atrinik agent-ledger update --ledger tooling-issues \
  --key 'mechanism=<slug>;remediation=<slug>' --status open \
  --observation 'generic symptom' --impact 'bounded impact' \
  --recommended-action 'safe next action'

The command finds the shared wrapper root even when invoked from a linked worktree, reads and validates the latest bytes under a stable lock, and publishes a bounded atomic replacement. Use its returned digest with --expected-digest for fail-closed stale-writer detection; follow its lock, stale, and retry diagnostics. Separate filesystems cannot share that local lock and require an explicit coordinator or event handoff. Never copy ledger contents into source, CI, release, issue, pull-request, or delivery evidence.

Develop in an owned local worktree and run commands from its repository root.

Pinned build and runtime containers

Use the short-lived CPU worker composition for application builds and toolchain tests. It preserves exact same-path sources, common Git metadata, live operational review directories and resource leases, while keeping credentials and Codex state outside the worker. Reuse compatible owner-isolated caches across worker exits. The immutable Linux image supplies Ubuntu 26.04 userland; this proves its container toolchain, not native desktop qualification. No host compiler package lock or QEMU is required.

Initialize the selected sources in the native worktree before creating the worker; init clones only missing repositories and preserves existing checkouts:

./atrinik init --with classic
./atrinik profile show classic --json

Inside the exact pinned worker, diagnose the build environment and use the same options for plan and execution, recording the returned resource intent first:

python3 -m atrinik_workspace.linux_platform
./atrinik build all --profile classic --test --plan --json
./atrinik build all --profile classic --test --expected-plan RETURNED_PLAN_SHA256

Keep portable export and native gameplay separate. The immutable portable producer creates the movable client. Verify its exact exported directory after transfer; the native desktop supplies the loader, driver, display and audio. A verified export requires no compiler or source-build preflight.

The retained Windows/WSL2 WSLg desktop composition provides /dev/dxg, WSL libraries, display/audio endpoints, host networking and its Docker feature. It also mounts the pre-existing private $HOME/.config/gh-atrinik store, $HOME/.codex-atrinik and host Git configuration. It is a trusted, credential-bearing desktop composition, not the isolated CPU worker or a credential-free application runtime.

An already-provisioned owned WSLg session retains those exact prerequisites, image/mounts and historical compatibility gates. Do not expose its credentials to untrusted code or separate runtime services. The native standard-store setup does not provision its alternate auth bind; this configuration supplies no fresh credential-free WSLg launch recipe. Do not copy tokens or recreate a development coordinator to fill that gap. WSLg runtime capability and historical canonical-container proof remain distinct from direct-native Linux authority; native WSL rejection is unchanged. Native Windows package/D3D12 qualification remains a separate supported workflow.

Use the isolated server runtime for headless server execution and .devcontainer/windows-cross/devcontainer.json for the separate Classic Windows toolchain. Runtime/build configuration selection grants no delivery authority. Add --docker to the build-environment report only when an operation needs Docker. A daemon permission failure needs a Docker access fix; GPU flags or display mounts cannot repair it.

The wrapper owns the composition files; the standalone devcontainer component owns the published toolchain images. The historical ordinary composition mounts auth/Codex state and is not the credential-free native build-worker recipe.

Docker storage topology

Native CPU workers reuse the bound worktree's workspace/build and compatible compiler/dependency caches. Keep source/common-Git and lease coordinates stable, and bind each real operational build/reviews directory read-only at its unchanged path. Follow the execution contract's exact image, mount, inventory and shared-lock proofs before starting. A separately owned volume may back the exact recorded build path; never overlay occupied state or copy a source, ledger or credentials into it.

The Windows cross-build configuration uses its per-container workspace volume. Its Docker package fallback deliberately keeps the private immutable source staging root and final package output on bind mounts. It attaches separate namespaced named volumes for client/server CMake trees, ccache, and dependency downloads, initializes their writable roots before the non-root build, and records their exact names in the package build metadata. No source checkout, registered worktree, server state, credential, or delivery ledger is copied into a cache volume.

Volume names use the Dev Container identity through ATRINIK_DOCKER_VOLUME_NAMESPACE; parallel containers therefore do not share mutable build state. Stop all containers using a volume before removing that exact volume. Wrapper cleanup remains preview-first for its marker-owned contents, while volume removal is an explicit operator action after the container lease is gone.

The repeatable synthetic comparison records environment, pinned image, namespace, cold/warm bind and volume timings, interruption/cache-reuse observations, host export checksums, and exact cleanup results:

python3 scripts/benchmark_devcontainer_storage.py \
  --image ghcr.io/atrinik/windows-build:1.18.0@sha256:01065f081cdf843a6591abf25f2b27734103ab385c5aa003b2eeb9a3a1ca0e5a \
  --output build/storage/windows-docker.json

The helper uses bounded deterministic input and refuses pre-existing benchmark volumes. Use --keep-volumes only when the exact reported volume is needed for manual inspection. These synthetic storage results do not establish delivery ownership, build acceptance or runtime behavior. Historical ordinary-container cache mounts remain preserved under their existing compatibility contract.

The workspace and container VS Code settings exclude the wrapper-owned workspace/ and top-level build/ trees from recursive file watching, and the root Pyright configuration excludes them from Python analysis. Primary component checkouts beside the wrapper remain indexed. Open a managed worktree under workspace/worktrees/ as its own VS Code folder or window when it needs language-service coverage.

Shell completion

Activate native completion for the current Bash, Zsh, or Fish session without changing a startup file:

# Bash (the same command works after putting atrinik on PATH)
source <(./atrinik completion bash)

# Zsh, after compinit is available
autoload -Uz compinit && compinit
source <(./atrinik completion zsh)

# Fish
./atrinik completion fish | source

For persistent per-user activation, create the shell's normal completion directory yourself and write the deterministic output to its native file:

# Bash
./atrinik completion bash > ~/.local/share/bash-completion/completions/atrinik

# Zsh (ensure ~/.zfunc is in fpath before compinit)
./atrinik completion zsh > ~/.zfunc/_atrinik

# Fish
./atrinik completion fish > ~/.config/fish/completions/atrinik.fish

The wrapper never creates those directories or edits shell configuration. Completion works for ./atrinik, an atrinik command on PATH, and absolute invocation paths. Commands, nested commands, exact options, mutually exclusive flags, and static parser choices come from the live argparse tree. Local manifest identities, built-in and saved profiles, owning-checkout worktree labels, states, scenarios, and recorded topologies are reread on every keypress. Filesystem values such as --path and --output remain native shell path completion, and wrapper suggestions stop after the run client|server -- forwarding boundary.

The provider reads only bounded local metadata and fails quietly to static parser candidates when optional state is absent or malformed. It does not construct a Workspace, inspect Git, probe processes, read scenario password files, or use the network. A development-container benchmark can be repeated with the private adapter protocol below; measure one cold invocation, then the median of repeated fresh processes after filesystem caches are warm:

time ./atrinik __complete 1 -- atrinik "" >/dev/null
for run in $(seq 1 30); do
  time ./atrinik __complete 1 -- atrinik "" >/dev/null
done

On the Python 3.14 development container used for this implementation, the top-level candidate query measured 63 ms cold and 61 ms warm median. The protocol is internal to the generated adapters; scripts should be obtained through completion bash|zsh|fish rather than hand-written against it.

MCP information-access contract

mcp/contract/v1 defines the common, versioned safety and measurement gates for optional Atrinik MCP servers and evaluated connectors. It pins exact coordinates, stable failures, pagination, cache identity, hard record/byte/time/context limits, six known-answer domains, an adversarial corpus, and build/configure/defer/reject decisions. The Linux context server exposes six context tools and revision-aware search. A separate runtime server requires explicit approvals and exposes no control or logs. Installation and activation remain optional; the pilot guide records the remaining adoption evidence. Direct wrapper, repository CLI, rg, Git, gh, and browser workflows remain authoritative.

The supported public-source MCP startup is Docker-only. The initial published linux/amd64 image was built from wrapper commit 476cf9dad436ce7b5fb89113c46014fcca3b8f77; anonymous manifest lookup, pull and the seven-tool smoke test have passed for this exact digest:

codex mcp add atrinik -- docker run --rm -i --read-only --network none \
  --cap-drop ALL --security-opt no-new-privileges \
  --pids-limit 128 --memory 256m --cpus 2 \
  ghcr.io/atrinik/atrinik-mcp@sha256:e1e8880cc80979813e9ef39fcfe4b6568a7cab48124bbf3b0f02f72b327c4618 stdio

The image contains an immutable public corpus of the wrapper plus 19 component repositories, so this command needs no host mount, checkout, client wrapper or runtime network. See the context server guide for local use and remote MCP guide for the HTTPS Docker Compose quickstart. Codex supports both STDIO commands and authenticated Streamable HTTP URLs as documented in the official OpenAI MCP guide.

Validate or benchmark the contract without installing an MCP SDK:

python3 -m atrinik_workspace.mcp_contract validate
python3 -m atrinik_workspace.mcp_contract benchmark \
  --iterations 30 --output build/mcp/benchmark.json

The benchmark defaults offline and writes sanitized evidence under ignored build/. See the safety and measurement contract for bounds, threat coverage, capability ownership, optional live-GitHub measurement, and downstream consumer gates.

Optional dependency and license diagnostics

Supply-chain commands are optional inspection tools. They never gate builds, tests, PR readiness, or delivery, and catalog updates are never required. The catalog can be stale: compare reports with current component lockfiles, copyright notices and licenses before relying on them. Explicit validate and audit findings are printed as diagnostics with exit status zero; I/O failures remain errors. No automatic audit runs as part of integration or on a schedule.

supply-chain/inventory.json records known repositories and the owned toolchains, actions, images, source archives, system libraries, optional tools, vendored sources, licenses, update cadences, EOL responses, and validation paths they consume. Repository records distinguish physical checkout, logical component, source root, repository coordinate, branch, commit-resolution state, cohort, role, and license; generated reports resolve the full commit from the selected profile and explicitly mark uninitialized or non-selected components unavailable. That distinction is mandatory both for logical components sharing atrinik/classic and for the two atrinik/content checkouts. In an aggregate monorepo checkout, the physical checkout record audits the active root workflows and Dependabot policy. Logical component records still audit dependency inputs throughout their source directories, but ignore imported nested workflows and nested Dependabot files because GitHub does not activate them. The strict schema is checked without a third-party Python dependency. GitHub Actions and container images use immutable commits or digests with human-readable update hints. Workflows own the exact Action commits: the audit requires full-commit pins but does not repeat them in the catalog, so Dependabot Action updates need no catalog edit. Every active repository enables weekly Dependabot updates for its supported ecosystems. Git submodules are not a supported dependency path. The shared deploy-control checkout owns its Worker/agent package lock, action pins, runner contract, and release/deployment inputs; the wrapper records those boundaries without copying its implementation, credentials, bindings, or mutable host state.

Validate the catalog alone or audit the exact checkouts selected by a complete profile. Initialize the replacement stack before its audit; use the additive Classic initialization when auditing either stack together or the Classic stack itself:

./atrinik supply-chain validate
./atrinik init
./atrinik supply-chain audit --profile default
./atrinik init --with classic
./atrinik supply-chain audit --profile classic
./atrinik supply-chain versions --output build/supply-chain/versions.json
./atrinik supply-chain report --profile default --format licenses \
  --output build/supply-chain/default/licenses.md
./atrinik supply-chain report --profile default --format cyclonedx \
  --output build/supply-chain/default/cyclonedx.json
./atrinik supply-chain report --profile default --format spdx \
  --output build/supply-chain/default/spdx.json
./atrinik supply-chain report --profile classic --format licenses \
  --output build/supply-chain/classic/licenses.md

An audit fails before scanning when any physical checkout or logical component selected by its profile is unavailable, including components that are not yet marked audit-ready. This prevents an isolated wrapper worktree or partial local workspace from silently weakening an aggregate audit. Absolute --repository NAME=PATH overrides can select review worktrees, but cannot make the rest of the profile optional.

Generated reports remain ignored under build/. The manually requested diagnostic workflow uses ./atrinik init --with classic to materialize the manifest-defined union of both stacks, audits their physical checkout metadata and logical component source roots, reports unowned dependency inputs, movable workflow/image references, and submodules, prints exact available tool versions, and publishes separate deterministic license, CycloneDX, and SPDX artifacts for each stack. Dependency-input discovery covers npm, Cargo, Go, Buf, Rust-toolchain, and repository dependency-policy manifests. Workflow audits accept only literal runners or statically enumerated matrix runner values, and every npx use must be preceded in the same workflow by an immutable setup-node action. When auditing review code, initialize the complete profile beside that wrapper checkout and use repeated absolute --repository NAME=PATH overrides only for the components under review. The command verifies each override's GitHub repository and branch identity before reading it. A review branch is accepted only when its linked worktree shares the expected checkout primary's common Git directory, so an unrelated or historical checkout cannot impersonate content@main.

Historical MIT provenance grants

docs/PROVENANCE.md is the single exhaustive approved grantor registry. The canonical privacy-preserving identity schema, public registry and operating policy are in governance/provenance-identities/ and docs/PROVENANCE_IDENTITIES.md. Component repositories keep exact material scope and an immutable pinned reference; they never duplicate aliases or canonical identity records.

The cross-repository M1 evidence and exact reuse procedure are indexed in docs/REPLACEMENT_FOUNDATIONS.md. The machine record maps every fresh repository to its local CI, provenance, dependency, notices, packaging, SBOM, and mixed-license gates without making this coordinator a second copy of their implementation policy.

The Classic repository remains GPL-2.0-or-later, but that is not a blanket source-reuse ban. Exact, independently separable material proven to fall within an applicable approved historical grant—including that row's temporal and sole-original-authorship scope—may be inspected as implementation reference, copied, migrated or ported, translated or adapted, and MIT-relicensed after the canonical complete-history, identity, separability, embedded-material, and destination-record review. Source-informed work from qualifying material is provenance-approved reuse, not clean-room work. Later material needs contemporaneous compatible permission. The source license and unrelated dependencies, assets, and surrounding work do not change; destination evidence cites the exact wrapper revision containing the registry used.

Validate the canonical registry and one or more component references through a bounded local checkout. This reads only the pinned registry/schema Git blobs and does not use the network:

./atrinik provenance validate --reference PATH

The MIT-by-default tools repository, its GPL-2.0-or-later map-checker-qt/ exception, and user-facing replacement/retirement paths are inventoried in docs/CLASSIC_TOOLS_MIGRATION.md. They are available only through the explicit classic cohort and are not a production replacement build or runtime dependency.

Component sets and quick start

./atrinik init
./atrinik status --json
./atrinik profile show default

With no component arguments, init clones only the replacement/default initialization cohort. That includes the replacement MIT server, client, editor, protocol, renderer, content-toolkit, and website repositories; content from atrinik/content@main; compatible shared resources, sound, metaserver code; the source-only shared atrinik/deploy-control checkout for organization infrastructure; and required development infrastructure. It does not clone atrinik/classic, atrinik/playtester, or the MIT-by-default tools repository with its GPL-2.0-or-later map-checker-qt/ exception, and does not touch a retained historical atrinik/content@1.x checkout. The replacement repositories have independently validated M1 build, package, provenance, and dependency contracts. Their wrapper manifest build/runtime adapters and complete service integration have not landed, so default is inspectable and editable but is not yet a buildable or runnable game profile.

Add the complete currently playable classic stack explicitly:

./atrinik init --with classic
./atrinik status --json
./atrinik profile show classic
./atrinik build all --profile classic --test
./atrinik up --name classic-local --profile classic --temporary-state
./atrinik ps classic-local --json
./atrinik logs classic-local server --follow
# Press Ctrl-C to stop following logs; the services keep running.
./atrinik down classic-local

build all configures the selected Classic monorepo through its root CMake project, so protocol and libatrinik are compiled once and shared by the client and server. A component-specific build such as build client or build server continues to exercise that module's supported standalone FetchContent path. build topology selects the direct client and server targets plus their complete dependency closure, matching the normal paired up build root without adding the metaserver worker. It supports the standard --plan and --expected-plan fence; build all --test remains the full validation command.

Incremental Classic development

Use the development workflow when iterating on a playable Classic service:

./atrinik dev build --profile classic --services server,client
./atrinik dev build --profile classic --services server --json
./atrinik dev up --profile classic --name classic-local \
  --services server,client --temporary-state
./atrinik dev restart classic-local --service server
./atrinik dev restart classic-local --service client
./atrinik down classic-local

dev build and dev up resolve the complete client/server dependency closure and use the same topology build root, so a warm direct development build warms the paired launch. --services server, --services client, and --services both select the playable service set; selecting one service limits the CMake build targets and does not rebuild the other service. Content, resources, region maps, source views, CMake configure state, and the shared compiler cache report reused or refreshed decisions in JSON output. Add --test when the selected development build should materialize the configured CMake graph and run its CTest validation; this explicit mode may build both playable services so the unfiltered suite has all of its targets. The metaserver worker is not part of this playable scope; use the explicit build all --profile classic --test workflow for full validation. JSON output also includes elapsed build time and per-CMake configure/build/test timings for the cold/warm and service-only rebuild matrix.

dev up keeps local paired launch offline: the server disables port mapping and STUN, and the client disables the metaserver and STUN while connecting to the reserved loopback endpoint. dev restart requires a currently supervised topology, performs a controlled stop, rebuilds only the requested service target, and publishes a fresh immutable runtime generation. Persistent state and the reserved endpoint port are retained; disposable temporary state is copied into the new generation and the superseded copy is removed only after the replacement is ready. The topology may therefore restart both supervised processes as one sealed-generation transaction while keeping compilation service-selective and preserving the state/port contract.

Managed source views are reconciled in place, so unchanged links and copied files retain their identity while changed, retargeted, and stale entries are updated without following unsafe symlinks. Linked-directory structure and symlink targets participate in view identity; a dirty Git source conservatively runs configure on every build. CMake configuration is skipped only when the source-view state and a fingerprint of the generator, CMake/compiler toolchain, cache arguments, test mode, and relevant environment still match. Ninja may still run CMake's dependency regeneration during the build. Use --force-reconfigure to run the explicit configure step regardless. A skip also requires the expected CMake cache and Ninja graph to identify the current source and generator. Compiler, toolchain-file, or initialization-environment changes safely reinitialize only that marker-owned binary tree while retaining the shared compiler cache.

When ccache is available, native C and C++ builds automatically use the marker-owned shared workspace/build/compiler-cache, bounded at 5 GiB. Debug and source prefixes are normalized across equivalent profile roots when the selected environment compiler proves support for the required prefix-map switches. Opaque toolchain-selected compilers retain their own flag contract instead of receiving incompatible GCC-style switches, and retain directory hashing so objects with profile-specific debug paths cannot cross profile roots. Pass --no-ccache for an explicit uncached build; an unavailable cache command is reported with the same opt-out guidance.

Building the Classic server also runs its offline worldmaker and stages the generated region-map .png/.def pairs in the profile build. Generation uses the selected Classic, shared content@main, and resource views, so it requires the same native build dependencies as the server. A marker-owned cache is reused only while every selected checkout is clean and its recorded commit still matches; dirty inputs regenerate on every build. Missing incuna_-1 output, incomplete pairs, malformed files, or generator failure stop the build while preserving the last valid cache.

Server launch uses a disposable assets staging root with a writable data directory and the selected generated client-maps. Generated game data never needs to exist in, copy into, or overlay a registered state. A supervised topology copies the maps into its owned runtime snapshot before the server takes its immutable asset snapshot. QUIC serves that snapshot by default; http_url only advertises an optional operator-managed HTTP(S) origin. Region maps are reclaimed with their marker-owned profile build by the normal preview-first ./atrinik cleanup --scope builds lifecycle; topology snapshots remain with the retained topology record and are atomically replaced the next time that topology name is launched.

Building metaserver-worker retains a validated dependency installation keyed by exact package and lockfile bytes, optional project .npmrc, Node/npm, Node runtime and host platform identity, and effective npm configuration. External file-backed npm configuration, custom script shells, and external Node preload options fail closed; project .npmrc is supported through an authenticated copy. The hashed lifecycle-script environment and source metadata also participate in the key. npm ci remains the only installer. Copied root metadata is authenticated before the wrapper temporarily restores owner-only write access needed by dependency-install and source-view transactions; the source mode is reapplied before view publication. Sealed immutable source generations therefore cannot block staging writes. Worker checks receive temporary full owner access with group and other write access disabled for allowed generated outputs, and the sealed root mode is restored afterward. A second input-identical build reuses that installation and an unchanged profile source view. Because enabled dependency lifecycle scripts can observe root files, the complete non-generated source digest participates in every dependency key and source symlinks fail closed. The install root is stable and hashed; copied modification times, filesystem flags, and extended metadata participate in the key while staging access times are normalized; the lifecycle source is authenticated before install; installed output that embeds its staging path is rejected; and project .npmrc content is provided as a restrictive temporary copy and never published in the shared cache. Wrapper transaction metadata is hidden while lifecycle scripts run and restored before publication. Every profile gets its own node_modules copy, so its checks cannot mutate the shared cache. A canonical no-follow digest covers the complete installed tree, including modes and bounded relative links. The isolated view permits only Vite's profile-local .vite/.vite-temp outputs outside that immutable snapshot. Build output reports dependency installation/cache time and source-view preparation/reuse time.

--with classic has one exact meaning: add the complete classic initialization cohort to the replacement/default cohort. It is not a classic-only mode. The cohort consists of one atrinik/classic checkout, the MIT atrinik/playtester checkout, and the MIT-by-default tools repository with its GPL-2.0-or-later map-checker-qt/ exception. The union initializes the shared atrinik/content@main checkout exactly once. The classic monorepo supplies logical classic-server, classic-client, classic-editor, classic-libatrinik, and classic-protocol components from its server/, client/, editor/, libatrinik/, and protocol/ source directories. Compatible shared assets and infrastructure are reused from the default cohort. Rerunning either initialization mode is idempotent and never updates, rebranches, replaces, or repurposes an existing checkout.

The playtester logical component provides the classic-only playtester role and declares content, libatrinik, and protocol inputs. Its wrapper build contract is none: initialization, profiles, worktrees, and supply-chain identity are coordinated here, while installation and tests remain owned by atrinik/playtester.

Checkout entries have explicit local destinations; normally these are direct children of the wrapper root such as ./client, ./classic, ./content, ./observatory, ./deploy-control, ./web-platform, and ./pathfinder. Logical components name their owning checkout and a safe source root within it. Both stacks map role content to that one shared checkout. A local ./content-1x directory may remain as preserved migration history, but it is not initialized or selected as an active component.

Initialization follows the GitHub transport of the wrapper's origin (then upstream): an SSH wrapper clone produces SSH component clones, while an HTTPS wrapper clone produces HTTPS component clones. If neither remote supplies a recognized GitHub URL, initialization falls back to public HTTPS. Existing explicit partial initialization remains supported, for example ./atrinik init content renderer. A logical component name is also accepted; all names resolving to one checkout are cloned only once. Absent optional checkouts are reported as optional rather than invalidating status or a built-in profile.

The manifest assigns logical roles such as client, server, protocol, libatrinik, content, playtester, source-only observatory, shared source-only deploy-control, and the shared web-platform package to providers within each stack. The observatory and deploy-control roles are default-only and have no wrapper build adapter or runtime dependency; deploy-control owns its Worker/agent package and deployment workflow boundaries in its own repository. The shared web-platform package is default-only and has no wrapper build adapter or runtime dependency while its package contract is being established. The built-in default and classic profiles resolve exactly one compatible provider for every role they require. A runnable service closure cannot combine replacement and classic implementations; shared read-only repositories are reusable only where the manifest declares them compatible.

status --json is non-networked, stable machine-readable output. For each requested or manifest-wide physical checkout it reports default/classic cohort and stack membership, logical modules and roles, license, destination, initialization state, and whether an absent checkout is optional. It therefore distinguishes an intentionally absent classic checkout from a broken default workspace.

Migrating former standalone classic repositories

An older workspace may have the classic sources as five independent repositories, either at former canonical paths or the later legacy-server, legacy-client, legacy-editor, legacy-libatrinik, and legacy-protocol paths. Initialize only the destination classic checkout, then use the checked migration instead of moving directories by hand:

./atrinik init classic
./atrinik migrate repositories --dry-run
./atrinik migrate repositories --dry-run --json
./atrinik migrate repositories --apply
./atrinik migrate repositories --audit --json

init classic needs only the maintained main branch. The migration verifies integrated commits against the immutable commit maps. When an old local worktree points at a branch-only commit whose rewritten object is no longer published, apply imports that exact local source commit as a bridge parent instead of depending on a retired history/* ref.

The dry run produces the complete migration plan without changing the workspace. Apply combines each proven former repository at the matching ./classic/server, ./classic/client, ./classic/editor, ./classic/libatrinik, or ./classic/protocol source directory, preserves recoverable originals and existing linked-worktree directories, repairs Git administrative links when necessary, and rewrites proven classic profiles to the checkout-root/source-root schema as one checked operation. Source history remains attributable through the monorepo import rather than becoming a history-free copy.

Preflight refuses ambiguous identities, conflicting occupants, live affected topologies, unsafe Git states, and selectors it cannot prove. Review the report, resolve the named condition, and rerun the complete dry run; never move paths by hand merely to silence the audit. Content and content-1x, server states, build trees, collected runtimes, scenario data, topology records and logs are not moved or reinterpreted. --audit is read-only and verifies the post-migration repository, worktree, and profile invariants.

After apply and audit, ./atrinik init --with classic can fill in the rest of the classic cohort. Do not run that additive command first in a pre-split workspace: its default-cohort preflight correctly refuses former classic repositories that still occupy replacement checkout paths. Pre-split scenario records that lack immutable stack and provider identities remain on disk but are deliberately inert; recreate one before using it rather than allowing its old default profile name to acquire replacement providers.

Migrating persisted content selectors

Workspaces created before the content consolidation can retain profiles that name content-1x, historical build/scenario/topology records, or worktrees in the former namespace. Keep all of that state in place and run the dedicated checked migration:

./atrinik migrate content --dry-run --json
./atrinik migrate content --apply
./atrinik migrate content --audit --json

The dry run proves the canonical content@main consolidation commit and inventories every legacy selector and affected resource. Apply refuses dirty, detached, locked, live, colliding, in-progress, or unproven inputs. A simple certified primary selector becomes content@main; a managed worktree moves to the shared namespace only when its repository, common Git directory, commit/tree ancestry, destination, and cleanliness all match. An old 1.x worktree or arbitrary external path is never silently repointed.

Original profile bytes are journaled and updated atomically. Audit is read-only. Before any later remote branch retirement, the exact bytes and proven worktree paths can be restored with ./atrinik migrate content --restore --json. The old ./content-1x checkout, stopped records, states, logs, and historical coordinates remain preserved and inert; this migration never deletes them. Cleanup continues to inventory those references and remains a separate preview-first operation.

Filesystem paths after storage migration

Managed resources are identified by their normalized canonical paths. Moving the workspace storage to another SSD, rebuilding the devcontainer, or changing the underlying mount device does not require a migration or record rewrite when every managed resource retains the same canonical path. New records omit filesystem device, inode, and ctime fields; readers accept those fields in older records as ignored compatibility metadata.

Integrated Classic immutable dependency sources use a managed per-profile producer cache outside the resettable CMake binary directory. A failed configure can be retried with verified cached inputs when downloads are unavailable.

The former migrate filesystem command and --confirm-remount workflow have been removed. Continue with the ordinary command for the affected resource. Path normalization, no-follow access, symlink and object-type rejection, ownership and mode checks, file locks, generations, digests, Git coordinates, process ownership, leases, and lifecycle validation still apply. See docs/FILESYSTEM-IDENTITY.md for the complete contract.

The current classic client command opens a graphical application. Verify that the devcontainer display forwarding socket is live before launching it. Use --dry-run to build and print either launch command without starting the process.

Non-Git wrapper roots use their own lease namespace and never inherit an ancestor checkout; linked worktrees share their actual common Git namespace.

For task-blocking local tooling or metadata failures, follow local recovery. Authorized bounded repairs preserve evidence and active ownership, then retry the public wrapper operation.

Manual verification handoffs

Change handoffs should end with a copy-pasteable verification recipe that uses the thin wrapper instead of internal build paths or direct component binaries. Use the actual profile, topology, and state policy for the change. A runtime client/server review normally follows this shape; until replacement runtime contracts land, PROFILE must be classic or derived from it:

./atrinik profile show PROFILE
./atrinik build COMPONENT --profile PROFILE --test
./atrinik topology show PROFILE --temporary-state --json
./atrinik up --name TOPOLOGY --profile PROFILE --temporary-state
./atrinik ps TOPOLOGY --json
./atrinik logs TOPOLOGY client --follow
# Perform the feature-specific checks described in the handoff.
./atrinik down TOPOLOGY

Each current topology persists a random generation identity and a mode-0600 filesystem control endpoint. ps and down therefore work from another supported devcontainer or sandbox that shares the workspace even when its PID namespace cannot see the namespace-local process numbers. JSON status reports live, exited, stale, or fail-closed unreachable liveness plus exact runtime-generation, process-tree, state-policy owner/path/lifecycle, and port observations and the safe next action. Text status prints the retained generation identity and action. A control response must match both the topology name and generation; down never falls back to signaling a mismatched or recycled PID. The runtime places the socket under a short generation-derived name in the shared workspace, avoiding ordinary managed-worktree and topology-name path growth. The process-tree lease is tied to both the generation and exact file identity; never replace, unlink, or repair it by hand because an invalid current lease fails closed.

If a supervisor is killed rather than shut down, its same-namespace guardian terminates exact process-tree lease holders and retains the runtime generation and server state until their absence is proven. No layout or mutable build-root lease survives publication. During that interval another session reports unreachable and fails closed: wait, retry ./atrinik ps TOPOLOGY --json, then retry ./atrinik down TOPOLOGY. If the lease remains retained and control remains unreachable, preserve the exact record and lease for operator diagnosis; do not scan /proc, signal recorded PIDs, remove lease files, or reuse the topology name.

The handoff should name any display or runtime prerequisite, list the exact manual actions and expected results, and include down for cleanup. When no runtime check applies, it should say so and still provide the relevant wrapper build/test and topology-inspection commands.

Synchronizing repositories

Inspect the local primary checkouts before changing them:

./atrinik status
./atrinik status client classic --json

Status is deliberately fast and does not contact GitHub. Ahead/behind counts compare against each checkout's cached remote default-branch ref; run sync to fetch and fast-forward when current remote state is required. JSON output is stable machine-readable input for scripts and AI tools. Set membership and optional/initialized metadata remain present even when an optional checkout is absent. Status is checkout-oriented: the classic record lists the logical modules supplied by that one repository.

With no component arguments, fast-forward only initialized members of the replacement/default cohort:

./atrinik sync

sync never clones a missing checkout. Request initialized classic-cohort members by using the same exact additive option as initialization, or limit the operation to explicit checkout or logical component identities. Names that resolve to the same checkout are deduplicated. Also update every clean attached feature worktree from a newly synchronized primary branch only when intended:

./atrinik sync --with classic
./atrinik sync client classic
./atrinik sync --worktrees merge
./atrinik sync --worktrees rebase

sync --with classic considers initialized default and classic checkouts; it does not turn an optional missing checkout into a clone. The command stops instead of changing a dirty checkout. Worktree merge or rebase conflicts are left in that worktree for normal Git resolution. Historical content-1x paths and records are inert and are never treated as content@main. Create new content review worktrees from the shared content checkout.

A target build resolves only that target's transitive provider inputs. During its bounded preparation phase, each clean primary input is exported from its exact Git commit into a wrapper-owned, read-only source generation; the build restores entries omitted by repository-owned export-ignore release rules directly from their recorded Git blob IDs before validating the complete tree; then releases that primary's source lease before configure, compile, and tests. The reserved build topology target instead keeps the normal paired up live selected-source coordinates and their source leases through the build. Its plan and execution therefore derive the same build root that topology show reports, including clean primary resource and sound providers. The manifest may give a logical component strict checkout-relative source_includes for shared sibling files or directories that its build reads outside the logical source directory, including narrowly declared files or directories below another component in the same checkout. Includes cannot equal or contain a component source, overlap their own source, or overlap each other. Those inputs are exported beside the logical source, enter the immutable generation key and authenticated closure digest, and are reproduced beside the component's build source view. The Classic client and server both declare the repository-root cmake/ modules, license, and attributions this way, so their supported scoped builds retain client/ and server/ as the paths printed by atrinik path while using one authoritative copy of each shared input. Archive publication retains its temporary descriptor, and extraction creates entries and applies modes relative to pinned, no-follow generation directories. CMake dependencies that run mutation-based tests receive writable profile-local copies; the shared generation itself remains sealed. The immutable Classic client uses a private client-layout containing its client view and declared sibling inputs. Its provenance verifier receives copied tools, data, fixtures, textures, and fonts plus the exact server dependency lock captured in the same generation; it never stages that lock into the server build view. Consequently a long-running build from a Classic feature worktree does not block sync --with classic from advancing unrelated or snapshotted clean primaries. Dirty sources and selected worktrees remain live inputs and retain their exact source leases. The authored Classic content publisher still proves its target against a live Git checkout, so operations that consume it retain that exact content lease. build all requests the union of every target's dependency closure and retains or snapshots every input without weakening coherence.

Agent development scopes

Use one wrapper-owned development scope as the default entry point for concurrent agent work. Provisioning resolves every logical selector to its physical checkout, creates one full worktree per selected checkout, publishes one immutable derived profile, reserves a topology name and state policy, and publishes the completed scope record last:

./atrinik scope create classic-server --name issue-402 --from classic --json

Omit --name for a timestamped, collision-resistant agent-* name. A supplied name is stable: repeating the exact completed request returns the existing record, while a different component, label, branch, start point, topology, or state request fails without replacing it. Multiple Classic selectors still produce exactly one classic worktree containing all five classic-* source directories. Per-checkout coordinates can be selected deliberately:

./atrinik scope create classic-server content --name issue-402 \
  --from classic \
  --label classic=issue-402-classic \
  --branch classic=feat/agent-development-scopes \
  --start-point classic=origin/main \
  --json

Classic has two selector namespaces: a logical component such as classic-client is positional, while --label, --branch, and --start-point overrides use the physical checkout key classic. A logical selector therefore uses --label classic=...; classic-client=... is rejected as an unselected checkout override. The scope name is the single namespace source: the derived profile and topology are both scope-<name>. If --topology is supplied, it must equal that canonical value; creation rejects any other value before publishing a profile, topology, worktree, or scope record.

Automated scopes default to generation-owned temporary state. Persistent state is opt-in with --state NAME for an existing registered state or --default-state for the shared default. Provisioning does not start a topology or create persistent state.

The secret-free JSON record under workspace/scopes/<name>/scope.json contains the scope name/generation/request digest; base profile and stack; requested logical components; every repository, checkout, label, branch, start point, commit, tree, path, and common-Git identity; the immutable profile name/path and digest; topology name/path; state ownership/lifecycle; and exact supported path, build, topology, log, shutdown, and release commands. Use those returned commands rather than reconstructing managed paths. scope show and scope list return the same validated records.

Scope command maps are creation-time snapshots. A later manifest addition therefore does not invalidate a completed scope or retroactively add commands to its handoff; every retained entry must still be a valid current coordinate and exact command, while removed or edited coordinates fail closed.

Delivery live proof can retain a historical scope from a different, absent wrapper/workspace namespace as external evidence when its complete record or recoverable journal is internally consistent and cannot reference the selected worktree. It pins the bounded records through admission and CAS rechecks; candidate overlap, aliases, present foreign namespaces, changed/uncertain journals, and pending release evidence still refuse admission. This does not adopt or repair the historical scope. Ordinary scope inspection and cleanup continue to require their original current-workspace checks.

Creation journals every worktree, profile-reference, profile, and completed record publication boundary. A failed transaction removes only exact newly created worktrees and profiles that remain clean, unchanged, and unreferenced; changed or uncertain inputs and the durable journal remain as explicit cleanup references for recovery.

If a named create fails after Git has created the requested branch but before the worktree is registered—for example because Git LFS or a checkout filter is unavailable—the journal may finish rolled-back with that branch-only side effect retained. Rerun the exact original scope create command, including the same selectors, name, labels, branches, start points, profile, topology, and state flags. The wrapper verifies the reservation generation, request digest, retained row coordinates, repository/workspace/scope identities, base commit, and branch head, then adopts the branch only when the destination and all worktree, profile, topology, lease, and reference coordinates are absent and conflict-free. Changed, dirty, checked-out, foreign, ambiguous, or uncertain evidence fails closed while preserving the journal as audit evidence. After recovery, use scope show --json and the delivery helper's scope-observe/scope-bind-cas; never hand-edit the journal or ledger.

The returned commands form one complete lifecycle: build the scope profile, start only its reserved topology with its recorded state policy, inspect it, stop it, then preview and apply release. Two scopes may select distinct worktrees of one physical checkout and run that lifecycle concurrently. A live scope A does not prevent a disjoint scope B from stopping and releasing. Use readiness markers, lease ownership, and published status transitions when testing concurrency; timeouts bound failure but elapsed compiler or startup time is not correctness evidence.

Scope release is explicit and hash-bound preview-first:

./atrinik scope release issue-402 --dry-run --json
./atrinik scope release issue-402 --apply --plan PLAN_SHA256 --json

Apply recomputes the plan under the exact leases and refuses a stale plan, live or unreachable topology, retained generation, active lease, dirty, detached, replaced, ambiguously owned, or unexpectedly referenced worktree, changed profile, or uncertain build root. Named and default persistent state is always retained. Stopped topology history remains owned by the separate topology-cleanup lifecycle; its exact stopped scope-owned reference does not prevent release only when current regular spec/status records bind the same profile, generation, and resolved coordinates and prove a control-requested clean shutdown with released runtime, port, and state leases. Stale, historical, mismatched, or unrelated records fail closed. Release journals initial, destructive-substep, build, profile, worktree, and final completion boundaries. After interruption, run a fresh preview and resume with that new digest; completed removals and exact pending reference/branch cleanup are recovered. The completed scope record and release journal remain recovery evidence and available to bounded, secret-free shell completion. Each destructive action is recorded as in-flight before mutation, so a retry can prove the exact absent post-state and finish after a crash between removal and the completed-action journal update.

If a released scope's retained requested_components disagrees with the schema-v1 planned selector, do not edit or delete the ledger, scope record, or release journal. Use the delivery helper's recover-released-scope CAS with the exact predecessor generation/digest pair, scope-show bytes, completed release journal, and explicit-recovery authority. It accepts only the two proven Classic directions (classic/classic-client), preserves the old name, branch, start SHA, roots, and evidence, proves fresh replacement collisions, and replans the corrected selector under a new scope name.

An older helper can instead leave a planned ledger whose live scope already uses the canonical topology but whose request retained another topology name. Preserve the exact predecessor generation/digest pair and raw scope show, worktree-list, and safety outputs. The delivery helper's recover-prebind-scope accepts only an explicit authority binding those bytes and coordinates; it CAS-updates the topology request alone, records the predecessor digest in history, and retries after a crash without manual ledger edits or deletion. Released, active-but- ambiguous, changed, or unsafe evidence is rejected.

Checkout worktrees

Create a branch and full-repository worktree from a checkout's remote default branch. A logical component name resolves to its owning checkout, so this classic example creates workspace/worktrees/classic/socket-review:

./atrinik worktree create classic-server socket-review \
  --branch feat/socket-review

Choose another start point or attach an existing local branch:

./atrinik worktree create classic release-fix \
  --branch fix/release --from origin/main
./atrinik worktree create content maps-pr \
  --branch review/maps-pr --existing

List or remove managed worktrees:

./atrinik worktree list
./atrinik worktree list --json
./atrinik worktree list --wrapper-self --json
./atrinik worktree remove content maps-pr

The default list remains manifest-owned. --wrapper-self instead emits the complete parser-driven Git inventory for the wrapper repository, tagging both its primary and linked worktrees as physical checkout atrinik. It cannot be combined with component selectors; use its JSON bytes directly when a workflow needs retained wrapper-self inventory evidence.

Removal refuses dirty worktrees. Each worktree is a full Git worktree of its physical repository, so a classic worktree contains all five classic source directories. Ordinary git commit, git push, and gh pr create work from inside it. These primitive commands remain supported for manual composition; prefer an atomic scope for concurrent automated development.

Previewing and reclaiming stale workspace data

Cleanup is always operator-invoked and preview-first. With no options it inventories registered worktrees and marker-owned profile builds older than seven days, including immutable source generations and individually marker-owned Worker dependency entries, without changing the filesystem:

./atrinik cleanup
./atrinik cleanup --dry-run --json
./atrinik cleanup --scope worktrees classic-server --older-than 14
./atrinik cleanup --scope builds --scope npm-cache --scope compiler-cache --older-than 0
./atrinik cleanup --scope sound-cache --older-than 7 --dry-run --json
./atrinik cleanup --scope topologies --older-than 7 --dry-run --json
./atrinik cleanup --scope topologies --older-than 7 --apply
./atrinik cleanup --scope temporary-states --older-than 7 --dry-run --json
./atrinik cleanup --scope cleanup-journals --older-than 30 --dry-run --json
./atrinik cleanup --scope cleanup-journals RECEIPT.json --older-than 30 --apply
./atrinik cleanup --scope all --older-than 7 --apply

--dry-run is the explicit spelling of the default mode; only --apply mutates. Repeated --scope options combine worktrees, builds, and the opt-in temporary-states, npm-cache, compiler-cache, and sound-cache; all selects all six. To select one managed profile build, use --scope builds --build-root NAME, where NAME is the exact final directory name from the inventory, such as rendering-fixes-ac5b65ee46bc. Preview with --dry-run --json, then apply the identical request. This selector requires only the builds scope and no positional filters. Paths, case aliases and unknown names are rejected. It excludes every other build, dependency cache and source generation; the selected root retains all age, ownership, reference, lease and revalidation protections. The exact name is included in reports and recovery receipt identity. Existing pending receipts must be retried with the same selector even after removal.

Topology history is a separate opt-in topologies scope and is deliberately excluded from both the default and all, so a broad cache/worktree cleanup cannot silently expand to runtime history. For one abandoned topology, pass its exact name as the positional selector and inspect the JSON before applying the identical request:

./atrinik ps TOPOLOGY --json
./atrinik cleanup --scope topologies TOPOLOGY --older-than 0 --dry-run --json
./atrinik cleanup --scope topologies TOPOLOGY --older-than 0 --apply --json

The preview is eligible only when reference_classification is inactive_topology. That shared classification requires a published stop, unreachable or legacy control, released process/runtime/port/layout leases, removed temporary state, and complete mutable-output cleanup. Active, reachable, retained, malformed, or uncertain records remain protected. This is lifecycle-bound evidence; age never proves that a topology is safe, and an exact selector prevents recovery from selecting another agent's topology. Delivered cleanup receipts use the separate cleanup-journals scope, also excluded from all. Broad inventory remains bounded; an exact-name selection and its current or legacy journal retry remain recoverable above that bound. Current and legacy recovery discovery advances one durable bounded page per identical apply retry. One globally leased cursor owns that discovery; other maintenance requests must finish the recorded request first and cannot accumulate parallel cursors. The cursor stores the exact canonical request and its digest so a later process can identify and resume the required invocation without reconstructing its filters. Only exact schema-v2, regular, owner-only receipts are eligible. Age is measured from durable delivery; pending, malformed, linked, or otherwise unsafe receipts remain protected. A receipt that records removals requires its exact filename as the positional selector. Retirement takes an exclusive receipt lease, so it cannot interleave with archive proof holding the matching shared lease. Positional checkout or logical component names narrow worktree and sound-cache inventory, exclude topology-owned temporary state, and still deduplicate aliases to one physical checkout. The special atrinik filter selects wrapper worktrees. JSON output is stable schema-versioned data and keeps Git/GitHub diagnostics off stdout; its byte fields remain exact integers. Text output uses compact base-1024 IEC sizes (KiB, MiB, GiB, and larger) for allocated, ignored, candidate, protected, and removed bytes.

The worktree inventory covers every initialized physical checkout plus current wrapper worktrees that Git proves are direct children of exactly workspace/worktrees/atrinik/. Historical wrapper worktrees are considered only as direct children of the top-level build/worktrees/ namespace. A worktree becomes eligible only when it is registered to the expected common Git directory and repository, named and unlocked, has no Git operation or ordinary tracked/untracked change, and is not retained by a profile, scenario, live topology, or repository-migration record. Normally, the authenticated gh commit-associated-pulls query must prove one merged PR with the manifest base branch, an exact head.sha match, no associated open PR, and a merge age beyond the grace period.

The only historical-base exception is a wrapper worktree directly below build/worktrees/. Its expected coordinate remains atrinik/atrinik@main, but the PR base must be master. The authenticated API evidence must include the exact head, base.sha, and merge_commit_sha; the local merge commit's first parent must equal that base SHA, and the merge commit must be an ancestor of the frozen final-master boundary ee5ba2096c94bce0161629423d4962a966bc61d8. The local graph proof ignores replace refs and fails closed if info/grafts exists. Missing, unavailable, mismatched, or ambiguous API or local Git evidence protects the item, and apply reruns the proof immediately before removal. Wrong base, closed-unmerged PR, advanced branch, detached worktree, external path, or any other ownership uncertainty also protects it.

Status inspection uses --ignore-submodules=none, so repository configuration cannot hide submodule changes. A worktree with populated submodules remains protected even when otherwise clean because its per-worktree Git directories can contain private refs, reflogs, and objects. If only its prunable administrative record remains, that record protects the repository-wide prune scope for the same reason. Ignored compiler/dependency output does not make a worktree dirty, but its paths and allocated bytes are reported because git worktree remove will reclaim it. Apply uses only ordinary non-force worktree removal and preserves local and remote branch refs and Git objects.

Active issue-delivery evidence is a separate protected ownership boundary. When build/reviews exists, cleanup inventories it through the canonical delivery-ledger helper and protects the review root, every active ledger's report and lock, and each ledger-owned worktree. Missing reports or locks, unsupported helper output, and unrecognized inventory errors protect the complete cleanup plan and surface the inventory error on the affected review root; the wrapper never recreates missing evidence. The repository migration preview and apply paths use the same inventory and refuse while any active ledger exists. Recovery therefore requires a separately authenticated explicit-recovery grant and exact preserved bytes. A fresh ledger, timestamp, branch, worktree, issue assignment, Project state, or push access cannot substitute for lost evidence; when a required canonical report or member is gone, the safe result is an explicit stop awaiting maintainer direction.

Profile builds are eligible only as direct workspace/build/profiles/<profile>-<key> children with an exact regular ownership marker. Each build use atomically refreshes strict metadata with its profile/key, selected repository/branch/checkout/source coordinates, commits, and last_used_at. A marker-proven build created before that metadata uses the maximum no-follow tree mtime as a conservative legacy age. A build selected by a live topology, busy build lock, registered worktree, or the optional strict workspace/build/retention.json record is protected. That retention record is schema 1 and contains exactly schema_version plus an absolute build_roots array. A build sourced from a worktree eligible in the same plan may be reclaimed regardless of age unless another protection applies.

Immutable source generations use the same default builds scope and grace period. Cleanup authenticates their checkout/key path, ownership marker, and closed commit/tree/subpath metadata before considering removal. Build selection separately proves the complete tree digest and exact path, entry-type, executable-mode, symlink-target, and blob identity against the recorded Git source tree. A mismatch under exact descriptor-verified marker ownership atomically retains the generation as a recovery transaction and rebuilds the canonical key; uncertain ownership fails the build without moving data. Cleanup reports an owned canonical content-digest mismatch as an eligible corrupt_source_generation, while recovery transactions remain independently previewable. Inspect retained data with ./atrinik cleanup --scope builds --older-than 0 --dry-run --json; after reviewing the exact protected or eligible generation, use the same scoped command with --apply. An active build holds the generation's shared lock; apply takes its exclusive side and repeats ownership, content state, and age validation before bounded removal. Recovery and staging transactions within the marker-owned container are separately inventoried, remain protected under an active generation lock, and are reclaimable only after the normal grace period.

Worker dependency entries under workspace/build/worker-dependencies/ use the same default builds scope and grace period. Cleanup requires the exact parent and entry markers, strict metadata and last-used time, a safe direct-child key, and an idle per-key build lock; uncertainty protects the entry. Removing a stale entry leaves the marker-owned container and npm download cache intact. Recognizable interrupted staging and backup directories live below the separately marker-owned .transactions container and are reclaimed by the same preview-first scope only after their conservative tree-mtime/root-ctime grace period and per-key lock checks. Apply repeats identity, ownership, and age validation while holding that lock through removal. A valid matching backup is restored under the lock before another install is attempted.

The shared workspace/build/npm-cache and workspace/build/compiler-cache are never part of default cleanup. Their explicit scopes require exact marker-owned paths, valid last-use metadata, safe fixed containment, age, and absence of an active build. Only the npm path admits one legacy known cache after the same proof. Invalid entries inside a valid Worker cache root remain protected worker-dependencies items. Unmarked profile roots, invalid Worker cache roots, other workspace/build children, and all remaining mixed top-level build/ entries are report-only unmanaged-build items. Deep-review reports, ad hoc builds, packages, archives, and unregistered siblings are never recursively deleted.

The explicit sound-cache scope inventories only 20-hex exact-input trees below build/atrinik-workspace/ in registered atrinik/sound primary and linked worktrees. It requires the exact nonpublishing playtest marker, safe Git-proven containment, conservative tree age, and an idle producer build lock. Apply repeats those proofs under that lock before removing one tree; invalid, active, young, unregistered, or uncertain entries remain protected. Every remaining producer cache, plus any busy or invalid per-output lock, protects its containing sound worktree from ordinary worktree cleanup, including --scope all. Run the sound-cache apply first and preview worktrees again afterward. Producer build/verify commands hold a shared Git-admin lease; worktree removal holds its exclusive side from final proof through Git removal, so a producer cannot start in the removal window. A sound worktree without the versioned producer lease marker is not reclaimable by wrapper cleanup.

The explicit topologies scope inventories direct marker-owned directories below workspace/topologies/. It reports liveness, control generation, process-tree, runtime, port, and legacy repository-layout lease state, conservative age, and every path apply would remove. Only old exited or legacy stale records with unreachable controls and released leases are eligible. Orderly records age from stopped_at; legacy stale records without it use the newest no-follow tree mtime. Live, unreachable, young, locked, linked, malformed, unowned, or unverifiable records remain protected. Apply takes the exact topology coordinate lease and operation lock, repeats identity/generation/lease/age/tree validation, and removes only that topology directory. It never invokes down, signals processes, reuses a name, removes build roots, or changes profiles, scenarios, source, or persistent state. A topology containing any generation-owned temporary state remains protected; reclaim eligible disposable state with the separate scope first.

The explicit temporary-states scope inventories generation-named states below marker-owned topology records. An old disposable state becomes eligible only when its topology/generation metadata, directory path and metadata, registry absence, and released exact lease all validate. Retained, promoted, live, unreachable, busy, linked, malformed, registered, or uncertain state remains protected. Apply holds the topology operation and state locks while repeating the proof and never stops a topology.

Apply performs one complete inventory and size recomputation, then acquires the exact target/reference leases and freshly revalidates each stable-sorted candidate without rescanning unrelated report-only payloads. Any new uncertainty fails closed. Busy targets are skipped so they do not convoy unrelated cleanup. Eligible topology records come first, then profile builds and explicit sound-cache entries, exact Git worktrees, other explicit caches, and safely shared prunable Git metadata. workspace/cleanup-journals/ records the exact request, original report, ordered targets, and one write-ahead in-flight action. Each action is first prepared; only a second durable removing checkpoint written after exact locked revalidation authorizes absence or partial-removal recovery. The same cleanup request resumes that journal after interruption, recognizes a completed in-flight removal, and reaches one complete-pending-output receipt without changing the original target selection. That receipt binds the exact terminal report and replays it for an identical retry. The CLI flushes the report before acknowledging it as complete-delivered; direct API callers must call cleanup_acknowledge(report) after consuming it. Only a delivered receipt permits a new run with the same selector. Busy or transiently failing targets leave the journal resumable while disjoint targets may still complete.

Composing coherent component sources

A profile retains a stack identity and chooses one physical checkout root for every logical component owned by that checkout. Start a currently runnable profile from the built-in classic base; start replacement-only source composition from default. Overrides may change a provider's source checkout, but they cannot replace it with a provider from the other stack or leave a required logical role ambiguous. Commands accept an in-stack component identity or its logical role, so role client resolves to classic-client in a classic-derived profile. Selecting checkout classic, any classic-* component, or one of its roles updates all five classic selectors together.

./atrinik profile create maps-review --from classic
./atrinik profile set maps-review content --worktree maps-pr
./atrinik profile set maps-review classic-server --worktree socket-review
./atrinik profile show maps-review
./atrinik build all --profile maps-review --test

The classic-server alias above has the same checkout-wide effect as naming classic: every classic logical component comes from socket-review. Resolution then returns the appropriate server/, client/, editor/, libatrinik/, or protocol/ source root for each component. Profile schema 5 rejects different selectors for logical components that share one physical checkout and records the selected sound mode plus immutable released-product coordinates when applicable. Existing schema-3 and schema-4 profiles load as source or their previously selected mode and are upgraded when next changed.

Clone an existing profile when starting a related combination instead of repeating every selector:

./atrinik profile create maps-review-2 --from maps-review

An existing checkout outside the managed workspace can also be selected:

./atrinik profile set maps-review classic-client \
  --path /absolute/path/to/classic-checkout

The classic-client alias still updates all five classic selectors. The path is always a Git checkout root, never a component subdirectory. The repository identity is validated for every selector, and the manifest's safe source path is appended only after validation. Generated build trees are keyed by profile schema, stack generation, exact repository/branch/checkout/source and role-provider identities, and resolved paths, so classic and replacement output—and different combinations of distinct physical checkouts—cannot overwrite one another. Scenario and topology records retain those same coordinates; older records without them are inert.

The content migration reader accepts the old internal migrated-worktree selector only as recovery input. Current profiles use normal content primary, worktree, or proven absolute-path selectors. Historical 1.x selectors remain truthful and inert instead of being relabeled as main.

Print an exact selected logical source path for use with cd, editors, or other tools. Read-only profile, worktree, and state listings also support --json.

cd "$(./atrinik path classic-server --profile maps-review)"
./atrinik profile show maps-review --json
./atrinik state list --json

path classic-server prints the resolved server/ source root. Use checkout commands such as status, sync, and worktree when the full repository root is required.

Before a server build or launch, the coordinator prepares marker-owned content and resource caches inside the exact profile build. A cache is reused only when its schema and provider, repository, branch, checkout, source path, checkout path, and clean HEAD metadata match and its required output structure remains valid. Dirty inputs rebuild every time and do not receive reusable metadata; inputs are checked again after generation so a concurrent checkout change cannot replace the previous valid cache. Only tracked files below the resource repository's runtime-paths.txt allowlist are staged; development metadata and untracked files cannot become server assets. Client builds expose the selected sound checkout by default. A saved profile derived from classic may instead opt into the complete local-only compatibility tree supplied by the selected sound checkout:

./atrinik profile create classic-audio --from classic
./atrinik profile set classic-audio sound --worktree issue-27-playtest-tree
./atrinik profile sound-mode classic-audio local-playtest
./atrinik profile show classic-audio --json
./atrinik build classic-client --profile classic-audio --test
./atrinik topology show classic-audio --service client --json

The built-in classic profile and every replacement profile remain in source mode. Local-playtest mode requires a clean selected sound checkout with the public tools/sound_release.py build-playtest-tree command. That repository owns conversion and full decoder verification; it writes only to its ignored build/atrinik-workspace/ state. The wrapper independently requires the version-1 nonpublishing marker and schema, exact 339-key closure, every source-manifest-derived byte-preserved Vorbis or rendered Opus mapping (including payloads stored at legacy extensions), every payload/hash/count, immutable input hashes, and the complete tree digest. It never falls back to the raw mixed-format checkout.

Exact clean inputs reuse the same verified local output without network access. The profile build and supervised client runtime link that one root, and their JSON records include its mode, source commit/tree, clean-state result, manifest/toolchain/schema/marker/blocker hashes, counts, and output digest. The tree is not an archive or released-runtime input and cannot enter the wrapper's PACKAGE_TYPE=none Classic build path as a package. A changed input gets a distinct cache key; failed or racing generation leaves existing output untouched. Wrapper-owned profile builds remain covered by ordinary retention. Sound-owned ignored outputs are preserved by default and are reclaimed only through the explicit preview-first sound-cache cleanup scope described above.

A saved Classic-derived profile may instead consume the publishable Classic compatibility runtime from an immutable atrinik/sound release. Released mode does not invoke a source builder and never falls back to source or local-playtest. Supply every coordinate posted by the sound release. For example, the published v1.2.0 Classic runtime is selected with:

./atrinik profile create classic-released-audio --from classic
./atrinik profile sound-mode classic-released-audio released \
  --release-repository atrinik/sound \
  --release-tag v1.2.0 \
  --release-product-version 1.2.0 \
  --release-source-commit 642e5a25a476c96b764054b7b57307274b0fabb5 \
  --release-source-tree d57ef0b499cb00f2f7cabf359c320f70f542d81c \
  --release-asset-url https://github.com/atrinik/sound/releases/download/v1.2.0/atrinik-sound-classic-runtime-1.2.0.tar.gz \
  --release-archive-sha256 0a48a2a0087fecf0f9bbe815f20460ab70f858656b4e4a9d1479f8f03c8b09bf \
  --release-manifest-sha256 1894c2ca0b563d1b4ab69c29ac839cf5d873680c416f343072aacad4308889cb \
  --release-source-manifest-sha256 3aacd122abe16da771ac1eb6ad80c50c1c6e7ab43d555dc8772f21be24248366 \
  --release-schema-sha256 428e1312d9922ab4ec20c0ee89d93d842528db6d8cc75197c135f4d4f59066aa \
  --release-toolchain-sha256 ee842444c37df3c6784665c2dacef4ab9220f3abfc5c2daf9214fe4b40aadbf7 \
  --release-tree-sha256 2c3d42ea91ca088ac37e5215e3452dad31e5f1fb17018941ed5ad0a3c53060da
./atrinik profile show classic-released-audio --json
./atrinik build classic-client --profile classic-released-audio --test
./atrinik topology show classic-released-audio --service client --json

The wrapper downloads only that exact versioned GitHub release URL, verifies the outer checksum, safely extracts one bounded product prefix, and then checks canonical internal checksums, the publishable/non-playtest manifest and packaged schema, the nonblocking remediation report, packaged notices and licenses, exact 339-path closure, every payload hash and codec signature, the 189 byte-preserved Vorbis / 150 Opus split, and the logical-tree digest. The verified archive and tree live below the coordinate-keyed profile build; unchanged inputs reuse them offline. Build and topology records retain all coordinates and verification results. A changed coordinate produces a distinct build key, while incomplete or mismatched caches fail closed and remain covered by normal preview-first build cleanup. Supply-chain audit output identifies the selected archive, source commit/tree, and logical tree; license, CycloneDX, and SPDX reports for that profile also carry the complete immutable coordinate set.

Portable Linux client

Linux execution and export documents native dependency preflight, native delivery and pinned workers, explicit X11/XWayland and GPU/audio selection, the movable Classic client, and a separate persistent headless server. The public commands are ./atrinik linux export --profile NAME --output DIRECTORY and ./atrinik linux verify DIRECTORY. Export requires the pinned portable producer and a verified released-sound profile matching the selected source. Before merge, the automatic nonpublishing pull-request acceptance job is the actual producer route. Keep relocation/decoding, hardware gameplay, audible playback, Windows/WSLg, current LLVM Windows packaging, historical MXE paired font baselines and native Windows D3D12 evidence separate.

Deterministic test scenarios

A scenario is a local, ready-to-login account and character plus its own registered server state. It is useful for handing off an issue reproduction without asking every reviewer to register another account and character.

./atrinik scenario create issue-42 --profile maps-review --preset basic-player
./atrinik scenario show issue-42 --json
./atrinik up --name issue-42 --profile maps-review --state scenario-issue-42

basic-player provisions a normal human_male first-login character through the selected server's own account API. On first login the server supplies its configured starting map, standard skills, and initial items. The wrapper builds the selected server, creates the dedicated scenario-issue-42 state, stores a generated password in a mode-0600 ignored file, and prints exact topology show/up/ps/logs/down commands. show and list never reveal the password. A supervised server/client topology that selects the scenario state validates its ownership and metadata, then launches the client with the complete login automatically. scenario credentials remains available for bounded local diagnosis. scenario list keeps the global inventory usable when a retained scenario can no longer resolve its profile or fails current validation. JSON output represents that entry with its name, path, inert: true, and a stable inert_reason; bounded human output labels the same entry inert. Control characters in inert names and paths are escaped. Exact show, credential, and reset operations continue to fail closed.

The generated scenario password is disposable and local. Automatic login may expose it in the local client process arguments, client output, or Codex execution logs; this is the only intended exception. Never copy it to commits, GitHub, public logs, durable handoffs, or final reports, and never reuse it.

Scenarios live below ignored workspace/scenarios/. Their metadata records the profile plus every resolved provisioning dependency's checkout, source root, path, commit, and dirty status. Account files contain the normal Argon2id password record, and the reserved empty player file deliberately causes the first client login to use normal character initialization. The offline provisioner starts no listener, plugin, metaserver, or console and refuses existing account or character identities.

After stopping the topology, reset only the scenario-owned mutable state while keeping its login and source profile stable:

./atrinik down issue-42
./atrinik scenario reset issue-42

Reset refuses a running or otherwise locked state and validates the ownership marker, state registration, state shape, and credential permissions before it replaces anything. External and shared states are never scenario reset targets. For a repeatable Brynknot idle reproduction, use a Classic server build that supports the server-owned brynknot-idle preset:

./atrinik scenario create brynknot-review --profile maps-review --preset brynknot-idle
./atrinik up --name brynknot-review --profile maps-review --state scenario-brynknot-review

This preset places the character and savebed on /shattered_islands/world_0_70 at (20, 8), preserves the world clock, and adds no special item. basic-player continues to use normal first-login placement. Stop the topology before resetting brynknot-review; account and save creation remain owned by the server provisioner.

Generate the fixed Brynknot movement route from a registered scenario, then run it through a fresh supervised server/client topology with an absolute route path:

./atrinik scenario route brynknot-review --output /tmp/brynknot-route.xml
./atrinik scenario benchmark brynknot-review --name brynknot-run \
  --route /tmp/brynknot-route.xml --json
./atrinik scenario benchmark brynknot-review --name brynknot-capture \
  --route /tmp/brynknot-route.xml --capture --json
./atrinik scenario benchmark brynknot-review --name brynknot-video \
  --route /tmp/brynknot-route.xml --record-video --json
./atrinik scenario benchmark brynknot-review --name brynknot-full-moon \
  --route /tmp/brynknot-route.xml --capture --lighting-phase full-moon --json

scenario route is an offline, absent-only export. It uses the fixed brynknot-v1 producer, requires clean selected Classic source and content, and writes the XML plus a .provenance.json companion with their committed source identities. It does not start a runtime, edit an account, or change scenario state.

scenario benchmark requires native Classic support for --live-movement-route and --live-movement-report. It stages the route, verifier, report, and summary below the fresh topology's benchmark/ directory, then generation-fences shutdown. It revalidates the scenario under its shared lease and reserves the fresh topology root under its exclusive lease through startup. The generation is persisted in the benchmark summary before detached startup so interrupted operators can use generation-fenced shutdown. After an interrupted benchmark, pass the generation saved in its retained summary:

./atrinik down brynknot-run --expected-generation SAVED_GENERATION

The command refuses a different generation, including a later run that reused the name. The registered scenario is preserved and is never reset. Success requires every real movement checkpoint to publish the expected map position and every checkpoint to have presented-frame coverage. The terminal summary durably binds the verified frame report by size and SHA-256 and records verification and shutdown results. The report records per-frame CPU time and GPU host submission/presentation timings; those GPU values are host timings, not hardware GPU execution duration. The baseline command remains unchanged when optional evidence flags are absent.

--record-video requests the single fixed private output benchmark/gameplay.avi. The wrapper refuses a pre-existing output and accepts success only for a bounded, indexed 20 FPS MJPEG AVI with nonzero frames and coherent RIFF, stream, timing, frame, and index structure. The summary binds the validated recording bytes with SHA-256. This container check does not decode the JPEG frames; native playback or frame decoding is separate evidence. The client records the complete play window, from entering gameplay through disconnect. Recording adds client work, so its timing is not comparable to the recording-disabled performance baseline.

--capture requests both fixed private evidence files, benchmark/initial.png and benchmark/final.png. Each must be an exclusive, hash-validated PNG of at most 64 MiB; a run requesting capture fails unless both are present and their bounded compressed data and scanlines validate. Capture happens outside the measured walking interval while remaining inside the global and step deadlines. Its manifest records started_utc_us and the complete pinned native source/content identity.

--lighting-phase accepts only day, new-moon, or full-moon and requires --capture. Before the first checkpoint, the client sends the one fixed normal server command and waits for a fresh MAP update, primary presentation, and clock observation. The runtime operator must first verify the isolated default operator privilege used for this lighting run. A rejected command fails within the existing bounds. The wrapper does not grant operator privilege or edit accounts, player saves, or scenario state.

Failures return nonzero and retain bounded evidence for diagnosis. Route input is limited to 8 MiB and 50,000 checkpoints, runtime is limited to one hour, and the native report is limited to 128 MiB. --timeout SECONDS may select a shorter runtime bound covering generation publication, detached startup, readiness, and gameplay. Generation-fenced shutdown and evidence verification retain their separate bounds and may finish after that runtime deadline.

For book-writing reproduction, select a Classic server build that supports writing-books. It supplies writable books, a pen, Literacy, and Inscription through the server's account provisioner:

./atrinik scenario create writing-review --profile maps-review --preset writing-books
./atrinik up --name writing-review --profile maps-review --state scenario-writing-review

Stop writing-review before resetting its scenario-owned state.

Do not create static account or player fixtures; add a tested server-owned preset if a future reproduction needs more than basic-player. The Classic server also owns lighting-radiance-day, lighting-radiance-dawn, and lighting-radiance-night: each places an unapplied mithril lamp in a character at the Greyton lighting-review map and initializes the isolated world clock to the named period. lighting-radiance-inside places the character beside the same map's interior fireplace at night so ownership-gated roof and interior rendering can be reviewed. These presets are reserved for repeatable renderer reviews whose ordinary world progression would dominate the test.

Supervised topologies and practical workflows

A profile is a declarative source topology. The topology and process-lifecycle commands turn that selection into a Compose-like native development stack:

./atrinik topology show PROFILE
./atrinik up --name TOPOLOGY --profile PROFILE --temporary-state [--port UDP_PORT]
./atrinik ps [TOPOLOGY]
./atrinik logs TOPOLOGY [server|client] [--follow]
./atrinik down TOPOLOGY

Classic server listeners default to loopback. For a server in a container with an explicitly published UDP port, pass --server-listener all-ipv4 to topology show, up, or dev up. Use the same option when planning and starting that generation. The finite choices are loopback and all-ipv4; client-only topologies reject the option. New plans, specs and ps --json report server_listener; old records without it retain their original loopback behavior. dev restart preserves the selection, and a running topology cannot be retuned by another up.

all-ipv4 binds the server inside its container; Docker's host publication is separate and must remain 127.0.0.1:HOST_PORT:CONTAINER_PORT/udp for a same-host client. The advertised client endpoint.host remains 127.0.0.1, never 0.0.0.0. Port reservations cover the whole namespace regardless of listener choice. See the independent server recipe.

Server topologies choose exactly one state policy: --temporary-state creates a fresh generation-owned state for isolated automation, --state NAME selects an existing registered persistent state, and --default-state explicitly selects the legacy managed persistent default. Omitting all three remains backward compatible with --state default. topology show, up, and ps --json report the policy, exact owner, canonical path, and lifecycle. Bounded and followed service logs begin with the same policy context so captured output retains the state ownership boundary. Temporary state is never entered in state list; a confirmed clean down removes it after its process and state leases are released. Clean proof requires expected service exit status as well as released leases and remains durable so an interrupted down can safely retry finalization. A crash, unreachable supervisor, malformed record, or uncertain lease retains it for diagnosis.

Retain a clean temporary state deliberately, then promote it without replacing an existing name:

./atrinik down TOPOLOGY --retain-state
./atrinik state promote TOPOLOGY SAVED_NAME --json

Promotion registers the exact stopped directory in place and persistent policy surfaces retain its topology-generation provenance in independent durable metadata, including across a promotion retry or unavailable origin record. Retained and promoted states are protected, and a topology name with unfinished temporary state cannot be restarted until that state is promoted or explicitly reclaimed. Abandoned disposable states participate only in the explicit preview-first cleanup scope:

./atrinik cleanup --scope temporary-states --older-than 7 --dry-run --json
./atrinik cleanup --scope temporary-states --older-than 7 --apply --json

Cleanup never stops a topology and never removes a live, busy, linked, malformed, registered, retained, promoted, or otherwise uncertain state. For topology-history recovery, use the exact topology name with ps and the topologies scope. Do not infer inactivity from directory age or choose a different state/topology when another agent owns it; retained state, lease uncertainty, and concurrent restart/replacement are deliberately fail-closed.

Package a Classic review profile for Windows

Create one portable ZIP when the client must be reviewed as a native Windows process rather than through the devcontainer display. The package cross-builds the selected Classic client and server, includes the profile's collected maps, generated client maps, resources, and sound, and snapshots one persistent server state with its accounts and player data:

./atrinik down REVIEW_TOPOLOGY
./atrinik package windows \
  --profile REVIEW_PROFILE \
  --state REVIEW_STATE \
  --output build/packages/review-windows.zip \
  --json

The state must be stopped and must have been started at least once so its QUIC identity exists. To transfer a temporary topology's state, stop it with --retain-state and promote it to a new persistent name first. Packaging refuses a live or otherwise busy state, an incompatible profile/state pairing, an existing output file, or a non-Classic profile.

Run the command inside the windows-cross devcontainer to use its installed toolchain directly. From the native Linux worktree or WSL2, the wrapper uses Docker and the digest-pinned image in .devcontainer/windows-cross/devcontainer.json. After the command succeeds, copy the ZIP to Windows, extract it, and double-click run.bat. The launcher starts the local packaged server on UDP port 1730 and pins the client to that server's copied certificate fingerprint. Use --port PORT when 1730 is not available on the Windows host.

The output file is mode 0600 on the packaging host and the command reports its SHA-256 digest. Treat it as sensitive: server/data contains private player data, credentials, and the server private identity. Do not upload the ZIP to a public pull request, issue, CI artifact, or release. The wrapper never overwrites an existing ZIP.

Native Windows Classic GPU preflight

A review ZIP is a handoff artifact, not proof of a successful native runtime. Follow docs/WINDOWS_GPU_PREFLIGHT.md for the existing Windows package smoke, D3D12 qualification benchmark, evidence schema, failure classification, and safe cleanup sequence. The production ZIP has no Direct3D12 force-switch; the documented conformance environment is test-build-only. Never launch the graphical client in the Linux coordinator as a substitute for native Windows validation.

For a complete Classic profile, up, scenarios, and individual builds resolve one manifest-derived build-root selection across the client, server, content, protocol, libatrinik, sound, resources, and metaserver-worker roles. Only the requested game service targets are built; the wider selection keeps their incremental outputs and recorded coordinates on one root. Partial profiles retain the requested service's dependency closure.

Classic GPU shader toolchain

On x86-64 Linux, a managed Classic client build prepares the checksum-pinned shader toolchain from the selected Classic checkout and passes its absolute paths to CMake. The preparation is shared by standalone build client, paired up, and the client portion of build all; its lockfile and shader-manifest identity are retained in the profile build metadata. No caller PATH changes are required.

For a host-provided toolchain, set both executable overrides and optionally the DXC library directory before invoking the wrapper:

export ATRINIK_DXC_EXECUTABLE=/absolute/path/to/dxc
export ATRINIK_SPIRV_CROSS_EXECUTABLE=/absolute/path/to/spirv-cross
export ATRINIK_DXC_LIBRARY_DIRECTORY=/absolute/path/to/dxc/lib
./atrinik build client --profile classic --test

Alternatively, set ATRINIK_GPU_SHADER_DIRECTORY to an absolute directory containing a generated cohort and its SHA256SUMS manifest. The explicit cohort is validated by the Classic CMake contract. Do not combine that variable with the executable overrides; on platforms where the pinned cohort is not available, use one of these explicit overrides.

Provider selection is stack-coherent: a classic service never binds a replacement protocol or content@main. Today the classic stack is the runnable implementation; the default replacement profile will become runnable as its component contracts land. For a runnable profile, up builds the requested targets, reuses or refreshes content and resource caches, stages sound, prepares an isolated runtime, and starts both game processes under one supervisor. A server gets an available UDP port by default; --port 0 has the same automatic-allocation meaning, while --port 1 through --port 65535 requests that exact port. Automatic selection briefly holds the workspace allocator only while it chooses and publishes a unique generation-bound reservation. Every port uses a short mode-0600 transaction file, and every server retains its own immutable mode-0600 generation lease through supervisor and guardian recovery, so startup preparation and readiness waits for different ports overlap. An exact-port conflict fails without waiting for an unrelated port and names the owning topology and generation plus the safe retry action; once startup has published supervisor status, ps and down are available. The supervisor rechecks kernel availability immediately before launching the server; an external process that wins the bind race produces a bounded startup error without changing another topology's reservation. The supervisor waits for both the QUIC certificate fingerprint and completed server initialization, then gives the paired client an authenticated loopback endpoint, disables metaserver and STUN discovery in that client, and disables STUN discovery and automatic port mapping in the server before declaring the topology ready. Use --service server or --service client for a single service. Client startup requires a live forwarded display socket.

Ordinary wrapper operations coordinate through fair, exact-resource leases, not the workspace-global layout lock. Workspace-local coordinates live under workspace/leases/; physical-checkout Git administration and source coordinates live under the wrapper's common-Git atrinik-resource-leases/ namespace so wrapper worktrees or relocated state roots cannot split coordination. Every operation also retains its own wrapper-worktree source coordinate, preventing cleanup from removing the code and ignored component checkouts beneath an active wrapper view. Saved non-primary profile references are also registered in this physical namespace, so cleanup from a relocated state root observes references published by another root. First-use registry backfill retains exact paths from missing profile and scenario sources as conservative historical references without changing the authored records. Those unbound records do not prevent status, sync, or unrelated commands from constructing the workspace, but they protect a source that later reappears at the same path. Genuine source-lease contention reports the exact coordinate, owning operation and supported recovery action; an authored record that changes during confirmation fails with a distinct retry diagnostic. Profile names, topology names, scenarios, states, build roots, and cache keys remain workspace-local.

Delivery live proof also reads saved profiles through a bounded, pinned, descriptor-relative inventory without modifying them. A profile whose selector map is a strict subset of its current stack is historical for reference discovery: its retained selectors are still fully validated, and any selector resolving to the candidate worktree remains a blocking reference. Extra components, malformed selectors, and other uncertain profile state fail closed. Delivery scope observation and binding accept either an exact physical checkout selector or one exact logical component selector. For Classic, classic is the physical checkout and classic-* are its logical components; while older operators are being migrated, use a positional classic-* selector and keep per-checkout --label, --branch, and --start-point overrides keyed by physical checkout classic. This preserves one checkout-wide worktree and avoids treating the physical checkout name as a logical component. Each lease request publishes its locked waiting owner record before main-lock admission, then transitions it to admitted through a per-coordinate transition gate under owner-directory serialization. The main lock is acquired before that short gate, so a blocked request cannot convoy compatible peers or prevent the current holder from releasing. Diagnostics list admitted holders before queued waiters, rendezvous with every in-progress admission before returning a stable snapshot, and cannot reap a partially published record. Failed publication removes its exact token; if the filesystem also refuses that cleanup, the operation fails closed and reports the retained token as cleanup uncertainty. Teardown always releases the main lease even when owner-metadata finalization fails, while reporting retained metadata uncertainty for later diagnostic reaping. If main-lease release itself cannot be confirmed, the owner record is durably marked release-uncertain and retained as explicit recovery evidence. Requests acquire that deterministic order. A writer queued for one coordinate precedes later readers of that coordinate, while unrelated resources continue: two builds on different worktrees of one repository overlap, and init/sync for distinct checkouts do not convoy. Multi-source writers use all-or-none retry, so waiting for one busy source does not retain earlier disjoint source coordinates. Distinct explicit topology ports use exact startup locks; only automatic port selection briefly uses the allocator mutex.

A build holds its profile-name lease while deriving the requested target's transitive provider closure, then locks only those selected sources and revalidates them. Clean primary inputs are exported atomically into reusable, commit/tree/subpath-keyed read-only generations below workspace/build/source-generations/. Publication flushes every sealed source file and directory, compares a descriptor-pinned whole-tree identity, content, and mount-boundary inventory immediately before the no-replace rename, then flushes the containing directory; reuse verifies ownership metadata and a complete tree digest plus the exact recorded Git tree and the captured checkout, source, and common-Git canonical filesystem paths. An incomplete generation with exact marker ownership is atomically retained as a recovery transaction only after a pinned traversal excludes nested mounts, then rebuilt at its canonical key; uncertain ownership fails closed. Recovery transactions remain visible to preview-first builds cleanup and its normal grace period. No generation links or hard-links back to mutable primary files. Existing generations are authenticated under a shared per-key lock; only an absent or conclusively corrupt generation takes the exclusive creation lock and rechecks after admission. Every generated path is revalidated after the build takes its shared pin; only then are its primary source leases released. Dirty primaries and worktrees stay locked for as long as the build can read them. Cache and region-map coordinates come from the captured snapshot or generation metadata rather than rereading a released primary. The build persists original filesystem/Git observations and immutable generation paths and digests in .atrinik-profile-resolution.json, and does not reread a mutable profile by name. Profile or topology publication and worktree removal share any remaining live target source lease, so cleanup cannot race a newly published exact reference. Cleanup apply locks and revalidates one stable-sorted candidate at a time, skips busy candidates, and journals completed actions in workspace/cleanup-journals/.

Waits longer than 10 seconds report the resource kind, stable coordinate, known owner operation, and supported recovery command without relying on a namespace-local PID. Owner records are written and locked in a private staging directory, then linked atomically into the diagnostic namespace; stale-record scans therefore never observe a new record before its live-owner lock is established. Legacy records are retained conservatively because their visible publication predates that invariant. The wrapper fails closed when advisory shared locking or resource identity is unavailable. Active preparation leases are inherited by subprocesses. Build and startup hold profile, source, and build-root leases only until a sealed runtime generation is published. Foreground processes then retain the runtime-generation lease plus server state when applicable; supervisors and guardians retain only runtime-generation, process-tree, server-state, and generation-specific port-reservation leases.

Classic Linux servers that publish atrinik-server-capabilities.json beside the executable use the inherited private-state descriptor contract. The wrapper copies that artifact into the sealed generation and verifies its exact schema and executable SHA-256 under the generation lease before selecting --datapath_fd=N --datapath=./data. It repeats the capability, descriptor, lock, and exact data -> /proc/self/fd/N checks immediately before launch. An absent artifact preserves legacy arguments; a present invalid artifact stops startup. Foreground servers use the same checks; offline provisioning keeps its ordinary path contract. Newly created Classic state roots are private (mode 0700), even when the source template is public. Existing state permissions are preserved; capability launches reject an existing state root that is not private.

The common-Git repository-layout.lock is the bounded maintenance barrier for schema/layout migration apply or restore. Ordinary exact-lease operations share the barrier, so they overlap one another but cannot race an exclusive migration; subprocesses inherit it only while they retain their exact operation leases. Migration entry points require or derive this physical barrier rather than falling back to the state-root-local legacy lock.

The supervisor records exact source commits/trees, build metadata, runtime digests, state paths, and process start identities. ps without a name lists every recorded topology; a name selects one. It distinguishes a live process from a reused PID, and down signals only processes holding that topology's identity lease, including orphaned services and descendants. The server state remains locked for the complete supervised lifetime. Each topology also has a persistent isolated client configuration/cache root and a complete sealed executable runtime, so rebuilding a profile or changing/removing a selected worktree cannot alter a live topology. Server-generated transport files live below a generation-named directory inside the exclusively leased state and are reached through the published state exception; copied maps are sealed beside that output and bound into the manifest, while other served inputs remain sealed inside the runtime generation. The inherited identity lease atomically prevents the same topology name from restarting while any generation remains. Server services do not inherit allocator, transaction, or generation reservation descriptors; the supervisor and same-generation guardian retain the exact reservation and release it after orderly shutdown or exact process-tree recovery. ps --json exposes its port, owner, generation, and retained/released observation without credentials. Reservation records are never reclaimed from recorded PIDs. Logs live below workspace/topologies/ and rotate at 10 MiB with three backups.

Use case: run the latest playable classic branches

Use this after first cloning the wrapper, or when returning to development and wanting a known-current baseline:

cd ~/atrinik
./atrinik init
./atrinik init --with classic
./atrinik sync --with classic
./atrinik topology show classic
./atrinik up --name classic-main --profile classic --default-state
./atrinik ps classic-main
./atrinik logs classic-main server --follow
# Press Ctrl-C to stop following logs; the services keep running.
./atrinik down classic-main

This is useful for ordinary playtesting and for proving that a problem also exists without any feature worktree. The initial replacement-only init is shown separately to emphasize that --with classic adds to it. sync refuses dirty primary repositories and never initializes an absent checkout, so it cannot silently overwrite work or expand the workspace.

Use case: develop the classic server in a monorepo worktree

Create one full classic repository worktree and select it for the entire classic checkout. The branch may change only server/, but all five logical components resolve from the same branch:

./atrinik worktree create classic socket-fix \
  --branch fix/socket-timeout
./atrinik profile create socket-fix --from classic
./atrinik profile set socket-fix classic --worktree socket-fix
./atrinik topology show socket-fix
./atrinik state add socket-fix
./atrinik up --name socket-fix --profile socket-fix --state socket-fix

cd "$(./atrinik path classic-server --profile socket-fix)"
git status
# Edit, test, commit, and push here as in any normal Git repository.

cd ~/atrinik
./atrinik logs socket-fix server --follow
./atrinik down socket-fix

This is useful for a server-focused pull request: the wrapper resolves server/ and every related classic source from one coherent monorepo commit, then rebuilds the affected dependency closure. Unchanged source directories in that worktree naturally match the branch's base commit; they are not selected from a second classic checkout.

Use case: combine client, server, and content pull requests

Client and server pull requests now belong to the same atrinik/classic repository. Fetch both, combine them into one monorepo branch and worktree, then select that checkout alongside the independent content worktree. A profile cannot select two worktrees for one physical checkout. Substitute the actual pull-request numbers:

git -C classic fetch origin pull/CLIENT_PR/head:review/client-ui
git -C classic fetch origin pull/SERVER_PR/head:review/server-combat
git -C content fetch origin pull/CONTENT_PR/head:review/content-maps

./atrinik worktree create classic combined-classic \
  --branch review/combined-classic --from review/server-combat
./atrinik worktree create content maps-review \
  --branch review/content-maps --existing

./atrinik profile create combined-review --from classic
./atrinik profile set combined-review classic --worktree combined-classic
./atrinik profile set combined-review content --worktree maps-review

CLASSIC_SOURCE="$(./atrinik path classic-server --profile combined-review)"
git -C "$CLASSIC_SOURCE" merge --no-edit review/client-ui

./atrinik topology show combined-review --json
./atrinik state add review
./atrinik up --name combined-review --profile combined-review --state review
./atrinik ps combined-review --json
./atrinik logs combined-review --follow
./atrinik down combined-review

Resolve and commit any merge conflicts before building. Git accepts the resolved server/ source as -C because it belongs to the full classic worktree; the merge still combines the entire repository. Content is collected from its separate worktree before launch, while all classic source roots come from the one combined commit. The JSON topology output is an exact checkout/source bill of materials for review notes or agent automation.

Use case: review new maps with unchanged binaries

Keep the classic client and server on their synchronized primary checkouts and select only the shared content@main worktree:

./atrinik profile create map-check --from classic
./atrinik profile set map-check content --worktree maps-review
./atrinik topology show map-check
./atrinik state add map-check
./atrinik up --name map-check --profile map-check --state map-check
./atrinik logs map-check server --follow
./atrinik down map-check

This is useful when a map/content pull request needs a real server and client but should not be tested against unrelated native branches. Automatic collection means there is no manual copy step and no generated output is written into the content worktree.

Use case: reuse one persistent server world across worktrees

Register an existing server-data directory once, then select it by name from any topology:

./atrinik state add shared --path /workspaces/atrinik/server-data
./atrinik up --name combined-review --profile combined-review --state shared
./atrinik down combined-review
./atrinik up --name classic-main --profile classic --state shared
./atrinik down classic-main

This is useful for comparing a feature topology with main using the same accounts and world state. Run them sequentially: the coordinator deliberately refuses to start two servers against the same state directory at once.

Use case: compare two source combinations safely

Clone a profile, change one selector, inspect both bills of materials, and run them one after the other against the same named state:

./atrinik profile create candidate-b --from combined-review
./atrinik profile set candidate-b classic --primary

./atrinik topology show combined-review --json
./atrinik topology show candidate-b --json

./atrinik up --name combined-review --profile combined-review --state shared
# Exercise the first combination.
./atrinik down combined-review

./atrinik up --name candidate-b --profile candidate-b --state shared
# Repeat the same exercise with the primary classic checkout.
./atrinik down candidate-b

Separate path-keyed build trees prevent the two combinations from overwriting one another, while the common state makes the comparison repeatable.

Use case: run classic and replacement topologies at the same time

Once the replacement components' wrapper build/runtime adapters and integrated service closure land, use distinct profiles, topology names, server states, and ports to run classic beside default. This is the required isolation pattern; today only the classic command is runnable:

./atrinik state add classic-world
./atrinik state add replacement-world

./atrinik up --name classic-side --profile classic \
  --state classic-world --port 17300
# Available after replacement runtime contracts land:
./atrinik up --name replacement-side --profile default \
  --state replacement-world --port 17301

./atrinik ps
./atrinik logs classic-side server --follow
./atrinik logs replacement-side client --follow

./atrinik down classic-side
./atrinik down replacement-side

This is useful for side-by-side regression checks, protocol experiments, and reviewing two pull-request combinations without stopping either one. Each client is pinned to its own server fingerprint and has separate settings and caches. A managed client's native window title includes both its topology and profile, for example Atrinik Client — topology classic-side - profile classic. Use the topology name shown there with ./atrinik ps NAME --json, ./atrinik logs NAME client, and ./atrinik down NAME; clients from the same profile remain distinguishable by topology. Omit both --port options to have the coordinator choose two available ports. Two live servers may not use the same state directory; the state lock turns that mistake into an immediate error instead of mutable-data corruption. The same rule applies to parallel agents: allocate a unique topology name, profile, state, and port for each run. Inspect or recover by exact topology name (./atrinik ps NAME --json), never through a broad topology cleanup.

Use case: run only a headless server

In a terminal without display forwarding, start only the server and inspect it from another shell:

./atrinik up --name combined-review --profile combined-review \
  --state review --service server
./atrinik ps combined-review
./atrinik logs combined-review server --follow
./atrinik down combined-review

This is useful for protocol, content, runtime, and server work where opening a graphical client would be distracting or impossible.

Use case: clean up after a completed review

Stop the topology before removing checkout worktrees. Removal refuses dirty worktrees, so commit, stash, or otherwise preserve intentional edits first:

./atrinik down combined-review
./atrinik cleanup --scope topologies combined-review --older-than 0 --dry-run --json
./atrinik cleanup --scope topologies combined-review --older-than 0 --apply --json
./atrinik profile set combined-review classic --primary
./atrinik profile set combined-review content --primary
./atrinik cleanup --scope worktrees --scope builds \
  classic content --older-than 7 --dry-run
./atrinik cleanup --scope worktrees --scope builds \
  classic content --older-than 7 --apply

The saved combined-review profile protects both selected worktrees until the explicit profile set commands repoint it. Do that only when the retained review selection and stopped topology history are no longer useful, then preview each cleanup scope. Only the explicit topologies scope removes eligible topology records and logs. Cleanup never removes profiles, scenarios, registered or scenario state, migration evidence, commits, or branches. Only the explicit temporary-states scope can reclaim an abandoned, unregistered, disposable generation state after exact revalidation.

Delivery-ledger sidecars are not ordinary cleanup targets. A merge-ready PR keeps its active coordinates and recovery evidence. After the PR is externally merged and selected issues reach their expected states, a separately authorized operator prepares exact post-merge evidence and runs:

Actor identity is live evidence for delivery. Issue-mode genesis captures the viewer login/node and push authority for every target repository in one live authenticated response before generation-1 publication; a mixed or stale tuple fails before local staging or any delivery mutation. pr-bind-cas repeats the complete tuple immediately before its CAS. If the actor changes after genesis but before PR binding, use only the helper's recover-prebind-identity transaction: it preserves the predecessor digest/history and exact target/artifact coordinates, and requires an explicit recovery authority, a safe bound worktree, live reproof, and no candidate PR.

Target base/head movement is likewise helper-owned: generic ledger CAS rejects it. The target-refresh CAS pins the recorded primitive/scope worktree, proves descendant commits and the exact live merge base, and rechecks immediately before replacement. Fresh issue-mode draft PR binding is similarly helper-owned: bind-check is only a diagnostic, while pr-bind-cas re-proves the authenticated PR, comments, target, and bound worktree immediately before its private CAS. An explicit recovery can correct one historical nonexistent head plus its bound stale merge base while retaining both source generations.

python3 scripts/delivery_ledger.py \
  release-preview build/reviews LEDGER_NAME release.json
python3 scripts/delivery_ledger.py \
  release-apply build/reviews LEDGER_NAME release.json --plan PLAN_SHA256

Release uses a pinned gh against github.com, re-observes the exact terminal PR/issue state and actor, and requires authority issued strictly after merge. It holds wrapper leases while verifying the recorded clean worktree and either Git ancestry or exact squash-change equivalence again after staging, then durably marks the ledger inert; it removes nothing. Next run the relevant ./atrinik cleanup --dry-run --json, review it, and independently run the same scoped command with --apply. Retain the exact raw preview/apply JSON in the archive evidence; the helper validates both reports and requires identical command coordinates, derives their canonical target selection, verifies the wrapper's schema-2 journal request, original report, completion, and timestamp order, and holds the exact wrapper coordinates through a final absence recheck and archive installation. An active scope can transition only when its live generation-matched scope release journal is complete. That journal is the removal evidence for its scope-produced worktree, which is not fabricated as a generic cleanup action.

After cleanup, a new explicit authority issued strictly after cleanup apply may bundle the canonical ledger, release marker, lock, report, migration evidence, and retained intent:

python3 scripts/delivery_ledger.py \
  archive-preview build/reviews LEDGER_NAME archive.json
python3 scripts/delivery_ledger.py \
  archive-apply build/reviews LEDGER_NAME archive.json --plan PLAN_SHA256

The one bounded archive remains audit evidence without reserving active coordinates. Once its recorded retention period has elapsed, use the helper-clocked reclaim-preview and pass the complete returned preview plus its digest to reclaim-apply. Reclaim retains one fixed terminal completion checkpoint after its quarantined exact-path removal; the next successful reclaim replaces that checkpoint, bounding review-root growth. These helper commands never delete worktrees, profiles, topologies, state, branches, or runtime resources. See the issue-delivery ledger reference for the strict evidence schemas and crash-recovery rules.

Server state policies

The built-in state named default is initialized once at workspace/state/server/default and then reused by every profile. Register a second managed state or an existing compatible directory when isolation is useful:

./atrinik state add review
./atrinik state add existing --path /absolute/path/to/server-data
./atrinik state list
./atrinik run server --profile maps-review --state review --port 1730
# In another terminal, after the server reports that it is ready:
./atrinik run client --profile maps-review --state review --port 1730

State contains player, key, unique-item, and other mutable runtime data. It is never regenerated over an existing directory. A nonblocking lock prevents two coordinator-launched servers from using the same state simultaneously. Managed default, named, scenario, and temporary state records preserve their distinct policy and owner identities; an optional implementation marker causes future Classic/replacement mismatches to fail closed instead of sharing an incompatible directory. Registered external paths remain outside wrapper deletion ownership. Scenario state remains registered, scenario-owned, and resettable only through scenario reset; it is not temporary topology state. Repository migration never moves, rewrites, or retags an existing state; state ownership evolution is a separate migration contract.

Arguments after -- are forwarded to the selected executable:

./atrinik run server --profile maps-review --state review -- --version
./atrinik run client --profile maps-review --state review -- --help

The foreground commands are a paired local-development path: use the same --state and --port in both terminals. The server always starts with automatic port mapping and STUN discovery disabled. The client reads the state's generated QUIC certificate, adds its authenticated loopback endpoint, and starts with metaserver and STUN discovery disabled. Its native title shows profile PROFILE (direct run) so it cannot be confused with a supervised topology. The bounded launch identity exists only in the child process environment; it is not saved to client configuration or used as package, protocol, or network user-agent version data. Clients started outside the wrapper retain the ordinary package title. Start the server first so that its persistent quic-identity.pem exists. Additional arguments are appended after these defaults, and join-password arguments are redacted from command logging. Each command first publishes a random command-owned immutable generation, releases source/layout/build leases, runs with only that generation lease (and server state for the server), then reclaims the exact generation on normal exit. Prefer up for routine use because it allocates a port, captures the fingerprint, and sequences both processes automatically.

Workspace location and recovery

Set ATRINIK_WORKSPACE_DIR to an absolute path before invoking the command to place generated worktrees, profiles, builds, and state elsewhere:

export ATRINIK_WORKSPACE_DIR=/workspaces/atrinik-data
./atrinik init

Primary physical repositories remain directly beside the wrapper even when this variable is set. The coordinator marks directories it owns and refuses to replace unmarked paths. Component Git history is authoritative; profiles are small ignored JSON files and can be recreated. Back up persistent state separately. See docs/ARCHITECTURE.md for data-flow and safety details.

Validation

python3 -m pip install --requirement requirements-dev.txt
python3 -m coverage run -m unittest discover -v --durations 50
python3 -m coverage report --show-missing
python3 -m compileall -q atrinik atrinik_workspace tests
./atrinik manifest validate
./atrinik cleanup --scope all --older-than 7 --dry-run --json

The required workflow runs deterministic measured shards, verifies exact-once discovery, and combines branch coverage behind one stable Integration validation check. Its latency budget and evidence method are documented in docs/CI_PERFORMANCE.md.

For supported process-isolated local execution, see docs/LOCAL_TESTING.md. It covers targeted tests, serial fallback, fast parallel runs, and parallel branch coverage.

Use ./atrinik build COMPONENT --profile classic --test for current native component integration. Replacement repositories run their standalone aggregate validations today; wrapper builds still fail with a clear unavailable-contract error until their adapters land. The metaserver-worker wrapper contract runs its complete npm run check suite.

Retained corrected Classic deliveries can advance an accepted dependency through advance-retained-dependency-cas. For those deliveries, topology show and up require the exact --retained-build-plan SHA256 fence. The runtime gets a distinct plan-derived build root, preserving the historical scenario and build evidence.

Retained correction dependency advancement can bind one immutable atrinik/content@main input at declaration, the first plan, or a new content-plan/content-built successor after an already completed build. Live merged-PR provenance and clean read-only content source observations are required; historical content/build/runtime/state evidence and undeclared dependency inputs remain unchanged. See the retained resource correction protocol.

For a retained producer used by an isolated executor, the public runtime handoff publishes an immutable envelope in the existing shared build namespace and requires a live coordinator lease on every consume. topology show PROFILE and up accept --runtime-handoff, --handoff-issue, --handoff-attempt and independently pinned --handoff-publisher and --handoff-endpoint alongside --retained-build-plan. Coordinator-private review mounts remain isolated.

About

Atrinik multi-repository development workspace and component coordinator

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

32 stars

Watchers

10 watching

Forks

Releases

Packages

Used by

Contributors

Languages