@intentius/chant 0.124.2 → 0.124.3

package/src/point-decision.e2e.test.ts

@@ -0,0 +1,95 @@
+/**
+ * #3816: a tool built into one file decides a gate that asks a decision point
+ * with `@intentius/chant/point-decision`, asking through the chant bin
+ * (`chantGatePointAsker`) and recording through its own gate ledger port.
+ * The question is open until a person answers it with `chant workspace points
+ * answer`; then the same call records the resolution that cites the answer,
+ * once per answer and plan. With `store: "ledger"` the question is held on
+ * `chant/lifecycle`, not in the working tree (#3815).
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
+import { cleanScratch, workspace } from "./workspace/__fixtures__/decide-workspace";
+import { defaultChantCommand } from "./workspace/conformance";
+import { memoryGateLedgerPort } from "./op/gate";
+import { chantGatePointAsker, evaluatePointGate, type PointGateCheck } from "./point-decision";
+
+const PLAN = `jcs1-sha256:${"5".repeat(64)}`;
+
+const POINTS = {
+  points: {
+    "prod-apply": {
+      title: "Apply this plan to prod",
+      question: { type: "noul", instructions: "Should this plan be applied to prod?", criteria: { true: "Apply it.", false: "Do not apply it." } },
+      inputs: { "gate.component": "the Op the gate belongs to", "gate.planDigest": "the plan the gate binds" },
+      deciders: [{ kind: "quorum", count: 1 }],
+    },
+  },
+};
+
+const command = defaultChantCommand();
+let root: string;
+
+const chant = (...args: string[]): Record<string, unknown> => {
+  let out: string;
+  try {
+    out = execFileSync(command[0], [...command.slice(1), ...args], { cwd: root, encoding: "utf-8", env: { ...process.env, NO_COLOR: "1" }, stdio: ["ignore", "pipe", "pipe"] });
+  } catch (e) {
+    out = String((e as { stdout?: string }).stdout ?? "");
+  }
+  return JSON.parse(out) as Record<string, unknown>;
+};
+
+const answersInTree = (): string[] => (existsSync(join(root, "answers")) ? readdirSync(join(root, "answers")).filter((f) => f.endsWith(".md")) : []);
+
+beforeAll(() => {
+  root = workspace(POINTS);
+  vi.stubEnv("CI", "");
+});
+
+afterAll(() => {
+  vi.unstubAllEnvs();
+  cleanScratch();
+});
+
+describe("a gate-point decision through the chant bin (#3816)", () => {
+  test("waits on the open question, then passes on a person's answer, once per answer and plan", async () => {
+    const port = memoryGateLedgerPort();
+    const asker = chantGatePointAsker({ command, cwd: root });
+    const input = { op: "tf-apply", gate: "approve-apply", point: { name: "prod-apply" }, planDigest: PLAN, now: "2026-10-11T13:00:00.000Z" };
+
+    const first = await evaluatePointGate(port, asker, input);
+    expect(first).toMatchObject({ satisfied: false, recorded: true, waiting: { point: "prod-apply", state: "escalated", subject: "gate:tf-apply/approve-apply" } });
+    const waiting = first as Extract<PointGateCheck, { waiting: unknown }>;
+    expect(port.appended).toEqual([expect.objectContaining({ op: "tf-apply", gate: "approve-apply", planDigest: PLAN, answer: { point: "prod-apply", id: waiting.waiting.id, path: waiting.waiting.path } })]);
+
+    // Asked again while open, the standing pending fact is reused.
+    expect(await evaluatePointGate(port, asker, input)).toMatchObject({ satisfied: false, recorded: false });
+
+    expect(chant("workspace", "points", "answer", waiting.waiting.id, "--answer", "yes", "--by", "alice")).toMatchObject({ written: true, question: { state: "answered" } });
+
+    const passed = await evaluatePointGate(port, asker, input);
+    expect(passed).toMatchObject({ satisfied: true, recorded: true, resolution: { resolvedBy: "alice", planDigest: PLAN, answer: { id: waiting.waiting.id, answer: true, decider: "quorum", answeredBy: ["alice"] } } });
+    expect(await evaluatePointGate(port, asker, input)).toMatchObject({ satisfied: true, recorded: false });
+    expect(port.resolved).toHaveLength(1);
+  }, 120_000);
+
+  test("a point with store ledger holds the question on chant/lifecycle, and an answer it does not pass on refuses", async () => {
+    const port = memoryGateLedgerPort();
+    const asker = chantGatePointAsker({ command, cwd: root });
+    const before = answersInTree();
+    const input = { op: "ledger-apply", gate: "approve-apply", point: { name: "prod-apply", store: "ledger" as const }, planDigest: PLAN };
+
+    const first = (await evaluatePointGate(port, asker, input)) as Extract<PointGateCheck, { waiting: unknown }>;
+    expect(first.waiting.state).toBe("escalated");
+    expect(answersInTree()).toEqual(before);
+
+    chant("workspace", "points", "answer", first.waiting.id, "--answer", "no", "--by", "alice");
+    const refused = await evaluatePointGate(port, asker, input);
+    expect(refused).toMatchObject({ satisfied: false, answer: { id: first.waiting.id, answer: false } });
+    expect("refused" in refused && refused.refused).toContain("passes only on true");
+  }, 120_000);
+});

package/src/point-decision.ts

@@ -0,0 +1,280 @@
+/**
+ * The decision for a gate that asks a decision point (#3170), for a tool that
+ * runs from one bundled file (#3816).
+ *
+ * `@intentius/chant/point-decision` holds chant's rule for such a gate: ask
+ * the point with the gate's `gate.*` facts ({@link gatePointInputs}, under
+ * {@link gateSubject}), then
+ *
+ * - the question is open: record a pending fact that cites it, once per
+ *   question and plan, and wait;
+ * - it is answered with an answer the gate passes on (`pass`, default yes):
+ *   record a resolution that cites the answer, once per answer and plan, and
+ *   go through;
+ * - it is answered otherwise: refuse, naming the record.
+ *
+ * Both halves are injected. A {@link GatePointAsker} asks the point (chant's
+ * own, `workspaceGatePointAsker` in `@intentius/chant/op`, reads the
+ * workspace; {@link chantGatePointAsker} runs the chant bin instead), and a
+ * {@link PointGateLedgerPort} reads and appends the gate ledger. So this module imports no workspace, CLI,
+ * TypeScript, zod or git code, which `point-decision-bundle.test.ts` holds
+ * it to. `./op/gate-point-run.ts` re-exports it, and chant's own runs decide
+ * by it.
+ */
+
+import { execFile } from "node:child_process";
+import { isPendingGateExpired, latestPendingGate } from "./lifecycle/gate-ledger-select";
+import { DEFAULT_GATE_EXPIRY, resolveApprovalUrl } from "./lifecycle/gate-pending";
+import { samePlanDigest } from "./lifecycle/plan-digest";
+import type { GateAnswerRef, GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
+import { parseDuration } from "./op/duration";
+import type { GateLedgerPort } from "./op/gate";
+import { DEFAULT_GATE_POINT_PASS, defaultGatePointStore, gatePointInputs, gateSubject, type GatePoint, type GatePointFacts, type GatePointStore } from "./op/gate-point";
+import type { WaitingPoint } from "./op/steward-points";
+
+export {
+  DEFAULT_GATE_POINT_PASS,
+  GATE_POINT_INPUTS,
+  defaultGatePointStore,
+  gatePointInputs,
+  gatePointOf,
+  gatePointProblems,
+  gateSubject,
+  type GatePoint,
+  type GatePointFacts,
+  type GatePointStore,
+} from "./op/gate-point";
+export type { GateAnswerRef, GateResolutionRecord, GateResolutionInput, PendingGateInput, PendingGateRecord } from "./lifecycle/gate-ledger";
+export type { WaitingPoint } from "./op/steward-points";
+
+/**
+ * The gate ledger as {@link evaluatePointGate} uses it: read an op's facts,
+ * append a pending fact, append a resolution. chant's own is
+ * `gitGateLedgerPort` (`@intentius/chant/op`), on `chant/lifecycle`.
+ */
+export type PointGateLedgerPort = Pick<GateLedgerPort, "read" | "appendPending" | "appendResolution">;
+
+/** The question a gate's point was asked, as the gate reads it. */
+export interface GatePointQuestion {
+  /** The answer record's id: what `points answer` takes. */
+  id: string;
+  point: string;
+  /** The record, from the repository root. */
+  path: string;
+  state: "escalated" | "proposed" | "answered";
+  /** The answer, or null while the question is open. */
+  answer: string | boolean | null;
+  /** The decider that gave the recorded state: table, model or quorum. */
+  decider: string;
+  answeredBy: string[];
+  subject: string | null;
+  /** The steward whose turn asked it, or null. */
+  steward: string | null;
+}
+
+/** What a gate asks its point with. */
+export interface GatePointRequest {
+  point: string;
+  /** The authored inputs, references resolved. */
+  inputs: Record<string, unknown>;
+  facts: GatePointFacts;
+  /** What the answer record's `constrains` names: {@link gateSubject}. */
+  subject: string;
+  /** Where the question goes, as the gate's `point.store` declares it (#3815). Undefined leaves it to the asker. */
+  store?: GatePointStore;
+}
+
+/**
+ * How a gate asks its point. A test passes a stub; `workspaceGatePointAsker`
+ * (`@intentius/chant/op`) is chant's, which asks through the workspace. A tool
+ * built into one file passes its own, such as one that runs the chant bin.
+ */
+export interface GatePointAsker {
+  ask(request: GatePointRequest): Promise<GatePointQuestion>;
+}
+
+/** What the run needs to decide a gate that asks a point. */
+export interface PointGateInput {
+  op: string;
+  gate: string;
+  point: GatePoint;
+  /** The authored inputs, references resolved. */
+  inputs?: Record<string, unknown>;
+  description?: string;
+  timeout?: string;
+  runId?: string;
+  planDigest?: string;
+  /** The environment the run was started for: the `gate.env` input. Op gate facts on the ledger record none. */
+  env?: string;
+  now?: string;
+}
+
+/** What reaching a gate that asks a point decided. */
+export type PointGateCheck =
+  | {
+      satisfied: true;
+      /** The resolution that cites the answer: this run's, or one an earlier run wrote for the same answer and plan. */
+      resolution: GateResolutionRecord;
+      answer: GateAnswerRef;
+      /** Whether this run appended the resolution. */
+      recorded: boolean;
+      pushed?: boolean;
+      pushWarning?: string;
+    }
+  | {
+      satisfied: false;
+      /** The question is answered, with an answer the gate does not pass on. */
+      refused: string;
+      answer: GateAnswerRef;
+    }
+  | {
+      satisfied: false;
+      /** The open question the run waits on. */
+      waiting: WaitingPoint;
+      /** The pending fact that cites it. */
+      pending: PendingGateRecord;
+      recorded: boolean;
+      pushed?: boolean;
+      pushWarning?: string;
+    };
+
+/** Who a resolution written for an answer is by: the people who answered, or the decider that did. */
+function resolvedByOf(q: GatePointQuestion): string {
+  return q.answeredBy.length > 0 ? q.answeredBy.join(", ") : q.decider;
+}
+
+/** Decide a gate that asks a point: ask it, then record the pending fact or the resolution that cites the answer. */
+export async function evaluatePointGate(port: PointGateLedgerPort, asker: GatePointAsker, input: PointGateInput): Promise<PointGateCheck> {
+  const now = input.now ?? new Date().toISOString();
+  const facts: GatePointFacts = { component: input.op, name: input.gate, env: input.env ?? null, planDigest: input.planDigest ?? null };
+  const q = await asker.ask({ point: input.point.name, inputs: input.inputs ?? {}, facts, subject: gateSubject(input.op, input.gate, input.env), ...(input.point.store ? { store: input.point.store } : {}) });
+  const ref: GateAnswerRef = { point: q.point, id: q.id, path: q.path };
+
+  if (q.state === "answered" && q.answer !== null) {
+    const answer: GateAnswerRef = { ...ref, answer: q.answer, decider: q.decider, ...(q.answeredBy.length > 0 ? { answeredBy: q.answeredBy } : {}) };
+    const pass = input.point.pass ?? DEFAULT_GATE_POINT_PASS;
+    if (!pass.includes(q.answer)) {
+      return {
+        satisfied: false,
+        answer,
+        refused:
+          `decision point ${q.point} answered ${JSON.stringify(q.answer)} (${q.id}, by ${resolvedByOf(q)}), and gate "${input.gate}" passes only on ${pass.map((a) => JSON.stringify(a)).join(" or ")}. ` +
+          `To ask again, take the answer back: chant workspace points retract ${q.id} --by <name>`,
+      };
+    }
+    const ledger = await port.read(input.op);
+    const standing = ledger.resolutions.find(
+      (r) => r.gate === input.gate && r.answer?.id === q.id && r.environment === undefined && samePlanDigest(r.planDigest, input.planDigest),
+    );
+    if (standing) return { satisfied: true, resolution: standing, answer, recorded: false };
+    if (!port.appendResolution) throw new Error(`gate "${input.gate}" asks decision point ${q.point}, and this gate ledger cannot record the resolution that cites its answer`);
+    const { record, pushed, pushWarning } = await port.appendResolution({
+      op: input.op,
+      gate: input.gate,
+      resolvedBy: resolvedByOf(q),
+      timestamp: now,
+      note: `answered through decision point ${q.point} (${q.id})`,
+      ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+      approver: { kind: q.decider === "quorum" || q.answeredBy.length > 0 ? "human" : "agent" },
+      answer,
+    });
+    return { satisfied: true, resolution: record, answer, recorded: true, pushed, ...(pushWarning ? { pushWarning } : {}) };
+  }
+
+  const waiting: WaitingPoint = { id: q.id, point: q.point, state: q.state === "proposed" ? "proposed" : "escalated", path: q.path, subject: q.subject, steward: q.steward };
+  const ledger = await port.read(input.op);
+  const standing = latestPendingGate(ledger.pending.filter((p) => p.environment === undefined), input.gate);
+  if (standing && !isPendingGateExpired(standing, now) && samePlanDigest(standing.planDigest, input.planDigest) && standing.answer?.id === q.id) {
+    return { satisfied: false, waiting, pending: standing, recorded: false };
+  }
+  const url = resolveApprovalUrl();
+  const { record, pushed, pushWarning } = await port.appendPending({
+    op: input.op,
+    gate: input.gate,
+    timestamp: now,
+    expiresAt: new Date(new Date(now).getTime() + parseDuration(input.timeout ?? DEFAULT_GATE_EXPIRY)).toISOString(),
+    ...(input.description ? { description: input.description } : {}),
+    ...(input.runId ? { runId: input.runId } : {}),
+    ...(url ? { url } : {}),
+    ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+    answer: ref,
+  });
+  return { satisfied: false, waiting, pending: record, recorded: true, pushed, ...(pushWarning ? { pushWarning } : {}) };
+}
+
+/** How {@link chantGatePointAsker} runs chant. */
+export interface ChantGatePointAskerOptions {
+  /** The chant command and its leading arguments, such as `["npx", "chant"]` or `[process.execPath, "/path/to/chant"]`. */
+  command: string[];
+  /** Where the workspace is found. Defaults to the working directory. */
+  cwd?: string;
+}
+
+/** Run chant with `args` and parse the JSON document it prints. A refusal is a document too, and exits 1. */
+function runChantJson(opts: ChantGatePointAskerOptions, args: string[]): Promise<Record<string, unknown>> {
+  const [bin, ...lead] = opts.command;
+  return new Promise((resolve, reject) => {
+    execFile(bin, [...lead, ...args], { cwd: opts.cwd, encoding: "utf-8", maxBuffer: 16 * 1024 * 1024, env: { ...process.env, NO_COLOR: "1" } }, (err, stdout, stderr) => {
+      try {
+        resolve(JSON.parse(stdout) as Record<string, unknown>);
+      } catch {
+        reject(new Error(`chant ${args.slice(0, 3).join(" ")} printed no JSON document${err ? `: ${err.message}` : ""}${stderr ? `\n${stderr.trim()}` : ""}`));
+      }
+    });
+  });
+}
+
+function refusal(what: string, doc: Record<string, unknown>): Error | undefined {
+  const e = doc.error as { code?: string; message?: string } | undefined;
+  return e ? new Error(`${what}: ${e.code}: ${e.message}`) : undefined;
+}
+
+/**
+ * A {@link GatePointAsker} that runs the chant bin, for a tool that bundles
+ * this module and not the workspace code (#3816). It reads the point's
+ * declared inputs with `chant workspace points --json`, passes the gate's
+ * `gate.*` ones ({@link gatePointInputs}), and asks with `chant workspace
+ * points ask <point> --inputs <json> --subject <gate> --json`, with `--store`
+ * from the gate's `point.store` or, naming none, the ledger in a CI job
+ * ({@link defaultGatePointStore}). chant calls no model here, so a point's
+ * model decider is not asked and its question goes to people; a table and a
+ * quorum decide as in chant's own runs.
+ */
+export function chantGatePointAsker(opts: ChantGatePointAskerOptions): GatePointAsker {
+  return {
+    async ask(request) {
+      const listed = await runChantJson(opts, ["workspace", "points", "--json"]);
+      const bad = refusal(`decision point ${request.point}`, listed);
+      if (bad) throw bad;
+      const point = (listed.points as { name: string; inputs: { name: string }[] }[] | undefined)?.find((p) => p.name === request.point);
+      if (!point) throw new Error(`gate "${request.facts.name}" asks decision point ${request.point}, and no points file declares it`);
+      const inputs = gatePointInputs(request.point, point.inputs.map((i) => i.name), request.facts, request.inputs);
+      const store = request.store ?? defaultGatePointStore();
+      const doc = await runChantJson(opts, ["workspace", "points", "ask", request.point, "--inputs", JSON.stringify(inputs), "--subject", request.subject, ...(store ? ["--store", store] : [])]);
+      const failed = refusal(`decision point ${request.point}`, doc);
+      if (failed) throw failed;
+      const q = doc.question as {
+        id: string;
+        point: string;
+        path: string;
+        state: GatePointQuestion["state"];
+        answer: string | boolean | null;
+        decider: { kind?: unknown };
+        answeredBy: string[];
+        subject: string | null;
+        askedBy: { steward: string } | null;
+      };
+      return {
+        id: q.id,
+        point: q.point,
+        path: q.path,
+        state: q.state,
+        answer: q.state === "answered" ? q.answer : null,
+        decider: typeof q.decider?.kind === "string" ? q.decider.kind : "quorum",
+        answeredBy: q.answeredBy ?? [],
+        subject: q.subject,
+        steward: q.askedBy?.steward ?? null,
+      };
+    },
+  };
+}

package/src/pr-forge.test.ts

@@ -613,3 +613,65 @@ describe("forgeTargetFromEnv (#3759)", () => {
     expect(() => forgeTargetFromEnv({})).toThrow(/forge is not known/);
   });
 });
+
+describe("addComment and findIssue (#3818)", () => {
+  const gh = { apiBase: "https://api.github.com", repo: "acme/infra", token: "t0k" };
+
+  test("addComment posts a new comment every time, with no read and no marker", async () => {
+    const { fetch, calls } = fakeFetch({ "POST /repos/acme/infra/issues/12/comments": { id: 9, html_url: "https://h/9" } });
+    const forge = githubForge({ ...gh, fetch });
+    expect(await forge.addComment(12, "terragucci: locked")).toEqual({ id: 9, url: "https://h/9" });
+    await forge.addComment(12, "terragucci: locked");
+    expect(calls.map((c) => c.method)).toEqual(["POST", "POST"]);
+    expect(calls[0].body).toEqual({ body: "terragucci: locked" });
+  });
+
+  test("addComment on Forgejo and GitLab", async () => {
+    const fj = fakeFetch({ "POST /api/v1/repos/acme/infra/issues/4/comments": { id: 2, html_url: "https://cb/2" } });
+    expect(await forgejoForge({ ...gh, apiBase: "https://codeberg.org/api/v1", host: "codeberg.org", fetch: fj.fetch }).addComment(4, "hi")).toEqual({ id: 2, url: "https://cb/2" });
+    const gl = fakeFetch({ "POST /api/v4/projects/42/merge_requests/5/notes": { id: 77, body: "hi" } });
+    const r = await gitlabForge({ apiBase: "https://gl/api/v4", project: "42", token: "t", fetch: gl.fetch }).addComment(5, "hi");
+    expect(r).toEqual({ id: 77 });
+    expect(gl.calls).toHaveLength(1);
+    expect(gl.calls[0].body).toEqual({ body: "hi" });
+  });
+
+  test("trackIssue says when the issue was opened", async () => {
+    const open = { number: 8, title: "Drift", body: "<!-- d -->\nold", html_url: "https://h/issues/8", created_at: "2026-10-01T00:00:00Z" };
+    const upd = fakeFetch({ "GET /repos/acme/infra/issues": [open], "PATCH /repos/acme/infra/issues/8": { ...open, body: "<!-- d -->\nnew" } });
+    expect(await githubForge({ ...gh, fetch: upd.fetch }).trackIssue("<!-- d -->", { title: "Drift", body: "<!-- d -->\nnew" })).toEqual({
+      action: "updated", number: 8, url: "https://h/issues/8", created: "2026-10-01T00:00:00Z",
+    });
+    const made = fakeFetch({ "GET /repos/acme/infra/issues": [], "POST /repos/acme/infra/issues": { ...open, number: 9, html_url: "https://h/issues/9", created_at: "2026-10-11T00:00:00Z" } });
+    expect(await githubForge({ ...gh, fetch: made.fetch }).trackIssue("<!-- d -->", { title: "Drift", body: "<!-- d -->\nb" })).toMatchObject({ action: "opened", number: 9, created: "2026-10-11T00:00:00Z" });
+    const gl = fakeFetch({ "GET /api/v4/projects/42/issues": [{ iid: 3, title: "Drift", description: "<!-- d -->\nold", web_url: "https://gl/i/3", created_at: "2026-09-30T00:00:00Z" }] });
+    const r = await gitlabForge({ apiBase: "https://gl/api/v4", project: "42", token: "t", fetch: gl.fetch }).trackIssue("<!-- d -->", null);
+    expect(r).toEqual({ action: "left", number: 3, url: "https://gl/i/3", created: "2026-09-30T00:00:00Z" });
+  });
+
+  test("findIssue reads the oldest open match with no write and no token", async () => {
+    const { fetch, calls } = fakeFetch({
+      "GET /repos/acme/infra/issues": [
+        { number: 5, title: "PR", body: "<!-- d -->", pull_request: {} },
+        { number: 7, title: "newer", body: "<!-- d -->\nb", user: { login: "bot" }, created_at: "2026-10-05T00:00:00Z", html_url: "https://h/issues/7" },
+        { number: 6, title: "planted", body: "<!-- d -->\nx", user: { login: "mallory" }, created_at: "2026-10-04T00:00:00Z" },
+      ],
+    });
+    const forge = githubForge({ apiBase: "https://api.github.com", repo: "acme/infra", fetch });
+    expect(await forge.findIssue("<!-- d -->", { author: "bot" })).toEqual({ number: 7, title: "newer", body: "<!-- d -->\nb", created: "2026-10-05T00:00:00Z", url: "https://h/issues/7" });
+    expect((await forge.findIssue("<!-- d -->"))?.number).toBe(6);
+    expect(await forge.findIssue("<!-- none -->")).toBeUndefined();
+    expect(calls.every((c) => c.method === "GET" && !("Authorization" in c.headers))).toBe(true);
+  });
+
+  test("findIssue on GitLab and Forgejo, tokenless", async () => {
+    const gl = fakeFetch({ "GET /api/v4/projects/42/issues": [{ iid: 3, title: "Drift", description: "<!-- d -->\nb", web_url: "https://gl/i/3", created_at: "2026-09-30T00:00:00Z" }] });
+    const g = gitlabForge({ apiBase: "https://gl/api/v4", project: "42", fetch: gl.fetch });
+    expect(await g.findIssue("<!-- d -->")).toEqual({ number: 3, title: "Drift", body: "<!-- d -->\nb", created: "2026-09-30T00:00:00Z", url: "https://gl/i/3" });
+    expect(Object.keys(gl.calls[0].headers)).toEqual([]);
+    const fj = fakeFetch({ "GET /api/v1/repos/acme/infra/issues": [{ number: 2, title: "t", body: "<!-- d -->", created_at: "2026-10-02T00:00:00Z" }] });
+    const f = forgejoForge({ apiBase: "https://codeberg.org/api/v1", repo: "acme/infra", host: "codeberg.org", fetch: fj.fetch });
+    expect((await f.findIssue("<!-- d -->"))?.created).toBe("2026-10-02T00:00:00Z");
+    expect(fj.calls[0].headers.Authorization).toBeUndefined();
+  });
+});

package/src/pr-forge.ts

@@ -85,6 +85,25 @@ export interface FoundComment {
   url?: string;
 }
 
+/** What {@link PrForge.addComment} posted. */
+export interface AddedComment {
+  /** The new comment's or note's id. */
+  id: number;
+  /** Its web URL, when the forge's answer carries one (GitHub and Forgejo do; a GitLab note does not). */
+  url?: string;
+}
+
+/** An open tracking issue {@link PrForge.findIssue} read back. */
+export interface FoundIssue {
+  /** The issue's number (GitHub, Forgejo) or iid (GitLab). */
+  number: number;
+  title: string;
+  body: string;
+  /** When the issue was opened: the forge's `created_at`, an ISO 8601 string. */
+  created?: string;
+  url?: string;
+}
+
 /** A finding to keep in a tracking issue. `body` carries the marker. */
 export interface IssueFinding {
   title: string;
@@ -123,6 +142,8 @@ export interface IssueResult {
   /** The issue's number (GitHub, Forgejo) or iid (GitLab). */
   number?: number;
   url?: string;
+  /** When the issue was opened (the forge's `created_at`, ISO 8601), for an issue that exists after the call or was just closed. */
+  created?: string;
 }
 
 export interface PrForge {
@@ -155,6 +176,13 @@ export interface PrForge {
    * GitLab's system notes are skipped.
    */
   findComment(pr: number, marker: string, opts?: MarkerMatch): Promise<FoundComment | undefined>;
+  /**
+   * Post a new comment on pull request `pr` (a new note on merge request
+   * `pr`). No marker is looked for or required, and an earlier comment is
+   * never edited: every call adds one. For replies, where
+   * {@link upsertComment} would overwrite the last.
+   */
+  addComment(pr: number, body: string): Promise<AddedComment>;
   setStatus(sha: string, status: ForgeStatus): Promise<void>;
   /**
    * Keep one OPEN tracking issue for `marker` in line with `finding`: open
@@ -164,6 +192,13 @@ export interface PrForge {
    * taken for issues. When several match, the oldest is kept.
    */
   trackIssue(marker: string, finding: IssueFinding | null, opts?: TrackIssueOptions): Promise<IssueResult>;
+  /**
+   * The OPEN issue {@link trackIssue} would keep for `marker`: the oldest one
+   * {@link MarkerMatch} finds, `author` honoured, pull requests left out.
+   * Undefined when there is none. Writes nothing, so a client built without a
+   * token reads a public repository's issue with it.
+   */
+  findIssue(marker: string, opts?: MarkerMatch): Promise<FoundIssue | undefined>;
   /**
    * {@link trackIssue} by prefix for a finding, without the body check,
    * resolving to the issue's web URL. `reconcilePr`'s `issue` mode's form.
@@ -247,6 +282,8 @@ interface Thread {
   title?: string;
   author?: string;
   url?: string;
+  /** An issue's `created_at`. */
+  created?: string;
 }
 
 /** The calls each forge makes for the shared comment and issue recipes. */
@@ -298,7 +335,8 @@ async function upsertCommentWith(t: Threads, pr: number, marker: string, body: s
 async function trackIssueWith(t: Threads, marker: string, finding: IssueFinding | null, opts: TrackIssueOptions, check: boolean): Promise<IssueResult> {
   if (finding && check) checkMarker("issue", marker, finding.body, opts.match);
   const mine = (await t.openIssues(marker)).filter(ownedBy(marker, opts)).sort((a, b) => a.id - b.id)[0];
-  const at = (i: Thread | undefined): Omit<IssueResult, "action"> => (i ? { number: i.id, ...(i.url ? { url: i.url } : {}) } : {});
+  const at = (i: Thread | undefined): Omit<IssueResult, "action"> =>
+    i ? { number: i.id, ...(i.url ? { url: i.url } : {}), ...(i.created ? { created: i.created } : {}) } : {};
   if (finding === null) {
     if (!mine) return { action: "none" };
     if (!opts.closeOnClear) return { action: "left", ...at(mine) };
@@ -318,8 +356,17 @@ function sameIssue(open: IssueFinding, finding: IssueFinding, sameWhen: TrackIss
 }
 
 /** The recipes every client shares, over its own {@link Threads}. */
-function threadCalls(t: Threads): Pick<PrForge, "upsertComment" | "upsertNote" | "findComment" | "trackIssue" | "upsertIssue"> {
+function threadCalls(t: Threads): Pick<PrForge, "upsertComment" | "upsertNote" | "findComment" | "addComment" | "trackIssue" | "findIssue" | "upsertIssue"> {
   return {
+    async addComment(pr, body) {
+      const made = await t.addComment(pr, body);
+      return { id: made?.id ?? 0, ...(made?.url ? { url: made.url } : {}) };
+    },
+    async findIssue(marker, opts = {}) {
+      if (!marker) throw new Error("the issue needs a marker to be found");
+      const i = (await t.openIssues(marker)).filter(ownedBy(marker, opts)).sort((a, b) => a.id - b.id)[0];
+      return i ? { number: i.id, title: i.title ?? "", body: i.body, ...(i.created ? { created: i.created } : {}), ...(i.url ? { url: i.url } : {}) } : undefined;
+    },
     async findComment(pr, marker, opts = {}) {
       const c = await ownComment(t, pr, marker, opts);
       return c ? { id: c.id, body: c.body, ...(c.url ? { url: c.url } : {}) } : undefined;
@@ -336,7 +383,8 @@ export interface GithubForgeOptions {
   apiBase: string;
   /** `owner/name`. */
   repo: string;
-  token: string;
+  /** Without one, no credential is sent: enough to read a public repository ({@link PrForge.findComment}, {@link PrForge.findIssue}). */
+  token?: string;
   /** The forge's host, for naming reviewers. Default github.com. */
   host?: string;
   runUrl?: string;
@@ -354,8 +402,8 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
   const api = transport(
     opts.apiBase,
     kind === "github"
-      ? { Authorization: `Bearer ${opts.token}`, Accept: "application/vnd.github+json" }
-      : { Authorization: `token ${opts.token}`, Accept: "application/json" },
+      ? { ...(opts.token ? { Authorization: `Bearer ${opts.token}` } : {}), Accept: "application/vnd.github+json" }
+      : { ...(opts.token ? { Authorization: `token ${opts.token}` } : {}), Accept: "application/json" },
     opts.fetch ?? (globalThis.fetch as unknown as ForgeFetch),
   );
   const repo = `/repos/${opts.repo}`;
@@ -368,7 +416,8 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
     if (id === undefined) return undefined;
     const author = loginOf(v);
     const url = str(v.html_url);
-    return { id, body: str(v.body) ?? "", ...(str(v.title) !== undefined ? { title: str(v.title) } : {}), ...(author ? { author } : {}), ...(url ? { url } : {}) };
+    const created = str(v.created_at);
+    return { id, body: str(v.body) ?? "", ...(created ? { created } : {}), ...(str(v.title) !== undefined ? { title: str(v.title) } : {}), ...(author ? { author } : {}), ...(url ? { url } : {}) };
   };
   const threads = (items: unknown[]): Thread[] => items.map(thread).filter((t): t is Thread => t !== undefined);
   const t: Threads = {
@@ -452,7 +501,8 @@ export interface GitlabForgeOptions {
   apiBase: string;
   /** `$CI_PROJECT_ID`, or the URL-encoded path. */
   project: string;
-  token: string;
+  /** Without one, no credential is sent: enough to read a public project ({@link PrForge.findComment}, {@link PrForge.findIssue}). */
+  token?: string;
   /**
    * The header the token goes in: `PRIVATE-TOKEN` (the default) for an
    * access token, `JOB-TOKEN` for `CI_JOB_TOKEN`. One in the other's header
@@ -474,7 +524,7 @@ const GITLAB_STATE: Record<ForgeStatus["state"], string> = { pending: "pending",
  */
 export function gitlabForge(opts: GitlabForgeOptions): PrForge {
   const host = (opts.host ?? "gitlab.com").toLowerCase();
-  const api = transport(opts.apiBase, { [opts.tokenHeader ?? "PRIVATE-TOKEN"]: opts.token }, opts.fetch ?? (globalThis.fetch as unknown as ForgeFetch));
+  const api = transport(opts.apiBase, opts.token ? { [opts.tokenHeader ?? "PRIVATE-TOKEN"]: opts.token } : {}, opts.fetch ?? (globalThis.fetch as unknown as ForgeFetch));
   const project = `/projects/${encodeURIComponent(decodeURIComponent(opts.project))}`;
   const pageParams = (page: number) => `per_page=100&page=${page}`;
   const authorOf = (v: Record<string, unknown>): string | undefined => (isObject(v.author) ? str(v.author.username) : undefined);
@@ -491,7 +541,8 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
     if (id === undefined) return undefined;
     const author = authorOf(v);
     const url = str(v.web_url);
-    return { id, body: str(v.description) ?? "", ...(str(v.title) !== undefined ? { title: str(v.title) } : {}), ...(author ? { author } : {}), ...(url ? { url } : {}) };
+    const created = str(v.created_at);
+    return { id, body: str(v.description) ?? "", ...(created ? { created } : {}), ...(str(v.title) !== undefined ? { title: str(v.title) } : {}), ...(author ? { author } : {}), ...(url ? { url } : {}) };
   };
   const notes = `${project}/merge_requests`;
   const t: Threads = {

package/src/workspace/decide.ts

@@ -445,7 +445,9 @@ export interface AskPointOptions {
    * or the lifecycle ledger (#2786). Defaults to the ledger in a steward's
    * turn (`steward` given, or this process a steward's turn), since a steward
    * never writes the checkout, and to the tree otherwise. A question already
-   * held on the ledger is rewritten there whatever this says.
+   * held on the ledger is rewritten there whatever this says. Outside a
+   * steward's turn, `points ask --store ledger` and a gate's `point.store`
+   * reach it (#3815), for a checkout that does not outlive the run.
    */
   store?: "tree" | "ledger";
   /** The date written as asked_on, and answered_on for a table's answer, YYYY-MM-DD. Defaults to today, in UTC. */
@@ -823,7 +825,10 @@ async function findQuestion(cwd: string, kind: string | undefined, id: string):
   if (kinds.length === 0) throw new PointsWriteError("points-undeclared", "no record kind with an answers block is declared: name one with --kind, or declare one in chant.workspace.json");
   for (const k of kinds) {
     const opened = await openAnswers(k, cwd);
-    // A question a steward asked is on the ledger (#2786), and people's answer goes back there.
+    // A question a steward asked is on the ledger (#2786), and people's answer goes back there. So is
+    // one a CI job asked with --store ledger (#3815), from a checkout that is gone: fetch the
+    // branch first, so a clone that never ran the job finds the question.
+    await refreshLedger(opened.o.loaded.file);
     const read = await readWithLedger(opened.o);
     const target = read.before.find((e) => e.id === id);
     if (target && target.data !== null) return { opened, before: read.before, read, target: target as FoundQuestion["target"] };

package/src/workspace/points-cli.ts

@@ -304,7 +304,7 @@ export async function runWorkspacePoints(ctx: CommandContext): Promise<number> {
       if (!("value" in response)) return print(response);
       ask = responseAsk(response.value);
     }
-    return print(await askPoint({ cwd, point, inputs: inputs.value, candidates: given, subject: args.subject, kind: args.kind, ask, dryRun: args.dryRun }));
+    return print(await askPoint({ cwd, point, inputs: inputs.value, candidates: given, subject: args.subject, kind: args.kind, ask, ...(args.store ? { store: args.store } : {}), dryRun: args.dryRun }));
   }
   if (verb === "answer") {
     const id = args.extraPositional2;