@skrr-ai/cli 0.1.108 → 0.1.110

package/dist/lib/daemon-machine-identity-copy.d.ts

@@ -0,0 +1,14 @@
+import type { DaemonMachineIdentitySkew } from './daemon-machine-identity';
+/**
+ * What to tell someone whose installed background service would register their
+ * profile on the default profile's machine row (OSK-S-440).
+ *
+ * The consequence is stated before the remedy because the remedy costs something
+ * (updating a service) and the consequence is what justifies it: a second
+ * profile on the default's row replaces its Daemon and its device-key pin, and
+ * the default profile's next refresh is refused until it signs in again.
+ *
+ * Lives here, apart from the comparison, because this is copy and reads
+ * `BRAND.displayName`; the comparison is pure and imports nothing from it.
+ */
+export declare function describeDaemonMachineIdentitySkew(skew: DaemonMachineIdentitySkew): string[];

package/dist/lib/daemon-machine-identity-copy.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeDaemonMachineIdentitySkew = describeDaemonMachineIdentitySkew;
+const data_provider_1 = require("@skrr-ai/data-provider");
+/**
+ * What to tell someone whose installed background service would register their
+ * profile on the default profile's machine row (OSK-S-440).
+ *
+ * The consequence is stated before the remedy because the remedy costs something
+ * (updating a service) and the consequence is what justifies it: a second
+ * profile on the default's row replaces its Daemon and its device-key pin, and
+ * the default profile's next refresh is refused until it signs in again.
+ *
+ * Lives here, apart from the comparison, because this is copy and reads
+ * `BRAND.displayName`; the comparison is pure and imports nothing from it.
+ */
+function describeDaemonMachineIdentitySkew(skew) {
+    const product = data_provider_1.BRAND.displayName;
+    const said = skew.reported
+        ? `it reports machine identity ${skew.reported}, where profile '${skew.profile}' has ${skew.expected}`
+        : `it does not report a machine identity at all, so ${product} cannot tell which one it would use`;
+    return [
+        `The ${product} background service at ${skew.binary} does not support a separate machine identity per profile: ${said}.`,
+        `Using it for '${skew.profile}' would register that profile on the default profile's machine and could replace the default profile's device-key pin. Nothing was changed.`,
+        `Update the background service (skrr daemon update), or put a current skrrd first on your PATH, then run: skrr login --profile ${skew.profile}`,
+    ];
+}

package/dist/lib/daemon-machine-identity.d.ts

@@ -0,0 +1,27 @@
+export interface DaemonMachineIdentitySkew {
+    /** The profile being signed in. */
+    profile: string;
+    /** The machine identity this profile has, as decided by the profile's own record. */
+    expected: string;
+    /** What the daemon binary says it will send; null when it said nothing. */
+    reported: string | null;
+    /** The `skrrd` that was asked. */
+    binary: string;
+}
+/**
+ * Null when the daemon will register this profile under the identity it has;
+ * otherwise what disagrees.
+ *
+ * Not applicable to the default profile (its identity is the hardware value in
+ * every version), to a hosted runtime (the control plane issues it), or when no
+ * profile is named.
+ *
+ * A daemon that reports NOTHING is a skew, not a pass: this check exists because
+ * an older binary cannot say, and "could not confirm" must not read as "fine" on
+ * the step that binds a credential to a machine row.
+ */
+export declare function daemonMachineIdentitySkew(opts: {
+    profile: string | null | undefined;
+    binary: string;
+    reported: string | null | undefined;
+}): DaemonMachineIdentitySkew | null;

package/dist/lib/daemon-machine-identity.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.daemonMachineIdentitySkew = daemonMachineIdentitySkew;
+/**
+ * daemon-machine-identity.ts — does the installed daemon give this profile the
+ * machine identity the CLI decided it has?
+ *
+ * Two programs compute one identity: the CLI (and the profile's persisted
+ * `machine-identity.json`) say a profile that started new has its own machine
+ * row, and the DAEMON is what registers. A daemon that predates per-profile
+ * identities (OSK-13845) does not read that file; it sends the hardware value
+ * whatever the profile is. Nothing noticed. The CLI minted the daemon's credential
+ * for what the daemon REPORTED (`accept-handoff --print-id`), so the credential
+ * was bound to the default machine's row, the service registered there, and the
+ * failure OSK-13845 exists to prevent happened anyway: two profiles on one Daemon
+ * row and one device-key pin, the second profile's interactive login re-pinning
+ * the first one's key (OSK-S-440, profile `aapexp`).
+ *
+ * Measured, not inferred: the same new profile, in an empty home, answered by
+ * two `skrrd` binaries. The current one reports `<hardware>:p-<hash>` and writes
+ * `machine-identity.json` and `daemon-identity.json`; the build that was first on
+ * the dogfooder's PATH (a checkout `dist` from before OSK-13845, whose version
+ * string still reads the checkout's package.json) reports the bare hardware value
+ * and writes neither. The profile it left behind had a `machine-identity.json`
+ * (the CLI's) and no `daemon-identity.json` after four daemon starts.
+ *
+ * The fix is to compare, not to guess a version: ask the binary what it will
+ * send, compare with what this profile's decided identity is, and refuse BEFORE
+ * anything is minted or installed when they differ. Comparing the value is the
+ * only test that cannot be wrong about a build that is older than its own
+ * version string says.
+ *
+ * Pure: the I/O (spawning the binary) is in `daemonHandoff.ts`, the copy in
+ * `daemon-machine-identity-copy.ts`.
+ */
+const machine_uuid_1 = require("@skrr-ai/auth-core/machine-uuid");
+const keychain_1 = require("./keychain");
+/**
+ * Null when the daemon will register this profile under the identity it has;
+ * otherwise what disagrees.
+ *
+ * Not applicable to the default profile (its identity is the hardware value in
+ * every version), to a hosted runtime (the control plane issues it), or when no
+ * profile is named.
+ *
+ * A daemon that reports NOTHING is a skew, not a pass: this check exists because
+ * an older binary cannot say, and "could not confirm" must not read as "fine" on
+ * the step that binds a credential to a machine row.
+ */
+function daemonMachineIdentitySkew(opts) {
+    const profile = opts.profile?.trim();
+    if (!profile || profile === keychain_1.DEFAULT_PROFILE)
+        return null;
+    if ((0, machine_uuid_1.hostedRuntimeIdOverride)('OVERSKY_MACHINE_UUID'))
+        return null;
+    const expected = (0, machine_uuid_1.getMachineUuidForProfile)(profile);
+    const reported = opts.reported?.trim() || null;
+    if (reported === expected)
+        return null;
+    return { profile, expected, reported, binary: opts.binary };
+}

package/dist/lib/daemon-setup.js

@@ -33,7 +33,9 @@ exports.offerDaemonSetup = offerDaemonSetup;
  * with an instruction when there is not, and never on the opt-out.
  */
 const auth_core_1 = require("@skrr-ai/auth-core");
+const data_provider_1 = require("@skrr-ai/data-provider");
 const prompt_1 = require("./prompt");
+const daemon_command_hint_1 = require("./daemon-command-hint");
 const daemon_binding_1 = require("./daemon-binding");
 const daemon_handoff_opt_out_1 = require("./daemon-handoff-opt-out");
 const exec_runtime_binary_1 = require("./exec-runtime-binary");
@@ -94,8 +96,15 @@ async function offerDaemonSetup(opts = {}) {
     }
     const confirmImpl = opts.confirmImpl ?? prompt_1.confirm;
     log('');
-    log('  This computer has no skrr background service. It is what lets your agents work here —');
+    log(`  This computer has no ${data_provider_1.BRAND.displayName} background service. It is what lets your agents work here —`);
     log('  running commands, editing files, and driving a browser on this machine.');
+    // What it does UNASKED is part of the decision, and it used to be found
+    // afterwards in a status table (OSK-16439). The defaults are the daemon's
+    // (`DEFAULT_CONFIG.permissions`, pinned against this sentence by
+    // `unattended-posture.spec.ts` in the daemon): reads, writes, shell commands
+    // and Claude sessions run without a prompt until someone changes them.
+    log('  Until you change it, agents can read files, edit files and run shell commands here');
+    log(`  without asking you first. To be asked before each call instead: \`${(0, daemon_command_hint_1.daemonCommandHint)('config', { extraArgs: '--require-approvals' })}\``);
     // This creates a persistent service with broad local capabilities, so a
     // bare Enter must visibly and behaviorally decline it. `confirm` names its
     // second argument `defaultNo`; passing false showed `[Y/n]` and accepted an

package/dist/lib/daemonBrokerRefusal.js

@@ -5,6 +5,7 @@ exports.describeBrokerRefusal = describeBrokerRefusal;
 exports.describeGuestDaemonUnavailable = describeGuestDaemonUnavailable;
 exports.describeLocalDaemonUnavailable = describeLocalDaemonUnavailable;
 exports.describeBrokerFailure = describeBrokerFailure;
+const daemon_command_hint_1 = require("./daemon-command-hint");
 /**
  * True when a daemon ANSWERED the hand-off and refused it — as opposed to no
  * daemon being there to ask (`no_bootstrap`, a stale descriptor nobody listens
@@ -89,12 +90,12 @@ function describeBrokerRefusal(failure, bin = 'skrr') {
     }
     else if (code === 'DEVICE_PROOF_PIN_MISMATCH') {
         remedy =
-            `Run \`${bin} daemon login\` to sign the background service in again — an interactive daemon login re-pins its device key — then retry. ` +
+            `Run \`${(0, daemon_command_hint_1.daemonCommandHint)('login', { bin })}\` to sign the background service in again — an interactive daemon login re-pins its device key — then retry. ` +
                 `\`${bin} login\` signs this CLI in on its own instead.`;
     }
     else if (DAEMON_RELOGIN_CODES.has(code) || failure.reason === 'daemon_not_authed') {
         remedy =
-            `Run \`${bin} daemon login\` to sign the background service in again, then retry. ` +
+            `Run \`${(0, daemon_command_hint_1.daemonCommandHint)('login', { bin })}\` to sign the background service in again, then retry. ` +
                 `\`${bin} login\` signs this CLI in on its own instead.`;
     }
     else if (failure.reason === 'ci_token_refused') {

package/dist/lib/daemonHandoff.d.ts

@@ -1,3 +1,4 @@
+import { type DaemonMachineIdentitySkew } from './daemon-machine-identity';
 /**
  * Hand the local daemon a credential of its own, right after `skrr login`.
  *
@@ -40,8 +41,25 @@ export interface DaemonHandoffOutcome {
      * The two absent cases are separated because they need different work — one
      * needs a binary fetched, the other only needs the service registered.
      */
-    reason?: 'opted-out' | 'brokered' | 'no-binary' | 'legacy-binary' | 'unsupported-daemon' | 'no-service' | 'foreign-root' | 'mint-refused' | 'platform-managed';
+    reason?: 'opted-out' | 'brokered' | 'no-binary' | 'legacy-binary' | 'unsupported-daemon' | 'no-service' | 'foreign-root' | 'mint-refused' | 'platform-managed' | 'machine-identity-skew';
+    /** Set with `reason: 'machine-identity-skew'`; the caller words it. */
+    skew?: DaemonMachineIdentitySkew;
 }
 export declare function handOffToLocalDaemon(env?: NodeJS.ProcessEnv, opts?: {
     loginFlow?: string;
 }): Promise<DaemonHandoffOutcome>;
+/**
+ * Ask the installed daemon which machine identity it will register `profile`
+ * under, and say what disagrees with the profile's own (OSK-S-440).
+ *
+ * For the commands that install or sign in a daemon WITHOUT going through the
+ * credential hand-off (`skrr daemon install`, `skrr daemon login`): the same
+ * question, asked of the binary they are about to run. Null when the daemon
+ * agrees, when the profile is the default one, or when there is no binary to ask
+ * (the caller has its own answer for that).
+ *
+ * A binary that cannot be asked at all - too old to have `accept-handoff`, or
+ * one that fails the probe - is reported as a skew with no identity, because the
+ * point of asking is not to bind a profile to a machine row on a guess.
+ */
+export declare function checkLocalDaemonMachineIdentity(profile: string | null | undefined, binary?: string | null): Promise<DaemonMachineIdentitySkew | null>;

package/dist/lib/daemonHandoff.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handOffToLocalDaemon = handOffToLocalDaemon;
+exports.checkLocalDaemonMachineIdentity = checkLocalDaemonMachineIdentity;
 const node_child_process_1 = require("node:child_process");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const config_1 = require("./config");
 const daemon_handoff_opt_out_1 = require("./daemon-handoff-opt-out");
+const daemon_machine_identity_1 = require("./daemon-machine-identity");
 const dedicated_service_1 = require("./dedicated-service");
 const exec_runtime_binary_1 = require("./exec-runtime-binary");
 const keychain_1 = require("./keychain");
@@ -256,7 +258,8 @@ async function handOffToLocalDaemon(env = process.env, opts = {}) {
         return {
             status: 'skipped',
             reason: 'unsupported-daemon',
-            detail: 'the installed daemon predates `accept-handoff`; run `skrr daemon login` once',
+            // The remedy is named by the caller, spelled for the profile (OSK-16435).
+            detail: 'the installed daemon is too old to accept a hand-off',
         };
     }
     // Ask the daemon which id it will bind, rather than deriving it here. The id
@@ -274,6 +277,26 @@ async function handOffToLocalDaemon(env = process.env, opts = {}) {
         };
     }
     const { idSource, machineUuid, daemonServer } = parseIdProvenance(printed.stderr);
+    // Before anything is minted or installed: does THIS binary register the profile
+    // under the machine identity the profile has? The mint below binds the
+    // credential to the machine uuid the daemon just REPORTED, so a binary that
+    // reports the hardware value for a profile that has its own would put it on the
+    // default profile's row - and the install that follows would run that same
+    // binary as a service. Nothing about the id or the provenance would look wrong.
+    const skew = (0, daemon_machine_identity_1.daemonMachineIdentitySkew)({
+        profile: (0, keychain_1.getActiveProfile)(),
+        binary,
+        reported: machineUuid,
+    });
+    if (skew) {
+        return {
+            status: 'failed',
+            reason: 'machine-identity-skew',
+            skew,
+            detail: `the installed daemon reports machine identity ${skew.reported ?? '(none)'} ` +
+                `where profile '${skew.profile}' has ${skew.expected}`,
+        };
+    }
     // A well-formed id is not the same as a real daemon. With no service installed
     // the daemon derives one from whatever directory this process is in, so the id
     // above names a daemon that does not exist and will not exist under that id if
@@ -353,3 +376,40 @@ async function handOffToLocalDaemon(env = process.env, opts = {}) {
         }),
     };
 }
+/**
+ * Ask the installed daemon which machine identity it will register `profile`
+ * under, and say what disagrees with the profile's own (OSK-S-440).
+ *
+ * For the commands that install or sign in a daemon WITHOUT going through the
+ * credential hand-off (`skrr daemon install`, `skrr daemon login`): the same
+ * question, asked of the binary they are about to run. Null when the daemon
+ * agrees, when the profile is the default one, or when there is no binary to ask
+ * (the caller has its own answer for that).
+ *
+ * A binary that cannot be asked at all - too old to have `accept-handoff`, or
+ * one that fails the probe - is reported as a skew with no identity, because the
+ * point of asking is not to bind a profile to a machine row on a guess.
+ */
+async function checkLocalDaemonMachineIdentity(profile, binary = (0, exec_runtime_binary_1.findRuntimeBinary)()) {
+    if (!profile || profile === keychain_1.DEFAULT_PROFILE || !binary)
+        return null;
+    const printed = await runOversky(binary, ['accept-handoff', '--print-id', '--profile', profile], {
+        timeoutMs: PROBE_TIMEOUT_MS,
+    });
+    if (!printed.ok) {
+        // A daemon too old to have `accept-handoff` answers "unknown command": it is
+        // older than per-profile identities too, which is the skew itself.
+        if (/unknown command/i.test(printed.stderr)) {
+            return (0, daemon_machine_identity_1.daemonMachineIdentitySkew)({ profile, binary, reported: null });
+        }
+        // Any other failed probe says nothing about the daemon's identity, and
+        // refusing a sign-in on a flaky probe would be a worse failure than the one
+        // this guards: let the command run and meet whatever the daemon itself says.
+        return null;
+    }
+    return (0, daemon_machine_identity_1.daemonMachineIdentitySkew)({
+        profile,
+        binary,
+        reported: parseIdProvenance(printed.stderr).machineUuid,
+    });
+}

package/dist/lib/deployed-build.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What the server this CLI talks to is running: the commit its API was built
+ * from and the commit its web shell was built from (OSK-15497).
+ *
+ * Both are public facts the server already publishes for anyone:
+ *   - the API: `GET /api/health` → `build.commit`, baked into the image once at
+ *     build time by the release pipeline;
+ *   - the web: `GET /web-version.json` → `sha`, written into the shell when it
+ *     is published.
+ *
+ * They are read separately and shown separately because they legitimately
+ * differ: a release that changes only API code keeps the published shell, and
+ * a frontend-only release keeps the API image. Collapsing them into one
+ * "deployed version" would be wrong whenever that happens, which is often.
+ *
+ * Neither read needs a credential, and neither failure is the user's problem,
+ * so a failure is reported as "could not read" with the reason, never as an
+ * error that fails `doctor`.
+ */
+export type BuildCommitRead = {
+    /** The 40-hex commit, or null when the server did not name one. */
+    commit: string | null;
+    /** Where it was read from, so a reader can check it themselves. */
+    source: string;
+    /** Why there is no commit: unreadable, or the server reports an unstamped build. */
+    error: string | null;
+};
+export type DeployedBuild = {
+    api: BuildCommitRead;
+    web: BuildCommitRead;
+};
+type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+export declare function readDeployedBuild(baseURL: string, fetchImpl?: FetchLike): Promise<DeployedBuild>;
+/** The lines `skrr doctor` prints under the server. */
+export declare function deployedBuildLines(build: DeployedBuild): string[];
+export {};

package/dist/lib/deployed-build.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * What the server this CLI talks to is running: the commit its API was built
+ * from and the commit its web shell was built from (OSK-15497).
+ *
+ * Both are public facts the server already publishes for anyone:
+ *   - the API: `GET /api/health` → `build.commit`, baked into the image once at
+ *     build time by the release pipeline;
+ *   - the web: `GET /web-version.json` → `sha`, written into the shell when it
+ *     is published.
+ *
+ * They are read separately and shown separately because they legitimately
+ * differ: a release that changes only API code keeps the published shell, and
+ * a frontend-only release keeps the API image. Collapsing them into one
+ * "deployed version" would be wrong whenever that happens, which is often.
+ *
+ * Neither read needs a credential, and neither failure is the user's problem,
+ * so a failure is reported as "could not read" with the reason, never as an
+ * error that fails `doctor`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readDeployedBuild = readDeployedBuild;
+exports.deployedBuildLines = deployedBuildLines;
+const COMMIT = /^[a-f0-9]{40}$/;
+const TIMEOUT_MS = 5_000;
+async function readCommit(url, pick, unstamped, fetchImpl) {
+    try {
+        const res = await fetchImpl(url, {
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return { commit: null, source: url, error: `HTTP ${res.status}` };
+        const value = pick(await res.json());
+        if (typeof value === 'string' && COMMIT.test(value)) {
+            return { commit: value, source: url, error: null };
+        }
+        return { commit: null, source: url, error: unstamped };
+    }
+    catch (err) {
+        return {
+            commit: null,
+            source: url,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+async function readDeployedBuild(baseURL, fetchImpl = fetch) {
+    const origin = baseURL.replace(/\/+$/, '');
+    const [api, web] = await Promise.all([
+        readCommit(`${origin}/api/health`, (body) => body?.build?.commit, 'the server does not report the commit its API was built from', fetchImpl),
+        readCommit(`${origin}/web-version.json`, (body) => body?.sha, 'the published web shell carries no commit', fetchImpl),
+    ]);
+    return { api, web };
+}
+const short = (sha) => sha.slice(0, 12);
+/** The lines `skrr doctor` prints under the server. */
+function deployedBuildLines(build) {
+    const describe = (read) => read.commit ? short(read.commit) : `unknown (${read.error ?? 'no commit'})`;
+    const lines = [`Deployed: API ${describe(build.api)} · web ${describe(build.web)}`];
+    if (build.api.commit && build.web.commit && build.api.commit !== build.web.commit) {
+        lines.push('          Built from different commits. That is normal: a release that changes only ' +
+            'one of them keeps the other as it was.');
+    }
+    return lines;
+}

package/dist/lib/grants.d.ts

@@ -1,4 +1,5 @@
 import type { GrantAccess, GrantAccessSource } from '@skrr-ai/data-provider';
+import { type TableColumn } from './format';
 export declare const GRANT_PRINCIPAL_KINDS: readonly ["agent", "commitment"];
 export declare const GRANT_CREDENTIAL_KINDS: readonly ["env", "bearer", "basic", "json"];
 export interface GrantPrincipal {
@@ -20,7 +21,8 @@ export interface Grant {
         configured: boolean;
         kind?: string;
         envKeys: string[];
-        fingerprint?: string;
+        /** When the value was last set (create or rotate). Never a digest of it. */
+        setAt?: string;
     } | null;
     tools: string[];
     runtime: {
@@ -58,4 +60,28 @@ export declare const grantApi: {
  * gate that could drift.
  */
 export declare function parseEnvPairs(pairs: string[]): Record<string, string>;
+/** The cells every Grant table shows, in one place (OSK-15357). */
+export type GrantTableCells = {
+    id: string;
+    label: string;
+    provider: string;
+    access: string;
+    principal: string;
+    credential: string;
+    runtime: string;
+    state: string;
+};
+/**
+ * One Grant as table cells. `skrr grants list` and `skrr workspaces grants`
+ * both read this, so a column with the same header means the same thing in
+ * both and the two tables can be compared by eye. They used not to: the
+ * workspace table printed capabilities under ACCESS while this one printed the
+ * declared access class.
+ */
+export declare function grantTableCells(g: Pick<Grant, 'id' | 'label' | 'provider' | 'access' | 'accessSource' | 'credential' | 'revokedAt' | 'active'> & {
+    principal?: Partial<GrantPrincipal> | null;
+    runtime?: Partial<Grant['runtime']> | null;
+}): GrantTableCells;
+/** The shared columns, in order; a caller may add its own around them. */
+export declare const GRANT_TABLE_COLUMNS: Array<TableColumn<GrantTableCells>>;
 export declare function renderGrantList(grants: Grant[], log: (line: string) => void): void;

package/dist/lib/grants.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.grantApi = exports.GRANT_CREDENTIAL_KINDS = exports.GRANT_PRINCIPAL_KINDS = void 0;
+exports.GRANT_TABLE_COLUMNS = exports.grantApi = exports.GRANT_CREDENTIAL_KINDS = exports.GRANT_PRINCIPAL_KINDS = void 0;
 exports.parseEnvPairs = parseEnvPairs;
+exports.grantTableCells = grantTableCells;
 exports.renderGrantList = renderGrantList;
 /**
  * grants.ts — client for the Grant vault (`/api/grants/*`).
@@ -51,35 +52,52 @@ function parseEnvPairs(pairs) {
     }
     return out;
 }
-function renderGrantList(grants, log) {
-    if (grants.length === 0) {
-        log('No grants.');
-        return;
-    }
-    (0, format_1.renderTable)(grants.map((g) => ({
+/**
+ * One Grant as table cells. `skrr grants list` and `skrr workspaces grants`
+ * both read this, so a column with the same header means the same thing in
+ * both and the two tables can be compared by eye. They used not to: the
+ * workspace table printed capabilities under ACCESS while this one printed the
+ * declared access class.
+ */
+function grantTableCells(g) {
+    const principal = g.principal ?? null;
+    let state = 'expired';
+    if (g.revokedAt)
+        state = 'revoked';
+    else if (g.active)
+        state = 'active';
+    return {
         id: g.id,
         label: g.label,
-        provider: g.provider,
+        provider: g.provider || '—',
         access: g.access
             ? `${g.access} (${g.accessSource === 'attested' ? 'attested' : 'declared, not verified'})`
             : 'undeclared',
-        principal: g.principal.agentId || g.principal.commitmentId || g.principal.kind,
+        principal: principal?.agentId || principal?.commitmentId || principal?.kind || '—',
         // NAMES only. This is the audit surface; a value never reaches the CLI.
         credential: g.credential?.configured
             ? g.credential.envKeys.join(',') || g.credential.kind || 'set'
             : '-',
-        runtime: [g.runtime.sandbox ? 'sandbox' : null, g.runtime.daemon ? 'daemon' : null]
+        runtime: [g.runtime?.sandbox ? 'sandbox' : null, g.runtime?.daemon ? 'daemon' : null]
             .filter(Boolean)
             .join('+') || 'none',
-        state: g.revokedAt ? 'revoked' : g.active ? 'active' : 'expired',
-    })), [
-        { key: 'label', header: 'LABEL', maxWidth: 26 },
-        { key: 'provider', header: 'PROVIDER', maxWidth: 12 },
-        { key: 'access', header: 'ACCESS', maxWidth: 32 },
-        { key: 'principal', header: 'PRINCIPAL', maxWidth: 24 },
-        { key: 'credential', header: 'VARIABLES', maxWidth: 34 },
-        { key: 'runtime', header: 'RUNTIME', maxWidth: 16 },
-        { key: 'state', header: 'STATE', maxWidth: 8 },
-        { key: 'id', header: 'ID', verbatim: true },
-    ], log);
+        state,
+    };
+}
+/** The shared columns, in order; a caller may add its own around them. */
+exports.GRANT_TABLE_COLUMNS = [
+    { key: 'label', header: 'LABEL', maxWidth: 26 },
+    { key: 'provider', header: 'PROVIDER', maxWidth: 12 },
+    { key: 'access', header: 'ACCESS', maxWidth: 32 },
+    { key: 'principal', header: 'PRINCIPAL', maxWidth: 24 },
+    { key: 'credential', header: 'VARIABLES', maxWidth: 34 },
+    { key: 'runtime', header: 'RUNTIME', maxWidth: 16 },
+    { key: 'state', header: 'STATE', maxWidth: 8 },
+];
+function renderGrantList(grants, log) {
+    if (grants.length === 0) {
+        log('No grants.');
+        return;
+    }
+    (0, format_1.renderTable)(grants.map((g) => grantTableCells(g)), [...exports.GRANT_TABLE_COLUMNS, { key: 'id', header: 'ID', verbatim: true }], log);
 }

package/dist/lib/harnesses.d.ts

@@ -238,6 +238,77 @@ export declare function updateHarness(id: string, patch: Record<string, unknown>
     harness?: Harness;
 }>;
 export declare function forgetHarness(id: string): Promise<unknown>;
+/**
+ * Why a superseded-looking row is KEPT by `harnesses prune`. Declared by the
+ * server (`pruneSupersededHarnesses.js`, `REASONS`) and worded once, in
+ * `harnessPruneReasonSentence`, so the table and `--json` never disagree.
+ */
+export type HarnessPruneReason = 'recent' | 'latest_registration' | 'no_live_sibling' | 'pinned' | 'granted' | 'default' | 'aliased' | 'changed_since_plan';
+export interface HarnessPruneRow {
+    id: string;
+    daemonId: string | null;
+    provider: string | null;
+    name: string | null;
+    lastSeenAt: string | null;
+    machineUuid: string | null;
+    /** The live sibling that replaced a row this call removes (or would). */
+    supersededBy?: {
+        id: string;
+        daemonId: string | null;
+        lastSeenAt: string | null;
+    };
+    /** Set on kept rows. */
+    reason?: HarnessPruneReason;
+    /** For `pinned`: who holds the pin. Other people's agents are a count, never named. */
+    detail?: {
+        agents?: Array<{
+            id: string;
+            name: string | null;
+        }>;
+        moreAgents?: number;
+        otherAuthors?: number;
+    };
+}
+export interface HarnessPruneResult {
+    dryRun: boolean;
+    limit: number;
+    minUnseenMs: number;
+    scan: {
+        rows: number;
+        complete: boolean;
+    };
+    /** Rows this call removes (dry run: would remove). */
+    remove: HarnessPruneRow[];
+    /** Rows this call actually removed; 0 on a dry run. */
+    removedCount: number;
+    /** Removable rows beyond `limit`; the next call takes them. */
+    remaining: number;
+    kept: HarnessPruneRow[];
+    keptTruncated: boolean;
+    counts: Record<string, number>;
+}
+/**
+ * Remove the caller's superseded harness rows - or, by default, say which would go.
+ *
+ * ONE route for both: the server makes the decision once and this only asks for it
+ * to be shown (`dryRun: true`, also its own default) or carried out. The caller
+ * never lists rows and picks, so there is no client-side rule to drift from the
+ * server's. A write, so `apiFetch` gives it an idempotency key and a retried
+ * request replays the recorded answer instead of running again.
+ */
+export declare function pruneHarnesses(options?: {
+    dryRun: boolean;
+    limit?: number;
+    minUnseenMs?: number;
+}): Promise<HarnessPruneResult>;
+/**
+ * `--older-than` takes a whole number with a unit: `90m`, `36h`, `7d`. A bare
+ * number is hours. Returns milliseconds. The server never goes below its offline
+ * window whatever this says.
+ */
+export declare function parseHarnessPruneAge(value: string): number;
+/** One sentence per reason a row was kept. The only place they are worded. */
+export declare function harnessPruneReasonSentence(row: HarnessPruneRow): string;
 /**
  * A per-USER display name. Distinct from `updateHarness({name})`, which renames
  * the harness for everyone it is shared with — this only changes what YOU see,