@percepteye/agent-flywheel 0.1.0

package/src/turns.js

@@ -0,0 +1,437 @@
+/**
+ * A captured production turn, on disk, in the format the Python SDK already
+ * writes and reads.
+ *
+ * ONE FORMAT, TWO IMPLEMENTATIONS. A customer deploys this package or the
+ * Python one, never both -- so the two must agree, and the thing that makes
+ * them agree cannot be a comment saying so. It is this: a turn is a DIRECTORY
+ * named for the turn id, with the shared core files below and two optional
+ * execution-identity files whose names and shapes also match Python:
+ *
+ *   tool_calls.jsonl   one JSON object per executed tool call  (already ours:
+ *                      `trajectory.js` has written it since day one, and it is
+ *                      why nothing here reimplements it)
+ *   turns.jsonl        {kind:"task"|"answer", text, turn_id,
+ *                       conversation_id, task_id}
+ *   conversation_id    the conversation this turn belongs to, as bare text
+ *   task_id            caller-authored case/work-item correlation, as text
+ *   task_id.conflict   monotonic abstention when two task bindings disagree
+ *   agent_fingerprint.json  an exact, SDK-reconciled execution fingerprint
+ *   agent_fingerprint.conflict  permanent abstention if writers disagree
+ *
+ * The Python end is `agent_flywheel.outcomes` (`record_turn_text`,
+ * `read_turn_text`, `read_conversation_id`) and `production.Attachment._turn_wire`.
+ * The rules below are not restatements of that code; they are the same rules,
+ * and where one is subtle the reason is given so the two do not drift apart by
+ * someone "simplifying" one side.
+ *
+ * WHAT MAKES A TURN HERE. OpenClaw gives every agent run a `runId`, and it is
+ * on all three hooks this lane uses -- `message_received` (the end user's
+ * message), `after_tool_call` (event AND context), and `agent_end` (the
+ * answer). So the turn boundary is DECLARED by the host rather than inferred
+ * by us, which is the same standard the Python side holds: guessing where one
+ * turn ends and the next begins is how one user's tool calls end up in
+ * another's record.
+ */
+import {
+  appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+
+import { readTrajectory, TOOL_CALLS_FILENAME } from "./trajectory.js";
+import { isLowerSha256 } from "./execution-identity.js";
+import {
+  ContractError, productionIdentifier, productionTurnIdentifier,
+} from "./wire.js";
+
+export const TURNS_FILENAME = "turns.jsonl";
+export const CONVERSATION_ID_FILENAME = "conversation_id";
+export const TASK_ID_FILENAME = "task_id";
+export const TASK_ID_CONFLICT_FILENAME = "task_id.conflict";
+export const AGENT_FINGERPRINT_FILENAME = "agent_fingerprint.json";
+export const AGENT_FINGERPRINT_CONFLICT_FILENAME = "agent_fingerprint.conflict";
+
+/** The two halves of a turn. Anything else is a programming error. */
+export const TURN_KINDS = ["task", "answer"];
+
+/**
+ * Matches Python's `record_turn_text(max_chars=20_000)`.
+ *
+ * A cap rather than the whole message, because this is a customer's end user's
+ * text and a runaway paste should not put a megabyte per turn on their disk.
+ * The same number on both sides, so a turn captured by either package
+ * truncates at the same point and the two corpora are comparable.
+ *
+ * CHARS MEANS CODE POINTS, which is what `truncateChars` below exists to make
+ * true -- see it for why `slice` was not that.
+ */
+export const MAX_TEXT_CHARS = 20_000;
+
+/**
+ * `text[:MAX_TEXT_CHARS]` as PYTHON means it: code POINTS, not UTF-16 units.
+ *
+ * `String.prototype.slice` counts UTF-16 code units, so it truncated a
+ * mostly-emoji message at HALF the documented point -- the two corpora were
+ * not comparable, which is the one thing the shared constant is for. Worse, a
+ * cut landing between the halves of a surrogate pair leaves a LONE SURROGATE,
+ * which `JSON.stringify` writes into `turns.jsonl` and onto the wire; the
+ * intake cannot encode it to UTF-8, the chunk is never acknowledged, and
+ * `createTurnUploader.flush` leaves every marker in that chunk unwritten, so
+ * the poisoned turn is re-sent on every flush forever. Iterating the string
+ * yields whole code points, so neither is possible.
+ *
+ * The length guard is not an optimisation of the general case, it IS the
+ * common case: code units are never fewer than code points, so text under the
+ * cap in units is under it in points and never needs to be split at all.
+ */
+function truncateChars(text) {
+  if (text.length <= MAX_TEXT_CHARS) return text;
+  return [...text].slice(0, MAX_TEXT_CHARS).join("");
+}
+
+/** One turn's directory. The directory name IS the turn id. */
+export function turnDir(root, turnId) {
+  const exact = safeTurnId(turnId);
+  if (exact === null) {
+    throw new ContractError("turn id does not match the production identifier grammar");
+  }
+  return join(root, exact);
+}
+
+/**
+ * A turn id is host-supplied, and it becomes a path segment.
+ *
+ * Valid opaque ids are preserved byte-for-byte. Invalid values return null;
+ * the host adapter can then mint a fresh id for that run rather than silently
+ * cleaning two different caller ids into the same directory name.
+ */
+export function safeTurnId(value) {
+  return productionTurnIdentifier(value);
+}
+
+/**
+ * Append one half of a turn. Returns whether anything was written.
+ *
+ * NEVER THROWS. This runs inside a customer's production request, and the
+ * standing rule is that a capture bug costs the observation and never the
+ * turn.
+ *
+ * EMPTY TEXT WRITES NOTHING, rather than writing an empty record: "the agent
+ * answered with silence" and "we were not given the answer" are different
+ * claims, and only the second is true when there is no text. Collapsing them
+ * would put an empty `final_text` on the wire, which the intake would accept
+ * as a real -- and terrible -- answer.
+ */
+export function recordTurnText(dir, kind, text, ids = {}) {
+  if (!TURN_KINDS.includes(kind)) {
+    throw new Error(`turn kind must be one of ${TURN_KINDS}, got ${kind}`);
+  }
+  if (typeof text !== "string" || !text.trim()) return false;
+  const record = { kind, text: truncateChars(text.trim()) };
+  for (const [k, v] of Object.entries(ids)) {
+    if (typeof v === "string" && v) record[k] = v;
+  }
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, TURNS_FILENAME),
+                   JSON.stringify(record) + "\n", "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Record which conversation this turn belongs to. Idempotent, never throws. */
+export function recordConversationId(dir, conversationId) {
+  const exact = productionIdentifier(conversationId);
+  if (exact === null) return false;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, CONVERSATION_ID_FILENAME),
+                  exact, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Persist one caller-authored task/case correlation without relabelling a
+ * mixed turn. This is neutral evidence only; it grants no training meaning.
+ */
+export function recordTaskId(dir, taskId) {
+  const exact = productionIdentifier(taskId);
+  if (exact === null) return false;
+  const sidecar = join(dir, TASK_ID_FILENAME);
+  const conflict = join(dir, TASK_ID_CONFLICT_FILENAME);
+  try {
+    mkdirSync(dir, { recursive: true });
+    if (existsSync(conflict)) return false;
+    try {
+      writeFileSync(sidecar, exact, { encoding: "utf8", flag: "wx" });
+      return true;
+    } catch (err) {
+      if (err?.code !== "EEXIST") return false;
+    }
+    let current = null;
+    try {
+      current = readFileSync(sidecar, "utf8");
+    } catch {
+      current = null;
+    }
+    if (current === exact) return true;
+    try {
+      writeFileSync(conflict, "", { encoding: "utf8", flag: "wx" });
+    } catch (err) {
+      if (err?.code !== "EEXIST") return false;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+/**
+ * Persist an SDK-reconciled identity without letting a second writer relabel
+ * a mixed turn. A conflict marker is monotonic and makes every reader abstain.
+ */
+export function recordExecutionFingerprint(dir, fingerprint) {
+  const digest = fingerprint?.execution_sha256;
+  if (!isLowerSha256(digest)) return false;
+  const expected = { execution_sha256: digest };
+  const sidecar = join(dir, AGENT_FINGERPRINT_FILENAME);
+  const conflict = join(dir, AGENT_FINGERPRINT_CONFLICT_FILENAME);
+  try {
+    mkdirSync(dir, { recursive: true });
+    if (existsSync(conflict)) return false;
+    try {
+      writeFileSync(sidecar, JSON.stringify(expected), { encoding: "utf8", flag: "wx" });
+      return true;
+    } catch (err) {
+      if (err?.code !== "EEXIST") return false;
+    }
+    let current = null;
+    try {
+      current = JSON.parse(readFileSync(sidecar, "utf8"));
+    } catch {
+      current = null;
+    }
+    if (
+      current && typeof current === "object" && !Array.isArray(current)
+      && Object.keys(current).length === 1
+      && current.execution_sha256 === digest
+    ) return true;
+    try {
+      writeFileSync(conflict, "", { encoding: "utf8", flag: "wx" });
+    } catch (err) {
+      if (err?.code !== "EEXIST") return false;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+/** Permanently invalidate a turn whose observations disagree. */
+export function recordExecutionFingerprintConflict(dir) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    try {
+      writeFileSync(join(dir, AGENT_FINGERPRINT_CONFLICT_FILENAME), "", {
+        encoding: "utf8", flag: "wx",
+      });
+    } catch (err) {
+      if (err?.code !== "EEXIST") return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Read only the exact sidecar shape this SDK authors. */
+export function readExecutionFingerprint(dir) {
+  const conflict = join(dir, AGENT_FINGERPRINT_CONFLICT_FILENAME);
+  if (existsSync(conflict)) return null;
+  let value;
+  try {
+    value = JSON.parse(readFileSync(join(dir, AGENT_FINGERPRINT_FILENAME), "utf8"));
+  } catch {
+    return null;
+  }
+  if (
+    !value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).length !== 1
+    || !isLowerSha256(value.execution_sha256)
+    || existsSync(conflict)
+  ) return null;
+  return { execution_sha256: value.execution_sha256 };
+}
+
+/** The conversation this turn declared, or `null`. */
+export function readConversationId(dir) {
+  try {
+    const raw = readFileSync(join(dir, CONVERSATION_ID_FILENAME), "utf8");
+    return productionIdentifier(raw) === raw ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read an exact, non-conflicting task binding, or null. */
+export function readTaskId(dir) {
+  const conflict = join(dir, TASK_ID_CONFLICT_FILENAME);
+  if (existsSync(conflict)) return null;
+  let raw;
+  try {
+    raw = readFileSync(join(dir, TASK_ID_FILENAME), "utf8");
+  } catch {
+    return null;
+  }
+  return productionIdentifier(raw) === raw && !existsSync(conflict) ? raw : null;
+}
+
+/**
+ * The turn's task and answer, or `null` when nothing was recorded.
+ *
+ * THE LAST RECORD OF EACH KIND WINS, matching Python. A turn that was answered
+ * twice -- a retry, a correction -- ends with the answer that was actually
+ * returned, not the one that was superseded.
+ *
+ * `null` (no file) is not the same as `{}` (a file recording neither half),
+ * and neither is collapsed, for the same reason the tool-call tri-state is
+ * not.
+ */
+export function readTurnText(dir) {
+  let raw;
+  try {
+    raw = readFileSync(join(dir, TURNS_FILENAME), "utf8");
+  } catch {
+    return null;
+  }
+  const out = {};
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const rec = JSON.parse(line);
+      if (TURN_KINDS.includes(rec?.kind) && typeof rec.text === "string") {
+        out[rec.kind] = rec.text;
+      }
+    } catch {
+      // A truncated final write costs that record and nothing else -- the same
+      // per-line recovery the tool-call reader does.
+    }
+  }
+  return out;
+}
+
+/**
+ * One captured turn in the intake's wire shape, or `null` if it is empty.
+ *
+ * TURN-NATIVE, NOT CORPUS-SHAPED. What crosses the boundary is what the agent
+ * observed -- the user's message, the answer, the calls. Projecting into a
+ * training-row format happens on the control plane's side, where it can change
+ * without a customer redeploying.
+ *
+ * THE TOOL-CALL TRI-STATE is asked of the FILE, not of whether this plugin
+ * happens to be recording. Python had a bug here worth not repeating: it
+ * answered `[] if adapters_bound else None`, which reports on whether capture
+ * was configured at attach time and says nothing about whether THIS turn
+ * recorded anything -- so a turn whose trajectory was never written went up as
+ * a positive assertion that the agent made zero calls. An observation nobody
+ * made.
+ *
+ *   rows present            -> the calls
+ *   file present, no rows   -> []    (it ran and called nothing)
+ *   file absent             -> null  (nothing was recorded for it)
+ */
+export function turnWire(dir, { turnIndex = 0 } = {}) {
+  const turnId = productionTurnIdentifier(basename(dir));
+  if (turnId === null) {
+    throw new ContractError(
+      "captured turn id is not representable on the flywheel/1 wire",
+    );
+  }
+  const text = readTurnText(dir) || {};
+  const { calls, malformed } = readTrajectory(dir);
+  const answer = text.answer ?? null;
+  const task = text.task ?? null;
+  const taskId = readTaskId(dir);
+
+  let toolCalls;
+  if (calls && calls.length) toolCalls = calls;
+  else if (existsSync(join(dir, TOOL_CALLS_FILENAME))) toolCalls = [];
+  else toolCalls = null;
+
+  if (!task && !answer && !(toolCalls && toolCalls.length) && !taskId) return null;
+
+  const wire = {
+    // `basename`, not `split("/")`. The turn id is the DIRECTORY NAME, and on
+    // win32 `join` builds paths with `\`, so splitting on a hardcoded "/"
+    // returned the whole absolute path: an operator's home directory went onto
+    // the wire as the turn id, and it could never match the bare `d.name` that
+    // `createTurnUploader` writes into `.uploaded` -- so no turn was ever
+    // considered uploaded and every flush re-sent the entire capture root.
+    turn_id: turnId,
+    input_text: task,
+    final_text: answer,
+    tool_calls: toolCalls,
+    tool_calls_omitted_count: malformed,
+  };
+  const cid = readConversationId(dir);
+  if (cid) {
+    wire.conversation_id = cid;
+    wire.turn_index = turnIndex;
+  }
+  if (taskId) wire.task_id = taskId;
+  const fingerprint = readExecutionFingerprint(dir);
+  if (fingerprint !== null) wire.agent_fingerprint = fingerprint;
+  return wire;
+}
+
+/**
+ * Every turn directory under `root`, oldest first.
+ *
+ * ORDERED BY MTIME, which is the ordering Python derives `turn_index` from.
+ * Both ends must agree, because the control plane indexes on
+ * `(org, agent, conversation_id, turn_index)` and a conversation whose turns
+ * all claim index 0 cannot be ordered at all.
+ */
+export function listTurnDirs(root) {
+  let names;
+  try {
+    names = readdirSync(root);
+  } catch {
+    return [];
+  }
+  const dirs = [];
+  for (const name of names) {
+    const path = join(root, name);
+    try {
+      const st = statSync(path);
+      if (st.isDirectory()) dirs.push({ path, name, mtime: st.mtimeMs });
+    } catch {
+      // Vanished between listing and stat: a concurrent prune. Not an error.
+    }
+  }
+  dirs.sort((a, b) => a.mtime - b.mtime || a.name.localeCompare(b.name));
+  return dirs;
+}
+
+/**
+ * This turn's position within its conversation.
+ *
+ * Computed over every turn of that conversation ON DISK, not just the ones
+ * being uploaded now, so a turn sent in a later batch keeps the position it
+ * actually had. A counter held in memory would restart at zero on every
+ * process restart -- and every turn landing at index 0 is precisely what the
+ * control plane's index exists to prevent.
+ */
+export function turnIndexOf(root, dirName, conversationId) {
+  if (!conversationId) return 0;
+  const siblings = listTurnDirs(root)
+    .filter((d) => readConversationId(d.path) === conversationId);
+  const i = siblings.findIndex((d) => d.name === dirName);
+  return i < 0 ? 0 : i;
+}

package/src/unattended.js

@@ -0,0 +1,251 @@
+/**
+ * UNATTENDED ROLLOUTS: the plugin starts the turn itself.
+ *
+ * WHAT TRAINING MODE DOES. There is no switch of its own here, and there were
+ * two wrong answers before this one.
+ *
+ * First it was opt-in, on the argument that this reaches past a restriction
+ * the host states for its own scheduling API. That treated "the plugin runs
+ * the rollout" as something beyond what was asked for, and it is not:
+ * `PERCEPTEYE_AGENT_MODE=training` already means "this install claims rollouts
+ * and runs them", and in that mode the plugin already claims work and puts
+ * tasks into the agent's context. Starting the turn is how that promise is
+ * kept, so opt-in only meant the flywheel sat idle waiting to be enabled.
+ *
+ * Then it was default-on with its own kill switch, which was the same mistake
+ * one step smaller: `PERCEPTEYE_AGENT_MODE` already answers "does this install
+ * drive?", so a second flag was a second answer to a settled question. The one
+ * state it could have named -- claim rollouts but wait for a human to start
+ * each turn -- has no customer behind it. An operator who wants the agent left
+ * alone sets `production`, and gets a stronger guarantee than a flag: this
+ * module is never even reached.
+ *
+ * The real risk is handled below by DEGRADING, not by a switch: a flag never
+ * made the host seam more stable, it only meant somebody had to know about it.
+ *
+ * ── WHAT IT REACHES PAST, AND WHY THAT IS SURVIVABLE ──────────────────────
+ *
+ * OpenClaw's documented API for starting a turn from a plugin,
+ * `api.session.workflow.scheduleSessionTurn`, is restricted to plugins bundled
+ * with the host: `schedulePluginSessionTurn` returns immediately for any other
+ * origin (registry-B8eQDFB4.js:1186), silently.
+ *
+ * The capability underneath is not restricted. `gateway_start` and
+ * `cron_changed` hand every plugin the raw host cron service as
+ * `ctx.getCron()` (server-startup-post-attach-B3O9knW5.js:765,
+ * server-cron-Cwg2hJro.js:4384); `registerTypedHook` gates conversation hooks
+ * by origin and prompt-injection hooks by policy, and `gateway_start` is in
+ * neither set; and `server-cron` carries no origin check at all. A job with
+ * `payload.kind: "agentTurn"` reaches `runIsolatedAgentJob` (:2433) and
+ * `runCronIsolatedAgentTurn` (:4484), which runs the agent. The job built
+ * below is deliberately the same shape the bundled-only wrapper builds
+ * (registry-B8eQDFB4.js:1240-1254).
+ *
+ * So this reaches past a restriction the host states explicitly, by way of a
+ * service it hands out elsewhere. That may be an inconsistency rather than an
+ * intention, which means it can be closed in a patch release. Two consequences
+ * are designed in rather than discovered later:
+ *
+ *   1. It is confined to TRAINING mode, structurally. A process serving real
+ *      users never reaches this module, whatever the setting says.
+ *   2. It DEGRADES to the default lane instead of failing. If `getCron()`
+ *      returns nothing -- the seam closed, or cron is simply unavailable --
+ *      the plugin says so once, STOPS POLLING, and leaves the `session_start`
+ *      injection lane as the only claimer. A capability that disappears must
+ *      not take rollouts down with it.
+ *
+ *      STOPPING IS THE WHOLE OF THE DEGRADATION, and the first version of it
+ *      left that part out: it announced the fallback, handed the rollout
+ *      back, and then polled again `pollMs` later, forever. Mission Control's
+ *      `claim` increments `attempt`, and its `abandon` requeues only while
+ *      `attempt < max_attempts` -- so a runner that claims and hands back
+ *      every 30 seconds walks the whole org's queue to ABANDONED at three
+ *      attempts each, having run none of it, while reporting itself as having
+ *      fallen back. A seam that is gone must make this lane QUIET, not busy.
+ *
+ *      `start()` is the one thing that undoes it, because its only callers
+ *      are `gateway_start` and `cron_changed` and both mean the host has just
+ *      handed over a cron context. That keeps a LATER-ARRIVING cron usable
+ *      (see `cronTurnStarter` below) without reopening the churn: a host with
+ *      no cron service emits neither event, so nothing restarts the loop.
+ *
+ * ── ONE ROLLOUT AT A TIME, IN ITS OWN SESSION ─────────────────────────────
+ *
+ * Each rollout runs under `percepteye-rollout-<id>`, never a session a person
+ * is using. Commandeering a human's session to run training work would be
+ * indefensible, and an isolated session is also what makes `agent_end`
+ * attributable: the key the turn runs under is the key the report is looked up
+ * by.
+ *
+ * Serial by construction -- the runner claims only when nothing is in flight.
+ * A concurrency knob would be the second thing to get wrong here, and a
+ * customer's gateway is not the place to discover that.
+ */
+import { taskText } from "./rollout.js";
+
+export const JOB_PREFIX = "percepteye:rollout:";
+
+/** How often to look for work when idle. */
+export const DEFAULT_POLL_MS = 30_000;
+
+/**
+ * Turn the raw cron service into "start a turn", or say why it cannot.
+ *
+ * `getCron` is a FUNCTION, not a service, because the context that carries it
+ * only exists during `gateway_start`/`cron_changed` and the service may not be
+ * up yet at that moment -- the bundled memory-core plugin has the same problem
+ * and defers the same way. Resolving it per call keeps a later-arriving cron
+ * usable instead of caching an `undefined` forever.
+ */
+export function cronTurnStarter(getCron) {
+  return async function startTurn({ sessionKey, message, rolloutId }) {
+    const cron = typeof getCron === "function" ? getCron() : null;
+    if (!cron || typeof cron.add !== "function") {
+      return {
+        started: false,
+        degraded: true,
+        reason:
+          "the host cron service is unavailable to this plugin, so no turn " +
+          "can be started",
+      };
+    }
+    try {
+      await cron.add({
+        name: `${JOB_PREFIX}${rolloutId}`,
+        // Idempotent per rollout: a retried claim of the same work cannot
+        // queue a second turn for it.
+        declarationKey: `${JOB_PREFIX}${rolloutId}`,
+        enabled: true,
+        // One-shot, effectively now. `at` is what the host's own wrapper uses
+        // for a `delayMs`, clamped to at least 1ms.
+        schedule: { kind: "at", at: new Date(Date.now() + 1).toISOString() },
+        sessionTarget: `session:${sessionKey}`,
+        payload: { kind: "agentTurn", message },
+        deleteAfterRun: true,
+        wakeMode: "now",
+        // NOT "announce". Announcing would deliver the rollout's output into
+        // whatever chat the customer last used, which is training work
+        // appearing in a human's conversation.
+        delivery: { mode: "none" },
+      });
+      return { started: true, degraded: false, reason: null };
+    } catch (err) {
+      return {
+        started: false,
+        // NOT degraded: cron answered and refused. Falling back to the
+        // injection lane on a genuine rejection would hide a real error behind
+        // a quieter mode.
+        degraded: false,
+        reason: `the host refused the rollout turn: ${err?.message ?? err}`,
+      };
+    }
+  };
+}
+
+/** The session a rollout runs in. Never a session a person is using. */
+export const sessionKeyFor = (rolloutId) => `percepteye-rollout-${rolloutId}`;
+
+/**
+ * Claim, start, and keep going -- one rollout at a time.
+ *
+ * `driver` is the same one the attended lane uses, so reporting and typed
+ * abandon happen in exactly one place for both lanes.
+ */
+export function createUnattendedRunner({
+  transport, driver, startTurn, logger = null, pollMs = DEFAULT_POLL_MS,
+}) {
+  let timer = null;
+  let running = false;
+  /**
+   * The turn-starting seam is gone, so this lane claims nothing.
+   *
+   * ONE FLAG, NOT TWO. It used to be `degradedAnnounced`, gating only the
+   * warning, which meant the loop went on claiming and handing back -- see the
+   * header. "Have we said it" and "should we still claim" are the same
+   * question here: the announcement IS the fallback taking effect.
+   */
+  let degraded = false;
+
+  function stopTimer() {
+    if (timer) clearInterval(timer);
+    timer = null;
+  }
+
+  async function tick() {
+    // Never claim once the seam is known dead: a claim we cannot start still
+    // costs the rollout an attempt, and three of those retire it unrun.
+    // Checked HERE rather than in `start()` alone, so a directly driven tick
+    // cannot walk around it either.
+    if (degraded || running || driver.inFlight.size > 0) return null;
+    running = true;
+    try {
+      let claimed;
+      try {
+        claimed = await transport.claim(1);
+      } catch (err) {
+        logger?.warn?.(
+          `[agent-flywheel] could not claim a rollout: ${err?.message ?? err}`);
+        return null;
+      }
+      const rollout = claimed?.rollouts?.[0];
+      if (!rollout) return null;
+
+      const sessionKey = sessionKeyFor(rollout.rolloutId);
+      driver.track(sessionKey, rollout);
+
+      const result = await startTurn({
+        sessionKey, rolloutId: rollout.rolloutId, message: taskText(rollout),
+      });
+      if (result.started) {
+        logger?.info?.(
+          `[agent-flywheel] rollout ${rollout.rolloutId} started unattended in ` +
+          `session ${sessionKey}.`);
+        return rollout;
+      }
+
+      // The turn will never run, so the work goes back NOW rather than sitting
+      // until its lease lapses.
+      await driver.giveBack(
+        sessionKey, rollout, "entrypoint_error", result.reason);
+      if (result.degraded) {
+        degraded = true;
+        // The fallback, actually taken: stop looking for work. Anything else
+        // spends one rollout's attempt per poll on a turn that cannot start.
+        stopTimer();
+        logger?.warn?.(
+          `[agent-flywheel] unattended rollouts are configured but ${result.reason}. ` +
+          `Falling back to the default lane: this plugin has stopped polling ` +
+          `for rollouts and tasks are delivered into the next turn you start. ` +
+          `Nothing else changes.`);
+      }
+      return null;
+    } finally {
+      running = false;
+    }
+  }
+
+  return {
+    tick,
+    /**
+     * Is this lane still looking for work?
+     *
+     * The observable half of the degradation. `tick`'s own guard is what stops
+     * the claiming, and a test that only counts claims passes just as happily
+     * with `stopTimer()` deleted -- leaving a poll interval waking every 30
+     * seconds forever to return immediately, in a customer's gateway, in a
+     * lane the operator was told had gone quiet.
+     */
+    get polling() { return timer !== null; },
+    start() {
+      // Only `gateway_start` and `cron_changed` call this, and both mean the
+      // host has just handed over a cron context -- the one event that can
+      // undo a degradation, and the only thing that restarts the loop.
+      degraded = false;
+      if (timer) return;
+      timer = setInterval(() => { tick().catch(() => {}); }, pollMs);
+      // Never hold a customer's gateway open on our account.
+      timer.unref?.();
+    },
+    stop: stopTimer,
+  };
+}