sharednet 0.1.0

package/dist/instance-computation.js

@@ -0,0 +1,26 @@
+import { createHmac } from "node:crypto";
+import { localError } from "./errors.js";
+import { detectRuntime } from "./runtime-detection.js";
+/** The driver's session, when the driver exposes one. See runtime-detection.ts. */
+export function detectRuntimeSession(env) {
+    const detected = detectRuntime(env, { parentProcess: () => null });
+    return detected.anchor === null ? null : { runtimeKind: detected.kind, anchor: detected.anchor };
+}
+export function computeLocalInstanceKey(installationSecret, runtimeKind, providerSessionAnchor) {
+    let key;
+    try {
+        key = Buffer.from(installationSecret, "base64url");
+    }
+    catch {
+        throw localError("invalid_local_state", "The installation secret is invalid.");
+    }
+    if (key.byteLength !== 32) {
+        throw localError("invalid_local_state", "The installation secret is invalid.");
+    }
+    if (!providerSessionAnchor) {
+        throw localError("runtime_session_not_detected", "The current runtime session could not be detected.");
+    }
+    return createHmac("sha256", key)
+        .update(`${runtimeKind}\0${providerSessionAnchor}`, "utf8")
+        .digest("hex");
+}

package/dist/login.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `sharednet login`: a device-style approval. The CLI starts a login, shows a
+ * code and a URL, the human approves it in the Web, and the CLI polls until
+ * it is handed an API key minted at that moment. Any anonymous seats this
+ * machine holds are sent as proof of possession so the approval binds their
+ * Principals to the account. Decision 2026-09-06 §3.
+ */
+type Environment = Record<string, string | undefined>;
+export interface LoginDependencies {
+    env: Environment;
+    fetch: typeof globalThis.fetch;
+    stdout: (value: string) => void;
+    stderr: (value: string) => void;
+    now: () => Date;
+    sleep?: (ms: number) => Promise<void>;
+    /** Opens a URL in the human's browser; the default shells out. */
+    openBrowser?: (url: string) => Promise<boolean>;
+}
+export declare function login(args: string[], dependencies: LoginDependencies): Promise<unknown>;
+export {};

package/dist/login.js

@@ -0,0 +1,137 @@
+import { spawn } from "node:child_process";
+import { readdir } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { ApiClient, resolveBaseUrl } from "./api-client.js";
+import { CliError, localError } from "./errors.js";
+import { getOrCreateInstallationSecret, getStoragePaths, readRoomCredential, writeStoredApiCredential, } from "./storage.js";
+const VALUE_OPTIONS = new Set(["label"]);
+const FLAG_OPTIONS = new Set(["no-browser"]);
+function parseLoginArguments(args) {
+    let label;
+    let openBrowser = true;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (!argument.startsWith("--")) {
+            throw localError("invalid_arguments", "Usage: sharednet login [--label <where>] [--no-browser]");
+        }
+        const separator = argument.indexOf("=");
+        const name = argument.slice(2, separator === -1 ? undefined : separator);
+        if (FLAG_OPTIONS.has(name)) {
+            if (separator !== -1)
+                throw localError("invalid_option", `The --${name} option does not accept a value.`);
+            openBrowser = false;
+            continue;
+        }
+        if (!VALUE_OPTIONS.has(name))
+            throw localError("unknown_option", "The command contains an unknown option.");
+        const value = separator === -1 ? args[++index] : argument.slice(separator + 1);
+        if (!value || value.startsWith("--"))
+            throw localError("missing_option_value", `The --${name} option requires a value.`);
+        label = value;
+    }
+    return { label, openBrowser };
+}
+async function defaultOpenBrowser(url) {
+    const command = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd", "/c", "start", "", url] : ["xdg-open", url];
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(command[0], command.slice(1), { detached: true, stdio: "ignore" });
+            child.once("error", () => resolve(false));
+            child.once("spawn", () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/** Every seat token this machine holds, so approval can bind their Principals. */
+async function heldSeatTokens(paths) {
+    let roomDirs;
+    try {
+        roomDirs = await readdir(paths.roomsDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const tokens = [];
+    for (const roomId of roomDirs) {
+        if (!/^rom_[A-Za-z0-9]+$/.test(roomId))
+            continue;
+        let files;
+        try {
+            files = await readdir(join(paths.roomsDir, roomId));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            const memberId = file.replace(/\.json$/, "");
+            if (!/^(?:i|mem)_[A-Za-z0-9]+$/.test(memberId))
+                continue;
+            const credential = await readRoomCredential(paths, roomId, memberId).catch(() => null);
+            if (credential && /^(?:sni|rmt)_[A-Za-z0-9_-]{43}$/.test(credential.member_token)) {
+                tokens.push(credential.member_token);
+            }
+        }
+    }
+    return tokens.slice(0, 50);
+}
+export async function login(args, dependencies) {
+    const { label, openBrowser } = parseLoginArguments(args);
+    const baseUrl = resolveBaseUrl(dependencies.env.SHAREDNET_BASE_URL);
+    const paths = getStoragePaths(dependencies.env);
+    const client = new ApiClient(baseUrl, dependencies.fetch);
+    const seats = await heldSeatTokens(paths);
+    const started = await client.request("POST", "/cli/logins", "", {
+        label: label ?? hostname() ?? null,
+        ...(seats.length > 0 ? { seats } : {}),
+    });
+    if (!started?.login?.id || !started.user_code || !started.poll_token || !started.verify_url) {
+        throw new CliError("invalid_server_response", "The SharedNet service returned an invalid response.", 5);
+    }
+    dependencies.stderr(`Approve this terminal in your browser.\n\n  Code:  ${started.user_code}\n  Open:  ${started.verify_url}\n\n` +
+        (started.login.bind_instance_ids.length > 0
+            ? `Approval also binds ${started.login.bind_instance_ids.length} seat(s) this machine holds to your account.\n\n`
+            : ""));
+    if (openBrowser) {
+        const opened = await (dependencies.openBrowser ?? defaultOpenBrowser)(started.verify_url);
+        if (!opened)
+            dependencies.stderr("Could not open a browser; open the URL yourself.\n");
+    }
+    const sleep = dependencies.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const intervalMs = Math.max(1, started.interval_seconds || 3) * 1000;
+    const deadline = Date.parse(started.login.expires_at);
+    for (;;) {
+        const result = await client.request("POST", `/cli/logins/${encodeURIComponent(started.login.id)}/poll`, started.poll_token);
+        if (result.state === "approved") {
+            const installationSecret = await getOrCreateInstallationSecret(paths);
+            await writeStoredApiCredential(paths, {
+                schema_version: 1,
+                base_url: baseUrl,
+                principal_id: result.principal.id,
+                api_key_id: result.api_key_id,
+                api_key: result.api_key,
+                installation_secret: installationSecret,
+                created_at: dependencies.now().toISOString(),
+                expires_at: null,
+            });
+            // The key stays in the credential file; the terminal sees only ids.
+            return {
+                principal_id: result.principal.id,
+                api_key_id: result.api_key_id,
+                bound_instance_ids: result.login.bind_instance_ids,
+                credentials_file: paths.credentialsFile,
+            };
+        }
+        if (Number.isFinite(deadline) && dependencies.now().getTime() >= deadline) {
+            throw new CliError("login_expired", "The login was not approved in time. Run sharednet login again.", 4);
+        }
+        await sleep(intervalMs);
+    }
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<number>;

package/dist/main.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runCli } from "./cli.js";
+export async function main(argv = process.argv.slice(2)) {
+    return runCli(argv);
+}
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : "";
+if (invokedPath && fileURLToPath(import.meta.url) === invokedPath) {
+    process.exitCode = await main();
+}

package/dist/runtime-detection.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Which coding-agent driver is running this CLI, read off the driver's own
+ * environment. Everything here is diagnostic: it names the seat on the Web and
+ * picks its icon, and the session anchor feeds the local Instance key. Nothing
+ * is trusted for authorization.
+ *
+ * Markers verified on 2026-09-06 on macOS:
+ *   Claude Code   CLAUDECODE=1, CLAUDE_CODE_SESSION_ID, CLAUDE_CODE_ENTRYPOINT
+ *                 (claude-desktop | cli), CLAUDE_AGENT_SDK_VERSION
+ *   Codex CLI     CODEX_SESSION_ID, CODEX_THREAD_ID (lineage, not a session),
+ *                 CODEX_CI=1 under `codex exec`; parent process is `codex`
+ * The OpenCode, OpenHands, Gemini CLI and Cursor markers below are taken from
+ * their documentation and not yet verified on a machine; the parent-process
+ * fallback covers a driver whose variables differ.
+ */
+export type RuntimeSource = "detected" | "declared";
+export interface DetectedRuntime {
+    /** A handle such as `claude-code`; `custom` when nothing was recognised. */
+    kind: string;
+    /** The driver's exact session id, kept on this machine and only ever HMACed. */
+    anchor: string | null;
+    version: string | null;
+    entrypoint: string | null;
+    source: RuntimeSource;
+}
+type Environment = Record<string, string | undefined>;
+/**
+ * The nearest ancestor process that is a known driver, or null. A CLI run
+ * from a Codex shell inside a Claude Code session has both drivers'
+ * variables in its environment; the process tree says which one is actually
+ * running it.
+ */
+export declare function nearestDriverAncestor(startPid?: number): string | null;
+/** The name of the process that launched this one, or null when it cannot be read. */
+export declare function parentProcessName(ppid?: number): string | null;
+export declare function detectRuntime(env: Environment, options?: {
+    parentProcess?: () => string | null;
+    ancestorDriver?: () => string | null;
+}): DetectedRuntime;
+export declare function isRuntimeKind(value: string): boolean;
+/** The diagnostic fields a detected driver contributes to an Instance's metadata. */
+export declare function runtimeMetadataOf(runtime: DetectedRuntime): Record<string, string>;
+export {};

package/dist/runtime-detection.js

@@ -0,0 +1,165 @@
+import { spawnSync } from "node:child_process";
+import { basename } from "node:path";
+const RUNTIME_KIND_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+function nonEmpty(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : null;
+}
+function clean(value) {
+    if (value === null)
+        return null;
+    const printable = value.replace(/[^\x20-\x7e]/g, "").trim().slice(0, 64);
+    return printable.length > 0 ? printable : null;
+}
+function hasPrefix(env, prefix) {
+    return Object.keys(env).some((key) => key.startsWith(prefix) && nonEmpty(env[key]) !== null);
+}
+const PARENT_PROCESS_KINDS = {
+    claude: "claude-code",
+    codex: "codex",
+    opencode: "opencode",
+    openhands: "openhands",
+    gemini: "gemini-cli",
+    cursor: "cursor",
+};
+function processEntry(pid) {
+    if (process.platform === "win32" || !Number.isInteger(pid) || pid <= 1)
+        return null;
+    const result = spawnSync("ps", ["-o", "ppid=,comm=", "-p", String(pid)], {
+        encoding: "utf8",
+        timeout: 2000,
+    });
+    if (result.status !== 0)
+        return null;
+    const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(result.stdout);
+    if (!match)
+        return null;
+    return { ppid: Number(match[1]), name: basename(match[2]) };
+}
+/**
+ * The nearest ancestor process that is a known driver, or null. A CLI run
+ * from a Codex shell inside a Claude Code session has both drivers'
+ * variables in its environment; the process tree says which one is actually
+ * running it.
+ */
+export function nearestDriverAncestor(startPid = process.ppid) {
+    let pid = startPid;
+    for (let hop = 0; hop < 12; hop += 1) {
+        const entry = processEntry(pid);
+        if (!entry)
+            return null;
+        const kind = PARENT_PROCESS_KINDS[entry.name.toLowerCase()];
+        if (kind)
+            return kind;
+        if (entry.ppid <= 1 || entry.ppid === pid)
+            return null;
+        pid = entry.ppid;
+    }
+    return null;
+}
+/** The name of the process that launched this one, or null when it cannot be read. */
+export function parentProcessName(ppid = process.ppid) {
+    return processEntry(ppid)?.name ?? null;
+}
+/**
+ * Detect the driver. Every driver whose variables are present is a candidate;
+ * one that exposes its own session id outranks one that only leaves markers,
+ * because markers are inherited by everything a driver spawns while a session
+ * id is set per process. When two drivers both expose a session id, the
+ * process tree decides; when it cannot, the first in DRIVER_ORDER wins.
+ */
+const DRIVER_ORDER = ["codex", "claude-code", "opencode", "openhands", "gemini-cli", "cursor"];
+function candidates(env) {
+    const found = [];
+    const claudeAnchor = nonEmpty(env.CLAUDE_CODE_SESSION_ID) ?? nonEmpty(env.CLAUDE_SESSION_ID);
+    if (claudeAnchor !== null || nonEmpty(env.CLAUDECODE) !== null) {
+        found.push({
+            kind: "claude-code",
+            anchor: claudeAnchor,
+            version: clean(nonEmpty(env.CLAUDE_AGENT_SDK_VERSION)),
+            entrypoint: clean(nonEmpty(env.CLAUDE_CODE_ENTRYPOINT)),
+            source: "detected",
+        });
+    }
+    // CODEX_THREAD_ID is deliberately not an anchor: it is lineage, not the
+    // executing session, and would collapse concurrent child sessions.
+    const codexAnchor = nonEmpty(env.CODEX_SESSION_ID);
+    if (codexAnchor !== null) {
+        found.push({
+            kind: "codex",
+            anchor: codexAnchor,
+            version: clean(nonEmpty(env.CODEX_VERSION)),
+            entrypoint: nonEmpty(env.CODEX_CI) !== null ? "exec" : null,
+            source: "detected",
+        });
+    }
+    if (hasPrefix(env, "OPENCODE")) {
+        found.push({
+            kind: "opencode",
+            anchor: nonEmpty(env.OPENCODE_SESSION_ID),
+            version: clean(nonEmpty(env.OPENCODE_VERSION)),
+            entrypoint: null,
+            source: "detected",
+        });
+    }
+    if (hasPrefix(env, "OPENHANDS")) {
+        found.push({
+            kind: "openhands",
+            anchor: nonEmpty(env.OPENHANDS_SESSION_ID) ?? nonEmpty(env.OPENHANDS_CONVERSATION_ID),
+            version: clean(nonEmpty(env.OPENHANDS_VERSION)),
+            entrypoint: null,
+            source: "detected",
+        });
+    }
+    if (nonEmpty(env.GEMINI_CLI) !== null || hasPrefix(env, "GEMINI_CLI_")) {
+        found.push({
+            kind: "gemini-cli",
+            anchor: nonEmpty(env.GEMINI_CLI_SESSION_ID),
+            version: clean(nonEmpty(env.GEMINI_CLI_VERSION)),
+            entrypoint: null,
+            source: "detected",
+        });
+    }
+    if (nonEmpty(env.CURSOR_AGENT) !== null || nonEmpty(env.CURSOR_TRACE_ID) !== null) {
+        found.push({
+            kind: "cursor",
+            anchor: nonEmpty(env.CURSOR_TRACE_ID),
+            version: null,
+            entrypoint: null,
+            source: "detected",
+        });
+    }
+    return found.sort((a, b) => DRIVER_ORDER.indexOf(a.kind) - DRIVER_ORDER.indexOf(b.kind));
+}
+export function detectRuntime(env, options = {}) {
+    const found = candidates(env);
+    const withSession = found.filter((candidate) => candidate.anchor !== null);
+    if (withSession.length === 1)
+        return withSession[0];
+    if (withSession.length > 1) {
+        const byTree = (options.ancestorDriver ?? nearestDriverAncestor)();
+        return withSession.find((candidate) => candidate.kind === byTree) ?? withSession[0];
+    }
+    if (found.length > 0) {
+        const byTree = (options.ancestorDriver ?? nearestDriverAncestor)();
+        return found.find((candidate) => candidate.kind === byTree) ?? found[0];
+    }
+    const parent = (options.parentProcess ?? parentProcessName)();
+    const byParent = parent ? PARENT_PROCESS_KINDS[parent.toLowerCase()] : undefined;
+    if (byParent) {
+        return { kind: byParent, anchor: null, version: null, entrypoint: null, source: "detected" };
+    }
+    return { kind: "custom", anchor: null, version: null, entrypoint: null, source: "declared" };
+}
+export function isRuntimeKind(value) {
+    return RUNTIME_KIND_PATTERN.test(value);
+}
+/** The diagnostic fields a detected driver contributes to an Instance's metadata. */
+export function runtimeMetadataOf(runtime) {
+    const metadata = { runtime_source: runtime.source };
+    if (runtime.version)
+        metadata.driver_version = runtime.version;
+    if (runtime.entrypoint)
+        metadata.entrypoint = runtime.entrypoint;
+    return metadata;
+}

package/dist/session.d.ts

@@ -0,0 +1,80 @@
+import { ApiClient } from "./api-client.ts";
+import { type StoragePaths, type StoredSession } from "./storage.ts";
+/**
+ * Acting as an account: the stored credential, registering this session as an
+ * Instance, keeping its lease alive. Shared by `session start`, the Room
+ * commands, and `join` when a credential is present.
+ */
+type Environment = Record<string, string | undefined>;
+export declare const CLI_VERSION = "0.1.0";
+export interface AgentShape {
+    id: string;
+    principal_id?: string;
+    handle?: string;
+}
+export interface InstanceShape {
+    id: string;
+    principal_id: string;
+    agent_id: string | null;
+    started_at: string;
+    lease_expires_at: string;
+    token_expires_at?: string;
+    expires_at?: string;
+    [key: string]: unknown;
+}
+export interface InstanceStartPayload {
+    instance: InstanceShape;
+    token: string;
+    heartbeat_after_seconds: number;
+}
+export interface CurrentInstancePayload {
+    principal: unknown;
+    agent: AgentShape | null;
+    instance: InstanceShape;
+}
+export declare function resolveApiKey(env: Environment, paths: StoragePaths, baseUrl: string): Promise<string>;
+/**
+ * Resolves `--agent` to a tag. An `a_` id is fetched; anything else is a
+ * handle and is created on first use, the way `git tag` behaves — the server's
+ * POST is idempotent by handle, so one call covers both "exists" and "new".
+ * `default` names the absence of a tag and resolves to nothing.
+ */
+export declare function resolveTag(client: ApiClient, apiKey: string, requested: string): Promise<AgentShape | null>;
+/**
+ * Where this session runs, for humans telling untagged sessions apart. It is
+ * shown, never trusted: the server records it as diagnostics and nothing reads
+ * it for authorization or grouping.
+ *
+ * Only the workspace's last path segment is sent. The full path is a map of
+ * this machine — home directory, user name, client folders — and none of that
+ * is needed to tell "the one in the sharednet folder" from the others.
+ */
+export declare function runtimeMetadata(env: Environment): Record<string, string>;
+export declare function validateRuntime(value: string): string;
+export declare function storedSessionFromStart(baseUrl: string, localInstanceKey: string | null, payload: InstanceStartPayload): StoredSession;
+export declare function selectSession(paths: StoragePaths, baseUrl: string, explicitId: string | undefined, env: Environment): Promise<StoredSession>;
+export declare function refreshIfNeeded(client: ApiClient, paths: StoragePaths, session: StoredSession, now: Date): Promise<StoredSession>;
+export interface RegisterInstanceOptions {
+    /** `--runtime`: overrides the detected driver's name, never its session. */
+    runtimeOverride?: string;
+    /** `--new`: a fresh Instance even though the session was detected. */
+    forceNew: boolean;
+    /** `--agent`: a tag id or handle to group the Instance under. */
+    agent?: string;
+    /** Without a detected session and without `forceNew`, refuse (session start) or register fresh (join). */
+    freshWhenUndetected: boolean;
+    /** Sent as given; omitted, the server applies the Principal's default (public). */
+    reach?: "public" | "private";
+}
+/**
+ * Registers this session as an Instance of the account behind the stored
+ * credential. A same-session re-registration comes back with the existing
+ * Instance and a fresh token; a new session comes back created.
+ */
+export declare function registerInstance(env: Environment, fetchImplementation: typeof globalThis.fetch, paths: StoragePaths, baseUrl: string, options: RegisterInstanceOptions): Promise<{
+    session: StoredSession;
+    payload: InstanceStartPayload;
+}>;
+/** True when this machine can act as an account: a key in the environment or a stored credential for this origin. */
+export declare function hasAccountCredential(env: Environment, paths: StoragePaths, baseUrl: string): Promise<boolean>;
+export {};

package/dist/session.js

@@ -0,0 +1,182 @@
+import { hostname, platform } from "node:os";
+import { ApiClient } from "./api-client.js";
+import { CliError, localError } from "./errors.js";
+import { computeLocalInstanceKey } from "./instance-computation.js";
+import { detectRuntime, isRuntimeKind, runtimeMetadataOf } from "./runtime-detection.js";
+import { deleteSession, getOrCreateInstallationSecret, listSessions, readSessionById, readStoredApiCredential, writeSession, } from "./storage.js";
+export const CLI_VERSION = "0.1.0";
+function apiKeyAuthenticationError() {
+    return new CliError("authentication_required", "Set SHAREDNET_API_KEY or run sharednet login first.", 3);
+}
+export async function resolveApiKey(env, paths, baseUrl) {
+    const environmentKey = env.SHAREDNET_API_KEY?.trim();
+    if (environmentKey)
+        return environmentKey;
+    const credential = await readStoredApiCredential(paths);
+    if (!credential)
+        throw apiKeyAuthenticationError();
+    if (credential.base_url !== baseUrl) {
+        throw localError("credential_origin_mismatch", "The stored credential belongs to a different SharedNet origin.");
+    }
+    if (credential.expires_at && Date.parse(credential.expires_at) <= Date.now()) {
+        throw new CliError("invalid_credentials", "The stored API key has expired.", 3);
+    }
+    return credential.api_key;
+}
+/**
+ * Resolves `--agent` to a tag. An `a_` id is fetched; anything else is a
+ * handle and is created on first use, the way `git tag` behaves — the server's
+ * POST is idempotent by handle, so one call covers both "exists" and "new".
+ * `default` names the absence of a tag and resolves to nothing.
+ */
+export async function resolveTag(client, apiKey, requested) {
+    const handle = requested.normalize("NFKC").trim().toLowerCase();
+    if (handle === "default")
+        return null;
+    let agent;
+    if (/^a_[A-Za-z0-9]+$/.test(requested)) {
+        const payload = await client.request("GET", `/agents/${encodeURIComponent(requested)}`, apiKey);
+        agent = payload.agent;
+    }
+    else {
+        if (!/^[a-z][a-z0-9-]{0,31}$/.test(handle)) {
+            throw localError("invalid_agent", "An Agent is an a_ id or a handle matching ^[a-z][a-z0-9-]{0,31}$.");
+        }
+        const payload = await client.request("POST", "/agents", apiKey, {
+            handle,
+        });
+        agent = payload.agent;
+    }
+    if (!agent?.id) {
+        throw new CliError("invalid_server_response", "The SharedNet service returned an invalid Agent response.", 5);
+    }
+    return agent;
+}
+/**
+ * Where this session runs, for humans telling untagged sessions apart. It is
+ * shown, never trusted: the server records it as diagnostics and nothing reads
+ * it for authorization or grouping.
+ *
+ * Only the workspace's last path segment is sent. The full path is a map of
+ * this machine — home directory, user name, client folders — and none of that
+ * is needed to tell "the one in the sharednet folder" from the others.
+ */
+export function runtimeMetadata(env) {
+    const clean = (value) => (value ?? "").replace(/[\u0000-\u001f\u007f]/g, "").trim().slice(0, 256);
+    const metadata = {};
+    const host = clean(hostname());
+    const workspacePath = clean(env.PWD ?? process.cwd());
+    const workspace = workspacePath.split(/[\\/]+/).filter(Boolean).at(-1) ?? "";
+    if (host)
+        metadata.hostname = host;
+    if (workspace)
+        metadata.workspace = workspace;
+    metadata.os = platform();
+    return metadata;
+}
+export function validateRuntime(value) {
+    const kind = value.normalize("NFKC").trim().toLowerCase();
+    if (isRuntimeKind(kind))
+        return kind;
+    throw localError("invalid_runtime", "Runtime must be a handle such as claude-code, codex, or opencode.");
+}
+export function storedSessionFromStart(baseUrl, localInstanceKey, payload) {
+    const { instance, token } = payload;
+    if (!instance?.id || !instance.principal_id || !token) {
+        throw new CliError("invalid_server_response", "The SharedNet service returned an invalid Instance response.", 5);
+    }
+    return {
+        schema_version: 1,
+        base_url: baseUrl,
+        principal_id: instance.principal_id,
+        agent_id: instance.agent_id ?? null,
+        instance_id: instance.id,
+        local_instance_key: localInstanceKey,
+        instance_token: token,
+        created_at: instance.started_at,
+        lease_expires_at: instance.lease_expires_at,
+        expires_at: null,
+    };
+}
+export async function selectSession(paths, baseUrl, explicitId, env) {
+    const selectedId = explicitId || env.SHAREDNET_SESSION?.trim();
+    if (selectedId) {
+        if (!/^i_[A-Za-z0-9_-]+$/.test(selectedId)) {
+            throw localError("invalid_session_id", "SHAREDNET_SESSION must be an Instance ID.");
+        }
+        const selected = await readSessionById(paths, selectedId);
+        if (!selected || selected.base_url !== baseUrl) {
+            throw localError("session_not_found", "The selected local SharedNet session was not found.");
+        }
+        return selected;
+    }
+    const usable = (await listSessions(paths)).filter((session) => session.base_url === baseUrl);
+    if (usable.length !== 1) {
+        throw localError("session_selection_required", "Select a local Instance with --session or SHAREDNET_SESSION.");
+    }
+    return usable[0];
+}
+export async function refreshIfNeeded(client, paths, session, now) {
+    if (Date.parse(session.lease_expires_at) - now.getTime() > 30_000)
+        return session;
+    try {
+        const payload = await client.request("POST", "/instances/current/heartbeat", session.instance_token, {});
+        const refreshed = {
+            ...session,
+            lease_expires_at: payload.instance.lease_expires_at,
+            expires_at: null,
+        };
+        await writeSession(paths, refreshed);
+        return refreshed;
+    }
+    catch (error) {
+        if (error instanceof CliError && error.exitCode === 3) {
+            await deleteSession(paths, session.instance_id);
+        }
+        throw error;
+    }
+}
+/**
+ * Registers this session as an Instance of the account behind the stored
+ * credential. A same-session re-registration comes back with the existing
+ * Instance and a fresh token; a new session comes back created.
+ */
+export async function registerInstance(env, fetchImplementation, paths, baseUrl, options) {
+    const installationSecret = await getOrCreateInstallationSecret(paths);
+    // The driver is read off its own environment; --runtime only overrides the name.
+    const detected = detectRuntime(env);
+    const runtimeKind = options.runtimeOverride ? validateRuntime(options.runtimeOverride) : detected.kind;
+    let localInstanceKey = null;
+    if (!options.forceNew) {
+        const undetected = detected.anchor === null || (options.runtimeOverride !== undefined && runtimeKind !== detected.kind);
+        if (undetected && !options.freshWhenUndetected) {
+            throw localError("runtime_session_not_detected", "The current runtime session could not be detected; use --new deliberately.");
+        }
+        if (!undetected) {
+            // The key goes to the server, which is the one place that can guarantee
+            // one live Instance per runtime session. The raw session id stays here.
+            localInstanceKey = computeLocalInstanceKey(installationSecret, runtimeKind, detected.anchor);
+        }
+    }
+    const apiKey = await resolveApiKey(env, paths, baseUrl);
+    const client = new ApiClient(baseUrl, fetchImplementation);
+    const tag = options.agent ? await resolveTag(client, apiKey, options.agent) : undefined;
+    const payload = await client.request("POST", "/instances", apiKey, {
+        runtime_kind: runtimeKind,
+        cli_version: CLI_VERSION,
+        ...(localInstanceKey ? { local_instance_key: localInstanceKey } : {}),
+        ...(tag === undefined ? {} : { agent_id: tag?.id ?? null }),
+        ...(options.reach === undefined ? {} : { reach: options.reach }),
+        runtime_metadata: { ...runtimeMetadata(env), ...runtimeMetadataOf(detected) },
+    });
+    const session = storedSessionFromStart(baseUrl, localInstanceKey, payload);
+    await writeSession(paths, session);
+    return { session, payload };
+}
+/** True when this machine can act as an account: a key in the environment or a stored credential for this origin. */
+export async function hasAccountCredential(env, paths, baseUrl) {
+    if (env.SHAREDNET_API_KEY?.trim())
+        return true;
+    const credential = await readStoredApiCredential(paths).catch(() => null);
+    return credential !== null && credential.base_url === baseUrl;
+}