@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/dist/modules/workspace/startup/beside-checkout.js

@@ -0,0 +1,110 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { logger } from '../../../shared/logging.js';
+import { isAbsence } from '../../../shared/fs.contract.js';
+import { printable } from '../../../shared/printable.js';
+const log = logger('kb-startup');
+/** The opening of the boot note, so a test and an operator's grep agree on it. */
+export const BESIDE_CHECKOUT_NOTE = 'Beside the checkout, not in the repository:';
+/**
+ * Name whatever is sitting in a workspace directory other than the checkout —
+ * and touch none of it.
+ *
+ * A workspace directory holds the repository as one folder (`<kbDirName>/`).
+ * Anything else in there is in a location git never sees: never committed,
+ * never pushed, never shared, and invisible in the app once the explorer reads
+ * its roots from the checkout. Nothing the platform accepts can write there any
+ * more — every path goes through the normaliser now — but deployments that ran
+ * the older code already have such files, and the only way anyone learns of
+ * them is if the platform says so. So it says so, once per start, per workspace.
+ *
+ * DELETES NOTHING, MOVES NOTHING, on purpose. The platform cannot prove it
+ * wrote any of it: a stray may be an operator's own scratch file beside a
+ * clone, and a boot that quietly removed it would be a data loss nobody asked
+ * for. The operator cleans up, and the note stops on the next start.
+ *
+ * EVERYTHING other than the checkout folder is named, the platform's own
+ * transient `tmp/` scratch included on the rare start that finds one (a run
+ * clears it when it finishes). That is deliberate: the note's claim is about
+ * what is not in the repository, and a note that quietly kept exceptions would
+ * be a note an operator could not trust.
+ *
+ * NOT a `OnServerStart` step, and deliberately outside the KB startup phase.
+ * That phase is gated — it does nothing until the branch model and the
+ * repository URL are configured, and it is retried on setup completion and
+ * again whenever the remote comes back. A note that lived inside it would be
+ * silent on exactly the deployments most likely to hold strays (setup never
+ * finished, remote unreachable) and would repeat itself on every retry. This
+ * runs ONCE per boot, from the server builder, before that phase, and needs
+ * no remote and no clone: what it reads is already on disk.
+ *
+ * Reads the workspaces root directly rather than through a branch handle: it
+ * needs the directories that are ALREADY on disk, not the branches this build
+ * would clone, and a read-only scan must not be the thing that clones a branch.
+ */
+export async function noteBesideCheckout(workspacesRoot, kbDirName, 
+/** Where the note goes. Injected so a test can read it without a log sink. */
+note = (line) => log.warn(line)) {
+    const workspaces = await entries(workspacesRoot);
+    for (const workspace of workspaces) {
+        if (!workspace.isDirectory())
+            continue;
+        const workspaceDir = path.join(workspacesRoot, workspace.name);
+        const found = [];
+        for (const entry of await entries(workspaceDir)) {
+            // The exemption is the CHECKOUT's, not the name's. A regular file called
+            // `knowledge-base` is not a clone — `WorkspaceService` refuses the
+            // workspace outright as a squatted clone path — so a name-only filter
+            // would hide the one thing an operator has to remove to get the
+            // deployment working. Judged by `stat`, which FOLLOWS links, exactly as
+            // the service judges it: a clone mounted elsewhere is the operator's
+            // business, here as it is there.
+            if (entry.name === kbDirName && (await isDirectory(path.join(workspaceDir, entry.name))))
+                continue;
+            // A trailing slash marks the folders, so one line says which is which
+            // without the operator having to go and look. Then `printable`, because
+            // every name here is disk-controlled text on its way into an operator's
+            // log: one carrying a control character must not steer the terminal or
+            // forge a second line of the note, and the quotes it adds keep a name
+            // with a space or a comma in it readable in the list.
+            found.push(printable(entry.isDirectory() ? `${entry.name}/` : entry.name));
+        }
+        const strays = found.sort();
+        if (strays.length === 0)
+            continue;
+        note(`${BESIDE_CHECKOUT_NOTE} ${strays.join(', ')} — in the workspace for ${printable(workspace.name)}, ` +
+            'outside the git clone, so never committed or pushed. Nothing was deleted or moved; remove them by hand when you have looked.');
+    }
+}
+/**
+ * Whether `p` is a directory, links followed.
+ *
+ * Absence is an answer — a dangling link where the checkout should be is not a
+ * checkout, and saying so is the note's job. Anything else (a permission
+ * failure, an I/O error, a symlink loop) is NOT an answer: swallowing it would
+ * publish "the checkout is a stray" about a path this process could not read.
+ * It is thrown, the same rule {@link entries} keeps, and the boot's diagnostic
+ * handler names the path instead.
+ */
+async function isDirectory(p) {
+    try {
+        return (await fs.stat(p)).isDirectory();
+    }
+    catch (err) {
+        if (isAbsence(err))
+            return false;
+        throw err;
+    }
+}
+/** A directory's entries, or none when it is not there yet (a cold start). */
+async function entries(dir) {
+    try {
+        return await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (isAbsence(err))
+            return [];
+        throw err;
+    }
+}
+//# sourceMappingURL=beside-checkout.js.map

package/dist/modules/workspace/startup/beside-checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beside-checkout.js","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/beside-checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEzD,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;AAEjC,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAAG,6CAA6C,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,cAAsB,EACtB,SAAiB;AACjB,8EAA8E;AAC9E,OAA+B,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;IAEvD,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IACjD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE;YAAE,SAAS;QACvC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QAC/D,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,KAAK,IAAI,MAAM,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YAChD,yEAAyE;YACzE,mEAAmE;YACnE,sEAAsE;YACtE,gEAAgE;YAChE,wEAAwE;YACxE,qEAAqE;YACrE,iCAAiC;YACjC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;gBAAE,SAAS;YACnG,sEAAsE;YACtE,wEAAwE;YACxE,wEAAwE;YACxE,uEAAuE;YACvE,sEAAsE;YACtE,sDAAsD;YACtD,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7E,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAClC,IAAI,CACF,GAAG,oBAAoB,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,2BAA2B,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI;YAClG,8HAA8H,CACjI,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,WAAW,CAAC,CAAS;IAClC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,SAAS,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACjC,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,KAAK,UAAU,OAAO,CAAC,GAAW;IAChC,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,SAAS,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QAC9B,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/modules/workspace/startup/kb-git.d.ts

@@ -1,23 +1,18 @@
+import { type IGitRunner } from '../../../shared/git.contract.js';
 /**
  * The startup phase's own git plumbing — the runner owns every remote and
  * repository operation of the phase (steps only declare buffered ops), so
- * this is deliberately small and self-contained rather than borrowed from
- * the runtime workspace service.
+ * this is deliberately small: the credential and clone-config arguments the
+ * phase needs on every call, over the one git port the rest of the backend
+ * runs through (`shared/git.contract.ts`).
  */
 /** Fallback committer identity; workflow commits override with `--author`. */
 export declare const BOT_NAME = "Bevel Workflow";
 export declare const BOT_EMAIL = "bevel-workflow@bevel.software";
-/**
- * Scrub credentials from anything that reaches a log or an error message:
- * the configured token wherever it appears, and URL userinfo — a remote
- * spelled `https://user:pass@host` would otherwise leak `pass` verbatim
- * through every git failure that quotes the URL back.
- */
-export declare function redactSecret(text: string): string;
-export declare function git(cwd: string, gitUsername: string, args: string[]): Promise<string>;
-export declare function stampIdentity(repo: string, gitUsername: string): Promise<void>;
+export declare function git(runner: IGitRunner, cwd: string, gitUsername: string, args: string[]): Promise<string>;
+export declare function stampIdentity(runner: IGitRunner, repo: string, gitUsername: string): Promise<void>;
 /** Branch names present on the remote, from `ls-remote --heads`. */
-export declare function lsRemoteHeads(repoUrl: string, gitUsername: string): Promise<Set<string>>;
+export declare function lsRemoteHeads(runner: IGitRunner, repoUrl: string, gitUsername: string): Promise<Set<string>>;
 /** A temp dir that is always removed, success or failure. */
 export declare function withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T>;
 //# sourceMappingURL=kb-git.d.ts.map

package/dist/modules/workspace/startup/kb-git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kb-git.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/kb-git.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,QAAQ,mBAAmB,CAAC;AACzC,eAAO,MAAM,SAAS,kCAAkC,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIjD;AA6BD,wBAAsB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB3F;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpF;AAED,oEAAoE;AACpE,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAQ9F;AAED,6DAA6D;AAC7D,wBAAsB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOhF"}
+{"version":3,"file":"kb-git.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/kb-git.ts"],"names":[],"mappings":"AAIA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAI/E;;;;;;GAMG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,QAAQ,mBAAmB,CAAC;AACzC,eAAO,MAAM,SAAS,kCAAkC,CAAC;AAsCzD,wBAAsB,GAAG,CACvB,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAsBjB;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxG;AAED,oEAAoE;AACpE,wBAAsB,aAAa,CACjC,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAQtB;AAED,6DAA6D;AAC7D,wBAAsB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOhF"}

package/dist/modules/workspace/startup/kb-git.js

@@ -1,30 +1,28 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
 import { cloneCredentialArgs, credentialHelperValue } from '../../kb-fs/clone-config.js';
-const execFileAsync = promisify(execFile);
+import { GitRunError } from '../../../shared/git.contract.js';
+import { ClassifiedFailure, classifyGitFailure } from '../../../shared/git-failure.js';
+import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js';
 /**
  * The startup phase's own git plumbing — the runner owns every remote and
  * repository operation of the phase (steps only declare buffered ops), so
- * this is deliberately small and self-contained rather than borrowed from
- * the runtime workspace service.
+ * this is deliberately small: the credential and clone-config arguments the
+ * phase needs on every call, over the one git port the rest of the backend
+ * runs through (`shared/git.contract.ts`).
  */
 /** Fallback committer identity; workflow commits override with `--author`. */
 export const BOT_NAME = 'Bevel Workflow';
 export const BOT_EMAIL = 'bevel-workflow@bevel.software';
 /**
- * Scrub credentials from anything that reaches a log or an error message:
- * the configured token wherever it appears, and URL userinfo — a remote
- * spelled `https://user:pass@host` would otherwise leak `pass` verbatim
- * through every git failure that quotes the URL back.
+ * A stalled remote must FAIL the phase, not hang the boot forever —
+ * fail-closed (and KB_SAFE_BOOT's demotion) can only engage on an error that
+ * actually arrives. Ten minutes is generous for the largest clone, and far
+ * past the port's default, which is sized for a running deployment's
+ * operations rather than a first clone.
  */
-export function redactSecret(text) {
-    const token = process.env.GITHUB_TOKEN;
-    const scrubbed = token ? text.replaceAll(token, '***') : text;
-    return scrubbed.replace(/:\/\/[^/@\s]+@/g, '://***@');
-}
+const STARTUP_GIT_TIMEOUT_MS = 600_000;
 /**
  * Per-invocation `-c` config. Long paths always (Windows checkouts of deep
  * KB trees); when a token is present, an inline credential helper that reads
@@ -52,36 +50,37 @@ function withPersistedCloneConfig(gitUsername, args) {
         return args;
     return [args[0], ...cloneCredentialArgs(gitUsername), ...args.slice(1)];
 }
-export async function git(cwd, gitUsername, args) {
+export async function git(runner, cwd, gitUsername, args) {
+    const argv = [...credArgs(gitUsername), ...withPersistedCloneConfig(gitUsername, args)];
     try {
-        const argv = [...credArgs(gitUsername), ...withPersistedCloneConfig(gitUsername, args)];
-        const { stdout } = await execFileAsync('git', argv, {
-            cwd,
-            // A stalled remote must FAIL the phase, not hang the boot forever —
-            // fail-closed (and KB_SAFE_BOOT's demotion) can only engage on an error
-            // that actually arrives. 10 minutes is generous for the largest clone.
-            timeout: 600_000,
-            // The 1MiB default truncates `ls-remote --heads` on remotes with very
-            // many branches, which would silently drop heads from the phase's view.
-            maxBuffer: 64 * 1024 * 1024,
-            // A credential prompt must fail the phase, not hang the boot forever
-            // waiting on a terminal nobody is watching.
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        // A floor under the configured ceiling, not a replacement for it: an
+        // operator who raised GIT_TIMEOUT_MS past ten minutes gets that here too.
+        const { stdout } = await runner.run(cwd, argv, {
+            timeoutMs: Math.max(runner.defaultTimeoutMs, STARTUP_GIT_TIMEOUT_MS),
         });
-        return stdout.toString();
+        return stdout;
     }
     catch (err) {
+        // Classified here, from what git said — the port's error already names the
+        // subcommand and carries git's stderr in its message — before the scrub
+        // can rewrite it; the message that leaves is the scrubbed one. A remote in
+        // the argv has its query values scrubbed as secrets of their own. The
+        // port's error rides along as the cause: its fields say whether git ran
+        // at all, which the runner reads to tell a missing git from a remote
+        // that would not answer.
         const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(redactSecret(`git ${args[0]} failed: ${msg}`));
+        const raw = err instanceof GitRunError ? msg : `git ${args[0]} failed: ${msg}`;
+        const querySecrets = args.flatMap((arg) => urlQuerySecrets(arg));
+        throw new ClassifiedFailure(redactSecret(raw, querySecrets), classifyGitFailure(raw), { cause: err });
     }
 }
-export async function stampIdentity(repo, gitUsername) {
-    await git(repo, gitUsername, ['config', 'user.name', BOT_NAME]);
-    await git(repo, gitUsername, ['config', 'user.email', BOT_EMAIL]);
+export async function stampIdentity(runner, repo, gitUsername) {
+    await git(runner, repo, gitUsername, ['config', 'user.name', BOT_NAME]);
+    await git(runner, repo, gitUsername, ['config', 'user.email', BOT_EMAIL]);
 }
 /** Branch names present on the remote, from `ls-remote --heads`. */
-export async function lsRemoteHeads(repoUrl, gitUsername) {
-    const out = await git(os.tmpdir(), gitUsername, ['ls-remote', '--heads', repoUrl]);
+export async function lsRemoteHeads(runner, repoUrl, gitUsername) {
+    const out = await git(runner, os.tmpdir(), gitUsername, ['ls-remote', '--heads', repoUrl]);
     const heads = new Set();
     for (const line of out.split('\n')) {
         const m = /\srefs\/heads\/(.+)$/.exec(line.trim());

package/dist/modules/workspace/startup/kb-git.js.map

@@ -1 +1 @@
-{"version":3,"file":"kb-git.js","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/kb-git.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"kb-git.js","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/kb-git.ts"],"names":[],"mappings":"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"}

package/dist/modules/workspace/startup/kb-startup-runner.d.ts

@@ -1,4 +1,6 @@
 import type { OnServerStart } from './on-server-start.js';
+import { type IGitRunner } from '../../../shared/git.contract.js';
+import { ClassifiedFailure, type GitFailure } from '../../../shared/git-failure.js';
 /**
  * The KB startup phase: run every registered {@link OnServerStart} step, in
  * order, against lazily-cloned branch handles, then land one commit per
@@ -22,8 +24,16 @@ import type { OnServerStart } from './on-server-start.js';
  * loudly, at boot and in the log, because an env var outlives the emergency.
  */
 export interface KbStartupRunnerOptions {
+    /** How git is run — see `shared/git.contract.ts`. */
+    gitRunner: IGitRunner;
     kbRepoUrl: () => string;
     gitUsername: () => string;
+    /**
+     * The git token in effect (settings-stored or environment), scrubbed from
+     * every message the phase throws or logs. Optional: `GITHUB_TOKEN` and its
+     * aliases are scrubbed regardless.
+     */
+    gitToken?: () => string;
     workspacesRoot: string;
     kbDirName: string;
     templateDir: string;
@@ -42,14 +52,99 @@ export interface KbStartupRunnerOptions {
         from the commit. */
     buildSeedTree: (dir: string) => Promise<string[]>;
 }
+/**
+ * The remote could not be reached or refused us: a host that is down, a DNS
+ * name that does not resolve, a token that was rotated. Told apart from every
+ * other way the phase can fail because it is the one that says nothing about
+ * the knowledge base — what we would write is not known to be wrong, we
+ * simply cannot get there right now — and so the one a boot may survive:
+ * the deployment comes up gated and unmaintained, and tries again.
+ *
+ * A {@link ClassifiedFailure} that keeps the classification the remote
+ * contact already produced when it has one — `credentials-rejected`,
+ * `not-found` — and is `unreachable` only when nothing more specific is
+ * known. The setup screen shows the remediation for THAT kind, the same one a
+ * setup-time connection test shows for the same token: a rotated token reads
+ * as "the host rejected the credentials", not as a network the server cannot
+ * reach, and the retry loop is not left re-dialing a host that will never
+ * accept it.
+ */
+export declare class KbRemoteUnreachableError extends ClassifiedFailure {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+export interface RetryOptions {
+    /** First wait before trying again. Default 30s. */
+    initialDelayMs?: number;
+    /** The wait doubles up to this. Default 10 minutes. */
+    maxDelayMs?: number;
+    /** Test seam — defaults to `setTimeout` wrapped as a promise, unref'd. */
+    sleep?: (ms: number) => Promise<void>;
+    log?: (message: string) => void;
+}
 export declare class KbStartupRunner {
     private readonly opts;
     constructor(opts: KbStartupRunnerOptions);
+    /** The run in progress, so two invokers share one rather than racing clones. */
+    private inFlight;
+    /** Why the last run failed, redacted; null after a run that finished. */
+    private failure;
+    /** The same failure classified — what the setup screen shows. */
+    private failureKind;
+    /** The phase's last attempt to reach the remote — for the readiness answer. */
+    private remoteContact;
+    /**
+     * {@link redactSecret} plus the token in effect, which may never have reached
+     * the environment. Tokens, URL userinfo and URL query strings go — and the
+     * configured remote's own query values (a presigned remote's credential) are
+     * named as secrets too, so they are scrubbed even where git's text carries
+     * them without the URL around them.
+     */
+    private redact;
+    /**
+     * When this runner last tried the remote and whether it answered. The
+     * phase's `ls-remote` is often the FIRST contact a boot makes, and on a
+     * gated deployment the only one, so a readiness answer that read only the
+     * workspace layer's fetches would call an unreachable remote "ok".
+     */
+    lastRemoteContact(): {
+        at: number;
+        ok: boolean;
+    } | null;
+    /**
+     * Why the most recent run failed, or null when the last run finished — the
+     * gate reads this so a boot that survived an unreachable remote keeps the
+     * deployment shut until a later run succeeds, exactly as a failed
+     * setup-time run does.
+     */
+    lastFailure(): string | null;
+    /** The most recent failure in the terms an admin can act on; null when the last run finished. */
+    lastFailureKind(): GitFailure | null;
     /**
      * Run the whole phase. Throws to stop the boot; returns normally when the
      * KB is fully maintained (or safe boot abandoned the phase, loudly).
+     *
+     * One run at a time: a second caller — the setup save while a background
+     * retry is under way, or the reverse — joins the run in progress rather
+     * than starting another over the same clones.
      */
     runAll(): Promise<void>;
+    /**
+     * Keep running the phase until it finishes, for a boot that survived an
+     * unreachable remote. Safe to run while the process serves, because the
+     * deployment is GATED for as long as `lastFailure` stands: no session can
+     * be holding a working clone the phase would race. Doubles the wait up to a
+     * ceiling — a host that is down for an hour is asked every ten minutes,
+     * not every thirty seconds — and stops on the first success, or on a
+     * failure that is NOT the remote being unreachable: that one says the
+     * knowledge base itself is wrong, and asking again will not change it.
+     * The timer never holds the process open.
+     */
+    retryUntilMaintained(opts?: RetryOptions): {
+        stop(): void;
+    };
+    private runAllOnce;
     /**
      * Remote preparation — runner machinery, not a step, because every remote
      * failure mode here is the runner's to own: an EMPTY remote gets the full

package/dist/modules/workspace/startup/kb-startup-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kb-startup-runner.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/kb-startup-runner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAY,aAAa,EAAsB,MAAM,sBAAsB,CAAC;AAGxF;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IAC3C,8EAA8E;IAC9E,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,oFAAoF;IACpF,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC;;;;;;2BAMuB;IACvB,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACnD;AAED,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,sBAAsB;IAEzD;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA+G7B;;;;;OAKG;YACW,YAAY;IAyE1B,OAAO,CAAC,YAAY;IAkBpB;;;;;;;;OAQG;YACW,WAAW;IA0BzB,6EAA6E;YAC/D,QAAQ;CAoFvB"}
+{"version":3,"file":"kb-startup-runner.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/kb-startup-runner.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAY,aAAa,EAAsB,MAAM,sBAAsB,CAAC;AAExF,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC/E,OAAO,EACL,iBAAiB,EAIjB,KAAK,UAAU,EAChB,MAAM,gCAAgC,CAAC;AAGxC;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,SAAS,EAAE,UAAU,CAAC;IACtB,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IAC3C,8EAA8E;IAC9E,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,oFAAoF;IACpF,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC;;;;;;2BAMuB;IACvB,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,wBAAyB,SAAQ,iBAAiB;gBACjD,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQxD;AAED,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,sBAAsB;IAEzD,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAA8B;IAC9C,yEAAyE;IACzE,OAAO,CAAC,OAAO,CAAuB;IACtC,iEAAiE;IACjE,OAAO,CAAC,WAAW,CAA2B;IAC9C,+EAA+E;IAC/E,OAAO,CAAC,aAAa,CAA4C;IAEjE;;;;;;OAMG;IACH,OAAO,CAAC,MAAM;IAId;;;;;OAKG;IACH,iBAAiB,IAAI;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAIvD;;;;;OAKG;IACH,WAAW,IAAI,MAAM,GAAG,IAAI;IAI5B,iGAAiG;IACjG,eAAe,IAAI,UAAU,GAAG,IAAI;IAIpC;;;;;;;OAOG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBvB;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,IAAI,GAAE,YAAiB,GAAG;QAAE,IAAI,IAAI,IAAI,CAAA;KAAE;YAgEjD,UAAU;IA0HxB;;;;;OAKG;YACW,YAAY;IA+F1B,OAAO,CAAC,YAAY;IAuBpB;;;;;;;;OAQG;YACW,WAAW;IA0BzB,6EAA6E;YAC/D,QAAQ;CAmFvB"}