@intentius/chant 0.102.0 → 0.104.0

package/src/workspace/squash.ts

@@ -0,0 +1,198 @@
+/**
+ * Following a squash merge to the pull request's original commits (#3035,
+ * ws-092).
+ *
+ * A squash merge folds a pull request's commits into one new commit, and with
+ * them the trailers and signatures that joined each to its run and its work.
+ * The forge keeps the originals: GitHub and Forgejo both keep a pull
+ * request's head at `refs/pull/<n>/head` on the remote. A read that is asked
+ * to follow squashes (`--follow-squash`) looks for that ref locally, fetches
+ * the missing ones from `origin` in one `git fetch`, and keeps what it
+ * fetched under `refs/chant/pull/<n>/head`, so the next read needs no network.
+ * Without the flag nothing here runs, and a read never touches the network
+ * (studio-032 b: follow only when asked).
+ *
+ * A commit is followed as a squash when its subject ends with `(#<n>)`, as
+ * GitHub and Forgejo write a squash's subject, it has one parent, and the
+ * pull request's head is not already in its history (a merge commit or a
+ * rebase keeps the originals, so there is nothing to follow). Its original
+ * commits are the head's commits that the squash's parent does not have,
+ * oldest first. When the ref can't be read or fetched, the read says so and
+ * keeps its answer without them.
+ */
+
+import { execFileSync } from "node:child_process";
+
+/** A forge chant knows the pull request refs of. */
+export type Forge = "github" | "forgejo";
+
+/** Where a read keeps the pull request heads it fetched. */
+export const PULL_CACHE_PREFIX = "refs/chant/pull/";
+
+/** The remote a squash's pull request ref is fetched from. */
+export const SQUASH_REMOTE = "origin";
+
+/** How long one fetch of pull request refs may take. */
+const FETCH_TIMEOUT_MS = 60_000;
+
+function git(top: string, args: string[], opts: { input?: string; timeout?: number } = {}): string | undefined {
+  try {
+    return execFileSync("git", args, {
+      cwd: top,
+      encoding: "utf-8",
+      input: opts.input,
+      timeout: opts.timeout,
+      stdio: [opts.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+      maxBuffer: 256 * 1024 * 1024,
+      // A fetch must never wait on a credential prompt.
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+/** The pull request number a squash's subject ends with, `(#<n>)`, or null. */
+export function pullRequestOf(subject: string): number | null {
+  const m = subject.match(/\(#([0-9]+)\)\s*$/);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * The forge a remote URL points at: `github` for github.com and GitHub
+ * Enterprise hosts named for it, `forgejo` for codeberg.org and hosts named
+ * forgejo or gitea. Null for any other, which is still read at
+ * `refs/pull/<n>/head`, the ref both keep.
+ */
+export function forgeOf(url: string | null | undefined): Forge | null {
+  if (!url) return null;
+  const host = (url.match(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?([^/:]+)/i)?.[1] ?? url.match(/^(?:[^@/]*@)?([^/:]+):/)?.[1] ?? "").toLowerCase();
+  if (host === "github.com" || host.endsWith(".github.com") || /(^|[.-])github([.-]|$)/.test(host)) return "github";
+  if (host === "codeberg.org" || /(^|[.-])(forgejo|gitea)([.-]|$)/.test(host)) return "forgejo";
+  return null;
+}
+
+/** The pull request ref a forge keeps for `n`. GitHub and Forgejo keep the same one. */
+export function pullRef(_forge: Forge | null, n: number): string {
+  return `refs/pull/${n}/head`;
+}
+
+/** What following one squash commit found. */
+export interface SquashFollow {
+  /** The squash commit. */
+  sha: string;
+  pullRequest: number;
+  /** The forge `origin` points at, or null when it is none chant knows, or there is no `origin`. */
+  forge: Forge | null;
+  /** The local ref the pull request's head was read from, or null when none could be read. */
+  ref: string | null;
+  /** The pull request's head commit, or null. */
+  head: string | null;
+  /** Whether this read fetched the ref from the remote. */
+  fetched: boolean;
+  /** Whether the original commits were read. */
+  followed: boolean;
+  /** The original commits, oldest first. Empty when not followed. */
+  commits: string[];
+  /** Why it was not followed, when it wasn't. */
+  problem: string | null;
+}
+
+const commitOf = (top: string, rev: string): string | undefined => git(top, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`])?.trim() || undefined;
+
+/** The local ref holding pull request `n`'s head: chant's cache, the forge's own ref, or a `refs/remotes/<remote>/pr/<n>` mirror. */
+function localPullRef(top: string, forge: Forge | null, n: number): { ref: string; head: string } | undefined {
+  for (const ref of [`${PULL_CACHE_PREFIX}${n}/head`, pullRef(forge, n), `refs/remotes/${SQUASH_REMOTE}/pr/${n}`]) {
+    const head = commitOf(top, ref);
+    if (head) return { ref, head };
+  }
+  return undefined;
+}
+
+/** Fetch each pull request's head into chant's cache, all in one fetch and then one by one if that fails. The numbers fetched. */
+function fetchPullRefs(top: string, forge: Forge | null, numbers: number[]): Set<number> {
+  const spec = (n: number) => `+${pullRef(forge, n)}:${PULL_CACHE_PREFIX}${n}/head`;
+  const fetchRefs = (ns: number[]) => git(top, ["fetch", "--no-tags", "--quiet", "--no-write-fetch-head", SQUASH_REMOTE, ...ns.map(spec)], { timeout: FETCH_TIMEOUT_MS }) !== undefined;
+  if (numbers.length === 0) return new Set();
+  if (fetchRefs(numbers)) return new Set(numbers);
+  // One missing ref fails the whole fetch; the others may still be there.
+  return new Set(numbers.length === 1 ? [] : numbers.filter((n) => fetchRefs([n])));
+}
+
+/**
+ * Follow each squash commit among `commits` to its pull request's original
+ * commits (#3035). A commit that is not a squash (no `(#<n>)` subject, a
+ * merge, or a head already in its history) is left out of the result. With
+ * `fetchMissing`, a pull request ref missing locally is fetched from `origin`;
+ * without it, only refs already present are read.
+ */
+export function followSquashes(top: string, commits: { sha: string; subject: string }[], opts: { fetchMissing: boolean }): Map<string, SquashFollow> {
+  const out = new Map<string, SquashFollow>();
+  const candidates = commits.map((c) => ({ sha: c.sha, n: pullRequestOf(c.subject) })).filter((c): c is { sha: string; n: number } => c.n !== null);
+  if (candidates.length === 0) return out;
+  const parents = new Map<string, string[]>();
+  for (const line of (git(top, ["log", "--no-walk=unsorted", "--stdin", "--format=%H %P"], { input: `${candidates.map((c) => c.sha).join("\n")}\n` }) ?? "").split("\n")) {
+    const [sha, ...ps] = line.trim().split(/\s+/);
+    if (sha) parents.set(sha, ps);
+  }
+  const squashes = candidates.filter((c) => parents.get(c.sha)?.length === 1);
+  if (squashes.length === 0) return out;
+  const url = git(top, ["config", "--get", `remote.${SQUASH_REMOTE}.url`])?.trim() || null;
+  const forge = forgeOf(url);
+  const local = new Map<number, { ref: string; head: string }>();
+  for (const n of new Set(squashes.map((c) => c.n))) {
+    const hit = localPullRef(top, forge, n);
+    if (hit) local.set(n, hit);
+  }
+  const missing = [...new Set(squashes.map((c) => c.n))].filter((n) => !local.has(n));
+  const fetched = opts.fetchMissing && url ? fetchPullRefs(top, forge, missing) : new Set<number>();
+  for (const n of fetched) {
+    const head = commitOf(top, `${PULL_CACHE_PREFIX}${n}/head`);
+    if (head) local.set(n, { ref: `${PULL_CACHE_PREFIX}${n}/head`, head });
+  }
+  for (const c of squashes) {
+    const hit = local.get(c.n);
+    const base: SquashFollow = { sha: c.sha, pullRequest: c.n, forge, ref: null, head: null, fetched: false, followed: false, commits: [], problem: null };
+    if (!hit) {
+      const problem = !opts.fetchMissing
+        ? `${pullRef(forge, c.n)} is not in this clone`
+        : !url
+          ? `there is no ${SQUASH_REMOTE} remote to fetch ${pullRef(forge, c.n)} from`
+          : `${pullRef(forge, c.n)} could not be fetched from ${SQUASH_REMOTE}: the forge has no such ref, or it can't be reached`;
+      out.set(c.sha, { ...base, problem });
+      continue;
+    }
+    // A head already in the commit's history was merged or rebased, not squashed: nothing to follow.
+    if (git(top, ["merge-base", "--is-ancestor", hit.head, c.sha]) !== undefined) continue;
+    const parent = parents.get(c.sha)![0];
+    const list = git(top, ["rev-list", "--reverse", "--no-merges", hit.head, `^${parent}`]);
+    if (list === undefined) {
+      out.set(c.sha, { ...base, ref: hit.ref, head: hit.head, fetched: fetched.has(c.n), problem: `the commits of ${hit.ref} could not be listed` });
+      continue;
+    }
+    const originals = list.split("\n").map((s) => s.trim()).filter(Boolean);
+    out.set(c.sha, { ...base, ref: hit.ref, head: hit.head, fetched: fetched.has(c.n), followed: true, commits: originals });
+  }
+  return out;
+}
+
+/**
+ * For the lines of `path` in a squash commit: which original commit last wrote
+ * each, by `git blame` at the pull request's head, when the file there is the
+ * same as in the squash (#3035). Undefined when it is not, since the lines
+ * then don't correspond one to one.
+ */
+export function squashLineOrigins(top: string, squash: string, head: string, path: string, originals: Set<string>): Map<number, string> | undefined {
+  const a = git(top, ["rev-parse", "--verify", "--quiet", `${squash}:${path}`])?.trim();
+  const b = git(top, ["rev-parse", "--verify", "--quiet", `${head}:${path}`])?.trim();
+  if (!a || a !== b) return undefined;
+  const out = git(top, ["blame", "--porcelain", head, "--", path]);
+  if (out === undefined) return undefined;
+  const lines = new Map<number, string>();
+  // Every line has a header, `<sha> <line in that commit> <line now>`, with a count after it on a group's first.
+  for (const l of out.split("\n")) {
+    const m = l.match(/^([0-9a-f]{40,64}) \d+ (\d+)(?: \d+)?$/);
+    if (m && originals.has(m[1])) lines.set(Number(m[2]), m[1]);
+  }
+  return lines;
+}

package/src/workspace/status-contract.test.ts

@@ -318,6 +318,9 @@ describe("chant workspace status on built workspaces", () => {
         services: [],
         factory: null,
         listing: null,
+        publisher: null,
+        ship: null,
+        replicate: null,
       },
     ]);
   });
@@ -451,7 +454,7 @@ describe("gate state in chant workspace status --json (#2674)", () => {
         state: "approved",
         recordedAt: "2026-09-20T00:00:00.000Z",
         expiresAt: "2026-12-31T00:00:00.000Z",
-        approvals: [{ principal: "alice", channel: "cli", at: "2026-09-20T01:00:00.000Z" }],
+        approvals: [{ principal: "alice", channel: "cli", relayedBy: null, at: "2026-09-20T01:00:00.000Z" }],
         needed: 1,
         signed: null,
         approve: `chant approve web deploy --env staging --plan ${D("1")}`,
@@ -478,7 +481,7 @@ describe("gate state in chant workspace status --json (#2674)", () => {
         recordedAt: "2026-09-20T00:00:00.000Z",
         expiresAt: "2026-12-31T00:00:00.000Z",
         // The agent's approval doesn't count toward the quorum.
-        approvals: [{ principal: "bob", channel: "cli", at: "2026-09-20T02:00:00.000Z" }],
+        approvals: [{ principal: "bob", channel: "cli", relayedBy: null, at: "2026-09-20T02:00:00.000Z" }],
         needed: 2,
         signed: null,
         approve: `chant approve web review --env staging --plan ${D("4")}`,

package/src/workspace/status-gates.ts

@@ -43,6 +43,8 @@ export interface StatusGateApproval {
   principal: string;
   /** The channel it was recorded on (`cli`, `mcp`, `acp`), or null for a record older than chant#2384. */
   channel: string | null;
+  /** Who relayed it for `principal` (`chant approve --relayed-by`, #3402), or null when nobody did. */
+  relayedBy: string | null;
   at: string;
 }
 
@@ -124,7 +126,7 @@ export function approveCommand(component: string, gate: string, env: string | nu
   return `chant approve ${component} ${gate}${env !== null ? ` --env ${env}` : ""}${planDigest ? ` --plan ${planDigest}` : ""}${signed ? " --sign" : ""}`;
 }
 
-const approvalOf = (r: GateResolutionRecord): StatusGateApproval => ({ principal: r.resolvedBy, channel: r.origin ?? null, at: r.timestamp });
+const approvalOf = (r: GateResolutionRecord): StatusGateApproval => ({ principal: r.resolvedBy, channel: r.origin ?? null, relayedBy: r.relayedBy ?? null, at: r.timestamp });
 
 /** One gate in one environment, decided against its newest pending fact. */
 function decide(component: string, standing: PendingGateRecord, all: GateResolutionRecord[], now: string, rule: GateApprovalRule | null): StatusGate {

package/src/workspace/status.schema.json

@@ -5,6 +5,50 @@
   "description": "What `chant workspace status <env> --json` prints, version 1 of the read contract for releases across members (#2524 D15, D19, #2544). Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`. Each member's gates, read from its gate ledger on the same branch, are in the JSON only (#2674), and so is each member's box block, from the declaration (#2726), with its isolation resolved (#2727). So are its stewards, their Ops and each Op's last run (#2731), the work lease each Op's turn holds (#2748), and the open decision points a steward waits on (#2749).",
   "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
   "$defs": {
+    "boxShip": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["op", "gate", "env", "bookkeeping", "serving", "pending"],
+      "properties": {
+        "op": { "type": "string", "description": "The Op in the box member that commits the staged tree and releases it." },
+        "gate": { "type": "string", "description": "The gate the Op stops at for a person's approval." },
+        "env": { "type": "string", "description": "The environment whose release ledger, under the box member, the Op records each release in." },
+        "bookkeeping": { "type": "array", "items": { "type": "string" }, "description": "Path prefixes from the workspace root whose changes never count as waiting to ship." },
+        "serving": {
+          "description": "The latest release in env's ledger, the commit the box's site serves, or null when nothing has shipped or the ledger can't be read.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["commit", "digest", "component", "at", "actor"],
+              "properties": {
+                "commit": { "type": "string" },
+                "digest": { "type": "string" },
+                "component": { "type": "string" },
+                "at": { "type": "string" },
+                "actor": { "type": ["string", "null"] }
+              }
+            }
+          ]
+        },
+        "pending": {
+          "description": "What is waiting to ship: the files that differ between serving.commit and the working tree, tracked or untracked and not ignored, bookkeeping left out. paths is sorted and lists at most 200. Null when nothing has shipped or the serving commit isn't in this checkout.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["files", "paths"],
+              "properties": {
+                "files": { "type": "integer", "minimum": 0 },
+                "paths": { "type": "array", "items": { "type": "string" }, "maxItems": 200 }
+              }
+            }
+          ]
+        }
+      }
+    },
     "result": {
       "description": "The declaration was read. Exit code 0, even when some ledgers can't be read or members differ.",
       "type": "object",
@@ -46,6 +90,10 @@
             "baseFrom": { "enum": ["origin/HEAD", "main", "master", null], "description": "Where the target branch was found; null when there is none." }
           }
         },
+        "replication": {
+          "description": "Added in contract 1 by #3172. When a box block declares replicate (ws-085), where each ref it names (work branches, kept attempts, work-in-progress snapshots, the ledger branch) stands against the remote: replicated, or how many commits ahead. Read from the local refs and what chant recorded at its last push or fetch under refs/chant/replica/<remote>/; the command never fetches. chant workspace wip --json prints the same, with each branch's snapshots. null when no box declares replicate.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/replication" }]
+        },
         "plantable": {
           "description": "Added in contract 1 by #3146. Whether a host such as a studio's planter can plant the workspace as one box: exactly one member's box block declares services. Not a check: a records-only or infra workspace is valid and simply not plantable.",
           "$ref": "#/$defs/plantable"
@@ -122,11 +170,24 @@
     },
     "member": {
       "type": "object",
-      "required": ["name", "dir", "kind", "environments", "compare", "readable", "gateLedger", "gates", "box", "stewards", "stewardReasons"],
+      "required": ["name", "dir", "kind", "fields", "environments", "compare", "readable", "gateLedger", "gates", "box", "stewards", "stewardReasons"],
       "properties": {
         "name": { "type": "string" },
         "dir": { "type": "string", "description": "Relative to the workspace root, with / separators; \".\" is the root member." },
         "kind": { "type": "string" },
+        "fields": {
+          "description": "The fields the member's kind declares (#3151), each set from the entry or its default, null when it has neither. Null when the kind declares no fields or no pinned package supplies it. A value of the wrong type reads as the default, and chant workspace check reports it (WSP005). Added in contract 1 by chant 0.103.0.",
+          "type": ["object", "null"],
+          "additionalProperties": {
+            "oneOf": [
+              { "type": "string" },
+              { "type": "integer" },
+              { "type": "boolean" },
+              { "type": "null" },
+              { "type": "object", "additionalProperties": { "oneOf": [{ "type": "string" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" }] } }
+            ]
+          }
+        },
         "environments": {
           "description": "env first, then compareTo when it is given and differs from env.",
           "type": "array",
@@ -485,6 +546,41 @@
         "decided_on": { "type": ["string", "null"], "description": "The day it was decided, or null while it is proposed." }
       }
     },
+    "replication": {
+      "type": "object",
+      "required": ["policy", "remoteConfigured", "replicated", "refs"],
+      "properties": {
+        "policy": {
+          "type": "object",
+          "required": ["box", "remote", "refs", "on", "every"],
+          "properties": {
+            "box": { "type": "string", "description": "The member whose box block declares the policy." },
+            "remote": { "type": "string" },
+            "refs": { "type": "array", "items": { "enum": ["work", "kept", "wip", "ledger"] } },
+            "on": { "type": "array", "items": { "enum": ["save", "release"] } },
+            "every": { "type": ["string", "null"] }
+          }
+        },
+        "remoteConfigured": { "type": "boolean", "description": "Whether the checkout has a git remote of the policy's name." },
+        "replicated": { "type": "boolean", "description": "True when every ref listed is on the remote as it is locally." },
+        "refs": {
+          "type": "array",
+          "description": "Every local ref the policy names, sorted by ref.",
+          "items": {
+            "type": "object",
+            "required": ["ref", "class", "commit", "replica", "replicated", "ahead"],
+            "properties": {
+              "ref": { "type": "string", "description": "Such as refs/heads/chant/work/W-001, refs/chant/kept/W-001/<token>, refs/chant/wip/chant/work/W-001 or refs/heads/chant/lifecycle." },
+              "class": { "enum": ["work", "kept", "wip", "ledger"] },
+              "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" },
+              "replica": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40,64}$", "description": "What the remote held of the ref as chant last saw it (or, for a branch, git's remote-tracking ref), or null when unknown." },
+              "replicated": { "type": "boolean" },
+              "ahead": { "type": "integer", "minimum": 0, "description": "Commits reachable from commit that nothing known to be on the remote reaches; 0 when replicated." }
+            }
+          }
+        }
+      }
+    },
     "box": {
       "type": "object",
       "required": ["capabilities", "isolation", "intent", "services"],
@@ -497,6 +593,30 @@
           "description": "Added in contract 1 by #3146. What the box shows of itself on a home site, or null when the block declares no listing.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/listing" }]
         },
+        "publisher": {
+          "description": "Added in contract 1 by #3165. The command that publishes the box's work, as the box block declares it (ws-088), or null when it names none. A surface offers a publish only when it is set, and asks for one with chant workspace box publish rather than running it.",
+          "type": ["string", "null"]
+        },
+        "ship": {
+          "description": "Added in contract 1 by ws-100. How the box ships its staged work to its own site, with defaults filled in, the release its site serves and what is waiting to ship, or null when the box block declares no ship. A surface offers Ship only when it is set: it runs chant run <op> in the member's directory with the person in CHANT_SHIP_BY and approves <gate> as for any Op.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/boxShip" }]
+        },
+        "replicate": {
+          "description": "Added in contract 1 by #3172. Where the box's work in progress is replicated (ws-085), with every default filled in, or null when the block declares no policy. At most one member's box has one; the top-level replication says how far each ref is from the remote.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["remote", "refs", "on", "every"],
+              "properties": {
+                "remote": { "type": "string", "description": "The git remote, by name; origin when the block names none." },
+                "refs": { "type": "array", "items": { "enum": ["work", "kept", "wip", "ledger"] }, "description": "What is replicated, in this order; all four when the block names none." },
+                "on": { "type": "array", "items": { "enum": ["save", "release"] }, "description": "When chant pushes on its own; both when the block names none." },
+                "every": { "type": ["string", "null"], "description": "The interval at which the host runs chant workspace wip push, or null." }
+              }
+            }
+          ]
+        },
         "services": {
           "description": "The services the box block declares (#2880), in declaration order, or empty when it declares none. A reader has them before any converge tick; a steward's ConvergeOp's lastTick carries each one's verdict. cmd is as declared: its ${VAR} references are left for the process that applies it to expand. Added by chant 0.95.0.",
           "type": "array",
@@ -561,7 +681,7 @@
     },
     "factory": {
       "type": "object",
-      "required": ["builds", "check", "checks", "builders", "publish"],
+      "required": ["builds", "check", "checks", "builders", "tiers", "builderFor", "publish"],
       "properties": {
         "builds": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "The members the factory builds, in declaration order. A work item a person asks for constrains member:<the first>." },
         "check": {
@@ -580,6 +700,8 @@
         },
         "checks": { "type": ["string", "null"], "description": "Where a work item's builder writes its check, from the workspace root, or null for the orchestrator's choice." },
         "builders": { "type": ["string", "null"], "description": "The member that declares the builder agents, or null." },
+        "tiers": {"type": "array", "items": {"type": "object", "required": ["tier", "agent", "kinds", "session"], "properties": {"tier": {"type": "string"}, "agent": {"type": "string"}, "kinds": {"oneOf": [{"type": "null"}, {"type": "array", "items": {"type": "string"}}]}, "session": {"type": ["string", "null"]}}}, "description": "Which builder agent builds at which tier, as declared (#3152, ws-094), each { tier, agent, kinds, session } with kinds and session null when not declared; empty when none is. Added in contract 1 by chant 0.103.0."},
+        "builderFor": {"type": "object", "additionalProperties": {"type": "object", "additionalProperties": {"type": "object", "required": ["agent", "session"], "properties": {"agent": {"type": "string"}, "session": {"type": ["string", "null"]}}}}, "description": "The builder for each member the factory builds, by tier (#3152): member name, then tier, then { agent, session }. For a member the entry naming its kind is used, else the tier's entry with no kinds; a tier with neither is left out. Added in contract 1 by chant 0.103.0."},
         "publish": {
           "description": "Where a finished build is published, or null when the factory doesn't publish past the box.",
           "oneOf": [
@@ -703,10 +825,11 @@
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["principal", "channel", "at"],
+            "required": ["principal", "channel", "relayedBy", "at"],
             "properties": {
               "principal": { "type": "string", "description": "Who recorded it." },
               "channel": { "type": ["string", "null"], "description": "The channel it was recorded on, such as cli or mcp, or null for a record older than chant#2384." },
+              "relayedBy": { "type": ["string", "null"], "description": "Added in contract 1 by #3402. Who carried the approval to chant for principal (chant approve --relayed-by), such as a follower relaying a person's approval; a seal covers it. Null when nobody relayed it." },
               "at": { "type": "string" }
             }
           }

package/src/workspace/status.ts

@@ -42,9 +42,11 @@ import { latestPerComponent, readReleaseLedger, type ReleaseRecord } from "../li
 import { readReleasePlan, type ReleasePlan } from "../lifecycle/plan-ledger";
 import { listWorkLeases, type WorkLeaseState } from "../lifecycle/work-lease";
 import { readCheckoutHead, type CheckoutHead } from "./records-checkout";
+import { policyView, replicationState, type ReplicationState } from "./wip";
 import { findWorkspaceRoot } from "../project-root";
 import { resolveBoxes, type ResolvedIsolation } from "./box-isolation";
 import { resolveBoxIntents, unresolvedIntent, type BoxIntent } from "./box-intent";
+import { loadKindRegistry, resolveMemberFields, type MemberFields } from "./kinds";
 import { factoryView, listingView, plantability, treeBytes, type FactoryView, type ListingView, type Plantable } from "./box-factory";
 import { declaredRecordKinds, readDeclaration, readerVersion, WorkspaceReadError, type Declaration, type ErrorLocation, type Member } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
@@ -160,6 +162,13 @@ export interface StatusMember {
   name: string;
   dir: string;
   kind: string;
+  /**
+   * The fields the member's kind declares (#3151), each set from the entry or
+   * its default (null when it has none), or null when the kind declares no
+   * fields or no pinned package supplies it. A value of the wrong type reads
+   * as the default; `chant workspace check` reports it (WSP005).
+   */
+  fields: MemberFields["fields"];
   /** The environment asked for first, then the one compared to, if any. */
   environments: StatusEnvironment[];
   /** Null without `--compare-to`. */
@@ -178,6 +187,31 @@ export interface StatusMember {
   stewardReasons: { code: StewardReasonCode; message: string }[];
 }
 
+/** The most paths `ship.pending.paths` lists; `files` still counts them all. */
+export const SHIP_PENDING_PATHS_MAX = 200;
+
+/**
+ * A box's ship (ws-100): the Op, gate and environment it declares, the
+ * release its site serves (the latest in that environment's release ledger
+ * under the box member), and what is waiting to ship.
+ */
+export interface StatusBoxShip {
+  op: string;
+  gate: string;
+  env: string;
+  bookkeeping: string[];
+  /** The latest release in `env`'s ledger: the commit the box's site serves. Null when nothing has shipped, or the ledger can't be read. */
+  serving: { commit: string; digest: string; component: string; at: string; actor: string | null } | null;
+  /**
+   * The files that differ between `serving.commit` and the working tree
+   * (tracked changes, committed or not, and untracked files git does not
+   * ignore), bookkeeping left out; `paths` sorted, at most
+   * SHIP_PENDING_PATHS_MAX of them. Null when nothing has shipped or the
+   * serving commit isn't in this checkout.
+   */
+  pending: { files: number; paths: string[] } | null;
+}
+
 /** A box's brokered capabilities, from the declaration (#2726). */
 export interface StatusBox {
   capabilities: { name: string; broker: string | null; scope: string[] }[];
@@ -196,6 +230,12 @@ export interface StatusBox {
   factory: FactoryView | null;
   /** What the box shows of itself on a home site, with the cover's sha256 (#3146), or null when the block declares no listing. */
   listing: ListingView | null;
+  /** The command that publishes the box's work, as declared (#3165, ws-088), or null when the block names none. */
+  publisher: string | null;
+  /** How the box ships its staged work, what its site serves and what is waiting (ws-100), or null when the block declares no ship. */
+  ship: StatusBoxShip | null;
+  /** Where the box's work in progress is replicated, with defaults filled in (#3172, ws-085), or null when the block declares no policy. */
+  replicate: { remote: string; refs: string[]; on: string[]; every: string | null } | null;
 }
 
 /** A declared box service as `status --json` prints it (#2880): every field present, null or false when not declared. */
@@ -252,6 +292,8 @@ export type StatusDocument =
       leases: StatusLease[];
       /** Each work item's acceptance criteria, met of total, by declared kind then item (#2772). Empty when no declared work kind has criteria. */
       acceptance: StatusAcceptance[];
+      /** How far each ref the box's replicate policy names is from its remote (#3172), read locally; null when no box declares one. */
+      replication: ReplicationState | null;
       summary: { members: number; released: number; unreadable: number; differing: number | null };
     }
   | {
@@ -321,6 +363,40 @@ async function ledgerFor(member: Member, env: string, cwd: string): Promise<Omit
   return { layout: "flat", path: `${env}/releases.jsonl` };
 }
 
+/** A box's ship as status prints it (ws-100). Never throws: what can't be read is null. */
+async function shipView(member: Member, cwd: string, read: LedgerReader): Promise<StatusBoxShip | null> {
+  const ship = member.box?.ship;
+  if (!ship) return null;
+  const view: StatusBoxShip = { op: ship.op, gate: ship.gate, env: ship.env, bookkeeping: [...ship.bookkeeping], serving: null, pending: null };
+  let records: ReleaseRecord[] = [];
+  try {
+    records = (await read((await ledgerFor(member, ship.env, cwd)).path, cwd)).records;
+  } catch {
+    return view;
+  }
+  const last = records[records.length - 1];
+  if (!last) return view;
+  view.serving = { commit: last.gitSha, digest: last.digest, component: last.component, at: last.timestamp, actor: last.actor ?? null };
+  const top = gitTop(cwd);
+  if (!top) return view;
+  const lines = (args: string[]): string[] | null => {
+    try {
+      return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 }).split("\0").filter(Boolean);
+    } catch {
+      return null;
+    }
+  };
+  // The commit must be here: a release from a commit this checkout never had says nothing about it.
+  if (lines(["cat-file", "-e", `${last.gitSha}^{commit}`]) === null) return view;
+  const changed = lines(["diff", "--name-only", "-z", "--no-renames", last.gitSha, "--"]);
+  const untracked = lines(["ls-files", "--others", "--exclude-standard", "-z"]);
+  if (changed === null || untracked === null) return view;
+  const bookkeeping = (path: string) => ship.bookkeeping.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+  const paths = [...new Set([...changed, ...untracked])].filter((path) => !bookkeeping(path)).sort();
+  view.pending = { files: paths.length, paths: paths.slice(0, SHIP_PENDING_PATHS_MAX) };
+  return view;
+}
+
 const defaultReader: LedgerReader = (path, cwd) => readReleaseLedger(path.slice(0, -"/releases.jsonl".length), { cwd });
 
 async function readEnvironment(member: Member, env: string, cwd: string, read: LedgerReader): Promise<StatusEnvironment> {
@@ -412,6 +488,8 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
     const isolation = new Map(resolveBoxes(declaration).map((b) => [b.member.name, b.isolation]));
     const intents = new Map((await resolveBoxIntents(declaration, found.dir)).map((i) => [i.member, i.record?.intent ?? unresolvedIntent(i.id)]));
     const coverBytes = treeBytes(workingTree(found.dir));
+    // The kinds the pins supply (#3151), for each member's fields. A pin that can't be read is check's to report (WSP002).
+    const kinds = loadKindRegistry(declaration.pins, found.dir).registry;
     // #3163: the declaration's identity.gates at base, read once for every member's gates.
     const ruleSource = scopeSource(found.dir);
     const rules = (gate: string) => gateAdmissionFrom(ruleSource, gate);
@@ -426,6 +504,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
         name: m.name,
         dir: m.dir,
         kind: m.kind,
+        fields: resolveMemberFields(kinds.get(m.kind), m.fields).fields,
         environments,
         compare: query.compareTo === undefined ? null : compareEnvironments(environments[0], environments[environments.length - 1]),
         readable: environments.every((e) => e.reason === null),
@@ -447,8 +526,11 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
                   health: s.health,
                   optional: s.optional,
                 })),
-                factory: factoryView(m.box.factory),
+                factory: factoryView(m.box.factory, declaration.members),
                 listing: listingView(m.box.listing, coverBytes),
+                publisher: m.box.publisher,
+                ship: await shipView(m, found.dir, read),
+                replicate: m.box.replicate === null ? null : (({ box: _box, ...rest }) => rest)(policyView(m.name, m.box.replicate)),
               },
         stewards: stewards.stewards,
         stewardReasons: stewards.reasons,
@@ -475,6 +557,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
       members,
       leases,
       acceptance,
+      replication: replicationOf(declaration, top),
       summary: {
         members: members.length,
         released: members.filter((m) => m.environments[0].releases.length > 0).length,
@@ -631,3 +714,9 @@ export function formatStatus(doc: Extract<StatusDocument, { members: unknown }>)
   );
   return lines.join("\n");
 }
+
+/** Where the box's work in progress stands against its remote (#3172), or null when no box block declares replicate. */
+function replicationOf(declaration: Declaration, top: string): ReplicationState | null {
+  const m = declaration.members.find((x) => x.box?.replicate);
+  return m ? replicationState(top, policyView(m.name, m.box!.replicate!)) : null;
+}