@codyswann/lisa 4.33.8 → 4.33.10

package/README.md

@@ -264,6 +264,28 @@ Lisa can watch a queue of ready work and dispatch each item through the lifecycl
 > **Prompt for your coding agent**
 > "Which commands let this Lisa scan a work queue, dispatch ready items, repair stuck ones, and report on scheduled-automation health? Show me how I'd point one at my queue and what it expects in configuration."
 
+### Running several agents on one machine
+
+Test runners size themselves to the machine, not to what else is running on it. Left alone, each run claims roughly one worker per core, so *k* agents working at once claim *k* × cores. That is not merely slow: past a certain point the machine starts terminating processes, and a gate that was killed looks exactly like a gate that failed — so an agent "fixes" a phantom, retries, and adds the load that kills the next run.
+
+Lisa caps the pool for you, in three layers:
+
+| layer | what it does | when it applies |
+|---|---|---|
+| **Floor** | Half the machine's cores | Always, when this run is the only one |
+| **Divisor** | Floor ÷ concurrent runs, never below 2 workers | Whenever other Lisa runs are live |
+| **Override** | Exactly the number you give it | Whenever you set it |
+
+You do not have to configure any of this. A run discovers how many sibling runs are live by looking at the shared scratch namespace, so the divisor applies to a fleet nobody told it about. Two variables are available when you want to steer it:
+
+- **`LISA_FLEET_CONCURRENCY`** — state how many runs are coming, rather than letting the run count what has already started. Useful when you are about to launch six agents and want the first one sized for six.
+- **`LISA_VITEST_MAX_WORKERS`** — set the pool size outright. Wins over both other layers, in both directions: raise it above the floor as readily as you lower it.
+
+A smaller pool is not automatically safer, which is why the floor is a proportion rather than a small constant and why the divisor stops at two workers. Below that a suite serialises, every file waits behind every other file, and per-test time budgets start expiring even as machine load falls — trading a visible failure for a subtler one.
+
+> **Prompt for your coding agent**
+> "Show me how this project's test worker pool is sized — find the resolver, tell me what each of the three layers would give on this machine right now, and how many sibling runs it currently detects."
+
 ## Working across trackers and sources
 
 Lisa is deliberately vendor-neutral. The lifecycle runs the same whether your tickets live in one tracker or another and whether your product specs originate in one document tool or another — a thin dispatch layer selects the right integration from configuration, so the workflow you learn transfers.

package/all/copy-overwrite/scripts/lisa-hooks/parity-safety-net.sh

@@ -1690,7 +1690,50 @@ fi
 
 # 13. Dropping or truncating a database / schema / table (Lisa-only guard —
 #     upstream has no SQL protection; keep).
-if matches '\b(drop[[:space:]]+(database|schema|table)|truncate[[:space:]]+(table[[:space:]]+)?[[:alnum:]_."`]+)\b'; then
+#
+# The two arms used to be asymmetric, and only the lopsided one produced false
+# positives (issue #3530). The `drop` arm requires a following keyword —
+# `drop database|schema|table` — so `drop the ball` never matched it. The
+# `truncate` arm made that keyword OPTIONAL:
+#
+#     truncate[[:space:]]+(table[[:space:]]+)?[[:alnum:]_."`]+
+#
+# which reduces to "`truncate`, whitespace, any identifier-ish word", so
+# `truncate the board`, `truncate results` and `truncate output` all matched.
+# A session was refused for a bug-report TITLE describing a connection that
+# truncates results — and a title has no escape hatch, because the remedy this
+# hook prints at the wall (write the text to a file, pass it BY PATH) covers a
+# body, while the title flag of an issue-filing CLI is necessarily inline. The
+# only exit left was to reword, which is what trains people to route around a
+# guard.
+#
+# The fix keeps the coverage and drops the English, in three arms.
+#
+# ARM 1 — `drop`, byte-identical to before. It was already correct, and a
+# rewrite that unified the arms could only make it permissive.
+readonly SQL_DROP='\bdrop[[:space:]]+(database|schema|table)\b'
+# ARM 2 — `truncate` carrying its own evidence that it is a statement rather
+# than a verb: the TABLE keyword (what the drop arm demands), a
+# schema-qualified name, a quoted identifier, a trailing `;`, or one of the
+# tail keywords that only ever follow a TRUNCATE. English has none of these.
+readonly SQL_TRUNCATE_TAIL='(cascade|restrict|restart[[:space:]]+identity|continue[[:space:]]+identity)([^[:alnum:]_]|$)'
+readonly SQL_TRUNCATE_EVIDENCE='\btruncate[[:space:]]+(table[[:space:]]+[[:alnum:]_."`]+|(only[[:space:]]+)?([[:alnum:]_]+\.[[:alnum:]_."`]+|["`][[:alnum:]_. ]+["`]|[[:alnum:]_]+[[:space:]]*(;|'"$SQL_TRUNCATE_TAIL"')))'
+# ARM 3 — the permissive-dialect `TRUNCATE <name>` with none of that evidence.
+# Deleting this shape is what a lazy fix does: it passes every prose scenario
+# while silently removing the coverage a regression fixture already asserts
+# (`mysql -e 'TRUNCATE sessions'`). So it is recognized by CONTEXT instead —
+# the same command must also invoke a command-line database client. Prose in a
+# tracker filing or a commit message invokes none, which is exactly the
+# difference the text scan could not see on its own.
+readonly SQL_CLIENT='(^|[^[:alnum:]_./-])([[:alnum:]_./-]*/)?(psql|pgcli|mysql|mysqladmin|mysqlsh|mariadb|mycli|sqlite3|sqlcmd|cqlsh|clickhouse-client|cockroach|mongosh|duckdb|usql)([[:space:]]|$)'
+readonly SQL_TRUNCATE_BARE='\btruncate[[:space:]]+(only[[:space:]]+)?[[:alnum:]_."`]'
+# Residual, accepted and stated: a bare `TRUNCATE <name>` with no terminator,
+# no qualification and no recognized client in the same command goes unmatched
+# — the same trade the `drop` arm has always made for `drop the ball`. No DROP
+# shape is weakened, and the guard still fails in the safe direction.
+if matches "$SQL_DROP" \
+  || matches "$SQL_TRUNCATE_EVIDENCE" \
+  || { matches "$SQL_CLIENT" && matches "$SQL_TRUNCATE_BARE"; }; then
   block "destructive SQL (DROP/TRUNCATE) detected"
 fi
 

package/all/copy-overwrite/scripts/lisa-work-item.mjs

@@ -25,6 +25,14 @@ const RELEASE_SUBJECT =
   /^chore\(release\): \d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)? \[skip ci\]$/;
 const ZERO_OID = /^0+$/;
 const MARKER = "[lisa-pr-link]";
+/**
+ * The deploy environment whose done role is terminal — the only one that
+ * closes a work item. Named once because three separate readers compare
+ * against it, and a literal repeated three times is three places to drift.
+ */
+const PRODUCTION = "production";
+/** How a base branch that maps to no deploy environment is described. */
+const NOT_A_DEPLOY_BRANCH = "not a deploy branch";
 /**
  * The command that establishes the ticket-side backlink.
  *
@@ -513,8 +521,11 @@ function lifecycleContract(config, provider) {
   // state is called `Done` — a message that sends someone looking for a state
   // that is not what they configured and not what Linear shows them.
   const terminalName = String(terminal ?? "");
+  const byEnvironment = doneRolesByEnvironment(roles.done, terminalName);
   return {
     claimed: requireString(roles.claimed, `${provider} claimed lifecycle role`),
+    done: byEnvironment,
+    productionEnvironment: productionEnvironmentOf(byEnvironment, terminalName),
     ready: requireString(roles.ready, `${provider} ready lifecycle role`),
     roles: lifecycleRoleSet(roles, done),
     terminal: terminalName.toLowerCase(),
@@ -522,6 +533,55 @@ function lifecycleContract(config, provider) {
   };
 }
 
+/**
+ * The done roles keyed by deploy environment, in configured order.
+ *
+ * The single-string form (`done: "Done"`) is a project that names one done
+ * role for every environment, so it is read as the production one — that is
+ * the only environment whose role closes anything.
+ * @param {unknown} done The configured `done` role or role map.
+ * @param {string} terminalName The resolved terminal role's spelling.
+ * @returns {[string, string][]} `[environment, role]` pairs, order preserved.
+ */
+function doneRolesByEnvironment(done, terminalName) {
+  const entries =
+    typeof done === "string"
+      ? [[PRODUCTION, done]]
+      : done && typeof done === "object"
+        ? Object.entries(done)
+        : [];
+  const mapped = entries
+    .map(([environment, role]) => [
+      String(environment).trim().toLowerCase(),
+      typeof role === "string" ? role.trim() : "",
+    ])
+    .filter(([environment, role]) => environment !== "" && role !== "");
+  // A shape this reader could not decompose must never leave the writer with
+  // NO environment to apply, which would refuse every completion in a project
+  // whose `done` nests. The resolved terminal is always an answer.
+  return mapped.length > 0 ? mapped : [[PRODUCTION, terminalName]];
+}
+
+/**
+ * Which of the configured environments is the production one.
+ *
+ * Found by matching the already-resolved TERMINAL ROLE, not by position. The
+ * terminal role is the single existing answer to "which role closes an item",
+ * so deriving the environment from it means the two can never disagree — and
+ * it avoids deriving anything a second, independent way from JSON key order,
+ * which is not semantically meaningful and which no schema constrains.
+ * @param {[string, string][]} byEnvironment `[environment, role]` pairs.
+ * @param {string} terminalName The resolved terminal role's spelling.
+ * @returns {string} The production environment's name.
+ */
+function productionEnvironmentOf(byEnvironment, terminalName) {
+  const folded = terminalName.trim().toLowerCase();
+  const matched = byEnvironment.find(
+    ([, role]) => role.toLowerCase() === folded
+  );
+  return matched?.[0] ?? PRODUCTION;
+}
+
 /**
  * Every lifecycle role a project has configured, in the project's own spelling.
  *
@@ -670,6 +730,46 @@ function verifyLevel(config) {
   return value;
 }
 
+/**
+ * Deploy branches reversed: branch name -> the environment it deploys.
+ *
+ * `deploy.branches` is written env-first (`production: main`) because that is
+ * how a human thinks about it. Every reader here starts from a branch — a
+ * merged pull request's base — and needs the environment, so the map is
+ * inverted once, here, rather than searched at each use.
+ *
+ * **The fallback is deliberate and narrow.** A project that configures no
+ * deploy branches at all is not saying "nothing ever deploys"; it is saying
+ * nothing unusual happens, and its default branch is its production branch.
+ * Treating the absent map as "no branch deploys anything" would refuse every
+ * completion in every project that never wrote the key — a fix that stops
+ * completing anything is not a fix. What the fallback does NOT do is invent an
+ * environment for a branch that is simply not in a map the project DID write:
+ * that is the stacked-integration case, and it is exactly the one that must
+ * not be read as production.
+ * @param {object} config The resolved Lisa configuration.
+ * @returns {Map<string, string>} Branch name to deploy environment.
+ */
+export function deployBranchEnvironments(config) {
+  const configured = config?.deploy?.branches;
+  const entries =
+    configured && typeof configured === "object"
+      ? Object.entries(configured)
+      : [];
+  const mapped = new Map();
+  for (const [environment, branch] of entries) {
+    const name = typeof branch === "string" ? branch.trim() : "";
+    if (name !== "") mapped.set(name, String(environment).trim().toLowerCase());
+  }
+  if (mapped.size > 0) return mapped;
+  const fallback = config?.policy?.repository?.default_branch;
+  const branch =
+    typeof fallback === "string" && fallback.trim() !== ""
+      ? fallback.trim()
+      : "main";
+  return new Map([[branch, PRODUCTION]]);
+}
+
 function trackerContract(config = readConfig()) {
   const provider = requireString(config.tracker, "tracker").toLowerCase();
   const identityRepo = currentRepoIdentity(config);
@@ -686,6 +786,7 @@ function trackerContract(config = readConfig()) {
       provider,
       repository,
       identityRepo,
+      deployBranches: deployBranchEnvironments(config),
       verify: verifyLevel(config),
       lifecycle: lifecycleContract(config, provider),
       repositoryIsIdentity:
@@ -3127,9 +3228,193 @@ function githubTimeline(ref) {
 }
 
 /**
- * Move a work item to its configured terminal role and close it.
+ * The branch a merged pull request was merged INTO.
  *
- * The terminal role is RESOLVED from configuration, never assumed. Lisa's own
+ * A second call per pull request, because the timeline cannot answer it: a
+ * `cross-referenced` event carries the referencing item in ISSUE shape, and an
+ * issue has no base branch. Reading the base is the whole point — without it
+ * "a merged pull request references this item" is the only evidence there is,
+ * and that sentence is true of a merge into an integration branch that shipped
+ * nothing.
+ * @param {string} repository `owner/name` the pull request belongs to.
+ * @param {number} number The pull-request number.
+ * @returns {string} The base branch name, empty when it could not be read.
+ */
+function pullRequestBaseBranch(repository, number) {
+  const result = run(
+    "gh",
+    ["api", `repos/${repository}/pulls/${number}`, "--jq", ".base.ref"],
+    { allowFailure: true }
+  );
+  if (result.status !== 0)
+    throw githubFailure(result, `${repository}#${number}`);
+  return result.stdout.trim();
+}
+
+/**
+ * Decide which lifecycle role a set of merged pull requests has earned.
+ *
+ * The defect this exists to end: completion read "is there a merged pull
+ * request referencing this item" and never asked which branch it merged into,
+ * so a stacked pull request landing on an integration branch stamped the
+ * PRODUCTION terminal role and closed the item. Nothing had reached the deploy
+ * branch and nothing had deployed, but every recovery flow — sweep, repair
+ * intake, the rollup reconcilers — reads a closed item carrying the terminal
+ * role as finished, so the corruption is in the direction that stops recovery
+ * from firing.
+ *
+ * **Production is recognised, never ranked.** An earlier draft of this
+ * function ordered environments by their POSITION in the configured `done`
+ * map, which makes correctness depend on JSON key order — not semantically
+ * meaningful, constrained by no schema, and able to fail in the direction of
+ * writing the WRONG TERMINAL ROLE rather than merely refusing, which is the
+ * original defect with extra steps. So the only distinction drawn here is
+ * production versus not: a merge into the production environment is terminal,
+ * a single non-production environment records its own role, and several
+ * different non-production environments are reported rather than ranked. That
+ * is enough, because the role this ticket is about is the terminal one.
+ *
+ * Pure and exported so the decision can be asserted without a network.
+ * @param {{base: string, number: number}[]} pullRequests Merged pull requests.
+ * @param {Map<string, string>} branchEnvironments Branch to deploy environment.
+ * @param {{done: [string, string][], productionEnvironment: string}} lifecycle
+ *   The resolved lifecycle contract.
+ * @returns {{ambiguous: boolean, environment: string|null, evidence: {base: string, environment: string|null, number: number}[], role: string|null, terminal: boolean}}
+ *   The role earned, or a null role when nothing was earned or nothing ranks.
+ */
+export function mergedBaseDecision(
+  pullRequests,
+  branchEnvironments,
+  lifecycle
+) {
+  const roles = new Map(lifecycle?.done ?? []);
+  const production = lifecycle?.productionEnvironment;
+  const evidence = (pullRequests ?? []).map(request => {
+    const base = String(request?.base ?? "");
+    return {
+      base,
+      environment: branchEnvironments?.get(base) ?? null,
+      number: request?.number,
+    };
+  });
+  const reached = [
+    ...new Set(
+      evidence
+        .map(entry => entry.environment)
+        .filter(environment => roles.has(environment))
+    ),
+  ];
+  if (reached.includes(production)) {
+    return {
+      ambiguous: false,
+      environment: production,
+      evidence,
+      role: roles.get(production),
+      terminal: true,
+    };
+  }
+  // Exactly one non-production environment is unambiguous. Two different ones
+  // would need an ordering the configuration does not state, so they are
+  // reported instead of guessed at.
+  if (reached.length !== 1) {
+    return {
+      ambiguous: reached.length > 1,
+      environment: null,
+      evidence,
+      role: null,
+      terminal: false,
+    };
+  }
+  return {
+    ambiguous: false,
+    environment: reached[0],
+    evidence,
+    role: roles.get(reached[0]),
+    terminal: false,
+  };
+}
+
+/**
+ * Name every merged pull request and the branch it landed on.
+ *
+ * An operator reading a run that completed nothing has to be able to tell WHY
+ * without opening the code, and "which branch did it actually merge into" is
+ * the whole answer.
+ * @param {{base: string, environment: string|null, number: number}[]} evidence
+ *   What each merged pull request was observed to target.
+ * @returns {string} A readable one-line summary.
+ */
+function describeMergeBases(evidence) {
+  return evidence
+    .map(
+      entry =>
+        `#${entry.number} -> ${entry.base || "(unknown base)"} [${entry.environment ?? NOT_A_DEPLOY_BRANCH}]`
+    )
+    .join(", ");
+}
+
+/**
+ * Name the branches this project does deploy, and which one it took to be
+ * production.
+ *
+ * Naming the production branch explicitly is what makes a wrong ASSUMPTION
+ * visible. A project that never wrote `deploy.branches` has its default branch
+ * read as production; if that is not its real production branch, every
+ * completion refuses and the operator has to be able to see the assumption in
+ * the refusal rather than infer it from a list.
+ * @param {Map<string, string>} branchEnvironments Branch to deploy environment.
+ * @param {string} production The production environment's name.
+ * @returns {string} A readable list, with the production branch called out.
+ */
+function describeDeployBranches(branchEnvironments, production) {
+  const listed =
+    [...branchEnvironments]
+      .map(([branch, environment]) => `${branch} [${environment}]`)
+      .join(", ") || "(none configured)";
+  const [productionBranch] =
+    [...branchEnvironments].find(
+      ([, environment]) => environment === production
+    ) ?? [];
+  return productionBranch === undefined
+    ? `${listed}; no branch maps to "${production}"`
+    : `${listed}; production is taken to be "${productionBranch}"`;
+}
+
+/**
+ * Record a deploy role that is NOT the production terminal.
+ *
+ * Adds the environment's role and stops. It deliberately does not close the
+ * item and does not retire the claimed role: the work is genuinely still in
+ * flight until it reaches the production branch, and native closure fires only
+ * at the production terminal.
+ * @param {string} ref Canonical work-item reference.
+ * @param {{labels: string[]}} before The pre-write tracker state.
+ * @param {string} role The environment's configured done role.
+ * @returns {void}
+ */
+function recordDeployRole(ref, before, role) {
+  if (carriesLabel(before.labels, role)) return;
+  const [repository, number] = ref.split("#");
+  const edited = run(
+    "gh",
+    [
+      "issue",
+      "edit",
+      String(number),
+      "--repo",
+      repository,
+      "--add-label",
+      role,
+    ],
+    { allowFailure: true }
+  );
+  if (edited.status !== 0) throw githubFailure(edited, ref);
+}
+
+/**
+ * Move a work item to the lifecycle role its merges have actually earned.
+ *
+ * The role is RESOLVED from configuration, never assumed. Lisa's own
  * repository maps `production` to `status:done`, but the map is environment
  * aware — a project whose target is `dev` has a different terminal role, and a
  * hardcoded label would silently apply the wrong one there while looking
@@ -3139,9 +3424,18 @@ function githubTimeline(ref) {
  * is pointed at is a way to make unfinished work disappear, which is the same
  * defect class as a gate that passes because it found nothing. Evidence is a
  * merged pull request in this repository.
+ *
+ * **And a merged pull request is not evidence on its own.** The base branch it
+ * merged into decides which role it earned: only a merge into the production
+ * deploy branch is terminal. A merge into an integration branch records the
+ * environment's role at most, and a merge into a branch this project does not
+ * deploy at all records nothing and closes nothing — reported, never silent,
+ * because a completion that quietly did not happen is the same failure as one
+ * that wrongly did.
  * @param {string} ref Canonical work-item reference.
  * @param {object} contract The resolved tracker contract.
- * @returns {{merged: number[], terminal: string}} What was applied, and why.
+ * @returns {{applied: boolean, merged: number[], report: string, terminal: string|null}}
+ *   What was applied, and why.
  */
 function completeGithubWorkItem(ref, contract) {
   const [repository] = ref.split("#");
@@ -3154,11 +3448,51 @@ function completeGithubWorkItem(ref, contract) {
         `from a real one afterwards. If the work shipped some other way, say so on the item and close it deliberately.`
     );
   }
+  const decision = mergedBaseDecision(
+    merged.map(number => ({
+      base: pullRequestBaseBranch(repository, number),
+      number,
+    })),
+    contract.deployBranches,
+    contract.lifecycle
+  );
+  const evidence = merged.map(number => `#${number}`).join(", ");
+  const bases = describeMergeBases(decision.evidence);
+  if (decision.role === null) {
+    const why = decision.ambiguous
+      ? `Several different non-production deploy environments were reached, and the configuration states\n` +
+        `no ordering between them, so this writer reports them rather than guessing which is furthest.`
+      : `No merged pull request reached a branch this project deploys, so no lifecycle role was\n` +
+        `applied and ${ref} stays open. It completes when the change reaches a deploy branch.`;
+    return {
+      applied: false,
+      bases,
+      merged,
+      report:
+        `work-item NOT completed: ${ref} (merged: ${evidence}) bases: ${bases}\n` +
+        `${why}\n` +
+        `Deploy branches: ${describeDeployBranches(contract.deployBranches, contract.lifecycle.productionEnvironment)}.\n` +
+        `If that production branch is wrong, "deploy.branches" in .lisa.config.json is what to fix.`,
+      terminal: null,
+    };
+  }
   const before = githubLifecycleState(
     ref,
     `GitHub issue ${ref} completion read`
   );
   assertNotAbandoned(ref, before);
+  if (!decision.terminal) {
+    recordDeployRole(ref, before, decision.role);
+    return {
+      applied: true,
+      bases,
+      merged,
+      report:
+        `work-item advanced: ${ref} -> ${decision.role} (merged: ${evidence}) bases: ${bases}\n` +
+        `${decision.environment} is not the production environment, so ${ref} stays open.`,
+      terminal: decision.role,
+    };
+  }
   reconcileGithubLifecycle(ref, before, contract);
   // A SECOND read, deliberately. The edit and the close each reported their own
   // success, and a writer that trusts those is asserting about tracker state it
@@ -3168,7 +3502,13 @@ function completeGithubWorkItem(ref, contract) {
     `GitHub issue ${ref} completion readback`
   );
   assertCompletionReadback(ref, after, contract);
-  return { merged, terminal: contract.lifecycle.terminalName };
+  return {
+    applied: true,
+    bases,
+    merged,
+    report: `work-item completed: ${ref} -> ${contract.lifecycle.terminalName} (merged: ${evidence}) bases: ${bases}`,
+    terminal: contract.lifecycle.terminalName,
+  };
 }
 
 /**
@@ -3582,11 +3922,15 @@ function complete(args) {
   }
   const ref = canonicalizeRef(supplied ?? bound, contract);
   const prUrl = pullRequestUrlOption(args);
-  const { merged, terminal } = completeWorkItem(ref, contract, prUrl);
+  const outcome = completeWorkItem(ref, contract, prUrl);
+  // The writer composes its own sentence when the base branch shaped the
+  // outcome, because only the writer knows which bases it read. The Linear
+  // path has no such decision to report, so it keeps the original line.
   console.log(
-    `work-item completed: ${ref} -> ${terminal} (merged: ${merged
-      .map(number => `#${number}`)
-      .join(", ")})`
+    outcome.report ??
+      `work-item completed: ${ref} -> ${outcome.terminal} (merged: ${outcome.merged
+        .map(number => `#${number}`)
+        .join(", ")})`
   );
 }
 
@@ -3645,8 +3989,15 @@ function sweep(args) {
       console.log(`DRIFT  ${ref}  merged: ${evidence}  ${issue.title}`);
       continue;
     }
-    const { terminal } = completeWorkItem(ref, contract);
-    console.log(`completed ${ref} -> ${terminal}  (merged: ${evidence})`);
+    const outcome = completeWorkItem(ref, contract);
+    // A sweep must not abort on the first item whose merges have not reached a
+    // deploy branch. It reports that item and carries on, which is what makes
+    // the backstop safe to run over a whole queue.
+    console.log(
+      outcome.applied
+        ? `completed ${ref} -> ${outcome.terminal}  (merged: ${evidence}) bases: ${outcome.bases}`
+        : outcome.report
+    );
   }
   if (drifted === 0) {
     console.log(

package/dist/configs/vitest/base.d.ts

@@ -93,11 +93,18 @@ export declare function worktreeExclusions(): readonly string[];
  */
 export declare const MAX_WORKERS_OVERRIDE_VAR = "LISA_VITEST_MAX_WORKERS";
 /**
- * Environment variable naming how many concurrent runs share this machine.
+ * Environment variable stating how many concurrent runs share this machine.
  *
- * Set by whatever launches a fleet of agents. Absent for an ordinary developer,
- * which is the point: the divisor applies only when something states that this
- * run is one of several, so the single-run case is never throttled by it.
+ * Optional, and it is a statement of INTENT rather than an observation: "six
+ * runs are coming", which is knowledge a count of what is live right now cannot
+ * have. So it outranks {@link discoverFleetConcurrency} when present.
+ *
+ * It is no longer the only way the divisor is reached, and that correction is
+ * the whole of #3665. Shipped as the sole mechanism, it was set by nothing —
+ * one occurrence in the tree, its own declaration — so the divisor was inert
+ * for every consumer and the cap arrived as floor-only. Discovery is the layer
+ * that reaches a run nobody configured; this variable is now the way to
+ * override what discovery sees.
  */
 export declare const FLEET_CONCURRENCY_VAR = "LISA_FLEET_CONCURRENCY";
 /**
@@ -122,6 +129,56 @@ export declare const DEFAULT_MAX_WORKERS = "50%";
  * a visible kill for an invisible timeout has not helped anyone.
  */
 export declare const MIN_FLEET_WORKERS = 2;
+/**
+ * How many Lisa test runs are live on this machine right now, including this one.
+ *
+ * ## Why this is discovered rather than declared
+ *
+ * The divisor shipped as an explicit signal, and for a release nothing set it:
+ * `LISA_FLEET_CONCURRENCY` occurred exactly once in the tree, at its own
+ * declaration. So the cap reached every consumer as floor-only, and the layer
+ * that addresses multi-agent contention was inert by default
+ * (CodySwannGT/lisa#3665).
+ *
+ * The obvious repair — pick a component and have it export the variable — fails
+ * its own test. **Nothing knows how many runs it is about to start.** Agents are
+ * launched independently, each in its own worktree, by whoever happens to be
+ * driving; there is no scheduler holding that number. A setter would have to
+ * guess, and a guessed fleet size that goes stale the moment the fleet resizes
+ * is a worse contract than no setter at all.
+ *
+ * What every run *can* do is look. Each supervised run already registers a
+ * `run-<pid>-<epoch>-<suffix>` root inside one namespace under `os.tmpdir()`,
+ * which on this platform is per-user and therefore shared by every checkout on
+ * the machine. Counting the roots whose owning process is still alive answers
+ * the question at the only moment it matters — when this run is about to size
+ * its pool — without anybody having to know the answer in advance.
+ *
+ * ## Fail open, never closed
+ *
+ * This runs inside a Vitest config factory, so a throw here does not degrade a
+ * test run, it prevents one. Every failure path returns 1 (no fleet detected),
+ * which yields the floor — the behaviour that shipped. An unreadable namespace,
+ * a permission error, a platform without `process.kill`, an absent directory on
+ * the very first run: all of them mean "no evidence of siblings", never "assume
+ * the worst and throttle".
+ *
+ * Our own pid is excluded rather than subtracted, because the config may load
+ * before or after this run registers its own root, and both orders must give
+ * the same count. The result adds one back for this run.
+ * @param deps - Injectable seams so tests state a fleet instead of spawning one.
+ * @param deps.namespaceDir - Directory holding run roots.
+ * @param deps.readDir - Directory lister.
+ * @param deps.isAlive - Process-liveness probe.
+ * @param deps.self - This process's id.
+ * @returns Live run count including this one; 1 when nothing else is detected.
+ */
+export declare function discoverFleetConcurrency(deps?: {
+    namespaceDir?: () => string;
+    readDir?: (dir: string) => readonly string[];
+    isAlive?: (pid: number) => boolean;
+    self?: number;
+}): number;
 /**
  * Resolves the Vitest worker-pool cap for this run.
  *
@@ -142,14 +199,21 @@ export declare const MIN_FLEET_WORKERS = 2;
  * recorded, not hypothesised — see {@link MIN_FLEET_WORKERS}. So the resolution
  * has three layers, and only the middle one knows about the fleet:
  *
- * 1. **Floor.** {@link DEFAULT_MAX_WORKERS}, always. This is the only layer that
- *    reaches a run nobody configured, which is most of them.
- * 2. **Divisor.** When {@link FLEET_CONCURRENCY_VAR} states that this run is one
- *    of *k*, the floor is divided by *k* so the fleet's total pool is bounded by
- *    the machine rather than multiplied by its own size — never below
- *    {@link MIN_FLEET_WORKERS}.
+ * 1. **Floor.** {@link DEFAULT_MAX_WORKERS}, when this run is the only one.
+ * 2. **Divisor.** The floor divided by the number of concurrent runs, so the
+ *    fleet's total pool is bounded by the machine rather than multiplied by its
+ *    own size — never below {@link MIN_FLEET_WORKERS}. That number comes from
+ *    {@link FLEET_CONCURRENCY_VAR} when something states it, and otherwise from
+ *    {@link discoverFleetConcurrency}, which counts live sibling runs.
+ *    Discovery is what makes this layer reach a run nobody configured; as an
+ *    opt-in signal it reached nothing for a release (#3665).
  * 3. **Override.** {@link MAX_WORKERS_OVERRIDE_VAR} replaces both, upward or
  *    downward.
+ *
+ * A stated signal outranks discovery rather than being reconciled with it. An
+ * operator who says "we are six" is describing an intent — six runs are coming,
+ * even if only two have started — and a count of what happens to be live right
+ * now must not quietly contradict it.
  * ## Why the environment is imported rather than reached for
  *
  * The default comes from `node:process`'s `env` binding, not from the ambient
@@ -162,9 +226,10 @@ export declare const MIN_FLEET_WORKERS = 2;
  * parameter injectable so tests state an environment rather than mutating one.
  * @param environment - Environment to read; defaults to this process's.
  * @param cores - Logical cores available; defaults to this machine's count.
+ * @param discover - Fleet-size discovery; defaults to counting live run roots.
  * @returns A value for Vitest's `maxWorkers` — a worker count, or a percentage.
  */
-export declare function resolveMaxWorkers(environment?: NodeJS.ProcessEnv, cores?: number): number | string;
+export declare function resolveMaxWorkers(environment?: NodeJS.ProcessEnv, cores?: number, discover?: () => number): number | string;
 /**
  * Setup files that bound and reclaim the suite's temporary directories.
  *

package/dist/configs/vitest/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/configs/vitest/base.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpD,8DAA8D;AAC9D,KAAK,UAAU,GAAG,cAAc,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE;QACd,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,kBAO/B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAatD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAGlD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,IAAI,SAAS,MAAM,EAAE,CAItD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAenC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,GAAE,MAAM,CAAC,UAAgB,EACpC,KAAK,GAAE,MAA+B,GACrC,MAAM,GAAG,MAAM,CASjB;AAoBD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAKrD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,SAAS,MAAM,EAAE,CAEtD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACxB,YAAY,kBAAkB,KAC7B,gBAaD,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,kBAAkB,EAC5B,WAAW,kBAAkB,KAC5B,kBAiBF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,GAAG,SAAS,UAAU,EAAE,KAAG,UA4C7D,CAAC"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/configs/vitest/base.ts"],"names":[],"mappings":"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"}