@@ -81,6 +81,8 @@ Every reproduced race requires a failing-before and passing-after regression. As
 - If the external lifecycle mechanism or mode changes between validation passes, abort before the irreversible command. Create durable lifecycle ownership from the final stable mode, never from an earlier observation.
 - When an irreversible command has an ambiguous timeout, cancellation, transport, or unknown outcome, retain durable in-flight ownership and reconcile external state before enabling retry. Only a confirmed refusal may become retryable failure.
 - Correlate retry observations to the current attempt with an immutable external identity or event boundary, and fail closed when multiple post-boundary action sequences appear. Matching only the resource or commit identity can replay another attempt's terminal event.
+- Make an idempotency key required at the API boundary for every replayable action, and look up its saved outcome before any other guard, including in-flight, validation and coordinator shutdown guards. The one exception is the server's HTTP 503 during shutdown, which applies nothing; the client must keep the key and resend it. Save every definite outcome under the key (refusals before admission too), keep the saved response current with the durable outcome it reports, and replay failures as failures with complete result fields. Only a passing, nothing-applied outcome (shutdown, abort, deadline, storage error) stays resendable.
+- When a refusal must also change durable state (for example, handing an expired task to a person), commit that change outside the refused transaction, together with the saved refusal. Never write it inside the transaction the refusal rolls back.
 
 ## Owned host and Docker resources
 
 
@@ -19,6 +19,8 @@ export interface RemoteMergeState {
   mergeQueue: boolean;
   requiredChecks: RequiredCheck[];
   alreadyFixed: 'clear' | 'found' | 'unknown';
+  /** The pull request's web URL, when GitHub reports a valid one. Display only; never used to decide readiness. */
+  url?: string;
 }
 
 export interface MergeResult { url: string; }
@@ -139,7 +141,7 @@ export class GhMergeGateway implements MergeGateway, MergeQueueGateway {
   }
 
   async #inspectNow(signal?: AbortSignal): Promise<RemoteMergeState> {
-    const pr = await this.#json(['pr','view',String(this.config.pullRequest),'--repo',this.config.repository,'--json','baseRefName,baseRefOid,headRefName,headRefOid,state,mergeable,statusCheckRollup'], signal) as Record<string, unknown>;
+    const pr = await this.#json(['pr','view',String(this.config.pullRequest),'--repo',this.config.repository,'--json','baseRefName,baseRefOid,headRefName,headRefOid,state,mergeable,statusCheckRollup,url'], signal) as Record<string, unknown>;
     if (typeof pr.baseRefName !== 'string' || typeof pr.headRefName !== 'string' || !['OPEN','CLOSED','MERGED'].includes(String(pr.state)) || !['MERGEABLE','CONFLICTING','UNKNOWN'].includes(String(pr.mergeable)) || !Array.isArray(pr.statusCheckRollup))
       throw new Error('GitHub returned an incomplete pull request state.');
     const branch = encodeURIComponent(pr.baseRefName);
@@ -233,6 +235,7 @@ export class GhMergeGateway implements MergeGateway, MergeQueueGateway {
       base: fullSha(pr.baseRefOid, 'base SHA'), head: fullSha(pr.headRefOid, 'head SHA'),
       pullRequestState: pr.state as RemoteMergeState['pullRequestState'], mergeable: pr.mergeable as RemoteMergeState['mergeable'],
       rulesKnown, atomicBaseGuard, mergeQueue, requiredChecks, alreadyFixed: await this.#alreadyFixed(signal),
+      ...(typeof pr.url === 'string' && pr.url.length <= 2048 && /^https:\/\//.test(pr.url) ? { url: pr.url } : {}),
     };
   }
 
 
@@ -0,0 +1,102 @@
+import { createHash } from 'node:crypto';
+import type { InvocationContext, Phase, StopReason } from '../agents/contract.ts';
+
+/** F1 runner lifecycle vocabulary. See docs/implementation/runner-lifecycle.md. */
+export type AttemptState = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'stale';
+export type FirstReason = 'cancelled' | 'shutdown' | 'stale' | 'time-limit';
+export type AttemptKind = 'planning' | 'question' | 'review' | 'check' | 'execute' | 'fix' | 'rebase-fix';
+export type TaskStatus = 'queued' | 'running' | 'needs human' | 'needs amendment' | 'needs approval'
+  | 'possibly already fixed' | 'in review' | 'approved but merge blocked' | 'merged' | 'cancelled';
+
+export const TASK_STATUSES: readonly TaskStatus[] = ['queued', 'running', 'needs human', 'needs amendment', 'needs approval',
+  'possibly already fixed', 'in review', 'approved but merge blocked', 'merged', 'cancelled'];
+export const CLOSED_STATUSES: readonly TaskStatus[] = ['merged', 'cancelled'];
+/** A merge starts only from review; every other status is closed, running, queued or waiting for a person. */
+export const MERGEABLE_STATUSES: readonly TaskStatus[] = ['in review', 'approved but merge blocked'];
+export const TERMINAL_STATES: readonly AttemptState[] = ['completed', 'failed', 'cancelled', 'stale'];
+export const FIRST_REASONS: readonly FirstReason[] = ['cancelled', 'shutdown', 'stale', 'time-limit'];
+/** Each F attempt kind runs under exactly one existing D phase. */
+export const ATTEMPT_PHASES = {
+  planning: 'planning', question: 'questions', review: 'review', check: 'review',
+  execute: 'execute', fix: 'fix', 'rebase-fix': 'fix',
+} as const satisfies Record<AttemptKind, Phase>;
+export const WRITABLE_KINDS: readonly AttemptKind[] = ['execute', 'fix', 'rebase-fix'];
+export const MAX_REASON = 4000;
+export const MAX_RESULT_BYTES = 1024 * 1024;
+export const DEFAULT_TASK_BUDGET_MS = 2 * 60 * 60 * 1000;
+
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+/** Attempt, action and allocation IDs are lowercase UUID v4s; anything else is refused before use. */
+export function isUuidV4(value: unknown): value is string { return typeof value === 'string' && UUID_V4.test(value); }
+export function assertUuidV4(value: unknown, name: string): asserts value is string {
+  if (!isUuidV4(value)) throw new GuardRefusal(`${name} must be a lowercase UUID v4.`);
+}
+
+/** A guard refused the action. Refusals are definite outcomes and are recorded for replay. */
+export class GuardRefusal extends Error {}
+/** Reusing an action ID for a different request. */
+export class ActionIdReused extends GuardRefusal {}
+/**
+ * A refusal whose state change must outlive the rollback of the refused transaction. The Store commits `effect`
+ * with the saved refusal inside userAction, or in its own transaction when there is no enclosing action.
+ */
+export class RefusalWithEffect extends GuardRefusal {
+  readonly effect: () => void;
+  constructor(message: string, effect: () => void) { super(message); this.effect = effect; }
+}
+
+export function bounded(reason: string): string {
+  const text = reason.trim() || 'No reason given.';
+  return text.length > MAX_REASON ? `${text.slice(0, MAX_REASON - 1)}…` : text;
+}
+
+/** Stable fingerprint of a user action request; key order does not matter. */
+export function requestHash(kind: string, request: unknown): string {
+  const canonical = (value: unknown): unknown => Array.isArray(value) ? value.map(canonical)
+    : value && typeof value === 'object'
+      ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical((value as Record<string, unknown>)[key])]))
+      : value;
+  return createHash('sha256').update(JSON.stringify([kind, canonical(request)])).digest('hex');
+}
+
+export interface Settlement {
+  /** F's first reason: the durable one, or the in-memory one if its write failed. */
+  firstReason: FirstReason | null;
+  contextCurrent: boolean;
+  stopReason?: StopReason;
+  exitCode: number | null;
+  /** Output passed validation (schema, size and, for writable attempts, the file-scope audit). */
+  valid: boolean;
+  /** Bounded actionable detail from the provider, used for generic failures. */
+  detail?: string;
+}
+export interface Classification {
+  state: Exclude<AttemptState, 'pending' | 'running'>;
+  reason: string | null;
+  /** The task budget ran out; the task moves to needs human unless it is closed or a cancel is pending. */
+  timeLimit: boolean;
+}
+
+/** Terminal-state precedence at settlement. Order matters; see "Rules for the running state", rule 2. */
+export function classifySettlement(s: Settlement): Classification {
+  const dFailure = s.stopReason === 'timeout' || s.stopReason === 'output-limit' || s.stopReason === 'capture-failure';
+  const dReason = () => s.stopReason === 'timeout' ? 'Timed out.' : bounded(s.detail ?? `Agent stopped: ${s.stopReason}.`);
+  switch (s.firstReason) {
+    case 'cancelled': return { state: 'cancelled', reason: 'Cancelled.', timeLimit: false };
+    // D keeps the first reason it received: a non-shutdown stop reason proves D stopped before shutdown reached it.
+    case 'shutdown': return dFailure ? { state: 'failed', reason: dReason(), timeLimit: false }
+      : { state: 'cancelled', reason: 'Stopped by shutdown', timeLimit: false };
+    case 'stale': return { state: 'stale', reason: bounded(s.detail ?? 'The plan, snapshot, assignment or referenced code changed.'), timeLimit: false };
+    case 'time-limit': return { state: 'cancelled', reason: 'Task time limit reached', timeLimit: true };
+  }
+  if (!s.contextCurrent) return { state: 'stale', reason: 'The plan, snapshot, assignment or referenced code changed.', timeLimit: false };
+  // With no first reason, any D stop reason means the agent did not finish normally, even with exit 0.
+  if (dFailure || s.stopReason) return { state: 'failed', reason: dReason(), timeLimit: false };
+  if (s.exitCode === 0 && s.valid) return { state: 'completed', reason: null, timeLimit: false };
+  return { state: 'failed', reason: bounded(s.detail ?? `Agent exited with code ${s.exitCode ?? 'none'}.`), timeLimit: false };
+}
+
+export function sameContext(a: InvocationContext, b: InvocationContext): boolean {
+  return a.snapshotId === b.snapshotId && a.planId === b.planId && a.planRevision === b.planRevision
+    && a.assignmentId === b.assignmentId && a.referencedCodeHash === b.referencedCodeHash && a.stateVersion === b.stateVersion;
+}