ADR-0080 Architecture decision record
A nested Workspace takes a Handoff at its cut
The Sandbox is the security boundary (ADR-0028). Inside one Sandbox the Agents have free rein, and jr2 separates only their identities (ADR-0076). So a coder and a reviewer in one Workspace are a quick loop, not an independent review: the coder can change each file, each object of the clone and each Worktree that the reviewer reads. A final review that the author can trust needs a new Agent in a new Sandbox, which sees the commit under review and nothing else of the coder's Sandbox.
A nested workspace() gives the new Sandbox: the body invokes it, and it ends when its parent stops it (ADR-0012). Before this decision, the commit could reach it only through the remote: the coder pushed its branch and the review cut the pushed commit. That publishes work before its review, and it needs a push for each round. This decision carries the commit from the parent Sandbox to the nested one through jr2, with no remote. A design panel wrote five prototypes of the surface. A spike tested a git server between the Sandboxes on real files (Considered options), and a probe tested the bundle range.
Decision
The surface
A Handoff is plain data: the parent cut's
WorktreeReady.{ slot, path, branch, head }, as areadycut of a Worktree gives it (ADR-0075). The parent Machine passes it to the nested Workspace through the door, as each other input. There is nohandoff()Effect, no seal and no extra parent state.@jr2/orchestratorexportshandoff, the schema of a Handoff, for a door's input.The commit enters the nested Workspace only at its cut.
worktree()gets a third arm:ts{ path: "/work/app/final", handoff, branch?: "fix/123" } // a branch Worktree at the Handoff's commitThe child's Workspace clones the real Repo, as each Workspace does, and its attach knows nothing of the Handoff. The cut makes a branch Worktree at
handoff.head. The branch isbranch ?? handoff.branch, so by default it has the parent's name. It tracksorigin/<branch>when the clone holds that branch.foundis"handoff". A re-cut of the path with the same Handoff isheld, and a re-cut with another Handoff isrefused. Each cut at a Handoff, aheldone too, first carries the Handoff's files from the parent Sandbox, so it needs the source: a carry that isrefusedorunknownsettles the cut with that outcome before the child's Harness answers. The child's Harness decidesheldandrefusedfrom its own record of the path, as for each re-cut (ADR-0075): two rounds' nested Workspaces can share one Sandbox name (ADR-0064), so the run's ledger cannot tell their cuts apart.The slot's
expectapplies to the child's branch, as at a branch cut (ADR-0075). The Handoff's head sets what the branch holds, andexpectsays whether the name can exist. A push in the child publishes to the child's branch, and a Chart or a pick can name that branch throughbranch. Withexpect: "new", the cut refuses a name that the remote has, so such a name cannot reach an existing branch. The door's rules for a lent cut (ADR-0075, "A Chart") thus hold for a cut at a Handoff too.Each round leaves the state that invoked the last one. A parent that leaves the state stops the nested Workspace, and the host deletes its Sandbox before the next round places one of the same name (ADR-0012, ADR-0064). A parent that invokes the nested Workspace again from the same state, in one transition (for example
reenter: true), stops the old one and starts the new one in one step. The new one then takes over the old Sandbox, as a re-invoke after a caught defect does in the step that catches it. Its cut with a new Handoff isrefused, and its cut with the same Handoff isheld: it gets the last round's Worktree, with the commits of the last reviewer. Such a round is not independent. So a Machine goes through another state between two rounds, for example the parent's coding state.jr2 trusts no field of a Handoff. A Handoff comes through a door, and a door's input can come from an Agent's pick or a Chart. So the cut finds the whole Handoff in the run's ledger, and refuses it when one fact does not agree:
- the run is the child's own run. A dispatched run has its own ledger and no enclosing Workspace (ADR-0071), so a Handoff never crosses a dispatch;
- the Workspace whose cut made the row encloses the child. The child's own Workspace, a sibling and a Workspace of another run are refused;
- the source slot's Repo is the child slot's Repo;
- a settled
readycut ofpathin that Workspace hasheadas its head. An earlierreadycut of the path is also good, so a Machine can hand off a commit on which the coder has since built: the author pins the publish to the reviewed commit (below); branchis that row's branch. Without this check a Chart could forgemain, and a signed push in the child would publish tomain. The row's branch is what the Orchestrator sent to the parent's cut, never the cut's answer, which a process of the parent Agents' domain can write (ADR-0067);- the child's branch is a name. A detached Handoff (
branch: null) needsbranchin the cut's input; - the child's clone has no local branch of that name at another commit. The child's Harness checks this one at the cut, as it checks each name of a cut (ADR-0075).
Each of these is the Agent's word, so each settles as
refused, with a reason, and changes nothing. A bad Handoff never goes toonError(ADR-0067), and the Machine routes it, for example tofail()(ADR-0073). These checks are for a Handoff of the right shape. The shape is checked where an Agent's value enters. The Menu checks a pick against its schema, so a pick's Handoff of the wrong shape never reaches the nested door. A Chart is different: the door checks only the literal parts of a Chart'sinputat its admission. It refuses a literal Handoff, so a Chart gives a Handoff only as a reference, such as{ "$ref": "context.h" }, which resolves at the invoke. A wrong shape there is that invoke's error, as for each input that a Chart lends (ADR-0070). A value of the wrong shape that a Machine's own mapper gives settles the cutrefusedwhen it starts.What the ledger check holds, and what it leaves to the Machine. The check holds that the commit is the head of a
readycut in an enclosing Workspace of the run, on that cut's branch. Which of those commits the child takes is the Machine's choice: a Handoff that a pick carries lets the Agent choose among them. Thebranchof the cut's input is not a ledger fact. It names the child's branch, as thebranchof a branch arm does (ADR-0075), so a Machine that takes it from a pick or a Chart lets the Agent name the branch that a push in the child publishes to. The slot'sexpectlimits that name, as for a branch arm: withexpect: "new", it cannot be a branch that exists. A slot with noexpectlimits nothing, and a Chart cannot use such a slot.The cut is the only check.
jr2 updoes not look at a door that takes a Handoff, and the Orchestrator does not look a Handoff up when the parent invokes the nested Workspace. A forged Handoff costs one Sandbox, and the cut refuses it.One nested Workspace for each final round. Each round invokes a new nested Workspace with the newest Handoff. What the final reviewer must know of earlier rounds comes in through the door as data, for example the notes of each round. The parent and the child end together: a parent that leaves the nested state stops the child, and the host deletes the child's Sandbox (ADR-0012).
The author chooses where to publish.
pushstays available in every Workspace, the parent's and the child's.push({ pin: true })with{ worktree, sha: handoff.head }publishes exactly the reviewed commit, in either Workspace. jr2 adds no rule for a Worktree that a Handoff made.
What the final reviewer sees
The child's Agents must not need to know jr2. In the child, git is ordinary:
/work/<slot>/defaultis the Sandbox's own clone of the real Repo.originis the real remote, which a fetch reaches through the node cache (ADR-0053).git remote -vshows onlyorigin.- The Worktree holds an ordinary local branch, at exactly
head, with the parent's name. Whenorigin/<branch>exists,git statusshows ahead and behind. git logshows the parent Agents' commits, with their authors and messages.- jr2 leaves no other remote, no
refs/jr2/*ref and noFETCH_HEAD. - Only
headand its ancestors enter the child's clone, and only the Git LFS objects that their pointers name enter its LFS store. The parent's other branches, its untracked and ignored files, its config and its caches stay in the parent Sandbox.
The transport: a git bundle
The parent Sandbox writes a bundle of the handed-off range:
headand the ancestors that the parent clone's remote-tracking refs oforigindo not hold. git writes no bundle for a bare sha, so the step namesheadby a ref in a git folder of its own whose alternates are the clone's objects, as the cut does (ADR-0075), and bundles that ref--notthe clone's remote-tracking refs oforigin(refs/remotes/origin/*). The child's clone has onlyorigin, so a commit that the parent fetched from another remote travels in the bundle, and does not become a prerequisite that the child lacks. The source Harness writes it as the cut does: through the spawner, in the Sandbox's Landlock domain (ADR-0076), with jr2's cleared env, the cut's pinned config (no hooks, no fsmonitor,core.commitGraph=false,core.multiPackIndex=false,core.alternateRefsCommand=true, and the rest of the cut's set), a deadline, and a kill of the process group at the deadline. In the domain, the step reads only what an Agent of the parent can read itself. The deadline is necessary: in the spike, a FIFO that an Agent planted in the clone held git for ever. The bundle is the parent domain's file, so jr2 trusts nothing in it: the child's cut takes from it only what the steps below let through.The step also reads the files, as a stream. In the same step, under the same deadline and kill, a process of the domain reads the bundle and each Git LFS object (below) and writes them to its stdout. The spawner sends that output to the source Harness as output frames, and the Harness pauses and resumes it as it sends on. The process opens only a regular file, so it does not read a FIFO, a device or a link to one. The Harness does not use the spawner's whole-file read for a Handoff, and it counts the bytes as they come (the bound, below). A read that an Agent's file holds ends at the deadline, as git does. The deadline is 300 s of the step's own time, from its start to its last byte. The clock stops while the Harness holds the step paused for a reader that is behind: a slow carry is not a fault of the parent's files, so it never makes the cut
refused.The answer is a stream of frames. Each frame is one JSON line: a part's header (the bundle first, then each Git LFS object by its oid) with its size,
dataframes that hold the part's bytes, and one terminal frame: the end, "nothing to carry",refusedwith a reason, orunknown. The source Harness writes each frame in its own words from what the step wrote, and it ends the streamrefusedat the first header that is out of this form. An Agent can trace the step and change its output, so the Harness reads that output as the domain's data. The step's chunks are therefore the Agents' to choose: the Harness puts a part's bytes indataframes of up to 64 KiB, at the end of the part, or after one second, never one frame for each chunk. A terminal frame can come between any two frames, so a refusal in the middle of a part still reaches the reader, and the parts before it are void.An empty range carries nothing. When a remote-tracking ref of
originin the parent clone already reacheshead, git writes no bundle (Refusing to create empty bundle). This occurs when the parent pushed the branch before the final review, or when the branch has no commit of its own. The bundle step finds this before it writes a bundle, and the source Harness answers "nothing to carry": no bundle and no Git LFS objects. The child's cut then takesheadfrom its own clone after its fetch (ADR-0075), when the clone holds it, and the node cache gives the Git LFS objects. An Agent can set a remote-tracking ref oforiginin the parent clone tohead, so the child's clone can lackhead. The cut is thenrefused, and the reason names the commit.The Orchestrator carries the files, and no route faces a Sandbox. It already talks to every Harness (ADR-0058). When it runs the child's cut Effect, the Orchestrator checks the Handoff of that Effect's input against the ledger and records the source on that cut's intent row. Then it uses two legs of the Harness wire, each behind the Harness bearer:
POST /handoffon the source Harness, with the path and the head of the ledger row. The source Harness runs the bundle step and answers with one stream: the bundle, then the Git LFS objects.PUT /handoffs/<id>on the child's Harness, with the Effect's id, before the Orchestrator starts the cut's exec (POST /exec/<id>, ADR-0067). The Orchestrator streams the source's answer into it. The child's Harness writes the files to a folder of that cut through a process that the spawner starts in the child's domain and that stdin frames feed, so neither Harness holds the whole stream: the land process says each byte count that it wrote, and the Harness sends only a window (4 MiB) ahead of it. The folder is/work/.jr2/handoffs/<id>, in jr2's folder of/work(ADR-0075), on the Sandbox's volume, because the Effect's id names no Repo Slot. The land process writes into<id>.partand renames it to<id>at the end frame, so the cut finds all the files or none. The cut reads the folder of its own Effect id, and removes it when it settles, also when it isrefused. The child's Harness removes it too, in the domain, when the exec of that id settles with any outcome: a cut that its timeout kills does not reach its own cleanup, and an exec that a kill ended before its start never ran. The take's own git folder inTMPDIRof a killed cut stays until the next cut of that clone removes it (ADR-0075).
The two legs are one pipe: the Orchestrator reads a chunk of the source only when the child's leg took the last one, so it holds no whole part, and a slow child holds the source's step paused. The Orchestrator checks the source's stream as it reads it: each header is a JSON line of a bounded length, in the order of the form, the bytes of each part are counted against its header, and a part has at most 16
dataframes and one more for each KiB of its size. It writes each frame of the child's body itself, from the values that passed these checks, so the child gets only the parts and their end. A body that ends before its end frame is a carry that the Orchestrator ended, and the child keeps nothing of it: the land process removes<id>.partwhen it finds the fault itself, and when the child's Harness kills it (the body broke), the Harness waits for its exit and then removes<id>.partand<id>in the domain. The child answers{ landed: true }when it holds the files. A second body for one Effect id replaces the files of the first. The lands of one id run one at a time, so that a removal never hits the files of a newer body, and a newer body stops the land before it: the Orchestrator sends it only after it gave up the first. A carry that endsrefusedorunknowncan end after the child renamed the files into place, so the Orchestrator then sends a kill of the cut's Effect id to the child's Harness, best effort. The kill settles that id in the child, which removes its landed files as for every exec that settles. That removal goes in the id's lane too: it stops a land of the id that still runs and waits for its end, so that land cannot rename its part into place after the removal looked.The Orchestrator asks the Harness of the source Workspace where it runs now, and only while that Workspace still encloses the child: a Workspace that no longer runs gives no Handoff, and the cut is then
unknown.The child makes no request for a Handoff, so no credential of the child's domain reaches one: the Orchestrator sends a bundle only for the source that the cut's own intent row records, never for a cut that the Machine did not ask for. Only the child's Harness knows that a re-cut is
held, so the Orchestrator carries the files for each cut at a Handoff, and aheldre-cut does not read them. So aheldre-cut also settlesrefusedorunknownwhen its carry does: the parent's Agents removed the commit, or the parent's Harness does not answer. A cut that goes again after the child's Harness restarted (ADR-0067) carries again first, and that carry's outcome settles it too, although the child's record holds the first answer.One bound covers the bundle and its Git LFS objects together, and a second bound covers the number of objects. A Handoff is the parent Agents' files, and the Orchestrator serves each run of the Instance, so an Agent's file must not steer how much it carries or holds. The byte bound is 1 GiB. The object bound is 100 000 Git LFS objects, and each object has at least one byte: git-lfs stores no empty file, and an object of no bytes would cost nothing against the byte bound. The Orchestrator and the source Harness each keep one oid for each object of a carry (each object comes once), so without the object bound a stream of headers of no bytes held about 250 MiB for each million objects, and could stop the Orchestrator (1 GiB) for every run. The bundle step adds the sizes and counts the objects before it writes the first part, and refuses a Handoff past either bound; a pointer of no bytes names no object to carry. The source Harness and the Orchestrator each stop the stream at either bound, and the cut is then
refused, with the bound in the reason. A header of an object of no bytes is out of the form.The child's cut takes only
head's closure, and git checks each object. git before about 2.46 runs no fsck on a fetch from a bundle, whatevertransfer.fsckObjectssays, and a fetch from a bundle stores each object of the bundle's pack. So the cut does not fetch from the bundle. It refuses a bundle unless it has exactly one ref, athead. It unbundles into a git folder that it makes in the cut's own folder, whose alternates are the child clone's objects, so that git checks the bundle's prerequisites against the clone. It sets a ref atheadthere, and the clone fetches that ref overfile://withtransfer.fsckObjects=trueandfetch.fsckObjects=true(the second wins over the first, and over a value in the clone's config). For a fetch overfile://, git clears the config that the cut gives by env in theupload-packthat it starts, so the cut writescore.commitGraph=falseandcore.multiPackIndex=falseinto its git folder's own config: thatupload-packreads the clone's objects through the alternates, and reads no commit-graph and no multi-pack-index that an Agent wrote in the clone. The fetch writes no ref and noFETCH_HEAD. So onlyhead's closure enters the clone, and git checks each of its objects with fsck, also on git before 2.46 (a probe on git 2.39.5 refused a commit with a bad date). Then the cut makes the branch athead.The cut records its source. The child cut's intent row keeps the resolved source (the run, the Workspace and the ledger row), so a restored run asks the same source, and the cut stays idempotent.
Two kinds of transport error. An error that the parent's files or the parent's clone cause is
refused, with the reason, because a cut again meets the same files:- the source Harness answers that the commit, or a prerequisite of the bundle, is not there;
- the bundle step passes its deadline (for example, at a FIFO that an Agent planted);
- the bundle file is not a regular file;
- the stream passes the byte bound or the object bound;
- the bundle has a ref that is not at
head, or more than one ref, or is not a bundle, or fsck refuses an object; - the child's clone does not hold a prerequisite of the bundle (for example, the remote was force-pushed or the branch was deleted after the parent fetched, or the cut's fetch got no answer). The reason names the missing commit, and what the fetch said when it got no answer;
- the range is empty, and the child's clone does not hold
headafter its fetch. The reason names the commit.
A Git LFS object that is not a regular file in the parent clone, or whose size is not its pointer's, is left out of the stream, and the child asks the node cache for it, as for each object that the Handoff does not carry. A remote-tracking ref of
originin the parent clone that names no commit is left out of the range's negatives.When the source Harness does not answer, the cut is
unknown, and the Machine can cut again. A connection that never opened, to either Harness, is tried again a few times first (for about 4 s), because no byte of the carry left. The Orchestrator ends a carry after 360 s with no byte from the source: longer than the bundle step's deadline, so a step that the parent's files hold ends asrefusedand never asunknown. A carry that a slow child stalls for that long also endsunknown, which ends the source's stream and so kills the step. A carry also has a time of its own: the byte bound at 1 MiB/s, and one idle wait (about 23 minutes). A child that takes a byte now and then resets the idle wait, and the bundle step's deadline stops while the step is paused, so without this time such a child would hold the cut, the parent's step and its bundle file without end. The child's Harness has a bound of its own for aPUT /handoffs/<id>, because it sends nothing on that request until it answers, so no packet finds an Orchestrator that is gone, and the Orchestrator's times bound a carry only while it runs. node's request time (300 s) is too short for a carry, so the Harness spares that one route from it, and every other route keeps it. The land has a time of its own instead: the carry's time and 60 s. Past it, the land process is killed and its files are removed, as for a body that breaks. The cut'stimeoutdoes not cover the carry: it starts with the cut's exec, after the carry. A carry past its time isunknown, and both legs end. An HTTP error of either Harness, a source stream that ends before its last frame, breaks, or is out of its form, and a child that does not answer{ landed: true }areunknowntoo. A reason names the Harness whose leg failed: a break of the source's stream names the source, not the child. Any other fault of the carry isunknownas well, never the invoke's error: the parent's files can cause it.The carry only reads the source and replaces the child's files under one Effect id, so it can run again. When the child's Harness restarts and the Orchestrator sends the cut's start again, it carries the files again first, so a restart is never a
refusedfor a commit that the clone does not hold. The landed files are on the Sandbox's volume, so a restart of the Harness container between the land and the start also keeps them. A restored run carries them again under the same id, from the source that the intent row keeps. When the child's Harness holds the exec of that id already (the Orchestrator restarted after the start reached it, or a kill came first), it lands nothing and answers 409{ started: true }: the start then runs nothing, so no later settle of the id would remove the files, and a cut that runs would see its files replaced. The carry is thenstarted, and the cut goes on to its start and reads the exec.No server. No process serves git between Sandboxes, no alternates point at another Sandbox, and no git protocol version is chosen. On the parent side, the only git folder that jr2 makes is the bundle step's, which holds one ref and reads the clone's objects through its alternates. The child's
file://fetch runs in the child, between two folders of its own cut. The bundle and the Git LFS objects that its commits name (below) are the only files that leave the parent Sandbox.
Large files
- Git LFS objects travel with the Handoff. The bundle step also collects each Git LFS object that a bundled commit points to and that the parent clone holds. A pointer is a blob of the range (a blob that the remote-tracking refs of
origindo not reach) that has the form of a Git LFS pointer: the step reads no.gitattributes, which an Agent writes. The object is the file of its oid in the clone's LFS store. The Orchestrator carries them with the bundle. - The child lands an object only when a pointer names it and its bytes match. A pointer in a commit of the handed-off range (the commits that the fetch brought into the clone) must name the object's oid, and the object's sha256 must be its oid. The cut leaves out each other object. git-lfs checks only the size of an object in the store, so without the sha256 check an object of the same size with other bytes checks out with exit 0. Then the cut's usual ask of the node cache gets the objects that the Handoff did not carry (ADR-0075). A push from the child uploads from its own LFS store, as each push does.
- The surface does not change.
An Agent's git and a bare repository
A commit can hold a bare repository in its tree. In the spike, git status inside the folder of a bare repository that a commit holds ran that repository's core.fsmonitor. So jr2 sets safe.bareRepository=explicit for each Agent process, through GIT_CONFIG_COUNT, GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> in the domain's env (ADR-0076). With it, a push, a clone or a fetch by path and --git-dir work, and git -C bare.git is refused with a message that names the setting. Other commands in such a folder fail with no word of the setting: git config says not in a git directory or reads no repository config. So a project's test suite or tool that runs git in a bare repository by its folder fails in a jr2 Sandbox, and the final reviewer that runs the tests sees it fail. The fix is --git-dir or GIT_DIR in the tool, or GIT_CONFIG_PARAMETERS="'safe.bareRepository'='all'" in the image or harness.env, which turns the setting off for the Sandbox. jr2 up warns about it in the ENV of an image that it builds. The git of the cut, the sync and the bundle step runs with jr2's cleared env and its own config. The attach runs its git with the domain's env, and so with this entry: a clone and an upload-pack by path work under it, and the attach reads the node cache, a bare repository, by --git-dir. jr2's entry goes after the image's own entries, so an image that sets GIT_CONFIG_COUNT keeps its entries, and the Harness needs to read no image. git reads GIT_CONFIG_PARAMETERS after the counted entries, so a safe.bareRepository there is used in place of jr2's. jr2 up warns, and does not refuse, when the ENV of a Sandbox Image that it builds sets GIT_CONFIG_COUNT, or names safe.bareRepository in GIT_CONFIG_PARAMETERS (ADR-0076). The image's git must be 2.38 or later to read the setting; an older git ignores it, and the Harness logs one warning at start. git before 2.45 also refuses git that runs inside a .git folder or .git/worktrees/<name>, so a hook or a tool that runs git there needs git 2.45 or --git-dir. The git of the default image (node:24-slim) is 2.39.
Example
The parent's quick loop ends at a reviewer's pass. Then each round of the final review is a new nested Workspace, and the parent publishes the commit that the last round approved.
const finalInput = z.object({ handoff, earlier: z.array(z.string()) });
type FinalInput = Workspaced<z.infer<typeof finalInput>, "app">;
const finalTree = (c: FinalInput) => `${c.workspace.repos.app}/final` as const;
// In the nested Workspace's body:
cutting: {
invoke: {
src: "cut",
input: ({ context }) => ({ path: finalTree(context), handoff: context.handoff }),
onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
},
},
// In the parent's body. `handoff` is the `ready` output of a cut of the coder's Worktree.
finalReview: {
invoke: {
src: "finalReview", // workspace(finalBody, { input: finalInput, repos: { app } })
input: ({ context }) => ({ handoff: context.handoff!, earlier: context.earlier }),
onDone: [
{ guard: ({ event }) => event.output.outcome === "pass", target: "publishing" },
{ target: "coding", actions: assign({ earlier: ({ context, event }) => [...context.earlier, event.output.notes] }) },
],
},
},
publishing: {
invoke: { src: "publish", input: ({ context }) => ({ worktree: coderTree(context), sha: context.handoff!.head }) },
},Considered options
- Serve the commit with git's smart HTTP. The child's cut fetched through its Custodian and the Orchestrator from a throwaway bare repository in the source Harness, which
git upload-packserved, at protocol v0. Rejected. The spike showed that protocol v2'supload-packserved any object of the store: another branch, a stash, a dangling blob. So the server had to hold to v0 and to a store of onlyhead's objects. The serving step also followed anobjects/info/alternatesthat an Agent wrote, with the server's access, and carried a file that the Agent could not read. A server is a protocol to police for the life of the Sandbox. A bundle is one file, which the domain writes, and from which the child takes onlyhead's closure through fsck. - The child's cut fetches straight from the bundle, with
transfer.fsckObjects=true. Rejected. git before about 2.46 runs no fsck on a fetch from a bundle: on git 2.39.5 (the@kindSandbox image) and 2.43, a commit with a bad date landed with exit 0, and the same fetch overfile://was refused. The fetch also stores each object of the bundle's pack, so a bundle with a second ref put that ref's objects in the child's clone, with no ref to them. A floor of git 2.46 in each Sandbox Image closes only the first of these, and it binds each image that an author brings. - A
handoff()Effect that seals the Handoff in the parent. Rejected. The ledger already holds each fact of a Handoff, so a seal gives no property that the lookup does not give. It adds an Effect, a state in each parent and a key to keep. - The Handoff at the child's Repo Binding, so that the child's Repo Slot is bound to the Handoff in place of a remote. Rejected. A bad Handoff then fails the attach, which a Machine cannot route as a
refusedoutcome, and an Agent's word must not reachonError(ADR-0067). The child'soriginwould also not be the real remote. At the cut, a bad Handoff is an ordinaryrefused. - One long-lived nested reviewer for all the rounds, which gets each new Handoff as an event. Rejected for now. It changes the one-way composition of ADR-0011 into a kept, two-way event channel. A final review is meant to be independent, and a long-lived Sandbox keeps the caches and the conversation of round 1. A re-cut with another Handoff is
refusedtoday, so this can come later with no break. - A push guard: a push without
pinfrom a Worktree that a Handoff made isrejectedwhen the branch moved. Rejected. The author chooses where to publish, andpush({ pin: true })with the reviewedshaalready publishes exactly the reviewed commit. A rule for one kind of Worktree is one more rule to learn, for a case that the author closes with one option. - An early check:
jr2 uprefuses a registered root whose door takes a Handoff, and the Orchestrator looks the Handoff up when the parent invokes the nested Workspace, before it places the pod. Rejected. The cut must check in any case. A check at the invoke can fail on an Agent's word, so it must be a Failure and not a defect in the placement (ADR-0073, ADR-0067): a second refusal path to save one Sandbox. - A Sandbox name that is unique for each invoke, so that a second round cannot race the delete of the first round's pod. Rejected. A parent that invokes the same Machine again from the same state must give it the same name, so that a restored or re-invoked Workspace takes over its Sandbox (ADR-0064, ADR-0073). The name comes from the actor path (ADR-0012), which tells the Workspaces of two Pool workers apart. Two rounds share one name. A round that the parent invokes after it left the invoking state waits for the delete of the old one. A round that the parent invokes again from the same state takes over the old Sandbox, so a Machine leaves the state between two rounds (Decision).
- The coder pushes its branch, and a review Workspace cuts the pushed commit. This needs no kit change. Rejected as the way to the final review: it publishes work before its review, it needs a push and a fetch of the remote for each round, and the Machine cannot keep the reviewed commit off the remote.
- Trust git-lfs to check an object that the Handoff carries. Rejected: git-lfs checks only the size. A reviewer showed that a planted object of the same size checks out with exit 0.
Consequences
- An independent final review is one nested
workspace()and one cut arm. The quick loop in one Workspace does not change. - Each round costs a new Sandbox: a placement, a clone, an install of the dependencies, and a new conversation. A measured nested Sandbox was Ready about 3 s after its create.
- The commit messages and the files of the commit are the parent Agents' words, and they reach the final reviewer unchanged. They can try to persuade it. That is the review's job to see; the final reviewer runs the code in its own Sandbox, and the author decides what that Sandbox holds.
- The
@kindtier runs the loop in real pods (features/handoff.feature): two rounds that the parent publishes with the pin while the coder's later commit stays off the remote, a nested Workspace that publishes, a forged head and a forged branch, and a large file that only the parent's clone holds. - A Handoff goes only down. A commit that the final reviewer makes stays in the child, and it is published only when the child pushes it.
- Each slot needs its own Handoff, door field and cut. A Handoff given to the cut of a slot that holds another Repo is
refusedat the cut. - Later, without a break: a per-run Repo Slot that takes only its remote and its base from a Handoff (the commit still enters at the cut), a review Machine in
@jr2/machines, and a long-lived nested reviewer.