@skyramp/mcp 0.3.4 → 0.3.6-rc.1

package/build/types/RepositoryAnalysis.js

@@ -87,7 +87,7 @@ export const scenarioStepSchema = z.object({
     interactionType: z.enum(["success", "error", "edge-case"]),
     requestBody: z.record(z.any()).optional(),
     queryParams: z.record(z.any()).optional(),
-    responseBody: z.record(z.any()).optional(),
+    responseBody: z.union([z.record(z.any()), z.array(z.any())]).optional(),
     expectedStatusCode: z.number(),
     expectedResponseFields: z.array(z.string()).optional(),
     chainsFrom: z

package/build/types/ReuseOutcome.d.ts

@@ -1,6 +1,9 @@
 /**
- * The POM code-reuse shape carried in a TestbotReport — the wire contract between
- * this server and the consumers that render it (test-bot.git).
+ * The code-reuse observability shape carried in a TestbotReport — the wire contract
+ * between this server and the consumers that render it (test-bot.git). It covers
+ * both reuse paths: page-object (POM) reuse for browser tests, and shared-helper
+ * (SkyrampUtils) reuse for API tests, plus whether the generation chain that leads
+ * to reuse was followed at all.
  *
  * Lives in types/ rather than beside the derivation logic in
  * tools/code-refactor/reuse-outcome.ts, and is re-exported from types/index.ts,
@@ -45,11 +48,72 @@ export interface ReuseSkippedEntry {
     declinedBy?: ReuseDeclinedBy;
     reason: string;
 }
+/** A raw locator left inline in the delivered spec that a catalogued POM member
+ *  covers — the calls the spec did NOT make, which the call counts cannot express.
+ *
+ *  Purely informational: nothing gates on it. A page object may legitimately not
+ *  model a given assertion, so an entry here is a prompt to look, never a verdict
+ *  that the spec is wrong.
+ *
+ *  Overlaps with {@link ReuseOutcome.skipped} on purpose, so a reader who sees the
+ *  same page object in both lists is not looking at two problems. A decline names a
+ *  FILE (`// kept inline: <file basename>`), never a locator, so filtering this list
+ *  by it would drop every miss in that file — including the ones the agent never
+ *  considered. Read `skipped` as the reasons the agent gave, and this list as what
+ *  the delivered spec still carries. */
+export interface ReuseMissedEntry {
+    /** The selector token exactly as it appears in the delivered spec. */
+    locator: string;
+    /** Basename of the catalog's `Import:` path. Deliberately EXTENSION-LESS
+     *  (`functionsPage`), unlike {@link ReuseSkippedEntry.pageObject}, which carries
+     *  the extension (`functionsPage.js`) because it is parsed out of the agent's
+     *  `// kept inline: <file basename>` comment. Resolving the catalog's
+     *  extension-less import against disk would mean probing `.ts`/`.js` and inventing
+     *  new failure modes for a cosmetic gain, so the two are documented rather than
+     *  unified. */
+    pageObject: string;
+    /** `<ClassName>.<member>` as the catalog names it, e.g. `FunctionsPage.getRowByName`. */
+    member: string;
+}
+/** Outcome of the shared-helper (SkyrampUtils) verification for a test. A separate
+ *  enum from {@link ReuseVerificationOutcome} on purpose: the utils path has no
+ *  page-object layer to skip on, and reusing `skipped-no-pom` to mean "no helper
+ *  file was written" would be a mislabelled member. */
+export declare enum HelperVerificationOutcome {
+    Passed = "passed",
+    Failed = "failed",
+    /** The test neither wrote nor imports a shared utils file. */
+    NoUtilsFile = "no-utils-file"
+}
+/** Shared-helper reuse for an API test, re-derived from the delivered files at report
+ *  time — nothing here is read back from what the agent or the verify pass recorded.
+ *  Absent altogether when no utils file exists for the test (the same omission rule
+ *  as the POM fields at zero candidates: a zero says nothing "no file" does not). */
+export interface HelperReuseOutcome {
+    /** BASENAME of the shared utils file the test imports from or this run wrote —
+     *  found by its header, never by a conventional name (the reuse prompt allows "a
+     *  new file with a different name" once the conventional one is large). Several
+     *  files are joined with `, `. */
+    utilsFile: string;
+    /** Helpers the delivered test imports from that file that the file defines. */
+    helpersImported?: number;
+    /** Inline request calls in OTHER Skyramp-generated tests beside this one that a
+     *  helper in `utilsFile` already wraps — reuse that was available and not taken.
+     *  Omitted at zero. Informational, like {@link ReuseOutcome.missedReuse}. */
+    siblingInlineCallSites?: number;
+    /** Whether the delivered utils file holds the shared-helper invariants: one helper
+     *  per method+path, status-code-only assertions, method+resource names — with
+     *  documented declines (`reuse-verify: allow …`) counted as holding. */
+    verification?: HelperVerificationOutcome;
+}
 /**
- * What lands in a report's `reuse` field, for a UI test whose generation ran POM
- * code reuse. Every member is optional: consumers must render from whatever
- * subset is present, and omit the summary entirely when the object is absent (as
- * it is for non-UI tests, and in reports from versions predating the field).
+ * What lands in a report's `reuse` field for a generated test. Every member is
+ * optional: consumers must render from whatever subset is present, and omit the
+ * summary entirely when the object is absent (as it is for tests whose generation
+ * ran no reuse step, and in reports from versions predating the field). POM fields
+ * appear for browser tests that took the POM path; `helpers` for tests on the
+ * SkyrampUtils path; `chainSkipped` for either when the reuse step was owed and
+ * never called.
  *
  * `candidatesDetected` counts FILES while the call counts count CALLS — an
  * indicator, never a fraction. Do not render the pair as a ratio or percentage.
@@ -58,6 +122,38 @@ export interface ReuseOutcome {
     candidatesDetected?: number;
     callsReused?: number;
     callsVerified?: number;
+    /** Calls the verifier could not statically check — dynamic locators, chained
+     *  `.click()` on a property, anything not resolvable without executing.
+     *
+     *  `callsVerified + callsUnverifiable === callsReused` holds, so a renderer can
+     *  say "9 reused, 6 verified, 3 not statically verifiable" instead of implying
+     *  three failures. Carried as its own number rather than left to the renderer to
+     *  subtract, so a consumer cannot arrive at a different one.
+     *
+     *  It equals `unverifiableCalls.length` too — the verifier puts every call it
+     *  examines in exactly one of the two buckets — but derive it from the counts,
+     *  since the list is omitted when empty. */
+    callsUnverifiable?: number;
+    /** The unverifiable calls by name. Unrecognized bindings are NOT included — they
+     *  are not calls, and counting them here is what made the old single list
+     *  unusable. */
+    unverifiableCalls?: string[];
+    /** Raw selector tokens still inline in the delivered spec. The denominator the
+     *  call counts lack: `callsReused: 2` alone cannot distinguish thorough reuse
+     *  from a spec that reused login and ignored everything else. */
+    rawLocatorsInline?: number;
+    /** The subset of those raw locators that a catalogued POM member covers.
+     *  Informational; see {@link ReuseMissedEntry}. */
+    missedReuse?: ReuseMissedEntry[];
     verification?: ReuseVerificationOutcome;
     skipped?: ReuseSkippedEntry[];
+    /** Shared-helper (SkyrampUtils) reuse. See {@link HelperReuseOutcome}. */
+    helpers?: HelperReuseOutcome;
+    /** Present — and only ever `true` — when generation handed off a modularize→reuse
+     *  step for this test and no reuse pass was recorded for it. Since the execution
+     *  checkpoint refuses to run such a test until reuse is called, this can only
+     *  appear when the agent walked past that checkpoint to the report: it is a
+     *  direct signal of gate evasion, not a general "did not happen". Omitted (never
+     *  `false`) when the chain was followed. */
+    chainSkipped?: true;
 }

package/build/types/ReuseOutcome.js

@@ -1,6 +1,9 @@
 /**
- * The POM code-reuse shape carried in a TestbotReport — the wire contract between
- * this server and the consumers that render it (test-bot.git).
+ * The code-reuse observability shape carried in a TestbotReport — the wire contract
+ * between this server and the consumers that render it (test-bot.git). It covers
+ * both reuse paths: page-object (POM) reuse for browser tests, and shared-helper
+ * (SkyrampUtils) reuse for API tests, plus whether the generation chain that leads
+ * to reuse was followed at all.
  *
  * Lives in types/ rather than beside the derivation logic in
  * tools/code-refactor/reuse-outcome.ts, and is re-exported from types/index.ts,
@@ -31,3 +34,14 @@ export var ReuseVerificationOutcome;
     /** No page-object layer existed to reuse. */
     ReuseVerificationOutcome["SkippedNoPom"] = "skipped-no-pom";
 })(ReuseVerificationOutcome || (ReuseVerificationOutcome = {}));
+/** Outcome of the shared-helper (SkyrampUtils) verification for a test. A separate
+ *  enum from {@link ReuseVerificationOutcome} on purpose: the utils path has no
+ *  page-object layer to skip on, and reusing `skipped-no-pom` to mean "no helper
+ *  file was written" would be a mislabelled member. */
+export var HelperVerificationOutcome;
+(function (HelperVerificationOutcome) {
+    HelperVerificationOutcome["Passed"] = "passed";
+    HelperVerificationOutcome["Failed"] = "failed";
+    /** The test neither wrote nor imports a shared utils file. */
+    HelperVerificationOutcome["NoUtilsFile"] = "no-utils-file";
+})(HelperVerificationOutcome || (HelperVerificationOutcome = {}));

package/build/types/TestRecommendation.js

@@ -15,7 +15,7 @@ export var Novelty;
 })(Novelty || (Novelty = {}));
 /** Internal-only categories (not submitted to tools). */
 const INTERNAL_CATEGORIES = [
-    "new_endpoint", // CRITICAL - diff-direct scenarios always fill GENERATE slots first
+    "new_endpoint", // MEDIUM - diff-direct scenario; where a test came from, not a guarantee of a slot
     "bug_caught", // CRITICAL - tests targeting a specific <bug_found> flaw identified during enrichment
 ];
 /** External categories valid for tool submissions, ordered by priority. */
@@ -39,9 +39,27 @@ export const SCENARIO_CATEGORIES = [...INTERNAL_CATEGORIES, ...CATEGORIES];
 export const TEST_CATEGORIES = CATEGORIES;
 /** Priority assignment for each category. */
 export const CATEGORY_PRIORITY = {
-    new_endpoint: PriorityTier.CRITICAL,
+    // CRITICAL means "this test targets a specific identified flaw" — only bug_caught
+    // asserts that. new_endpoint says where a test came from (a template fired on an
+    // endpoint the diff added), not that it earns a guaranteed slot. Reserving the
+    // top tier for it let server-drafted templates outrank anything an agent said,
+    // by label rather than merit. (The registration enum is SCENARIO_CATEGORIES, so
+    // an agent CAN submit new_endpoint; externalCategory maps it to crud/LOW for
+    // report and merge purposes only.)
+    //
+    // It sits BELOW the categories that state what a test proves, not level with
+    // them. Level was still too high: the last rank key is the candidateId, so among
+    // same-tier candidates the ALPHABET decided. Template names start with the
+    // resource (billing-, bookings-, export-, members-) and an agent names a scenario
+    // for what it checks, so on cc15-org-reviewer-role all 8 templates outranked all
+    // 12 candidates the agent wrote, and 2 of the 3 GENERATE slots went to the letter
+    // "b" beating "o". MEDIUM, not LOW: a template on an endpoint the diff just added
+    // is still worth more than a crud test on an endpoint that was always there. The
+    // floor survives — when the agent offers nothing above MEDIUM, templates still
+    // fill GENERATE.
+    new_endpoint: PriorityTier.MEDIUM,
     bug_caught: PriorityTier.CRITICAL, // tests targeting a <bug_found> flaw — always in GENERATE
-    business_rule: PriorityTier.HIGH, // formula/business-logic bugs are high priority but CRITICAL is reserved for new-endpoint diff-direct scenarios
+    business_rule: PriorityTier.HIGH, // formula/business-logic bugs are high priority
     security_boundary: PriorityTier.HIGH,
     data_integrity: PriorityTier.HIGH,
     breaking_change: PriorityTier.HIGH,

package/build/types/TestTypes.js

@@ -163,7 +163,9 @@ export const basePlaywrightSchema = z.object({
     playwrightViewportSize: z
         .union([
         z.enum(["", "hd", "full-hd", "2k"]),
-        z.string().regex(/^\d+,\d+$/, "Custom viewport must be 'WIDTH,HEIGHT' format (e.g., '1920,1080')"),
+        z
+            .string()
+            .regex(/^\d+,\d+$/, "Custom viewport must be 'WIDTH,HEIGHT' format (e.g., '1920,1080')"),
     ])
         .default("")
         .describe("Viewport size for playwright browser. THE VALUE MUST BE IN THE FORMAT ['', 'hd', 'full-hd', '2k', 'x,y' e.g. '1920,1080' for 1920x1080 resolution]. DEFAULT VALUE IS ''. If set to '', the browser will use its default viewport size."),
@@ -215,10 +217,10 @@ export const baseTestSchema = {
     queryParams: z
         .string()
         .default("")
-        .describe("MUST be string of comma separated values like 'id=1,name=John' for URL query parameters. "
-        + "Workspace-configured api.defaultQueryParams (if set) are merged in automatically, with any "
-        + "api.queryParamOverrides entry whose pathPattern matches this endpoint layered on top — "
-        + "no need to repeat them here. An explicit value for the same key here overrides both."),
+        .describe("MUST be string of comma separated values like 'id=1,name=John' for URL query parameters. " +
+        "Workspace-configured api.defaultQueryParams (if set) are merged in automatically, with any " +
+        "api.queryParamOverrides entry whose pathPattern matches this endpoint layered on top — " +
+        "no need to repeat them here. An explicit value for the same key here overrides both."),
     formParams: z
         .string()
         .default("")
@@ -235,7 +237,9 @@ export const baseTestSchema = {
             JSON.parse(val);
             return true;
         }
-        catch { /* not JSON */ }
+        catch {
+            /* not JSON */
+        }
         const trimmed = val.trim();
         // Accept common YAML patterns: document separator, mappings (key: val), sequences (- item)
         if (trimmed.startsWith("---"))
@@ -254,7 +258,9 @@ export const baseTestSchema = {
     responseStatusCode: z
         .string()
         .default("")
-        .refine((val) => !val || /^\d{3}$/.test(val), { message: "Must be a 3-digit HTTP status code (e.g., '200', '404') or empty string" })
+        .refine((val) => !val || /^[1-5]\d{2}$/.test(val), {
+        message: "Must be a valid HTTP status code in 100-599 (e.g., '200', '404') or empty string",
+    })
         .describe("Expected HTTP response status code (e.g., '200', '201', '404'). DO NOT ASSUME STATUS CODE IF NOT PROVIDED"),
     ...baseSchema.shape,
 };
@@ -262,7 +268,7 @@ export const codeRefactoringSchema = z.object({
     codeReuse: z
         .boolean()
         .default(false)
-        .describe("Reuse existing code in the generated test — for TS/JS Playwright tests this refactors the test to use the repo's existing Page Object Model"),
+        .describe("Reuse existing code in the generated test — consolidates helper functions shared with sibling Skyramp-generated tests into a SkyrampUtils file; for TS/JS Playwright tests with POM reuse enabled it instead refactors the test to use the repo's existing Page Object Model"),
     modularizeCode: z
         .boolean()
         .default(false)

package/build/types/TestbotReport.d.ts

@@ -14,7 +14,9 @@ export declare enum IssueFoundCategory {
 /**
  * Shape of the JSON report written by skyramp_submit_report and read by testbot
  * for rendering as Markdown. All fields mirror the corresponding Zod schemas in
- * submitReportTool.ts — keep the two in sync.
+ * submitReportTool.ts — keep the two in sync. This type describes what a READER
+ * may encounter across MCP versions; the Zod schemas define what the current
+ * producer must submit, so a field can be required on submit but optional here.
  */
 export interface TestbotReport {
     businessCaseAnalysis: string;
@@ -25,6 +27,9 @@ export interface TestbotReport {
         fileName: string;
         reasoning: string;
         description: string;
+        /** `owner/repo` attribution in multi-repo runs (SKYR-3786). Absent = the
+         *  primary repo, or a single-repo run. */
+        repository?: string;
         scenarioFile?: string;
         traceFile?: string;
         frontendTrace?: string;
@@ -53,6 +58,8 @@ export interface TestbotReport {
         status: "Pass" | "Fail" | "Skipped";
         details: string;
         videoPath?: string;
+        /** See newTestsCreated[].repository. */
+        repository?: string;
     }[];
     additionalRecommendations?: {
         testId: string;
@@ -66,7 +73,7 @@ export interface TestbotReport {
             description: string;
             expectedStatusCode?: number;
             requestBody?: Record<string, unknown>;
-            responseBody?: Record<string, unknown>;
+            responseBody?: Record<string, unknown> | unknown[];
         }[];
         description: string;
         priority: "high" | "medium" | "low";
@@ -74,11 +81,26 @@ export interface TestbotReport {
         openApiSpec?: string;
         backendTrace?: string;
         frontendTrace?: string;
+        /** See newTestsCreated[].repository. */
+        repository?: string;
     }[];
     issuesFound: {
         description: string;
         severity?: "critical" | "high" | "medium" | "low";
-        category: IssueFoundCategory;
+        /** Required by the submit_report schema since 0.3.4; absent in reports
+         *  written by older MCP versions. Readers treat absence as Bug. */
+        category?: IssueFoundCategory;
+        /** Where the defect lives, checked against the checkout when the report is
+         *  submitted. The submit schema requires sourceFile on a `bug` entry; symbol
+         *  and line stay optional there (a config file or template has no symbol, and
+         *  line numbers are advisory). All three are optional here because a report
+         *  from an older MCP version has none of them, and a lint/type/config entry
+         *  never needs them. */
+        sourceFile?: string;
+        sourceSymbol?: string;
+        sourceLine?: number;
+        /** See newTestsCreated[].repository. */
+        repository?: string;
     }[];
     nextSteps: string[];
     commitMessage: string;

package/build/types/index.d.ts

@@ -3,6 +3,6 @@ export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
 export type { TestbotReport } from "./TestbotReport.js";
 export { IssueFoundCategory } from "./TestbotReport.js";
-export { ReuseDeclinedBy, ReuseVerificationOutcome } from "./ReuseOutcome.js";
-export type { ReuseOutcome, ReuseSkippedEntry } from "./ReuseOutcome.js";
+export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./ReuseOutcome.js";
+export type { ReuseOutcome, ReuseSkippedEntry, ReuseMissedEntry, HelperReuseOutcome, } from "./ReuseOutcome.js";
 export type { RelatedRepository, TestbotPromptOptions, } from "./TestbotPromptOptions.js";

package/build/types/index.js

@@ -2,4 +2,4 @@ export { TestExecutionStatus } from "./TestExecution.js";
 export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
 export { IssueFoundCategory } from "./TestbotReport.js";
-export { ReuseDeclinedBy, ReuseVerificationOutcome } from "./ReuseOutcome.js";
+export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./ReuseOutcome.js";

package/build/utils/AnalysisStateManager.d.ts

@@ -8,8 +8,21 @@ import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
 import type { ApprovedPlanItem } from "../types/Recommendation.js";
 import type { ExternalTestRunRecord } from "../types/ExternalTestExecution.js";
 import type { VideoRecord } from "../types/TestExecution.js";
+import type { RepoCheckout } from "./reportVerification.js";
 export type { CandidateUiPage } from "./uiPageEnumerator.js";
 export declare function setTestsRepoDir(dir: string | undefined): void;
+/**
+ * Record the run's tests repo without ever clearing a known value.
+ *
+ * The tests repo is a RUN-scoped fact, but analyze_changes is called once per
+ * repository and only the PRIMARY call carries `testsRepoDir` — a related
+ * repo's call omits it. An unconditional set therefore wiped the primary's
+ * value on the second call of every multi-repo run, and by report time the
+ * tests repo was unknown: a UI test generated there looked unbacked by any
+ * working tree and the agent demoted it out of newTestsCreated (SKYR-4204,
+ * run 32536569467). Callers that mean to clear it use setTestsRepoDir.
+ */
+export declare function rememberTestsRepoDir(dir: string | undefined): void;
 export declare function getTestsRepoDir(): string | undefined;
 /** Filename of the run-scoped analysis state file under `runArtifactDir()`.
  *  Single-sourced so the constructor that WRITES there and `resolveRunStatePath`
@@ -54,6 +67,20 @@ export declare function clearActiveRunStatePath(): void;
  * decide where to look for it.
  */
 export declare function resolveRunStatePath(explicitPath?: string): string | undefined;
+/**
+ * The run's state file if this process is actually serving a run, else undefined.
+ *
+ * Distinct from {@link resolveRunStatePath}, which answers "where would the file
+ * be": the fallback above builds a path from `$RUNNER_TEMP`, and GitHub Actions
+ * sets RUNNER_TEMP on every job — including this repo's own CI, where a resolvable
+ * path is not a run. Callers that gate BEHAVIOUR on being in a run must use this
+ * one; callers that only want to write state can keep using the path, because a
+ * write to a file that holds no run data is already a no-op.
+ *
+ * Returns the path rather than a boolean so a caller can also key per-run state on
+ * it, and lives here because this is the module that decides where the file goes.
+ */
+export declare function currentRunStateFile(): string | undefined;
 export declare function registerSession(sessionId: string, stateFilePath: string): void;
 export declare function getSessionFilePath(sessionId: string): string | undefined;
 export declare function getRegisteredSessions(): ReadonlyMap<string, string>;
@@ -114,7 +141,12 @@ export interface UiAnalysisContext {
  * when it has its own pre-ranked GENERATE items). `generate` is the mandated,
  * final list generation tools gate against (see planGuard.ts); `additional` is
  * report-only; `demotions` carries discriminator claims that failed structural
- * verification (the candidate itself is never dropped, only the claim).
+ * verification — the demotion drops the CLAIM, never the candidate, but it does
+ * not keep the candidate either: budgeting can still cut it, so the same id may
+ * appear in both `demotions` and `dropped`;
+ * `dropped` carries candidates the selection stage removed outright from
+ * `generate`/`additional` (SKYR-4214) — the visible record of what got cut
+ * and why, since neither list says anything about what is missing from it.
  */
 export interface ApprovedPlan {
     planId: string;
@@ -125,6 +157,10 @@ export interface ApprovedPlan {
         candidateId: string;
         reason: string;
     }>;
+    dropped: Array<{
+        candidateId: string;
+        reason: string;
+    }>;
 }
 /**
  * Budget inputs computed once by skyramp_analyze_changes (from the same
@@ -142,6 +178,15 @@ export interface PlanBudgetContext {
     hasFrontendChanges: boolean;
     /** Serialized form of the BudgetContext.externalCoverage Set. */
     externalCoverageKeys: string[];
+    /** Whether the PR diff changes any test file; see BudgetContext. */
+    diffChangesTestFiles?: boolean;
+}
+export interface ReuseHandOff {
+    testType: string;
+    language: string;
+    /** The framework the hand-off named, so a refusal can hand back a call the
+     *  reuse tool's schema accepts (`framework` is required there). */
+    framework: string;
 }
 /**
  * Unified state data combining test discovery + endpoint scanning
@@ -186,6 +231,19 @@ export interface UnifiedAnalysisState {
      *  which computes every value in-process; skyramp_submit_report merges it into
      *  the report's `reuse` field. Never supplied by the LLM. */
     reuseOutcomes?: Record<string, ReuseRecord>;
+    /** SKYR-4262. Assertion-enhancement obligations per spec, keyed by test-file
+     *  BASENAME (same key as `reuseOutcomes`). Written in-process by
+     *  skyramp_enhance_assertions when it hands out instructions; checked by
+     *  skyramp_execute_test, which blocks when the spec is byte-identical to its
+     *  state at handout time (the agent acknowledged the instructions but never
+     *  acted on them). Never supplied by the LLM. */
+    enhanceOutcomes?: Record<string, import("../tools/code-refactor/enhance-state.js").EnhanceRecord>;
+    /** Generation hand-offs that owe a modularize→reuse pass, keyed by the ABSOLUTE
+     *  PATH of each file the generation call wrote (found by snapshotting `outputDir`
+     *  before and after codegen — the agent, not the tool, chooses the file name).
+     *  Written by the generation service at the exact site that emits the hand-off, so
+     *  the debt has the same server-derived trust as `reuseOutcomes`. */
+    reuseHandOffs?: Record<string, ReuseHandOff>;
     /**
      * SKYR-4156. Recorded video per executed browser test, keyed by test-file
      * BASENAME (the same key `reuseOutcomes` uses, so matching needs no path
@@ -319,6 +377,16 @@ export declare class StateManager<T = any> {
     getRepoRepositoryPath(repo?: string): Promise<string | undefined>;
     /** List the related repo keys present in the run-scoped file (empty if single-repo). */
     listRelatedRepos(): Promise<string[]>;
+    /**
+     * Every checkout this run has — the primary plus each related repo — each with
+     * the owner/repo it holds, for callers that resolve a path against "any repo in
+     * the run" rather than one named repo. `relatedRepos` is keyed by owner/repo, so
+     * the key IS that checkout's name; the primary's name comes from its metadata and
+     * can be absent. Reads the state file once, and drops both an absent path and the
+     * `"unknown"` placeholder metadata carries when the path was never resolved, so
+     * every returned entry is a path worth trying.
+     */
+    listRepoCheckouts(): Promise<RepoCheckout[]>;
     getStatePath(): string;
     getSessionId(): string;
     getStateType(): StateType;

package/build/utils/AnalysisStateManager.js

@@ -19,6 +19,21 @@ let _testsRepoDir;
 export function setTestsRepoDir(dir) {
     _testsRepoDir = dir;
 }
+/**
+ * Record the run's tests repo without ever clearing a known value.
+ *
+ * The tests repo is a RUN-scoped fact, but analyze_changes is called once per
+ * repository and only the PRIMARY call carries `testsRepoDir` — a related
+ * repo's call omits it. An unconditional set therefore wiped the primary's
+ * value on the second call of every multi-repo run, and by report time the
+ * tests repo was unknown: a UI test generated there looked unbacked by any
+ * working tree and the agent demoted it out of newTestsCreated (SKYR-4204,
+ * run 32536569467). Callers that mean to clear it use setTestsRepoDir.
+ */
+export function rememberTestsRepoDir(dir) {
+    if (dir)
+        _testsRepoDir = dir;
+}
 export function getTestsRepoDir() {
     return _testsRepoDir;
 }
@@ -98,6 +113,25 @@ export function resolveRunStatePath(explicitPath) {
     }
     return undefined;
 }
+/**
+ * The run's state file if this process is actually serving a run, else undefined.
+ *
+ * Distinct from {@link resolveRunStatePath}, which answers "where would the file
+ * be": the fallback above builds a path from `$RUNNER_TEMP`, and GitHub Actions
+ * sets RUNNER_TEMP on every job — including this repo's own CI, where a resolvable
+ * path is not a run. Callers that gate BEHAVIOUR on being in a run must use this
+ * one; callers that only want to write state can keep using the path, because a
+ * write to a file that holds no run data is already a no-op.
+ *
+ * Returns the path rather than a boolean so a caller can also key per-run state on
+ * it, and lives here because this is the module that decides where the file goes.
+ */
+export function currentRunStateFile() {
+    const stateFile = resolveRunStatePath();
+    return stateFile !== undefined && fs.existsSync(stateFile)
+        ? stateFile
+        : undefined;
+}
 /**
  * In-memory session store: sessionId → { data, storedAt }.
  * Eliminates the need for the LLM to read/write state files on disk.
@@ -119,8 +153,7 @@ function evictStaleSessions() {
         }
     }
     if (inMemorySessionStore.size > MAX_SESSIONS) {
-        const sorted = [...inMemorySessionStore.entries()]
-            .sort((a, b) => a[1].storedAt - b[1].storedAt);
+        const sorted = [...inMemorySessionStore.entries()].sort((a, b) => a[1].storedAt - b[1].storedAt);
         const toDrop = sorted.slice(0, sorted.length - MAX_SESSIONS);
         for (const [id] of toDrop) {
             inMemorySessionStore.delete(id);
@@ -157,7 +190,9 @@ export function normalizeRecommendationState(data) {
     if (!data.analysis && data.apiEndpoints) {
         logger.info("Detected unwrapped RepositoryAnalysis — adapting");
         return {
-            repositoryPath: data.repositoryPath || data.metadata?.repositoryName || "unknown",
+            repositoryPath: data.repositoryPath ||
+                data.metadata?.repositoryName ||
+                "unknown",
             analysisScope: data.analysisScope || data.metadata?.analysisScope,
             analysis: data,
         };
@@ -305,7 +340,9 @@ export class StateManager {
                 },
                 ...(existingRelated ? { relatedRepos: existingRelated } : {}),
             };
-            await fs.promises.mkdir(path.dirname(this.stateFile), { recursive: true });
+            await fs.promises.mkdir(path.dirname(this.stateFile), {
+                recursive: true,
+            });
             await fs.promises.writeFile(this.stateFile, JSON.stringify(state, null, 2), "utf-8");
             logger.debug(`Wrote data to state file: ${this.stateFile}`);
         }
@@ -414,6 +451,31 @@ export class StateManager {
         const full = await this.readFullState();
         return Object.keys(full?.relatedRepos ?? {});
     }
+    /**
+     * Every checkout this run has — the primary plus each related repo — each with
+     * the owner/repo it holds, for callers that resolve a path against "any repo in
+     * the run" rather than one named repo. `relatedRepos` is keyed by owner/repo, so
+     * the key IS that checkout's name; the primary's name comes from its metadata and
+     * can be absent. Reads the state file once, and drops both an absent path and the
+     * `"unknown"` placeholder metadata carries when the path was never resolved, so
+     * every returned entry is a path worth trying.
+     */
+    async listRepoCheckouts() {
+        const full = await this.readFullState();
+        const checkouts = [
+            {
+                root: full?.metadata.repositoryPath,
+                repository: full?.metadata.repository,
+                primary: true,
+            },
+            ...Object.entries(full?.relatedRepos ?? {}).map(([repository, section]) => ({
+                root: section.repositoryPath,
+                repository,
+                primary: false,
+            })),
+        ];
+        return checkouts.flatMap((c) => c.root && c.root !== "unknown" ? [{ ...c, root: c.root }] : []);
+    }
     getStatePath() {
         return this.stateFile;
     }
@@ -457,7 +519,9 @@ export class StateManager {
      */
     static async cleanupOldFiles(maxAgeHours = 24, stateDir, stateTypes) {
         const baseDir = stateDir || runArtifactDir() || os.tmpdir();
-        const files = await fs.promises.readdir(baseDir).catch(() => []);
+        const files = await fs.promises
+            .readdir(baseDir)
+            .catch(() => []);
         const statePrefixes = stateTypes
             ? stateTypes.map((t) => STATE_FILE_PREFIXES[t])
             : Object.values(STATE_FILE_PREFIXES);

package/build/utils/branchDiff.d.ts

@@ -15,6 +15,16 @@ export interface BranchDiffData {
  * Always uses the `b/` form so renames return the new path.
  */
 export declare function parseChangedFilesFromDiff(rawDiff: string): string[];
+/**
+ * Splits a unified diff into per-file added-line arrays, keyed by the `b/`
+ * (post-change) path. Exported so other file->resource-affinity callers
+ * (e.g. `pathAffinityClassification.ts`'s fallback, SKYR-3857) can derive the
+ * same per-file diff hunks this module uses, without re-implementing the
+ * diff-header walk. Lives here rather than in `importerHop.ts`, its original
+ * home, so callers that `importerHop.ts` itself imports can reach it without
+ * an import cycle.
+ */
+export declare function sliceAddedLinesByFile(diffContent: string): Map<string, string[]>;
 /**
  * Normalize and validate a caller-provided base branch/ref before passing it
  * to git. Reject option-like or ambiguous values so the ref is always treated

package/build/utils/branchDiff.js

@@ -13,6 +13,34 @@ export function parseChangedFilesFromDiff(rawDiff) {
     }
     return out;
 }
+/**
+ * Splits a unified diff into per-file added-line arrays, keyed by the `b/`
+ * (post-change) path. Exported so other file->resource-affinity callers
+ * (e.g. `pathAffinityClassification.ts`'s fallback, SKYR-3857) can derive the
+ * same per-file diff hunks this module uses, without re-implementing the
+ * diff-header walk. Lives here rather than in `importerHop.ts`, its original
+ * home, so callers that `importerHop.ts` itself imports can reach it without
+ * an import cycle.
+ */
+export function sliceAddedLinesByFile(diffContent) {
+    const sections = new Map();
+    let currentFile = null;
+    for (const line of diffContent.split("\n")) {
+        const headerMatch = /^diff --git a\/.+ b\/(.+)$/.exec(line);
+        if (headerMatch) {
+            currentFile = headerMatch[1];
+            continue;
+        }
+        if (!currentFile)
+            continue;
+        if (line.startsWith("+") && !line.startsWith("+++")) {
+            const arr = sections.get(currentFile) ?? [];
+            arr.push(line);
+            sections.set(currentFile, arr);
+        }
+    }
+    return sections;
+}
 /** Parse diff headers to find newly created and deleted files. */
 function isShaLikeRef(ref) {
     return /^[0-9a-f]{7,40}$/i.test(ref);