@skrr-ai/cli 0.1.108 → 0.1.110

package/dist/lib/harnesses.js

@@ -13,6 +13,9 @@ exports.listQuotaAccounts = listQuotaAccounts;
 exports.getQuotaHistory = getQuotaHistory;
 exports.updateHarness = updateHarness;
 exports.forgetHarness = forgetHarness;
+exports.pruneHarnesses = pruneHarnesses;
+exports.parseHarnessPruneAge = parseHarnessPruneAge;
+exports.harnessPruneReasonSentence = harnessPruneReasonSentence;
 exports.setHarnessAlias = setHarnessAlias;
 exports.setDefaultHarness = setDefaultHarness;
 exports.mintInstallToken = mintInstallToken;
@@ -173,6 +176,73 @@ async function updateHarness(id, patch) {
 async function forgetHarness(id) {
     return (0, api_fetch_1.apiFetch)(`/api/harnesses/${encodeURIComponent(id)}`, { method: 'DELETE' });
 }
+/**
+ * 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.
+ */
+async function pruneHarnesses(options = { dryRun: true }) {
+    return (0, api_fetch_1.apiFetch)('/api/harnesses/prune', {
+        method: 'POST',
+        body: {
+            dryRun: options.dryRun,
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(options.minUnseenMs !== undefined ? { minUnseenMs: options.minUnseenMs } : {}),
+        },
+    });
+}
+/**
+ * `--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.
+ */
+function parseHarnessPruneAge(value) {
+    const match = value.trim().match(/^(\d+)\s*(m|h|d)?$/i);
+    if (!match) {
+        throw new Error(`Invalid --older-than value "${value}". Use a number with m, h or d, such as 90m, 36h or 7d.`);
+    }
+    const amount = Number(match[1]);
+    const unit = (match[2] || 'h').toLowerCase();
+    const perUnit = unit === 'd' ? 86_400_000 : unit === 'h' ? 3_600_000 : 60_000;
+    return amount * perUnit;
+}
+/** One sentence per reason a row was kept. The only place they are worded. */
+function harnessPruneReasonSentence(row) {
+    switch (row.reason) {
+        case 'recent':
+            return 'seen too recently to be sure it is gone';
+        case 'latest_registration':
+            return 'the newest registration of its provider on that machine';
+        case 'no_live_sibling':
+            return 'nothing has replaced it - no daemon on that machine is online for this provider';
+        case 'pinned': {
+            const names = (row.detail?.agents ?? []).map((a) => a.name ?? a.id);
+            const more = row.detail?.moreAgents ?? 0;
+            const others = row.detail?.otherAuthors ?? 0;
+            const parts = [];
+            if (names.length > 0) {
+                parts.push(`${names.join(', ')}${more > 0 ? ` and ${more} more` : ''}`);
+            }
+            if (others > 0)
+                parts.push(`${others} agent${others === 1 ? '' : 's'} of other people`);
+            return `agents are pinned to it${parts.length > 0 ? ` (${parts.join('; ')})` : ''}`;
+        }
+        case 'granted':
+            return 'it is lent to a workspace';
+        case 'default':
+            return 'it is your default harness';
+        case 'aliased':
+            return 'you gave it a name';
+        case 'changed_since_plan':
+            return 'it changed while this ran (came back online, or was pinned)';
+        default:
+            return String(row.reason ?? 'kept');
+    }
+}
 /**
  * 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,

package/dist/lib/json-mode.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether a `skrr` invocation asked for JSON — ONE definition.
+ *
+ * `BaseCommand` decides this for a command that is running. A command that was
+ * never found has no `BaseCommand`: the `command_not_found` hook runs before one
+ * exists, so it asked nothing and printed prose to stderr, and a script that
+ * piped `--json` output to `jq` got "parse error: Invalid numeric literal"
+ * instead of the refusal (OSK-16434). Both now read the same rule, so a flag
+ * added to one cannot be missing from the other.
+ */
+export declare function wantsJsonFromArgv(argv: readonly string[], env?: NodeJS.ProcessEnv): boolean;

package/dist/lib/json-mode.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wantsJsonFromArgv = wantsJsonFromArgv;
+/**
+ * Whether a `skrr` invocation asked for JSON — ONE definition.
+ *
+ * `BaseCommand` decides this for a command that is running. A command that was
+ * never found has no `BaseCommand`: the `command_not_found` hook runs before one
+ * exists, so it asked nothing and printed prose to stderr, and a script that
+ * piped `--json` output to `jq` got "parse error: Invalid numeric literal"
+ * instead of the refusal (OSK-16434). Both now read the same rule, so a flag
+ * added to one cannot be missing from the other.
+ */
+function wantsJsonFromArgv(argv, env = process.env) {
+    return (argv.includes('--json') ||
+        argv.includes('--ndjson') ||
+        env.SKY_JSON === '1' ||
+        env.OVERSKY_CLI_JSON === '1');
+}

package/dist/lib/json-output.d.ts

@@ -28,4 +28,29 @@ export declare function stripStorageFields(value: Json): Json;
  * untouched, as is JSON with nothing to strip, so existing formatting survives.
  */
 export declare function stripStorageFieldsFromText(text: string): string;
+/**
+ * The outcome marker for a `--json` RESULT document (OSK-16425).
+ *
+ * A failure prints `{ok:false, error:{...}}` on stdout, so that agents get the
+ * refusal structured. A success printed whatever the server sent, with no `ok`
+ * at all — so a script could not test one field for both, and a projection such
+ * as `jq '{id, title}'` turned the error document into `{"id":null,"title":null}`,
+ * which reads as an empty success. The reporter's own diagnosis of a failed
+ * command was wrong for exactly that reason.
+ *
+ * Adding `ok` here, to a document a command already holds, is truthful by
+ * construction: the caller knows whether the command succeeded when it prints.
+ * It is NOT done to text in `BaseCommand.log`, the way storage fields are
+ * stripped, because `log` cannot see the exit status to come: `doctor`,
+ * `tasks wait`, `outbox retry` and `code install` print a document and then
+ * exit non-zero, and stamping `ok:true` on those would assert a success the
+ * exit code denies.
+ *
+ * Only an object can carry it. An array is returned as it is, and so is an
+ * object that already says `ok` — that command's own meaning wins. `ok` is put
+ * first so it is the first thing read.
+ */
+export declare function withOk<T>(value: T, ok?: boolean): T | ({
+    ok: boolean;
+} & Record<string, unknown>);
 export {};

package/dist/lib/json-output.js

@@ -20,6 +20,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripStorageFields = stripStorageFields;
 exports.stripStorageFieldsFromText = stripStorageFieldsFromText;
+exports.withOk = withOk;
 function usableId(value) {
     return (typeof value === 'string' && value.length > 0) || typeof value === 'number';
 }
@@ -76,3 +77,32 @@ function stripStorageFieldsFromText(text) {
         return text;
     return JSON.stringify(stripped, null, text.includes('\n') ? 2 : undefined);
 }
+/**
+ * The outcome marker for a `--json` RESULT document (OSK-16425).
+ *
+ * A failure prints `{ok:false, error:{...}}` on stdout, so that agents get the
+ * refusal structured. A success printed whatever the server sent, with no `ok`
+ * at all — so a script could not test one field for both, and a projection such
+ * as `jq '{id, title}'` turned the error document into `{"id":null,"title":null}`,
+ * which reads as an empty success. The reporter's own diagnosis of a failed
+ * command was wrong for exactly that reason.
+ *
+ * Adding `ok` here, to a document a command already holds, is truthful by
+ * construction: the caller knows whether the command succeeded when it prints.
+ * It is NOT done to text in `BaseCommand.log`, the way storage fields are
+ * stripped, because `log` cannot see the exit status to come: `doctor`,
+ * `tasks wait`, `outbox retry` and `code install` print a document and then
+ * exit non-zero, and stamping `ok:true` on those would assert a success the
+ * exit code denies.
+ *
+ * Only an object can carry it. An array is returned as it is, and so is an
+ * object that already says `ok` — that command's own meaning wins. `ok` is put
+ * first so it is the first thing read.
+ */
+function withOk(value, ok = true) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    if (Object.prototype.hasOwnProperty.call(value, 'ok'))
+        return value;
+    return { ok, ...value };
+}

package/dist/lib/list-output.d.ts

@@ -18,7 +18,7 @@ export type ListEnvelope = {
  * Documented in docs/cli/SKRR_TASKS.md (List output for agents).
  */
 export declare const COMPACT_FIELDS: {
-    readonly task: readonly ["id", "identifier", "ref", "title", "status", "statusType", "priority", "estimate", "assigneeAgentIds", "assigneeUserIds", "parentId", "spaceId", "projectId", "goalId", "dueDate", "scheduledFor", "labelIds", "tags", "externalKey", "version", "executionMode", "nextAction", "createdAt", "updatedAt", "url"];
+    readonly task: readonly ["id", "identifier", "ref", "title", "status", "statusType", "priority", "estimate", "assigneeAgentIds", "assigneeUserIds", "parentId", "spaceId", "projectId", "goalId", "dueDate", "scheduledFor", "labelIds", "tags", "externalKey", "version", "executionMode", "nextAction", "economicsRank", "createdAt", "updatedAt", "url"];
     readonly space: readonly ["id", "identifier", "title", "status", "parentSpaceId", "leadAgentId", "labelIds", "archivedAt", "createdAt", "updatedAt", "url"];
     readonly project: readonly ["id", "identifier", "title", "spaceId", "externalKey", "taskCounts", "archivedAt", "createdAt", "updatedAt", "url"];
 };
@@ -64,6 +64,15 @@ export declare function limitNote(requested: number | undefined, rowCount: numbe
 };
 /** The text-mode twin of a warning: one `Note:` line a person can act on. */
 export declare function warningLines(warnings: readonly ListWarning[] | undefined): string[];
+/**
+ * The note a TABLE prints when it was given a JSON-only projection flag. `--compact` and
+ * `--fields` shape JSON output; on the table they did nothing and said nothing, so `--compact`
+ * looked broken (OSK-15374). Empty when neither flag was given.
+ */
+export declare function textModeProjectionNotes(flags: {
+    fields?: string;
+    compact?: boolean;
+}): string[];
 export type ListOutput = {
     stdout: string[];
     stderr: string[];

package/dist/lib/list-output.js

@@ -7,6 +7,7 @@ exports.toListEnvelope = toListEnvelope;
 exports.shapeListResponse = shapeListResponse;
 exports.limitNote = limitNote;
 exports.warningLines = warningLines;
+exports.textModeProjectionNotes = textModeProjectionNotes;
 exports.renderListOutput = renderListOutput;
 /**
  * Shared output shaping for `skrr` LIST commands (agent-surface audit
@@ -29,6 +30,7 @@ exports.renderListOutput = renderListOutput;
  * Pure functions, no oclif: the commands own I/O, this owns the shape.
  */
 const core_1 = require("@oclif/core");
+const json_output_1 = require("./json-output");
 /**
  * The navigation projection per resource: enough to identify a row, decide
  * whether it matters and fetch it with `show`. Allowlists, not drop-lists, so a
@@ -59,6 +61,8 @@ exports.COMPACT_FIELDS = {
         'version',
         'executionMode',
         'nextAction',
+        // Present only on a `--rank economics` page: the score the row was sorted by (OSK-16476).
+        'economicsRank',
         'createdAt',
         'updatedAt',
         'url',
@@ -206,7 +210,11 @@ function shapeListResponse(response, options) {
     if (limit.warning)
         warnings.push(limit.warning);
     return {
-        ...envelope,
+        // A list that reached this shaper succeeded; a failure never does, and prints
+        // `{ok:false, error}`. Saying so lets a script test one field for both, and
+        // keeps a projection of a failure from reading as an empty list (OSK-16425).
+        // The server's own `ok`, if it sent one, is kept.
+        ...(0, json_output_1.withOk)(envelope),
         data,
         ...(limit.applied !== undefined ? { limit_applied: limit.applied } : {}),
         ...(options.filterApplied ? { filter_applied: options.filterApplied } : {}),
@@ -247,6 +255,19 @@ function limitNote(requested, rowCount, hasMore) {
 function warningLines(warnings) {
     return (warnings ?? []).map((w) => `Note: ${w.hint}`);
 }
+/**
+ * The note a TABLE prints when it was given a JSON-only projection flag. `--compact` and
+ * `--fields` shape JSON output; on the table they did nothing and said nothing, so `--compact`
+ * looked broken (OSK-15374). Empty when neither flag was given.
+ */
+function textModeProjectionNotes(flags) {
+    const given = [flags.fields ? '--fields' : null, flags.compact ? '--compact' : null].filter(Boolean);
+    if (given.length === 0)
+        return [];
+    return [
+        `Note: ${given.join(' and ')} ${given.length > 1 ? 'shape' : 'shapes'} JSON output only; the table is unchanged. Add --json (or --ndjson) to apply ${given.length > 1 ? 'them' : 'it'}.`,
+    ];
+}
 /**
  * Render a shaped list for `--json` (pretty envelope) or `--ndjson` (rows one per
  * line, `_meta` on stderr). Pure; the caller writes the lines.

package/dist/lib/local-daemon-readiness.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Whether the local daemon is actually signed in and connected — as opposed to
+ * having been handed a credential (OSK-16437).
+ *
+ * `skrr login` used to print "The local daemon was signed in too" the moment
+ * `accept-handoff` exited 0. That means the credential was WRITTEN. It says
+ * nothing about a daemon using it, and a handoff that wrote a credential for a
+ * service that was not running, or that the server then refused, left a login
+ * that announced success on one line and failed to verify it on the next, with
+ * nothing saying which was true. `skrr daemon start` learned the same lesson
+ * ("a supervisor's successful `kickstart` means only that it accepted the
+ * request") and asks the daemon itself; this is that question for login.
+ *
+ * Two probes, in order of how directly they answer:
+ *
+ *   1. the loopback identity endpoint of THIS profile's daemon, which says it is
+ *      connected as this account on this server — the only proof;
+ *   2. `skrrd status --json`, asked only once the first has not answered, to say
+ *      WHY: the server refused the credential, the service is not running, or it
+ *      is running and has not connected yet. Those have different fixes.
+ */
+export type LocalDaemonReadiness = {
+    state: 'connected';
+    daemonId: string;
+} | {
+    state: 'reauth_required';
+    profile: string;
+    reason: string | null;
+    command: string;
+} | {
+    state: 'not_running';
+    profile: string;
+    runtimeStatus: string | null;
+} | {
+    state: 'not_connected';
+    profile: string;
+} | {
+    state: 'unreadable';
+    profile: string;
+};
+export interface ReadinessDeps {
+    /** One look at the loopback identity endpoint; the daemon id when it is connected as us. */
+    inspect: () => Promise<string | null>;
+    /** `skrrd status --json` for this profile. */
+    status: () => Promise<{
+        stdout: string;
+        code: number;
+    }>;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+export interface ConfirmOptions {
+    /** How long a daemon that is still starting gets. */
+    waitMs?: number;
+    pollMs?: number;
+    /** How long a service that reads `stopped` is given before it is believed. */
+    stoppedGraceMs?: number;
+    /** Progress, printed once and only when the first look found nothing. */
+    log?: (line: string) => void;
+    deps?: Partial<ReadinessDeps>;
+}
+export declare function confirmLocalDaemonSignedIn(options?: ConfirmOptions): Promise<LocalDaemonReadiness>;
+/**
+ * What `skrr login` prints about a daemon that was handed a credential and did
+ * not come up with it: what happened, why, and the one command. Pure, so every
+ * state can be read without a daemon.
+ */
+export declare function describeUnreadyLocalDaemon(readiness: Exclude<LocalDaemonReadiness, {
+    state: 'connected';
+}>, commands: {
+    status: string;
+    logs: string;
+    start: string;
+}): string[];
+/**
+ * The end of `skrr login` for a daemon that was handed a credential: wait for it
+ * to connect, then say ONE true thing. "Signed in too" only for a daemon that
+ * verified connected as this account; otherwise what happened, why, and the one
+ * command — and never both, which is what the login used to do.
+ */
+export declare function reportLocalDaemonAfterHandoff(options: {
+    /** `skrr login` may have been handed the daemon's account/deployment line already. */
+    deliveredDetail: string;
+    bin: string;
+    log: (line: string) => void;
+    confirm?: typeof confirmLocalDaemonSignedIn;
+}): Promise<{
+    daemonId?: string;
+    notReady: boolean;
+}>;

package/dist/lib/local-daemon-readiness.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirmLocalDaemonSignedIn = confirmLocalDaemonSignedIn;
+exports.describeUnreadyLocalDaemon = describeUnreadyLocalDaemon;
+exports.reportLocalDaemonAfterHandoff = reportLocalDaemonAfterHandoff;
+const exec_runtime_binary_1 = require("./exec-runtime-binary");
+const managed_instruction_local_1 = require("./managed-instruction-local");
+const keychain_1 = require("./keychain");
+const config_1 = require("./config");
+const runtime_start_verification_1 = require("./runtime-start-verification");
+const daemon_command_hint_1 = require("./daemon-command-hint");
+/** Each probe reads its inputs when called, so an injected one never touches real state. */
+function defaultDeps() {
+    return {
+        inspect: () => (0, managed_instruction_local_1.inspectLocalInstructionDaemon)((0, keychain_1.getActiveProfile)(), (0, config_1.loadConfig)().baseURL),
+        status: async () => {
+            const profile = (0, keychain_1.getActiveProfile)();
+            const args = [
+                'status',
+                '--json',
+                ...(profile !== keychain_1.DEFAULT_PROFILE ? ['--profile', profile] : []),
+            ];
+            try {
+                const out = await (0, exec_runtime_binary_1.execRuntimeBinaryCapture)(args, { timeoutMs: 15_000 });
+                return { stdout: out.stdout, code: out.code };
+            }
+            catch {
+                return { stdout: '', code: 1 };
+            }
+        },
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    };
+}
+async function confirmLocalDaemonSignedIn(options = {}) {
+    const deps = { ...defaultDeps(), ...options.deps };
+    const waitMs = options.waitMs ?? 20_000;
+    const pollMs = options.pollMs ?? 500;
+    const stoppedGraceMs = options.stoppedGraceMs ?? 6_000;
+    const profile = (0, keychain_1.getActiveProfile)();
+    const started = deps.now();
+    let announced = false;
+    let lastDiagnosisAt = -Infinity;
+    let verdict = { state: 'not_connected', profile };
+    for (;;) {
+        const daemonId = await deps.inspect();
+        if (daemonId)
+            return { state: 'connected', daemonId };
+        if (!announced) {
+            options.log?.('Waiting for the local daemon to connect...');
+            announced = true;
+        }
+        const elapsed = deps.now() - started;
+        // Ask WHY at a measured pace — each look spawns `skrrd` — and stop waiting
+        // the moment the answer is one no amount of waiting changes.
+        if (deps.now() - lastDiagnosisAt >= 2_000) {
+            lastDiagnosisAt = deps.now();
+            const status = await deps.status();
+            const verification = (0, runtime_start_verification_1.verifyRuntimeStart)(status.stdout, status.code, ['--profile', profile]);
+            if (verification.status === 'reauth_required') {
+                return {
+                    state: 'reauth_required',
+                    profile: verification.profile,
+                    reason: verification.reason,
+                    command: verification.recoveryCommand,
+                };
+            }
+            if (verification.status === 'not_running') {
+                verdict = {
+                    state: 'not_running',
+                    profile: verification.profile,
+                    runtimeStatus: verification.runtimeStatus,
+                };
+                // A service that was just started reads `stopped` for a moment between
+                // launchd accepting the request and the process existing; only believe
+                // it once it has had that long.
+                if (elapsed >= stoppedGraceMs)
+                    return verdict;
+            }
+            else if (verification.status === 'unreadable_status') {
+                verdict = { state: 'unreadable', profile: verification.profile };
+            }
+            else {
+                verdict = { state: 'not_connected', profile };
+            }
+        }
+        if (elapsed >= waitMs)
+            return verdict;
+        await deps.sleep(Math.min(pollMs, Math.max(0, waitMs - elapsed)));
+    }
+}
+/**
+ * What `skrr login` prints about a daemon that was handed a credential and did
+ * not come up with it: what happened, why, and the one command. Pure, so every
+ * state can be read without a daemon.
+ */
+function describeUnreadyLocalDaemon(readiness, commands) {
+    switch (readiness.state) {
+        case 'reauth_required':
+            return [
+                `The local daemon received its sign-in but cannot use it: ${readiness.reason === 'TOKEN_MISSING'
+                    ? 'it started without a credential'
+                    : `the server refused it (${readiness.reason ?? 'UNKNOWN'})`}.`,
+                `  Sign it in with: ${readiness.command}`,
+            ];
+        case 'not_running':
+            return [
+                `The local daemon received its sign-in but is not running (service status: ${readiness.runtimeStatus ?? 'unknown'}).`,
+                `  See why with \`${commands.logs}\`, then start it with \`${commands.start}\`.`,
+            ];
+        case 'not_connected':
+            return [
+                'The local daemon received its sign-in and is running, but has not connected yet.',
+                `  Check it with \`${commands.status}\`.`,
+            ];
+        case 'unreadable':
+            return [
+                'The local daemon received its sign-in, but its status could not be read to confirm it.',
+                `  Check it with \`${commands.status}\`.`,
+            ];
+    }
+}
+/**
+ * The end of `skrr login` for a daemon that was handed a credential: wait for it
+ * to connect, then say ONE true thing. "Signed in too" only for a daemon that
+ * verified connected as this account; otherwise what happened, why, and the one
+ * command — and never both, which is what the login used to do.
+ */
+async function reportLocalDaemonAfterHandoff(options) {
+    const readiness = await (options.confirm ?? confirmLocalDaemonSignedIn)({ log: options.log });
+    if (readiness.state === 'connected') {
+        options.log(`The local daemon was signed in too — ${options.deliveredDetail}.`);
+        return { daemonId: readiness.daemonId, notReady: false };
+    }
+    for (const line of describeUnreadyLocalDaemon(readiness, {
+        status: (0, daemon_command_hint_1.daemonCommandHint)('status', { bin: options.bin }),
+        logs: (0, daemon_command_hint_1.daemonCommandHint)('logs', { bin: options.bin }),
+        start: (0, daemon_command_hint_1.daemonCommandHint)('start', { bin: options.bin }),
+    })) {
+        options.log(line);
+    }
+    return { notReady: true };
+}

package/dist/lib/machines.d.ts

@@ -53,6 +53,35 @@ export interface MachineHarnessRow {
      * them.
      */
     superseded?: boolean;
+    /**
+     * Recorded `online`, but no heartbeat for longer than the server's stale
+     * threshold (`MachineContact.staleAfterMs`). Present only when true. The server
+     * decides this once; a row's own `status` stays what was recorded
+     * (OSK-16442).
+     */
+    stale?: boolean;
+    /** How long that row has been silent, in ms. Present with `stale`. */
+    staleForMs?: number;
+}
+/**
+ * What a machine's heartbeats say, apart from what its rows are recorded as
+ * (OSK-16442). A daemon that was stopped or frozen stays recorded `online` for a
+ * minute or more before the server gives up on it, so `status` alone said
+ * `online` for a process that had not been heard from in a minute.
+ *
+ * - `live`: a row is online and heard from recently.
+ * - `stale`: rows are recorded online, but none has been heard from for
+ *   `staleAfterMs`. The machine's `status` is `degraded` meanwhile.
+ * - `offline`: nothing is recorded online.
+ *
+ * The thresholds are the server's, sent so this CLI never restates them. Absent
+ * on a server older than this field and on a lease-backed machine.
+ */
+export interface MachineContact {
+    state: 'live' | 'stale' | 'offline';
+    staleForMs: number | null;
+    staleAfterMs: number;
+    offlineAfterMs: number;
 }
 export interface Machine {
     id: string;
@@ -69,6 +98,7 @@ export interface Machine {
      * none will ever arrive.
      */
     statusReason?: string | null;
+    contact?: MachineContact | null;
     machineUuid: string | null;
     stableDaemonId: string | null;
     daemonId: string | null;
@@ -120,6 +150,93 @@ export declare function machineStateLabel(machine: Machine): string;
 export declare function hiddenMachinesSummary(hidden: readonly Machine[]): string;
 /** Is this a machine a user could still use, or bring back? */
 export declare function isReachableMachine(machine: Machine): boolean;
+/**
+ * A computer somebody installed a daemon on, as opposed to a hosted sandbox.
+ *
+ * A daemon launched on a person's own computer registers as
+ * `daemon_<hash>_<source>[_<profile>]` (`parseDaemonId`); a hosted or cloud
+ * machine's daemon carries an id minted by the control plane
+ * (`hosted-machine-…`, `cloud-coding-…`) that names no launch source. A lease
+ * decides a managed machine's own state, so it is never one of these.
+ */
+export declare function isOwnComputer(machine: Machine): boolean;
+/**
+ * What the default `machines list` keeps: everything reachable, and every one of
+ * the person's own computers while it is offline (OSK-16442).
+ *
+ * The default hides offline machines because hosted sandboxes accumulate by the
+ * hundreds and buried the one that was usable (OSK-7639). Applied to a computer
+ * it did something else: the moment its last daemon stopped, the whole row left
+ * the list, in text and in `--json`, so "my computer is offline" and "my computer
+ * is gone" read the same. A computer is a handful of rows however long it is
+ * kept, and `offline` with its last-seen time is the answer a person asks the
+ * list for, so it stays; only what can no longer be used is left behind `--all`.
+ */
+export declare function isListedByDefault(machine: Machine): boolean;
+/**
+ * One daemon registration on a machine, as its own record (OSK-16440).
+ *
+ * A machine row aggregates every harness registration ever made under one
+ * hardware identity. The daemon that made each is only a string on a harness
+ * row, and the profile it ran as is a suffix of that string — so a script that
+ * wanted "the daemon that just registered" had to take the first unfamiliar
+ * `daemonId` out of a flat list that, depending on whether anything on the
+ * computer happened to be online, held 4 rows or 98 of them.
+ */
+export interface MachineDaemonSummary {
+    daemonId: string;
+    /** The profile the daemon ran as, read from its id; null for an id that names none (a hosted box). */
+    profile: string | null;
+    /** How it was launched (`cli`, `launchd`, …); null when the id does not say. */
+    source: string | null;
+    /**
+     * `online` when any registration is online and heard from recently, `stale`
+     * when some are recorded online but none has been heard from lately, `offline`
+     * otherwise.
+     */
+    status: 'online' | 'stale' | 'offline';
+    lastSeenAt: string | null;
+    harnessCount: number;
+    /** Of those, how many a newer registration of the same provider replaced. */
+    supersededCount: number;
+    /** The profile this CLI is running as. */
+    activeProfile: boolean;
+}
+export declare function parseDaemonId(daemonId: string): {
+    source: string;
+    profile: string;
+} | null;
+export declare function summarizeDaemons(harnesses: readonly MachineHarnessRow[], activeProfile: string): MachineDaemonSummary[];
+/** Whether the machine's identity is THIS computer's (the default profile's, or a profile qualified from it). */
+export declare function isThisComputer(machine: Machine, hardwareMachineUuid: string): boolean;
+export interface MachineListView extends Machine {
+    /** This machine is the computer the CLI is running on. */
+    thisComputer: boolean;
+    /** One record per daemon registration; see {@link MachineDaemonSummary}. */
+    daemons: MachineDaemonSummary[];
+    /**
+     * Harness rows left out of `harnesses` because a newer registration replaced
+     * them (default view only). `supersededHarnessCount` still reports the
+     * server's own total, so nothing is silently subtracted.
+     */
+    hiddenHarnessCount?: number;
+}
+/**
+ * What `machines list` shows of one machine (OSK-16440).
+ *
+ * The default list is "what is reachable now", and a machine's own history is
+ * not part of that. A machine row carries every harness registration it ever
+ * had; one of them being online made the whole 98-row history appear in a list
+ * that, a minute earlier, had held four rows — the same command, a different
+ * answer, for no reason a reader could see. So the default view keeps the
+ * registrations that still stand and says how many it left out; `--all` keeps
+ * everything.
+ */
+export declare function machineListView(machine: Machine, options: {
+    all: boolean;
+    hardwareMachineUuid: string;
+    activeProfile: string;
+}): MachineListView;
 /** The user-editable slice. Identities, capabilities and lifecycle are not. */
 export interface MachinePreferencesPatch {
     name?: string;