@skrr-ai/cli 0.1.87 → 0.1.89

package/dist/lib/dedicated-machines.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEDICATED_FILE_MAX_BYTES = exports.DEDICATED_FILE_CHUNK_BYTES = exports.DEDICATED_EXEC_DEFAULT_TIMEOUT_MS = exports.DEDICATED_EXEC_MAX_TIMEOUT_MS = exports.DEDICATED_MACHINE_PRODUCT = exports.DEDICATED_LEASE_ACTIONS = void 0;
+exports.computerMachineId = exports.DEDICATED_FILE_MAX_BYTES = exports.DEDICATED_FILE_CHUNK_BYTES = exports.DEDICATED_EXEC_DEFAULT_TIMEOUT_MS = exports.DEDICATED_EXEC_MAX_TIMEOUT_MS = exports.DEDICATED_MACHINE_PRODUCT = exports.DEDICATED_LEASE_ACTIONS = void 0;
 exports.describeDedicatedCheckpoint = describeDedicatedCheckpoint;
 exports.compareDaemonVersions = compareDaemonVersions;
 exports.describeDedicatedDaemonRelease = describeDedicatedDaemonRelease;
 exports.describeDedicatedImageStanding = describeDedicatedImageStanding;
 exports.dedicatedRuntimeCreateInput = dedicatedRuntimeCreateInput;
 exports.isDedicatedRepositoryRef = isDedicatedRepositoryRef;
+exports.withDedicatedScope = withDedicatedScope;
 exports.createDedicatedRuntime = createDedicatedRuntime;
 exports.getDedicatedOperatorPriceBook = getDedicatedOperatorPriceBook;
 exports.dedicatedOperatorPriceBookLines = dedicatedOperatorPriceBookLines;
@@ -16,12 +17,16 @@ exports.performDedicatedLeaseAction = performDedicatedLeaseAction;
 exports.growDedicatedRuntime = growDedicatedRuntime;
 exports.restoreDeletedDedicatedRuntime = restoreDeletedDedicatedRuntime;
 exports.setDedicatedRuntimeSpendingLimit = setDedicatedRuntimeSpendingLimit;
+exports.getDedicatedRuntimeAgentBrowser = getDedicatedRuntimeAgentBrowser;
+exports.setDedicatedRuntimeAgentBrowser = setDedicatedRuntimeAgentBrowser;
+exports.describeDedicatedAgentBrowser = describeDedicatedAgentBrowser;
 exports.closeDedicatedRuntimeIncidentHold = closeDedicatedRuntimeIncidentHold;
 exports.destroyDedicatedRuntime = destroyDedicatedRuntime;
 exports.execDedicatedRuntime = execDedicatedRuntime;
 exports.getDedicatedRuntimeSignInStatus = getDedicatedRuntimeSignInStatus;
 exports.startDedicatedRuntimeExecution = startDedicatedRuntimeExecution;
 exports.observeDedicatedRuntimeExecution = observeDedicatedRuntimeExecution;
+exports.dedicatedComputerUrl = dedicatedComputerUrl;
 exports.readDedicatedRuntimeFileChunk = readDedicatedRuntimeFileChunk;
 exports.writeDedicatedRuntimeFileChunk = writeDedicatedRuntimeFileChunk;
 exports.parseDedicatedCopyEndpoints = parseDedicatedCopyEndpoints;
@@ -53,6 +58,7 @@ const auth_core_1 = require("@skrr-ai/auth-core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const api_fetch_1 = require("./api-fetch");
 const machine_spend_cap_1 = require("./machine-spend-cap");
+const web_url_1 = require("./web-url");
 const edge_error_page_1 = require("./edge-error-page");
 const harnesses_1 = require("./harnesses");
 exports.DEDICATED_LEASE_ACTIONS = [
@@ -365,6 +371,40 @@ async function restoreDeletedDedicatedRuntime(leaseId, options = {}) {
 async function setDedicatedRuntimeSpendingLimit(leaseId, spendingLimitCents, scope = {}) {
     return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/leases/${encodeURIComponent(leaseId)}/billing`, scope), { method: 'PATCH', body: { spendingLimitCents } });
 }
+async function getDedicatedRuntimeAgentBrowser(leaseId, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/agent-browser`, scope));
+}
+/** Turn the agents' browser on or off. An actual change is in the machine's audit record. */
+async function setDedicatedRuntimeAgentBrowser(leaseId, enabled, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/agent-browser`, scope), { method: 'PUT', body: { enabled } });
+}
+/**
+ * One line for a person. Says the bad cases out loud: a setting that is on
+ * while the connected daemon does not offer it yet, and a setting we could
+ * not read at all.
+ */
+function describeDedicatedAgentBrowser(value, leaseId) {
+    if (!value)
+        return 'unknown';
+    if ('error' in value)
+        return `unknown (could not read: ${value.error})`;
+    if (value.state === 'pending_first_start') {
+        return value.enabled
+            ? 'on when the machine first starts (the default for new machines)'
+            : 'off when the machine first starts';
+    }
+    if (value.state === 'off') {
+        return value.offered
+            ? `off — sessions already running keep theirs until the daemon reconnects (\`skrr machines dedicated restart ${leaseId}\`)`
+            : `off — turn on with \`skrr machines dedicated agent-browser ${leaseId} --on\``;
+    }
+    if (value.offered === true)
+        return 'on — every agent session can open one; you can watch and take it over';
+    if (value.offered === false) {
+        return `on, but the connected daemon does not offer it yet: it applies when the daemon reconnects (\`skrr machines dedicated restart ${leaseId}\`), and an image without Chrome never offers it`;
+    }
+    return 'on (not connected now, so whether the machine offers it is unknown)';
+}
 async function closeDedicatedRuntimeIncidentHold(leaseId, options = {}) {
     return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/incident-hold/close`, options), {
         method: 'POST',
@@ -445,11 +485,89 @@ async function observeDedicatedRuntimeExecution(leaseId, executionId, options) {
 /** Mirrors the daemon's bounds (daemon/src/tools/file-transfer.ts). */
 exports.DEDICATED_FILE_CHUNK_BYTES = 512 * 1024;
 exports.DEDICATED_FILE_MAX_BYTES = 64 * 1024 * 1024;
+/**
+ * `lease:<leaseId>` is the machine id the computer file routes address a
+ * Dedicated Runtime by (`/api/machines/:machineId/files/*`, authorised by
+ * ComputerAccess), the same id the machine inventory uses.
+ */
+const computerMachineId = (leaseId) => `lease:${leaseId}`;
+exports.computerMachineId = computerMachineId;
+/**
+ * The computer's page for a Dedicated Runtime — `/machines/<machineId>/computer`
+ * (the route `paneRouteConfig` serves the computer shell at, design §11).
+ * Composed on the `machine` web route rather than concatenated against baseURL,
+ * so the `api.`-subdomain → apex origin mapping stays the one in web-url.ts.
+ */
+function dedicatedComputerUrl(baseURL, leaseId) {
+    const page = (0, web_url_1.webUrl)(baseURL, { kind: 'machine', machineId: (0, exports.computerMachineId)(leaseId) });
+    return page ? `${page}/computer` : null;
+}
+const LEGACY_FILE_CODES = {
+    file_changed: 'DEDICATED_RUNTIME_FILE_CHANGED',
+    too_large: 'DEDICATED_RUNTIME_FILE_TOO_LARGE',
+    not_found: 'DEDICATED_RUNTIME_FILE_NOT_FOUND',
+};
+/**
+ * The copy loop branches on the `DEDICATED_RUNTIME_*` code a refused chunk
+ * carried (a destination that is a directory, a file that changed). The file
+ * routes answer in the computer's wire vocabulary and keep the specific cause in
+ * `details.reason`, so a refusal is re-coded here, at the one place that knows
+ * about the copy loop, rather than the loop learning two vocabularies.
+ */
+function withCopyLoopCode(err) {
+    if (!(err instanceof api_fetch_1.ApiFetchError))
+        return err;
+    let reason;
+    try {
+        reason = JSON.parse(err.body ?? '{}').details?.reason;
+    }
+    catch {
+        reason = undefined;
+    }
+    const code = typeof reason === 'string' && reason.startsWith('DEDICATED_RUNTIME_')
+        ? reason
+        : err.code
+            ? LEGACY_FILE_CODES[err.code]
+            : undefined;
+    if (code)
+        err.code = code;
+    return err;
+}
+/**
+ * One chunk of a download. `generation` is the lease generation the `cp`
+ * command resolved at its start, presented on every chunk (review C-01): a
+ * machine replaced mid-copy refuses the rest `stale_generation`.
+ */
 async function readDedicatedRuntimeFileChunk(leaseId, input, scope = {}, signal) {
-    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/files/read`, scope), { method: 'POST', body: input, ...(signal ? { signal } : {}) });
+    const wire = await (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/${encodeURIComponent((0, exports.computerMachineId)(leaseId))}/files/read`, scope), { method: 'POST', body: input, ...(signal ? { signal } : {}) }).catch((err) => {
+        throw withCopyLoopCode(err);
+    });
+    return {
+        path: wire.path,
+        size: wire.size,
+        // The tag's nanosecond mtime, as the whole-millisecond value the copy loop
+        // compares between chunks to notice a file that changed under it.
+        mtimeMs: Number(BigInt(wire.tag.mtimeNs) / 1000000n),
+        ...(typeof wire.executable === 'boolean' ? { executable: wire.executable } : {}),
+        offset: wire.offset,
+        bytesRead: Buffer.from(wire.data, 'base64').byteLength,
+        dataBase64: wire.data,
+        eof: wire.eof,
+    };
 }
+/**
+ * One call of a chunked upload. `generation` fences every chunk to the machine
+ * the command resolved (review C-01). How the commit treats a destination is
+ * the caller's explicit choice (review CW-01), never an unconditional replace:
+ * `createOnly` commits only if nothing has the name (else 409
+ * `invalid_request`/`exists`); `replaceTag` commits only over the file with
+ * exactly that tag (else 409 `file_changed` with `currentTag`, null when it is
+ * gone). Never both. Each needs `computer_files_fenced_v1` on the machine.
+ */
 async function writeDedicatedRuntimeFileChunk(leaseId, input, scope = {}) {
-    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/files/write`, scope), { method: 'POST', body: input });
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/${encodeURIComponent((0, exports.computerMachineId)(leaseId))}/files/write`, scope), { method: 'POST', body: input }).catch((err) => {
+        throw withCopyLoopCode(err);
+    });
 }
 const REMOTE_ENDPOINT = /^(rtl_[A-Za-z0-9_-]{1,80}):(.+)$/;
 /**
@@ -570,7 +688,8 @@ function dedicatedSpendSummary(lease) {
     if (!billing)
         return '-';
     const cap = billing.monthlySpendLimitCents !== undefined
-        ? billing.monthlySpendLimitCents : billing.spendingLimitCents;
+        ? billing.monthlySpendLimitCents
+        : billing.spendingLimitCents;
     if (billing.spendStatusUnavailable) {
         return `spend unavailable right now · ${cap === null ? 'no monthly cap' : `cap ${formatUsdCents(cap)}`}`;
     }
@@ -647,6 +766,12 @@ function describeDedicatedLease(lease, harnesses = [], opts = {}) {
     row('state', lease.stateReason
         ? `${dedicatedLeaseState(lease)} (${lease.stateReason})`
         : dedicatedLeaseState(lease));
+    // A reason the platform wrote for its own stop gets a sentence, not just a code: the
+    // code names an internal rule and leaves the owner asking where their machine went
+    // (OSK-13732). A reason with no copy keeps printing as the code above.
+    const stateReasonCopy = (0, data_provider_1.describeMachineStateReason)(lease.stateReason);
+    if (stateReasonCopy)
+        row('why', stateReasonCopy);
     const resources = lease.resources || {};
     const size = [
         resources.sizePreset,
@@ -725,6 +850,9 @@ function describeDedicatedLease(lease, harnesses = [], opts = {}) {
         if (checkpoint)
             lines.push(`  ${''.padEnd(13)}${checkpoint.sentence}`);
     }
+    if (opts.agentBrowser !== undefined) {
+        row('agent browser', describeDedicatedAgentBrowser(opts.agentBrowser, dedicatedLeaseId(lease)));
+    }
     const engines = dedicatedLeaseHarnesses(lease, harnesses);
     if (engines.length > 0) {
         row('engines', engines.map((harness) => `${harness.provider} (${harness.status || 'unknown'})`).join(', '));
@@ -1119,10 +1247,13 @@ function dedicatedCreateSummary(catalog, choices) {
         : 'server default';
     const retains = retentionClass !== undefined && retentionClass !== 'none';
     const capCents = choices.spendingLimitCents !== undefined
-        ? choices.spendingLimitCents : catalog?.defaultMonthlySpendingLimitCents;
+        ? choices.spendingLimitCents
+        : catalog?.defaultMonthlySpendingLimitCents;
     const cap = capCents !== undefined && capCents !== null
         ? `${formatUsdCents(capCents)} per month${choices.spendingLimitCents === undefined ? ' (catalog default)' : ''}`
-        : capCents === null ? 'no cap — compute and retained storage still bill' : 'server default';
+        : capCents === null
+            ? 'no cap — compute and retained storage still bill'
+            : 'server default';
     return [
         `Create Dedicated Runtime "${choices.name}" — it bills while it runs:`,
         `  size         ${choices.sizePreset} — ${spec}`,

package/dist/lib/exec-runtime-binary.d.ts

@@ -86,7 +86,9 @@ export type RuntimeBinaryOutput = {
  * post-condition probes, where output is evidence rather than user-facing
  * command output.
  */
-export declare function execRuntimeBinaryCapture(args: string[]): Promise<RuntimeBinaryOutput>;
+export declare function execRuntimeBinaryCapture(args: string[], opts?: {
+    timeoutMs?: number;
+}): Promise<RuntimeBinaryOutput>;
 /**
  * Check an installed daemon's top-level help before forwarding a command that
  * was added after older daemon releases shipped. A false result is useful to

package/dist/lib/exec-runtime-binary.js

@@ -251,7 +251,7 @@ function execRuntimeBinary(args, opts = {}) {
  * post-condition probes, where output is evidence rather than user-facing
  * command output.
  */
-function execRuntimeBinaryCapture(args) {
+function execRuntimeBinaryCapture(args, opts = {}) {
     return new Promise((resolve, reject) => {
         const bin = findRuntimeBinary();
         if (!bin) {
@@ -279,8 +279,22 @@ function execRuntimeBinaryCapture(args) {
         child.stderr?.on('data', (chunk) => {
             stderr = append(stderr, chunk);
         });
-        child.on('error', reject);
+        // A probe is a read: past its bound it is abandoned (and the child
+        // stopped) rather than allowed to stall the command that asked.
+        const timer = opts.timeoutMs && opts.timeoutMs > 0
+            ? setTimeout(() => {
+                child.kill('SIGTERM');
+                reject(new Error('runtime-binary-probe-timeout'));
+            }, opts.timeoutMs)
+            : null;
+        child.on('error', (error) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(error);
+        });
         child.on('exit', (code, signal) => {
+            if (timer)
+                clearTimeout(timer);
             resolve({
                 code: signal ? 128 + signalNumber(signal) : (code ?? 0),
                 stdout,

package/dist/lib/label-scope.d.ts

@@ -39,6 +39,18 @@ export declare const labelScopeFlags: {
     scope: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
     'scope-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
 };
+/**
+ * `--allow-duplicate-name`, shared by every command that can put a live name
+ * into a scope (create, rename, restore).
+ *
+ * The SERVER owns the rule (`LabelService.assertNameFreeInOtherScope`): a name
+ * another label you can use already carries is refused with
+ * `409 duplicate_name_other_scope`, and the refusal names that label. The CLI
+ * only relays the override, so every surface — web, MCP, CLI — gets one answer.
+ */
+export declare const allowDuplicateNameFlags: {
+    'allow-duplicate-name': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+};
 export interface ResolvedLabelScope {
     scope: LabelScope;
     scopeId?: string;

package/dist/lib/label-scope.js

@@ -11,7 +11,7 @@
  * id the server can infer (it falls back to the caller).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.labelScopeFlags = exports.HEX_COLOR_RE = exports.LABEL_APPLICABLE = exports.LABEL_SCOPES_INFERRED = exports.LABEL_SCOPES_REQUIRING_ID = exports.LABEL_SCOPES = void 0;
+exports.allowDuplicateNameFlags = exports.labelScopeFlags = exports.HEX_COLOR_RE = exports.LABEL_APPLICABLE = exports.LABEL_SCOPES_INFERRED = exports.LABEL_SCOPES_REQUIRING_ID = exports.LABEL_SCOPES = void 0;
 exports.normalizeLabelColor = normalizeLabelColor;
 exports.resolveLabelScope = resolveLabelScope;
 exports.resolveApplicableTo = resolveApplicableTo;
@@ -56,6 +56,20 @@ exports.labelScopeFlags = {
         description: `Scope owner ID — required for ${joinScopes(scopesRequiringId())}. Omit for ${joinScopes(exports.LABEL_SCOPES_INFERRED)} (defaults to you).`,
     }),
 };
+/**
+ * `--allow-duplicate-name`, shared by every command that can put a live name
+ * into a scope (create, rename, restore).
+ *
+ * The SERVER owns the rule (`LabelService.assertNameFreeInOtherScope`): a name
+ * another label you can use already carries is refused with
+ * `409 duplicate_name_other_scope`, and the refusal names that label. The CLI
+ * only relays the override, so every surface — web, MCP, CLI — gets one answer.
+ */
+exports.allowDuplicateNameFlags = {
+    'allow-duplicate-name': core_1.Flags.boolean({
+        description: 'Proceed even though another label you can use (your user scope, or a workspace you belong to) already has this name. Refused by default: two labels with one name make `--label <name>` ambiguous.',
+    }),
+};
 /**
  * Validate the scope pair. Throws a plain `Error` so callers can surface it
  * through `this.error(..., { exit: 1 })` with the rest of their flag checks.

package/dist/lib/machine-audit.d.ts

@@ -0,0 +1,34 @@
+import { COMPUTER_AUDIT_KINDS, type ComputerAuditPage } from '@skrr-ai/data-provider';
+/**
+ * machine-audit.ts — request client for `GET /api/machines/:machineId/audit`
+ * (design §9, D8/D10; OSK-13607): who did what on a machine, after the
+ * daemon's live Activity window has rolled off.
+ *
+ * The owner reads it always; a grantee at any tier reads it too, without the
+ * `grant_*` events (those name the other people the machine is shared with).
+ * Vocabulary and the page shape are owned by `@skrr-ai/data-provider`.
+ *
+ * ## Inline path literal
+ *
+ * `domain-api-parity` resolves a command to an endpoint by reading this
+ * string; a helper that assembled the URL would read as unreachable.
+ */
+export { COMPUTER_AUDIT_KINDS };
+export type { ComputerAuditPage };
+export interface MachineAuditQuery {
+    kinds?: string[];
+    actorUserId?: string;
+    /** ISO time or epoch ms — occurredAt >= since. */
+    since?: string | number;
+    /** ISO time or epoch ms — occurredAt < until. */
+    until?: string | number;
+    cursor?: string;
+    limit?: number;
+}
+/**
+ * A `--since` / `--until` value as an ISO time: an absolute time as typed
+ * (`2026-09-24`, `2026-09-24T10:00:00Z`), or an age such as `90m`, `12h`,
+ * `7d`, `2w` counted back from `now`. Throws on anything else, naming the flag.
+ */
+export declare function parseAuditTime(value: string, flagName: string, now?: number): string;
+export declare function listMachineAudit(machineId: string, query?: MachineAuditQuery): Promise<ComputerAuditPage>;

package/dist/lib/machine-audit.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPUTER_AUDIT_KINDS = void 0;
+exports.parseAuditTime = parseAuditTime;
+exports.listMachineAudit = listMachineAudit;
+const data_provider_1 = require("@skrr-ai/data-provider");
+Object.defineProperty(exports, "COMPUTER_AUDIT_KINDS", { enumerable: true, get: function () { return data_provider_1.COMPUTER_AUDIT_KINDS; } });
+const api_fetch_1 = require("./api-fetch");
+const DURATION_MS = {
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 7 * 86_400_000,
+};
+/**
+ * A `--since` / `--until` value as an ISO time: an absolute time as typed
+ * (`2026-09-24`, `2026-09-24T10:00:00Z`), or an age such as `90m`, `12h`,
+ * `7d`, `2w` counted back from `now`. Throws on anything else, naming the flag.
+ */
+function parseAuditTime(value, flagName, now = Date.now()) {
+    const trimmed = value.trim();
+    const age = trimmed.match(/^(\d+)([smhdw])$/i);
+    if (age) {
+        return new Date(now - Number(age[1]) * DURATION_MS[age[2].toLowerCase()]).toISOString();
+    }
+    const absolute = new Date(trimmed);
+    if (!trimmed || Number.isNaN(absolute.getTime())) {
+        throw new Error(`Invalid ${flagName} value: ${value}. Use a time such as 2026-09-24 or an age such as 7d.`);
+    }
+    return absolute.toISOString();
+}
+async function listMachineAudit(machineId, query = {}) {
+    const params = new URLSearchParams();
+    for (const kind of query.kinds ?? [])
+        params.append('kind', kind);
+    if (query.actorUserId)
+        params.set('actor', query.actorUserId);
+    if (query.since != null)
+        params.set('since', String(query.since));
+    if (query.until != null)
+        params.set('until', String(query.until));
+    if (query.cursor)
+        params.set('cursor', query.cursor);
+    if (query.limit != null)
+        params.set('limit', String(query.limit));
+    const qs = params.toString();
+    const suffix = qs ? `?${qs}` : '';
+    return (0, api_fetch_1.apiFetch)(`/api/machines/${encodeURIComponent(machineId)}/audit` + suffix);
+}

package/dist/lib/machine-grants.d.ts

@@ -0,0 +1,70 @@
+/**
+ * machine-grants.ts — request client for `/api/machines/:machineId/grants`
+ * (design §9, D10; OSK-13558): who the owner shares a machine with.
+ *
+ * A grant gives one person, on one machine, one of two fixed tiers — `watch`
+ * (see every surface and its activity; no input, no file browsing) or
+ * `operate` (everything watch has, plus control and file read/write). `power`,
+ * closing other people's surfaces and grant management stay with the owner,
+ * which is why every verb here resolves machine OWNERSHIP server-side rather
+ * than checking a grant. The grantee may be any user, inside the owner's
+ * workspace or not.
+ *
+ * ## Inline path literals
+ *
+ * `domain-api-parity` resolves a command to an endpoint by reading these
+ * strings. A helper that assembles the URL is opaque to it, so the endpoint
+ * would read as unreachable and get allow-listed — a check going green on an
+ * assertion it never made.
+ */
+export declare const MACHINE_GRANT_TIERS: readonly ["watch", "operate"];
+export type MachineGrantTier = (typeof MACHINE_GRANT_TIERS)[number];
+/** One grant, as `ComputerGrantService.publicGrant` emits it. */
+export interface MachineGrant {
+    grantId: string;
+    machineId: string;
+    ownerUserId: string;
+    granteeUserId: string;
+    tier: MachineGrantTier;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export interface MachineGrantList {
+    version: number;
+    grants: MachineGrant[];
+}
+export interface MachineGrantMutation {
+    grant: MachineGrant;
+    version: number;
+    /** POST only: false when the person already held this exact grant. */
+    created?: boolean;
+    /** PATCH only: false when the grant already held this tier. */
+    changed?: boolean;
+}
+export interface MachineGrantRevocation {
+    revoked: MachineGrant;
+    version: number;
+}
+export declare function listMachineGrants(machineId: string): Promise<MachineGrantList>;
+export declare function shareMachine(machineId: string, granteeUserId: string, tier: MachineGrantTier): Promise<MachineGrantMutation>;
+export declare function changeMachineGrant(machineId: string, granteeUserId: string, tier: MachineGrantTier): Promise<MachineGrantMutation>;
+export declare function unshareMachine(machineId: string, granteeUserId: string): Promise<MachineGrantRevocation>;
+export interface SharedMachine {
+    machineId: string;
+    name: string | null;
+    owner: {
+        userId: string;
+        name: string;
+        username?: string;
+        avatar?: string;
+    } | null;
+    tier: MachineGrantTier;
+    grantedAt?: number;
+    power?: {
+        phase: string;
+    } | null;
+}
+export interface SharedMachineList {
+    machines: SharedMachine[];
+}
+export declare function listSharedMachines(): Promise<SharedMachineList>;

package/dist/lib/machine-grants.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MACHINE_GRANT_TIERS = void 0;
+exports.listMachineGrants = listMachineGrants;
+exports.shareMachine = shareMachine;
+exports.changeMachineGrant = changeMachineGrant;
+exports.unshareMachine = unshareMachine;
+exports.listSharedMachines = listSharedMachines;
+const api_fetch_1 = require("./api-fetch");
+/**
+ * machine-grants.ts — request client for `/api/machines/:machineId/grants`
+ * (design §9, D10; OSK-13558): who the owner shares a machine with.
+ *
+ * A grant gives one person, on one machine, one of two fixed tiers — `watch`
+ * (see every surface and its activity; no input, no file browsing) or
+ * `operate` (everything watch has, plus control and file read/write). `power`,
+ * closing other people's surfaces and grant management stay with the owner,
+ * which is why every verb here resolves machine OWNERSHIP server-side rather
+ * than checking a grant. The grantee may be any user, inside the owner's
+ * workspace or not.
+ *
+ * ## Inline path literals
+ *
+ * `domain-api-parity` resolves a command to an endpoint by reading these
+ * strings. A helper that assembles the URL is opaque to it, so the endpoint
+ * would read as unreachable and get allow-listed — a check going green on an
+ * assertion it never made.
+ */
+exports.MACHINE_GRANT_TIERS = ['watch', 'operate'];
+async function listMachineGrants(machineId) {
+    return (0, api_fetch_1.apiFetch)(`/api/machines/${encodeURIComponent(machineId)}/grants`);
+}
+async function shareMachine(machineId, granteeUserId, tier) {
+    return (0, api_fetch_1.apiFetch)(`/api/machines/${encodeURIComponent(machineId)}/grants`, {
+        method: 'POST',
+        body: { granteeUserId, tier },
+    });
+}
+async function changeMachineGrant(machineId, granteeUserId, tier) {
+    return (0, api_fetch_1.apiFetch)(`/api/machines/${encodeURIComponent(machineId)}/grants/${encodeURIComponent(granteeUserId)}`, { method: 'PATCH', body: { tier } });
+}
+async function unshareMachine(machineId, granteeUserId) {
+    return (0, api_fetch_1.apiFetch)(`/api/machines/${encodeURIComponent(machineId)}/grants/${encodeURIComponent(granteeUserId)}`, { method: 'DELETE' });
+}
+async function listSharedMachines() {
+    return (0, api_fetch_1.apiFetch)('/api/machines/shared-with-me');
+}

package/dist/lib/machine-services.d.ts

@@ -0,0 +1,64 @@
+/**
+ * machine-services.ts — request client for `/api/machines/:machineId/services`
+ * (design §20.5; 9-17, OSK-13579): a machine's declared services, the web
+ * services an agent or a person started on it, named so the computer can open
+ * them in its own browser.
+ *
+ * Not the same thing as `skrr machines dedicated service`: those are always-on
+ * WORKLOADS a Dedicated Runtime keeps running. A declared service is an
+ * address — a port on the machine's own loopback, and an optional path — on
+ * any computer, a personal machine's included. Declaring one starts nothing.
+ *
+ * Who may: the owner and an `operate` grantee declare and withdraw; a `watch`
+ * grantee may list. The server decides (`ComputerAccess`), and so does the
+ * machine's daemon, against the grant set it holds.
+ *
+ * ## Inline path literals
+ *
+ * `domain-api-parity` resolves a command to an endpoint by reading these
+ * strings, so each one is written out here rather than assembled by a helper.
+ */
+export declare const DECLARED_SERVICE_PROTOCOLS: readonly ["http", "https"];
+export type DeclaredServiceProtocol = (typeof DECLARED_SERVICE_PROTOCOLS)[number];
+export type DeclaredServiceActor = {
+    kind: 'agent';
+    agentId: string;
+    sessionId: string;
+    label: string;
+} | {
+    kind: 'human';
+    userId: string;
+    label: string;
+};
+/** One declared service, as the machine's manifest carries it. */
+export interface DeclaredService {
+    name: string;
+    port: number;
+    path: string;
+    protocol: DeclaredServiceProtocol;
+    declaredBy: DeclaredServiceActor;
+    declaredAt: number;
+}
+export interface DeclaredServicesResult {
+    services: DeclaredService[];
+    service?: DeclaredService;
+    replaced?: boolean;
+    withdrawn?: DeclaredService;
+}
+/** Where a service opens: always the machine's own loopback. */
+export declare function declaredServiceAddress(service: Pick<DeclaredService, 'port' | 'path' | 'protocol'>): string;
+export declare function listMachineServices(machineId: string): Promise<DeclaredServicesResult>;
+export declare function declareMachineService(machineId: string, service: {
+    name: string;
+    port: number;
+    path?: string;
+    protocol?: DeclaredServiceProtocol;
+}): Promise<DeclaredServicesResult>;
+export declare function withdrawMachineService(machineId: string, name: string): Promise<DeclaredServicesResult>;
+/**
+ * The machine id a services command addresses. A machine the person owns
+ * resolves from their inventory by any of its names; a machine shared WITH
+ * them is not in that inventory, so a full machine id (`lease:…`,
+ * `daemon:…`, `machine:…`) is taken as written — the server decides access.
+ */
+export declare function servicesMachineId(ref: string): Promise<string>;

package/dist/lib/machine-services.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DECLARED_SERVICE_PROTOCOLS = void 0;
+exports.declaredServiceAddress = declaredServiceAddress;
+exports.listMachineServices = listMachineServices;
+exports.declareMachineService = declareMachineService;
+exports.withdrawMachineService = withdrawMachineService;
+exports.servicesMachineId = servicesMachineId;
+const api_fetch_1 = require("./api-fetch");
+const machines_1 = require("./machines");
+/**
+ * machine-services.ts — request client for `/api/machines/:machineId/services`
+ * (design §20.5; 9-17, OSK-13579): a machine's declared services, the web
+ * services an agent or a person started on it, named so the computer can open
+ * them in its own browser.
+ *
+ * Not the same thing as `skrr machines dedicated service`: those are always-on
+ * WORKLOADS a Dedicated Runtime keeps running. A declared service is an
+ * address — a port on the machine's own loopback, and an optional path — on
+ * any computer, a personal machine's included. Declaring one starts nothing.
+ *
+ * Who may: the owner and an `operate` grantee declare and withdraw; a `watch`
+ * grantee may list. The server decides (`ComputerAccess`), and so does the
+ * machine's daemon, against the grant set it holds.
+ *
+ * ## Inline path literals
+ *
+ * `domain-api-parity` resolves a command to an endpoint by reading these
+ * strings, so each one is written out here rather than assembled by a helper.
+ */
+exports.DECLARED_SERVICE_PROTOCOLS = ['http', 'https'];
+/** Where a service opens: always the machine's own loopback. */
+function declaredServiceAddress(service) {
+    return `${service.protocol}://localhost:${service.port}${service.path}`;
+}
+async function listMachineServices(machineId) {
+    return (0, api_fetch_1.apiFetch)(`/api/machines/${encodeURIComponent(machineId)}/services`);
+}
+async function declareMachineService(machineId, service) {
+    return (0, api_fetch_1.apiFetch)(`/api/machines/${encodeURIComponent(machineId)}/services`, { method: 'POST', body: { service } });
+}
+async function withdrawMachineService(machineId, name) {
+    return (0, api_fetch_1.apiFetch)(`/api/machines/${encodeURIComponent(machineId)}/services/${encodeURIComponent(name)}`, { method: 'DELETE' });
+}
+/**
+ * The machine id a services command addresses. A machine the person owns
+ * resolves from their inventory by any of its names; a machine shared WITH
+ * them is not in that inventory, so a full machine id (`lease:…`,
+ * `daemon:…`, `machine:…`) is taken as written — the server decides access.
+ */
+async function servicesMachineId(ref) {
+    try {
+        return (0, machines_1.resolveMachineRef)(await (0, machines_1.listMachines)(), ref).id;
+    }
+    catch (error) {
+        if (/^(lease|daemon|machine|stable-daemon):\S+$/.test(ref))
+            return ref;
+        throw error;
+    }
+}

package/dist/lib/task-view-render.d.ts

@@ -19,6 +19,8 @@ export interface TaskViewFilters {
     priorities?: string[];
     assignees?: string[];
     labels?: string[];
+    /** How `labels` combine; absent means `any`. */
+    labelMatch?: string;
     goalIds?: string[];
     projectIds?: string[];
     cycleIds?: string[];