Intents and forks

Projects and the trunk

A project is one repository under Wayglass. wayglass init creates it on the Worker, which creates a trunk repo in Artifacts. The trunk is where approved changes land. Nobody holds a standing write token for it: the Worker mints one for 300 seconds when a decision is approved and the change is about to land, and revokes it when the land finishes.

A project’s jurisdiction (us or eu, depending on the namespaces the Worker is configured with) is chosen at init and fixed from then on, because Artifacts cannot move a repo between namespaces. The jurisdiction tags every change in the project; see Tags.

Intents

An intent is a declared unit of work: a goal, a reason, and the paths the agent expects to touch.

wayglass intent declare --goal "Rate-limit login" \
  --reason "Brute-force attempts in the audit log" \
  --path "web/login.ts" --path "worker/src/limits/**"

All three are required. The reason is not decoration: it is shown to reviewers, stored in the audit log, and written into the git note on the landed commit.

Declaring an intent:

1. records it on the Worker with your agent name as its author,
2. forks the trunk into a new repo named <project>--<intent-id>,
3. mints a write token for that fork only, valid for 900 seconds,
4. checks the declared paths against every other open intent and returns any overlaps,
5. makes it this checkout’s current intent (.wayglass/state/current),
6. fetches the commit the fork starts from and fast-forwards a clean checkout that is behind it, so push is not rejected after other changes landed. A dirty or diverged checkout is left alone with a warning.

The token appears only in --json output (or with --show-token) and is never written to disk. You rarely need it: push asks the Worker for a fresh one each time and the Worker revokes the older ones. Only the agent that declared the intent can get a fresh token. If a Worker cannot mint one, push falls back to WAYGLASS_FORK_TOKEN.

Commands that act on an intent (push, propose, land, session share) pick it in this order: the argument, then WAYGLASS_INTENT, then the checkout’s current intent.

Intent statuses

Status	Meaning
open	Declared; the agent is working
proposed	A change was proposed and has a decision
landed	The approved change is on the trunk
abandoned	Given up

intent list shows open and proposed intents; --all adds the rest. intent show <id> prints one intent with its declared and changed paths, head commit and fork.

Declared and actual paths

Each push reports the files changed since the fork was created (at most 200 per report). The Worker keeps them as the intent’s actual paths and checks overlaps against both declared and actual paths of every other open intent.

propose also lists any changed file outside the declared paths as undeclared_paths and warns. It does not refuse the change, but the overlap checks before that push could not see those files coming. Declare them next time.

Why a fork per intent

Each fork is a separate repo with its own token, so an agent can write only to its own work. A token leaked from one agent’s session cannot touch the trunk or another agent’s fork, and it expires within 15 minutes. This follows Cloudflare’s own guidance for Artifacts: one repo per unit of autonomous work, forked from a trusted baseline, with short-lived per-session tokens.