PILOT BOOK — PASSAGE PLANS IN DETAIL

File before departure. Sail informed.

Radar tells you about collisions while they happen. Passage plans prevent them: before starting to code, an agent (or human) files the footprint it intends to change and gets a traffic advisory back — before any code is written. A plan is an advisory reservation, never a lock: anyone can still edit anything; they just do it informed.

The lifecycle

                ┌──────────── expires_at (24h TTL) ───────────┐
                ▼                                              │
filed ──edits inside footprint──▶ active ◀──rejoin route──┐    │
  │                                 │                     │    │
  │                          edits outside                │    │
  │                                 ▼                     │    │
  └──edits outside───────────▶ drifted ───────────────────┘    │
                                                               │
  completed  ← session closes / assignment completes /         │
  withdrawn  ← farled_complete_plan / assignment fails         │
  expired    ← TTL lapses ─────────────────────────────────────┘

Live status flows from three independent sources, in trust order: observed edits (reconciled on every change report), lifecycle events (session close; on Cloud, assignments reaching terminal states), and explicit calls — with the TTL as the final backstop. A dead laptop can never reserve water for more than 24 hours.

Filing a plan

At the end of the planning phase, call the MCP tool (or POST /v1/work-plans with the same body):

farled_file_plan {
  "repository_id":  "github.com/acme/app",
  "actor_id":       "my-agent",
  "intended_paths": ["src/checkout/**", "src/lib/currency.ts"],
  "summary":        "Fix checkout summary TypeError + regression test",
  "confidence":     "medium",
  "work_session_id": "<reporter session id, if one is running>"
}

Declare the narrowest footprint you honestly can — over-broad globs generate advisories against you and dilute everyone's traffic picture. Passing work_session_id links the plan to your reporter session, which enables drift reconciliation and automatic completion when the session closes.

The advisory

The response carries a deterministic recommendation — same state, same answer, no model in the loop:

Overlap rules: plan-vs-plan compares glob literal prefixes (src/checkout/** overlaps src/**; src/a/** does not overlap src/b/**) — deliberately erring toward warning. Plan-vs-observed matches your globs against real changed paths. Your own plans never conflict with you.

Drift

On every change report, the server reconciles the session's observed edits against its filed plan:

• edits inside the footprint confirm the plan → active;
• any edit outside marks it drifted and opens an advisory plan_drift signal naming the stray paths;
• rejoining the route resolves the signal and re-confirms the plan.

Drift never blocks anything. It flags scope creep and tells other traffic that this plan's reservation no longer describes reality.

Farled Cloud extras

• Auto-plans at dispatch — assigning a task files a plan from the task's affected_paths automatically. Dispatched work reserves its water with zero agent effort, and the assign response carries the advisory as plan_advisory.
• Terminal assignment states release the plan: completed → completed, failed/cancelled → withdrawn.

Wiring agents to file plans

Add one paragraph to your repo's agent instructions (CLAUDE.md, AGENTS.md, or equivalent):

At the end of your planning phase — before writing any code — file a
passage plan with farled_file_plan declaring the paths you intend to
change, and follow its advisory. When your work ships or you abandon
it, call farled_complete_plan.

That's the entire integration. Plans are optional everywhere: unplanned work is still observed, detected, and advised exactly as before.

API summary