CLI guide · Harness

paniolo worktree pool

Keep a pool of pre-warmed Git worktrees for one repository and hand each coding agent its own slot. This page covers the configuration, the slot lifecycle, and every subcommand with its options, output, and refusals. For the overview, see worktree slots. Slots isolate files and caches but not the machine; pair them with paniolo queue to keep heavy gates from colliding on shared hardware.

Availability

Ships with the CLI

paniolo worktree pool is part of @paniolo/cli and the native Harness packages. It needs no account. paniolo worktree pool --help shows what your binary carries.

VersionAdds
0.5.97The public pool: status, init, adopt, claim, release, refresh, cleanup, and the advisory primary lease.
0.5.98The revision-aware Codex hook.
0.5.99Pool state shared with Ranch Hand's internal pool, migrated in place.
0.5.101reclaim frees another owner's stale claim when its work is merged or pushed, from the CLI or the MCP worktree_write tool.
0.5.100init creates every configured slot; claim checks the branch name before reserving and accepts --from; failed claims can be recovered; status adds claim age, last activity, --stale-hours, foreign-owner reasons, and unmanagedWorktrees; per-slot ports with slotPorts and env; --format json on claim, release, and refresh; release accepts a branch equal to its upstream; MCP tools for every command; worktree commands skip presentation-mode lookup, so hooks start faster.

Options and output marked Since 0.5.100 below need that version or later; paniolo --version shows yours.

Concepts

Pools, slots, owners, states

A pool belongs to one repository named in the harness paniolo.config.json. Its slots are Git worktrees at fixed paths, listed in allocation order. Each slot is a normal linked worktree that Git has locked, so git worktree prune cannot remove it.

An owner is any nonempty string that identifies one agent session, such as a session ID. Every command that changes a claim takes --owner and refuses to act on another owner's slot.

Pool state is one JSON file in the repository's Git common directory, .git/paniolo/worktree-pool/state.json, shared by every worktree of that repository. Each change happens under a lock and increments the pool revision. Do not edit the file by hand; every recovery has a command.

StateMeaning
idleClean, detached at the base ref, locked, and free to claim.
warmingReserved by an operation in progress: a claim, release, refresh, or cleanup.
claimedHeld by an owner on a topic branch.
failedAn operation stopped partway. The slot's files and any branch are kept, and the slot stays unavailable until it is recovered.
unknownShown by status only: the configured path has no record in the state file yet. Use init or adopt.

A slot's preparation receipts record each preparation step's fingerprint: a hash of its input files and of the versions of its programs. A step runs again only when that fingerprint changes, a required output is missing, or the step is marked alwaysRun.

Configuration

The worktreePool block

Declare the pool under the repository in the harness config, so the product repository carries no agent-specific files. Paths are validated before any command runs Git.

{ "repos": { "my-app": { "path": "repos/my-app", "worktreePool": { "root": "repos", "slots": [".dev-worker-my-app-01", ".dev-worker-my-app-02"], "baseRef": "origin/main", "hostOs": "windows", "minFreeBytes": 1073741824, "cacheRoot": "../caches/my-app", "preparation": [ { "name": "pnpm", "program": "pnpm.cmd", "versionPrograms": ["node"], "args": ["install", "--frozen-lockfile"], "timeoutSeconds": 900, "inputs": ["pnpm-lock.yaml", "package.json"], "requiredOutputs": ["node_modules/.modules.yaml"] } ], "cleanup": [ { "kind": "merged-branches", "branchPatterns": ["codex/*", "claude/*"] } ], "pruneMergedBranches": true, "primaryLease": false } } } }

Pool fields

FieldRequiredMeaning and rules
rootYesDirectory that holds the slots, relative to the config file or absolute. No .. segments.
slotsYes1 to 16 slot paths relative to root, in allocation order. Relative, no traversal, no drive letters, and unique without regard to case. --slot N options count from 1 in this order.
baseRefYesA remote tracking branch such as origin/main. Idle slots sit detached here, and new topic branches start here.
hostOsYeswindows, linux, or macos. Commands refuse to run on another OS, so a Windows slot is never driven from WSL and its caches stay valid.
minFreeBytesYesFree space required under root before init creates a slot. Must be greater than zero.
cacheRootNoA shared cache directory, relative to the config file or absolute. Required by cleanup steps whose targetRoot is cache.
preparationNoOrdered trusted steps that make a slot ready. See below.
cleanupNoOrdered bounded cleanup steps. See below.
pruneMergedBranchesNoOpt-in required by merged-branches cleanup. Default false.
primaryLeaseNoAllows the advisory primary checkout lease. Default false.
slotPortsNoSince 0.5.100. Named port bases, such as {"vite": 5100}. See ports for each slot.

Preparation steps

Each step runs one program with an argument list and no shell, so nothing is interpolated. Steps run in order during claim and refresh.

FieldRequiredMeaning and rules
nameYesUnique, nonempty step name. Shown in claim and refresh output.
programYesThe executable to run, resolved in the slot.
argsNoArguments passed as a list.
versionProgramsNoExtra tools whose --version output joins the fingerprint, such as node or rustc. The step's own program is always included.
timeoutSecondsYes1 to 86,400. A step that runs longer fails the operation.
inputsYes, unless alwaysRunRelative files or directories whose contents form the fingerprint. They must exist and stay inside the slot.
requiredOutputsYesRelative paths that must exist after the step. A missing output reruns the step next time.
alwaysRunNoRun on every preparation, for cheap checks such as a certificate probe.

Cleanup steps

Cleanup uses two fixed Rust implementations, not configured commands. It never force-deletes, never touches a dirty tree, and never leaves the slot or the cache root.

KindFieldsWhat it removes
cargo-stale-link-outputstargetRoot (slot or cache), target (relative Cargo target directory), minAgeDays (positive)Linked test and binary outputs under each profile's deps/, such as MSVC .exe and .pdb pairs, unused for at least minAgeDays. It keeps what makes the next build fast: .rlib, .rmeta, .d, build/, incremental/, and .fingerprint/.
merged-branchesbranchPatterns: bounded prefix/* patterns. Requires pruneMergedBranches: true.Local branches that the slot has used, that match a pattern, and whose tip is merged into the base or exactly pushed to the remote.

Ports for each slot

Since 0.5.100. Give every checkout its own dev and test ports, so you can review several agents' branches side by side in the browser, and a test run in one slot never takes over another slot's server. Declare named port bases:

"slotPorts": { "vite": 5100, "api": 8700, "e2e-vite": 5200, "e2e-api": 8800 }

Checkout N serves each name on base + N. A slot's number is its directory name's trailing digits, so .dev-worker-my-app-07 is slot 7, with Vite on 5107, the API on 8707, and e2e servers on 5207 and 8807. A name without trailing digits uses its position in slots, counting from 1. The primary checkout is slot 0 and gets the bases themselves.

Give e2e runs their own names. If tests reuse the dev ports, starting a test run in a slot stops the dev server a person has open there.

Up to 8 names, each lowercase letters, digits, or -. Slot numbers must be unique and between 1 and 999, and every base plus the highest slot number must stay within 65535. Scripts read the result with env. If a port must be registered somewhere ahead of time, such as an OAuth redirect URL, register each slot's port once.

Different slots on each machine

A fast workstation can run more agents at once than a laptop, and each slot costs disk for its dependencies and build output. Keep the shared pool in paniolo.config.json, and override it per machine in a paniolo.config.local.json beside it. Keep that file out of Git; it holds one developer's preferences, not shared policy.

For example, on a laptop, one slot and a smaller space reserve:

{ "repos": { "my-app": { "worktreePool": { "slots": [".dev-worker-my-app-01"], "minFreeBytes": 536870912 } } } }
  • Objects merge, everything else replaces. Name only the fields that differ. An array such as slots or preparation replaces the shared one completely, so list every slot this machine should use.
  • Each machine keeps its own pool state. State lives in each clone's .git directory, so machines never see each other's slots or claims.
  • Commands read only the configured slots. A slot you drop from the list keeps its files on disk, and the pool stops managing it. Delete it yourself or keep it for later. status lists such worktrees under unmanagedWorktrees.
  • The overlay loads only next to a file named paniolo.config.json. The default config lookup finds it; a --config path to a file with another name skips it.
Common options

Every subcommand

OptionMeaning
--repo KEYThe repository key under repos in the config. Required. An unknown key, a repository without a pool, or a host OS mismatch is refused before Git runs.
--config PATHThe config file. Defaults to the nearest paniolo.config.json in the current directory or a parent, so run commands from the harness root.
--format jsonAccepted by status and cleanup, and since 0.5.100 by claim, release, and refresh. JSON is the only format and the default.

Commands print JSON on stdout and exit 0 on success. A refusal prints a message on stderr and exits nonzero without changing pool state, unless the command reports that a slot was marked failed.

Command

status

paniolo worktree pool status --repo KEY [--stale-hours N] [--format json] [--config PATH]

Reads every configured slot and the pool state, and changes nothing in Git or the state file. Run it before choosing a checkout.

OptionMeaning
--format jsonOutput format. JSON is the only format and the default.
--stale-hours NSince 0.5.100. List only claimed, warming, or failed slots with no commit or file change for at least N hours. It reports likely abandoned claims and never frees them.
{ "repo": "my-app", "revision": 42, "slots": [ { "path": "repos/.dev-worker-my-app-01", "state": "claimed", "owner": "codex-sessio", "branch": "codex/topic", "host": "windows", "registration": "linked", "locked": true, "clean": false, "unavailableReason": "worktree is dirty", "claimedAt": 1793900000, "lastActivityAt": 1793912345, "inactiveSeconds": 120 } ], "primary": null, "unmanagedWorktrees": ["repos/.dev-worker-my-app-legacy"] }
FieldMeaning
revisionThe pool revision, or null before any state exists.
stateOne of the slot states.
ownerThe claim owner, shortened to 12 characters.
branchThe checked-out branch, or the claim's recorded branch.
registrationlinked, missing (no directory), unregistered (a directory Git does not know), redirected (a junction or symlink), or primary.
locked, cleanGit lock and working-tree state. clean is null when Git could not inspect the checkout.
unavailableReasonWhy the slot cannot be claimed now, checked in this order: registration, a checkout owned by another account, an unlocked worktree, a dirty tree, a stored failure, then any non-idle state. null means the slot is ready.
failureFor a failed slot: the code, operation, phase, path, and Windows error code if any.
claimedAt, lastActivityAt, inactiveSecondsSince 0.5.100. Unix seconds when the claim began; Unix seconds of the newest commit or uncommitted file change in the checkout; and seconds since the later of the two.
slotNumber, portsSince 0.5.100. The slot's number and, with slotPorts, its ports by name. claim returns them too.
primaryThe advisory primary lease, if one is held.
unmanagedWorktreesSince 0.5.100. Linked worktrees under root that the config does not list as slots, such as legacy manual slots. Omitted when empty.
Command

init

paniolo worktree pool init --repo KEY [--slots N] [--apply] [--config PATH]

Previews, then creates, configured slots. Without --apply it only prints each resolved path and the free space it found. With --apply it creates each missing slot as a detached worktree at baseRef, locks it, and records it as idle. Running it again is safe.

OptionMeaning
--slots NInitialize the first N configured slots. Since 0.5.100: defaults to every configured slot and refuses N larger than the list. In 0.5.99, init handles only the first slot.
--applyCreate the slots. Without it, nothing changes.

Each slot prints one line: preview, created, already initialized, or in use (claimed) for a slot with a non-idle record, followed by the path and free bytes.

It refuses when free space under root is below minFreeBytes, when the root is redirected or a slot's parent escapes it, when a path already exists but is not a registered worktree, and when an existing slot is dirty or unlocked. It never overwrites a directory. To bring an existing worktree under management, use adopt.

preview: C:\work\repos\.dev-worker-my-app-01 (213906612224 free bytes) created: C:\work\repos\.dev-worker-my-app-01 (213906612224 free bytes)
Command

adopt

paniolo worktree pool adopt --repo KEY --path SLOT_PATH [--apply] [--config PATH]

Imports a worktree you already have, keeping its files, including ignored build output and dependencies. Without --apply it only checks the candidate.

The path must be one of the configured slots, not reached through a junction or symlink, and a clean, detached, Git-locked linked worktree. Adoption also refuses a slot another owner has claimed, and a legacy manual claim ref under refs/bardoshare/warm/. Since 0.5.100: a checkout owned by another account is refused with that account's name.

Output is adopted: PATH, or preview or already adopted: PATH. Adding a slot to slots in the config comes first; adopt only accepts configured paths.

Command

claim

paniolo worktree pool claim --repo KEY --owner OWNER --branch BRANCH [--config PATH] paniolo worktree pool claim --repo KEY --owner OWNER --from origin/BRANCH [--branch NAME] paniolo worktree pool claim --repo KEY --owner OWNER --slot primary [--accept-existing-state --handoff LABEL]

Reserves a slot for one owner and checks out a topic branch in it. Use the path it returns; do not guess a slot.

OptionMeaning
--owner OWNERYour session's owner ID. Required and nonempty.
--branch BRANCHThe new topic branch. It must be a valid branch name. Since 0.5.100: an existing local branch with this name is refused before any slot is reserved.
--from REFSince 0.5.100. Start the branch at an existing ref instead of baseRef, such as an open pull request's branch. A REMOTE/BRANCH ref is fetched, the slot is prepared against it, the new branch tracks it, and --branch defaults to the remote branch's name. An unresolvable ref is refused before any slot is reserved.
--slot primaryTake the advisory primary lease instead of a managed slot.
--accept-existing-state, --handoff LABELPrimary lease only: accept a dirty primary checkout and label the handoff.

What a managed claim does

  1. If this owner already holds a claimed slot, it returns that slot with "reused": true and changes nothing.
  2. Since 0.5.100: it returns this owner's earlier failed claims to idle when their checkouts are still clean, detached, and locked.
  3. It reserves the first idle, clean, locked, detached slot in config order, marking it warming. Two agents can never reserve the same slot.
  4. It fetches the base branch and detaches the slot at baseRef, or at --from.
  5. It runs configured cleanup, then the preparation steps whose fingerprints changed.
  6. It creates the topic branch, checks that the worktree is still linked, locked, clean, and on that branch, and marks the slot claimed.

If any step after the reservation fails, the slot is marked failed, with its files kept, and the error is returned. See recovery.

{ "path": "C:\\work\\repos\\.dev-worker-my-app-02", "branch": "codex/topic", "revision": 43, "owner": "codex-session-1234", "reused": false, "prepared": ["pnpm"] }

prepared lists the steps that ran this time. Steps whose fingerprints matched are reused and not listed.

Command

release

paniolo worktree pool release --repo KEY --path SLOT_PATH --owner OWNER [--config PATH] paniolo worktree pool release --repo KEY --slot primary --owner OWNER [--handoff LABEL] [--handoff-back LABEL]

Returns an owned slot to the pool only after proving the work is preserved. It refuses, and leaves the claim unchanged, when:

  • the path is not a configured slot, or the slot is not claimed by this owner;
  • the checkout is dirty, unlocked, or on a different branch than the claim;
  • the branch head is neither merged into baseRef nor exactly equal to the remote branch of the same name, nor, since 0.5.100, exactly equal to the branch's configured upstream.

Push the branch under its own name, or merge it, before releasing. Since 0.5.100: a branch claimed with --from origin/x --branch y can also be pushed to its upstream, git push origin HEAD:x. On success the slot is detached at the base, cleanup runs, and the slot becomes idle with its caches kept. The local topic branch stays; delete it with git branch -d, which refuses an unmerged branch.

Since 0.5.100: the owner of a claim that failed before its branch was created can release it too. That returns a clean, detached, locked checkout to idle.

{ "path": "C:\\work\\repos\\.dev-worker-my-app-02", "state": "idle", "revision": 44 }

reclaim

paniolo worktree pool reclaim --repo KEY --path SLOT_PATH [--stale-hours N] [--apply] [--config PATH]

Since 0.5.101. Frees another owner's claim when the session that made it is gone and nothing can be lost. Both must hold:

  • Stale: no commit, file change, or new claim for N hours. The default is 24; the minimum is 1.
  • Preserved: the same proof release uses, a clean tree whose branch is merged into the base or exactly pushed.

It releases the slot under its recorded owner through the same code as release. Without --apply it only reports what it would do. A refusal names what would be lost, so you know what to save first:

1 unpushed commit on codex/topic: not merged into origin/main and not pushed; save the work or ask codex-session-1234 1 uncommitted file in slot 2; save the work or ask codex-session-1234 claim by codex-session-1234 is not stale: inactive for 3 h, fewer than 24
Command

refresh

paniolo worktree pool refresh --repo KEY [--slot N] [--retry-failed] [--config PATH]

Moves idle slots to the latest base and reprepares them, so the next claim starts current. It fetches, detaches each slot at baseRef, and runs preparation. Claimed and failed slots are skipped; refresh never resets or switches a claimed checkout.

OptionMeaning
--slot NRefresh only the Nth configured slot, counting from 1.
--retry-failedRequires --slot. Retry a slot left failed by an earlier refresh, and, since 0.5.100, a claim that failed before creating its branch. It proceeds only if the checkout is clean, detached, locked, and linked; a dirty slot or one on a branch is refused.

Output is a list of {"path", "prepared"} objects. If a refresh fails, that slot is marked failed and the command prints a diagnostic with the exact retry command, then exits 1.

Command

cleanup

paniolo worktree pool cleanup --repo KEY [--slot N] [--owner OWNER] [--apply] [--retry-failed] [--format json]

Previews, then applies, the configured cleanup steps. claim and release already run cleanup, so this command is for reclaiming space on demand.

OptionMeaning
--slot NClean only the Nth slot. Without it, every idle slot is selected.
--owner OWNERClean your own claimed slot. Requires --slot, so cleanup can never select another owner's slot.
--applyRemove the listed items. Without it, cleanup only reports what it would remove.
--retry-failedRetry a slot left failed by an earlier cleanup. Requires --slot and --apply, without --owner, on a detached slot.
[ { "slot": "C:\\work\\repos\\.dev-worker-my-app-01", "items": [ { "path": "C:\\work\\repos\\.dev-worker-my-app-01\\target\\debug\\deps\\my_app-3f2a.exe", "bytes": 48123904, "step": "cargo-stale-link-outputs", "reason": "link output my_app-3f2a unused for 7+ days" } ], "removed": 1, "freedBytes": 48123904, "skipped": [] } ]

skipped explains steps that could not run, such as a shared cache that another operation holds. If a file is held open partway through, the slot is marked failed with the file and the Windows error code; nothing is force-deleted or scheduled for deletion on reboot.

Command · 0.5.100

env

paniolo worktree pool env --repo KEY [--path PATH] [--format dotenv|json] [--config PATH]

Names the checkout that contains a path, by default the current directory: a configured slot, or the primary checkout as slot 0. It prints that checkout's number and the ports from slotPorts, so dev and test scripts never have to work out the slot from a directory name themselves. It reads only the config and changes nothing.

PANIOLO_SLOT=7 PANIOLO_SLOT_PATH=C:\work\repos\.dev-worker-my-app-07 PANIOLO_PORT_VITE=5107 PANIOLO_PORT_API=8707 PANIOLO_PORT_E2E_VITE=5207 PANIOLO_PORT_E2E_API=8807

Port names become upper case, with - turned into _. --format json prints {"slot", "path", "ports"}. A path outside every slot and the primary checkout is refused.

Command

prompt-status

paniolo worktree pool prompt-status --repo KEY [--since REVISION] [--checkout PATH] [--owner OWNER]

Prints a one-line ownership notice of at most 512 bytes, for hooks and scripts that inject context into an agent session. It lists the primary lease and up to eight non-idle slots, then points at status for details. It reads state only and never runs Git.

OptionMeaning
--since REVISIONPrint nothing when the pool revision still equals this value and there is no conflict.
--checkout PATHThe agent's current directory. If another owner holds it, the notice starts with CONFLICT.
--owner OWNERThe agent's own owner ID, so its own claim is not reported as a conflict.
pool revision 43: warm path=C:\work\repos\.dev-worker-my-app-02 state=claimed owner=codex-sessio branch=codex/topic; inspect: paniolo worktree pool status --repo my-app
Command

hook

paniolo worktree pool hook --repo KEY --vendor codex --event session-start|user-prompt

A vendor hook adapter. Codex is the supported vendor. It reads the hook payload on stdin, takes the session ID as the owner and the payload's working directory as the checkout, and prints a hook response with the prompt-status notice.

  • session-start always reports the current claims.
  • user-prompt remembers the last revision each session saw and prints {} unless the pool changed or the checkout is in conflict.
  • Malformed input or a missing session ID prints {}, so a hook never blocks the agent.
{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"pool revision 43: ..."}}

Wire session-start. A process started on every prompt costs more than a 50 ms target on a busy Windows host, so prefer an explicit status for live views.

Optional

Primary checkout lease

With primaryLease: true, an agent that must work in the repository's main checkout can record that it is there. The lease is advisory: it shows up in status and in notices, but it cannot stop a person from editing. Teams that need separation should use managed slots.

  • claim --slot primary records the branch, head, and dirty paths without switching or preparing anything. It refuses a detached checkout or one leased by another owner. A dirty checkout needs --accept-existing-state and a --handoff LABEL.
  • release --slot primary closes the lease after proving the work is preserved. A label must match the one given at claim time. New dirty paths need --handoff-back LABEL, and unpushed commits are refused.
Recovery

When a slot is stuck

A failed slot

status shows "state": "failed" with the failure's phase and path. The slot's files and any branch are intact.

Failed duringRecover with
refreshrefresh --repo KEY --slot N --retry-failed
cleanupcleanup --repo KEY --slot N --apply --retry-failed
a claim, before its branch existedSince 0.5.100: the owner claims again or runs release; anyone can run refresh --repo KEY --slot N --retry-failed.
a claim, after its branch existedThe owner saves the work, then releases the slot.

Every retry first checks that the checkout is clean, detached, locked, and linked. A dirty checkout or one on a branch is refused so no work is lost; save that work yourself first.

A file is held open

On Windows a running process can hold a file in a slot. Refresh and cleanup then mark the slot failed, print a diagnostic, and exit 1. Close the holder and run the command in nextAction.

{ "code": "resource_busy", "operation": "cleanup", "slot": "C:\\work\\repos\\.dev-worker-my-app-01", "phase": "remove_stale_link_output", "path": "C:\\work\\repos\\.dev-worker-my-app-01\\target\\debug\\deps\\my_app-3f2a.exe", "win32Code": 32, "possibleProcesses": [{ "name": "my_app-3f2a.exe", "pid": 4120 }], "partialChange": false, "slotState": "failed", "nextAction": "Close possible holders, then run paniolo worktree pool cleanup --repo my-app --slot 1 --apply --retry-failed", "detail": "..." }

code is resource_busy for a sharing violation (Windows errors 32 and 33), access_denied_unknown for error 5, where the cause is uncertain, or file_operation_failed otherwise. possibleProcesses is a best-effort guess and may be empty. partialChange says whether anything was removed before the failure. The pool never kills a process.

An abandoned claim

The pool never frees another owner's slot on its own, because that could destroy unpushed work. Find candidates with status --stale-hours 24 and confirm nothing is running in the slot. If its branch is already merged or pushed and the tree is clean, reclaim (0.5.101 and later) frees it without the owner. Otherwise save its work to a branch first, then have the owner release it.

A checkout owned by another account

Git refuses a repository folder owned by a different operating-system account, reporting "dubious ownership". Since 0.5.100: status names that account in unavailableReason and adopt refuses with the same reason. Transfer ownership of the folder before adopting it.

For coding agents

A typical agent session

# 1. Look before choosing a checkout paniolo worktree pool status --repo my-app # 2. Claim a slot with your session ID and a new topic branch paniolo worktree pool claim --repo my-app --owner codex-session-1234 --branch codex/fix-login # 3. Work only in the returned path; commit, push, open a PR git -C <path> push -u origin codex/fix-login # 4. Release once the branch is pushed or merged and the tree is clean paniolo worktree pool release --repo my-app --path <path> --owner codex-session-1234 # 5. Remove the merged local branch git branch -d codex/fix-login

If every slot is busy, wait for an owner to release one; never reset or take over a claim. To keep working on an existing pull request, claim with --from origin/BRANCH instead of --branch.

Through MCP

Since 0.5.100. Agents connected to the Paniolo MCP server can do the same without a shell. The worktree tool runs status and env (pass your working directory as path), and worktree_write runs init, adopt, claim, release, reclaim (0.5.101), refresh, and cleanup with the same arguments in camelCase (retryFailed, acceptExistingState, primary: true for the primary lease). Both run the same code as the CLI and refuse the same inputs. If a claim's preparation outlasts your client's call timeout, submit it with job_submit as worktree.claim and poll job_status.

Rules worth giving your agents

The published paniolo-worktree skill carries these, so agents load them on their own:

paniolo skills add paniolo-ai/skills --skill paniolo-worktree
  • The harness keeps one checkout. A harness that contains its satellite repositories gets no slots and no worktrees: its gates read the satellites through the config, and a harness worktree has an empty repos/. Its only checkout is the primary, slot 00. Agents take turns there on topic branches and hand it back on main.
  • Gates check the configured checkout. paniolo wiki --config, scan --target, and skills bundle --check validate the path in paniolo.config.json, not your slot. Point a temporary config at the slot to validate it, and confirm the output names it.
  • Never under .cache. paniolo bootstrap clears it on every install.
  • The .dev-worker- prefix belongs to slots. Anything else under the pool root shows up in unmanagedWorktrees; check it for unpushed work before removing it.