wicked-crew 0.7.6 → 0.7.8

package/dist/api/diagnostics.d.ts

@@ -0,0 +1,143 @@
+/**
+ * GET /api/v1/diagnostics — the daemon's self-knowledge surface.
+ *
+ * The operator question this answers is "is ACP really working across the CLIs, and what is this
+ * daemon actually running?" — an answer that previously lived only in raw NDJSON under
+ * `<state-home>/core.db.events/` and in whatever `--version` the operator remembered to run.
+ * Everything here is READ-ONLY and derived from records the daemon already owns:
+ *
+ *   - component versions (crew's package.json; the bundled studio's shipped manifest; the
+ *     installed wicked-core-ts; engine binaries crew already knows how to invoke)
+ *   - store files with sizes (core.db + its sidecars, the durable events dir as a total)
+ *   - a bounded tail of the daemon's own error-level log lines (an in-process ring — see
+ *     {@link ErrorRing}; empty on a daemon that has logged no errors, never invented)
+ *   - the ACP fold: acpSessionStarted / acpFallback per cliKey from the durable run event logs
+ *
+ * The honesty rule is the wire contract's: a field the daemon cannot answer is `null` (or an
+ * empty collection) — NEVER fabricated. A missing studio bundle is `null`, an unprobeable
+ * binary is `null`, a machine with no event logs folds to `{}`.
+ */
+/** Per-CLI ACP health, folded from the durable run event logs. Mirrors the wire contract's
+ *  `AcpCliDiagnostics` (wicked-crew-api-types). */
+export interface AcpCliFold {
+    sessionsStarted: number;
+    fallbacks: number;
+    fallbackKinds: Record<string, number>;
+    lastStartedTs: number | null;
+    lastFallbackTs: number | null;
+}
+/**
+ * Fold `acpSessionStarted` / `acpFallback` events per cliKey from `<dir>/*.ndjson`.
+ *
+ * Stream-parsed (readline over a file stream — never a whole-file read into memory), with a
+ * cheap substring pre-filter so the JSON parser only ever runs on candidate lines. A missing
+ * dir, an unreadable file, or a malformed line each degrade to "contributes nothing" — the
+ * fold is a diagnosis surface and must not itself become a failure mode.
+ */
+export declare function foldAcpEvents(eventsDir: string): Promise<Record<string, AcpCliFold>>;
+/**
+ * A short-TTL, in-flight-deduplicated cache around {@link foldAcpEvents}. The events dir holds
+ * one file per run (139+ observed), so the fold is real IO — briefly caching keeps a dashboard
+ * polling /diagnostics from turning the daemon into an NDJSON re-reader, while the TTL keeps
+ * the answer honest to within seconds.
+ */
+export declare class AcpFoldCache {
+    private readonly ttlMs;
+    private value;
+    private inFlight;
+    constructor(ttlMs?: number);
+    get(eventsDir: string): Promise<Record<string, AcpCliFold>>;
+}
+/** One captured error-level log line — the wire contract's `DiagnosticsRecentError`. */
+export interface RecentError {
+    ts: number;
+    source: string;
+    line: string;
+}
+/**
+ * A bounded ring of the daemon's own error-level log lines.
+ *
+ * Crew has no persistent log file of its own (pino writes to stdout; `daemon-stdout.log` under
+ * the state home belongs to whatever launched the daemon) — so the "recent errors" record is
+ * an IN-PROCESS ring fed by a tee on the pino stream ({@link teeStreamWithErrorRing}). Empty
+ * on a fresh or healthy daemon; capped so it can never grow with uptime.
+ */
+export declare class ErrorRing {
+    private readonly cap;
+    private readonly entries;
+    constructor(cap?: number);
+    push(entry: RecentError): void;
+    /** Newest first — the wire order. */
+    list(): RecentError[];
+}
+/**
+ * A pino destination that forwards every line to `out` (stdout in the daemon) and folds
+ * error-level lines into `ring`. Passed to Fastify as `logger.stream`, so the ring sees
+ * exactly what the daemon logs — no second logging channel to keep in step.
+ *
+ * The parse is guarded end-to-end: a log line that fails to parse as pino JSON still ships to
+ * `out` verbatim, and a throw in the ring can never break logging (which would turn the
+ * diagnosis surface into an outage).
+ */
+export declare function teeStreamWithErrorRing(ring: ErrorRing, out?: {
+    write(chunk: string): unknown;
+}): {
+    write(chunk: string): void;
+};
+/**
+ * The bundled studio's version, read from the manifest the bundle ALREADY ships:
+ * `testid-inventory.json` carries `studioVersion` (a versioned build artifact, TH-13). No
+ * bundle — a headless daemon — is `null`, and so is a bundle predating the inventory.
+ */
+export declare function readStudioBundleVersion(studioRoot: string): string | null;
+/**
+ * The installed version of a dependency, or `null`. Walks the resolver's candidate dirs and
+ * reads package.json with fs — the same sidestep `apiTypesVersion()` uses, because a
+ * types-only exports map (wicked-core-ts included) refuses `require.resolve` on the package
+ * root and on `/package.json` alike.
+ */
+export declare function installedPackageVersion(name: string): string | null;
+/** First semver-looking token of a `--version` output, else the trimmed first line, else null. */
+export declare function parseVersionOutput(stdout: string): string | null;
+type ExecLike = (file: string, args: string[], opts?: {
+    timeout?: number;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * `--version` of the engine binaries crew ALREADY knows how to invoke — never a new path
+ * resolution invented for diagnostics:
+ *
+ *   - `wicked-core`: the standalone engine binary the adapter resolves at construction for the
+ *     gate-hook command and publishes as `WICKED_CORE_EXE`. Env unset = crew never resolved
+ *     one = `null`.
+ *   - `wicked-estate`: invoked by bare name on PATH, exactly as the graph-view/blast-radius
+ *     routes do. Not on PATH = `null`.
+ *
+ * Under a test runner the probes are SKIPPED (both `null`) unless an exec is injected — the
+ * seat-health-probe posture: a test-built server never spawns CLI children by default.
+ */
+export declare function engineBinaryVersions(exec?: ExecLike): Promise<Record<string, string | null>>;
+/** Version probes answer the same for the life of a process — cache the first answer. */
+export declare class EngineVersionCache {
+    private value;
+    private inFlight;
+    get(exec?: ExecLike): Promise<Record<string, string | null>>;
+}
+/** One store file (or dir, sized as a total) — the wire contract's `DiagnosticsStoreFile`. */
+export interface StoreFileEntry {
+    name: string;
+    path: string;
+    bytes: number;
+}
+/**
+ * `core.db` and every sidecar sharing its basename (`core.db-wal`, `core.db.knowledge`,
+ * `core.db.mem*`, …), plus the events dir (`core.db.events`) sized as a TOTAL of its
+ * contents. Paths and sizes only — no file contents ever ride this wire.
+ */
+export declare function listStoreFiles(dbPath: string): Promise<StoreFileEntry[]>;
+/** Where a core db's durable run event logs live — the engine's `<db>.events/` convention. */
+export declare function eventsDirOf(dbPath: string): string;
+export {};
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/api/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/api/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/api/diagnostics.js

@@ -0,0 +1,417 @@
+/**
+ * GET /api/v1/diagnostics — the daemon's self-knowledge surface.
+ *
+ * The operator question this answers is "is ACP really working across the CLIs, and what is this
+ * daemon actually running?" — an answer that previously lived only in raw NDJSON under
+ * `<state-home>/core.db.events/` and in whatever `--version` the operator remembered to run.
+ * Everything here is READ-ONLY and derived from records the daemon already owns:
+ *
+ *   - component versions (crew's package.json; the bundled studio's shipped manifest; the
+ *     installed wicked-core-ts; engine binaries crew already knows how to invoke)
+ *   - store files with sizes (core.db + its sidecars, the durable events dir as a total)
+ *   - a bounded tail of the daemon's own error-level log lines (an in-process ring — see
+ *     {@link ErrorRing}; empty on a daemon that has logged no errors, never invented)
+ *   - the ACP fold: acpSessionStarted / acpFallback per cliKey from the durable run event logs
+ *
+ * The honesty rule is the wire contract's: a field the daemon cannot answer is `null` (or an
+ * empty collection) — NEVER fabricated. A missing studio bundle is `null`, an unprobeable
+ * binary is `null`, a machine with no event logs folds to `{}`.
+ */
+import { createReadStream, existsSync, readFileSync } from 'node:fs';
+import { promises as fsp } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { execCapped } from '../core/exec.js';
+/** Bounds on the fold's work — the events dir grows one file per run forever, and this fold
+ *  runs inside a request handler, so both dimensions are capped. At the caps this is still
+ *  hundreds of runs' worth of history; past them the answer is the bounded subset (newest
+ *  files first), which stays honest for "is ACP working" — the recent record is what matters. */
+const ACP_FOLD_MAX_FILES = 512;
+const ACP_FOLD_MAX_LINE_BYTES = 1024 * 1024;
+/**
+ * Fold `acpSessionStarted` / `acpFallback` events per cliKey from `<dir>/*.ndjson`.
+ *
+ * Stream-parsed (readline over a file stream — never a whole-file read into memory), with a
+ * cheap substring pre-filter so the JSON parser only ever runs on candidate lines. A missing
+ * dir, an unreadable file, or a malformed line each degrade to "contributes nothing" — the
+ * fold is a diagnosis surface and must not itself become a failure mode.
+ */
+export async function foldAcpEvents(eventsDir) {
+    const byCli = {};
+    let names;
+    try {
+        names = await fsp.readdir(eventsDir);
+    }
+    catch {
+        return byCli; // no events dir yet — nothing recorded, honestly empty
+    }
+    let files = names.filter((n) => n.endsWith('.ndjson'));
+    if (files.length > ACP_FOLD_MAX_FILES) {
+        // Newest runs first when the cap bites: mtime is one stat per file, paid only past the cap.
+        const stamped = await Promise.all(files.map(async (n) => {
+            try {
+                const st = await fsp.stat(join(eventsDir, n));
+                return { n, mtime: st.mtimeMs };
+            }
+            catch {
+                return { n, mtime: 0 };
+            }
+        }));
+        files = stamped
+            .sort((a, b) => b.mtime - a.mtime)
+            .slice(0, ACP_FOLD_MAX_FILES)
+            .map((s) => s.n);
+    }
+    for (const name of files) {
+        await foldOneFile(join(eventsDir, name), byCli);
+    }
+    return byCli;
+}
+function entryFor(byCli, cliKey) {
+    let e = byCli[cliKey];
+    if (e === undefined) {
+        e = {
+            sessionsStarted: 0,
+            fallbacks: 0,
+            fallbackKinds: {},
+            lastStartedTs: null,
+            lastFallbackTs: null,
+        };
+        byCli[cliKey] = e;
+    }
+    return e;
+}
+async function foldOneFile(path, byCli) {
+    let rl;
+    let stream;
+    try {
+        stream = createReadStream(path, { encoding: 'utf8' });
+        rl = createInterface({ input: stream, crlfDelay: Infinity });
+    }
+    catch {
+        return; // unreadable file contributes nothing
+    }
+    try {
+        for await (const line of rl) {
+            // Substring pre-filter: almost every line in a run log is NOT an ACP event, and
+            // JSON.parse on megabytes of narration is exactly the stall this fold must not cause.
+            const isStart = line.includes('"acpSessionStarted"');
+            const isFallback = !isStart && line.includes('"acpFallback"');
+            if (!isStart && !isFallback)
+                continue;
+            if (line.length > ACP_FOLD_MAX_LINE_BYTES)
+                continue; // pathological line — skip, don't parse
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue; // torn tail line of a crashed run — not this surface's problem
+            }
+            if (typeof event.cliKey !== 'string')
+                continue;
+            const ts = typeof event.ts === 'number' ? event.ts : null;
+            if (event.type === 'acpSessionStarted') {
+                const e = entryFor(byCli, event.cliKey);
+                e.sessionsStarted += 1;
+                if (ts !== null && (e.lastStartedTs === null || ts > e.lastStartedTs)) {
+                    e.lastStartedTs = ts;
+                }
+            }
+            else if (event.type === 'acpFallback') {
+                const e = entryFor(byCli, event.cliKey);
+                e.fallbacks += 1;
+                const kind = typeof event.fallbackKind === 'string' ? event.fallbackKind : 'unknown';
+                e.fallbackKinds[kind] = (e.fallbackKinds[kind] ?? 0) + 1;
+                if (ts !== null && (e.lastFallbackTs === null || ts > e.lastFallbackTs)) {
+                    e.lastFallbackTs = ts;
+                }
+            }
+        }
+    }
+    catch {
+        // A read error mid-stream (file rotated away, disk hiccup): keep what folded so far.
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+}
+/**
+ * A short-TTL, in-flight-deduplicated cache around {@link foldAcpEvents}. The events dir holds
+ * one file per run (139+ observed), so the fold is real IO — briefly caching keeps a dashboard
+ * polling /diagnostics from turning the daemon into an NDJSON re-reader, while the TTL keeps
+ * the answer honest to within seconds.
+ */
+export class AcpFoldCache {
+    ttlMs;
+    value = null;
+    inFlight = null;
+    constructor(ttlMs = 15_000) {
+        this.ttlMs = ttlMs;
+    }
+    async get(eventsDir) {
+        const now = Date.now();
+        if (this.value !== null && now - this.value.at < this.ttlMs)
+            return this.value.byCli;
+        if (this.inFlight !== null)
+            return this.inFlight;
+        this.inFlight = foldAcpEvents(eventsDir)
+            .then((byCli) => {
+            this.value = { at: Date.now(), byCli };
+            return byCli;
+        })
+            .finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+}
+/** Keep captured lines readable, not exhaustive: the tail is a diagnosis pointer, the full
+ *  narrative stays wherever the operator ships the daemon's stdout. */
+const RING_LINE_MAX_CHARS = 2000;
+/**
+ * A bounded ring of the daemon's own error-level log lines.
+ *
+ * Crew has no persistent log file of its own (pino writes to stdout; `daemon-stdout.log` under
+ * the state home belongs to whatever launched the daemon) — so the "recent errors" record is
+ * an IN-PROCESS ring fed by a tee on the pino stream ({@link teeStreamWithErrorRing}). Empty
+ * on a fresh or healthy daemon; capped so it can never grow with uptime.
+ */
+export class ErrorRing {
+    cap;
+    entries = [];
+    constructor(cap = 20) {
+        this.cap = cap;
+    }
+    push(entry) {
+        const line = entry.line.length > RING_LINE_MAX_CHARS
+            ? `${entry.line.slice(0, RING_LINE_MAX_CHARS)}…`
+            : entry.line;
+        this.entries.push({ ...entry, line });
+        if (this.entries.length > this.cap)
+            this.entries.shift();
+    }
+    /** Newest first — the wire order. */
+    list() {
+        return [...this.entries].reverse();
+    }
+}
+/** Pino numeric levels: 50 = error, 60 = fatal. Anything below stays out of the ring. */
+const PINO_ERROR_LEVEL = 50;
+/**
+ * A pino destination that forwards every line to `out` (stdout in the daemon) and folds
+ * error-level lines into `ring`. Passed to Fastify as `logger.stream`, so the ring sees
+ * exactly what the daemon logs — no second logging channel to keep in step.
+ *
+ * The parse is guarded end-to-end: a log line that fails to parse as pino JSON still ships to
+ * `out` verbatim, and a throw in the ring can never break logging (which would turn the
+ * diagnosis surface into an outage).
+ */
+export function teeStreamWithErrorRing(ring, out = process.stdout) {
+    return {
+        write(chunk) {
+            try {
+                out.write(chunk);
+            }
+            catch {
+                /* a broken stdout must not also kill the ring */
+            }
+            try {
+                // Cheap pre-filter before JSON.parse — most lines are info/debug.
+                if (!/"level":\s*(50|60)\b/.test(chunk))
+                    return;
+                for (const line of chunk.split('\n')) {
+                    if (line === '')
+                        continue;
+                    const parsed = JSON.parse(line);
+                    const level = typeof parsed.level === 'number' ? parsed.level : 0;
+                    if (level < PINO_ERROR_LEVEL)
+                        continue;
+                    ring.push({
+                        ts: typeof parsed.time === 'number' ? parsed.time : Date.now(),
+                        source: 'daemon',
+                        line: typeof parsed.msg === 'string' ? parsed.msg : line,
+                    });
+                }
+            }
+            catch {
+                /* an unparseable line is not an error record — skip it */
+            }
+        },
+    };
+}
+// ── Component versions ───────────────────────────────────────────────────────
+/**
+ * The bundled studio's version, read from the manifest the bundle ALREADY ships:
+ * `testid-inventory.json` carries `studioVersion` (a versioned build artifact, TH-13). No
+ * bundle — a headless daemon — is `null`, and so is a bundle predating the inventory.
+ */
+export function readStudioBundleVersion(studioRoot) {
+    try {
+        const raw = readFileSync(join(studioRoot, 'testid-inventory.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.studioVersion === 'string' ? parsed.studioVersion : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The installed version of a dependency, or `null`. Walks the resolver's candidate dirs and
+ * reads package.json with fs — the same sidestep `apiTypesVersion()` uses, because a
+ * types-only exports map (wicked-core-ts included) refuses `require.resolve` on the package
+ * root and on `/package.json` alike.
+ */
+export function installedPackageVersion(name) {
+    try {
+        const require = createRequire(import.meta.url);
+        for (const dir of require.resolve.paths(name) ?? []) {
+            const pkgPath = join(dir, name, 'package.json');
+            if (existsSync(pkgPath)) {
+                const version = JSON.parse(readFileSync(pkgPath, 'utf8'))
+                    .version;
+                return typeof version === 'string' ? version : null;
+            }
+        }
+    }
+    catch {
+        /* fall through to null */
+    }
+    return null;
+}
+/** First semver-looking token of a `--version` output, else the trimmed first line, else null. */
+export function parseVersionOutput(stdout) {
+    const firstLine = stdout.split('\n', 1)[0]?.trim() ?? '';
+    if (firstLine === '')
+        return null;
+    const semver = firstLine.match(/\d+\.\d+\.\d+[^\s]*/);
+    return semver !== null ? semver[0] : firstLine;
+}
+/**
+ * `--version` of the engine binaries crew ALREADY knows how to invoke — never a new path
+ * resolution invented for diagnostics:
+ *
+ *   - `wicked-core`: the standalone engine binary the adapter resolves at construction for the
+ *     gate-hook command and publishes as `WICKED_CORE_EXE`. Env unset = crew never resolved
+ *     one = `null`.
+ *   - `wicked-estate`: invoked by bare name on PATH, exactly as the graph-view/blast-radius
+ *     routes do. Not on PATH = `null`.
+ *
+ * Under a test runner the probes are SKIPPED (both `null`) unless an exec is injected — the
+ * seat-health-probe posture: a test-built server never spawns CLI children by default.
+ */
+export async function engineBinaryVersions(exec) {
+    const underTestRunner = process.env['VITEST'] !== undefined || process.env['NODE_ENV'] === 'test';
+    if (exec === undefined && underTestRunner) {
+        return { 'wicked-core': null, 'wicked-estate': null };
+    }
+    const run = exec ?? execCapped;
+    const probe = async (file) => {
+        try {
+            const { stdout } = await run(file, ['--version'], { timeout: 5_000 });
+            return parseVersionOutput(stdout);
+        }
+        catch {
+            return null;
+        }
+    };
+    const coreExe = process.env['WICKED_CORE_EXE'];
+    const [core, estate] = await Promise.all([
+        coreExe !== undefined && coreExe !== '' ? probe(coreExe) : Promise.resolve(null),
+        probe('wicked-estate'),
+    ]);
+    return { 'wicked-core': core, 'wicked-estate': estate };
+}
+/** Version probes answer the same for the life of a process — cache the first answer. */
+export class EngineVersionCache {
+    value = null;
+    inFlight = null;
+    async get(exec) {
+        if (this.value !== null)
+            return this.value;
+        if (this.inFlight !== null)
+            return this.inFlight;
+        this.inFlight = engineBinaryVersions(exec)
+            .then((v) => {
+            this.value = v;
+            return v;
+        })
+            .finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+}
+/** Directory totals stop counting past this many entries — a runaway dir must not turn a
+ *  diagnostics GET into a filesystem crawl. The observed events dir is ~139 files. */
+const DIR_SIZE_MAX_ENTRIES = 10_000;
+async function dirBytes(path) {
+    let total = 0;
+    let seen = 0;
+    const stack = [path];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let names;
+        try {
+            names = await fsp.readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (seen >= DIR_SIZE_MAX_ENTRIES)
+                return total;
+            seen += 1;
+            const child = join(dir, name);
+            try {
+                const st = await fsp.stat(child);
+                if (st.isDirectory())
+                    stack.push(child);
+                else
+                    total += st.size;
+            }
+            catch {
+                /* raced deletion — skip */
+            }
+        }
+    }
+    return total;
+}
+/**
+ * `core.db` and every sidecar sharing its basename (`core.db-wal`, `core.db.knowledge`,
+ * `core.db.mem*`, …), plus the events dir (`core.db.events`) sized as a TOTAL of its
+ * contents. Paths and sizes only — no file contents ever ride this wire.
+ */
+export async function listStoreFiles(dbPath) {
+    const home = dirname(dbPath);
+    const base = basename(dbPath);
+    let names;
+    try {
+        names = await fsp.readdir(home);
+    }
+    catch {
+        return [];
+    }
+    const matches = names
+        .filter((n) => n === base || n.startsWith(`${base}.`) || n.startsWith(`${base}-`))
+        .sort();
+    const out = [];
+    for (const name of matches) {
+        const path = join(home, name);
+        try {
+            const st = await fsp.stat(path);
+            out.push({ name, path, bytes: st.isDirectory() ? await dirBytes(path) : st.size });
+        }
+        catch {
+            /* raced deletion — skip */
+        }
+    }
+    return out;
+}
+/** Where a core db's durable run event logs live — the engine's `<db>.events/` convention. */
+export function eventsDirOf(dbPath) {
+    return `${dbPath}.events`;
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/api/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/api/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/api/multiscope.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Multi-codebase scope resolution — the PINNED multiscope wire shared by the testing launch
+ * surfaces (`POST /testing/recon`, `POST /campaigns`).
+ *
+ * Both launch bodies accept two OPTIONAL camelCase fields:
+ *
+ *  - `repoRefs?: string[]` — explicit codebase attachments. Each ref must resolve in the repo
+ *    registry (by id, or by unique name — resolved TO the id) or the whole request fails with a
+ *    400 that NAMES the bad ref. Deduped, first occurrence wins.
+ *  - `projectId?: string` — crew resolves the project's `crew.repo` members server-side.
+ *    Unknown project ⇒ 404; a project with zero repo members (and no explicit `repoRefs` to
+ *    fall back on) ⇒ 400 naming the fix.
+ *
+ * BOTH given ⇒ the union (explicit `repoRefs` order first, then project members not already
+ * named). NEITHER ⇒ `repos: []` and the launch behaves exactly as it did before this wire
+ * existed — backward compatible by construction.
+ *
+ * Fail-closed by doctrine (FINDING-031 posture): a ref that would not launch is refused HERE,
+ * before anything is persisted, with the offending token named — never a silently narrowed
+ * scope or a mid-run "no such repo" a worker discovers for the operator.
+ */
+import type { CoreAdapter } from '../core/adapter.js';
+/** The two optional launch-body fields, as parsed by the route's zod schema. */
+export interface MultiscopeFields {
+    projectId?: string | undefined;
+    repoRefs?: string[] | undefined;
+}
+/** A resolved repo — id is what launches carry (`repoRef`/`repo_ref`), name is for display. */
+export interface ScopedRepo {
+    id: string;
+    name: string;
+}
+export type ScopeResolution = {
+    ok: true;
+    repos: ScopedRepo[];
+} | {
+    ok: false;
+    status: 400 | 404 | 409;
+    error: string;
+};
+/**
+ * Resolve the launch scope. Throws only what the adapter throws (notably
+ * `ProjectsUnsupportedError` on a pre-projects addon — the caller maps it to 501, the same
+ * "upgrade the engine" posture every project route holds).
+ */
+export declare function resolveScopeRepos(adapter: CoreAdapter, fields: MultiscopeFields): Promise<ScopeResolution>;
+//# sourceMappingURL=multiscope.d.ts.map

package/dist/api/multiscope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multiscope.d.ts","sourceRoot":"","sources":["../../src/api/multiscope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACjC;AAED,+FAA+F;AAC/F,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,eAAe,CAAC,CA0F1B"}