@intentius/chant 0.100.0 → 0.102.0

package/src/cli/main.test.ts

@@ -747,25 +747,58 @@ describe("workspace init and ls (#2534)", () => {
     expect(resolveCommand(init, commandRegistry)?.def.name).toBe("workspace init");
     expect(commandRegistry.filter((c) => c.name === "workspace" || c.name.startsWith("workspace ")).map((c) => c.name).sort()).toEqual([
       "workspace",
+      "workspace admit",
+      "workspace adopt-lineage",
+      "workspace agent",
       "workspace audit",
       "workspace build",
       "workspace check",
+      "workspace evidence",
+      "workspace export",
       "workspace graph",
+      "workspace hash-index",
+      "workspace import",
       "workspace init",
       "workspace lineage",
       "workspace lint",
       "workspace ls",
       "workspace member-run",
       "workspace patch",
+      "workspace pin",
       "workspace points",
       "workspace records",
+      "workspace runs",
+      "workspace signers",
       "workspace status",
       "workspace upgrade",
       "workspace verify",
+      "workspace versions",
       "workspace work",
     ]);
   });
 
+  test("adopt-lineage, hash-index, versions and upgrade --source take their flags (#2551)", () => {
+    const adopt = parseArgs(["workspace", "adopt-lineage", "app", "--from", "acme/starter#svc", "--tags", "v*", "--index", "i.json", "--param", "name=x", "--dry-run"]);
+    expect(adopt).toMatchObject({ command: "workspace", path: "adopt-lineage", extraPositional: "app", migrateFrom: "acme/starter#svc", tags: "v*", index: "i.json", param: ["name=x"], dryRun: true });
+    expect(resolveCommand(adopt, commandRegistry)?.def.name).toBe("workspace adopt-lineage");
+    expect(parseArgs(["workspace", "versions", "--available", "--template", "x"])).toMatchObject({ path: "versions", available: true, template: "x" });
+    expect(parseArgs(["workspace", "upgrade", "--source", "acme/upstream", "--to", "v2.0.0"])).toMatchObject({ source: "acme/upstream", migrateTo: "v2.0.0" });
+    expect(() => parseArgs(["workspace", "adopt-lineage", "--tags"])).toThrow(/--tags needs a tag glob/);
+    expect(() => parseArgs(["workspace", "upgrade", "--source", "--to"])).toThrow(/--source needs a template/);
+  });
+
+  test("export, import and admit take their arguments (#2552)", () => {
+    const exp = parseArgs(["workspace", "export", "app,design", "--to", "out", "--param", "domain=example.com", "--dry-run", "--json"]);
+    expect(exp).toMatchObject({ command: "workspace", path: "export", extraPositional: "app,design", migrateTo: "out", param: ["domain=example.com"], dryRun: true, json: true });
+    expect(resolveCommand(exp, commandRegistry)?.def.name).toBe("workspace export");
+    const imp = parseArgs(["workspace", "import", "../copy", "--remove"]);
+    expect(imp).toMatchObject({ path: "import", extraPositional: "../copy", remove: true });
+    expect(resolveCommand(imp, commandRegistry)?.def.name).toBe("workspace import");
+    const admit = parseArgs(["workspace", "admit", "ret-0123456789ab", "--note", "returned from the studio"]);
+    expect(admit).toMatchObject({ path: "admit", extraPositional: "ret-0123456789ab", note: "returned from the studio" });
+    expect(resolveCommand(admit, commandRegistry)?.def.name).toBe("workspace admit");
+  });
+
   test("workspace work takes its verb, id and lease flags (#2732)", () => {
     const claim = parseArgs(["workspace", "work", "claim", "W-001", "--holder", "a", "--ttl", "60", "--json"]);
     expect(claim).toMatchObject({ command: "workspace", path: "work", extraPositional: "claim", extraPositional2: "W-001", holder: "a", ttl: "60", json: true });

package/src/cli/main.ts

@@ -102,6 +102,7 @@ const BOOLEAN_FLAGS = new Set([
   "--durable-requests",
   "--skip-mcp",
   "--current",
+  "--uncommitted",
   "--allow-code",
   "--root-only",
   "--generated",
@@ -227,6 +228,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant import --kustomize <dir>` (#1548): render the overlay, import
       // the output through the k8s template parser.
       result.kustomize = args[++i];
+    } else if (arg === "--parser-option") {
+      // `chant import --parser-option key[=value]` (#2994), repeatable: checked
+      // against the lexicon's parserOptions() by the import command.
+      const v = args[++i];
+      if (!v || v.startsWith("-")) throw new Error("--parser-option needs key or key=value: --parser-option acceptLossyV1");
+      (result.parserOption ??= []).push(v);
     } else if (arg === "--type") {
       result.selectType = args[++i];
     } else if (arg === "--name") {
@@ -377,11 +384,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace graph --composites` (#2662)
       result.composites = true;
     } else if (arg === "--intent") {
-      // `chant workspace graph --intent <path[:start-end]>` (#2651), or `--intent --record <id>` with no region.
+      // `chant workspace graph --intent <path[:start-end]|path#symbol>` (#2651), or `--intent --record <id>` with no region.
       const value = args[i + 1];
       if (value !== undefined && !value.startsWith("-")) result.intent = args[++i];
       else if (args.includes("--record")) result.intent = "";
-      else throw new Error("--intent needs a region: --intent <path[:start-end]>, or --intent --record <id>");
+      else throw new Error("--intent needs a region: --intent <path[:start-end]|path#symbol>, or --intent --record <id>");
     } else if (arg === "--record") {
       // `chant workspace graph --intent --record <id>`
       result.record = args[++i];
@@ -409,6 +416,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!result.severity || result.severity.startsWith("-")) throw new Error("--severity needs off, warn or fail");
     } else if (arg === "--current") {
       result.current = true;
+    } else if (arg === "--uncommitted") {
+      // `chant workspace records --uncommitted` (#3160)
+      result.uncommitted = true;
     } else if (arg === "--set") {
       // `chant workspace records amend <id> --set <file|->` (#2670)
       result.set = args[++i];
@@ -445,6 +455,7 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--sign") {
       // `chant workspace records review <id> --sign [<key file>]` (#2687): seal the verdict.
       // `records new` and `records amend` take it too, to seal the record's author (#2688).
+      // `chant approve <op> <gate> --sign [<key file>]` seals a gate approval (#3163).
       // With no key file, git's user.signingkey, as `git commit -S` reads it.
       const next = args[i + 1];
       result.sign = next !== undefined && !next.startsWith("-") ? args[++i] : true;
@@ -456,6 +467,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace records new <kind> --prefix <prefix>` (#2670): the id prefix to allocate under.
       result.prefix = args[++i];
       if (!result.prefix || result.prefix.startsWith("-")) throw new Error("--prefix needs an id prefix: --prefix <prefix>");
+    } else if (arg === "--key" || arg === "--check-id" || arg === "--claim" || arg === "--environment" || arg === "--envelope" || arg === "--threshold") {
+      // `chant workspace evidence sign|verify` and `chant workspace signers` (#2553)
+      const value = args[++i];
+      if (value === undefined || value.startsWith("-")) throw new Error(`${arg} needs a value`);
+      const field = ({ "--key": "key", "--check-id": "checkId", "--claim": "claim", "--environment": "environment", "--envelope": "envelope", "--threshold": "threshold" } as const)[arg];
+      result[field] = value;
     } else if (arg === "--require") {
       // `chant workspace records|verify --require attested` (#2547)
       result.require = args[++i];
@@ -560,6 +577,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       const value = args[++i];
       if (!value || value.startsWith("-")) throw new Error(`${arg} needs a value: ${arg} <${arg.slice(2)}>`);
       result[arg.slice(2) as "holder" | "ttl" | "token" | "outcome"] = value;
+    } else if (arg === "--unit" || arg === "--decision") {
+      // `chant workspace runs --unit <id> | --decision <id>` (#3033): the runs on one work item, or for one decision.
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error(`${arg} needs an id: ${arg} <id>`);
+      result[arg.slice(2) as "unit" | "decision"] = value;
     } else if (arg === "--note") {
       result.note = args[++i];
     } else if (arg === "--expire") {
@@ -576,6 +598,24 @@ export function parseArgs(args: string[]): ParsedArgs {
       // #2550 — `chant workspace upgrade` runs a template's code migrations
       // only when asked to.
       result.allowCode = true;
+    } else if (arg === "--source") {
+      // #2551 — `chant workspace upgrade --source <repo>[#<member>]`.
+      result.source = args[++i];
+      if (!result.source || result.source.startsWith("-")) throw new Error("--source needs a template: --source <repo>[#<member>]");
+    } else if (arg === "--tags") {
+      // #2551 — `chant workspace adopt-lineage --tags <glob>`, also hash-index and versions.
+      result.tags = args[++i];
+      if (!result.tags || result.tags.startsWith("-")) throw new Error("--tags needs a tag glob: --tags 'v*'");
+    } else if (arg === "--index") {
+      // #2551 — `chant workspace adopt-lineage --index <file>`.
+      result.index = args[++i];
+      if (!result.index || result.index.startsWith("-")) throw new Error("--index needs a hash index file: --index <file>");
+    } else if (arg === "--remove") {
+      // #2552 — `chant workspace import --remove` removes the export member instead of writing it again.
+      result.remove = true;
+    } else if (arg === "--available") {
+      // #2551 — `chant workspace versions --available` lists the template's version tags.
+      result.available = true;
     } else if (arg === "--root-only") {
       // #2537 — `chant build` and `chant lint` at a declared workspace root
       // run on the root project alone instead of refusing with WSP000.
@@ -794,7 +834,11 @@ Ops:
                         and defaults to the PR/MR of the surrounding CI job.
                         The next "chant run <op>" walks through the gate.
                         --expire clears a pending fact without approving it,
-                        so the gate is re-decided from scratch next run
+                        so the gate is re-decided from scratch next run.
+                        --sign [<key file>] seals the approval with an ssh
+                        key; a gate the workspace's identity.gates names
+                        counts only an approval sealed by a key the signers
+                        file at base lists for --actor
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,
@@ -834,7 +878,7 @@ Workspace (level 1, #2524):
                         beside it and marks the members whose digests differ.
                         Read only; never fetches. --json prints the
                         read-contract document
-  workspace records [--kind <kind file>] [--current] [--at <rev>] [--base <rev>] [--require attested] [--json]
+  workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json]
                         Without --kind, every record kind the declaration
                         names. Read the records a record kind locates, validated
                         against its schema, with reason codes for invalid
@@ -844,7 +888,10 @@ Workspace (level 1, #2524):
                         the signers at --base (default: the target branch);
                         --require attested exits 2 if any record is not
                         attested. A pinned file that changed is a warning,
-                        asset-drift or asset-missing
+                        asset-drift or asset-missing. In the working tree,
+                        each record says whether it is committed, modified
+                        or new against HEAD, with the branch and base;
+                        --uncommitted lists only the modified and new ones
   workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json]
                         What changed in the records between <rev> and --at
                         (default: the working tree): new and removed records,
@@ -886,7 +933,7 @@ Workspace (level 1, #2524):
                         closing commit and seal, in one write. Without
                         --kind, the one session kind the declaration names.
                         Prints {path, id, changed, seal, closedRev}
-  workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <text>] [--note <text>] [--json]
+  workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <outcome>] [--note <text>] [--json]
                         Take, heartbeat or give back the lease on a work item:
                         refs/chant/lease/work/<id>, a compare-and-set ref with a
                         fencing token and an expiry, pushed to the remote so
@@ -897,6 +944,28 @@ Workspace (level 1, #2524):
                         A work item's lease history: each claim with its token
                         and holder, and how it ended, released with an outcome
                         or never released (expired or lost). Read-only
+  workspace work evidence <id> --holder <name> --token <token> --from <file|-> [--kind <kind file>]
+                        Attach evidence for one acceptance criterion under the
+                        lease you hold: the entry (criterion, result, title,
+                        a url or a path pinned by hash) is appended to the
+                        item's pins through records amend. Prints the
+                        work-evidence document and never commits
+  workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--json]
+                        The agent runs in the run ledger on chant/lifecycle, each
+                        with its model, tokens, cost and the commits it made,
+                        and totals per work item, decision and principal; a run
+                        that reports no cost is listed as unpriced, never zero.
+                        Read-only, never fetches
+  workspace runs start --from <file|->
+                        Record that an agent run started: who it worked for,
+                        its harness, model, work item and lease. Prints the run
+                        and its Chant-Run trailer. chant never starts a run
+  workspace runs end <run id> [--from <file|->]
+                        Record how a started run ended: its outcome, tokens,
+                        cost and price source, the transcript pinned by hash,
+                        and the commits it made
+  workspace runs record --from <file|->
+                        Record a finished run, its start and end in one write
   workspace points [--open] [--kind <kind file>] [--at <rev>] [--json]
                         List the decision points the declared answer kinds'
                         points files declare, and the questions asked of them;
@@ -909,24 +978,77 @@ Workspace (level 1, #2524):
   workspace points answer <id> --answer <value> --by <name>... [--kind <kind file>] [--dry-run]
                         Record people's answer to an open question, or confirm
                         a model's proposal, once the point's quorum is met
+  workspace pin <path> [--json]
+                        Print the integrity value that pins the plugin at
+                        <path>, to put in a path pin of chant.workspace.json.
+                        chant checks it before it reads the plugin
+  workspace agent [<name>] [--json]
+                        Print an agent session from the declaration: the one
+                        member it is bound to, the record kinds and verbs its
+                        write scope allows, and the spec records --current
+                        prints. Without a name, the session CHANT_AGENT names
   workspace verify [--base <rev>] [--head <rev>] [--require attested]
                         Check the commits in base..head against the signers
                         and roles read from base. A change to the signers file
                         or .chant/trust.json needs a signature by a signer
-                        trusted at base. Does nothing without a signers file
+                        trusted at base, and a new signer set needs a
+                        threshold of the old one. Does nothing without a
+                        signers file
+  workspace signers [--json] [rotate [--threshold <n>] | sign --key <file>]
+                        Show the signer history at base, or propose the next
+                        signer set and sign it with a current signer's key
+  workspace evidence sign --kind <kind file> --key <runner.pem> --check-id <id>
+                        Sign runner evidence over the records' hashes in a
+                        DSSE envelope, with a runner key .chant/trust.json
+                        lists. For CI and services, never a person's key
+  workspace evidence verify --envelope <file> [--at <rev>] [--json]
+                        Verify runner evidence offline, and whether the
+                        records it covers are unchanged
   workspace lineage [--json]
                         Show each scope in .chant/workspace.lock.json: its
                         template and pin, locally edited files and open
                         manual steps. Needs no workspace file
   workspace lineage resolve <path>
                         Close a manual step once the file is merged by hand
-  workspace upgrade [<scope>] [--to <ref|dir>] [--allow-code] [--dry-run] [--output <file>]
+  workspace upgrade [<scope>] [--to <ref|dir>] [--source <repo>[#<member>]] [--allow-code] [--dry-run] [--output <file>]
                         Bring a lineage scope to a newer template version: fetch
                         it, migrate and merge per file in a worktree, run build,
                         lint and workspace check there, then gate on the digest
                         of the patch (chant approve workspace-upgrade <scope>).
-                        A second run with the approval applies the patch
-  workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>]
+                        A second run with the approval applies the patch.
+                        --source <repo>[#<member>] moves the scope to another
+                        template through that template's bridge migration
+  workspace adopt-lineage [<scope>] --from <repo>[@<ref>][#<member>] [--tags <glob>]
+                        [--index <file>] [--param name=value] [--dry-run] [--json]
+                        Give a scope a git lineage: match a scope with none
+                        against the template's versions and record the best
+                        one, with the adopted commit range in .chant/trust.json,
+                        or move a directory lineage onto the version that
+                        reproduces its recorded files
+  workspace hash-index --from <repo>[#<member>] [--tags <glob>] [--output <file>]
+                        Compute the per-version file hashes adopt-lineage
+                        matches against, for a template's CI to publish
+  workspace versions [<dir>] [--template <id>] [--available [--tags <glob>]] [--json]
+                        Report the template, chant and lexicon versions of
+                        every lineage lock under <dir>, grouped into families
+                        by template; --available also lists each git
+                        template's version tags and where each lock sits
+  workspace export [<member>[,<member>...]] [--to <member>] [--param name=value] [--dry-run] [--json]
+                        Write members that set travel, with their lineage and
+                        records, into the export member (role export) as a
+                        workspace of their own; with no member named, every
+                        member that travels and the workspace's own records.
+                        --param gives a host-bound parameter its value there
+  workspace import [<dir>] [--remove] [--dry-run] [--json]
+                        Bring an export back: merge per file against the
+                        export's hashes, switch host values back, record the
+                        return in .chant/returns/<id>.json with the commits the
+                        files were made in, then write the export member again
+                        or, with --remove, remove it
+  workspace admit <return id> [--note <text>] [--dry-run] [--json]
+                        Admit the signers of a return in .chant/trust.json, so
+                        its signed work reads as attested once merged
+  workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>]
                         Fail on an unreadable lineage lock or an open manual
                         step, and, in a declared workspace, on a WSP check of
                         the declaration, member ledgers, pipelines or
@@ -934,14 +1056,21 @@ Workspace (level 1, #2524):
                         and compares their output. --kind warns on records
                         whose pinned files changed. Needs no workspace file.
                         --at reads a commit's git objects; --format json
-                        prints the read-contract document
+                        prints the read-contract document. --live --env
+                        resolves each declared member link against the live
+                        graph of <env> (each chant member runs chant graph
+                        --live, which reaches the account) and reports
+                        WSP141 and WSP142
   workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]
                         Map each path the diff changes to the current records
                         whose constrains cover it: change-uncovered when none
                         does, change-out-of-scope when a record in hand (the
                         --work item and its decisions) lists it in
                         out_of_scope. The declaration's changes block sets
-                        the severity (warn by default) and ignore globs
+                        the severity (warn by default) and ignore globs. When
+                        the declaration at base has writeScope or agents, each
+                        commit that writes outside its writer's scope fails
+                        the check (write-scope-member, write-scope-kind)
   workspace patch <base>..<head>|<base>...<head>|<commit> [--path <p>...] [--max-bytes <n>] [--json]
   workspace patch [<commit>] --worktree [--path <p>...] [--max-bytes <n>] [--json]
                         The hunks of a diff, file by file: a range, a work
@@ -972,7 +1101,7 @@ Workspace (level 1, #2524):
                         Each composite instance the members declare, with the
                         components whose contract can deploy it; an instance
                         with none lists an empty set
-  workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]
+  workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--json]
                         The intent graph over one region: the commits that
                         touched it, the decisions whose constrains cover it,
                         the artifacts they pin, and findings with closed codes.
@@ -1066,8 +1195,13 @@ Lexicon development:
                             --check: fail if the committed baseline drifted (never writes);
                             --run-examples: also run example build harness;
                             --pinned-digest <file>: verify spec digest before regen)
-  dev pinned-upgrade <dir> Report if a pinned lexicon (k8s|gcp|docker|gitlab) has a newer
-                           upstream release; dry-run bump + regen + surface-diff, then revert
+  dev pinned-upgrade <dir> [pin]
+                           Report if a lexicon that declares upstreamPin (k8s, k3s, gcp, docker,
+                           gitlab, cedar, sql) has a newer upstream release; dry-run bump + regen +
+                           surface-diff, then revert. A pin that moves with other constants (sql's
+                           image digest) is reported with how to move it, not edited. A lexicon
+                           with several pins (sql: clickhouse, postgres-14 .. postgres-18) gets one
+                           report per pin; name a pin to check only that one
                            (reports only; --force bypasses the spec cache, -f json for JSON)
   dev rolling-upgrade <dir>  Report rolling-spec drift (aws, azure, github): regen from
                            latest, diff surface vs committed baseline, print delta + PR
@@ -1110,8 +1244,9 @@ Options:
   -h, --help            Show this help message
   -V, --version         Print the installed chant's version
   --on <lexicon>        Which runtime hosts the run: a configured lexicon with
-                        an opRuntime, or the built-in local runtime when
-                        omitted (every run subcommand; #2121)
+                        an opRuntime, or local. Omitted, run.on in
+                        chant.config.ts decides, then the built-in local
+                        runtime (every run subcommand; #2121, #2523)
   --local               Run an Op with the local in-process executor (default)
   -p, --profile <name>  Named connection profile the hosting runtime targets
                         (fountain.profiles in chant.config.ts); each runtime's
@@ -1203,6 +1338,7 @@ Examples:
   chant components export prod --component search-service -o ./dist/search-service
   chant import template.json --output ./infra/
   chant import manifest.yaml --lexicon k8s --output ./infra/
+  chant import dash.json --lexicon grafana --parser-option acceptLossyV1
   chant import --from prod --name my-bucket --output src/
   chant lint ./infra/
   chant lint ./infra/ --format sarif
@@ -1468,9 +1604,19 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace ls", handler: async (ctx) => (await import("../workspace/ls")).runWorkspaceLs(ctx) },
   // #2732 — the work lease: claim, renew and release a work item.
   { name: "workspace work", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/work-cli")).runWorkspaceWork(ctx) },
+  // #3033 — the agent run record: what each run cost and which commits it made. chant records runs and never starts one.
+  { name: "workspace runs", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/runs-cli")).runWorkspaceRuns(ctx) },
   { name: "workspace status", handler: async (ctx) => (await import("../workspace/status")).runWorkspaceStatus(ctx) },
   { name: "workspace lineage", handler: async (ctx) => (await import("../workspace/lineage-cli")).runWorkspaceLineage(ctx) },
   { name: "workspace upgrade", handler: async (ctx) => (await import("../workspace/lineage-upgrade-cli")).runWorkspaceUpgrade(ctx) },
+  // #2551 — adopt a lineage, the hash index it matches against, and the versions of a family of workspaces.
+  { name: "workspace adopt-lineage", handler: async (ctx) => (await import("../workspace/lineage-adopt-cli")).runWorkspaceAdoptLineage(ctx) },
+  { name: "workspace hash-index", handler: async (ctx) => (await import("../workspace/lineage-adopt-cli")).runWorkspaceHashIndex(ctx) },
+  // #2552 — export a workspace or members, bring an export back, and admit a return's signers.
+  { name: "workspace export", handler: async (ctx) => (await import("../workspace/export-cli")).runWorkspaceExport(ctx) },
+  { name: "workspace import", handler: async (ctx) => (await import("../workspace/export-cli")).runWorkspaceImport(ctx) },
+  { name: "workspace admit", handler: async (ctx) => (await import("../workspace/export-cli")).runWorkspaceAdmit(ctx) },
+  { name: "workspace versions", handler: async (ctx) => (await import("../workspace/lineage-versions")).runWorkspaceVersions(ctx) },
   // #2641 — workspace check reads member configs statically and never runs one.
   { name: "workspace check", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/lineage-check")).runWorkspaceCheck(ctx) },
   // The hunks of a diff, for a reader that runs no git of its own.
@@ -1484,7 +1630,12 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace graph", handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "graph") },
   // Each unit decides for itself whether its config is loaded (runCommandInProcess).
   { name: "workspace member-run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-run")).runWorkspaceMemberRun(ctx, runCommandInProcess) },
+  { name: "workspace pin", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/pin-cli")).runWorkspacePin(ctx) },
+  // #2548 — an agent session's member, write scope and spec, for a session that resumes.
+  { name: "workspace agent", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/agent-cli")).runWorkspaceAgent(ctx) },
   { name: "workspace verify", handler: async (ctx) => (await import("../workspace/trust/verify-cli")).runWorkspaceVerify(ctx) },
+  { name: "workspace signers", handler: async (ctx) => (await import("../workspace/trust/signers-cli")).runWorkspaceSigners(ctx) },
+  { name: "workspace evidence", handler: async (ctx) => (await import("../workspace/trust/evidence-cli")).runWorkspaceEvidence(ctx) },
 
   // State subcommands
   { name: "lifecycle snapshot", requiresPlugins: true, handler: runLifecycleSnapshot },

package/src/cli/mcp/workspace-tools.test.ts

@@ -12,7 +12,7 @@ import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { createConformanceWorkspace, defaultChantCommand, mcpToolCall, type ConformanceWorkspace } from "../../workspace/conformance";
 import { McpServer } from "./server";
-import { workspaceReadTools, workspaceWriteTools } from "./workspace-tools";
+import { readArgv, workspaceReadTools, workspaceWriteTools } from "./workspace-tools";
 
 const KIND = "decisions/decision.kind.mjs";
 const chant = defaultChantCommand();
@@ -85,7 +85,7 @@ describe("which servers have the workspace tools", () => {
       const { tools } = (await rpc(server(cwd), "tools/list")) as { tools: { name: string }[] };
       expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(names));
     }
-    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-changes", "workspace-records", "workspace-points", "workspace-work-history", "records-new", "records-amend", "records-review", "records-close", "points-answer"]);
+    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-changes", "workspace-records", "workspace-points", "workspace-agent", "workspace-work-history", "workspace-runs", "records-new", "records-amend", "records-review", "records-close", "points-answer"]);
   });
 
   test("a server outside any workspace, or given none, does not", async () => {
@@ -161,6 +161,9 @@ describe("reads", () => {
 
   test("the conformance suite's argv maps to the tool that answers it", () => {
     expect(mcpToolCall(["workspace", "records", "--kind", KIND, "--json"])).toEqual({ name: "workspace-records", arguments: { kind: KIND } });
+    expect(mcpToolCall(["workspace", "records", "--uncommitted", "--kind", KIND, "--json"])).toEqual({ name: "workspace-records", arguments: { uncommitted: true, kind: KIND } });
+    expect(readArgv("workspace-records", { kind: KIND, uncommitted: true })).toEqual(["workspace", "records", "--kind", KIND, "--uncommitted", "--json"]);
+    expect(() => readArgv("workspace-records", { uncommitted: true, at: "HEAD" })).toThrow(/takes no at or since/);
     expect(mcpToolCall(["workspace", "status", "dev", "--json"])).toEqual({ name: "workspace-status", arguments: { env: "dev" } });
     expect(mcpToolCall(["workspace", "graph", "--intent", "a.mjs:1", "--kind", KIND, "--json"])).toEqual({ name: "workspace-graph", arguments: { intent: "a.mjs:1", kind: [KIND] } });
     expect(mcpToolCall(["workspace", "graph", "--composites", "--json"])).toEqual({ name: "workspace-graph", arguments: { composites: true } });

package/src/cli/mcp/workspace-tools.ts

@@ -7,7 +7,7 @@
  *
  * - The reads (`workspace-ls`, `workspace-status`, `workspace-graph`,
  *   `workspace-changes`, `workspace-records`, `workspace-points`,
- *   `workspace-work-history`) run `chant workspace <command>
+ *   `workspace-work-history`, `workspace-runs`) run `chant workspace <command>
  *   ... --json` with the chant this server runs as, in the server's
  *   directory, and return the
  *   document it printed, unchanged, with its reason codes (#2536). Running the
@@ -28,11 +28,20 @@
  *
  * Nothing here listens on a port or authenticates anyone (ws-052): the server
  * speaks over stdio, and `by` is recorded as given, as `--by` is.
+ *
+ * An agent session (#2548): a server started with `CHANT_AGENT` set writes in
+ * that session, bound to its one member, and its writes are refused outside
+ * the session's write scope with the CLI's codes (`write-scope-member`,
+ * `write-scope-kind`, `agent-unknown`). `workspace-agent` returns what the
+ * session reloads from.
  */
 
 import { spawn } from "node:child_process";
 import type { ToolContext, ToolDefinition, ToolHandler } from "./types";
 
+/** `AGENT_ENV` of `workspace/write-scope.ts`, kept here so the server loads nothing under workspace/ until a tool is called. */
+const AGENT_ENV = "CHANT_AGENT";
+
 /** How the reads run chant: a command and its leading arguments. */
 export type ChantCommand = string[];
 
@@ -49,6 +58,8 @@ export interface WorkspaceToolsOptions {
   cwd: string;
   /** The chant the reads run. Defaults to {@link ownChantCommand}. */
   chantCommand?: ChantCommand;
+  /** The agent session the writes are made in (#2548). Defaults to `CHANT_AGENT`. */
+  agent?: string;
 }
 
 const PROTOCOL =
@@ -100,7 +111,7 @@ export const workspaceReadTools: ToolDefinition[] = [
           items: { type: "string" },
           description: "Record kind files whose records join the graph (--kind). The plain graph takes one; intent takes several.",
         },
-        intent: { type: "string", description: "The region for the intent graph: a workspace path, path:line or path:start-end (--intent)." },
+        intent: { type: "string", description: "The region for the intent graph: a workspace path, path:line, path:start-end, or path#symbol for a TypeScript or JavaScript declaration such as src/server.ts#createApp (--intent). The document's why answers why the region is like this." },
         composites: { type: "boolean", description: "The composites document instead (--composites). Takes no kind or intent." },
         at: atProp,
       },
@@ -135,6 +146,10 @@ export const workspaceReadTools: ToolDefinition[] = [
       properties: {
         kind: kindProp,
         current: { type: "boolean", description: "Leave out records a closed record supersedes (--current)." },
+        uncommitted: {
+          type: "boolean",
+          description: "Only the records the working tree holds modified or new against HEAD, with the checkout's branch, head and base (--uncommitted, #3160). Takes no at or since.",
+        },
         since: { type: "string", description: "A revision, or a review session id, to compare with (--since)." },
         id: { type: "string", description: "Keep only the record with this id in the document's records." },
         at: atProp,
@@ -154,6 +169,17 @@ export const workspaceReadTools: ToolDefinition[] = [
       },
     },
   },
+  {
+    name: "workspace-agent",
+    description:
+      "An agent session and what it reloads from (#2548): chant workspace agent <name> --json (agent.schema.json). The one member it is bound to, the record kinds and verbs its write scope allows, and the spec records --current prints, read from the repository alone. Without name, this server's session (CHANT_AGENT). Returns the document unchanged.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The session's name, as the declaration's agents list gives it." },
+      },
+    },
+  },
   {
     name: "workspace-work-history",
     description:
@@ -167,6 +193,20 @@ export const workspaceReadTools: ToolDefinition[] = [
       required: ["item"],
     },
   },
+  {
+    name: "workspace-runs",
+    description:
+      "The agent runs in the workspace's run ledger on chant/lifecycle: chant workspace runs --json (runs.schema.json, #3033). Each run has who it worked for, its harness and model, its tokens and cost with the price source, the transcript pinned by hash and the commits it made, and the totals are per work item, per decision and per principal. A run that reports no cost is listed as unpriced, never counted as zero. Returns the document unchanged.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        unit: { type: "string", description: "Only the runs on this work item (--unit)." },
+        decision: { type: "string", description: "Only the runs that carried out this decision, by id or <kind>/<id> (--decision)." },
+        by: { type: "string", description: "Only the runs made for this principal (--by)." },
+        since: { type: "string", description: "Only the runs that made a commit after this revision, or started after it (--since)." },
+      },
+    },
+  },
 ];
 
 export const workspaceWriteTools: ToolDefinition[] = [
@@ -334,11 +374,22 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
         "--json",
       ];
     }
+    case "workspace-agent": {
+      const name = str(params, "name", true)!;
+      return ["workspace", "agent", name, "--json"];
+    }
     case "workspace-work-history": {
       const item = str(params, "item", true)!;
       const kind = str(params, "kind");
       return ["workspace", "work", "history", item, ...(kind !== undefined ? ["--kind", kind] : []), "--json"];
     }
+    case "workspace-runs": {
+      const flags = (["unit", "decision", "by", "since"] as const).flatMap((f) => {
+        const v = str(params, f);
+        return v !== undefined ? [`--${f}`, v] : [];
+      });
+      return ["workspace", "runs", ...flags, "--json"];
+    }
     case "workspace-points": {
       const kind = str(params, "kind");
       return ["workspace", "points", ...(bool(params, "open") ? ["--open"] : []), ...(kind !== undefined ? ["--kind", kind] : []), ...atArgs, "--json"];
@@ -346,11 +397,13 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
     case "workspace-records": {
       const kind = str(params, "kind");
       const since = str(params, "since");
+      if (bool(params, "uncommitted") && (at !== undefined || since !== undefined)) throw new ToolInputError("uncommitted reads the working tree against HEAD, and takes no at or since");
       return [
         "workspace",
         "records",
         ...(kind !== undefined ? ["--kind", kind] : []),
         ...(bool(params, "current") ? ["--current"] : []),
+        ...(bool(params, "uncommitted") ? ["--uncommitted"] : []),
         ...(since !== undefined ? ["--since", since] : []),
         ...atArgs,
         "--json",
@@ -413,10 +466,12 @@ export interface WorkspaceTool {
 export function createWorkspaceTools(options: WorkspaceToolsOptions): WorkspaceTool[] {
   const { cwd } = options;
   const chant = options.chantCommand ?? ownChantCommand();
+  const agent = options.agent ?? (process.env[AGENT_ENV] || undefined);
   const reads: WorkspaceTool[] = workspaceReadTools.map((definition) => ({
     definition,
     handler: async (params) => {
-      const argv = readArgv(definition.name, params);
+      const given = definition.name === "workspace-agent" && params.name === undefined && agent !== undefined ? { ...params, name: agent } : params;
+      const argv = readArgv(definition.name, given);
       const id = definition.name === "workspace-records" ? str(params, "id") : undefined;
       const doc = await runRead(chant, argv, cwd);
       return id !== undefined ? onlyRecord(doc, id) : doc;
@@ -446,6 +501,7 @@ export function createWorkspaceTools(options: WorkspaceToolsOptions): WorkspaceT
         sign: sign(params),
         dryRun: bool(params, "dryRun"),
         cwd,
+        agent,
         through: { source: mcpSource(context), opensInitial: true },
       });
     },
@@ -463,6 +519,7 @@ export function createWorkspaceTools(options: WorkspaceToolsOptions): WorkspaceT
         sign: sign(params),
         dryRun: bool(params, "dryRun"),
         cwd,
+        agent,
         through: { source: mcpSource(context) },
       });
     },
@@ -481,6 +538,7 @@ export function createWorkspaceTools(options: WorkspaceToolsOptions): WorkspaceT
         sign: sign(params),
         dryRun: bool(params, "dryRun"),
         cwd,
+        agent,
       });
     },
     "points-answer": async (params) => {
@@ -498,7 +556,7 @@ export function createWorkspaceTools(options: WorkspaceToolsOptions): WorkspaceT
       const named = str(params, "kind");
       const kind = named !== undefined ? w.resolveWriteKind(named, cwd) : await w.declaredSessionKind(RECORDS_CLOSE_SCHEMA_ID, cwd);
       if (typeof kind !== "string") return kind;
-      return closeRecord({ kind, id, dryRun: bool(params, "dryRun"), cwd });
+      return closeRecord({ kind, id, dryRun: bool(params, "dryRun"), cwd, agent });
     },
   };