@intentius/chant 0.124.30 → 0.124.32

package/src/workspace/pin-integrity.ts

@@ -28,6 +28,7 @@
 import { createHash } from "node:crypto";
 import { lstatSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { isWorkDir } from "../lifecycle/work-dir";
 
 export type IntegrityAlgorithm = "sha256" | "sha384" | "sha512";
 
@@ -39,7 +40,7 @@ export function parseIntegrity(value: string): { algorithm: IntegrityAlgorithm;
   return m ? { algorithm: m[1] as IntegrityAlgorithm, digest: m[2] } : undefined;
 }
 
-/** Directories a plugin hash never looks inside. */
+/** Directories a plugin hash never looks inside, with `.chant/work`, where work worktrees are (#2893). */
 const SKIPPED_DIRS = new Set(["node_modules", ".git"]);
 
 /** Thrown when a path can't be hashed: it is missing, or holds a symbolic link. */
@@ -50,7 +51,7 @@ function walk(dir: string, prefix: string, out: string[]): void {
     const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
     if (entry.isSymbolicLink()) throw new PinHashError(`${rel} is a symbolic link, which a pinned plugin may not contain`);
     if (entry.isDirectory()) {
-      if (!SKIPPED_DIRS.has(entry.name)) walk(join(dir, entry.name), rel, out);
+      if (!SKIPPED_DIRS.has(entry.name) && !isWorkDir(rel)) walk(join(dir, entry.name), rel, out);
     } else if (entry.isFile()) {
       out.push(rel);
     }

package/src/workspace/pr-report.schema.json

@@ -33,12 +33,12 @@
       "description": "The change-set digest of what this stage planned: computePlanDigest(\"change-set\", ...) over every member's { member, planDigest }. What the gate binds."
     },
     "status": {
-      "enum": ["planned", "plan-failed", "nothing", "applied", "failed", "refused"],
-      "description": "planned: every member planned (plan stage). plan-failed: a member failed to plan, so nothing can apply. nothing: no component deploys what the change touches. applied: every member applied. failed: a member failed to apply and its dependents did not run. refused: nothing applied, see refusal."
+      "enum": ["planned", "plan-failed", "nothing", "applied", "failed", "wave-applied", "refused", "waiting"],
+      "description": "planned: every member planned (plan stage). plan-failed: a member failed to plan, so nothing can apply. nothing: no component deploys what the change touches. applied: every member applied. failed: a member failed to apply and its dependents did not run. wave-applied (#4003, chant 0.124.32 and newer): with --wave-gate and --wave, the wave applied and a later wave is still to run. refused: nothing applied, see refusal. waiting (#3999): the approved plans applied except members held back after an upstream applied, which wait on an approval of the plan the last of rounds made."
     },
     "refusal": {
-      "enum": ["not-approved", "plan-changed", "not-a-reviewer", "no-pull-request"],
-      "description": "Why an apply refused. plan-changed: an approval stands for another digest, so the plan changed after review."
+      "enum": ["not-approved", "plan-changed", "not-a-reviewer", "author-approved", "no-pull-request", "wave-not-approved", "wave-plan-changed", "earlier-wave"],
+      "description": "Why an apply refused. plan-changed: an approval stands for another digest, so the plan changed after review. author-approved (#4000): under --require-review, an approval names the pull request's author or an author or committer of one of its commits. With --wave-gate (#4003, chant 0.124.32 and newer): wave-not-approved, a wave's new plan is not covered by the approved one and no approval of its gate stands for it; wave-plan-changed, an approval of its gate stands for another digest; earlier-wave, an earlier wave has work left or no record says it applied. The waves that applied before a wave refused stay applied; waves says which."
     },
     "message": { "type": "string", "description": "The refusal or failure as printed." },
     "resumed": {
@@ -54,6 +54,61 @@
       "description": "Added within contract version 1 by #4104, written by chant 0.124.30 and newer. Per dependency a member was planned against, the names of the outputs read from the deployed estate through its capability's outputs, sorted. A dependency outside the change is listed here too, and one whose stack is not deployed yet lists []. Outputs given with --seed-outputs, or carried from an earlier attempt's record, are not listed. Absent when no dependency was read, and on a resumed apply.",
       "additionalProperties": { "type": "array", "items": { "type": "string" } }
     },
+    "waveGate": {
+      "type": "string",
+      "description": "Added within contract version 1 by #4003, written by chant 0.124.32 and newer. pr-apply --wave-gate <name>: the apply runs a wave at a time, each planned after the one before it applied, and wave k waits on <name>-wave-<k> under op when its plan moved. Absent without it."
+    },
+    "waves": {
+      "type": "array",
+      "description": "With waveGate: each wave reached so far, in order, with the approval it applied or waits under.",
+      "items": {
+        "type": "object",
+        "required": ["wave", "components", "status", "approval", "gate", "digest"],
+        "properties": {
+          "wave": { "type": "integer", "minimum": 1, "description": "1-based, from selection.waves." },
+          "components": { "type": "array", "items": { "type": "string" }, "description": "The components planned in it on the run that reached it." },
+          "status": { "enum": ["applied", "failed", "plan-failed", "waiting"] },
+          "approval": { "enum": ["pull-request", "wave"], "description": "pull-request: the approved change set covers the wave's plan, and it applies under the pull request's approval (gate and digest are the report's). wave: its plan moved, and it needs an approval of its own gate for its new plan." },
+          "gate": { "type": "string", "description": "The gate it applied or waits under: the report's gate, or <waveGate>-wave-<k>." },
+          "digest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "The digest that gate binds: the report's digest, or the change-set digest of the wave's new plan." },
+          "approvedBy": { "type": "array", "items": { "type": "string" } },
+          "approved": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Waiting: an approval of the wave's gate stands for this other digest." },
+          "moved": { "type": "array", "items": { "type": "string" }, "description": "Why the approved change set does not cover the wave's plan, one line per member." }
+        }
+      }
+    },
+    "plannedOutputs": {
+      "type": "object",
+      "description": "Added within contract version 1 by #3999, written by chant 0.124.32 and newer. Per dependency in the change that a member was planned against, the names of the outputs its plan knows, sorted. An output a member reads that is not listed is known only after apply, and the member lists it under unknownInputs. Absent when no member read one.",
+      "additionalProperties": { "type": "array", "items": { "type": "string" } }
+    },
+    "rounds": {
+      "type": "array",
+      "description": "Added within contract version 1 by #3999. Apply stage: the rounds planned after an upstream applied, in order. A member whose plan read an upstream output that applied as another value, or was known only after apply, is held back and planned again against the outputs the apply left; each round has its own gate and digest. Absent when nothing was held.",
+      "items": {
+        "type": "object",
+        "required": ["round", "gate", "digest", "components", "approval", "status", "changeSet"],
+        "properties": {
+          "round": { "type": "integer", "minimum": 2 },
+          "gate": { "type": "string", "description": "The gate the round waits on: <gate>-round-<round>." },
+          "digest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "The change-set digest of what the round planned. What its gate binds." },
+          "components": { "type": "array", "items": { "type": "string" }, "description": "The components planned again, in apply order." },
+          "approval": {
+            "type": "object",
+            "required": ["status"],
+            "description": "Where the approval stands for digest, as the top-level approval.",
+            "properties": {
+              "status": { "enum": ["approved", "changed", "pending"] },
+              "approvedBy": { "type": "array", "items": { "type": "string" } },
+              "approved": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$" }
+            }
+          },
+          "status": { "enum": ["applied", "failed", "waiting", "plan-failed"] },
+          "message": { "type": "string", "description": "With waiting: why an approval that stands does not count under --require-review." },
+          "changeSet": { "type": "object", "description": "The change-set document the round planned. Its digest equals digest." }
+        }
+      }
+    },
     "approval": {
       "type": "object",
       "required": ["status"],
@@ -85,7 +140,7 @@
           "member": { "type": "string", "description": "The member's name in the change set: the root, for a terraform-family step." },
           "component": { "type": "string" },
           "planDigest": { "type": ["string", "null"], "description": "What a gate on this member alone binds. null when it failed to plan." },
-          "status": { "enum": ["planned", "plan-failed", "applied", "failed", "blocked"] },
+          "status": { "enum": ["planned", "plan-failed", "applied", "failed", "blocked", "waiting"], "description": "waiting (#3999): held back because its plan read an upstream output that applied as another value, or was known only after apply; it waits on an approval of its plan in rounds." },
           "counts": {
             "type": "object",
             "required": ["create", "update", "replace", "delete"],
@@ -100,8 +155,20 @@
           "inputsMoved": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "Apply stage: components this one depends on whose outputs changed when they applied. It applied the plan it was approved with; the next run plans it against the new values."
-          }
+            "description": "Apply stage: components this one depends on whose outputs changed when they applied. It applied the plan it was approved with; the next run plans it against the new values. Not written by chant 0.124.32 and newer, which holds such a member back instead (held, round)."
+          },
+          "unknownInputs": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "#3999: the upstream outputs its plan read that the change's plans could not say, as <component>.<output>, sorted. Known only after that upstream applies; the approval does not cover what this member does with them."
+          },
+          "buildInputs": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "#3999: the published artifact identities its plan read from a build in the same change, as <component>.publish.<field>, sorted. Known only after the build runs and never approved again: the build's provenance binds them, so the member applies without a later round."
+          },
+          "round": { "type": "integer", "minimum": 2, "description": "Apply stage (#3999): the round whose plan it applied or waits on, when not the first. planDigest and counts are that round's." },
+          "held": { "type": "string", "description": "Apply stage (#3999): why the first round's plan did not apply." }
         }
       }
     },

package/src/workspace/reason-codes.test.ts

@@ -44,6 +44,7 @@ import { PLANTABLE_REASON_CODES } from "./box-factory";
 import { BOX_FACTORY_ERROR_CODES } from "./box-factory-write";
 import { BOX_LISTING_ERROR_CODES } from "./box-listing";
 import { DECLARATION_WRITE_ERROR_CODES } from "./declaration-write";
+import { TRUST_WRITE_ERROR_CODES } from "./trust/trust-write";
 import { BOX_PUBLISH_ERROR_CODES } from "./box-publish";
 import { WRITE_LOCK_ERROR_CODES } from "./write-lock-cli";
 import { WIP_ERROR_CODES, WIP_WRITE_ERROR_CODES } from "./wip";
@@ -115,6 +116,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   PLANTABLE_REASON_CODES,
   BOX_LISTING_ERROR_CODES,
   DECLARATION_WRITE_ERROR_CODES,
+  TRUST_WRITE_ERROR_CODES,
   BOX_FACTORY_ERROR_CODES,
   BOX_PUBLISH_ERROR_CODES,
   WRITE_LOCK_ERROR_CODES,

package/src/workspace/reason-codes.ts

@@ -232,8 +232,8 @@ export const REASONS = {
   // A box that holds a credential (check, #2726). Each is also a WSP finding.
   "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",
   "box-capability-unbrokered": "A capability in a member's box block names no broker, so the box would hold its credential.",
-  // The credential fountain itself hands a persistent box (check, #2780). Also a WSP finding.
-  "box-fountain-callback-undeclared": "A box member builds a fountain Box, whose persistent sandbox fountain gives a callback token scoped to its owner, and the member's box block does not declare the fountain-callback capability brokered by fountain with scope owner.",
+  // The credential fountain itself hands a box (check, #2780). Also a WSP finding.
+  "box-fountain-callback-undeclared": "A box member builds a fountain Box, whose sandbox fountain gives a callback token scoped to its owner, and the member's box block does not declare the fountain-callback capability brokered by fountain with scope owner.",
   // A box's intent, the decision record its box block names (check, #2850). Each is also a WSP finding.
   "box-intent-unknown": "A box block names an intent, and no record of a declared kind named decision has that id.",
   "box-intent-unconstrained": "The decision record a box names as its intent constrains no member or path of this workspace: no member: entry for a declared member and no path: entry at, above or inside one's directory.",
@@ -271,6 +271,11 @@ export const REASONS = {
   // A declaration's members and hosts written through chant (member add|remove, host set, #3596): why the write was refused. Nothing is written.
   "member-exists": "member add names a member the declaration already has, with an entry other than the one given.",
   "member-unknown": "member remove names a member the declaration does not declare.",
+  // A runner entry of .chant/trust.json written through chant (trust runner add|remove, #3510): why the write was refused. Nothing is written.
+  "trust-config-invalid": ".chant/trust.json in the working tree is not JSON or does not match its schema, or the write would make it so.",
+  "trust-conflict": "--expect named a digest .chant/trust.json no longer has: another write changed it after the caller read it. The refusal names the digest it has now.",
+  "runner-exists": "trust runner add names a principal .chant/trust.json already lists with another key or class, or gives a key it lists for another principal.",
+  "runner-unknown": "trust runner remove names a principal .chant/trust.json lists no runner for.",
   // A box's factory written through chant (box factory set, #3600): why the write was refused. Nothing is written.
   "factory-member-unknown": "box factory set names a member the declaration does not declare.",
   "factory-box-missing": "box factory set names a member whose entry declares no box block, so it has no factory.",
@@ -314,8 +319,8 @@ export const REASONS = {
   "evidence-payload-type": "The envelope's payload type is not application/vnd.in-toto+json.",
   "evidence-statement-invalid": "The payload is not an in-toto Statement v1 with chant's runner-evidence predicate, or has a field the predicate does not define.",
   "evidence-runner-mismatch": "The statement names a runner other than the one whose key signed it.",
-  "runner-key-invalid": "The key given to evidence sign or runs sign is not an Ed25519 private key in PEM.",
-  "runner-key-is-signer": "The key given to evidence sign or runs sign is a person's key in the signers file. Evidence and run statements are signed by a service or CI identity.",
+  "runner-key-invalid": "The key given to evidence sign or runs sign is not an Ed25519 private key in PEM, or the key given to trust runner add is not an ssh-ed25519 public key or an Ed25519 key in PEM.",
+  "runner-key-is-signer": "The key given to evidence sign, runs sign or trust runner add is a person's key in the signers file, or trust runner add names a signer. Evidence and run statements are signed by a service or CI identity.",
   "runner-key-unlisted": "The policy at base lists no runner with the key given to evidence sign or runs sign.",
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",

package/src/workspace/run-event.schema.json

@@ -54,7 +54,9 @@
           "description": "github: a GitHub Actions run, also the spelling Forgejo Actions uses. gitlab: a CI pipeline. op: a steward's run, named by its Op run id. local: a run on the machine that started it, outside CI. chant: a pull-request job the chant runner ran (chant ci run, #4094), named by its Op run id; added within contract version 1 and written by chant 0.124.30 and newer, so a reader that switches on forge keeps a case for a value it does not know."
         },
         "repo": { "type": "string", "description": "The repository or project slug on the forge, when the environment named one." },
-        "url": { "type": "string", "description": "A link to the run, when the environment gave enough to build one." }
+        "url": { "type": "string", "description": "A link to the run, when the environment gave enough to build one." },
+        "jobId": { "type": "string", "description": "The forge's id for the job within the run: GITHUB_JOB on GitHub and Forgejo, CI_JOB_ID on GitLab. Added within contract 1 by #4156 and written by chant 0.124.32 and newer, only by chant ci run in a forge job." },
+        "attempt": { "type": "integer", "minimum": 1, "description": "The run's attempt, GITHUB_RUN_ATTEMPT on GitHub and Forgejo. Added within contract 1 by #4156 and written by chant 0.124.32 and newer, only by chant ci run in a forge job." }
       }
     },
     "settleStatus": {

package/src/workspace/status.schema.json

@@ -451,7 +451,9 @@
                         "properties": {
                           "forge": { "enum": ["github", "gitlab", "op", "local", "chant"], "description": "chant: a pull-request job the chant runner ran (chant ci run, #4094), added within contract 1 and written by chant 0.124.30 and newer." },
                           "repo": { "type": "string" },
-                          "url": { "type": "string" }
+                          "url": { "type": "string" },
+                          "jobId": { "type": "string", "description": "The forge's job id within the run. Added within contract 1 by #4156 and written by chant 0.124.32 and newer, only by chant ci run in a forge job." },
+                          "attempt": { "type": "integer", "minimum": 1, "description": "The run's attempt on GitHub and Forgejo. Added within contract 1 by #4156 and written by chant 0.124.32 and newer, only by chant ci run in a forge job." }
                         }
                       },
                       "failure": {

package/src/workspace/trust/trust-write.test.ts

@@ -0,0 +1,179 @@
+/**
+ * #3510: a runner entry of `.chant/trust.json` written through chant, with
+ * `--by` and `--expect` as the other working-tree writes take them, and read
+ * back by the readers that use runners: `readTrustPolicy`, `ciTagSigner` and
+ * `ci tick --source runs`.
+ *
+ * Each test works in its own temp repository (a bare origin where it pushes),
+ * and every key is a throwaway one. Nothing is written in process.cwd().
+ */
+
+import { execFileSync } from "node:child_process";
+import { createPublicKey, generateKeyPairSync } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { parseArgs } from "../../cli/parse-args";
+import { cleanScratch, contract, declaration, git, scratchDir, writeFiles } from "../__fixtures__/contract-repo";
+import { ciTagSigner, ciTick, opRunSigner } from "../ci-green";
+import { workingTreeSource } from "../record-source";
+import schema from "../trust-write.schema.json";
+import { runOpLocally } from "../../op/local-executor";
+import type { ActivityFn } from "../../op/activity-registry";
+import { sshFromEd25519 } from "./dsse";
+import { readTrustPolicy } from "./policy";
+import { trustDigest, trustWrite, type TrustWriteDocument, type TrustWriteRequest } from "./trust-write";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(schema);
+
+function runnerKey(): { pem: string; ssh: string } {
+  const { privateKey } = generateKeyPairSync("ed25519");
+  const jwk = createPublicKey(privateKey).export({ format: "jwk" }) as { x: string };
+  return { pem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(), ssh: sshFromEd25519(Buffer.from(jwk.x, "base64url")) };
+}
+
+function emptyRepo(files: Record<string, string> = {}): string {
+  const root = scratchDir("chant-trust-write-");
+  git(root, "init", "-q");
+  writeFiles(root, files);
+  return root;
+}
+
+function run(root: string, req: Omit<TrustWriteRequest, "cwd">): TrustWriteDocument {
+  const doc = trustWrite({ ...req, cwd: root });
+  expectValid(doc);
+  return doc;
+}
+
+const code = (doc: TrustWriteDocument) => ("error" in doc ? doc.error.code : null);
+const trustOf = (root: string) => JSON.parse(readFileSync(join(root, ".chant/trust.json"), "utf-8")) as Record<string, unknown>;
+const ok = (doc: TrustWriteDocument) => {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+};
+
+describe("trust runner add and remove (#3510)", () => {
+  test("add writes the entry and the runner role, remove takes both away, and a stale --expect is refused", () => {
+    const root = emptyRepo();
+    const bot = runnerKey();
+    writeFiles(root, { "keys/bot.pub": `${bot.ssh} bot@host\n` });
+
+    const added = ok(run(root, { action: "runner add", name: "ci:acme/app", key: "keys/bot.pub", by: "github:alex" }));
+    expect(added).toMatchObject({ action: "runner add", changed: true, previous: null, entry: { principal: "ci:acme/app", class: "runner", key: bot.ssh }, runnerRole: true, paths: [".chant/trust.json"] });
+    expect(added.previousDigest).toBe(trustDigest(null));
+    expect(added.digest).toBe(trustDigest(readFileSync(join(root, ".chant/trust.json"), "utf-8")));
+    expect(trustOf(root)).toEqual({ schema: 1, runners: [{ principal: "ci:acme/app", class: "runner", key: bot.ssh }], roles: { runner: ["ci:acme/app"] } });
+
+    // The same entry again changes nothing, and says so.
+    const again = ok(run(root, { action: "runner add", name: "ci:acme/app", key: bot.ssh, expect: added.digest }));
+    expect(again).toMatchObject({ changed: false, paths: [], digest: added.digest });
+
+    // A second runner, from a PEM private key, as a lobby holds it.
+    const lobby = runnerKey();
+    writeFileSync(join(root, "lobby.pem"), lobby.pem);
+    const second = ok(run(root, { action: "runner add", name: "studio:lobby", key: "lobby.pem", runnerClass: "service", expect: added.digest }));
+    expect(second).toMatchObject({ entry: { principal: "studio:lobby", class: "service", key: lobby.ssh }, runnerRole: false });
+
+    // The policy reads both, with the role for the runner only.
+    const policy = readTrustPolicy(workingTreeSource(root), null);
+    expect(policy.problems).toEqual([]);
+    expect(policy.runners.map((r) => r.principal)).toEqual(["ci:acme/app", "studio:lobby"]);
+    expect(policy.roles.runner).toEqual(["ci:acme/app"]);
+
+    const removed = ok(run(root, { action: "runner remove", name: "ci:acme/app", by: "github:alex", expect: second.digest }));
+    expect(removed).toMatchObject({ changed: true, previous: { principal: "ci:acme/app" }, entry: null, runnerRole: false });
+    expect(trustOf(root)).toEqual({ schema: 1, runners: [{ principal: "studio:lobby", class: "service", key: lobby.ssh }], roles: { runner: [] } });
+
+    // The digest the caller read is the one before the remove: refused, naming the last write.
+    const stale = run(root, { action: "runner remove", name: "studio:lobby", expect: second.digest });
+    expect(code(stale)).toBe("trust-conflict");
+    expect("conflict" in stale && stale.conflict).toMatchObject({ expected: second.digest, digest: removed.digest, lastWrite: { verb: "trust runner remove", by: "github:alex" } });
+    expect(trustOf(root).runners).toHaveLength(1);
+
+    expect(code(run(root, { action: "runner remove", name: "ci:acme/app" }))).toBe("runner-unknown");
+  });
+
+  test("an existing file is edited in place, keeping its other keys and layout", () => {
+    const text = `{\n  "schema": 1,\n  "roles": {\n    "admin": ["alex"]\n  },\n  "adopted": []\n}\n`;
+    const root = emptyRepo({ ".chant/trust.json": text });
+    const bot = runnerKey();
+    const doc = ok(run(root, { action: "runner add", name: "ci-bot", key: bot.ssh, expect: trustDigest(text) }));
+    const after = readFileSync(join(root, ".chant/trust.json"), "utf-8");
+    expect(after.startsWith(`{\n  "schema": 1,\n  "roles": {\n    "admin": ["alex"],`)).toBe(true);
+    expect(JSON.parse(after)).toEqual({ schema: 1, roles: { admin: ["alex"], runner: ["ci-bot"] }, adopted: [], runners: [{ principal: "ci-bot", class: "runner", key: bot.ssh }] });
+    expect(doc.digest).toBe(trustDigest(after));
+    // --dry-run reports the same and writes nothing.
+    const dry = ok(run(root, { action: "runner remove", name: "ci-bot", dryRun: true }));
+    expect(dry.changed).toBe(true);
+    expect(readFileSync(join(root, ".chant/trust.json"), "utf-8")).toBe(after);
+  });
+
+  test("refusals: a key that is not ssh-ed25519, a person's key, a taken key or principal, a broken file", () => {
+    const bot = runnerKey();
+    const person = runnerKey();
+    const root = emptyRepo({ ".chant/allowed_signers": `alex ${person.ssh}\n` });
+    expect(code(run(root, { action: "runner add", name: "x", key: "ssh-rsa AAAAB3NzaC1yc2E=" }))).toBe("runner-key-invalid");
+    expect(code(run(root, { action: "runner add", name: "x", key: "ssh-ed25519 AAAA" }))).toBe("runner-key-invalid");
+    expect(code(run(root, { action: "runner add", name: "x", key: "no-such-file.pub" }))).toBe("runner-key-invalid");
+    expect(code(run(root, { action: "runner add", name: "x", key: person.ssh }))).toBe("runner-key-is-signer");
+    expect(code(run(root, { action: "runner add", name: "alex", key: bot.ssh }))).toBe("runner-key-is-signer");
+    expect(code(run(root, { action: "runner add", name: "x" }))).toBe("write-usage-invalid");
+    expect(code(run(root, { action: "runner add", name: "x", key: bot.ssh, runnerClass: "person" }))).toBe("write-usage-invalid");
+    expect(code(run(root, { action: "runner add", name: "x", key: bot.ssh, expect: "abc" }))).toBe("write-usage-invalid");
+    expect(code(run(root, { action: "runner remove", name: "x", key: bot.ssh }))).toBe("write-usage-invalid");
+
+    ok(run(root, { action: "runner add", name: "ci-bot", key: bot.ssh }));
+    expect(code(run(root, { action: "runner add", name: "other", key: bot.ssh }))).toBe("runner-exists");
+    expect(code(run(root, { action: "runner add", name: "ci-bot", key: runnerKey().ssh }))).toBe("runner-exists");
+    expect(code(run(root, { action: "runner add", name: "ci-bot", key: bot.ssh, runnerClass: "service" }))).toBe("runner-exists");
+
+    writeFileSync(join(root, ".chant/trust.json"), `{ "schema": 2 }`);
+    expect(code(run(root, { action: "runner add", name: "y", key: runnerKey().ssh }))).toBe("trust-config-invalid");
+    expect(code(trustWrite({ cwd: scratchDir("chant-trust-nogit-"), action: "runner add", name: "y", key: bot.ssh }))).toBe("not-a-git-repository");
+  });
+
+  test("the command line takes --class, --key, --by and --expect", () => {
+    const args = parseArgs(["workspace", "trust", "runner", "add", "ci-bot", "--key", "k.pub", "--class", "service", "--by", "github:alex", "--expect", "a".repeat(64)]);
+    expect(args).toMatchObject({ key: "k.pub", runnerClass: "service", by: "github:alex", expect: "a".repeat(64) });
+  });
+});
+
+describe("a runner added through the write is trusted by the readers (#3510)", () => {
+  test("ci tick --source runs tags a commit from a run signed by a runner the write listed", async () => {
+    const bot = runnerKey();
+    const origin = scratchDir("chant-trust-write-origin-");
+    git(origin, "init", "-q", "--bare");
+    const root = scratchDir("chant-trust-write-ci-");
+    git(root, "init", "-q");
+    git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+    git(root, "remote", "add", "origin", origin);
+    const green = { branch: "main", phases: { test: ["test"] }, require: ["test"], source: "runs" };
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green } }), "app/a.txt": "a\n", "runner.pem": bot.pem });
+    writeFiles(root, { ".gitignore": "runner.pem\n" });
+
+    // Before the write, the key is refused.
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", "init");
+    expect(() => ciTagSigner(root, git(root, "rev-parse", "HEAD"), bot.pem)).toThrow(/lists no runner with this key/);
+
+    ok(run(root, { action: "runner add", name: "ci-bot", key: "runner.pem", by: "t" }));
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", "trust the ci-bot runner");
+    const head = git(root, "rev-parse", "HEAD");
+    expect(ciTagSigner(root, head, bot.pem).principal).toBe("ci-bot");
+
+    const pass = new Map<string, ActivityFn>([["step", async () => ({})]]);
+    const op = { name: "test", overview: "run test", labels: { Env: "ci" }, phases: [{ name: "Run", steps: [{ kind: "activity" as const, fn: "step", args: {} }] }] };
+    const { record } = await runOpLocally(op, pass, {}, undefined, { cwd: root, ledger: { cwd: root }, signRecord: opRunSigner(root, bot.pem) });
+    expect(record.gitSha).toBe(head);
+    git(root, "push", "-q", "origin", "main");
+    git(root, "push", "-q", "origin", "chant/lifecycle");
+
+    const tick = await ciTick({ cwd: root, runnerKey: bot.pem, now: new Date() });
+    expect(tick.made).toEqual([`ci/green/${head}`]);
+    expect(tick.signer).toBe("ci-bot");
+    expect(execFileSync("git", ["ls-remote", "--tags", origin], { encoding: "utf-8" })).toContain(`refs/tags/ci/green/${head}`);
+  });
+});