# Worktrees and landing This file says how a task works in its own worktree and lands on `next` in a project whose delivery is `trunk`. The pstack block in `AGENTS.md` points here. The `sync-pstack` skill renders this file from its shared source in `udecode/dotai`, so change it there. - **Worktrees.** Every session works in its own worktree cut from `origin/next`, and its work reaches `next` only through land.mjs. It cuts that worktree when its task first needs to run or change project files, such as for a repro, not at intake. A fix that the block's Improve the workflow mid-task rule lands separately from the task's change, a reflect lesson for the project included, lands through land.mjs from a worktree of its own. The Claude Code desktop app refuses a worktree session's edits in a second worktree of the project. Such a session lands that fix from its own worktree once its task has landed, because land.mjs folds every change in a worktree into the task's commit. Once its task lands, a session finishes any reflect, the reread of the run's asks that the block's Todo list and close rule makes before the final reply, and the `chips` skill's Close that its run owes, then merges its run directories into the main checkout and runs `scan.mjs --landed`, in the order `.agents/pstack/rules/chips.md`'s Landing gives a card session. It leaves its worktree for the cleanup scan, which removes it after a quiet day, and locks the worktree when `scan.mjs --landed` does not exit 0. A session that works again after the cleanup scan removed its worktree first cuts a new worktree from `origin/next` and runs `node .agents/pstack/setup.mjs` there. A session the lead starts gets its own worktree, with `use_worktree: true` in Claude Code, and its brief names this file. A code delegate that writes files gets its own worktree as pstack's Feature step says, and the project's Claude Code settings set `worktree.baseRef` to `"head"`, so that worktree starts from the session's last commit. The main checkout only pulls; no agent edits or commits there, except under the plans directory's `artifacts/`, which git ignores. In that directory `decisions-check.mjs` appends suggested-task rows to the ledger, as `.agents/pstack/rules/chips.md` says, and runs write their run directories. A run directory holds logs and small outputs. A checkout a run builds or runs, such as a benchmark tree, an export or a probe, goes in a worktree in a temp folder, never in the run directory, and the run removes it when done, because the `cleanup` skill deletes a run directory's installs and builds after a quiet day. A worktree of another repository, such as a benchmark baseline, installs with that repository's own commands instead of `setup.mjs`. In Claude Code, `guard.mjs` denies an agent's Edit, MultiEdit, Write or NotebookEdit of a main-checkout file, `.git` included, while that checkout is on `next` or the protected branch, except under the plans directory's `artifacts/`; a shell command or Codex's `apply_patch` that writes there is not caught. The desktop app refuses a worktree session's Edit and Write of the main checkout, as the block's Plans and trails rule says, but leaves other repositories alone, so a worktree session edits, commits and pushes another checkout, such as the shared skills repository, as that repository's own rules say. The project's Claude Code `SessionStart` hook runs `node .agents/pstack/setup.mjs --hook`. It works on the checkout the hook payload's `cwd` names, even when the hook starts in the main checkout. In a new worktree it copies the main checkout's untracked `.env` and `.env.local` files and installs dependencies, and in the main checkout keeps the suggested-task ledger in step with `refs/pstack/ledger` on origin and fast-forwards `next` when no local edit touches a path the incoming commits change. - **Landing.** After its writing passes, a task lands with `node .agents/pstack/land.mjs --message [--check ]...`. That landing is the owner's standing request to commit and push, so it meets a runtime rule that commits or pushes only when the user asks. The proof its playbook runs through the project's proof skill before the land, with land.mjs's `--check` run, is the verification a runtime rule asks for right before a commit. The lint fix, rebase and regeneration that land.mjs runs after that proof do not reopen it, because land.mjs runs the `--check` command on the commit it pushes. The message file holds one Conventional Commit, `type(scope): subject`, whose type is `feat`, `fix`, `docs`, `refactor`, `test`, `chore` or `perf` and whose subject is short, imperative and has no trailing period. Its body says why in a short paragraph and describes the final behavior. It has a `Beyond the ask:` line that names each change the request did not ask for, a `Picks:` line that names each call the owner would notice with the word that reverses it, and a `Not checked:` line that names what the task's proof did not check. That line's limits count as a narrower proof, as the Plans and trails rule means it, only when the gate the task's playbook sets required what went unchecked. Each of the three says `none` when it has nothing to name. A `fix` body also has an `Introduced-by: ` line for each landed commit that introduced the bug. When the cause is older than the history or outside the repository, such as a dependency or the platform, it says `Introduced-by: none` instead; code that was broken when it landed names the commit that landed it. Other types need no such line. land.mjs refuses a subject in any other form and a body without any one of those three lines. It refuses a message whose subject or body puts the word close, fix or resolve, in any form, right before an issue reference, with whitespace, a colon or both between them. An issue reference is `#`, `/#`, `GH-` or a GitHub issue or PR URL. GitHub closes that issue once the commit reaches the default branch, so the message names it as `#`, which links nothing. It also refuses a `fix` body with no `Introduced-by:` line, with `none` beside another `Introduced-by:` line, or with a line that has no space after its colon. Each other value must be a lowercase sha of 7 to 40 characters that names a commit on the branch it rebases onto. land.mjs commits the worktree, squashes the task into that one commit and rebases it onto `origin/next`. It then runs `pnpm lint:task --allow-ignored` with the changed files appended, each command in the config's `landChecks` and each `--check`, and delivers by this clone's `git config pstack.delivery`. `landChecks` holds the checks every land needs, so none of them depends on the lead naming it. With `push` it pushes `next`, and when that push is rejected because `next` moved, it rebases, runs the lint fix and every `--check` again on the rebased commit, and pushes again, up to three times, counting the companion's moves among them. It exits 75 with the commit local instead once a fourth move comes. Each check runs in a process group of its own, and at 55 minutes into the run land.mjs stops that group and exits 75 with the commit local. A check runner that records each step as it passes keeps the steps that finished, so the rerun runs only the rest. When a rebase changes `.agents/pstack/` or `.agents/pstack.json`, land.mjs goes on in a new process that loads the rebased copy, once per landing, so a landing never finishes on the helpers it started with. A landing takes one core of the machine's core pool the first time it rebuilds or checks, and holds it through every recheck until it exits, except while it waits out a GH006. It never waits for that core, because every session waits on its landing, so the pool only counts its workers against the proofs that queue. GitHub sometimes declines a push with GH006 and no reason, then accepts a push of the same change later, sometimes more than an hour later. land.mjs pushes such a commit again after 1, 2, 4, 8 and 16 minutes. When GitHub declines every try, or the next wait would end more than 55 minutes into the run, land.mjs exits 75 with the commit local. Each exit 75 is a pending external gate, not an unclear failure for the Blocked rule, so the lead runs land.mjs again with the same `--check` options and no `--message`, up to three more times, before it puts the landing under Needs you. It changes no code before such a rerun, because land.mjs commits every change in the worktree, and a check that still fails once both halves are read exits 1 and names a real failure. Each rerun is its own command under the Time budget rule, not a piece of one protocol, because it waits on GitHub or the branch and measures nothing, and the lead does other ready work outside that worktree meanwhile. land.mjs records each commit its checks passed on, a rebased one included, and drops that record whenever it starts the checks again, so a failed check is never skipped. A rerun with the same checks skips them when the commit it would push has the recorded tree, parent and message, unless the environment holds an assignment the config's `freshEnv` lists, such as the variables that make the project's checks ignore cached passes. Each run past the squash appends a line to `pstack-land-runs.jsonl` in the clone's git common directory when it starts and another when it exits. The exit line holds the run's minutes, its wait for cores, its check minutes, its moves, its declines, its exit and the first line of its failure. A started run whose process is gone without an exit line was stopped by a signal, such as the hour's timeout. Its log says nothing of when it stopped, so it counts from its start to the time land.mjs reads the log, up to the hour. `node .agents/pstack/land.mjs --friction` prints the runs of the last day. A run that was stopped, or that exited 75 for any reason but a GH006, loses all its minutes. Any other run, a GH006 exit included, loses only the minutes it waited for cores, because a GH006 is GitHub's outage, which no change to land.mjs fixes. land.mjs adds up the minutes lost since the later of a day ago and the newest row of any `land-friction` task. When a run exits and that sum reaches an hour, land.mjs offers one P3 task in the suggested-task ledger with topic `land-friction`, `via: hook` and no owner, as a project hook offers recurring work, so `/chips all` cards it. It prints one line about the offer, which the lead repeats in its reply. That task replaces the fix that the block's Improve the workflow mid-task rule would make for this friction, because the friction adds up across many landings. So the lead lands its own work and leaves the task to `/chips all`. It offers none while a `land-friction` task is offered or started. Run land.mjs in the background with an hour's timeout, because its checks and waits can take that long. Before its first run with a `--message`, run it in the foreground with the same `--message` and `--dry`, which runs the message, source, PR-section and Defaults refusals and each of the config's `landChecks` on the working tree, names every one that fails, then exits without committing. A check that reads commit messages sees only the commits already made, not the `--message` file. A rerun with no `--message` skips this, because land.mjs runs those refusals again. land.mjs refuses, before any check and again after each rebase, a task that changes an open dated plan whose `## Defaults` table plan-page.mjs would refuse, such as an impact other than big, small or the retired detail that older plans still use. The background command ends with land.mjs itself, never with a command such as `; echo $?`, so its exit status is the one the runtime reports. Unset, outside a checkout that holds the companion's `companion.dir`, it pushes a topic branch to `origin` and opens a PR into `next` with `gh`. When the task changes exactly one dated plan, the one its `Plan:` line names, land.mjs first renders that plan's page with `plan-page.mjs --pr` and opens the PR with that page as its body and each frame it prints attached; otherwise the body is the commit body, and land.mjs refuses a message without a `## Why` and a `## Verification` section, each with text. land.mjs then arms GitHub auto-merge on the PR with a method `next`'s rules allow, so the PR merges once its required checks and reviews pass, as the block's Auto-merge rule asks of every PR an agent opens; when arming fails, it prints why and leaves the merge to a maintainer. When plan-page.mjs refuses the plan, land.mjs stops before the push; fix the plan and run land.mjs again without `--message`. In a fork clone, one with an `upstream` remote for the canonical repository and `origin` for the fork, it fetches and rebases onto `upstream/next`, pushes the topic to the fork and opens the PR on upstream. A clone that cannot push to `origin` and has no `upstream` stops with one line saying to fork the repository and add the canonical one as `upstream`. Each entry of the config's `generated` list names the globs of output that its `command` rebuilds. When every path a rebase of this checkout conflicts on matches an entry's globs, land.mjs takes `origin/next`'s side of those paths, runs each matching command, stages what it wrote and continues the rebase. land.mjs also runs the command of an entry with `"always": true` after every rebase that did not already run it, because a clean rebase can leave the output stale against the merged sources. In a checkout that holds the companion, it runs that command only after the companion's rebase too, so the command reads the sources of both halves. It folds what the command wrote into the task's commit. It folds a file the companion tracks into the task's companion commit instead, inside the entry's globs or not, and starts that commit when the task has none. When that command fails or writes outside its entry's globs in a file the companion does not track, land.mjs stops there too, with no rebase in progress. When a command run for a conflict fails, land.mjs puts the conflicts back and stops with the rebase in progress, and when it changes a file outside its entry's globs, staged or not, land.mjs stops the same way. A companion rebase never rebuilds. Any other rebase conflict stops it with the rebase in progress and the conflicting paths listed, and names the command for each generated path among them; resolve them, `git add` them, run `git rebase --continue`, then run land.mjs again without `--message`. land.mjs also refuses while a revert still has commits to apply, until `GIT_EDITOR=true git revert --continue` finishes it. A failed check stops it with the squashed commit still local; fix the cause and rerun it the same way. When a `git commit`, or a rebase with no conflict, fails while `commit.gpgsign` is on, land.mjs adds the signer's name to the failure. When the error comes from that signer and its key and settings are right, only a person can clear it, so the lead skips the Blocked rule's attempts and leaves signing on. It asks once, under the page's Needs you or in its reply when the run keeps no plan, that the owner unlock the signer and keep it unlocked until the rerun exits, because the squash, each rebase and the companion's stamp sign again. After the owner answers, it runs land.mjs again as the failure says: the same command after a failed squash, which puts the task commits back, and the same `--check` options with no `--message` after any later failure, because the squashed commit stays local. This stop is no sign-in: the lead retrieves no credential, and only the owner can unlock the signer and approve the signature, so a rule that sends sign-ins through a skill first changes nothing here. Each later failure from the signer goes back to the owner once, with its new error. A signer failure after land.mjs printed `Landed` for the public half comes from the companion's `Lands-With:` stamp, and the plan already landed closed, so the lead skips the copy-back and asks once in its reply, and the rerun lands only the companion half. No task ends with work uncommitted in its worktree. With `push`, a task that closes its plan writes that close before its last land.mjs run, so the landing commit carries the record and no commit lands only to record that the plan landed. A task that leaves its plan open, such as one that stops at plan, lands the plan with its open `Status:`. A task that closes its plan first copies the plan and its subject file to the run directory. It writes the `## Close` and any fold into the subject file, and checks a fold with a `--folded` render, which refuses a plan with no Close. Then its close edit, the last edit before land.mjs, ticks each box whose proof exists or is that landing and sets the `Status:` the plan has once that landing is on `next`, such as executed, partial or blocked. Any reflect the run owes runs before that close edit, and so does the reread of the run's asks that the block's Todo list and close rule makes before the final reply, so reflect's rows and lists and each skipped ask's reason land in that commit. An ask that arrives after the close edit is finished after the land or skipped with its reason in the reply. The page counts a landed `Status:` as shipped. So from the close edit until land.mjs exits 0, the lead runs no `page-stop.mjs stage`, not even for a decision-log append, and sends no publish; the close stop after that exit publishes. A companion landing exits 0 only once both pushes succeed. When land.mjs stops short and the landing goes under Needs you, the lead copies the plan and subject file back from the run directory, reapplies any edit it made after that copy, such as reflect's lists, sets `Status: blocked: `, runs `page-stop.mjs stop` and publishes what it prints. The plan is open again, so a decision-log append stages as usual until the lead writes the Close, any fold and the close edit again before the next rerun. A run that stops after a landing it did not plan as its last lands its Close, its final `Status:` and that landing's row as one more commit. The plan and its decision log name no commit of their own landing, because the landing commit's `Plan:` line links the commit to the plan. land.mjs keeps a `Plan:` line the message already has and adds one only when the task changes exactly one dated plan, so a task that closes a plan writes that plan's `Plan:` line in its message. When a plan's work lands through separate land.mjs runs in several repositories, the plan's repository lands last, so its Close names each other landed commit; a companion pair lands in one run, and its `Lands-With:` line links the two commits. When land.mjs opens a PR instead, the plan keeps its open `Status:` until that PR merges. A task with a plan runs its close stop in its worktree after its last land.mjs run, as the Plan pages rule says, so its plan leads its page while that worktree still holds its frames; no session publishes from the main checkout. The lead holds back one close check, such as reading the pushed commit, to send with that stop's publish; a retry after a refusal may go out alone. Never force-push `next`, and never push it except through land.mjs; a `PreToolUse` hook denies an agent's force-push or delete of it or of the protected branch, and any other push to `next` except a dry run, and quotes the command for the owner to run. A project's release skill alone prefixes a push to `next` with `PSTACK_RELEASE=1`, such as a sync from the protected branch. The same hook denies an agent's own `gh pr create` into `next`, or one that names no base, unless `--help` or `-h` is a flag there, because land.mjs opens those PRs; a PR into any other base names that base with `--base`. It also denies any command line that names an `actions/runs//approve` or `actions/runs//pending_deployments` path, with any client or method, because approving a workflow run needs the user's word; the user approves it on the PR or in their own terminal. When it denies a companion command or a push to the branch, it also names each `cd` or `git -C` target it could not resolve, such as a variable, and says it judged the command in the directory before that step. - **Companion repository.** When `.agents/pstack.json` names a `companion`, a second git repository tracks the files `companion.list` names, in the same folder, through the git directory `companion.dir`, and this checkout's git ignores those files. Run its git as `git --git-dir= --work-tree=.`, or through the project's own wrapper. A checkout that holds `companion.dir` lands in push mode, which is what an unset `pstack.delivery` means there. In push mode, a checkout whose config names a companion it lacks refuses to land until the companion is attached. With `pstack.delivery` unset, such a checkout opens a PR, as the Landing rule says. Every land reads the companion's tip before the public one, because a landing pushes its public half first, so no check runs a companion test without its public half. A check can still run a public half without its companion half, when another landing pushes its public half before this land's public read and its companion half after this land's companion read. So when a check fails, land.mjs reads the companion's tip again. When a commit it gained has a `Lands-With:` line that names a commit with its own subject in the public tip the check ran on, that counts as a move, so land.mjs rebases both halves and checks them again, within the same three retries. It skips a companion-only commit, whose `Lands-With:` line names a commit with another subject, and a companion half that has not reached origin yet, so that failure reads like any failed check. When the failing file is a companion file and a public commit the task did not write changed the code it covers, the lead runs land.mjs again before it changes any code, once the companion's `origin/next` holds a commit whose `Lands-With:` line names that public commit, and that rerun clears it. Such a rerun counts toward the same three reruns as an exit 75. When that half has not arrived ten minutes after the failure, the lead asks once under Needs you, naming the public commit whose half is missing, as the Blocked rule does. It rebases the companion onto its `origin/next` and runs every check over both repositories, so a task that changes only public files is still checked against the companion's tests. land.mjs pushes `next` first, then the companion commit with the same message and a `Lands-With: ` line that names the first. Before each push of `next`, land.mjs fetches the companion again, and when its tip moved it rebases both halves and checks them again before it pushes either. That holds for a task that changes only public files too. A task that changes only companion files fetches `next` again before its companion push, and checks both halves again when `next` moved. A companion push refused because its tip moved after the public half landed rebases that half, checks it again and pushes it again. Both count toward the Landing rule's three moves. Any other refused companion push, or a move past those three, exits 75 with that commit local, and a rerun with no `--message` rebases, checks and pushes it. A task that changes only companion files lands one companion commit and leaves `next` alone. git cannot tell a companion file the task deleted from one the work tree lost. So land.mjs refuses while any file the companion tracks is missing from disk, and names `companion.restore`, the command that puts them back, when the config sets it. A companion deletion lands once it is staged, such as with `git --git-dir= --work-tree=. rm --cached -- `. A branch cut before `companion.list` existed on `origin/next` stops and names `companion.migrate`, which moves its work onto both repositories. guard.mjs denies what would delete or overwrite the companion's files: `git clean -x` or `-X`, any `git clean` through `companion.dir`, and a checkout, switch, reset, merge or rebase to a commit without `companion.list`. It judges a `cd` or `git -C` target it cannot resolve, such as a variable, in the directory before that step, so such a command that leads into the checkout passes. setup.mjs keeps the suggested-task ledger on the companion's origin through the main checkout's `companion.dir`, and skips that sync while the main checkout lacks it. - **Other people's PRs.** A repair to a PR whose head is another branch runs in a detached worktree at that head, and the page names the worktree path. The lead commits the repair there and pushes it with `git push origin HEAD:` once the remote head still matches the worktree's base, without asking. It keeps the description of a PR it opened true to the pushed diff. On another person's PR it leaves their description alone and keeps its latest comment about its own commits true instead, as the `plan-page` skill's PR section says; that comment is not a message the Messages rule holds back, because like a PR body it reports the lead's own delivery. When the PR's head branch does not allow maintainer edits, the lead carries the PR instead of stacking a PR on that branch (owner's word, 2026-11-04). It folds the PR's commits and its repair into one commit of its own, with one `Co-authored-by:` line for each author of those commits, and delivers that commit into the PR's base, through land.mjs when the base is `next` and as its own PR into any other base. Once its own PR is open or the commit has landed, the lead closes the author's PR with a comment that links what replaced it. The user's request to finish that PR is the word for that close and that comment. Merging, any other close, other comments, reviews and CI approval need the user's word. - **Review.** land.mjs ends each commit with a `Session:` line naming the agent session that landed it, a `Plan:` line when the task changes exactly one dated plan, and a `Lead:` line with the model and effort that `lead.mjs` reads from the transcript of the agent session running it. land.mjs replaces any `Lead:` line the message has, including the one a rerun takes from its earlier commit. When `lead.mjs` cannot read the session, such as outside an agent session, the line says `unknown` and land.mjs prints why. The owner reviews landed work with `node .agents/pstack/review.mjs`, which lists the commits on `origin/next` not yet reviewed, grouped by session, with a DiffsHub link to each, its plan, its `Beyond the ask:` line, its `Picks:` and `Not checked:` lines when it has them, and whether it shipped fast. When `.agents/pstack.json` sets `reviewPaths`, it lists only the commits with public changes or weakened tests, `--tier internal` or `--tier all` lists the rest, and a commit that changes only skipped paths or adds tests needs no review. In a checkout that holds the companion's `companion.dir`, it also lists the companion's commits, each after the commit its `Lands-With:` line names, and keeps a reviewed mark in each repository. `--net ` prints a session's listed commits as one diff per repository, so a later commit cancels what it undid. `--done ` marks one session's commits reviewed in every tier, and `--mark` marks them all. `--revert ` undoes a session. It reverts every first-parent commit on `next`, and on the companion's `origin/next`, whose `Session:` line names that session, newest first, so it also undoes that session's own plan and decision-log edits. It lands the result through land.mjs, with each `--check` it got, as one `fix(revert)` commit with an `Introduced-by:` line for each reverted commit. It refuses the main checkout, a worktree with uncommitted changes, a worktree with commits `next` lacks, and a session that landed a merge commit. On a conflict it stops with the revert in progress and prints the commands that finish it. With `--stage` it stops once the revert is staged and prints the land.mjs command, so a review the project asks for before such a push, such as a panel on a push that deletes behavior, reads the staged diff first. The hand-back reply's closing link list holds each commit this session landed for the request, a workflow fix or a reflect lesson it landed meanwhile included, as writing.md's Links in replies rule says, and the session title shows 👀 as the Session title rule says. land.mjs also refuses a commit whose subject and body name no source, so the owner can redo the work from its issue, card or plan rather than from its diff. A source is an issue of this repository or of the companion, written as `#`, `/#` or its GitHub URL. The id of a card in the suggested-task ledger, such as `t_1a2b3c4d`, is one too, and so is a `Plan:` line that names a dated plan in the plans directory that exists, written in the message or added for the dated plan the task changes. A bare `#` is not one. land.mjs reads the `sourceless` list from the config on `next`, so a task cannot drop it, and reads the lander's login with `gh api user`. Only the logins on that list land without a source. A task with no issue or card keeps a dated plan, and changing that plan names it, unless its lander's login is on `sourceless`.