@open-everywhere/core 0.1.0

package/agent/routines/permission-review.ts

@@ -0,0 +1,318 @@
+// THE ROUTINE PERMISSION REVIEW SURFACE (OPE-1290, PR 3 of 3) — the after-the-fact record.
+//
+// WHAT THIS FILE ANSWERS. "What did my routines ask for while I was away?" A permission card is a
+// post, and a post is buried by traffic: a card raised by a 03:00 fire can be 400 messages up the
+// thread by the time its owner reads the room. The card is still live and still clickable, but
+// nobody can find it. This file rebuilds that question from the ROWS instead of from the thread, so
+// `list_routines` can answer it whenever it is asked, however long after the fire.
+//
+// 🔴 IT READS. IT DECIDES NOTHING. No card is posted here, no grant is written, no memo is touched,
+// no row is expired. Arming still happens exactly where it happened before — a human's click on the
+// permission card, or a declaration on a creation/edit card — and this record only says which of
+// those doors is open and where it is. A surface that could arm a permission would be a second
+// decision mechanism on a plane whose whole design rests on there being one.
+//
+// 🔴 IT IS SCOPED BY THE ROUTINES IT IS GIVEN, NEVER BY THE CARD ROWS. `listPendingActions` is
+// ORG-wide, and `list_routines` is (org, surfaceKey)-scoped. So the join runs from each supplied
+// routine to its own cards — never from the card list outward — and a card belonging to a routine on
+// another surface is invisible here, exactly as that routine itself is. Reversing the direction of
+// this join is how a listing tool starts reporting another room's business.
+//
+// WHY THE ARMED SET COMES BACK FROM HERE TOO. Both answers are derived from ONE read of the
+// routine's permission key: the rows under that key are the declared permissions AND the card's two
+// markers. Calling `declared-permissions.ts` `listRoutinePermissions` beside this would read the
+// same rows a second time per routine on a listing path. The marker/permission split is not
+// re-implemented — it is
+// `isRoutinePermissionMemoKind`, the same predicate `routines/declared-permissions.ts` filters on, so the two
+// readers cannot drift about which row is a permission. `routinePermissionMemoParts` then says which
+// marker it is, which only this reader needs.
+
+import { getOperationalStore } from "../operational/provider.js";
+import type { PendingActionRow } from "../approvals/types.js";
+import { ROUTINE_PERMISSION_KIND, type RoutinePermissionArgs } from "../approvals/routine-permission.js";
+import {
+  declarationForPermissionKind,
+  describeDeclaredPermissionKind,
+  isRoutinePermissionMemoKind,
+  routinePermissionMemoParts,
+} from "../approvals/session-grant.js";
+import { routinePermissionKey, routineReportSurfaceKey, type Routine } from "./routine.js";
+import { routinePermissionKeyParts } from "./permission-key.js";
+
+/** The routine a review reads — id and generation make the key, the report surface names the room. */
+type ReviewedRoutine = Pick<Routine, "id" | "promptGeneration" | "surfaceKey" | "report">;
+
+/**
+ * What became of one permission a routine asked for. Every arm is derived from a row that exists,
+ * or — for `unreadable` — from a read that failed and says so.
+ *
+ * The arms are kept apart because a person acting on this record does something DIFFERENT in each,
+ * and because each is easy to state as another one and be wrong. 🔴 EVERY CONSUMER MUST HANDLE THEM
+ * ALL: `list_routines`'s zod enum is one such site, and a switch that omits an arm reports a state
+ * as something it is not. Count the arms below rather than a number in this sentence.
+ */
+export type RoutinePermissionAskState =
+  /** A card for it is pending in the routine's room right now. Clicking it arms every future fire. */
+  | "waiting"
+  /** A person declined it. Future fires refuse quietly and post no card, until the instruction is
+   *  edited. */
+  | "declined"
+  /** A card was posted under an EARLIER instruction and is still in the room. Its click-time
+   *  re-check refuses now, so answering it records nothing either way (OPE-1339 reaps it). */
+  | "superseded"
+  /**
+   * The routine asked, and no row records an answer: no card is pending, no permission was written,
+   * no decline was remembered.
+   *
+   * 🔴 IT IS A REAL STATE, NOT A GAP IN THE READ — and {@link RoutinePermissionAskState.unreadable}
+   * is what keeps that true. The ask marker is written when the card posts and outlives the card's
+   * row, so this is what a card ANSWERED WITHOUT ANYTHING STICKING looks like — an approve whose
+   * grant write failed, or a decline whose memo write failed (both are best-effort by design).
+   *
+   * Since OPE-1359 a later fire reads the card row before believing the marker, so it posts a FRESH
+   * card rather than pointing at the one that is gone. This state is what a reader sees between
+   * those two fires, and it still names the thing to fix.
+   */
+  | "lapsed"
+  /**
+   * The routine asked, and the card store could not be read, so what became of the card is unknown.
+   *
+   * 🔴 WITHOUT THIS ARM A STORE BLIP READS AS `lapsed`, WHICH IS A LIE. `lapsed` asserts an absence
+   * — no card is pending — and a read that failed observed nothing at all. The card is very likely
+   * still sitting in the room, clickable, and telling its owner to edit the instruction instead
+   * would bump the generation and kill exactly that card. The same split the timed wait had to make
+   * between `deadline` and `unreadable`: any reader that swallows an error needs its empty answer to
+   * know whether the last look saw anything.
+   */
+  | "unreadable";
+
+/** One permission a routine asked for, and where its answer stands. */
+export interface RoutinePermissionAsk {
+  /** The permission in plain language — the same words `list_routines` uses for a live permission. */
+  readonly permission: string;
+  /** How `create_routine` / `edit_routine` spell it: `pr.open`, `tool:<qualified tool>`. Null for a
+   *  permission kind no declaration maps onto — a legacy row that lifts nothing. */
+  readonly declaration: string | null;
+  readonly state: RoutinePermissionAskState;
+  /** When the card was posted. Null when no card row survives to say. */
+  readonly askedAt: string | null;
+  /** The surface the card was posted to (`platform/workspace/channel`), or null when no card row
+   *  survives to say. */
+  readonly room: string | null;
+  /** What a person does next, through the door that is already open. */
+  readonly nextStep: string;
+}
+
+/** One routine's permission picture: what it MAY do, and what it ASKED to do and did not get. */
+export interface RoutinePermissionView {
+  /** The live standing grants, in plain language — never a card marker (see the header). */
+  readonly permissions: string[];
+  /** The asks, oldest card first, then the ones with no card row left. */
+  readonly asks: RoutinePermissionAsk[];
+  /**
+   * The PERMISSION read for this routine failed, so {@link permissions} and every marker-derived ask are
+   * unknown rather than absent (OPE-1360).
+   *
+   * 🔴 IT IS THE PERMISSION LEG'S {@link RoutinePermissionAskState.unreadable}, and it exists for the
+   * identical reason. An empty `permissions` asserts "this routine holds nothing"; a read that threw
+   * observed nothing at all, and the two produce opposite advice — the first says arm it, the second
+   * says look again before deciding. The card leg has said which of the two it means since it
+   * shipped; this leg swallowed the failure to `[]` and could not.
+   *
+   * WHY A PER-ROUTINE FLAG AND NOT A SIXTH ASK STATE. The failure is about the WHOLE routine — its
+   * grants and every marker on its key at once — not about one permission. A sixth ask state would
+   * have to be invented per permission the reader could not enumerate, which is a list it does not
+   * have.
+   */
+  readonly permissionsUnreadable: boolean;
+}
+
+/** Nothing known — the fail-soft answer, and the shape a caller with no rows gets. `false` is right
+ *  here: a caller that never asked for a routine's rows has not had a read FAIL. */
+export function emptyRoutinePermissionView(): RoutinePermissionView {
+  return { permissions: [], asks: [], permissionsUnreadable: false };
+}
+
+/**
+ * The permission picture for each supplied routine, keyed by routine id.
+ *
+ * ONE org-wide card read for the whole call, then one keyed permission read per routine — the same
+ * shape `list_routines` already uses for its forensics.
+ *
+ * Fails SOFT PER LEG rather than failing the listing, and THE TWO LEGS FAIL DIFFERENTLY.
+ *
+ * A failed CARD read is SAID: every ask it would have answered becomes `unreadable`, never
+ * `lapsed`, because `lapsed` asserts an absence that a failed read never observed.
+ *
+ * A failed PERMISSION read is SAID TOO (OPE-1360): the routine's {@link
+ * RoutinePermissionView.permissionsUnreadable} is set, its standing set is empty, and the two
+ * together mean "unknown" rather than "holds nothing". It still under-reports — no grant is
+ * invented, which is the direction that matters — but a reader can now tell an empty answer from a
+ * failed one.
+ */
+export async function readRoutinePermissionViews(
+  org: string,
+  routines: readonly ReviewedRoutine[],
+  nowIso: string,
+): Promise<Map<string, RoutinePermissionView>> {
+  const cards = await readRoutinePermissionCards(org);
+  const out = new Map<string, RoutinePermissionView>();
+  for (const routine of routines) out.set(routine.id, await readOneView(org, routine, nowIso, cards));
+  return out;
+}
+
+/**
+ * Every PENDING routine-permission card in the org, with its frozen args parsed — or UNDEFINED when
+ * the store could not be read.
+ *
+ * 🔴 UNDEFINED IS NOT AN EMPTY LIST, and collapsing the two is the bug this signature exists to
+ * prevent. "No card is pending" and "nobody looked" produce opposite advice: the first says the card
+ * is gone, the second leaves a clickable card in the room that an `edit_routine` would destroy.
+ */
+async function readRoutinePermissionCards(org: string): Promise<readonly ParsedCard[] | undefined> {
+  const rows = await getOperationalStore()
+    .listPendingActions(org)
+    .catch(() => undefined);
+  if (rows === undefined) return undefined;
+  const out: ParsedCard[] = [];
+  for (const row of rows) {
+    if (row.kind !== ROUTINE_PERMISSION_KIND) continue;
+    const args = parseArgs(row.argsJson);
+    if (args === undefined) continue;
+    out.push({ row, args });
+  }
+  return out;
+}
+
+interface ParsedCard {
+  readonly row: PendingActionRow;
+  readonly args: Pick<RoutinePermissionArgs, "grantKey" | "grantKind" | "declaration" | "routineId">;
+}
+
+/** The frozen args, or undefined when the row cannot supply the four fields the join needs. A row
+ *  this cannot read names no permission, so it is dropped rather than half-rendered. */
+function parseArgs(argsJson: string): ParsedCard["args"] | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(argsJson);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null) return undefined;
+  const a = parsed as Partial<RoutinePermissionArgs>;
+  if (typeof a.grantKey !== "string" || typeof a.grantKind !== "string") return undefined;
+  if (typeof a.declaration !== "string" || typeof a.routineId !== "string") return undefined;
+  return { grantKey: a.grantKey, grantKind: a.grantKind, declaration: a.declaration, routineId: a.routineId };
+}
+
+async function readOneView(
+  org: string,
+  routine: ReviewedRoutine,
+  nowIso: string,
+  cards: readonly ParsedCard[] | undefined,
+): Promise<RoutinePermissionView> {
+  const liveKey = routinePermissionKey(routine);
+  // 🔴 UNDEFINED IS NOT AN EMPTY LIST here either (OPE-1360) — the same signature the card read
+  // above uses, for the same reason. A failed grant read used to become `[]`, which renders as a
+  // routine that holds nothing and has asked for nothing: an assertion this look never earned.
+  const rows = await getOperationalStore()
+    .listSessionApprovals(org, liveKey, nowIso)
+    .catch(() => undefined);
+  const permissionsUnreadable = rows === undefined;
+
+  // ONE pass over the routine's rows. `isRoutinePermissionMemoKind` is what keeps a marker out of
+  // the armed set — a marker rendered as a permission would tell a human the routine may do
+  // something no row permits, which is the one direction this reader may never fail in.
+  const permissions: string[] = [];
+  const granted = new Set<string>();
+  const asked = new Set<string>();
+  const declined = new Set<string>();
+  for (const row of rows ?? []) {
+    if (!isRoutinePermissionMemoKind(row.kind)) {
+      granted.add(row.kind);
+      permissions.push(describeDeclaredPermissionKind(row.kind));
+      continue;
+    }
+    const parts = routinePermissionMemoParts(row.kind);
+    if (parts === undefined) continue;
+    (parts.marker === "asked" ? asked : declined).add(parts.grantKind);
+  }
+
+  // The cards this routine owns, split by whether they can still arm anything. A card is only ever
+  // matched to the routine it names — never to the surface it sits on, which can be a report
+  // destination shared with other routines.
+  const live = new Map<string, ParsedCard>();
+  const superseded = new Map<string, ParsedCard>();
+  for (const card of cards ?? []) {
+    const parts = routinePermissionKeyParts(card.args.grantKey);
+    if (parts === undefined || parts.routineId !== routine.id) continue;
+    const bucket = card.args.grantKey === liveKey ? live : superseded;
+    // First card wins per permission: `listPendingActions` returns oldest first, and the oldest is
+    // the one every later refusal has been pointing at.
+    if (!bucket.has(card.args.grantKind)) bucket.set(card.args.grantKind, card);
+  }
+
+  const asks: RoutinePermissionAsk[] = [];
+  const seen = new Set<string>();
+  const push = (grantKind: string, state: RoutinePermissionAskState, card: ParsedCard | undefined): void => {
+    if (seen.has(grantKind)) return;
+    seen.add(grantKind);
+    asks.push({
+      permission: describeDeclaredPermissionKind(grantKind),
+      declaration: card?.args.declaration ?? declarationForPermissionKind(grantKind) ?? null,
+      state,
+      askedAt: card?.row.createdAt ?? null,
+      room: card?.row.postedTo ?? null,
+      nextStep: nextStepFor(state, card?.row.postedTo ?? routineReportSurfaceKey(routine)),
+    });
+  };
+
+  // 🔴 THE ORDER OF THESE FIVE LOOPS IS THE PRECEDENCE. An ARMED permission is no longer an ask at
+  // all — the row that lifts the gate exists, the permission is in `permissions`, and repeating it
+  // here would tell a reader the routine is still waiting for something it already has. So the
+  // granted kinds are marked seen and never pushed, and they outrank every marker on the key. After
+  // that the order is the planner's own (routines/permission-card.ts): a DECLINE answers the
+  // standing question for this generation whatever else sits on the key, a LIVE card outranks the
+  // bare ask marker that raised it, and the marker is what is left when no card row survives.
+  for (const grantKind of granted) seen.add(grantKind);
+  for (const grantKind of declined) push(grantKind, "declined", undefined);
+  for (const [grantKind, card] of live) push(grantKind, "waiting", card);
+  // 🔴 THE ONE PLACE THE CARD READ'S FAILURE IS ALLOWED TO SHOW. A marker with no card row behind it
+  // means the card was answered and nothing stuck — but ONLY if a look actually happened. When the
+  // card read failed there was no look, so the same marker says nothing more than "this was asked".
+  for (const grantKind of asked) push(grantKind, cards === undefined ? "unreadable" : "lapsed", undefined);
+  for (const [grantKind, card] of superseded) push(grantKind, "superseded", card);
+
+  // Sorted by how close the entry is to an action a reader can take: the live card first, because
+  // one click arms it; then `unreadable`, which asks for a look in the room and explicitly not for
+  // an edit; then the two states an `edit_routine` resolves; then the answered one. Ties keep the
+  // oldest ask first.
+  asks.sort((a, b) => STATE_ORDER[a.state] - STATE_ORDER[b.state] || (a.askedAt ?? "").localeCompare(b.askedAt ?? ""));
+  return { permissions, asks, permissionsUnreadable };
+}
+
+const STATE_ORDER: Record<RoutinePermissionAskState, number> = { waiting: 0, unreadable: 1, superseded: 2, lapsed: 3, declined: 4 };
+
+/**
+ * The one sentence that makes this record actionable — and it names only doors that are already
+ * open. Nothing here is a new way to decide a permission; each arm points at the card, the
+ * instruction, or the next fire.
+ */
+function nextStepFor(state: RoutinePermissionAskState, room: string): string {
+  switch (state) {
+    case "waiting":
+      return `Approve or decline the permission card waiting in ${room} — approving it arms every future run of this instruction.`;
+    case "declined":
+      return "Nothing is waiting: the routine stops asking until its instruction is edited. Editing it with `edit_routine` re-opens the question, and declaring the permission on that edit arms it outright.";
+    case "superseded":
+      return `The card in ${room} was posted under an earlier instruction, so answering it records nothing. The next run that needs the permission posts a fresh card.`;
+    case "lapsed":
+      // The copy changed with OPE-1359: a later run now READS the card row before believing the ask
+      // marker, so it posts a fresh card rather than reporting a card that is gone as waiting.
+      return `No card is waiting and nothing was recorded. The next run that needs the permission posts a fresh card in ${room}. Declare the permission with \`edit_routine\` to arm it outright, which also resets the ask.`;
+    case "unreadable":
+      // It says what was NOT established, and it does not send the reader to `edit_routine`: that
+      // bumps the generation, and a card this read failed to see would die on the way.
+      return `This routine asked for it, and the card store could not be read — so whether a card is still waiting in ${room} is unknown. Look there before deciding anything, and ask again once the store answers.`;
+  }
+}

package/agent/routines/policy.ts

@@ -0,0 +1,304 @@
+// PER-ROUTINE POLICY — the standing rules a routine accumulates, rendered into every one of its
+// fires as a TRUSTED block (OPE-141). The doctrine analogue of job.ts's progress ledger: where
+// `jobState` carries WHERE YOU GOT TO, this carries WHAT YOU MUST ALWAYS DO. Framework-free (no
+// eve / zod imports), like routine.ts / watch.ts / job.ts, so the store, the tools, the renderers
+// and the tests all share it without pulling the runtime.
+//
+// WHY IT EXISTS. A routine's prompt is written once, before anyone has seen it run. The first time
+// it does something wrong at 03:00 there is nowhere for "don't do that again" to live:
+//
+//   • a STATELESS routine (every kind except `sessionMode:"job"`) starts a FRESH session per fire.
+//     It forgets everything. Its only correction channel was `edit_routine` — rewriting the whole
+//     instruction, which revokes every standing grant and rotates a job's seat, for one clause;
+//   • a DURABLE JOB has two channels already (a live session a human can talk to, and its ledger),
+//     so it needs this LEAST. Which is exactly why policy is available to ALL routines rather than
+//     to jobs: restricting it to `job:true` would put it where it is least needed.
+//
+// 🔴 WHY THIS IS A SECOND BLOCK AND NOT PART OF `jobState`. The reason is governance, not layout,
+// and it is the whole design:
+//
+//   | | `jobState` (job.ts) | `policy` (here) |
+//   |---|---|---|
+//   | authored by | the MODEL, every fire | a human, by clicking a card |
+//   | gate | none — an ungated per-fire write is what makes jobs work | `routine.policy.add`, member tier |
+//   | shape | wholly rewritten each time | append-mostly, per-rule provenance |
+//   | taint | monotonically suspect (`jobTainted`), re-framed as data | `taint: "gate"` — a tainted turn is floored at a human decision, and denied unattended |
+//   | renders | trusted UNTIL tainted, then as a report | trusted, always |
+//
+// Unify them and you must either put the approval gate on the ledger (killing the ungated per-fire
+// write jobs depend on) or take the gate off the policy (which is precisely the injection hole).
+// Opposite governance ⇒ separate fields, separate blocks, separate write paths. Nothing in this
+// module is reachable from `record_job_state`, and nothing in job.ts can write `policy`.
+//
+// 🔴 WHAT BUYS THE RIGHT TO RENDER THE BLOCK AS TRUSTED. A rule is the only text in this system
+// injected as a TRUSTED INSTRUCTION into UNATTENDED fires FOREVER — strictly stronger than
+// `remember` (which renders into a conversation someone is in) and than the job ledger (which stops
+// being trusted the moment its taint flag rises). Four mechanical gates, none of them sufficient
+// alone (tools/add_routine_rule.ts states each one against its code):
+//
+//   1. a ROUTINE FIRE may not author a rule — the host-set, model-unforgeable `ROUTINE_MARKER`
+//      stamp is a hard refusal AT THE TOOL, so no autonomous run can amend its own doctrine;
+//   2. a TAINTED turn may not AUTO-APPROVE a rule — both tools declare `taint: "gate"`, so the
+//      approver chain floors the verdict at `ask` and the `unattended` arrow denies it when nobody
+//      is watching. 🔴 ENFORCED IN THE CHAIN, not in this module (OPE-438). It used to be a hard
+//      refusal here; a card a human reads — carrying what the turn ingested — replaced it, because a
+//      refusal a tainted turn cannot pass is a control people switch off;
+//   3. neither tool is in `JOB_WAKE_TOOLS`, so a restricted job wake does not hold them at all;
+//   4. the approval card freezes the exact text and needs a verified clicker.
+//
+// Gate 3 is belt to gate 1's braces (a job wake is a fire), and gate 1 is belt to gate 2's (a
+// tainted job fire re-seeds the taint signal from `jobTainted`, hooks/job-posture.ts — and a fire is
+// unattended, so gate 2 lands on deny there). They are deliberately redundant: this block's whole
+// value is that a fire may obey it without thinking, and that is only earned if authorship is
+// impossible from inside a fire by more than one mechanism.
+//
+// WHERE THE TEXT DURABLY LIVES, and why NOT `routine_prompt_revisions` (OPE-242). That log's
+// contract is "the exact PROMPT, byte-for-byte as the routine held it", indexed by the
+// `promptGeneration` a `routinePermissionKey()` embeds. A rule is not the prompt and a rule change
+// deliberately does NOT bump the generation — bumping it would revoke every standing grant and
+// rotate a durable job's seat every time someone added "don't post before 9am", which would make
+// the feature unusable. Writing rules into that table would make its one text column mean two
+// things and would break its generation join (many rows, one generation, texts the routine never
+// ran under). So a rule's two durable homes are the card's frozen `pending_actions.args_json` and
+// the `routine.policy.add` / `routine.policy.remove` audit rows, which carry the rule VERBATIM —
+// the same two-homes shape `routine.edit` has, with the audit row playing the log's part because a
+// rule is one capped line rather than a document. `remove` freezes the text it is destroying at
+// PROPOSE time for exactly the reason OPE-242 exists: the patch deletes the only live copy.
+
+import type { Routine } from "./routine.js";
+
+/** One standing rule. Every field except {@link incidentRunAt} is required — see the module header
+ *  on `why`, which is the capture-reasoning doctrine made structural rather than encouraged. */
+export interface RoutinePolicyRule {
+  /** `p-<8hex>` — the handle a human names in the channel to remove it. */
+  readonly id: string;
+  /** The imperative, one line. Rendered trusted into every fire. */
+  readonly rule: string;
+  /**
+   * WHY the rule exists — the incident or reasoning behind it. REQUIRED, and the requirement is
+   * structural rather than a nicety: a rule set is read months later by someone deciding whether a
+   * rule still applies, and a bare imperative with no cause cannot be retired safely (the
+   * `capture-reasoning` failure mode — a conclusion outliving the inputs that justified it).
+   * It also renders INTO the fire, so the model can tell an absolute from a stale mitigation.
+   */
+  readonly why: string;
+  readonly addedAt: string; // ISO
+  /** The principal who CLICKED the card. Never the model, never the requester — the whole point of
+   *  the gate is that arming is an act of a verified human. */
+  readonly addedBy: string;
+  /**
+   * Who authored the TEXT. A DISCLOSURE, never a control: both values pass the identical gates, and
+   * a model that mislabels `learned` as `human` gains nothing mechanically. It is on the card and in
+   * the block because "the agent proposed this about itself" is a thing a clicker should see, not
+   * because anything branches on it.
+   */
+  readonly source: "human" | "learned";
+  /** `lastRunAt` of the fire that provoked the rule, when there was one. */
+  readonly incidentRunAt?: string;
+}
+
+/**
+ * Hard cap on the rule set. REFUSED at the cap, never auto-evicted — auto-eviction silently deletes
+ * a guardrail, which is the exact act `cancel_routine`, `delete_skill` and `remove_routine_rule` are
+ * all gated against, and doing it invisibly on someone else's add would be worse than doing it on a
+ * card. The cap exists because this block is re-rendered into EVERY fire forever: its token cost is
+ * permanent and per-fire, so forcing a human to prune is a feature rather than a limitation.
+ */
+export const POLICY_MAX_RULES = 20;
+
+/** Per-field character caps. A rule is an imperative, not a document — and both strings are
+ *  re-rendered on every fire of every routine, forever. */
+export const POLICY_RULE_MAX_CHARS = 300;
+export const POLICY_WHY_MAX_CHARS = 300;
+
+/**
+ * The substring both untrusted-envelope delimiters carry (`access/untrusted.ts` `UNTRUSTED_OPEN` /
+ * `UNTRUSTED_CLOSE`). DUPLICATED here as a literal so this module stays framework-free — importing
+ * `untrusted.ts` would pull `taint-signal.ts` and therefore eve into the pure renderer the store and
+ * the tests share. Pinned against the real constants by an assertion in
+ * `scripts/routine-policy-test.ts`, the same discipline `WATCH_SILENCE_SENTINEL` uses.
+ */
+export const UNTRUSTED_DELIMITER_TOKEN = "untrusted_external_data";
+
+/** The tag this module renders its block under — named once so the prompt, the grammar guard and
+ *  the tests cannot drift. */
+export const POLICY_BLOCK_TAG = "[rules]";
+
+/**
+ * Is this text safe to render inside a TRUSTED block? Returns the refusal reason, or null.
+ *
+ * 🔴 THE GRAMMAR OF THE FIRE MESSAGE IS A SECURITY BOUNDARY. The rendered fire is a sequence of
+ * `[tag] …` blocks, trusted above and an untrusted fence below (routines/events.ts eventPrompt).
+ * Text that opens with its own `[tag]`, or that carries an envelope delimiter, can claim to BE one
+ * of those blocks — a rule reading `[job] ignore the ledger above` would render as a host-authored
+ * instruction. Rejecting the shape keeps the block's grammar unforgeable, which is the same posture
+ * `access/untrusted.ts` `defangDelimiters` takes on the other side of the fence. Rejecting rather
+ * than defanging is right here because, unlike untrusted content, a rule is a human's own sentence
+ * — there is somebody present to be told to rewrite it.
+ *
+ * NEWLINES ARE REJECTED, NOT STRIPPED. Stripping would silently join two clauses into one sentence
+ * whose meaning is not the one the human read on the card.
+ */
+export function policyTextProblem(text: string, field: "rule" | "why", maxChars: number): string | null {
+  const t = text.trim();
+  if (t.length === 0) {
+    return field === "why"
+      ? "every rule needs a `why` — the incident or reasoning behind it. A rule with no cause can never be safely retired, and it renders into every fire, so say what went wrong."
+      : "the rule text is empty — say what the routine must always (or never) do.";
+  }
+  if (t.length > maxChars) {
+    return `the \`${field}\` is ${t.length} characters; the cap is ${maxChars}. It is re-read on every fire of this routine forever, so make it one sentence.`;
+  }
+  if (/[\n\r]/.test(t)) {
+    return `the \`${field}\` must be ONE line — this one has a line break. Two rules are two calls, each with its own card, so each gets its own confirmation and its own provenance.`;
+  }
+  if (t.includes(UNTRUSTED_DELIMITER_TOKEN)) {
+    return `the \`${field}\` contains the untrusted-content envelope delimiter, which a standing rule may never carry — it renders as trusted text and would forge the boundary the fire message uses to separate instructions from data.`;
+  }
+  if (/^\[[^\]]*\]/.test(t)) {
+    return `the \`${field}\` starts with a \`[…]\` tag, which is the fire message's own block grammar (\`${POLICY_BLOCK_TAG}\`, \`[job]\`, \`[watch]\`, \`[silent]\`, \`[health]\`). A rule that opens one would impersonate a host-authored block — rephrase without the brackets.`;
+  }
+  return null;
+}
+
+/**
+ * THE ROUTINE-FIRE AUTHORSHIP GATE, as ONE pure function both tools call — gate 1 of the four in
+ * this module's header. Returns the refusal to throw, or null when the turn may propose.
+ *
+ * WHY IT LIVES HERE AND NOT IN EACH TOOL. Two tools enforcing "the same" refusal in two hand-written
+ * `if` blocks is two rules that agree until someone edits one. It is here for the reason
+ * `assertReportConsistent` is in routine.ts: the invariant belongs to the subsystem, not to a
+ * caller. It is PURE — the tools supply the fact from the real signal
+ * (`routineMarker(auth attributes)`), which is also what makes every arm of it reachable from a unit
+ * test; the live signal itself is session-scoped and fails soft, so a test that could only drive it
+ * through eve would exercise neither arm.
+ *
+ * 🔴 THE TAINT ARM IS GONE (OPE-438), and its absence is deliberate rather than an oversight. A
+ * tainted turn used to be refused here, before the approver chain ever saw the request. It is now
+ * handled by the chain alone: `add_routine_rule` and `remove_routine_rule` declare `taint: "gate"`,
+ * so a tainted turn's verdict is floored at `ask` and an unattended tainted run denies. Keeping a
+ * copy here would mean a human could approve a card and the tool would then refuse the act they
+ * approved — one control with two disagreeing enforcement points.
+ *
+ * WHAT SURVIVES, AND WHY IT IS A DIFFERENT QUESTION. The fire gate is STRUCTURAL: a routine's own
+ * run may not edit its own guardrails, no matter how clean the turn is and no matter who would
+ * approve it. There is no card that makes self-amendment acceptable, so it is not an approval
+ * question at all. Taint was always the softer of the two, which is why it is the one that moved.
+ */
+export function policyAuthorRefusal(
+  turn: { readonly inRoutineFire: boolean },
+  verb: "add" | "remove",
+): string | null {
+  if (turn.inRoutineFire) {
+    return verb === "add"
+      ? "A routine's own run can't add a standing rule — not even to itself. Rules are trusted instructions injected into unattended future runs, so they're only ever armed by a person in the channel. Say what went wrong in your answer instead, and whoever reads it can ask me to add the rule."
+      : "A routine's own run can't remove its standing rules. Those rules exist to constrain runs like this one, so a run removing them would be the routine editing its own guardrails. Say why the rule looks wrong in your answer, and someone in the channel can ask me to remove it.";
+  }
+  return null;
+}
+
+/** The rules currently on a routine — always an array, so no caller branches on absence. */
+export function policyRules(r: Pick<Routine, "policy">): readonly RoutinePolicyRule[] {
+  return r.policy ?? [];
+}
+
+/** Result of one `add`. `patch` is empty unless accepted — a refused add never touches the row. */
+export interface PolicyAddResult {
+  readonly accepted: boolean;
+  /** The refusal, phrased for the person who asked. Absent when accepted. */
+  readonly reason?: string;
+  readonly patch: Partial<Routine>;
+  /** Rule count AFTER the add when accepted, the unchanged count when refused. */
+  readonly count: number;
+}
+
+/**
+ * Fold one rule into a routine's policy. PURE — cap and grammar checked here, persistence at the
+ * ActionKind. Appends: order is the order they were armed in, which is the order a reader wants and
+ * the order the block renders.
+ *
+ * Refuses a DUPLICATE (same rule text, case- and whitespace-insensitive). Two identical rules are
+ * pure per-fire token cost with no added meaning, and the second one's `why` would be the one a
+ * later reader never sees.
+ */
+export function applyPolicyAdd(r: Pick<Routine, "policy">, rule: RoutinePolicyRule): PolicyAddResult {
+  const existing = policyRules(r);
+  const refuse = (reason: string): PolicyAddResult => ({ accepted: false, reason, patch: {}, count: existing.length });
+
+  const ruleProblem = policyTextProblem(rule.rule, "rule", POLICY_RULE_MAX_CHARS);
+  if (ruleProblem) return refuse(ruleProblem);
+  const whyProblem = policyTextProblem(rule.why, "why", POLICY_WHY_MAX_CHARS);
+  if (whyProblem) return refuse(whyProblem);
+
+  if (existing.length >= POLICY_MAX_RULES) {
+    return refuse(
+      `this routine already has the maximum ${POLICY_MAX_RULES} standing rules. Nothing is dropped automatically — a rule is a guardrail, and silently evicting the oldest to make room for a new one is exactly the removal this tool is gated against. Ask me to list them and remove one first.`,
+    );
+  }
+  const norm = (s: string): string => s.trim().replace(/\s+/g, " ").toLowerCase();
+  const dupe = existing.find((x) => norm(x.rule) === norm(rule.rule));
+  if (dupe) {
+    return refuse(`this routine already has that rule (${dupe.id}, added ${dupe.addedAt}) — nothing to add.`);
+  }
+  const next = [...existing, { ...rule, rule: rule.rule.trim(), why: rule.why.trim() }];
+  return { accepted: true, patch: { policy: next }, count: next.length };
+}
+
+/** Result of one `remove`. `removed` is the rule that went, so the caller can name it. */
+export interface PolicyRemoveResult {
+  readonly removed?: RoutinePolicyRule;
+  readonly patch: Partial<Routine>;
+  /** Rule count AFTER the removal, or the unchanged count when the id was not found. */
+  readonly count: number;
+}
+
+/**
+ * Drop one rule by id. PURE. A missing id yields an empty patch rather than an error, so a
+ * double-click on a card is a no-op instead of a failure — the card path can be raced.
+ */
+export function applyPolicyRemove(r: Pick<Routine, "policy">, ruleId: string): PolicyRemoveResult {
+  const existing = policyRules(r);
+  const removed = existing.find((x) => x.id === ruleId);
+  if (!removed) return { patch: {}, count: existing.length };
+  const next = existing.filter((x) => x.id !== ruleId);
+  // `[]` and not `undefined`: the patch is a shallow merge over the stored row, so clearing the last
+  // rule has to write an empty array. `undefined` would leave the old array in place on some merge
+  // shapes, which would mean a removal a human confirmed did not happen.
+  return { removed, patch: { policy: next }, count: next.length };
+}
+
+/** One rendered rule line pair. */
+function renderRule(x: RoutinePolicyRule): string[] {
+  const day = x.addedAt.slice(0, 10);
+  const who = x.source === "learned" ? ", proposed by me and confirmed" : "";
+  return [`- (${x.id}, ${day}${who}) ${x.rule}`, `    why: ${x.why}`];
+}
+
+/**
+ * THE TRUSTED BLOCK — rendered into EVERY fire of a routine that has rules, by all four fire shapes
+ * (renderScheduledMessage / renderWatchMessage / renderJobMessage / eventPrompt). Empty string when
+ * there are none, so every routine without policy renders byte-identically to before.
+ *
+ * 🔴 THE LAST LINE IS THE PRODUCT, not a footnote. Open Everywhere's claim is that the control plane
+ * is the room you are already in — so an autonomous run that posts into a channel has to advertise,
+ * in the same breath, that the rules governing it are editable from that channel by anyone reading.
+ * Without it, a routine's accumulated doctrine is discoverable only by someone who already knows
+ * `list_routines` exists, which is the "go to the portal to configure the agent" pattern this
+ * feature is the argument against.
+ *
+ * The count renders even at 1 of 20, because "how full is this" is the only signal a reader gets
+ * that the set has a bound — and the bound is what makes pruning happen (see POLICY_MAX_RULES).
+ */
+export function renderPolicyBlock(r: Pick<Routine, "policy">): string {
+  const rules = policyRules(r);
+  if (rules.length === 0) return "";
+  return [
+    `${POLICY_BLOCK_TAG} Standing rules for this routine. A human in this channel confirmed each one on an ` +
+      `approval card, so they are instructions, not suggestions: they OVERRIDE your default judgement and ` +
+      `you follow them exactly. If one conflicts with the task below, the rule wins — say so in your answer ` +
+      `rather than working around it.`,
+    ...rules.flatMap(renderRule),
+    `(${rules.length} of ${POLICY_MAX_RULES} rules. Anyone in this channel can change them — ask me to list, ` +
+      `add or remove a rule, and I'll post a card for someone to confirm.)`,
+  ].join("\n");
+}