@holmes-lab/holmes-kit 0.19.6 → 0.20.0

package/CHANGELOG.md

@@ -5,6 +5,102 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.20.0] - 2026-09-14
+
+The Concurrent Multi-Agent Workspace release. Several agents, machines and clones now work on one spec
+store at the same time and converge through Git without losing identity, authority or evidence. Every
+mechanism below was reproduced first as a failure on the shipped package (in temp workspaces, in real
+Git clones, and in a project OUTSIDE this repository on macOS and Linux), then specified, sealed,
+RED-first tested and shipped — 49 A-SPECs (602–650), each with an official regression run.
+
+### Added
+- **Workspace and run identity** (`workspace_identity`, REQ-623–626): a Git-shareable canonical
+  workspace id (`.ax/workspace.json`) plus a local replica registration (`.ax/state/`, never shared).
+  Every registered MCP write carries `holmes-execution/1` provenance — workspace, replica, run — and
+  CLI operator decisions and autonomy audit are attributed to owned runs. Legacy records without an
+  execution are reported as legacy, never inferred.
+- **Canonical entity identity for specs** (`entity_store`, REQ-627): a spec store can be *adopted*
+  into UUID-keyed entities with journaled, recoverable document transactions (create/edit/move),
+  atomic lock publication, aborted-before-journal recovery, verified-aside publication of updates and
+  deletions, and explicit abandonment of an operation blocked by a third party's state. Sealed bytes
+  are preserved; sealing/unsealing/retirement still require spec-approve authority.
+- **Recoverable display-id renumbering** (`entity_renumber`, REQ-628): rename `REQ-1000 → REQ-1500`
+  while keeping the entity UUID, dependency links, source `@implements` anchors and approval closure;
+  journaled, resumable after a crash, refuses on source-coverage diagnostics it cannot rewrite. The
+  raw legacy `spec_renumber` is journaled and rolls back, and is refused on an activated store.
+- **Git integration of concurrent work** (`entity_integrate`, REQ-629 + 632–637): plan a merge of two
+  Git inputs from a common ancestor over an adopted store, with stable entity identity, per-side
+  structured conflict evidence for every refusal, automatic renumbering of colliding new ids, rename
+  and shape cases, apply under exact-plan approval, recover, abandon, and **discharge** the derived
+  state obligations (graph, semantic cache) with an immutable `discharge.json`. Integration seal
+  transitions land in the provenance ledger as `spec-unsealed`/`spec-approved` events.
+- **Cross-replica double-spend reconciliation** (`ledger_reconcile`, REQ-642/643): single-use approval
+  nonces are consumed on the writer's own replica chain, so offline clones converge through Git
+  without conflicts; a nonce spent on two replicas is detected as a structured double-spend, every
+  authority-spending act (seal, unseal, retire, review resolution, entity acts, `risk_check`, the
+  shell gate) refuses with `ledger-conflict` until an operator reconciles it.
+- **Evidence follows the entity** (REQ-645): red-first test evidence, `ledger_timeline` and
+  integration audits resolve display-id history, so a renumbered A-SPEC keeps its RED→GREEN record.
+- **Approval grants bound to what the human read** (REQ-649): a grant minted by `holmes-kit approve`
+  now names its workspace and, for `spec-approve`, the digest of the spec as the operator read it.
+  A grant copied into another clone is refused as `foreign-workspace`; a seal of content that changed
+  after the decision is refused as `stale-subject` and re-filed. Requests carry the asking run, the
+  subject digest and the risk grade; the queue records `consumed` and `revoked`;
+  `holmes-kit approve --revoke <id> --reason <text>` withdraws a live grant; the grants directory is
+  git-ignored by `init` (a live grant is authority for one workspace, never a shared artifact).
+- **The decision surface** (`holmes-kit approve --status`, REQ-650): workspace and delegation posture
+  (project default / session envelope / off), and per request the risk grade, who asked (run, replica,
+  workspace), the subject digest and exactly what a grant would open (kind, exact target, duration,
+  workspace); recent decisions with their outcome — live until, consumed, expired, revoked, denied.
+  `approve --watch` prints the same picture before each pass that presents new items. The list, the
+  interactive keys and the non-TTY hint are byte-identical to 0.19.
+- **pytest is a first-class RED-first runner** (REQ-647): `test_run` classifies pytest outcomes per file
+  from the JUnit report (`red-error` / `red-assertion` / `green`), a planned file the failed run never
+  reached is `red-error`, and a full-tier run executes the ecosystems the project actually has
+  (jest is assumed only when nothing is detected). Measured in an external Python project: before,
+  a ranged run executed the anchored case and recorded nothing.
+- **Approval status reports re-seal blockers** (`approval_status.resealBlockers`, REQ-641): what a
+  re-seal (spec_approve again, renumber, integration, recovery) would be refused on, evaluated on
+  approved documents too; every re-seal refusal names the document and its findings.
+
+### Changed
+- **The MCP handler module is split** into typed groups (REQ-602–622: phase, risk, adoption, slice
+  orchestration, workspace queries, taint, maintenance, graph, context/review, test execution, review
+  evidence, spec authoring, lifecycle, approval) with public key order, refusal texts, conformance and
+  evidence contracts pinned byte-for-byte; a foreign `root` is refused before graph and review
+  derivation. Full-suite wall time dropped to 285 s.
+- **Derived state converges** (REQ-630/631/644): the semantic vector cache is published in flush
+  segments with owned compaction; the RTM graph is published by atomic replacement and consumers
+  report `current`/`stale`/`unverified`; incremental updates rebuild FILE nodes and import edges from
+  the whole scan. A corrupted `rtm.sqlite` is reported `unreadable` and rebuilt by `rtm_reindex`.
+- **Store boundaries** (REQ-638–640): overlapping store registrations are refused; symlinked store
+  aliases are `unsafe-path` everywhere; the publication window (check → write) is closed with a
+  verified aside and transient leftovers are settled before recovery.
+- **Installer-owned text is never a workspace reference** (REQ-646): the `.gitattributes` marker
+  block and installed skill files that mention `@implements` no longer block integration — measured
+  in every `init`-wired workspace. The marker definitions moved to `project/installer-markers.ts`.
+- **In-workspace view links are not unsafe sources** (REQ-648): the `.agents/skills → .claude/skills`
+  link `init --agent all` writes for Antigravity no longer blocks `entity_renumber`; file links,
+  dangling links and links leaving the workspace keep their diagnostic.
+
+### Fixed
+- Explicit contract citations keep priority in lexical localization (REQ-619); graph reachability is
+  distinguished from ranking-exclusive contribution (REQ-620).
+- A grant read against one spec body could seal a different one; a copied grant could seal in another
+  workspace (both measured on 0.19.6, closed by REQ-649).
+
+### Measured, stated limits
+- External matrix (`docs/goals/probes/external-matrix-2026-09-14.js`): tarball installed outside this
+  repository, `init --agent all`, doctor, pytest RED→GREEN, adoption, two registered clones, Git
+  integration, renumber, derived-state corruption/recovery, the approval round-trip (status → grant →
+  stale refusal → revoke → seal → deny) — every step passes on **macOS 26 arm64** and **Ubuntu 24.04
+  aarch64 (OrbStack)**. Windows native and live Codex / Claude Code / Antigravity sessions in the
+  external workspace were not exercised in this release cycle (previous Windows field validation:
+  2026-09-05, 0.10.1).
+- The session autonomy marker is project-wide (not run-scoped); a grant records the requesting run
+  but binds to the workspace and the subject, not the run. Integration snapshots are bounded at
+  64 MiB of Git objects per read. `decisions.jsonl` does not converge through Git by design.
+
 ## [0.19.6] - 2026-09-11
 
 A correction. 0.19.5 claimed a security improvement that does not reach the people it was written

package/README.md

@@ -16,6 +16,8 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 🧑‍🤝‍🧑 **Concurrent Multi-Agent Workspace** *(new in 0.20.0)*: several agents, machines and clones work on one spec store and converge through Git. A Git-shareable **workspace identity** with per-checkout replica registration (`workspace_identity`) stamps every governed write with run provenance; specs become **UUID-keyed entities** (`entity_store`) whose display ids can be **renumbered without losing identity, anchors or approval closure** (`entity_renumber`); independent work from a common ancestor is **integrated** with stable identity, per-side conflict evidence, automatic renumbering of colliding new ids and explicit derived-state discharge (`entity_integrate`); single-use approvals are spent on the writer's own ledger chain so offline clones merge cleanly, and a nonce spent twice is a structured **double-spend** that freezes every authority-spending act until `ledger_reconcile`. Evidence (RED→GREEN outcomes, timelines) follows the entity across renames. Reproduced end to end in a project outside this repository on macOS and Linux.
+- 🗂️ **Approval decisions you can actually see** *(new in 0.20.0)*: `holmes-kit approve --status` (and the `--watch` header) shows the workspace, the delegation posture, and per request the risk grade, who asked (run · replica · workspace), the subject digest and exactly what a grant would open — plus recent decisions with their outcome (live until / consumed / expired / revoked / denied). A grant is now **bound to the workspace it was minted in and to the content the human read**: a copied grant is refused as `foreign-workspace`, a seal of changed content as `stale-subject`, and `approve --revoke` withdraws a live grant. Grants are git-ignored by `init`.
 - 🔁 **Import cycles are governed, at the three moments that can each do something** *(new in 0.19.0)*: the spec graph has been required to be acyclic since early on; the code graph now is too. **Guidance** reaches the agent before it designs (the authoring playbooks say "share types through a third module", pinned by test). **A design-time advisory** — `approval_status`'s `graphPreview` gains `cycles` — names the cycles your declared files are *already* in, with each edge classified as `type-erasable` (TypeScript deletes it, so it is not a runtime cycle), `lazy-require` (a workaround someone already paid for) or `eager-value`; the note says in words that this is **not** a prediction, because at approval time the code that would create a cycle does not exist yet. **A ratchet** in the Stop hook's constitution catches new cycles after the code is written — shipped in `track` (records, never blocks), and the escape is a **named exception**, never a threshold, so a project carrying legacy cycles can still adopt the harness. This repository went from three cycles to zero, and the two lazy `require()` workarounds they forced are gone.
 - 📐 **Size and fan-in, shown but never judged** *(new in 0.19.0)*: the same design-time advisory carries `architecture` — lines, symbols, longest function, fan-in and fan-out for each declared file. Numbers only: no grade, no threshold, no participation in any verdict. A test pins the *absence* of a severity field, because one would grow into the gate the evidence does not support (the size/defect correlation in the literature is largely "there is more code"). Practitioners still reject inspecting more than five things, so the number is worth seeing — the person decides.
 - 🎯 **Candidates you could actually act on** *(new in 0.19.0)*: the commit-history channel used to admit whatever git named, so ledger files and build baselines took emission slots — measured, **63.3% of candidate slots** went to files that cannot be the answer, one at the head of the list. Now history-derived candidates must be able to be source, vendored trees are demoted, and inside a file the search already found, def-use ranking puts the functions the request reaches through data flow first (symbol Top-10 recall 0.087 → 0.287 on this repository; unchanged on two others, and reported as conditional rather than general).
@@ -240,6 +242,11 @@ flowchart LR
 | `holmes-kit semantic-setup` | Download and verify the local `bge-m3` model (opt-in; shared across projects) |
 | `holmes-kit semantic-check` | Verify local inference **offline**, without downloading anything |
 | `holmes-kit semantic-key set` | Store the cloud-tier key outside the tree (stdin only, never argv) |
+| `holmes-kit approve --status` | The whole approval picture: workspace, delegation, per-request risk/run/subject/grant preview, recent outcomes |
+| `holmes-kit approve --watch` | Resident decision surface: decide with one key as requests arrive (prints the status picture before each new item) |
+| `holmes-kit approve --grant <ref>` | Mint the narrow, workspace- and subject-bound grant for one request (`--ttl`, `--rationale`) |
+| `holmes-kit approve --deny <ref> --reason <text>` | Record a denial the agent sees on its next attempt |
+| `holmes-kit approve --revoke <id> --reason <text>` | Withdraw a live grant; the request must be decided again |
 | `holmes-kit doctor` | Comprehensive health check of specs, hooks, MCP, and anchors |
 | `holmes-kit doctor --fix` | Automatically self-heal and repair broken hooks or missing skills |
 | `holmes-kit ci` | Run non-interactive headless governance gate for GitHub Actions / GitLab CI |
@@ -293,7 +300,7 @@ Full per-cell bases (and every stated limit) live in [docs/language-support.md](
 | OS / Platform | Architecture | Status | Notes |
 | :--- | :--- | :---: | :--- |
 | **macOS** | Apple Silicon (arm64) / Intel (x64) | ✅ Tier 1 | macOS 12+ (Full hook enforcement) |
-| **Linux** | x86_64 / arm64 | ✅ Tier 1 | Ubuntu, Debian, Fedora, Arch, RHEL |
+| **Linux** | x86_64 / arm64 | ✅ Tier 1 | Ubuntu, Debian, Fedora, Arch, RHEL. **Field-validated 2026-09-14** (Ubuntu 24.04 aarch64, OrbStack): tarball install, `init --agent all`, doctor, pytest RED→GREEN, Git integration, renumber, derived-state recovery and the approval round-trip, all from the external matrix probe |
 | **Windows (WSL2)** | x86_64 | ✅ Tier 1 | WSL2 Ubuntu/Debian recommended |
 | **Windows Native** | x86_64 | ✅ Tier 1 | Windows 10/11 (Node.js 20+; prebuilt natives, no build tools needed in the common case). **Field-validated 2026-08-31** on a real user machine: registry install, natives (better-sqlite3 + 7 tree-sitter grammars), both OS gates, MCP handshake (30 tools), interactive init TUI, out-of-band approval channel (doctor 25 PASS; the 4 false FAILs it also showed were doctor's own win32 spawn bug, fixed in 0.3.2). See ADR-015 (platform tier is decided by executed verification — internal decision record) for tier criteria and residual risks (NTFS 8.3 names, reserved device names, 260-char paths; no Windows CI yet) |
 

package/dist/.build-id

@@ -1 +1 @@
-b6de96c3-mtx2uyhs
+e2d9bd59-mu0pzf41

package/dist/holmes/cli/approve-status.d.ts

@@ -0,0 +1,24 @@
+import { QueueState } from '../governance/approval-queue';
+export interface StatusContext {
+    now: string;
+    workspace: {
+        state: 'legacy' | 'initialized' | 'registered';
+        workspaceId?: string;
+        replicaId?: string;
+    };
+    delegation: {
+        mode: 'project-default' | 'session' | 'off';
+        until?: string;
+    };
+    /** Nonces that still have a grant file — a granted decision is LIVE only while its file exists. */
+    liveGrants: ReadonlySet<string>;
+}
+/** What the screen needs from disk: identity (status only, never initializing), delegation, live grant files. */
+export declare function statusContext(root: string, now?: string): StatusContext;
+/**
+ * The whole picture, template-owned: every agent-controlled field goes through the same screen-safe
+ * cells the list uses (A-SPEC-262.1 — a target must never own a line).
+ */
+export declare function renderStatus(state: QueueState, ctx: StatusContext, opts?: {
+    recent?: number;
+}): string;

package/dist/holmes/cli/approve-status.js

@@ -0,0 +1,166 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusContext = statusContext;
+exports.renderStatus = renderStatus;
+// @implements A-SPEC-650
+//
+// The DECISION PICTURE (GOAL §3-A) on the operator's existing terminal surface, chosen by the owner
+// 2026-09-14 over a browser page or harness-only dialogs. Measured on the shipped dist before this
+// slice: `approve --list` showed kind/target/reason/count/since/id; a live grant read as "No requests
+// awaiting approval."; consumed/revoked/denied/expired outcomes and the delegation posture appeared
+// nowhere. Everything here is READ-ONLY and pure over the folded queue + a small context; decisions
+// still go through grantRequest/denyRequest/holdRequest/revokeGrant, and no pinned line of the list,
+// the interactive loop or the key surface changes.
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const approval_grants_1 = require("../governance/approval-grants");
+const workspace_identity_1 = require("../project/workspace-identity");
+const autonomy_1 = require("../governance/autonomy");
+const approve_1 = require("./approve");
+const screen_safe_1 = require("./screen-safe");
+/** What the screen needs from disk: identity (status only, never initializing), delegation, live grant files. */
+function statusContext(root, now = new Date().toISOString()) {
+    let workspace = { state: 'legacy' };
+    try {
+        const id = (0, workspace_identity_1.workspaceIdentity)(root, 'status');
+        workspace = id.state === 'legacy' ? { state: 'legacy' } : { state: id.state, workspaceId: id.workspaceId, ...(id.state === 'registered' ? { replicaId: id.replicaId } : {}) };
+    }
+    catch {
+        workspace = { state: 'legacy' };
+    }
+    let delegation = { mode: 'off' };
+    try {
+        if ((0, autonomy_1.projectDefaultAutonomy)(root))
+            delegation = { mode: 'project-default' };
+        else if ((0, autonomy_1.sessionAutonomyActive)(root, now)) {
+            let until;
+            try {
+                until = String(JSON.parse(fs.readFileSync(path.join(root, ...autonomy_1.SESSION_AUTONOMY_MARKER), 'utf8')).expires);
+            }
+            catch {
+                until = undefined;
+            }
+            delegation = { mode: 'session', ...(until ? { until } : {}) };
+        }
+    }
+    catch {
+        delegation = { mode: 'off' };
+    }
+    const liveGrants = new Set();
+    try {
+        for (const g of (0, approval_grants_1.readGrants)(root).grants)
+            if (typeof g.nonce === 'string')
+                liveGrants.add(g.nonce);
+    }
+    catch { /* no grants dir */ }
+    return { now, workspace, delegation, liveGrants };
+}
+const short = (s, n) => (typeof s === 'string' && s !== '' ? (0, screen_safe_1.rowField)(s.slice(0, n), n) : '');
+const digest12 = (subject) => (typeof subject === 'string' && /^sha256:[0-9a-f]{64}$/.test(subject) ? subject.slice(7, 19) : 'none');
+function askedBy(p) {
+    if (p.execution)
+        return `run ${short(p.execution.runId, 8)} \u00b7 replica ${short(p.execution.replicaId, 8)} \u00b7 workspace ${short(p.execution.workspaceId, 8)}`;
+    return `no run recorded${p.replica && p.replica !== 'unknown' ? ` (replica ${(0, screen_safe_1.rowField)(p.replica, 24)})` : ''}`;
+}
+/** The outcome of a granted decision, judged from the fold and the live grant files. Pure. */
+function grantedOutcome(id, d, ctx) {
+    if (d.consumedTs)
+        return `consumed ${(0, screen_safe_1.rowField)(d.consumedTs, 28)}`;
+    const exp = d.expires ? Date.parse(d.expires) : NaN;
+    const nowMs = Date.parse(ctx.now);
+    const expired = Number.isFinite(exp) && Number.isFinite(nowMs) && nowMs > exp;
+    if (ctx.liveGrants.has(id) && !expired)
+        return `live until ${(0, screen_safe_1.rowField)(d.expires ?? '(no expiry)', 28)}`;
+    if (expired)
+        return `expired ${(0, screen_safe_1.rowField)(d.expires ?? '', 28)}`;
+    return 'spent (no consumption record)';
+}
+/**
+ * The whole picture, template-owned: every agent-controlled field goes through the same screen-safe
+ * cells the list uses (A-SPEC-262.1 — a target must never own a line).
+ */
+function renderStatus(state, ctx, opts) {
+    const lines = [];
+    if (ctx.workspace.state === 'legacy')
+        lines.push('\u25c6 legacy workspace (no identity) \u2014 grants bind to no workspace here');
+    // A replica id is a UUID on a registered clone (measured in the external matrix: the 36-char id clipped
+    // mid-row) and a hostname on legacy chains — show the same 8-char prefix the request rows use for ids.
+    else
+        lines.push(`\u25c6 workspace ${short(ctx.workspace.workspaceId, 8)}${ctx.workspace.replicaId ? ` \u00b7 replica ${/^[0-9a-f-]{36}$/.test(ctx.workspace.replicaId) ? short(ctx.workspace.replicaId, 8) : (0, screen_safe_1.rowField)(ctx.workspace.replicaId, 32)}` : ''}`);
+    if (ctx.delegation.mode === 'project-default')
+        lines.push('\u25c6 delegation: autonomous spec approval ON (project default, .mcp.json) \u2014 governance-critical, high-risk and irreversible still ask you');
+    else if (ctx.delegation.mode === 'session')
+        lines.push(`\u25c6 delegation: autonomous spec approval ON (this session, until ${(0, screen_safe_1.rowField)(ctx.delegation.until ?? '?', 28)}) \u2014 end early: holmes-kit autonomy off`);
+    else
+        lines.push('\u25c6 delegation: autonomous spec approval OFF \u2014 every spec approval is human');
+    lines.push('');
+    if (state.pending.length === 0)
+        lines.push('No requests awaiting approval.');
+    else
+        lines.push(`\u25c6 ${state.pending.length} request(s) awaiting approval`);
+    const bind = ctx.workspace.state === 'legacy' ? 'any workspace (legacy)' : 'this workspace only';
+    state.pending.forEach((p, i) => {
+        lines.push('');
+        lines.push(`[${i + 1}] ${(0, approve_1.subjectCells)(`[${i + 1}]  `, p)}`);
+        lines.push(`    reason: ${(0, screen_safe_1.rowField)(p.why, screen_safe_1.ROW_COLS)}`);
+        lines.push(`    risk: ${(0, screen_safe_1.rowField)(p.risk ?? 'unknown', 12)}   asked by: ${askedBy(p)}`);
+        lines.push(`    subject: ${digest12(p.subject)}   grant would be: ${(0, approve_1.subjectCells)('    subject: xxxxxxxxxxxx   grant would be: ', p)} exact \u00b7 ${approve_1.DEFAULT_TTL_MINUTES} min \u00b7 ${bind}`);
+        const since = p.firstTs ? ` \u00b7 since ${(0, screen_safe_1.rowField)(p.firstTs, 28)}` : '';
+        lines.push(`    blocked ${p.count}x${since}${p.hold ? '   (on hold)' : ''}`);
+        if (p.hold)
+            lines.push(`    question: ${(0, screen_safe_1.rowField)(p.question ?? '(no question)', screen_safe_1.ROW_COLS)}`);
+        lines.push(`    id: ${(0, screen_safe_1.rowField)(p.id, 40)}`);
+    });
+    const decided = Object.entries(state.decisions).sort((a, b) => (Date.parse(b[1].ts) || 0) - (Date.parse(a[1].ts) || 0)).slice(0, opts?.recent ?? 10);
+    if (decided.length > 0) {
+        lines.push('');
+        lines.push(`\u25c6 recent decisions (newest first, up to ${opts?.recent ?? 10})`);
+        for (const [id, d] of decided) {
+            const subject = state.subjects?.[id];
+            const cells = subject ? (0, approve_1.decisionSubject)({ id, kind: subject.kind, target: subject.target, why: '', count: 0, firstTs: '', lastTs: '' }, '  \u2713 granted  ') : (0, screen_safe_1.rowField)(id, 40);
+            if (d.event === 'granted')
+                lines.push(`  \u2713 granted  ${cells}  ${grantedOutcome(id, d, ctx)}`);
+            else if (d.event === 'revoked')
+                lines.push(`  \u2717 revoked  ${cells}  ${(0, screen_safe_1.rowField)(d.reason ?? '(no reason)', screen_safe_1.ROW_COLS)}`);
+            else
+                lines.push(`  \u2717 denied   ${cells}  ${(0, screen_safe_1.rowField)(d.reason ?? '(no reason)', screen_safe_1.ROW_COLS)}`);
+            lines.push(`     id: ${(0, screen_safe_1.rowField)(id, 40)}${d.actor ? ` \u00b7 by ${(0, screen_safe_1.rowField)(d.actor, 24)}` : ''}`);
+        }
+    }
+    if (state.malformedLines > 0)
+        lines.push(`(${state.malformedLines} unreadable line(s) in the queue \u2014 check for corruption)`);
+    return lines.join('\n');
+}

package/dist/holmes/cli/approve-watch.d.ts

@@ -45,6 +45,12 @@ export interface WatchOpts {
     keyStream?: KeyStream;
     /** Called once per NEW pending item (lastPresented dedup) — a throwing notifier is swallowed. */
     notify?: (item: PendingRequest) => void;
+    /**
+     * @implements A-SPEC-650
+     * The status header (workspace, delegation, the per-request picture, recent outcomes), printed once
+     * before each pass that presents NEW items — never on an idle poll. Absent: byte-identical output.
+     */
+    status?: () => string;
 }
 /** Exported for test: the shipped idle wait must resolve at once on abort, not after the timer. */
 export declare function defaultWaitIdle(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/holmes/cli/approve-watch.js

@@ -161,6 +161,12 @@ async function runWatch(root, io, actor, opts = {}) {
                 }
             }
             const shown = new Set(state.pending.map((p) => p.id)); // what this pass presents
+            if (opts.status) {
+                try {
+                    io.print(opts.status());
+                }
+                catch { /* the header is not a lever: a failing renderer never blocks a decision */ }
+            }
             try {
                 if (opts.keyStream)
                     await presentByKey(root, io, actor, opts.keyStream, state);

package/dist/holmes/cli/approve.d.ts

@@ -1,4 +1,22 @@
 import { QueueState, PendingRequest } from '../governance/approval-queue';
+/**
+ * `holmes-kit approve` — the surface where a human decides.
+ *
+ * @implements A-SPEC-246
+ * The queue makes the review list (REQ-244) and grant files deliver approvals with no editing and
+ * no reconnect (REQ-245); what was missing is the surface where the decision happens. Without it
+ * the operator hand-writes grant JSON — scope grammar, expiry format, nonce rules — the exact
+ * "human types values into files" this programme exists to zero out.
+ *
+ * THE DECISION API IS THE HEART; THE TUI IS A SHELL. `grantRequest`/`denyRequest`/`holdRequest`
+ * write the files and events; both the interactive loop and the flags call the same three, so a
+ * CI or remote operator without a TTY is never locked out.
+ *
+ * A GRANT IS DERIVED, NEVER TYPED. kind→scope.kind, target→pattern, id→nonce, now+TTL→expires —
+ * all from the queue entry. The human's inputs are the decision, an optional rationale, and a TTL.
+ * The moment the human must know scope syntax, this UI has no reason to exist.
+ */
+export declare const DEFAULT_TTL_MINUTES = 30;
 export type DecisionResult = {
     ok: true;
     expires?: string;
@@ -11,6 +29,15 @@ export declare function grantRequest(root: string, id: string, opts: {
     ttlMinutes?: number;
     rationale?: string;
 }): DecisionResult;
+/**
+ * @implements A-SPEC-649
+ * Withdraw a live grant. The operator changed their mind, or the request's subject moved on: the
+ * file goes, and the queue says so — a `revoked` decision the fold reads like a denial. Refuses
+ * an empty reason (a revocation the agent cannot read is invisible) and an id that was never
+ * granted here (nothing to withdraw). A grant already spent has no file; revoking it records the
+ * intent for the audit trail but cannot un-seal — the ledger is the record of what happened.
+ */
+export declare function revokeGrant(root: string, id: string, reason: string, actor: string): DecisionResult;
 export declare function denyRequest(root: string, id: string, reason: string, actor: string): DecisionResult;
 /** Hold with a question — approve/deny later. The agent carries the question to the user. */
 export declare function holdRequest(root: string, id: string, question: string, actor: string): DecisionResult;

package/dist/holmes/cli/approve.js

@@ -33,7 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TTL_MINUTES = void 0;
 exports.grantRequest = grantRequest;
+exports.revokeGrant = revokeGrant;
 exports.denyRequest = denyRequest;
 exports.holdRequest = holdRequest;
 exports.staleView = staleView;
@@ -45,13 +47,16 @@ exports.decisionDetail = decisionDetail;
 exports.renderRefusals = renderRefusals;
 exports.renderNonTtyHint = renderNonTtyHint;
 exports.runInteractive = runInteractive;
-// @implements A-SPEC-246
+// @implements A-SPEC-246, A-SPEC-626
+const execution_context_1 = require("../project/execution-context");
+const root_1 = require("../project/root");
 const fs = __importStar(require("node:fs"));
 const npx_bin_1 = require("../project/npx-bin");
 const path = __importStar(require("node:path"));
 const approval_queue_1 = require("../governance/approval-queue");
 const screen_safe_1 = require("./screen-safe");
 const approval_grants_1 = require("../governance/approval-grants");
+const workspace_identity_1 = require("../project/workspace-identity");
 /**
  * `holmes-kit approve` — the surface where a human decides.
  *
@@ -69,7 +74,7 @@ const approval_grants_1 = require("../governance/approval-grants");
  * all from the queue entry. The human's inputs are the decision, an optional rationale, and a TTL.
  * The moment the human must know scope syntax, this UI has no reason to exist.
  */
-const DEFAULT_TTL_MINUTES = 30;
+exports.DEFAULT_TTL_MINUTES = 30; // A-SPEC-650: the status surface names the default grant duration
 // @implements A-SPEC-262.1 — round-5: the guard bounded TTL below only. `--ttl 1e12` threw an
 // uncaught RangeError out of the interactive loop (killing every remaining decision on the surface
 // whose purpose is making decisions cheap), and `--ttl 1e10` minted a grant expiring in the year
@@ -143,13 +148,14 @@ const isWritablePath = (file) => {
 };
 const appendEvent = (root, event) => {
     try {
+        const execution = (0, execution_context_1.executionForRoot)((0, root_1.resolveProjectRoot)(root).root);
         const file = path.join(root, approval_queue_1.QUEUE_RELPATH);
         if (!fs.existsSync(path.join(root, '.ax')))
             return false;
         fs.mkdirSync(path.dirname(file), { recursive: true });
         if (!isWritablePath(file))
             return false;
-        fs.appendFileSync(file, JSON.stringify({ ...event, ts: new Date().toISOString() }) + '\n');
+        fs.appendFileSync(file, JSON.stringify({ ...event, ts: new Date().toISOString(), ...(execution ? { execution } : {}) }) + '\n');
         return true;
     }
     catch {
@@ -181,7 +187,7 @@ function recordIsSelfConsistent(entry) {
     return entry.id === (0, approval_queue_1.approvalRequestId)(entry.kind, entry.target);
 }
 function grantRequest(root, id, opts) {
-    const ttl = opts.ttlMinutes ?? DEFAULT_TTL_MINUTES;
+    const ttl = opts.ttlMinutes ?? exports.DEFAULT_TTL_MINUTES;
     if (typeof ttl !== 'number' || !Number.isFinite(ttl) || !Number.isInteger(ttl) || ttl <= 0 || ttl > MAX_TTL_MINUTES) {
         return { ok: false, reason: `TTL must be an integer number of minutes in 1..${MAX_TTL_MINUTES} — received: ${(0, screen_safe_1.rowField)(String(ttl), 40)}` };
     }
@@ -196,7 +202,25 @@ function grantRequest(root, id, opts) {
     // second guard is not defence in depth, it is a line nobody can prove still works (round-3
     // mutation test: neutering it left the suite green).
     const expires = new Date(Date.now() + ttl * 60_000).toISOString();
+    // @implements A-SPEC-649 — the grant names WHERE it was minted and WHAT the operator read, so a
+    // copy in another clone and a seal of changed content are refused by name (measured 2026-09-14:
+    // both were accepted). A legacy workspace has no id to name; a request filed without a subject
+    // (shell, config-write: the target already IS the content) binds to the workspace only.
+    let workspace;
+    try {
+        const identity = (0, workspace_identity_1.workspaceIdentity)(root, 'status');
+        workspace = identity.state === 'legacy' ? undefined : identity.workspaceId;
+    }
+    catch {
+        workspace = undefined;
+    }
+    const binding = {
+        ...(workspace ? { workspace } : {}),
+        ...(entry.subject ? { subject: entry.subject } : {}),
+        ...(entry.execution?.runId ? { requestedBy: entry.execution.runId } : {}),
+    };
     const grant = {
+        ...binding,
         actor: opts.actor,
         token: 'grant',
         rationale: opts.rationale?.trim() ? opts.rationale : DEFAULT_RATIONALE,
@@ -229,7 +253,7 @@ function grantRequest(root, id, opts) {
         // class round-6 closed in findingContext, three files over.
         return { ok: false, reason: `cannot write the grant file:\n   ${(0, screen_safe_1.rowField)(e instanceof Error ? e.message : String(e), 76)}` };
     }
-    if (!appendEvent(root, { event: 'granted', id, actor: opts.actor, expires, covered: entry.count })) {
+    if (!appendEvent(root, { event: 'granted', id, actor: opts.actor, expires, covered: entry.count, ...binding })) {
         try {
             fs.rmSync(tmp, { force: true });
         }
@@ -244,6 +268,43 @@ function grantRequest(root, id, opts) {
     }
     return { ok: true, expires };
 }
+/**
+ * @implements A-SPEC-649
+ * Withdraw a live grant. The operator changed their mind, or the request's subject moved on: the
+ * file goes, and the queue says so — a `revoked` decision the fold reads like a denial. Refuses
+ * an empty reason (a revocation the agent cannot read is invisible) and an id that was never
+ * granted here (nothing to withdraw). A grant already spent has no file; revoking it records the
+ * intent for the audit trail but cannot un-seal — the ledger is the record of what happened.
+ */
+function revokeGrant(root, id, reason, actor) {
+    if (typeof reason !== 'string' || reason.trim() === '')
+        return { ok: false, reason: 'a revocation needs a --reason the agent can read' };
+    const decided = (0, approval_queue_1.readQueue)(root, { includeAllKinds: true }).decisions[id];
+    const dir = path.join(root, approval_grants_1.GRANTS_RELDIR);
+    let hadFile = false;
+    try {
+        hadFile = fs.readdirSync(dir).some((n) => n === `${id}.json` && fs.lstatSync(path.join(dir, n)).isFile());
+    }
+    catch {
+        hadFile = false;
+    }
+    if (!hadFile && decided?.event !== 'granted')
+        return { ok: false, reason: `no grant to revoke for ${(0, screen_safe_1.rowField)(id, 40)} — nothing was granted here` };
+    if (hadFile) {
+        try {
+            fs.rmSync(path.join(dir, `${id}.json`), { force: true });
+        }
+        catch (e) {
+            return { ok: false, reason: `could not remove the grant file:\n   ${(0, screen_safe_1.rowField)(e instanceof Error ? e.message : String(e), 76)}` };
+        }
+    }
+    if (!appendEvent(root, { event: 'revoked', id, reason, actor })) {
+        return { ok: false, reason: hadFile
+                ? 'the grant file is gone but the revocation could not be recorded (queue event) — check write permission on .ax/approvals'
+                : 'could not write the revocation record (queue event) — check write permission on .ax/approvals. Nothing was recorded' };
+    }
+    return { ok: true };
+}
 function denyRequest(root, id, reason, actor) {
     const { entry } = findPending(root, id);
     if (!entry)
@@ -570,8 +631,8 @@ async function runInteractive(root, io, actor) {
         }
         else if (answer === 'e') {
             const rationale = (await io.ask(`reason (enter = "${DEFAULT_RATIONALE}") > `)).trim();
-            const ttlRaw = (await io.ask(`ttl (minutes, enter = ${DEFAULT_TTL_MINUTES}) > `)).trim();
-            const ttl = ttlRaw === '' ? DEFAULT_TTL_MINUTES : Number(ttlRaw);
+            const ttlRaw = (await io.ask(`ttl (minutes, enter = ${exports.DEFAULT_TTL_MINUTES}) > `)).trim();
+            const ttl = ttlRaw === '' ? exports.DEFAULT_TTL_MINUTES : Number(ttlRaw);
             const r = grantRequest(root, p.id, { actor, rationale, ttlMinutes: ttl });
             // @implements A-SPEC-262.1 — round-6: this branch alone RETURNED on failure, so a mistyped TTL
             // ("30min") ended the whole session with exit 0 and every remaining item undecided — measured on

package/dist/holmes/cli/cli-execution.d.ts

@@ -0,0 +1,2 @@
+/** Operator recovery predates registration: lookup failure removes attribution, never authority checks. */
+export declare function runOperatorExecution<T>(target: string, act: () => T): T;

package/dist/holmes/cli/cli-execution.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runOperatorExecution = runOperatorExecution;
+// @implements A-SPEC-626
+const node_crypto_1 = require("node:crypto");
+const root_1 = require("../project/root");
+const workspace_identity_1 = require("../project/workspace-identity");
+const execution_context_1 = require("../project/execution-context");
+/** Operator recovery predates registration: lookup failure removes attribution, never authority checks. */
+function runOperatorExecution(target, act) {
+    let root = target;
+    let execution;
+    try {
+        const resolved = (0, root_1.resolveProjectRoot)(target);
+        root = resolved.root;
+        if (resolved.marker === '.ax') {
+            const identity = (0, workspace_identity_1.workspaceIdentity)(root);
+            if (identity.state === 'registered')
+                execution = { schema: 'holmes-execution/1', workspaceId: identity.workspaceId, replicaId: identity.replicaId, runId: (0, node_crypto_1.randomUUID)() };
+        }
+    }
+    catch { /* identity lookup only; the actual command's errors are not caught here */ }
+    return (0, execution_context_1.withOwnedExecution)(root, execution, act);
+}

package/dist/holmes/cli/gitignore-merge.d.ts

@@ -1,8 +1,3 @@
-/**
- * PURE .gitignore block merge. holmes-kit writes derived state under `.ax/` in the TARGET project
- * (ledger, cpg_cache, reports) that must never be committed. The block is delimited so it can be
- * added, refreshed, and removed exactly — never touching the user's own lines.
- */
 export declare const BEGIN = "# >>> holmes-kit >>>";
 export declare const END = "# <<< holmes-kit <<<";
 /** Derived/runtime paths holmes-kit creates in a target project. */

package/dist/holmes/cli/gitignore-merge.js

@@ -11,8 +11,9 @@ exports.hasGitignoreBlock = hasGitignoreBlock;
  * (ledger, cpg_cache, reports) that must never be committed. The block is delimited so it can be
  * added, refreshed, and removed exactly — never touching the user's own lines.
  */
-exports.BEGIN = '# >>> holmes-kit >>>';
-exports.END = '# <<< holmes-kit <<<';
+const installer_markers_1 = require("../project/installer-markers");
+exports.BEGIN = installer_markers_1.HOLMES_BLOCK_BEGIN; // A-SPEC-646 — the walk that must ignore this block reads the same definition
+exports.END = installer_markers_1.HOLMES_BLOCK_END;
 /** Derived/runtime paths holmes-kit creates in a target project. */
 exports.IGNORE_LINES = [
     // @implements A-SPEC-148
@@ -41,6 +42,9 @@ exports.IGNORE_LINES = [
     // the human saw" — round-14, exact match). Raw-and-local is the only shape that serves both ADR-012
     // and approvals: the file never leaves the machine, and `holmes-kit approve` reads it right there.
     '.ax/approvals/refusals*.jsonl',
+    // @implements A-SPEC-649 — a minted grant is LIVE AUTHORITY for one workspace; committed and
+    // pulled, it would open the same door in every clone (measured: a copied grant sealed elsewhere).
+    '.ax/approvals/grants/',
     // @implements A-SPEC-193 — 하네스 배선물은 이 **설치본의 절대 경로**를 담는다(훅은 hooks.json
     // 이 있는 디렉터리를 cwd 로 돌고, 패키지가 어디 설치됐는지는 기계마다 다르다). 그 경로가
     // VCS 에 들어가면 다른 기계에서 남의 설치를 부르거나 아무것도 부르지 못한다. 팀과 공유하고