teamclaws 1.0.0 → 1.0.1

package/dist/output.js

@@ -1,4 +1,5 @@
 import { OUTPUT_SCHEMA_VERSION } from "./constants.js";
+const LOGIN_ACCOUNT_GUIDANCE = "Use your TeamClaws account. If you already have a workspace, use the account that has access to it. This may use a different email from your AI assistant account.";
 export class Output {
     json;
     stdout;
@@ -13,9 +14,11 @@ export class Output {
             schema_version: OUTPUT_SCHEMA_VERSION,
             event: "login_browser_required",
             url,
+            label: "Sign in to TeamClaws",
+            account_guidance: LOGIN_ACCOUNT_GUIDANCE,
         });
         if (!this.json)
-            this.stdout.write(`${url}\n`);
+            this.stdout.write(`Sign in to TeamClaws: ${url}\n${LOGIN_ACCOUNT_GUIDANCE}\n`);
     }
     pairingBrowser(url, userCode, agentAction) {
         const event = {
@@ -55,6 +58,8 @@ export class Output {
             event: "auth_status",
             status,
         };
+        if (status === "signed_out")
+            event.login_command = "teamclaws login --json";
         if (user)
             event.user = user;
         if (expiresAt)
@@ -63,7 +68,7 @@ export class Output {
         if (!this.json) {
             this.stdout.write(status === "signed_in" && user
                 ? `Signed in as ${user.display_name} (${user.email}).\n`
-                : "Not signed in to TeamClaws.\n");
+                : "Not signed in to TeamClaws. Run `teamclaws login` to sign in.\n");
         }
     }
     logoutComplete(remoteConfirmed) {
@@ -78,20 +83,30 @@ export class Output {
                 : "Signed out on this computer. TeamClaws could not confirm remote revocation.\n");
         }
     }
-    servers(servers) {
+    servers(servers, workspaceCount) {
         this.event({
             schema_version: OUTPUT_SCHEMA_VERSION,
             event: "servers_list",
             status: "success",
             servers,
+            workspace_count: workspaceCount ?? null,
+            discovery_state: workspaceCount === 0
+                ? "no_workspaces"
+                : servers.some((server) => server.pairing_ready)
+                    ? "ready"
+                    : workspaceCount === undefined && servers.length === 0
+                        ? "unknown"
+                        : "not_ready",
         });
         if (!this.json) {
             if (servers.length === 0) {
-                this.stdout.write("No pairing-ready TeamClaws workspaces are available.\n");
+                this.stdout.write(workspaceCount === 0
+                    ? "No TeamClaws workspaces are available to this account. Purchase a workspace at https://teamclaws.com/app/.\n"
+                    : "No pairing-ready TeamClaws workspaces are listed. Check existing workspaces at https://teamclaws.com/app/ before considering a purchase.\n");
                 return;
             }
             servers.forEach((server, index) => {
-                this.stdout.write(`${index + 1}. ${server.alias} — ${server.server_id} — ${server.workspace_url}\n`);
+                this.stdout.write(`${index + 1}. ${server.alias} — ${server.server_id} — ${server.workspace_url} — ${server.pairing_ready ? "ready to pair" : "not ready to pair"}\n`);
             });
         }
     }
@@ -191,6 +206,42 @@ export class Output {
             ? `Snapshot generated: ${generatedAt}.\n`
             : "Generation time is not supplied by the capabilities endpoint.\n");
     }
+    chatSessionsList(workspace, records) {
+        const sessions = records.map((record) => ({
+            session_id: record.session_id,
+            request_id: record.request_id,
+            owner_conversation_url: record.owner_conversation_url,
+            revision: record.revision,
+            response_cursor: record.response_cursor,
+            updated_at: record.updated_at,
+        }));
+        this.event({
+            schema_version: OUTPUT_SCHEMA_VERSION,
+            event: "chat_sessions_list",
+            status: "success",
+            source: "local",
+            workspace: { server_id: workspace.server_id, origin: workspace.origin },
+            sessions,
+        });
+        if (!this.json) {
+            this.stdout.write(sessions.length
+                ? "Locally recorded conversations:\n"
+                : "No locally recorded conversations for this workspace and pairing. This is not the workspace conversation inventory.\n");
+            for (const item of sessions)
+                this.stdout.write(`${item.session_id} — request ${item.request_id} — revision ${item.revision}, response cursor ${item.response_cursor} — ${item.owner_conversation_url}\n`);
+        }
+    }
+    chatReferenceRecovery(sessionId, requestId, ownerUrl, revision, responseCursor) {
+        this.externalChatEvent("chat_reference_recovery", {
+            session_id: sessionId,
+            request_id: requestId,
+            owner_conversation_url: ownerUrl,
+            revision,
+            response_cursor: responseCursor,
+        });
+        if (!this.json)
+            this.stdout.write(`Retain session ${sessionId}, request ${requestId}, revision ${revision}, response cursor ${responseCursor}: ${ownerUrl}\n`);
+    }
     chatCapabilities(selection) {
         this.externalChatEvent("capabilities_resolved", {
             provider_key: selection.provider_key,
@@ -295,4 +346,3 @@ export class Output {
         });
     }
 }
-//# sourceMappingURL=output.js.map

package/dist/pairing.js

@@ -242,4 +242,3 @@ async function waitFor(milliseconds, signal) {
         signal?.addEventListener("abort", abort, { once: true });
     });
 }
-//# sourceMappingURL=pairing.js.map

package/dist/shell.js

@@ -0,0 +1,69 @@
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { Readable } from "node:stream";
+import { TeamClawsError } from "./errors.js";
+import { errorFromResponse, requestJson } from "./http.js";
+import { isObject } from "./validation.js";
+export async function runShell(store, fetcher, target, command, signal) {
+    const credential = await store.findWorkspace(target);
+    if (!credential) {
+        throw new TeamClawsError("re_pair_required", "No saved pairing was found for this workspace. Pair it first.", { exitCode: 3 });
+    }
+    const response = await requestJson(fetcher, `${credential.origin}/teamclaws-admin/api/shell/`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${credential.device_id}:${credential.device_token}`,
+        },
+        textBody: command,
+        timeoutMs: null,
+        responseLimitBytes: null,
+        ...(signal ? { signal } : {}),
+    });
+    if (response.status !== 200)
+        throw errorFromResponse(response, "shell_failed");
+    const result = response.body;
+    if (!isObject(result) ||
+        typeof result.stdout !== "string" ||
+        typeof result.stderr !== "string" ||
+        !Number.isSafeInteger(result.exit_code)) {
+        throw new TeamClawsError("invalid_response", "Invalid shell result.", {
+            exitCode: 9,
+        });
+    }
+    return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exit_code: result.exit_code,
+    };
+}
+// Native fetch imposes transport deadlines. This single-use connection has no
+// request deadline, redirects, retries, or response body limit.
+export const shellFetch = async (input, init) => {
+    const url = new URL(String(input));
+    return await new Promise((resolve, reject) => {
+        const request = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, {
+            method: init?.method,
+            headers: Object.fromEntries(new Headers(init?.headers)),
+            agent: false,
+            timeout: 0,
+            ...(init?.signal ? { signal: init.signal } : {}),
+        }, (response) => {
+            const status = response.statusCode ?? 500;
+            const headers = new Headers();
+            for (let index = 0; index < response.rawHeaders.length; index += 2) {
+                headers.append(response.rawHeaders[index], response.rawHeaders[index + 1]);
+            }
+            if (status >= 300 && status < 400) {
+                response.resume();
+                reject(new Error("Shell redirects are not followed."));
+                return;
+            }
+            const body = Readable.toWeb(response);
+            if (status === 204 || status === 205 || status === 304)
+                response.resume();
+            resolve(new Response(status === 204 || status === 205 || status === 304 ? null : body, { status, headers }));
+        });
+        request.on("error", reject);
+        request.end(init?.body);
+    });
+};

package/dist/startup.js

@@ -0,0 +1,27 @@
+import { parseArguments, run } from "./app.js";
+import { checkRelease, releaseNotice } from "./update.js";
+export async function runCli(args, dependencies = {}, signal, check = checkRelease) {
+    // No persistent cache: every executable invocation checks before dispatch.
+    let releaseCheck;
+    try {
+        releaseCheck = await check(signal);
+    }
+    catch {
+        releaseCheck = { status: "unavailable" };
+    }
+    if (releaseCheck.status === "available") {
+        let json = args.includes("--json");
+        try {
+            json = parseArguments(args).json;
+        }
+        catch {
+            /* Match usage errors. */
+        }
+        const { release } = releaseCheck;
+        const message = releaseNotice(release);
+        (dependencies.io?.stderr ?? process.stderr).write(json
+            ? `${JSON.stringify({ schema_version: 1, event: "update_available", version: release.version, published_at: release.publishedAt, available_date: release.date, update_command: "teamclaws update", message })}\n`
+            : `${message}\n`);
+    }
+    return run(args, { ...dependencies, releaseCheck }, signal);
+}

package/dist/storage.js

@@ -5,7 +5,7 @@ import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { TeamClawsError } from "./errors.js";
-import { normalizeUuid, parseLoginCredential, parseStatusWorkspaceCredential, parseWorkspaceCredential, } from "./validation.js";
+import { isObject, requireHttpsUrl, requireInteger, normalizeUuid, parseLoginCredential, parseStatusWorkspaceCredential, parseWorkspaceCredential, } from "./validation.js";
 const execFile = promisify(execFileCallback);
 const SYSTEM_SID = "S-1-5-18";
 const MAX_WORKSPACE_CREDENTIAL_FILES = 256;
@@ -91,6 +91,76 @@ export class CredentialStore {
                 throw storageError();
         });
     }
+    conversationDirectory(credential) {
+        return join(this.root, "chat-references", normalizeUuid(credential.server_id), normalizeUuid(credential.device_id));
+    }
+    async checkConversationDirectory(credential) {
+        const directory = this.conversationDirectory(credential);
+        for (const path of [
+            this.root,
+            join(this.root, "chat-references"),
+            dirname(directory),
+            directory,
+        ]) {
+            await this.assertPrivateDirectory(path);
+        }
+    }
+    async listConversations(credential) {
+        try {
+            const directory = this.conversationDirectory(credential);
+            try {
+                await this.checkConversationDirectory(credential);
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return [];
+                throw error;
+            }
+            const records = [];
+            for (const name of (await readdir(directory)).sort()) {
+                if (!UUID_CREDENTIAL_NAME.test(name))
+                    continue;
+                const path = join(directory, name);
+                // A single reference is small; reject unexpectedly large local files.
+                if ((await lstat(path)).size > 16_384)
+                    throw conversationStorageError();
+                const value = await this.readJsonIfPresent(path);
+                if (value === undefined)
+                    continue;
+                const record = parseConversationReference(value, credential);
+                if (name !== `${record.session_id}.json`)
+                    throw conversationStorageError();
+                records.push(record);
+            }
+            return records.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+        }
+        catch {
+            throw conversationStorageError();
+        }
+    }
+    async upsertConversation(credential, reference) {
+        try {
+            const record = parseConversationReference(reference, credential);
+            const directory = this.conversationDirectory(credential);
+            await this.ensurePrivateDirectory(directory);
+            const path = join(directory, `${record.session_id}.json`);
+            const existing = await this.readJsonIfPresent(path);
+            if (existing !== undefined) {
+                const prior = parseConversationReference(existing, credential);
+                if (prior.session_id !== record.session_id)
+                    throw conversationStorageError();
+                // Resuming an earlier cursor must not regress this request's saved progress.
+                if (prior.request_id === record.request_id) {
+                    record.revision = Math.max(prior.revision, record.revision);
+                    record.response_cursor = Math.max(prior.response_cursor, record.response_cursor);
+                }
+            }
+            await this.writePrivateJson(path, record);
+        }
+        catch {
+            throw conversationStorageError();
+        }
+    }
     async readJsonIfPresent(path) {
         try {
             await this.assertRegularPrivateFile(path);
@@ -254,6 +324,20 @@ async function verifyWindowsPath(path, knownUserSid) {
         throw storageError();
     }
 }
+let localAdministratorSid;
+function resolveLocalAdministratorSid() {
+    return (localAdministratorSid ??= execFile("powershell.exe", [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        "[Security.AccessControl.RawSecurityDescriptor]::new('D:(A;;FA;;;LA)').DiscretionaryAcl[0].SecurityIdentifier.Value",
+    ], { encoding: "utf8" }).then(({ stdout }) => {
+        const sid = stdout.trim();
+        if (!/^S-1-5-21-\d+-\d+-\d+-500$/u.test(sid))
+            throw storageError();
+        return sid;
+    }));
+}
 export function isPrivateWindowsAcl(acl, userSid) {
     const allowed = new Set([userSid, SYSTEM_SID]);
     return (acl.protected &&
@@ -266,14 +350,20 @@ async function readWindowsAcl(path) {
         await execFile("icacls.exe", [path, "/save", aclPath, "/c", "/q"]);
         const buffer = await readFile(aclPath);
         const text = decodeWindowsText(buffer);
-        return parseWindowsAclText(text);
+        const acl = parseWindowsAclText(text);
+        if (acl.trustees.includes("LA")) {
+            const administratorSid = await resolveLocalAdministratorSid();
+            acl.trustees = acl.trustees.map((sid) => sid === "LA" ? administratorSid : sid);
+        }
+        return acl;
     }
     finally {
         await rm(aclPath, { force: true }).catch(() => undefined);
     }
 }
 export function parseWindowsAclText(text) {
-    const descriptor = text.split(/\r?\n/u).find((line) => line.includes("D:")) ?? "";
+    const descriptor = text.split(/\r?\n/u).find((line) => /D:(?:P|AI|AR)*(?:\(|$)/u.test(line)) ??
+        "";
     const daclStart = descriptor.indexOf("D:");
     if (daclStart < 0)
         return { protected: false, trustees: [] };
@@ -282,7 +372,11 @@ export function parseWindowsAclText(text) {
     const dacl = descriptor.slice(daclBodyStart, saclStart < 0 ? undefined : saclStart);
     const firstAce = dacl.indexOf("(");
     const controlFlags = dacl.slice(0, firstAce < 0 ? undefined : firstAce);
-    const trustees = [...dacl.matchAll(/;;;([^;)]+)\)/gu)].map((match) => match[1] === "SY" ? SYSTEM_SID : (match[1] ?? ""));
+    const trustees = [...dacl.matchAll(/;;;([^;)]+)\)/gu)].map((match) => match[1] === "SY"
+        ? SYSTEM_SID
+        : match[1] === "BA"
+            ? "S-1-5-32-544"
+            : (match[1] ?? ""));
     return {
         protected: controlFlags.includes("P"),
         trustees: [...new Set(trustees)],
@@ -290,7 +384,7 @@ export function parseWindowsAclText(text) {
 }
 async function currentWindowsSid() {
     try {
-        const { stdout } = await execFile("whoami.exe", ["/user", "/fo", "csv", "/nh"], {
+        const { stdout } = await execFile(join(process.env.SystemRoot ?? "C:\\Windows", "System32", "whoami.exe"), ["/user", "/fo", "csv", "/nh"], {
             encoding: "utf8",
         });
         const match = stdout.match(/"(S-\d(?:-\d+)+)"/u);
@@ -321,4 +415,35 @@ export function decodeWindowsText(buffer) {
 function storageError() {
     return new TeamClawsError("credential_storage_failed", "TeamClaws could not protect the local credential file.", { exitCode: 9 });
 }
-//# sourceMappingURL=storage.js.map
+function parseConversationReference(value, credential) {
+    if (!isObject(value))
+        throw conversationStorageError();
+    const server = normalizeUuid(value.server_id);
+    const device = normalizeUuid(value.device_id);
+    const origin = requireHttpsUrl(value.origin, "workspace origin").origin;
+    const owner = requireHttpsUrl(value.owner_conversation_url, "conversation URL");
+    if (server !== normalizeUuid(credential.server_id) ||
+        device !== normalizeUuid(credential.device_id) ||
+        origin !== credential.origin ||
+        value.origin !== origin ||
+        owner.origin !== origin ||
+        !owner.pathname.startsWith("/teamclaws-admin/") ||
+        typeof value.updated_at !== "string" ||
+        !Number.isFinite(Date.parse(value.updated_at)) ||
+        new Date(value.updated_at).toISOString() !== value.updated_at)
+        throw conversationStorageError();
+    return {
+        server_id: server,
+        origin,
+        device_id: device,
+        session_id: normalizeUuid(value.session_id),
+        request_id: normalizeUuid(value.request_id),
+        owner_conversation_url: owner.toString(),
+        revision: requireInteger(value.revision, "revision", 1, 2 ** 31 - 1),
+        response_cursor: requireInteger(value.response_cursor, "response cursor", 0, Number.MAX_SAFE_INTEGER),
+        updated_at: value.updated_at,
+    };
+}
+function conversationStorageError() {
+    return new TeamClawsError("chat_reference_storage_failed", "The local conversation references could not be read or saved safely. Retain any returned session/request identifiers; do not resend the message automatically.", { exitCode: 9 });
+}

package/dist/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/update.js

@@ -0,0 +1,230 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { PACKAGE_NAME, PACKAGE_VERSION } from "./constants.js";
+export const OFFICIAL_REGISTRY = "https://registry.npmjs.org/";
+export const UPDATE_TIMEOUT_MS = 1500;
+const MAX_METADATA_BYTES = 2 * 1024 * 1024;
+// Strict SemVer syntax; arbitrary-size numeric components avoid rounding.
+function semver(value) {
+    if (typeof value !== "string" || value.length > 256)
+        return null;
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(value);
+    return match
+        ? { core: match.slice(1, 4).map(BigInt), prerelease: !!match[4] }
+        : null;
+}
+export function isNewerStable(version, current) {
+    const latest = semver(version);
+    const installed = semver(current);
+    if (!latest || latest.prerelease || !installed)
+        return false;
+    for (let index = 0; index < 3; index++) {
+        if (latest.core[index] !== installed.core[index])
+            return latest.core[index] > installed.core[index];
+    }
+    return installed.prerelease;
+}
+function object(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid metadata");
+    return value;
+}
+export function parseRelease(metadata, now = Date.now()) {
+    const packument = object(metadata);
+    const version = object(packument["dist-tags"]).latest;
+    const parsed = semver(version);
+    if (packument.name !== PACKAGE_NAME ||
+        typeof version !== "string" ||
+        !parsed ||
+        parsed.prerelease)
+        throw new Error("Invalid release");
+    const manifest = object(object(packument.versions)[version]);
+    const dist = object(manifest.dist);
+    const publishedAt = object(packument.time)[version];
+    if (manifest.name !== PACKAGE_NAME ||
+        manifest.version !== version ||
+        manifest.deprecated ||
+        dist.tarball !==
+            `${OFFICIAL_REGISTRY}teamclaws/-/teamclaws-${version}.tgz` ||
+        typeof dist.integrity !== "string" ||
+        !/^sha512-[A-Za-z0-9+/]{86}==$/.test(dist.integrity) ||
+        typeof publishedAt !== "string" ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(publishedAt))
+        throw new Error("Invalid published release");
+    const timestamp = Date.parse(publishedAt);
+    if (!Number.isFinite(timestamp) ||
+        new Date(timestamp).toISOString() !== publishedAt ||
+        timestamp > now)
+        throw new Error("Invalid publish time");
+    const [year, month, day] = publishedAt.slice(0, 10).split("-");
+    return { version, publishedAt, date: `${month}/${day}/${year}` };
+}
+export async function checkRelease(signal, fetcher = fetch, current = PACKAGE_VERSION) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted)
+        abort();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            abort();
+            reject(new Error("Registry deadline"));
+        }, UPDATE_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([
+            timeout,
+            (async () => {
+                const response = await fetcher(`${OFFICIAL_REGISTRY}${PACKAGE_NAME}`, {
+                    signal: controller.signal,
+                    redirect: "error",
+                    credentials: "omit",
+                    headers: { Accept: "application/json" },
+                });
+                if (!response.ok || !response.body)
+                    throw new Error("Registry unavailable");
+                const reader = response.body.getReader();
+                const chunks = [];
+                let size = 0;
+                try {
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        size += value.byteLength;
+                        if (size > MAX_METADATA_BYTES)
+                            throw new Error("Metadata too large");
+                        chunks.push(value);
+                    }
+                }
+                finally {
+                    void reader.cancel().catch(() => { });
+                }
+                const release = parseRelease(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+                return isNewerStable(release.version, current)
+                    ? { status: "available", release }
+                    : { status: "current" };
+            })(),
+        ]);
+    }
+    catch {
+        return { status: "unavailable" };
+    }
+    finally {
+        clearTimeout(timer);
+        abort();
+        signal?.removeEventListener("abort", abort);
+    }
+}
+export function releaseNotice(release) {
+    return `Version ${release.version} Available starting on ${release.date}. Use command teamclaws update to update as soon as possible.`;
+}
+const execute = promisify(execFile);
+// npm's JS entrypoint avoids cmd.exe interpolation and .cmd spawning on Windows.
+export async function npmRunner(nodeExecutable = process.execPath, platform = process.platform) {
+    const nodeDirectory = dirname(nodeExecutable);
+    const candidates = platform === "win32"
+        ? [join(nodeDirectory, "node_modules/npm/bin/npm-cli.js")]
+        : [
+            join(nodeDirectory, "npm"),
+            resolve(nodeDirectory, "../lib/node_modules/npm/bin/npm-cli.js"),
+        ];
+    for (const candidate of candidates) {
+        try {
+            const entry = await realpath(candidate);
+            const pkg = JSON.parse(await readFile(resolve(dirname(entry), "../package.json"), "utf8"));
+            if (pkg.name !== "npm" || basename(entry) !== "npm-cli.js")
+                continue;
+            return async (args, timeout, signal) => {
+                const env = { ...process.env };
+                for (const key of Object.keys(env)) {
+                    if (/^npm_config_/i.test(key) ||
+                        /^(NODE_OPTIONS|NODE_PATH)$/i.test(key))
+                        delete env[key];
+                }
+                // Distinct empty files avoid npm's rejection of loading the same file
+                // as both user and global configuration. Prefix discovery is read-only
+                // and retains user config; installation uses only the verified prefix.
+                const scratch = args[0] === "install"
+                    ? await mkdtemp(join(tmpdir(), "teamclaws-npm-"))
+                    : undefined;
+                try {
+                    const config = [];
+                    if (scratch) {
+                        for (const name of ["user", "global"]) {
+                            const path = join(scratch, `${name}.npmrc`);
+                            await writeFile(path, "");
+                            config.push(`--${name}config=${path}`);
+                        }
+                    }
+                    const { stdout } = await execute(nodeExecutable, [entry, ...config, ...args], {
+                        cwd: scratch ?? tmpdir(),
+                        env,
+                        timeout,
+                        maxBuffer: 1024 * 1024,
+                        windowsHide: true,
+                        ...(signal ? { signal } : {}),
+                    });
+                    return stdout;
+                }
+                finally {
+                    if (scratch)
+                        await rm(scratch, { recursive: true, force: true });
+                }
+            };
+        }
+        catch {
+            /* Try the other supported npm layout. */
+        }
+    }
+    throw new Error("npm is unavailable beside the running Node installation.");
+}
+export function installerArguments(version, prefix) {
+    if (!isAbsolute(prefix) || /[\r\n\0]/.test(prefix))
+        throw new Error("Invalid installation prefix");
+    if (!semver(version) || semver(version).prerelease)
+        throw new Error("Invalid update version");
+    return [
+        "install",
+        "--global",
+        `--prefix=${prefix}`,
+        `--registry=${OFFICIAL_REGISTRY}`,
+        "--ignore-scripts",
+        "--no-audit",
+        "--no-fund",
+        "--update-notifier=false",
+        "--",
+        `${PACKAGE_NAME}@${version}`,
+    ];
+}
+export async function installRelease(release, signal, runner, packageRoot = fileURLToPath(new URL("../", import.meta.url)), platform = process.platform) {
+    if (!isNewerStable(release.version, PACKAGE_VERSION))
+        throw new Error("Refusing an equal, older, or invalid release.");
+    const npm = runner ?? (await npmRunner());
+    const prefix = (await npm(["prefix", "--global"], 5000, signal)).trim();
+    // Verify the active package is the actual global package under npm's reported
+    // prefix. Source, npm link, local/npx, pnpm and mismatched npm installs fail.
+    if (!prefix ||
+        !/^(?:\/|[A-Za-z]:[\\/])/.test(prefix) ||
+        /[\r\n\0]/.test(prefix))
+        throw new Error("Invalid npm global prefix.");
+    const canonicalPrefix = await realpath(prefix);
+    const expected = platform === "win32"
+        ? join(canonicalPrefix, "node_modules", PACKAGE_NAME)
+        : join(canonicalPrefix, "lib/node_modules", PACKAGE_NAME);
+    const actual = await realpath(packageRoot);
+    if (actual !== resolve(expected) || (await realpath(expected)) !== actual)
+        throw new Error("Unsupported installation: teamclaws update requires the active npm global installation. Update local, linked, npx, or managed installations with their original package manager.");
+    const pkg = JSON.parse(await readFile(join(actual, "package.json"), "utf8"));
+    if (pkg.name !== PACKAGE_NAME || pkg.version !== PACKAGE_VERSION)
+        throw new Error("Active package identity does not match.");
+    await npm(installerArguments(release.version, prefix), 120000, signal);
+    const updated = JSON.parse(await readFile(join(actual, "package.json"), "utf8"));
+    if (updated.name !== PACKAGE_NAME || updated.version !== release.version)
+        throw new Error("npm finished but the installed version could not be verified.");
+}

package/dist/validation.js

@@ -336,7 +336,7 @@ export function parseServersResponse(value) {
             exitCode: 9,
         });
     }
-    assertExactKeys(value, ["servers"], [], "server list");
+    assertExactKeys(value, ["servers"], ["workspace_count"], "server list");
     if (!Array.isArray(value.servers)) {
         throw new TeamClawsError("invalid_response", "TeamClaws returned an invalid server list.", {
             exitCode: 9,
@@ -455,4 +455,12 @@ function requireIsoDate(value, label) {
 function invalidCredentialFile() {
     return new TeamClawsError("invalid_credential_file", "The local TeamClaws credential file is invalid.", { exitCode: 9 });
 }
-//# sourceMappingURL=validation.js.map
+export function parseWorkspaceInventory(value) {
+    const servers = parseServersResponse(value);
+    if (!isObject(value) || value.workspace_count === undefined)
+        return { servers };
+    return {
+        servers,
+        workspace_count: requireInteger(value.workspace_count, "workspace count", servers.length, Number.MAX_SAFE_INTEGER),
+    };
+}