@orbytes/astrolab 0.3.0

package/src/pin/tickets.mjs

@@ -0,0 +1,697 @@
+// orbytes-pin — ticket allocation, rendering and reading.
+//
+// One ticket is one markdown file at `<repo>/backlog/tasks/pin-<NNN>-<slug>.md`, in backlog.md's
+// own frontmatter vocabulary plus a `pin:` block this package owns. The shape is fixed by
+// ../../docs/PIN-CONTRACT.md § "Ticket format" — do not redesign it here.
+//
+// Every path this module writes into a ticket is REPO-RELATIVE (contract non-negotiable 2): a
+// ticket is committed and read by an agent on another machine, so an absolute /Users/... path in
+// one is a leak and a lie. The repo root is found by walking up from the Astro config root to the
+// first directory holding `.git`, and nothing here accepts a root it did not find that way.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+
+/**
+ * The six states a ticket can be in, in board order. Nothing else may be written to `status`.
+ *
+ * Ruled 2026-09-22, one line per status:
+ *
+ *   · `Backlog`          — for when an agent should not pick it up yet
+ *   · `Ready for agent`  — replaces `To Do`
+ *   · `In Progress`      — an agent has it and is working on it
+ *   · `Ready for review` — done; a human in the loop moves it into resolved
+ *   · `Resolved`         — accepted
+ *   · `Cancelled`        — just an archive for cancelled work; items in here must not override
+ *                          anything or take up context space for an agent
+ *
+ * Three of those carry a rule, and each is enforced by something in this file rather than left as
+ * a convention to remember:
+ *
+ *   1. **`Ready for agent` is the only status an agent may start work from** (› `isAgentReady`).
+ *      `Backlog` means explicitly not yet. The same vocabulary was rolled out across the
+ *      issue tracker the day before, deliberately, so the local board and the tracker agree.
+ *   2. **Only a human sets `Resolved`. No agent moves a ticket there, ever.** That is the whole
+ *      reason `Ready for review` exists: until 2026-09-22 the last column was `Done`, which
+ *      conflated "an agent finished it" with "a human accepted it", so work waiting on review
+ *      had nowhere to sit and nothing on the board could say *this one wants you*.
+ *   3. **`Cancelled` is an archive that must not reach an agent's context** (› `listTickets`,
+ *      which excludes it unless asked). Not sorted last, not greyed out — absent.
+ *
+ * `To Do` and `Done` survive as legacy read aliases (› `normaliseStatus`) and are never written
+ * again.
+ */
+export const STATUSES = ["Backlog", "Ready for agent", "In Progress", "Ready for review", "Resolved", "Cancelled"];
+
+/** Not for agents yet — still being decided, or it waits on something else. */
+export const BACKLOG = "Backlog";
+
+/** The ONLY status an agent may start work from, and what a new pin is written as. */
+export const READY_FOR_AGENT = "Ready for agent";
+
+/** An agent has picked it up and is working on it. */
+export const IN_PROGRESS = "In Progress";
+
+/** Finished by an agent, not yet accepted. The human review queue, and the point of the 2026-09-22 change. */
+export const READY_FOR_REVIEW = "Ready for review";
+
+/** A human accepted the work. Only a human ever sets it; no agent moves a ticket here. */
+export const RESOLVED = "Resolved";
+
+/** The archive. Kept on disk, kept off every agent-facing read. */
+export const CANCELLED = "Cancelled";
+
+/** What a freshly picked ticket is written as — an agent may take it straight away. */
+export const DEFAULT_STATUS = READY_FOR_AGENT;
+
+/** The two statuses that end a ticket's life: accepted, or abandoned. */
+export const CLOSED_STATUSES = Object.freeze([RESOLVED, CANCELLED]);
+
+/**
+ * "Open" means neither `Resolved` nor `Cancelled` — every surface, one definition.
+ *
+ * A list and a predicate rather than a rule each surface re-derives, because there are now four
+ * open statuses and two surfaces (this board's columns and chips, the in-page panel's Open tab).
+ * Two places counting "open" their own way is how they come to disagree by one ticket.
+ *
+ * Use `isOpen(status)` on a status read off a file — it normalises the legacy aliases first,
+ * which a bare `OPEN_STATUSES.includes(...)` does not.
+ */
+export const OPEN_STATUSES = Object.freeze(STATUSES.filter((s) => !CLOSED_STATUSES.includes(s)));
+
+/**
+ * Statuses written before 2026-09-22, mapped onto today's vocabulary.
+ *
+ * Every ticket and every reader written before the split still says these, so they must keep
+ * parsing. `To Do` → `Ready for agent` is the ruled replacement — that status was introduced to
+ * take `To Do`'s place; `Done` → `Resolved` because a `Done` ticket on a three-column board with
+ * no review step was one a human had already let go by. `updateTicket` rewrites the line on the
+ * next write of that ticket, so the aliases drain themselves rather than living on disk forever.
+ */
+const LEGACY_STATUS = Object.freeze({ "To Do": READY_FOR_AGENT, Done: RESOLVED });
+
+/**
+ * A status as the board means it: today's vocabulary, with the legacy aliases resolved.
+ *
+ * Everything else is handed back trimmed and unchanged — an unknown status is a real thing to see
+ * on the board (it gets its own undroppable column), never something to round to a known one.
+ *
+ * @param {unknown} status the raw `status:` value read off a ticket
+ * @returns {string} the status in today's vocabulary, or "" when there was none
+ */
+export function normaliseStatus(status) {
+  const s = String(status ?? "").trim();
+  return LEGACY_STATUS[s] ?? s;
+}
+
+/**
+ * Is this ticket open — neither accepted nor cancelled?
+ *
+ * Deliberately a predicate on the status and not on the ticket, so both surfaces and any agent
+ * reading `listTickets()` ask the same question the same way. It handles the legacy aliases,
+ * which is the whole reason to call it rather than compare strings: `isOpen("Done")` is `false`.
+ *
+ * @param {unknown} status
+ */
+export function isOpen(status) {
+  return !CLOSED_STATUSES.includes(normaliseStatus(status));
+}
+
+/**
+ * Is this ticket archived — cancelled, and therefore invisible to every agent-facing read?
+ *
+ * Ruled 2026-09-22: items in here must not override anything or take up context space for an
+ * agent. `listTickets` drops these unless explicitly asked for them; `/pin` is the one place
+ * they are still visible, because an archive nobody can open is a delete.
+ *
+ * @param {unknown} status
+ */
+export function isCancelled(status) {
+  return normaliseStatus(status) === CANCELLED;
+}
+
+/**
+ * May an agent start work on a ticket in this status? Exactly one status says yes.
+ *
+ * `Backlog` is the explicit no — for when an agent should not pick it up yet. An agent that
+ * picks work off the board asks this question and nothing else; "not Resolved" is not the test,
+ * and neither is "To Do", which no longer exists.
+ *
+ * @param {unknown} status
+ */
+export function isAgentReady(status) {
+  return normaliseStatus(status) === READY_FOR_AGENT;
+}
+
+/** The opening fence of the body block that carries every pin field. Matched, never guessed. */
+export const PIN_FENCE = "```yaml pin";
+
+/**
+ * The repo root: the first ancestor of `from` that contains `.git`. Throws rather than guessing,
+ * because every path in a ticket is relative to it and a wrong root silently poisons every ticket.
+ * @param {string} from absolute directory to start from (the Astro config root)
+ */
+export function findRepoRoot(from) {
+  let dir = resolve(from);
+  for (;;) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  throw new Error(`orbytes-pin: no .git found above ${from} — cannot resolve the repo root, so no ticket path can be made repo-relative.`);
+}
+
+/** The repo directory name — the `<project>` segment of the screenshot archive path. */
+export const projectName = (repoRoot) => resolve(repoRoot).split(sep).filter(Boolean).pop();
+
+/** lowercase, non-alphanumerics collapsed to `-`, trimmed to 40 chars, no leading/trailing dash. */
+export function slugify(title) {
+  const s = String(title ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40)
+    .replace(/-+$/g, "");
+  return s || "untitled";
+}
+
+/**
+ * The ticket title: the first non-empty line of the pin comment, trimmed to 70 chars.
+ *
+ * 70 and not 80, and the number is load-bearing. backlog.md re-serialises frontmatter with
+ * js-yaml on every write, and js-yaml folds a scalar whose RAW LENGTH exceeds
+ * `lineWidth - indent` — 80 - 2 = 78 for a top-level key. Measured against backlog.md 1.52.0
+ * (2026-09-21) by writing tickets at every title length from 55 to 95, running
+ * `backlog task edit <n> -s "In Progress"` on each and reading the files back: 78 characters
+ * stayed on one line, 79 came back as a `>-` block, and the boundary did not move when the word
+ * boundaries were changed (`"ab " * 26`) or when the title was quoted by a colon. So it is the
+ * title's own length that decides, not the width of the rendered `title: …` line — the key and
+ * its separator cost nothing.
+ *
+ * The old cap of 80 sat two characters over that line, so a full-length title folded the first
+ * time a card was dragged to a new status, turning a file a person reads into a wrapped block.
+ * 70 leaves eight characters of headroom for an indent level or a js-yaml default that moves.
+ * `parseTicket` reads the folded form regardless; this half only stops provoking it.
+ */
+export function titleFrom(comment) {
+  const line = String(comment ?? "")
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .find((l) => l.length > 0);
+  // trimEnd: the slice can cut mid-phrase and leave a trailing space, which `yamlScalar` would
+  // then have to quote — a quoted title where every neighbour is bare, for no reason a reader sees.
+  return (line ?? "Untitled pin").slice(0, 70).trimEnd();
+}
+
+/**
+ * The next free number: max of every `pin-<NNN>` already in `tasks/`, plus one. Scanning
+ * filenames (not an index file) means a ticket deleted by hand never hands its number out twice
+ * to a reader of git history, and there is no counter to fall out of sync.
+ */
+export function nextNumber(tasksDir) {
+  let max = 0;
+  if (existsSync(tasksDir)) {
+    for (const name of readdirSync(tasksDir)) {
+      const m = /^pin-(\d+)(?:-|\.md$)/.exec(name);
+      if (m) max = Math.max(max, Number(m[1]));
+    }
+  }
+  return max + 1;
+}
+
+export const pad = (n) => String(n).padStart(3, "0");
+
+/**
+ * A YAML scalar that survives a round trip. Bare where that is unambiguous, single-quoted
+ * otherwise (YAML escapes a single quote by doubling it). `force` is for the fields the contract
+ * shows quoted whatever their content — dates, selectors, raw HTML.
+ */
+function yamlScalar(value, force = false) {
+  const s = String(value ?? "");
+  const unsafe =
+    force ||
+    s === "" ||
+    s !== s.trim() ||
+    /^[-?:,\[\]{}#&*!|>'"%@`]/.test(s) ||
+    /:\s|\s#/.test(s) ||
+    /[\n\r]/.test(s) ||
+    /^(true|false|null|~|yes|no|on|off)$/i.test(s) ||
+    /^[+-]?(\d|\.\d)/.test(s);
+  if (!unsafe) return s;
+  return `'${s.replace(/\r?\n/g, " ").replace(/'/g, "''")}'`;
+}
+
+const flowNums = (obj, keys) => `{ ${keys.map((k) => `${k}: ${Number(obj?.[k]) || 0}`).join(", ")} }`;
+
+/**
+ * The second label, beside `pin`. Derived from the section folder a stamped source names
+ * (`.../sections/About01Hero/V1/...` → `hero`), so tickets about one section are greppable.
+ * Underspecified by the contract, whose example shows `labels: [pin, hero]` on a hero section;
+ * this rule reproduces that. No resolvable section → `[pin]` alone, never a guess.
+ */
+export function labelsFor(source) {
+  const m = /\/sections\/([A-Za-z0-9]+)\//.exec(String(source ?? ""));
+  if (!m) return ["pin"];
+  const tail = m[1].replace(/^[A-Za-z]+\d+/, "") || m[1];
+  const label = slugify(tail.replace(/([a-z0-9])([A-Z])/g, "$1-$2"));
+  return label && label !== "untitled" ? ["pin", label] : ["pin"];
+}
+
+/**
+ * The ticket's markdown. Frontmatter carries ONLY backlog.md's own schema; everything this
+ * package needs lives in a fenced ```yaml pin block in the BODY.
+ *
+ * Why, measured against the installed backlog.md on 2026-09-21 — and this is the whole reason
+ * the shape is not the one ../../docs/PIN-CONTRACT.md § Ticket format drew:
+ *   · Any write through backlog — the CLI, or dragging a card's status in the web UI —
+ *     re-serialises frontmatter to backlog's own schema and silently drops every unknown key.
+ *     `backlog task edit <n> -s Done` on a contract-shaped ticket erased dispatch, source,
+ *     selector, rect, shot and outer_html. The first time a card was moved, the ticket stopped
+ *     being actionable. The body and its image survive that write untouched.
+ *   · backlog's detail view renders only its own known headings. Under `## Comment` the panel
+ *     read "No description" and `document.images` was empty — the comment AND the screenshot
+ *     were invisible on the board. Under `## Description` both render.
+ *
+ * Order inside the body is deliberate: what the reviewer reads (the comment, then the picture)
+ * comes before what an agent reads.
+ */
+export function renderTicket({ id, num, title, createdDate, labels, pin, comment }) {
+  const shotName = `pin-${pad(num)}.png`;
+  return [
+    "---",
+    `id: ${id}`,
+    `title: ${yamlScalar(title)}`,
+    // `Ready for agent`, not `Backlog`: a person picked this element and typed a comment about
+    // it, so it is work they want done. `Backlog` is the status a ticket is moved TO to wait.
+    // Written bare, with no quoting, which is safe because DEFAULT_STATUS comes from the closed
+    // allowlist above and every member of it is a plain YAML scalar.
+    `status: ${DEFAULT_STATUS}`,
+    "assignee: []",
+    `created_date: ${yamlScalar(createdDate, true)}`,
+    `labels: [${labels.join(", ")}]`,
+    "dependencies: []",
+    "priority: medium",
+    "---",
+    "",
+    // backlog.md renders this heading and no other. Do not rename it.
+    "## Description",
+    "",
+    // Verbatim. Never summarised, never rewritten — contract § Notes on the fields.
+    String(comment).replace(/\r\n/g, "\n").trimEnd(),
+    "",
+    // backlog.md's own served route, which is NOT the on-disk path in `shot:` below. Both are
+    // required and they differ on purpose.
+    `![](/assets/${shotName})`,
+    "",
+    // The info string is `yaml pin` so a reader matches the fence, never a position in the file.
+    PIN_FENCE,
+    `dispatch: ${pin.dispatch}`,
+    `source: ${yamlScalar(pin.source)}`,
+    `selector: ${yamlScalar(pin.selector, true)}`,
+    // How many nodes `selector` finds on a genuinely FRESH load of `url`. Seeded `pending`
+    // because nobody has checked yet — the ticket is written on the same synchronous tick as
+    // the click, and the only honest fresh load is the screenshot's, which happens after.
+    // shot.mjs replaces this with an integer when the shutter fires (› recordSelectorMatches).
+    // It stays `pending` when shots are off or the screenshot failed, which is the truth: the
+    // selector was never tested. It is never silently dropped, because silence is the defect
+    // this field exists to end — a selector anchored on a framework-generated id resolves to
+    // exactly one node when written and none ever again, and every other part of the ticket
+    // still looks perfect.
+    `selector_matches: ${pin.selectorMatches ?? "pending"}`,
+    `url: ${yamlScalar(pin.url)}`,
+    `viewport: ${flowNums(pin.viewport, ["width", "height", "dpr"])}`,
+    `scroll: ${flowNums(pin.scroll, ["x", "y"])}`,
+    `rect: ${flowNums(pin.rect, ["x", "y", "width", "height"])}`,
+    `shot: ${pin.shot}`,
+    `outer_html: ${yamlScalar(pin.outerHTML, true)}`,
+    "```",
+    "",
+  ].join("\n");
+}
+
+/** Reject a payload that cannot make a valid ticket. Refuses; never repairs. */
+export function validate(payload) {
+  const p = payload ?? {};
+  if (typeof p.comment !== "string" || p.comment.trim() === "") return "the comment is empty";
+  if (p.dispatch !== "now" && p.dispatch !== "queue") return `dispatch must be "now" or "queue", got ${JSON.stringify(p.dispatch)}`;
+  if (typeof p.selector !== "string" || p.selector.trim() === "") return "the selector is missing";
+  if (typeof p.url !== "string" || !p.url.startsWith("/")) return "the url must be a site path starting with /";
+  for (const [key, fields] of [["viewport", ["width", "height", "dpr"]], ["scroll", ["x", "y"]], ["rect", ["x", "y", "width", "height"]]]) {
+    const o = p[key];
+    if (!o || typeof o !== "object") return `${key} is missing`;
+    for (const f of fields) if (!Number.isFinite(Number(o[f]))) return `${key}.${f} is not a number`;
+  }
+  if (Number(p.rect.width) <= 0 || Number(p.rect.height) <= 0) return "the clicked element has no width or height to shoot";
+  return null;
+}
+
+/**
+ * Allocate, render and write one ticket. Atomic: the markdown is written to a temp file beside
+ * its destination and renamed, so a reader never sees half a ticket, and the destination is
+ * refused if it already exists (a lost race re-allocates rather than overwriting the comment).
+ *
+ * @returns {{ id: string, num: number, file: string, shot: string, archiveName: string, absolute: string }}
+ *   every path repo-relative except `absolute`, which never leaves this process.
+ */
+export function writeTicket(repoRoot, payload, { backlogDir = "backlog" } = {}) {
+  const bad = validate(payload);
+  if (bad) throw new Error(bad);
+
+  const tasksDir = join(repoRoot, backlogDir, "tasks");
+  mkdirSync(tasksDir, { recursive: true });
+
+  const title = titleFrom(payload.comment);
+  const slug = slugify(title);
+  const createdDate = new Date().toLocaleDateString("en-CA"); // local YYYY-MM-DD, not UTC
+
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const num = nextNumber(tasksDir) + attempt;
+    const base = `pin-${pad(num)}-${slug}.md`;
+    const absolute = join(tasksDir, base);
+    if (existsSync(absolute)) continue;
+    // A same-number file under a DIFFERENT slug must lose the race too, or two tickets share an id.
+    if (readdirSync(tasksDir).some((n) => n.startsWith(`pin-${pad(num)}-`) || n === `pin-${pad(num)}.md`)) continue;
+
+    const id = `PIN-${pad(num)}`;
+    const shot = `${backlogDir}/assets/pin-${pad(num)}.png`;
+    const body = renderTicket({
+      id,
+      num,
+      title,
+      createdDate,
+      labels: labelsFor(payload.source),
+      comment: payload.comment,
+      pin: {
+        dispatch: payload.dispatch,
+        source: payload.source || "unresolved",
+        selector: payload.selector,
+        selectorMatches: payload.selectorMatches,
+        url: payload.url,
+        viewport: payload.viewport,
+        scroll: payload.scroll,
+        rect: payload.rect,
+        shot,
+        outerHTML: String(payload.outerHTML ?? "").slice(0, 400),
+      },
+    });
+
+    const tmp = join(tasksDir, `.${base}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`);
+    try {
+      writeFileSync(tmp, body, { encoding: "utf8", flag: "wx" });
+      renameSync(tmp, absolute);
+    } catch (e) {
+      rmSync(tmp, { force: true });
+      throw e;
+    }
+    return { id, num, file: `${backlogDir}/tasks/${base}`, shot, archiveName: `pin-${pad(num)}.png`, absolute };
+  }
+  throw new Error("orbytes-pin: could not allocate a free ticket number after 8 tries");
+}
+
+/**
+ * Write the fresh-load selector count into a ticket that is already on disk.
+ *
+ * Surgical by design: it rewrites exactly the one `selector_matches:` line inside the fenced pin
+ * block and touches nothing else — not the frontmatter backlog.md owns, not the comment, not
+ * the image. Atomic, same temp-and-rename as writeTicket, so a reader never sees half a ticket.
+ *
+ * Refuses rather than warns (behaviour.md — a guard that warns instead of refusing is not a
+ * guard): no fence, no seeded line, or a file that moved between read and write, and this throws
+ * with the path in the message. The caller turns that into a visible failure; it must never
+ * become a ticket that quietly keeps saying `pending` while claiming to have been checked.
+ *
+ * @param {string} absolute absolute path of the ticket file
+ * @param {number} count nodes the ticket's selector matched on a fresh load
+ * @returns {{ file: string, matches: number }}
+ */
+export function recordSelectorMatches(absolute, count) {
+  const n = Number(count);
+  if (!Number.isInteger(n) || n < 0) throw new Error(`selector_matches must be a whole number, got ${JSON.stringify(count)}`);
+
+  const text = readFileSync(absolute, "utf8");
+  const fence = text.indexOf(PIN_FENCE);
+  if (fence === -1) throw new Error(`${absolute} has no ${PIN_FENCE} block to record selector_matches in`);
+  const end = text.indexOf("\n```", fence + PIN_FENCE.length);
+  if (end === -1) throw new Error(`${absolute} has an unterminated ${PIN_FENCE} block`);
+
+  const head = text.slice(0, fence);
+  const block = text.slice(fence, end);
+  const tail = text.slice(end);
+  if (!/^selector_matches:.*$/m.test(block)) {
+    throw new Error(`${absolute} has no selector_matches line in its pin block — it predates the field, or was rewritten`);
+  }
+  const updated = head + block.replace(/^selector_matches:.*$/m, `selector_matches: ${n}`) + tail;
+
+  const tmp = `${absolute}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+  try {
+    writeFileSync(tmp, updated, { encoding: "utf8", flag: "wx" });
+    renameSync(tmp, absolute);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+  return { file: absolute, matches: n };
+}
+
+// ── Reading ────────────────────────────────────────────────────────────────
+// A deliberately small parser for the shape renderTicket writes AND for what backlog.md rewrites
+// it into: top-level scalars, inline flow arrays and maps, block sequences and block scalars, in
+// the frontmatter and inside the fenced pin block. It is not a general YAML implementation —
+// anchors, tags, multi-document streams and nested block maps are all out of scope.
+
+const unquote = (s) => {
+  const t = s.trim();
+  if (t.startsWith("'") && t.endsWith("'") && t.length > 1) return t.slice(1, -1).replace(/''/g, "'");
+  if (t.startsWith('"') && t.endsWith('"') && t.length > 1) return t.slice(1, -1);
+  return t;
+};
+
+function coerce(raw) {
+  const t = raw.trim();
+  if (t.startsWith("[") && t.endsWith("]")) {
+    const inner = t.slice(1, -1).trim();
+    return inner ? inner.split(",").map((v) => unquote(v)) : [];
+  }
+  if (t.startsWith("{") && t.endsWith("}")) {
+    const out = {};
+    for (const part of t.slice(1, -1).split(",")) {
+      const i = part.indexOf(":");
+      if (i === -1) continue;
+      const v = unquote(part.slice(i + 1));
+      out[part.slice(0, i).trim()] = /^-?\d+(\.\d+)?$/.test(v) ? Number(v) : v;
+    }
+    return out;
+  }
+  return unquote(t);
+}
+
+/** A block-scalar header and nothing else: `>`, `>-`, `|`, `|+`, `|2-`, `|-2`. */
+const BLOCK_HEADER = /^([|>])((?:[-+]\d?)|(?:\d[-+]?)|)$/;
+
+/**
+ * A YAML block scalar's value: the indented lines captured under a `>` / `|` header.
+ *
+ * backlog.md rewrites a long `title` into this shape on any write — including the status change
+ * made by dragging a card — so this is the ordinary reading path for a real ticket, not a
+ * hand-edit allowance. Read as a plain scalar, the header alone parses to the literal string
+ * ">-" and every continuation line is dropped, which is unrecoverable: the title is gone from
+ * the parser's output entirely.
+ *
+ * Verified against real folded output. Three details are easy to get wrong and are all handled
+ * here deliberately:
+ *   · the explicit-indent forms `|2-` and `|-2` are both accepted, because YAML allows either
+ *     order, and the indent is read from either.
+ *   · when an explicit indent IS given, exactly that many columns are stripped, rather than the
+ *     minimum indentation of the block — which is the whole reason the indicator exists, since
+ *     it is what preserves leading spaces on the first line.
+ *   · in a folded block, N consecutive line breaks fold to N-1 newlines, so one blank line is
+ *     one newline, and a run of two or more blanks does not gain an extra. Interior runs of
+ *     spaces survive rather than collapsing.
+ *
+ * A more-indented line inside a folded block is never folded into its neighbours — a real YAML
+ * rule, cheap to honour, and the one shape where folding silently destroys structure.
+ *
+ * The chomping indicator is parsed and then ignored: it decides only the trailing newline, nothing downstream renders one, and a title that came back
+ * ending in "\n" would be correct YAML and a nuisance everywhere it is printed.
+ */
+function blockScalar(rawLines, style, explicitIndent, parentIndent) {
+  const indents = rawLines.filter((l) => l.trim() !== "").map((l) => /^[ \t]*/.exec(l)[0].length);
+  const strip = explicitIndent > 0 ? parentIndent + explicitIndent : indents.length ? Math.min(...indents) : 0;
+  const body = rawLines.map((l) => l.slice(strip));
+  while (body.length && body.at(-1).trim() === "") body.pop();
+  if (style === "|") return body.join("\n");
+
+  let out = "";
+  let breaks = 0;
+  let prevMore = false;
+  for (const line of body) {
+    if (line.trim() === "") {
+      breaks++;
+      continue;
+    }
+    const more = /^[ \t]/.test(line);
+    const text = more ? line.replace(/[ \t]+$/, "") : line.trim();
+    if (out === "") out = text;
+    else out += (breaks > 0 ? "\n".repeat(breaks) : more || prevMore ? "\n" : " ") + text;
+    breaks = 0;
+    prevMore = more;
+  }
+  return out;
+}
+
+/**
+ * One YAML mapping, as far as a ticket ever needs: `key: <flow scalar>`, `key:` over a block
+ * sequence, and `key:` over a block scalar.
+ *
+ * `anchored` is the difference between the two call sites and is not cosmetic. Frontmatter keys
+ * must start at column 0, so an indented line can only ever be a continuation — that is what
+ * stops a nested map's child keys being hoisted to the top level. Inside the pin fence, keys are
+ * matched after trimming, which is what the previous reader did and what keeps an indented
+ * hand-edit readable.
+ *
+ * @param {string[]} lines
+ * @param {{ anchored: boolean }} opts
+ */
+function parseMapping(lines, { anchored }) {
+  const out = {};
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (!raw.trim() || raw.trim().startsWith("#")) continue;
+    const kv = /^([A-Za-z_][\w]*):\s?(.*)$/.exec(anchored ? raw : raw.trim());
+    if (!kv) continue;
+    const [, key, rest] = kv;
+
+    // A block-scalar header is not a value: the value is the indented block beneath it. Tested
+    // BEFORE the plain-scalar branch, which would otherwise store ">-" and drop every line of
+    // the actual text.
+    const header = BLOCK_HEADER.exec(rest.trim());
+    if (header) {
+      const kept = [];
+      while (i + 1 < lines.length && (lines[i + 1].trim() === "" || /^[ \t]/.test(lines[i + 1]))) {
+        kept.push(lines[++i]);
+      }
+      const digit = /\d/.exec(header[2]);
+      out[key] = blockScalar(kept, header[1], digit ? Number(digit[0]) : 0, /^[ \t]*/.exec(raw)[0].length);
+      continue;
+    }
+
+    if (rest.trim() !== "") {
+      out[key] = coerce(rest);
+      continue;
+    }
+
+    // Nothing after the colon: a block sequence, or an empty value. backlog.md rewrites the
+    // inline `labels: [pin, hero]` this module writes into a `- pin` / `- hero` list on the same
+    // write that folds the title (measured 2026-09-21 against backlog.md 1.52.0), so this is the
+    // ordinary shape of a touched ticket, not a hand-edit allowance.
+    const items = [];
+    while (i + 1 < lines.length && /^\s+-\s/.test(lines[i + 1])) {
+      items.push(unquote(lines[++i].replace(/^\s+-\s/, "")));
+    }
+    out[key] = items.length ? items : "";
+  }
+  return out;
+}
+
+/**
+ * Parse one ticket: backlog.md's frontmatter (status, title, labels, priority…) plus the body —
+ * the pin comment and the fenced `yaml pin` block that carries every field this package owns.
+ *
+ * The pin fields come from the FENCE, never from frontmatter, because backlog strips unknown
+ * frontmatter keys on any write (see renderTicket). A ticket whose fence is missing or
+ * unparseable is a hard error naming the file, not a half-filled object: a pin with an empty
+ * rect would send a screenshot to the wrong place and look like it worked.
+ *
+ * `status` comes back RAW — exactly the string on disk, which on a ticket written before
+ * 2026-09-22 is `Done`. This is the file reader, and a reader that silently improved a value
+ * would leave nothing able to tell you what the file actually says. Put it through
+ * `normaliseStatus()` before comparing it to anything, or ask `isOpen()`; never `=== "Resolved"`.
+ *
+ * @param {string} text
+ * @param {string} [file] repo-relative path, used in the error message
+ */
+export function parseTicket(text, file = "<unknown file>") {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+  if (!m) throw new Error(`orbytes-pin: ${file} has no frontmatter — not a ticket.`);
+
+  // Frontmatter, in BOTH the shapes a ticket can be in: what this module writes (inline flow
+  // arrays, a bare `title`), and what backlog.md rewrites that into the first time anyone moves
+  // the card — `labels: [pin, hero]` becomes a `- pin` / `- hero` list, a title over 78 characters
+  // becomes a `>-` block, and `updated_date` appears. A reader that handles only the first shape
+  // loses `labels` and the real `title` on every ticket that has been touched on the board.
+  const front = parseMapping(m[1].split(/\r?\n/), { anchored: true });
+
+  const body = m[2];
+  const fence = body.indexOf(PIN_FENCE);
+  if (fence === -1) {
+    throw new Error(`orbytes-pin: ${file} has no \`\`\`yaml pin block — its pin data was stripped, or it was not written by this package.`);
+  }
+  const afterOpen = body.indexOf("\n", fence) + 1;
+  const closeAt = body.indexOf("\n```", afterOpen);
+  if (afterOpen === 0 || closeAt === -1) {
+    throw new Error(`orbytes-pin: ${file} has an unterminated \`\`\`yaml pin block.`);
+  }
+
+  // The same reader as the frontmatter. backlog never rewrites the body, so the fence holds what
+  // this module wrote — but one reader means a hand-edited block scalar in here cannot become a
+  // second, quieter version of the bug the frontmatter just had.
+  const pin = parseMapping(body.slice(afterOpen, closeAt).split(/\r?\n/), { anchored: false });
+  for (const required of ["dispatch", "source", "selector", "url", "viewport", "scroll", "rect", "shot"]) {
+    if (pin[required] === undefined) {
+      throw new Error(`orbytes-pin: ${file} is missing \`${required}\` from its yaml pin block.`);
+    }
+  }
+  // `selector_matches` is a COUNT, so hand it back as one. coerce() returns every top-level
+  // scalar as a string, and the string "0" is truthy — a reader writing the obvious
+  // `if (!t.pin.selector_matches)` would treat a dead selector as a healthy one, which is the
+  // exact silence this field exists to end. `pending` (never tested) and a ticket written
+  // before the field existed (undefined) both stay as they are: neither is a number, and
+  // neither may be rounded to one.
+  if (typeof pin.selector_matches === "string" && /^\d+$/.test(pin.selector_matches)) {
+    pin.selector_matches = Number(pin.selector_matches);
+  }
+
+  // The pin comment: everything under `## Description` up to the image or the fence, whichever
+  // comes first. A heading of any other name means backlog rendered nothing, so refuse it.
+  const heading = /^##[ \t]+Description[ \t]*$/m.exec(body);
+  if (!heading) throw new Error(`orbytes-pin: ${file} has no "## Description" heading — backlog.md renders no other.`);
+  const rest = body.slice(heading.index + heading[0].length);
+  const stop = Math.min(
+    ...[rest.indexOf(PIN_FENCE), rest.search(/^!\[\]\(/m)].filter((i) => i >= 0).concat([rest.length]),
+  );
+  return { ...front, pin, comment: rest.slice(0, stop).trim() };
+}
+
+/**
+ * Every LIVE ticket in `<repo>/<backlogDir>/tasks`, oldest number first.
+ *
+ * This is the agent-facing reader — what a session calls to find out what there is to do — so
+ * `Cancelled` tickets are **not in it**. Ruled 2026-09-22, on that status: it is just an archive
+ * for cancelled work, and items in here must not override anything or take up context space for
+ * an agent. Filtering here rather than in each caller is what makes that true by default: an agent
+ * that never heard of the rule still cannot be handed a dead ticket, and one that wants the
+ * archive has to say so in the call.
+ *
+ * `includeCancelled: true` returns them, and the only callers that pass it are the two surfaces
+ * that draw the archive — `/pin` and `orbytes-pin-gallery` — plus `updateTicket`, which has to be able to
+ * find a cancelled ticket in order to move it back out.
+ *
+ * Statuses come back RAW (› `parseTicket`), so the filter normalises before it compares: a ticket
+ * whose file still says `Done` is `Resolved`, and is live.
+ *
+ * @param {string} repoRoot
+ * @param {{ backlogDir?: string, includeCancelled?: boolean }} [options]
+ */
+export function listTickets(repoRoot, { backlogDir = "backlog", includeCancelled = false } = {}) {
+  const tasksDir = join(repoRoot, backlogDir, "tasks");
+  if (!existsSync(tasksDir)) return [];
+  return readdirSync(tasksDir)
+    .filter((n) => /^pin-\d+.*\.md$/.test(n))
+    .sort()
+    .map((name) => {
+      const file = `${backlogDir}/tasks/${name}`;
+      // Not swallowed: a ticket this package cannot read is a defect to see, not a row to drop.
+      return { ...parseTicket(readFileSync(join(tasksDir, name), "utf8"), file), file };
+    })
+    .filter((t) => includeCancelled || !isCancelled(t.status));
+}