Skip to content
jahalaPublic

About

pleach — deterministic conductor for DAGs of verified agent work (tend2 plans it, pleach runs it, umbel drives the workers)

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

pleach

CI License: MIT

A deterministic conductor for DAGs of verified agent work. pleach takes a plan, isolates each node in a detached git worktree merged from its dependencies' verified branches, enforces gates, and writes a local node/<id> branch only for work that passed them. It never pushes — the conductor does — but it says, at run end and after a landing, what exists only on this machine.

Agents produce; code decides. Close, verify, quarantine and retry are deterministic code paths. Agent output is parsed evidence, never interpreted.

Pleaching: the craft of training and interweaving living branches into a single structure.

Two products have been built this way, plan to landed code, with no human reviewing diffs: a six-feature PDF unifier, and the stem of plotplot, a released Rust binary in another repository and another language (its plans are public).

Install

A Bun CLI. Needs git >= 2.38. Run it without cloning:

bunx github:jahala/pleach validate plan.json
bunx github:jahala/pleach run plan.json

bunx runs pleach from bun's cache, so it does not make pleach/* imports resolve in your repo. To import the bundled adapters from a pleach.config.ts, install pleach as a dependency:

bun add -d github:jahala/pleach

The default runner also wants tmux and an umbel binary. --runner direct-cli needs neither, only the claude and codex CLIs.

Redacting secrets from agent and gate output needs a plotplot binary (cargo install --locked --git https://github.com/jahala/plotplot). pleach run / land / audit refuse to start without it; pass --no-redact to opt out explicitly — that choice is recorded on the run's run-start line and in every receipt. See docs/guarantees.md.

The gate ladder

Every node goes through the same fixed sequence. The agent touches only one step of it.

isolate → setup → work → conflict-marker scan → stage → smoke → cross-provider audit → commit

A conflict marker fails closed. The smoke command is the node's own declared test. The audit runs the check command in a fresh session from a different model vendor, so no model grades its own work. Only a node that clears all of it publishes a branch.

Usage

pleach run <plan.json>          Execute a plan (--land to land a fully-verified close; --only a,b
                                to run a named subset and its unbuilt dependencies)
pleach land <plan.json>         Merge a verified plan's sinks onto the checked-out branch
pleach audit <plan.json> <node> Re-run only the audit on a quarantined node; a further re-audit
                                 needs a changed accept.audit.command
pleach audit-wrap -- <command>  Wrap any check so it prints the block an audit command must print
pleach stop <plan.json>         Drain a running plan (--now aborts in-flight nodes)
pleach status <plan.json>       Print the latest run's state (JSON on stdout, table on stderr)
pleach wait <plan.json>         Block until the run ends; --node / --timeout shape it
pleach validate <plan.json>     Parse and validate; print the topo order
pleach schema                   Emit the plan contract as JSON Schema
pleach receipt <node>           Verify a settled node's close receipt
pleach clean                    Sweep a killed run's stale locks, orphaned worktrees and the
                                worker sessions its journal names (--dry-run lists without changing)

pleach --help carries every flag, default and exit code.

pleach run --only a,b runs just the named nodes and the unbuilt dependencies they need — nothing else is scheduled, closed dependencies are used as bases, and an id not in the plan refuses with exit 2. With --land the named ids become the landing's sinks. A node the subset left out reads out-of-scope in pleach status/wait (never skipped, never failed).

A plan may be edited while it runs. Before each launch, pleach run re-reads the plan file and applies the change to nodes that have not started — a conductor can recast an auditor or correct a prompt without aborting the run, and goal / maxConcurrency take the new values. A node that has already started keeps what it started with, and a change to the graph (node ids, needs, source) or a plan that no longer validates is refused: the run carries on with the plan in force.

What happens when things go wrong

Work is never silently lost and a verdict is never invented. A node that cannot finish keeps its tree on quarantine/<id> and writes a receipt.

Situation What pleach does
The auditor's relay is unreadable, or it dies Quarantines with gates green; pleach audit re-adjudicates without rebuilding
A provider is down --fallback-provider re-casts on another vendor; an outage is never paid twice
The provider needs a person to sign in Spawn exit 126 settles blocked, never retried on that provider; sign in once outside the conductor, then re-run
The network or the provider errors Waits and retries inside the same attempt; a short outage costs no attempts
A worker fails to spawn Waits and re-spawns inside the same attempt; a spawn error before any work costs no attempts
A worker's background job is still writing Gates wait until the tree is still; one that never settles fails the attempt, naming the paths
The plan holds a bare shell operator Refused at validate, before a worker costs anything
A gate command cannot start Node settles once; no attempt spent, no worker re-prompted
You halt the run stop drains, --now aborts; both keep the tree and write receipts
A worker goes quiet --idle-ms ends the wait; settles blocked, tree kept
A worker is stuck It writes BLOCKED.md and is not asked again
A git hook refuses the commit Gate verdict like any other; tree kept on a snapshot no hook can refuse
A git hook changes the commit The node fails; nothing a gate did not judge is published
A landing conflicts Every conflicting sink is pinned at refs/pleach/rebuild/<id> and rebuilt on the landed stack by the next pleach run — as one group, in plan order — never merged by hand
A seam throws mid-node Settles under seam:<lane>; the verdict names the next step
The journal loses lines Reported as journal-gap at the next run; each run keeps its own copy
A worker or gate prints a secret Redacted ([REDACTED]) before it reaches the journal, the log or a receipt
A verified branch or landing is on no remote run-end and landed name what is local-only; stderr warns to push
A killed run leaves sessions behind pleach clean kills the sessions its journal names, sweeps their worktrees, and clears stale locks; --dry-run lists them without changing

Full detail, one section each: docs/guarantees.md.

Adapters

pleach needs a runner (drives an agent per node) and a ledger (tracks which nodes are verified). With no config it uses umbelRunner + gitLedger, and gitLedger reads node/* branches from the repo, so a standalone run needs nothing external.

To choose explicitly, drop a pleach.config.ts at the repo root:

import { umbelRunner } from 'pleach/adapters/umbel';
import { gitLedger } from 'pleach/adapters/git';
import type { PleachConfig } from 'pleach/config';

export default {
  runner: umbelRunner({ bin: 'umbel', permissionMode: 'bypassPermissions' }),
  ledger: gitLedger({ repo: '.' }),
} satisfies PleachConfig;

Swap either line for your own implementation of RunnerSeam or LedgerSeam without touching the plan. Five adapters ship; --tend-module opts into the tend ledger instead. Contracts and a guide for writing your own: docs/adapters.md.

Writing a plan

The repo ships a Claude Code skill, pleach-plan: give it a goal and a repo and it decomposes the work into a gated DAG, then proves the result with pleach validate. Agents without it still have pleach schema and pleach --help.

Reading on

ENGINEERING.md is the binding doctrine. docs/contract/plan-schema.md is the plan contract, and this repo is its home. CONTRIBUTING.md covers the runtime substrate and how to run the tests.

pleach's own development is tracked in its verified garden: docs/tend2/pleach.tend2.html. The pages are self-contained; open any of them in a browser.

Support

"Buy Me A Coffee"

MIT licensed (LICENSE). A bed in the plotplot garden, alongside tilth (code intelligence), weeder (the judge of the diff), umbel (fans out agent CLIs in tmux), pollen (agent-to-agent messaging) and copeca (cost per correct answer). tend2 and petals are built but not public yet.

About

pleach — deterministic conductor for DAGs of verified agent work (tend2 plans it, pleach runs it, umbel drives the workers)

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages