@clipboard-health/groundcrew 4.2.0 → 4.2.1

package/dist/lib/adapters/shell/invoke.js

@@ -13,31 +13,22 @@
  */
 import { spawn } from "node:child_process";
 import { log } from "../../util.js";
-export const SHELL_COMMAND_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
-const TIMEOUT_SIGNAL = "SIGKILL";
+/**
+ * Hard cap on captured stdout/stderr per stream. Misbehaving scripts that
+ * `yes | head -c <huge>` would otherwise exhaust memory. 10 MB is enough for
+ * any realistic JSON ticket payload; tests can override via InvokeArgs.maxOutputBytes
+ * to exercise the truncation path with a smaller fixture.
+ */
+const DEFAULT_MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
 export class ShellAdapterTimeoutError extends Error {
     constructor(arguments_) {
         super(`Shell command timed out after ${arguments_.timeoutMs}ms: ${arguments_.command}`);
         this.name = "ShellAdapterTimeoutError";
     }
 }
-export class ShellAdapterOutputLimitError extends Error {
-    constructor(arguments_) {
-        super(`Shell command exceeded combined stdout/stderr maxBuffer of ${arguments_.maxBytes} bytes: ${arguments_.command}`);
-        this.name = "ShellAdapterOutputLimitError";
-    }
-}
 function shellQuote(value) {
     return `'${value.replaceAll("'", String.raw `'\''`)}'`;
 }
-function killChildProcess(child, signal, shouldUseProcessGroup) {
-    /* v8 ignore next 4 @preserve -- fallback path is for Windows or a spawn failure before pid assignment */
-    if (!shouldUseProcessGroup || child.pid === undefined) {
-        child.kill(signal);
-        return;
-    }
-    process.kill(-child.pid, signal);
-}
 export function applySubstitutions(command, subs) {
     let result = command;
     for (const [key, value] of Object.entries(subs)) {
@@ -49,92 +40,72 @@ export async function invokeShellCommand(args) {
     const command = args.substitutions === undefined
         ? args.command
         : applySubstitutions(args.command, args.substitutions);
+    const maxBytes = args.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
     return await new Promise((resolve, reject) => {
-        const shouldUseProcessGroup = process.platform !== "win32";
         const child = spawn("sh", ["-c", command], {
             cwd: args.cwd,
-            detached: shouldUseProcessGroup,
             // oxlint-disable-next-line node/no-process-env -- subprocess inherits the parent's full env by design; user-supplied vars layer on top
             env: { ...process.env, ...args.env },
             stdio: ["pipe", "pipe", "pipe"],
         });
-        const stdoutChunks = [];
-        const stderrChunks = [];
-        let stdoutLength = 0;
-        let stderrLength = 0;
+        let stdout = Buffer.alloc(0);
+        let stderr = Buffer.alloc(0);
+        let truncated = false;
         let settled = false;
-        function cleanup() {
-            clearTimeout(timer);
-        }
-        function killChild(signal) {
-            try {
-                killChildProcess(child, signal, shouldUseProcessGroup);
-            }
-            catch {
-                // The child may have exited between timeout/output-limit handling and the kill request.
-            }
-        }
-        function failAndKill(error) {
-            /* v8 ignore next 3 @preserve -- timeout/output-limit races can call this after another terminal event; deterministic tests cover the first terminal path */
+        const timer = setTimeout(() => {
+            /* v8 ignore next 3 @preserve -- timer/close race: clearTimeout in the close handler should prevent this branch, but the guard is kept as defense-in-depth */
             if (settled) {
                 return;
             }
             settled = true;
-            cleanup();
-            killChild(TIMEOUT_SIGNAL);
-            reject(error);
-        }
-        function appendOutput(input) {
-            /* v8 ignore next 3 @preserve -- streams may emit after timeout/output-limit settlement; this race guard is intentionally defensive */
-            if (settled) {
-                return input.currentLength;
+            child.kill("SIGKILL");
+            reject(new ShellAdapterTimeoutError({ command, timeoutMs: args.timeoutMs }));
+        }, args.timeoutMs);
+        // Buffer accumulators so the byte cap matches its name. A string-based
+        // comparison would measure UTF-16 code units against a byte budget,
+        // letting multibyte UTF-8 sneak past the cap and risking a mid-
+        // surrogate-pair slice on truncation.
+        const appendCapped = (current, chunk) => {
+            if (current.byteLength >= maxBytes) {
+                truncated = true;
+                return current;
             }
-            const nextCombinedLength = stdoutLength + stderrLength + input.chunk.length;
-            if (nextCombinedLength > SHELL_COMMAND_MAX_BUFFER_BYTES) {
-                failAndKill(new ShellAdapterOutputLimitError({
-                    command,
-                    maxBytes: SHELL_COMMAND_MAX_BUFFER_BYTES,
-                }));
-                return input.currentLength;
+            const next = Buffer.concat([current, chunk]);
+            if (next.byteLength <= maxBytes) {
+                return next;
             }
-            input.chunks.push(input.chunk);
-            return input.currentLength + input.chunk.length;
-        }
-        const timer = setTimeout(() => {
-            failAndKill(new ShellAdapterTimeoutError({ command, timeoutMs: args.timeoutMs }));
-        }, args.timeoutMs);
+            truncated = true;
+            const clipped = next.subarray(0, maxBytes);
+            return Buffer.concat([
+                clipped,
+                Buffer.from(`\n[truncated: stream exceeded ${maxBytes} bytes]`),
+            ]);
+        };
         child.stdout.on("data", (chunk) => {
-            stdoutLength = appendOutput({
-                chunks: stdoutChunks,
-                currentLength: stdoutLength,
-                chunk,
-            });
+            stdout = appendCapped(stdout, chunk);
         });
         child.stderr.on("data", (chunk) => {
-            stderrLength = appendOutput({
-                chunks: stderrChunks,
-                currentLength: stderrLength,
-                chunk,
-            });
+            stderr = appendCapped(stderr, chunk);
         });
         child.on("close", (code) => {
+            /* v8 ignore next 3 @preserve -- timer/close race: when the timeout fires first it SIGKILLs and sets settled=true; the 'close' event still arrives and must no-op. No deterministic test exists — an orphaned grandchild (`sh -c "sleep N; ..."`) keeps the stdout pipe open, so 'close' doesn't arrive until the real timeout elapses; mirrors the ignored timer/error settle guards above. */
             if (settled) {
                 return;
             }
             settled = true;
-            cleanup();
-            const stdout = Buffer.concat(stdoutChunks, stdoutLength).toString("utf8");
-            const stderr = Buffer.concat(stderrChunks, stderrLength).toString("utf8");
-            if (stderr.length > 0) {
-                log(`[shell:${args.sourceName}] ${command}\n${stderr.trimEnd()}`);
+            clearTimeout(timer);
+            const stderrText = stderr.toString("utf8");
+            if (stderrText.length > 0) {
+                log(`[shell:${args.sourceName}] ${command}\n${stderrText.trimEnd()}`);
             }
-            /* v8 ignore next @preserve -- `code` is null only when the process was killed by signal; timeout/output-limit paths settle before 'close' */
+            /* v8 ignore next @preserve -- `code` is null only when the process was killed by signal; the timeout path SIGKILLs but settles via the timer rather than 'close' */
             const exitCode = code ?? 1;
+            const stdoutText = stdout.toString("utf8");
             if (exitCode === 0 || exitCode === 3) {
-                resolve({ stdout, stderr, exitCode });
+                resolve({ stdout: stdoutText, stderr: stderrText, exitCode, truncated });
                 return;
             }
-            reject(new Error(`Shell command for source "${args.sourceName}" failed with exit ${exitCode}: ${stderr.trim().length > 0 ? stderr.trim() : command}`));
+            reject(new Error(`Shell command for source "${args.sourceName}" failed with exit ${exitCode}: ${stderrText.trim().length > 0 ? stderrText.trim() : command}`));
         });
         /* v8 ignore next 8 @preserve -- spawn 'error' event fires only on exec failures (PATH miss, EACCES) which are hard to simulate in tests without polluting host PATH */
         child.on("error", (error) => {
@@ -142,7 +113,7 @@ export async function invokeShellCommand(args) {
                 return;
             }
             settled = true;
-            cleanup();
+            clearTimeout(timer);
             reject(error);
         });
         if (args.stdin !== undefined) {

package/dist/lib/adapters/shell/schema.d.ts

@@ -34,6 +34,11 @@ export declare const shellIssueSchema: z.ZodObject<{
             other: "other";
             todo: "todo";
         }>;
+        statusReason: z.ZodOptional<z.ZodEnum<{
+            missing: "missing";
+            unmapped: "unmapped";
+        }>>;
+        nativeStatus: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     hasMoreBlockers: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     sourceRef: z.ZodUnknown;
@@ -64,6 +69,11 @@ export declare const shellFetchOutputSchema: z.ZodArray<z.ZodObject<{
             other: "other";
             todo: "todo";
         }>;
+        statusReason: z.ZodOptional<z.ZodEnum<{
+            missing: "missing";
+            unmapped: "unmapped";
+        }>>;
+        nativeStatus: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     hasMoreBlockers: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     sourceRef: z.ZodUnknown;

package/dist/lib/adapters/shell/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAY3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAA4B,CAAC;AAEhE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;iBAqBnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAY3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAA4B,CAAC;AAEhE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;iBAwBnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/lib/adapters/shell/schema.js

@@ -10,11 +10,12 @@
  */
 import { z } from "zod";
 const canonicalStatusSchema = z.enum(["todo", "in-progress", "in-review", "done", "other"]);
-const timeoutSchema = z.number().int().positive();
 const shellBlockerSchema = z.object({
     id: z.string(),
     title: z.string(),
     status: canonicalStatusSchema,
+    statusReason: z.enum(["missing", "unmapped"]).optional(),
+    nativeStatus: z.string().optional(),
 });
 export const shellIssueSchema = z.object({
     id: z.string(),
@@ -44,10 +45,13 @@ export const shellAdapterConfigSchema = z.object({
     cwd: z.string().optional(),
     timeouts: z
         .object({
-        verify: timeoutSchema.optional(),
-        fetch: timeoutSchema.optional(),
-        resolveOne: timeoutSchema.optional(),
-        markInProgress: timeoutSchema.optional(),
+        // Per-method timeout in milliseconds. Must be a positive integer —
+        // zero, negative, and fractional values would either deadlock or
+        // misbehave inside setTimeout.
+        verify: z.number().int().positive().optional(),
+        fetch: z.number().int().positive().optional(),
+        resolveOne: z.number().int().positive().optional(),
+        markInProgress: z.number().int().positive().optional(),
     })
         .optional(),
     env: z.record(z.string(), z.string()).optional(),

package/dist/lib/board.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"board.d.ts","sourceRoot":"","sources":["../../src/lib/board.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,KAAK;IACpB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B;;;OAGG;IACH,UAAU,CAAC,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;IACrE,wFAAwF;IACxF,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAcD,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,KAAK,CAqEnE"}
+{"version":3,"file":"board.d.ts","sourceRoot":"","sources":["../../src/lib/board.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,KAAK,EAEV,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,KAAK;IACpB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B;;;OAGG;IACH,UAAU,CAAC,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;IACrE,wFAAwF;IACxF,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAqBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,KAAK,CAwGnE"}

package/dist/lib/board.js

@@ -11,6 +11,12 @@ async function callVerify(source) {
 async function callFetch(source) {
     return await source.fetch();
 }
+async function callFetchParentSkips(source) {
+    if (source.fetchParentSkips !== undefined) {
+        return await source.fetchParentSkips();
+    }
+    return [];
+}
 async function callResolveOne(source, naturalId) {
     return await source.resolveOne(naturalId);
 }
@@ -38,8 +44,21 @@ export function createBoard(sources) {
             }
         },
         async fetch() {
-            const issuesPerSource = await Promise.all(sources.map(callFetch));
-            return { timestamp: new Date().toISOString(), issues: issuesPerSource.flat() };
+            // Per-source serialization: each source's callFetch must complete
+            // before its callFetchParentSkips so adapters that cache parent skips
+            // as a side effect of fetch() (e.g. Linear, which stores them on
+            // `lastParentSkips`) don't serve stale or empty data. Outer Promise.all
+            // keeps cross-source fan-out concurrent.
+            const perSource = await Promise.all(sources.map(async (source) => {
+                const issues = await callFetch(source);
+                const parentSkips = await callFetchParentSkips(source);
+                return { issues, parentSkips };
+            }));
+            return {
+                timestamp: new Date().toISOString(),
+                issues: perSource.flatMap((entry) => entry.issues),
+                parentSkips: perSource.flatMap((entry) => entry.parentSkips),
+            };
         },
         async resolveOne(idArgument) {
             const colonIndex = idArgument.indexOf(":");
@@ -52,9 +71,29 @@ export function createBoard(sources) {
                 }
                 return await callResolveOne(source, naturalId);
             }
-            const results = await Promise.all(sources.map(async (s) => await callResolveOne(s, idArgument)));
-            const matches = results.filter((r) => r !== undefined);
+            // Per-source resolveOne errors must not poison sibling resolutions.
+            // A source that rejects on a natural-id lookup is treated as "I don't
+            // have this ticket" (or "I can't say"). If any source resolved we use
+            // it; only when none resolved AND at least one rejected do we surface
+            // the rejection — so the user sees a real Linear/network error when
+            // there's no fallback, but a stray "not found" from one source doesn't
+            // mask a successful match from another.
+            const results = await Promise.allSettled(sources.map(async (s) => await callResolveOne(s, idArgument)));
+            const matches = [];
+            const rejections = [];
+            for (const result of results) {
+                if (result.status === "rejected") {
+                    rejections.push(result.reason);
+                    continue;
+                }
+                if (result.value !== undefined) {
+                    matches.push(result.value);
+                }
+            }
             if (matches.length === 0) {
+                if (rejections.length > 0) {
+                    throw rejections[0];
+                }
                 return undefined;
             }
             if (matches.length === 1) {

package/dist/lib/buildSources.d.ts

@@ -6,6 +6,7 @@
  * directory-scanned `adapterRegistry`.
  */
 import type { AdapterContext, AdapterDefinition } from "./adapterDefinition.ts";
+import type { ResolvedConfig } from "./config.ts";
 import type { TicketSource } from "./ticketSource.ts";
 /**
  * Production entry point. Awaits the directory-scanned registry, then dispatches.
@@ -16,4 +17,14 @@ export declare function buildSources(rawConfigs: readonly unknown[], context: Ad
  * import side effects.
  */
 export declare function buildSourcesWith(registry: Record<string, AdapterDefinition>, rawConfigs: readonly unknown[], context: AdapterContext): TicketSource[];
+/**
+ * Build the runtime source list from a ResolvedConfig: synthesizes the
+ * implicit Linear source (Linear is always active under the post-#110
+ * model — viewer + agent-* label filtering happens at the GraphQL layer)
+ * and appends any user-declared `sources`. The implicit source is omitted
+ * when the user already declared a Linear source (by `kind` or by runtime
+ * name "linear") so they can override its `name` / construction without
+ * spawning a duplicate adapter.
+ */
+export declare function sourcesFromConfig(config: ResolvedConfig): readonly unknown[];
 //# sourceMappingURL=buildSources.d.ts.map

package/dist/lib/buildSources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildSources.d.ts","sourceRoot":"","sources":["../../src/lib/buildSources.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD;;GAEG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC,CAGzB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC3C,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,YAAY,EAAE,CAchB"}
+{"version":3,"file":"buildSources.d.ts","sourceRoot":"","sources":["../../src/lib/buildSources.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD;;GAEG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC,CAGzB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC3C,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,YAAY,EAAE,CAchB;AA6BD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,OAAO,EAAE,CAM5E"}

package/dist/lib/buildSources.js

@@ -32,3 +32,44 @@ export function buildSourcesWith(registry, rawConfigs, context) {
         return adapter.create(config, context);
     });
 }
+const sourceShape = z.looseObject({
+    name: z.string().optional(),
+    kind: z.string().optional(),
+});
+/**
+ * True when `raw` is an explicitly-declared Linear source. Matches either a
+ * `kind: "linear"` entry — regardless of any `name` override — or any entry
+ * whose resolved runtime name (explicit `name`, else `kind`) is "linear".
+ * The latter catches a non-Linear adapter the user named "linear", which
+ * would otherwise collide with the implicit Linear source.
+ *
+ * Used to suppress the synthesized implicit Linear source so a renamed Linear
+ * entry like `{ kind: "linear", name: "custom" }` doesn't spawn a duplicate
+ * adapter pointed at the same viewer. Returns false for malformed entries
+ * (no `kind`/`name`) — those get rejected by the per-adapter Zod schema
+ * downstream.
+ */
+function isExplicitLinearSource(raw) {
+    const parsed = sourceShape.safeParse(raw);
+    /* v8 ignore next 3 @preserve -- looseObject() with all-optional fields only fails to parse non-object inputs (null, primitives); the same input would be rejected by the per-adapter Zod schema in buildSourcesWith, so this guard never fires in practice. */
+    if (!parsed.success) {
+        return false;
+    }
+    return parsed.data.kind === "linear" || (parsed.data.name ?? parsed.data.kind) === "linear";
+}
+/**
+ * Build the runtime source list from a ResolvedConfig: synthesizes the
+ * implicit Linear source (Linear is always active under the post-#110
+ * model — viewer + agent-* label filtering happens at the GraphQL layer)
+ * and appends any user-declared `sources`. The implicit source is omitted
+ * when the user already declared a Linear source (by `kind` or by runtime
+ * name "linear") so they can override its `name` / construction without
+ * spawning a duplicate adapter.
+ */
+export function sourcesFromConfig(config) {
+    const hasExplicitLinear = config.sources.some(isExplicitLinearSource);
+    if (hasExplicitLinear) {
+        return [...config.sources];
+    }
+    return [{ kind: "linear" }, ...config.sources];
+}

package/dist/lib/repositoryValidation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Host-level repository validation for canonical Issues. Adapters produce
+ * Issue.repository based on their own signal (Linear: agent-* label parse;
+ * shell: script JSON output). The host (dispatcher) decides whether that
+ * repository is configured for this crew via workspace.knownRepositories.
+ *
+ * WARN+skip on unknown repo is a deliberate behavior choice (P-refined in
+ * the MVP-2 plan): one badly-labelled ticket should not throw and abort
+ * the tick across N sources.
+ */
+import type { Issue } from "./ticketSource.ts";
+export declare function dispatchableRepository(issue: Issue, knownRepositories: readonly string[], log: (message: string) => void): string | undefined;
+//# sourceMappingURL=repositoryValidation.d.ts.map

package/dist/lib/repositoryValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repositoryValidation.d.ts","sourceRoot":"","sources":["../../src/lib/repositoryValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,KAAK,EACZ,iBAAiB,EAAE,SAAS,MAAM,EAAE,EACpC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC7B,MAAM,GAAG,SAAS,CAWpB"}

package/dist/lib/repositoryValidation.js

@@ -0,0 +1,20 @@
+/**
+ * Host-level repository validation for canonical Issues. Adapters produce
+ * Issue.repository based on their own signal (Linear: agent-* label parse;
+ * shell: script JSON output). The host (dispatcher) decides whether that
+ * repository is configured for this crew via workspace.knownRepositories.
+ *
+ * WARN+skip on unknown repo is a deliberate behavior choice (P-refined in
+ * the MVP-2 plan): one badly-labelled ticket should not throw and abort
+ * the tick across N sources.
+ */
+export function dispatchableRepository(issue, knownRepositories, log) {
+    if (issue.repository === undefined) {
+        return undefined;
+    }
+    if (!knownRepositories.includes(issue.repository)) {
+        log(`issue ${issue.id} references unknown repository ${issue.repository}; configured workspace.knownRepositories: ${knownRepositories.join(", ") || "(none)"}`);
+        return undefined;
+    }
+    return issue.repository;
+}

package/dist/lib/testing/canonicalFixtures.d.ts

@@ -0,0 +1,19 @@
+import { type Blocker, type Issue } from "../ticketSource.ts";
+export declare function canonicalLinearIssue(overrides: Partial<Issue> & {
+    naturalId: string;
+}): Issue;
+export declare function canonicalBlocker(overrides: Partial<Blocker> & {
+    naturalId: string;
+}): Blocker;
+/**
+ * Canonical Issue fixture for a non-Linear source. Default source name is
+ * "shell-test"; override via `sourceName`. Mirrors `canonicalLinearIssue`'s
+ * defaults except `sourceRef` is an empty opaque object (no LinearSourceRef
+ * shape, since this is meant to stand in for any non-Linear adapter — the
+ * shell adapter, future Jira adapter, etc.).
+ */
+export declare function canonicalShellIssue(overrides: Partial<Issue> & {
+    naturalId: string;
+    sourceName?: string;
+}): Issue;
+//# sourceMappingURL=canonicalFixtures.d.ts.map

package/dist/lib/testing/canonicalFixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalFixtures.d.ts","sourceRoot":"","sources":["../../../src/lib/testing/canonicalFixtures.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,KAAK,EAAiB,MAAM,oBAAoB,CAAC;AAE7E,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CA0B7F;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAQ7F;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACrE,KAAK,CAiBP"}

package/dist/lib/testing/canonicalFixtures.js

@@ -0,0 +1,62 @@
+import { toCanonicalId } from "../ticketSource.js";
+export function canonicalLinearIssue(overrides) {
+    const { naturalId, sourceRef: refOverride, ...rest } = overrides;
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- test fixture; sourceRef is opaque unknown in the Issue contract; we reinterpret it here only for fixture construction
+    const refPartial = refOverride ?? {};
+    const sourceRef = {
+        uuid: refPartial.uuid ?? `uuid-${naturalId}`,
+        statusId: refPartial.statusId ?? "statusId-default",
+        teamId: refPartial.teamId ?? "team-default",
+        stateType: refPartial.stateType ?? "unstarted",
+        nativeStatus: refPartial.nativeStatus ?? "Todo",
+    };
+    return {
+        id: toCanonicalId("linear", naturalId),
+        source: "linear",
+        title: `Title for ${naturalId}`,
+        description: "",
+        status: "todo",
+        repository: undefined,
+        model: undefined,
+        assignee: "Unassigned",
+        updatedAt: "2026-01-01T00:00:00.000Z",
+        blockers: [],
+        hasMoreBlockers: false,
+        ...rest,
+        sourceRef,
+    };
+}
+export function canonicalBlocker(overrides) {
+    const { naturalId, ...rest } = overrides;
+    return {
+        id: toCanonicalId("linear", naturalId),
+        title: `Title for ${naturalId}`,
+        status: "todo",
+        ...rest,
+    };
+}
+/**
+ * Canonical Issue fixture for a non-Linear source. Default source name is
+ * "shell-test"; override via `sourceName`. Mirrors `canonicalLinearIssue`'s
+ * defaults except `sourceRef` is an empty opaque object (no LinearSourceRef
+ * shape, since this is meant to stand in for any non-Linear adapter — the
+ * shell adapter, future Jira adapter, etc.).
+ */
+export function canonicalShellIssue(overrides) {
+    const { naturalId, sourceName = "shell-test", sourceRef, ...rest } = overrides;
+    return {
+        id: toCanonicalId(sourceName, naturalId),
+        source: sourceName,
+        title: `Title for ${naturalId}`,
+        description: "",
+        status: "todo",
+        repository: undefined,
+        model: undefined,
+        assignee: "Unassigned",
+        updatedAt: "2026-01-01T00:00:00.000Z",
+        blockers: [],
+        hasMoreBlockers: false,
+        sourceRef: sourceRef ?? {},
+        ...rest,
+    };
+}

package/dist/lib/ticketSource.d.ts

@@ -26,9 +26,33 @@ export interface Blocker {
     id: string;
     title: string;
     status: CanonicalStatus;
+    /**
+     * When `status === "other"`, adapters MUST set this to explain why
+     * they couldn't classify. Consumers (specifically `ticketDoctor`) render
+     * this verbatim to give users an actionable next step.
+     *
+     * - `"missing"`: the source returned no status for this blocker
+     *   (e.g., Linear had no state on the blocker; shell script omitted
+     *   the field).
+     * - `"unmapped"`: the source returned a status that isn't in the
+     *   source's known mapping (e.g., a Linear column not in
+     *   `linear.projects[*].statuses`, or an unrecognized shell value).
+     *
+     * MUST be undefined when `status !== "other"`.
+     */
+    statusReason?: "missing" | "unmapped";
+    /**
+     * Human-readable native status from the source, when available.
+     * Used for diagnostic display only — never branched on. Adapters SHOULD
+     * populate this when `statusReason === "unmapped"` so users can see
+     * which status name to add to their config; MAY populate for mapped
+     * statuses too if the source's native vocabulary differs usefully
+     * from `CanonicalStatus`.
+     */
+    nativeStatus?: string;
 }
 export interface Issue {
-    /** Canonical, source-prefixed id, e.g. "linear:eng-220" or "shell-jira:HRD-1". */
+    /** Canonical, source-prefixed id, e.g. "linear:eng-220" or "shell-jira:hrd-1". */
     id: string;
     /** Source name (the adapter's `name`, defaulting to its `kind`). */
     source: string;
@@ -52,9 +76,26 @@ export type GroundcrewIssue = Issue & {
     repository: string;
 };
 export declare function isGroundcrewIssue(issue: Issue): issue is GroundcrewIssue;
+/**
+ * A parent ticket that was dropped from the fetch result because it has
+ * sub-issues. Surfaced separately so the dispatcher can log WHY a
+ * Todo+labelled ticket wasn't picked up (PR #80 behavior).
+ */
+export interface ParentSkip {
+    /**
+     * Canonical, source-prefixed id, e.g. "linear:eng-220". Matches the form
+     * used by `Issue.id` so consumers can treat all ids uniformly and strip
+     * the prefix with `naturalIdFromCanonical` when displaying to operators.
+     */
+    id: string;
+    title: string;
+    childCount: number;
+}
 export interface BoardState {
     timestamp: string;
     issues: Issue[];
+    /** Parent tickets skipped because they have sub-issues. */
+    parentSkips: readonly ParentSkip[];
 }
 export interface TicketSource {
     /** Stable identifier used as the id prefix and in log lines. Equal to the source's config `name`. */
@@ -67,6 +108,13 @@ export interface TicketSource {
     resolveOne(naturalId: string): Promise<Issue | undefined>;
     /** Writeback. The adapter downcasts `issue.sourceRef` internally. */
     markInProgress(issue: Issue): Promise<void>;
+    /**
+     * Optional: return parent tickets that were excluded from `fetch()` because
+     * they have sub-issues. Board surfaces these so the dispatcher can log WHY
+     * a Todo+labelled ticket was skipped (PR #80 behavior). Adapters that
+     * don't distinguish parents simply omit this method; Board returns [].
+     */
+    fetchParentSkips?(): Promise<readonly ParentSkip[]>;
 }
 export declare class RepositoryResolutionError extends Error {
     constructor(arguments_: {
@@ -80,4 +128,26 @@ export declare class AmbiguousTicketError extends Error {
         matches: readonly string[];
     });
 }
+/**
+ * Build a canonical source-prefixed id from a source name and a natural
+ * (possibly mixed-case) id. Lower-cases the natural part so the same
+ * ticket always produces the same canonical id regardless of which code
+ * path or adapter constructed it.
+ *
+ * All adapters MUST use this helper when constructing canonical ids
+ * (rather than concatenating `${sourceName}:${naturalId}` inline) so
+ * that `Board.resolveOne` lookups against lower-cased natural-id input
+ * find the issue regardless of the casing the source emitted.
+ */
+export declare function toCanonicalId(sourceName: string, naturalId: string): string;
+/**
+ * Strip the source prefix from a canonical id, yielding the natural id
+ * the producing adapter exposed. Use at consumer boundaries where you
+ * need to compare a canonical id against natural-id artifacts like
+ * `WorktreeEntry.ticket` or filesystem directory names.
+ *
+ * Canonical ids always carry a `<source>:` prefix; the no-colon branch
+ * is a defensive fallback that's unreachable in normal operation.
+ */
+export declare function naturalIdFromCanonical(id: string): string;
 //# sourceMappingURL=ticketSource.d.ts.map

package/dist/lib/ticketSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ticketSource.d.ts","sourceRoot":"","sources":["../../src/lib/ticketSource.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,aAAa,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtF,MAAM,WAAW,OAAO;IACtB,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,KAAK;IACpB,kFAAkF;IAClF,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,CAAC;IACxB,8FAA8F;IAC9F,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,wFAAwF;IACxF,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,eAAe,CAExE;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,qGAAqG;IACrG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,oFAAoF;IACpF,KAAK,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC1B,0EAA0E;IAC1E,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;IAC1D,qEAAqE;IACrE,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,YAAmB,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAMjF;CACF;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAmB,UAAU,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAM/E;CACF"}
+{"version":3,"file":"ticketSource.d.ts","sourceRoot":"","sources":["../../src/lib/ticketSource.ts"],"names":[],"mappings":"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"}