@uchibeke/gallivant 0.2.1 → 0.3.0

package/docs/tasks.md

@@ -13,11 +13,11 @@ gallivant task "Explain the existing backup and restore commands in docs/operati
 ```
 
 Inspect the returned draft or answer its questions, then use its printed `Next`
-action to authorize implementation. Add `--run` to the original request when you
-want implementation to start automatically once the brief is ready. This is
-execution authorization, including after clarification answers. It is not a
-merge, deployment or release approval. To open the dashboard after dispatch,
-run `gallivant start` with no PRD path.
+action to approve that visible revision with `task start --revision <revision>
+--run`. Preparation always returns a draft or questions, including when the
+original command contains `--run`; it cannot pre-authorize an unseen draft.
+Approval grants implementation under the selected delivery profile. To open the
+dashboard after dispatch, run `gallivant start` with no PRD path.
 
 ## Supported preparation harnesses
 
@@ -40,183 +40,39 @@ open a pull request without execution authorization.
 
 ## Writing requests and publication boundaries
 
-This section is a detailed reference for requests that need clarification. For
-a first run, use the example above; for saved drafts, go to
-[inspect, answer and start](#inspect-answer-and-start).
-
-For a new request such as “Implement CSV and JSON export, test both, and open one
-pull request for review,” Gallivant preserves the original text and records exact
-source spans assigning only the affirmative publication clause to the coordinator.
-All remaining implementation requirements and prohibitions stay in the provider's
-acceptance criteria. The generated brief's **Coordinator delivery contract** is
-part of both initial approval and ongoing change detection. Its publication
-obligation is fulfilled only by matching canonical repository, PR, base, head and
-completion-gate evidence; a provider statement cannot fulfill it.
-
-New ownership contracts also include a same-statement connector such as `, and`,
-`and then` or `then` in the publication span, so it cannot become a dangling
-implementation requirement. Connectors split across lines or containing quoted
-implementation text need clarification. Previously approved contracts keep their
-original spans, criteria and fingerprints on retry; new requests use version five.
-Version five keeps feature metadata and synthetic-object qualifiers within one
-line, so a following line beginning with “title” or “body” cannot hide an earlier
-PR instruction. Saved versions one through four retain their approved feature
-interpretation and exact source spans.
-
-This first recognizer supports one unqualified `open/create/raise/submit` review-PR
-clause outside quoted text/code. It is not a general natural-language permission
-parser. Conditional or negated publication clauses, owner approval prerequisites,
-destination qualifiers, multiple PRs and delivery-only requests return
-`TASK_DELIVERY_SCOPE` before inference. Unsupported publication actions also
-require clarification; they never become impossible provider obligations.
-Initial requests and later answers share the same bounded directive checks.
-Local-only, no-push, task-hold or patch-only directions cannot silently fall back
-to the default review-PR workflow. Preference wording such as “I don't want a PR”
-or “We don't need a pull request” also requires clarification.
-Explicit workflow merge or auto-merge requests, and prohibitions on creating
-commits or branches, also return `TASK_DELIVERY_SCOPE` before preparation or a new
-answer is saved. The review-PR workflow needs a branch and commits and grants no
-merge authority. “Do not merge” remains a valid constraint.
-This includes subject-led requests such as “You need to merge it” and passive
-or nominal prohibitions such as “Commits are not allowed” and “Commit creation is
-forbidden.” Compound feature objects such as commit messages and branch reports
-remain implementation requirements.
-
-Implementation subjects such as a PR status badge, pull-request template,
-published articles, a publish button, a command to publish docs, local storage,
-commit SHA, diff viewer or branch selection
-remain ordinary requirements. Technical conditions also remain implementation
-scope: `If name is empty, return friend. Open a PR for review.` and the answer
-`Commit the database transaction after validation.` are supported. By contrast,
-`Wait for my approval. Open a PR for review.` requires clarification before work.
-An implementation may consist entirely of a prohibition, such as “Do not log API
-keys in error responses.” That requirement remains in the acceptance criteria.
-Application operations such as publishing events to a message bus, delivering
-notifications, creating user records or merging duplicate contacts also remain
-implementation scope. This distinction applies to initial text and later answers,
-including application-user consent requirements. A technical operation cannot hide
-a later workflow restriction: “Do not deliver notifications twice or create a
-branch” still requires clarification. Quoted examples and merge-button/status
-features do not authorize an actual merge.
-Technical context can also come from a transport (“publish records to Kafka” or
-“deliver reports to S3”),
-repeated delivery (“do not deliver reports twice”) or “delivery of files.” Bare
-commands, Git destinations and restrictions on the task's changes remain workflow
-controls. An unknown noun alone, as in “do not publish the solution,” does not
-override that boundary.
-Destinations apply to their own action: a later report upload cannot qualify an
-earlier restriction on publishing changes. Git metadata used by an application
-operation is distinct from publishing to a Git repository.
-Unrecognized coordinated wording ends destination scope. Shared destinations
-require noun-phrase evidence: determiners, recognized modifiers/compounds or bare
-plural/data nouns. This supports “invoices and tax reports,” “metrics plus traces”
-and “widgets and the gizmo” without enumerating every domain noun. An unknown
-phrase such as “forward reports” is not assumed to be a noun phrase merely because
-its verb is absent from the action vocabulary. For ambiguous application wording,
-state the destination on each action or use separate sentences; direct application
-objects retain an open vocabulary.
-Verb/adjective ambiguities such as “duplicate reports” cannot supply a shared
-destination without a noun marker. Write “metrics and the duplicate reports to
-S3,” or put the destination directly on each application operation.
-The same applies to bare “email,” which can be an action: use “the email” when
-sharing another object's destination, or state its application destination directly.
-Likewise, “log entries” and “download links” can be commands or noun compounds;
-use “the log entries” and “the download links” in shared-destination noun lists.
-These conservative checks apply to new requests and answers. Saved ownership
-contracts retain their approved source spans and interpretation.
-Modifier recognition is intentionally bounded: word endings do not establish a
-noun phrase (for example, “give” and “apply” are verbs). An unfamiliar modifier
-requires a direct application destination instead of a guessed shared scope.
-A later data object cannot qualify a workflow object such as “the solution.”
-Coordinated transfer actions such as “upload reports” or “copy files” start their
-own scope; their destinations cannot qualify an earlier publication prohibition.
-This includes negative leads such as “never upload” and “avoid uploading.” Data
-noun lists such as “metrics plus archived reports,” “the log entries” or “the download
-links” can still share a destination; explicit action leads such as “please
-download links” start a separate action.
-Ordinary leading elisions such as `'90s` and `'tis` remain implementation text even
-when a later possessive apostrophe follows. Use double quotes or backticks to quote
-an entire example beginning with an elision. Saved ownership versions one through
-three keep their original literal interpretation and exact source spans.
-Negative coordination preserves each action's scope: “Do not commit the database
-transaction nor push changes” still forbids delivery. Combining only technical
-operations, such as a database transaction and inserting items into a queue,
-remains implementation scope; `neither … nor …` follows the same distinction.
-Modal forms such as “nor should you push” retain the prohibition too.
-This includes “cannot,” contracted modals such as “can't” or “shouldn't,” and
-permission wording such as “aren't allowed to push.” “In addition to,” “besides,”
-and other supported coordination phrases keep the same action boundary.
-PR quantifiers such as “any,” “more,” “multiple” and numeric counts also retain
-their delivery meaning: “Don't submit any PRs” requires clarification, while
-“Don't submit any PR descriptions” remains an implementation requirement. Only
-the supported affirmative single-PR clause can create a publication obligation.
-Qualifiers such as “GitHub,” “automated” or “experimental” cannot hide that PR
-object. Reference phrases such as “generate a report about the PR” do not request
-PR creation.
-Prohibition forms such as “refrain from opening a PR” and “forbidden from creating
-any PRs” also require clarification. Describing the procedure for opening a PR
-does not itself request publication.
-Active subjects also retain the restriction: “I forbid you from opening a PR” and
-“prevent the agent from opening a PR” require clarification.
-Passive equivalents such as “opening a PR is prohibited/disallowed/banned” do too.
-Explicit merge delegation, including “I require you to merge,” “have the agent
-merge” and “tell the agent to merge,” cannot grant merge authority.
-An incomplete prefix such as “Do not” retains scope across line breaks and blank
-lines. A complete implementation constraint such as “Do not change the API” can
-still precede a separate affirmative PR instruction.
-Multiword qualifiers such as “under any circumstances” or “for any reason” retain
-the same restriction. Nominal prohibitions such as “PR creation is prohibited”
-also require clarification. Application-data merges retain open object names,
-including invoices, database rows, accounts and files; workflow PR/branch objects
-and mixed data/workflow lists remain outside merge authority.
-Bare branches and ref-shaped targets (`main`, `feature/foo`, `origin/main`, Git
-revisions) are workflow merges. Application merges need named data evidence;
-“merge invoices into the main table” retains that application context.
-Explicit Git-qualified single-token operands remain ambiguous even when the token
-is a data word: “merge invoices from tag metadata” requires clarification because
-`metadata` can be a tag name. For application data, name its type explicitly, for
-example “merge invoices with tag metadata records.” “Merge head counts into the
-database” remains an application operation.
-Quantity words do not resolve that ambiguity: “two extra tag names” and “three
-further reference fields” still require clarification. Use an explicit data type,
-such as “two extra tag name records” or “three further reference field records.”
-The same prohibition leads apply to push, commit and branch creation, including
-“refrain from pushing” and “I forbid you from committing.” A negative application
-clause cannot hide a coordinated workflow restriction, as in “do not log keys or
-commit changes”; independent statements and technical conditions retain scope.
-Infinitive complements such as “I forbid the agent to push changes” follow the
-same rule as “forbid the agent from pushing changes.”
-Generating PR titles, bodies, labels and other feature metadata also remains
-implementation scope; those objects do not authorize creating the PR itself.
-Possessive forms such as “the PR's body” and “the pull requests’ titles” follow
-the same rule and retain their exact original text in implementation requirements.
-Hyphenated metadata compounds such as “PR-title” and “pull-request-body” do too.
-PR fixtures and explicitly synthetic representations (such as a mock PR object or
-a normalized PR record, fake PR object or dummy/stub payload) are implementation
-data. Bare PR objects and actual Git commit/branch objects do not gain that exception.
-Local conditions attached to publication are still refused; the parser does not
-guess that a comma or semicolon ended a prohibition or approval requirement.
-
-Keep every feature requirement and restriction, and state publication separately
-when needed. Quoted literal labels/code remain implementation data, including
-paired typographic single/double quotes; unmatched typographic quotes do not hide
-instructions. If local-only
-or patch-only output is required, do not authorize this review-PR workflow or
-remove the restriction to bypass clarification.
-Clarify the complete task with the owner and submit it under a new operation ID;
-never delete a condition just to pass validation. Answers may refine implementation
-but cannot silently replace publication ownership or add a publication prerequisite.
-This applies to explicit publication clauses, the default review workflow and new
-answers to older saved tasks without completion metadata. Exact previously
-accepted answer retries still replay their saved receipt. There is no typed
-delivery-amendment operation yet. The supported answer boundary
-conservatively refuses recognized lifecycle/artifact language; it does not claim
-to understand every possible paraphrase. Review the complete saved owner contract
-before authorizing implementation, and clarify conflicting delivery intent instead
-of treating a model's interpretation as permission.
-Selecting `integrated` still grants no merge authority. Existing saved tasks,
-approved criteria, false attestations and exact operation retries retain their
-original semantics; this change does not repair historical results.
+New tasks use an owner-selected [typed delivery profile](task-profiles.md).
+The default implements the requested change on a task branch and opens one
+pull request for review. The resolved repository and base are bound to that
+profile. Selecting `integrated` waits for an externally observed merge; it
+does not authorize Gallivant or the implementation agent to merge.
+
+Describe the outcome, constraints and verification you want. Preparation uses
+the selected harness or the operator-configured model route to organize that
+request. Every original clause and accepted answer keeps its exact source span
+and a visible mapping. Owner constraints remain authoritative even when the
+planner places a clause in an assumption. Generated rationale and assumptions
+cannot replace those constraints.
+
+The delivery screen raises clarification questions for unsupported external
+actions, conflicting targets or unresolved executable command arguments.
+Request text, selected files and model output cannot widen the typed profile.
+Help and read-only commands do not waive commands evaluated through shell
+substitution before the tool starts. Literal examples, documented commands and
+ordinary variable-valued read arguments retain their context. The screen is a
+bounded clarification aid, not a claim to understand arbitrary shell programs
+or every paraphrase; repository credentials and runtime enforcement still define
+what an implementation can actually access.
+
+Prepare the brief, inspect its requirements and spending allowance, answer any
+material questions, then explicitly approve that revision to start. A prepared
+brief alone never authorizes implementation. See [inspect, answer and
+start](#inspect-answer-and-start) for the supported commands.
+
+Historical tasks retain the free-text ownership contract and fragment version
+with which they were created. Exact operation retries replay that saved identity;
+new clause limits do not reinterpret a previously accepted line-based request.
+This release keeps main's established legacy recognizer rather than adding a
+second expanded publication-language parser. New tasks use the typed workflow.
 
 ## Repository context and preparation
 
@@ -267,13 +123,21 @@ a shorter corrected answer can reuse the refused operation identity. Raw whitesp
 word counts alone are insufficient because JSON quoting escapes tabs. Recovery
 settles any already-owned preparation turn and preserves usage before stopping
 oversized saved state; it launches no further planning or repair turn.
-An intake accepts at most 128 immutable requirement fragments across nonblank
-request and answer lines, matching its mapping capacity. Oversize requests stop
+An intake accepts at most 128 immutable requirement fragments across material
+request and answer clauses, matching its mapping capacity. Oversize requests stop
 before repository lookup or preparation. An answer that exceeds the remaining
 capacity is rejected before context reads or state changes; its operation ID and
 revision remain available for a corrected reply. Prepare a smaller intake if
 the remaining material questions cannot fit. Existing owned turns are reconciled
 with usage retained before oversized legacy state stops without a new turn.
+Each answer operation is also limited to 32 KiB of combined UTF-8 bytes across
+question IDs and answer strings. A new over-limit operation returns `TASK_INPUT`
+before signature hashing or delivery parsing, without changing the saved task.
+Exact receipts created by an older version still replay up to the largest batch
+the prior in-process service could accept: 128 answers of 32 KiB each with IDs up to 128
+bytes (4,210,688 bytes total). A changed input under an existing operation ID
+within that compatibility bound returns `TASK_CONFLICT`; larger input returns
+`TASK_INPUT` before signature hashing.
 The complete serialized preparation prompt is also limited to 120 KiB, including
 JSON escaping, runtime instructions, saved answers, previous output and repair
 feedback. This portable limit is checked before a harness probe or launch on every
@@ -488,20 +352,19 @@ changing their selected paths conflicts. Other CLI task operations reject
 without discoverable test commands, answer the material question and supply the
 exact repository command using `--verify 'python -m unittest'`.
 
-`--run` on preparation persists execution authorization through questions and
-answers. Once the exact generated brief and source snapshot pass readiness, the
-service starts it once and brings up the normal daemon. No second confirmation is
-needed. If the process exits after saving readiness but before dispatch, retrying
-the same preparation request or answer identity resumes that saved authorization
-through the exact approval and dispatch-ownership checks. A preparation-only
-retry still returns the draft without implementation.
-Preparation without `--run` returns the draft and an explicit next action.
-`--no-daemon` leaves monitoring to an explicitly started `gallivant up`.
+Preparation returns the draft and an explicit next action. Only a separate
+`task start --revision <revision> --run` approves its review digest and starts
+implementation through the normal daemon. Answers invalidate approval and return
+the next revision for review. After explicit approval has been saved, a crash
+retry reconciles that same approval and dispatch ownership without duplicating a
+run. A saved typed preparation flag without a review approval requires explicit
+start. Historical tasks created before typed profiles retain their saved consent.
+`--no-daemon` on start leaves monitoring to an explicitly started `gallivant up`.
 
 Readiness uses the existing PRD checker and readiness decision procedure. It proves
 contract structure, not semantic correctness or passing implementation tests.
-Review the assumptions and mapping. All nonblank request lines are immutable
-requirement fragments; their exact text is attached to mapped criteria or shown as
+Review the assumptions and mapping. Sentences, semicolon clauses and nonblank request lines outside quoted literals
+and code are immutable requirement fragments; their exact text is attached to mapped criteria or shown as
 unresolved. An explicit answer can clarify a previously questioned fragment; the
 mapping records which answer resolved it. Saved question ownership determines the
 clarification even when the planner omits `resolvedBy`. All applicable answers
@@ -531,8 +394,7 @@ new intake to establish its story ownership; no authorization is inferred from
 untrusted context. Saved validation recomputes the same owner-derived body, so an
 older draft containing planner-written executable scope cannot dispatch even if
 its recorded hash and readiness digest match. Existing owned implementation runs
-still reconcile without a duplicate launch. No extra confirmation is added to
-already authorized `--run` work.
+still reconcile without a duplicate launch. Existing revision-pinned approvals remain valid for exact crash retries.
 Each question's requirement IDs must exactly match its unresolved mappings, with
 no duplicate IDs. Saved ownership limits which fragments an answer can clarify.
 Reopening an older unanswered question proves ownership from its saved mappings;

package/lib/attribution.mjs

@@ -1,3 +1,4 @@
+import { workArtifactHook } from "./work_artifacts.mjs";
 // Harness attribution in a commit message, and the `commit-msg` hook that refuses it.
 //
 // Commits use the operator's configured identity. Their message must also describe the change without runner
@@ -75,11 +76,12 @@ export const attributionError = line => [
  *
  * Exits 1 on a match, which is what makes `git commit` create no commit object at all.
  */
-export const COMMIT_MSG_HOOK = `#!/usr/bin/env node
-// Written by Gallivant (lib/attribution.mjs). Refuses a commit message that credits an AI harness.
+export const commitMsgHook = (policy = {}) => `#!/usr/bin/env node
+// Written by Gallivant (lib/attribution.mjs). Refuses task work artifacts and commit messages that credit an AI harness.
 // Self-contained on purpose: this runs inside a sandboxed checkout that cannot read Gallivant's own source.
 // Dynamic import works whether the checkout's package.json declares module or commonjs.
-import("node:fs").then(({ readFileSync }) => {
+import("node:fs").then(async ({ readFileSync }) => {
+${workArtifactHook(policy)}
 const ATTRIBUTION_PATTERNS = ${JSON.stringify(ATTRIBUTION_PATTERNS.map(re => [re.source, re.flags]))}.map(([source, flags]) => new RegExp(source, flags));
 ${attributionIn.toString()}
 const attributionError = ${attributionError.toString()};
@@ -93,3 +95,5 @@ if (line) {
 process.exit(0);
 });
 `;
+
+export const COMMIT_MSG_HOOK = commitMsgHook();

package/lib/block.mjs

@@ -3,7 +3,7 @@
 import { HARNESSES } from "./config.mjs";
 import { isSessionFor } from "./harness.mjs";
 import { BLOCK_OPEN, BLOCK_OPENS, BRANCH_PREFIXES } from "./public-format.mjs";
-import { normalizeReceipt } from "./deliverable.mjs";
+import { normalizeReceipt, withoutReceipt } from "./deliverable.mjs";
 
 const CLOSE = "-->";
 const FIELDS = ["prd", "harness", "session", "branch"];
@@ -21,6 +21,15 @@ function blocks(body) {
   return [...body.matchAll(OPEN_RE)].map(match => ({ start: match.index, open: match[0].trimEnd(), end: body.indexOf(CLOSE, match.index + match[0].length) }));
 }
 
+/** Preserve human prose; drop only recognized task-owned recovery/receipt records. */
+export function withoutTaskMetadata(body) {
+  let text = String(body || "");
+  const found = blocks(text);
+  if (found.length > 1 || found.some(b => b.end < 0)) throw new Error("Ambiguous recovery metadata; repair the source PR body before promotion");
+  if (found.length) text = text.slice(0, found[0].start) + text.slice(found[0].end + CLOSE.length);
+  return withoutReceipt(text).trim();
+}
+
 export function renderBlock({ prd, harness, session, branch }) {
   const data = Buffer.from(JSON.stringify({ version: 1, prd, harness, session: session ?? null, branch }), "utf8").toString("base64url");
   return `${BLOCK_OPEN}\n${data}\n${CLOSE}`;

package/lib/chains.mjs

@@ -1,16 +1,25 @@
+import { terminalIdentityProblem } from "./host_contract.mjs";
+import { hostApi } from "./hosts.mjs";
 // Linear, operator-approved plans. The normal start/tick machinery still owns every individual run.
 import { randomUUID } from "node:crypto";
 import { requestFor } from "./sources/index.mjs";
 import { resolveBase } from "./config.mjs";
-import { entryId } from "./state.mjs";
+import { entryId, resolveHandle, matchesChainAnchor } from "./state.mjs";
 import { prdIdFromBranch } from "./git.mjs";
-import { repoFromUrl } from "./gh.mjs";
+import { hosts } from "./hosts.mjs";
 import { start } from "./commands/start.mjs";
 import { validateStartRequest, captureStartInput, contentDigest, checkBaseFiles } from "./start_contract.mjs";
 
 const MAX_FAILURES = 5;
 const flights = new Map();
 const stamp = () => new Date().toISOString();
+const rateLimitDelay = value => {
+  const seconds = Number(value);
+  const requested = value != null && Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000
+    : typeof value === "string" && Number.isFinite(Date.parse(value)) ? Date.parse(value) - Date.now()
+      : 15 * 60_000;
+  return Math.min(2 * 60 * 60_000, Math.max(60_000, requested));
+};
 const validName = name => {
   if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name || "") || name.length > 80) throw new Error("chain name must be 1–80 lowercase letters, digits and single dashes");
 };
@@ -30,29 +39,58 @@ async function planStep(ctx, path, askedBase) {
 
 async function approveBaseFiles(ctx, plans) {
   const { repo, base } = plans[0];
-  if (!await ctx.gh.branchExists(repo, base)) throw new Error(`base ${repo}:${base} is missing or GitHub is unavailable`);
-  const sha = await ctx.gh.refSha(repo, base);
+  if (!await hostApi(ctx).branchExists(repo, base)) throw new Error(`base ${repo}:${base} is missing or GitHub is unavailable`);
+  const sha = await hostApi(ctx).refSha(repo, base);
   if (!/^[a-f0-9]{40,64}$/.test(sha || "")) throw new Error(`GitHub did not return a base commit for ${repo}:${base}`);
   const files = new Map();
   for (const plan of plans) {
     for (const [path] of plan.input.files) {
-      if (!files.has(path)) files.set(path, contentDigest(await ctx.gh.fileAtStrict(repo, path, sha)));
+      if (!files.has(path)) files.set(path, contentDigest(await hostApi(ctx).fileAtStrict(repo, path, sha)));
       plan.step.baseFiles[path] = files.get(path);
     }
   }
 }
 
-export async function queueChain(ctx, { name, paths, base = null }) {
+function prIdentityProblem(ctx, c, entry, pr) {
+  let parsed;
+  try { parsed = (ctx.hosts ?? hosts).fromUrl(pr.url); } catch { return "PR identity or intended base changed"; }
+  return parsed.repository.key !== c.repo || parsed.number !== entry.pr || pr.number !== entry.pr
+    || pr.headRefName !== entry.branch || pr.isCrossRepository !== false || pr.baseRefName !== c.base
+    || (entry.url && pr.url !== entry.url) ? "PR identity or intended base changed" : null;
+}
+
+async function planAnchor(ctx, selector, plan) {
+  const entries = ctx.state.entries();
+  let id;
+  if (/^https?:\/\//i.test(selector)) {
+    const { repository, number } = (ctx.hosts ?? hosts).fromUrl(selector);
+    const matches = entries.filter(([, entry]) => entry.repo === repository.key && entry.pr === number);
+    if (matches.length !== 1) throw new Error("--after requires exactly one registered predecessor PR; register it first");
+    id = matches[0][0];
+  } else id = resolveHandle(entries, selector);
+  const entry = ctx.state.get(id);
+  if (!Number.isSafeInteger(entry?.pr) || entry.pr < 1 || !entry.url || !entry.branch
+    || entry.repo !== plan.repo || entry.base !== plan.base) throw new Error("--after requires a registered PR in the same repository and approved base as the queued tasks");
+  const pr = await hostApi(ctx).prView(plan.repo, entry.pr);
+  const problem = prIdentityProblem(ctx, plan, entry, pr);
+  if (problem) throw new Error(`${id}: ${problem}`);
+  if (!["OPEN", "MERGED"].includes(pr.state)) throw new Error(`${id}: predecessor PR must be open or merged, not closed without merging`);
+  return { id, repo: entry.repo, base: entry.base, branch: entry.branch, pr: entry.pr, url: entry.url, merged: null };
+}
+
+export async function queueChain(ctx, { name, paths, base = null, after = null }) {
   validName(name);
-  if (!Array.isArray(paths) || paths.length < 2) throw new Error("a chain needs at least two ready PRD paths in execution order");
+  if (after !== null && (typeof after !== "string" || !after.trim())) throw new Error("--after requires a registered PR URL or handle");
+  if (!Array.isArray(paths) || paths.length < (after ? 1 : 2)) throw new Error(after ? "a chain with --after needs at least one ready PRD path" : "a chain needs at least two ready PRD paths in execution order");
   const plans = [];
   for (const path of paths) plans.push(await planStep(ctx, path, base));
   const first = plans[0];
   if (plans.some(p => p.repo !== first.repo || p.base !== first.base || p.step.checkout !== first.step.checkout)) throw new Error("a chain must use one repository checkout and one base branch");
   if (new Set(plans.map(p => p.step.id)).size !== plans.length) throw new Error("a chain cannot contain duplicate PRDs");
+  const anchor = after ? await planAnchor(ctx, after, first) : null;
   await approveBaseFiles(ctx, plans);
   return ctx.state.createChain({ name, repo: first.repo, base: first.base, status: "active", index: 0,
-    steps: plans.map(p => p.step), reason: null, failures: 0, created_at: stamp(), updated_at: stamp() });
+    ...(anchor ? { after: anchor } : {}), steps: plans.map(p => p.step), reason: null, failures: 0, created_at: stamp(), updated_at: stamp() });
 }
 
 export function cancelChain(ctx, name) {
@@ -65,7 +103,7 @@ export function cancelChain(ctx, name) {
 export async function retryChain(ctx, { name, resnapshot = false }) {
   const c = ctx.state.getChain(name);
   if (!c) throw new Error(`no chain ${name}`);
-  if (c.status !== "stopped") throw new Error(`chain ${name} is ${c.status}; --retry is for a stopped chain`);
+  if (c.status !== "stopped" && !(c.status === "active" && resnapshot)) throw new Error(`chain ${name} is ${c.status}; --retry is for a stopped chain, or --retry --resnapshot for undispatched steps in an active chain`);
   for (const step of c.steps) {
     if (ctx.state.startClaim(step.id) || (step.dispatch && !ctx.state.get(step.id))) throw new Error(uncertain(step.id));
   }
@@ -109,7 +147,40 @@ function matchesEntry(c, step, entry) {
     && entry.start_token && (!step.entry || step.entry.token === entry.start_token);
 }
 
+// Owned milestones and registered predecessors use the same host evidence and merge gate.
+async function observeMerge(ctx, c, id, entry) {
+  if (!entry.pr || (entry.last?.run && entry.last.exit == null) || ctx.runnerFor(id).current()?.running) return {};
+  const pr = await hostApi(ctx).prView(c.repo, entry.pr);
+  const identity = prIdentityProblem(ctx, c, entry, pr);
+  if (identity) return { problem: identity };
+  if (pr.state === "CLOSED") return { problem: `PR #${entry.pr} was closed without merging; reopen and register the PR before retrying, or cancel this chain` };
+  if (pr.state !== "MERGED") return {};
+  const problem = await terminalIdentityProblem(hostApi(ctx), entry, pr);
+  if (problem) return { problem };
+  const sha = pr.mergeCommit?.oid;
+  if (!/^[a-f0-9]{40,64}$/.test(sha || "") || !pr.mergedAt || !await hostApi(ctx).containsCommit(c.repo, c.base, sha)) {
+    return { problem: `merge commit is missing from the intended base ${c.base}` };
+  }
+  return { merged: { pr: entry.pr, sha, at: pr.mergedAt } };
+}
+
 async function tickChain(ctx, c) {
+  if (c.rateLimitUntil) {
+    if (Date.now() < Date.parse(c.rateLimitUntil)) return;
+    c = saveActive(ctx, c, { rateLimitUntil: null, reason: null });
+    if (c.status !== "active") return;
+  }
+  if (c.after) {
+    const entry = ctx.state.get(c.after.id);
+    if (!matchesChainAnchor(c.after, entry)) { await stop(ctx, c, `${c.after.id}: registered predecessor identity changed or is missing`); return; }
+    if (!c.after.merged) {
+      const observation = await observeMerge(ctx, c, c.after.id, entry);
+      if (observation.problem) await stop(ctx, c, `${c.after.id}: ${observation.problem}`);
+      else if (observation.merged) saveActive(ctx, c, { after: { ...c.after, merged: observation.merged }, failures: 0, reason: null });
+      else if (c.failures) saveActive(ctx, c, { failures: 0, reason: null });
+      return; // Observe the predecessor merge before a later tick can start any successor.
+    }
+  }
   let step = c.steps[c.index];
   if (step.dispatch) {
     const entry = ctx.state.get(step.id);
@@ -122,22 +193,11 @@ async function tickChain(ctx, c) {
       c = saveActive(ctx, c, { steps }); step = c.steps[c.index];
       if (c.status !== "active") return;
     }
-    // The normal run remains the recovery surface. Never have two milestone agents mutating dependent work.
-    if (!entry.pr || (entry.last?.run && entry.last.exit == null) || ctx.runnerFor(step.id).current()?.running) return;
-    const pr = await ctx.gh.prView(c.repo, entry.pr);
-    const identity = repoFromUrl(pr.url);
-    if (identity?.repo !== c.repo || identity.number !== entry.pr || pr.number !== entry.pr
-      || pr.headRefName !== entry.branch || pr.isCrossRepository !== false || pr.baseRefName !== c.base) {
-      await stop(ctx, c, `${step.id}: PR identity or intended base changed`); return;
-    }
-    if (pr.state === "CLOSED") { await stop(ctx, c, `${step.id}: PR #${entry.pr} was closed without merging; reopen and register the PR before retrying, or cancel this chain`); return; }
-    if (pr.state !== "MERGED") { if (c.failures) saveActive(ctx, c, { failures: 0, reason: null }); return; }
-    const sha = pr.mergeCommit?.oid;
-    if (!/^[a-f0-9]{40,64}$/.test(sha || "") || !pr.mergedAt || !await ctx.gh.containsCommit(c.repo, c.base, sha)) {
-      await stop(ctx, c, `${step.id}: merge commit is missing from the intended base ${c.base}`); return;
-    }
+    const observation = await observeMerge(ctx, c, step.id, entry);
+    if (observation.problem) { await stop(ctx, c, `${step.id}: ${observation.problem}`); return; }
+    if (!observation.merged) { if (c.failures) saveActive(ctx, c, { failures: 0, reason: null }); return; }
     const steps = structuredClone(c.steps);
-    steps[c.index].merged = { pr: entry.pr, sha, at: pr.mergedAt };
+    steps[c.index].merged = observation.merged;
     const index = c.index + 1;
     saveActive(ctx, c, { steps, index, status: index === steps.length ? "done" : "active", reason: null, failures: 0 });
     return; // At most one transition per chain per tick; another tick starts the successor.
@@ -146,13 +206,13 @@ async function tickChain(ctx, c) {
   if (ctx.state.get(step.id) || ctx.state.startClaim(step.id)) { await stop(ctx, c, uncertain(step.id)); return; }
   const p = await planStep(ctx, step.path, c.base);
   if (p.input.digest !== step.digest) { await stop(ctx, c, `${step.id}: queued PRD or sources changed; review them, then gallivant chain ${c.name} --retry --resnapshot`); return; }
-  const after = c.steps.slice(0, c.index).map(s => s.merged?.sha);
+  const after = [...(c.after ? [c.after.merged?.sha] : []), ...c.steps.slice(0, c.index).map(s => s.merged?.sha)];
   for (const sha of after) {
-    if (!sha || !await ctx.gh.containsCommit(c.repo, c.base, sha)) { await stop(ctx, c, `predecessor merge is no longer in ${c.base}; inspect the base history`); return; }
+    if (!sha || !await hostApi(ctx).containsCommit(c.repo, c.base, sha)) { await stop(ctx, c, `predecessor merge is no longer in ${c.base}; inspect the base history`); return; }
   }
   // Fail before cloning for a normal source collision; start rechecks against the actual clone to close the race.
-  const baseSha = await ctx.gh.refSha(c.repo, c.base);
-  await checkBaseFiles(p.input, step.baseFiles, path => ctx.gh.fileAtStrict(c.repo, path, baseSha));
+  const baseSha = await hostApi(ctx).refSha(c.repo, c.base);
+  await checkBaseFiles(p.input, step.baseFiles, path => hostApi(ctx).fileAtStrict(c.repo, path, baseSha));
   const dispatch = randomUUID();
   c = ctx.state.updateChain(c.name, current => {
     if (current.status !== "active" || current.index !== c.index || current.steps[current.index].dispatch) return {};
@@ -163,6 +223,7 @@ async function tickChain(ctx, c) {
   step = c.steps[c.index];
   try {
     await start(ctx, { path: step.path, base: c.base, chain: { name: c.name, index: c.index, dispatch, digest: step.digest, baseFiles: step.baseFiles, after } });
+    saveActive(ctx, c, { reason: null, failures: 0, rateLimitUntil: null });
   } catch (error) {
     const entry = ctx.state.get(step.id);
     // A post-registration failure (for example config persistence) still owns a valid run. Reconcile next tick.
@@ -186,6 +247,14 @@ export async function tickChains(ctx) {
       try { await tickChain(ctx, chain); results.push({ chain: chain.name, ok: true }); }
       catch (error) {
         const current = ctx.state.getChain(chain.name);
+        if (error.code === "BB_RATE_LIMIT") {
+          const rateLimitUntil = new Date(Date.now() + rateLimitDelay(error.retryAfter)).toISOString();
+          const reason = `Bitbucket API rate limited; next chain check after ${rateLimitUntil}`;
+          saveActive(ctx, current, { rateLimitUntil, reason, failures: 0 });
+          ctx.log.warn(`chain ${chain.name}: ${reason}`);
+          results.push({ chain: chain.name, ok: false, error: reason });
+          continue;
+        }
         const failures = (current.failures || 0) + 1;
         if (error.code === "CHAIN_INPUT_CHANGED") await stop(ctx, current, error.message);
         else if (failures >= MAX_FAILURES) await stop(ctx, current, `${error.message} (${failures} failed checks; retry after fixing)`);
@@ -203,9 +272,10 @@ export async function tickChains(ctx) {
 export function chainRows(ctx) {
   return ctx.state.chains().map(([name, c]) => {
     const step = c.steps[c.index], entry = step ? ctx.state.get(step.id) : null;
+    const anchor = c.after && !c.after.merged ? c.after : null;
     return { name, status: c.status, repo: c.repo, base: c.base, completed: c.index, total: c.steps.length,
-      current: step?.id || null, reason: c.reason || (c.status === "done" ? "all milestones merged" : entry ? (entry.reason || (entry.pr ? `waiting for PR #${entry.pr} to merge` : "waiting for the current run")) : "queued"),
-      url: entry?.url || null };
+      current: anchor?.id || step?.id || null, reason: c.reason || (c.status === "done" ? "all milestones merged" : anchor ? `waiting for predecessor PR #${anchor.pr} to merge` : entry ? (entry.reason || (entry.pr ? `waiting for PR #${entry.pr} to merge` : "waiting for the current run")) : "queued"),
+      url: anchor?.url || entry?.url || null };
   });
 }
 
@@ -215,6 +285,7 @@ export function renderChains(ctx, name = null) {
   const lines = rows.map(c => `${c.name}: ${c.status} — ${c.completed}/${c.total} merged -> ${c.repo}:${c.base}${["done", "cancelled"].includes(c.status) ? "" : ` — ${c.reason}`}`);
   if (name) {
     const c = ctx.state.getChain(name);
+    if (c.after) lines.push(`  after ${c.after.id} — ${c.after.merged ? "merged" : "waiting"} #${c.after.pr}\n     ${c.after.url}`);
     c.steps.forEach((s, i) => lines.push(`  ${i + 1}. ${s.id} — ${s.merged ? `merged #${s.merged.pr}` : s.dispatch ? "started" : "queued"}\n     ${s.path}`));
     if (c.status === "stopped") lines.push(`Inspect the reason, then: gallivant chain ${name} --retry`);
   }

package/lib/codex_cloud.mjs

@@ -1,6 +1,7 @@
 // Supported CLI only. There is no private Cloud HTTP client or review engine.
 import { join } from "node:path";
-import { execFileAsync, repositoryMatches } from "./gh.mjs";
+import { execFileAsync } from "./process.mjs";
+import { repositoryMatches } from "./repository.mjs";
 import { ensureDir, readJson, writeJsonAtomic } from "./fs.mjs";
 import { executionError, dispatchNotSentError, redact, accessProbeFailure } from "./execution_io.mjs";
 import { validateCloudConfig, CLOUD_VERSION, CLOUD_DISPATCH_UNAVAILABLE } from "./codex_cloud_config.mjs";