commandmate 0.26.0 → 0.27.0

package/dist/cli/utils/api-client.js

@@ -214,6 +214,28 @@ class ApiClient {
         }
         return headers;
     }
+    /**
+     * GET without any status handling, for callers that must read the raw response.
+     *
+     * Issue #1925: the server-capability probe has to tell a real 404 (an older
+     * daemon that predates the endpoint) from a 302 to /login (this request never
+     * authenticated) and from an HTML body served by something in the middle.
+     * {@link get} collapses all three into an exception with a message, which is
+     * exactly the distinction the probe exists to make — so it issues its own
+     * request, with `redirect: 'manual'` so a redirect stays visible instead of
+     * being followed to a 200 that parses as nothing.
+     *
+     * @param path - Path appended to the client's base URL
+     * @param init - Extra request headers merged over the client's own
+     * @returns The raw Response, whatever its status
+     */
+    async rawGet(path, init) {
+        return fetch(`${this.baseUrl}${path}`, {
+            method: 'GET',
+            headers: { ...this.getHeaders(), ...(init?.headers ?? {}) },
+            redirect: 'manual',
+        });
+    }
     /**
      * HTTP GET request
      * [DR1-05] Generic type parameter specified at call site

package/dist/cli/utils/server-capabilities.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Server capability probe (Issue #1925, design §4 D5 決定 1 / §10.6 / DR4-007).
+ *
+ * The CLI is routinely newer than the server it talks to: `npm i -g commandmate`
+ * replaces the CLI without restarting a running daemon, and `api-responses.ts`
+ * says so in two places. So a CLI that starts depending on a new endpoint has to
+ * find out whether the server has it — and it cannot find that out from the
+ * endpoint's own 404, because Next.js answers an unimplemented App Router path
+ * with a bare 404 that is indistinguishable from "that worktree does not exist".
+ *
+ * The rule this module exists to enforce is the one that is easy to get wrong:
+ * **anything other than a real 404 is not permission to resolve locally.** The
+ * local path is a degraded resolver (design §4 D5 決定 1: it has no
+ * primary-anchor stage), so quietly falling back on a 302-to-/login or on an
+ * HTML error page from a reverse proxy would change where `send` and `respond`
+ * land — and would do it precisely when something in the middle of the
+ * connection is behaving unexpectedly. Those cases end the command instead.
+ */
+import { type ApiClient } from './api-client';
+/** Path of the capability endpoint (`src/app/api/capabilities/route.ts`). */
+export declare const CAPABILITIES_PATH = "/api/capabilities";
+/**
+ * Capability token declared by a server that can resolve session targets.
+ * Mirrors SERVER_CAPABILITIES in the route; the CLI keeps its own copy of API
+ * constants (see api-responses.ts) rather than importing across the boundary.
+ */
+export declare const RESOLVE_SESSION_TARGET_CAPABILITY = "resolve-session-target";
+/** Outcome of the probe. Auth failures and undeterminable servers throw instead. */
+export type ServerCapabilityProbe = {
+    kind: 'supported';
+    serverVersion: string;
+    capabilities: string[];
+}
+/** A real 404: this server predates `/api/capabilities`. */
+ | {
+    kind: 'legacy';
+};
+/**
+ * Ask the server what it supports, once per client.
+ *
+ * @param client - API client aimed at the server
+ * @returns Whether the server has the capability endpoint at all
+ * @throws ApiError on 401/403, and on any response that cannot be classified
+ */
+export declare function probeServerCapabilities(client: ApiClient): Promise<ServerCapabilityProbe>;
+/** Drop every memo. Exists for tests that reuse one client across scenarios. */
+export declare function resetServerCapabilityProbe(): void;
+/**
+ * Whether this server can resolve session targets for the CLI.
+ *
+ * @param client - API client aimed at the server
+ * @returns true when the server declares {@link RESOLVE_SESSION_TARGET_CAPABILITY}
+ * @throws ApiError on 401/403 and on an unclassifiable response
+ */
+export declare function serverResolvesSessionTargets(client: ApiClient): Promise<boolean>;
+//# sourceMappingURL=server-capabilities.d.ts.map

package/dist/cli/utils/server-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-capabilities.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/server-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAA4B,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAExE,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,2BAA2B,CAAC;AAE1E,oFAAoF;AACpF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE;AACtE,4DAA4D;GAC1D;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAyBvB;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAazF;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAmFD;;;;;;GAMG;AACH,wBAAsB,4BAA4B,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAItF"}

package/dist/cli/utils/server-capabilities.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Server capability probe (Issue #1925, design §4 D5 決定 1 / §10.6 / DR4-007).
+ *
+ * The CLI is routinely newer than the server it talks to: `npm i -g commandmate`
+ * replaces the CLI without restarting a running daemon, and `api-responses.ts`
+ * says so in two places. So a CLI that starts depending on a new endpoint has to
+ * find out whether the server has it — and it cannot find that out from the
+ * endpoint's own 404, because Next.js answers an unimplemented App Router path
+ * with a bare 404 that is indistinguishable from "that worktree does not exist".
+ *
+ * The rule this module exists to enforce is the one that is easy to get wrong:
+ * **anything other than a real 404 is not permission to resolve locally.** The
+ * local path is a degraded resolver (design §4 D5 決定 1: it has no
+ * primary-anchor stage), so quietly falling back on a 302-to-/login or on an
+ * HTML error page from a reverse proxy would change where `send` and `respond`
+ * land — and would do it precisely when something in the middle of the
+ * connection is behaving unexpectedly. Those cases end the command instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOLVE_SESSION_TARGET_CAPABILITY = exports.CAPABILITIES_PATH = void 0;
+exports.probeServerCapabilities = probeServerCapabilities;
+exports.resetServerCapabilityProbe = resetServerCapabilityProbe;
+exports.serverResolvesSessionTargets = serverResolvesSessionTargets;
+const types_1 = require("../types");
+const api_client_1 = require("./api-client");
+/** Path of the capability endpoint (`src/app/api/capabilities/route.ts`). */
+exports.CAPABILITIES_PATH = '/api/capabilities';
+/**
+ * Capability token declared by a server that can resolve session targets.
+ * Mirrors SERVER_CAPABILITIES in the route; the CLI keeps its own copy of API
+ * constants (see api-responses.ts) rather than importing across the boundary.
+ */
+exports.RESOLVE_SESSION_TARGET_CAPABILITY = 'resolve-session-target';
+/**
+ * Message for the responses that are neither "new server" nor "old server".
+ * Names the two things that actually produce them, because the operator's next
+ * move differs: authenticate, or stop routing the CLI through the proxy.
+ */
+const UNDETERMINED_MESSAGE = 'Could not determine the CommandMate server capabilities: the response to '
+    + `GET ${exports.CAPABILITIES_PATH} was not JSON. This usually means the request was not `
+    + 'authenticated (set CM_AUTH_TOKEN) or that something between the CLI and the '
+    + 'server answered instead of it. Refusing to guess which agent to target.';
+/**
+ * Memo, keyed by the client rather than by the module.
+ *
+ * Design §4 D5 asks for one probe per process, and a command builds one
+ * ApiClient and resolves every target through it, so per-client is per-process
+ * in practice. Keying it this way keeps the answer out of module scope, where
+ * it would leak between the many "processes" a test run packs into one — and a
+ * probe count that depends on which test ran first is not a thing worth
+ * debugging later.
+ */
+let probes = new WeakMap();
+/**
+ * Ask the server what it supports, once per client.
+ *
+ * @param client - API client aimed at the server
+ * @returns Whether the server has the capability endpoint at all
+ * @throws ApiError on 401/403, and on any response that cannot be classified
+ */
+function probeServerCapabilities(client) {
+    const existing = probes.get(client);
+    if (existing)
+        return existing;
+    const probe = runProbe(client).catch((error) => {
+        // A failed probe is not a fact about the server worth remembering: the
+        // command is about to end anyway, and a cached rejection would outlive the
+        // reason for it.
+        probes.delete(client);
+        throw error;
+    });
+    probes.set(client, probe);
+    return probe;
+}
+/** Drop every memo. Exists for tests that reuse one client across scenarios. */
+function resetServerCapabilityProbe() {
+    probes = new WeakMap();
+}
+function undetermined(status) {
+    return new api_client_1.ApiError(UNDETERMINED_MESSAGE, types_1.ExitCode.CONFIG_ERROR, status);
+}
+/**
+ * A 404 counts as "old server" only when the body is what a 404 from this app
+ * looks like: nothing, or JSON. An HTML 404 came from something else.
+ */
+function isRealNotFoundBody(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return true;
+    try {
+        JSON.parse(trimmed);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function runProbe(client) {
+    let response;
+    try {
+        response = await client.rawGet(exports.CAPABILITIES_PATH, { headers: { Accept: 'application/json' } });
+    }
+    catch (error) {
+        const result = (0, api_client_1.handleApiError)(error);
+        throw new api_client_1.ApiError(result.message, result.exitCode);
+    }
+    // Authentication failed. The server is fine; the request was not allowed to
+    // see the answer, and "not allowed" is not "old".
+    if (response.status === 401 || response.status === 403) {
+        const result = (0, api_client_1.handleApiError)(null, response.status);
+        throw new api_client_1.ApiError(result.message, result.exitCode, response.status);
+    }
+    // A redirect means middleware sent an unauthenticated browser-shaped request
+    // to /login. `/login` is in AUTH_EXCLUDED_PATHS, so following it would land on
+    // a 200 whose body is HTML — which is why the request was issued with
+    // `redirect: 'manual'` and why a 3xx ends the command here.
+    if ((response.status >= 300 && response.status < 400) || response.redirected) {
+        throw undetermined(response.status);
+    }
+    if (response.status === 404) {
+        const text = await response.text().catch(() => '');
+        if (isRealNotFoundBody(text))
+            return { kind: 'legacy' };
+        throw undetermined(response.status);
+    }
+    if (!response.ok) {
+        const result = (0, api_client_1.handleApiError)(null, response.status);
+        throw new api_client_1.ApiError(result.message, result.exitCode, response.status);
+    }
+    const contentType = response.headers?.get('content-type') ?? '';
+    if (!contentType.toLowerCase().includes('application/json')) {
+        throw undetermined(response.status);
+    }
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch {
+        throw undetermined(response.status);
+    }
+    if (parsed === null || typeof parsed !== 'object') {
+        throw undetermined(response.status);
+    }
+    const record = parsed;
+    if (!Array.isArray(record.capabilities)) {
+        throw undetermined(response.status);
+    }
+    return {
+        kind: 'supported',
+        serverVersion: typeof record.serverVersion === 'string' ? record.serverVersion : '',
+        capabilities: record.capabilities.filter((entry) => typeof entry === 'string'),
+    };
+}
+/**
+ * Whether this server can resolve session targets for the CLI.
+ *
+ * @param client - API client aimed at the server
+ * @returns true when the server declares {@link RESOLVE_SESSION_TARGET_CAPABILITY}
+ * @throws ApiError on 401/403 and on an unclassifiable response
+ */
+async function serverResolvesSessionTargets(client) {
+    const probe = await probeServerCapabilities(client);
+    return probe.kind === 'supported'
+        && probe.capabilities.includes(exports.RESOLVE_SESSION_TARGET_CAPABILITY);
+}

package/dist/cli/utils/session-target.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Thin client for the server's session-target resolution (Issue #1925,
+ * design §4 D5 決定 1 / §6.4).
+ *
+ * The CLI used to carry its own copy of the precedence rules. It was not the
+ * same copy: the server resolves an unregistered instance id that happens to
+ * name a CLI tool to that tool's primary instance (#868), and the CLI's copy had
+ * no such stage — it fell through to `--agent`, or to nothing. So the same
+ * `--instance codex` produced different tmux session names depending on which
+ * side answered. The fix is not to make the copies agree (they cannot: the CLI
+ * build sets `paths: {}` and cannot import the server resolver); it is to stop
+ * having two answers. The server decides; this module asks.
+ *
+ * The old two-stage local resolution survives as one thing only: the
+ * compatibility path for a daemon older than the endpoint, reported as
+ * `resolvedBy: 'client-fallback'` with a warning on stderr. It is deliberately
+ * NOT kept in step with the server — adding the primary-anchor stage to it would
+ * be growing the second authority back (DR2-008).
+ */
+import type { ApiClient } from './api-client';
+/**
+ * Which stage of the precedence chain produced the answer. Mirrors
+ * SessionTargetResolvedBy in `src/lib/session/resolve-session-target.ts`; the
+ * CLI keeps its own copy of API shapes (see api-responses.ts).
+ */
+export type SessionTargetResolvedBy = 'explicit' | 'roster' | 'primary' | 'worktree-default' | 'fallback' | 'client-fallback';
+/** An explicit `--agent` that the roster contradicts. */
+export interface SessionTargetConflict {
+    instanceId: string;
+    rosterCliTool: string;
+    requestedCliTool: string;
+}
+export interface CliSessionTarget {
+    /**
+     * The agent to address, or undefined when nothing declared one.
+     *
+     * Undefined only reaches a caller on the `client-fallback` path: the server
+     * always answers with a concrete tool, and an old server keeps the behavior it
+     * always had, which is to decide for itself when the CLI sends no `cliToolId`.
+     */
+    cliToolId: string | undefined;
+    /** The instance addressed, echoed back so callers do not re-derive it. */
+    instanceId: string | undefined;
+    resolvedBy: SessionTargetResolvedBy;
+    /** The contradiction, when there is one. Callers decide whether it is fatal. */
+    conflict: SessionTargetConflict | null;
+}
+export interface ResolveSessionTargetOptions {
+    instanceId?: string;
+    /** The `--agent` / `--cli-tool` value, already validated as a known tool id. */
+    requestedCliTool?: string;
+}
+/**
+ * Resolve which agent and instance a command should address.
+ *
+ * @param client - API client aimed at the server
+ * @param worktreeId - Worktree ID
+ * @param options - `--instance` and `--agent` as the user gave them
+ * @returns The resolved target, with `conflict` set when `--agent` contradicts the roster
+ * @throws ApiError when the server's capabilities cannot be determined (auth
+ *   failure, redirect, non-JSON body) — those are never treated as "old server"
+ */
+export declare function resolveSessionTarget(client: ApiClient, worktreeId: string, options?: ResolveSessionTargetOptions): Promise<CliSessionTarget>;
+/**
+ * The sentence shown when the roster and `--agent` disagree. Names both
+ * declarations and the three ways out, because only the operator knows which of
+ * the two is wrong.
+ */
+export declare function describeSessionTargetConflict(conflict: SessionTargetConflict): string;
+//# sourceMappingURL=session-target.d.ts.map

package/dist/cli/utils/session-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-target.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/session-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAK9C;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAC/B,UAAU,GACV,QAAQ,GACR,SAAS,GACT,kBAAkB,GAClB,UAAU,GACV,iBAAiB,CAAC;AAEtB,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,EAAE,uBAAuB,CAAC;IACpC,gFAAgF;IAChF,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,2BAA2B;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAuBD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AA6ED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAMrF"}

package/dist/cli/utils/session-target.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Thin client for the server's session-target resolution (Issue #1925,
+ * design §4 D5 決定 1 / §6.4).
+ *
+ * The CLI used to carry its own copy of the precedence rules. It was not the
+ * same copy: the server resolves an unregistered instance id that happens to
+ * name a CLI tool to that tool's primary instance (#868), and the CLI's copy had
+ * no such stage — it fell through to `--agent`, or to nothing. So the same
+ * `--instance codex` produced different tmux session names depending on which
+ * side answered. The fix is not to make the copies agree (they cannot: the CLI
+ * build sets `paths: {}` and cannot import the server resolver); it is to stop
+ * having two answers. The server decides; this module asks.
+ *
+ * The old two-stage local resolution survives as one thing only: the
+ * compatibility path for a daemon older than the endpoint, reported as
+ * `resolvedBy: 'client-fallback'` with a warning on stderr. It is deliberately
+ * NOT kept in step with the server — adding the primary-anchor stage to it would
+ * be growing the second authority back (DR2-008).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSessionTarget = resolveSessionTarget;
+exports.describeSessionTargetConflict = describeSessionTargetConflict;
+const types_1 = require("../types");
+const agent_instances_1 = require("./agent-instances");
+const server_capabilities_1 = require("./server-capabilities");
+/**
+ * The one line of stderr a degraded resolution owes the operator (design §10.6
+ * item 6). Printed once per resolution rather than once per process on purpose:
+ * a command that resolves two targets against an old server degraded twice.
+ */
+function warnClientFallback() {
+    console.error('Warning: this CommandMate server is older than the CLI and cannot resolve agent instances; '
+        + 'resolving locally (resolvedBy: client-fallback). Restart the server to pick up the current '
+        + 'version: commandmate stop && commandmate start');
+}
+/**
+ * Resolve which agent and instance a command should address.
+ *
+ * @param client - API client aimed at the server
+ * @param worktreeId - Worktree ID
+ * @param options - `--instance` and `--agent` as the user gave them
+ * @returns The resolved target, with `conflict` set when `--agent` contradicts the roster
+ * @throws ApiError when the server's capabilities cannot be determined (auth
+ *   failure, redirect, non-JSON body) — those are never treated as "old server"
+ */
+async function resolveSessionTarget(client, worktreeId, options = {}) {
+    if (await (0, server_capabilities_1.serverResolvesSessionTargets)(client)) {
+        return resolveViaServer(client, worktreeId, options);
+    }
+    warnClientFallback();
+    return resolveLocally(client, worktreeId, options);
+}
+async function resolveViaServer(client, worktreeId, options) {
+    const query = new URLSearchParams();
+    if (options.instanceId)
+        query.set('instance', options.instanceId);
+    if (options.requestedCliTool)
+        query.set('cliTool', options.requestedCliTool);
+    const qs = query.toString();
+    const response = await client.get(`/api/worktrees/${worktreeId}/resolve-target${qs ? `?${qs}` : ''}`);
+    return {
+        cliToolId: response.cliToolId,
+        instanceId: response.instanceId,
+        resolvedBy: response.resolvedBy,
+        conflict: response.conflict ?? null,
+    };
+}
+/**
+ * Compatibility resolution for a server that predates the endpoint.
+ *
+ * Two stages, exactly as before: the roster entry, then `--agent`. No
+ * primary-anchor stage and no worktree-default read — an old server applies
+ * those itself when the CLI sends no `cliToolId`, and reimplementing them here
+ * is how the second authority grew in the first place (DR2-008).
+ */
+async function resolveLocally(client, worktreeId, options) {
+    const { instanceId, requestedCliTool } = options;
+    const degraded = (cliToolId, conflict = null) => ({
+        cliToolId,
+        instanceId,
+        resolvedBy: 'client-fallback',
+        conflict,
+    });
+    if (!instanceId) {
+        return degraded(requestedCliTool);
+    }
+    let registered;
+    try {
+        const instances = await (0, agent_instances_1.fetchAgentInstances)(client, worktreeId);
+        registered = instances.find((inst) => inst.id === instanceId);
+    }
+    catch (error) {
+        console.error(`Warning: could not read the agent-instance roster (${(0, types_1.getErrorMessage)(error)}); using --agent as given.`);
+        return degraded(requestedCliTool);
+    }
+    if (!registered) {
+        return degraded(requestedCliTool);
+    }
+    if (requestedCliTool && requestedCliTool !== registered.cliTool) {
+        return degraded(registered.cliTool, {
+            instanceId,
+            rosterCliTool: registered.cliTool,
+            requestedCliTool,
+        });
+    }
+    return degraded(registered.cliTool);
+}
+/**
+ * The sentence shown when the roster and `--agent` disagree. Names both
+ * declarations and the three ways out, because only the operator knows which of
+ * the two is wrong.
+ */
+function describeSessionTargetConflict(conflict) {
+    return (`instance '${conflict.instanceId}' is registered as ${conflict.rosterCliTool}, `
+        + `but --agent ${conflict.requestedCliTool} was given. `
+        + `Drop --agent, pass --agent ${conflict.rosterCliTool}, or re-register the instance.`);
+}

package/dist/lib/cli-tools/copilot-executable.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Where GitHub Copilot CLI actually is, and whether it is actually there
+ * (Issue #1907).
+ *
+ * ## Why this is not `gh copilot --help`
+ *
+ * `CopilotTool.isInstalled()` used to answer "is copilot installed?" with
+ * `gh --version` followed by `gh copilot --help`. Measured on gh 2.86.0 with an
+ * empty `gh extension list`, the second command exits 0 in ~20 ms on a machine
+ * where the extension does not exist, because `copilot` is no longer an
+ * extension at all -- it is a preview command built into `gh`, and the help text
+ * it prints says so itself:
+ *
+ * > If already installed, `gh` will execute the Copilot CLI found in your
+ * > `PATH`. If the Copilot CLI is not installed, it will be downloaded to
+ * > ~/.local/share/gh/copilot.
+ *
+ * So the old check proved that `gh` was installed and nothing more. The
+ * consequence was not a wrong badge: `startSession` typed `gh copilot` into the
+ * pane, gh started *downloading* copilot there, `waitForReady` spun its whole
+ * window against a progress bar, and the launch was logged as a success.
+ *
+ * This module answers the question with positive evidence instead (方針書 §4
+ * D1): an executable file that exists, and a `--version` that exits 0 and prints
+ * a version. Nothing here infers presence from the absence of an error.
+ *
+ * ## Why the path is resolved before it is run
+ *
+ * `copilot` is a common word and the probe runs with the server's privileges, so
+ * the candidate is resolved out of `PATH` to an absolute path first, checked to
+ * be an executable *file*, and only then handed to `execFile` with a bounded
+ * timeout, a bounded `maxBuffer` and `sanitizeEnvForChildProcess()`. This is the
+ * rule 方針書 §10.11 / DR4-010 states for version probes; it applies here for the
+ * same reason, since this is the probe that decides what gets launched.
+ *
+ * @module lib/cli-tools/copilot-executable
+ */
+/**
+ * How a resolved copilot was found.
+ *
+ * - `path` — a `copilot` executable on the server's `PATH`. The normal case for
+ *   `brew install copilot-cli` and `npm i -g @github/copilot`.
+ * - `gh-managed` — the copy `gh copilot` downloads for itself when `PATH` has
+ *   none. It is not on `PATH` by design, so it is launched back through
+ *   `gh copilot`; gh runs exactly this file, because gh prefers `PATH` and we
+ *   only get here when `PATH` has nothing.
+ */
+export type CopilotExecutableSource = 'path' | 'gh-managed';
+/** A copilot that was found AND answered `--version`. */
+export interface CopilotExecutable {
+    /** Absolute path of the file that answered. */
+    readonly path: string;
+    /** Version it reported, e.g. `1.0.80`. */
+    readonly version: string;
+    /** Which of the two locations it came from. */
+    readonly source: CopilotExecutableSource;
+}
+/** Budget for one `--version` call. Matches the old two-stage check's per-stage timeout. */
+export declare const COPILOT_VERSION_PROBE_TIMEOUT_MS = 5000;
+/**
+ * First executable named `name` on `PATH`, as an absolute path.
+ *
+ * Exported since Issue #1929: `DETECTOR_VERSION_PROBES` has to resolve every
+ * probe command the same way before executing it (DR4-010 (2)), and a second
+ * copy of this walk is exactly the "two probe mechanisms with different trust
+ * models" DR4-010 exists to prevent. The name stays generic because the walk
+ * is; what is copilot-specific is the caller below.
+ */
+export declare function findExecutableOnPath(name: string): string | null;
+/**
+ * The copilot this machine would actually run, or null when there is none.
+ *
+ * `PATH` first, gh's managed copy second — the order the operator experiences,
+ * and the order gh itself uses. Never throws: an unreadable directory, a missing
+ * `PATH`, a probe that times out are all "no evidence", which is the answer that
+ * makes `startSession` refuse instead of starting a download in the pane.
+ */
+export declare function resolveCopilotExecutable(): Promise<CopilotExecutable | null>;
+//# sourceMappingURL=copilot-executable.d.ts.map

package/dist/lib/cli-tools/copilot-executable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copilot-executable.d.ts","sourceRoot":"","sources":["../../../src/lib/cli-tools/copilot-executable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAQH;;;;;;;;;GASG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,YAAY,CAAC;AAE5D,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;CAC1C;AAQD,4FAA4F;AAC5F,eAAO,MAAM,gCAAgC,OAAO,CAAC;AAyBrD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAShE;AAuCD;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAiBlF"}