@bevel-software/platform-core-backend 0.21.0 → 0.23.0

package/dist/modules/workspace/agent-access.gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-access.gate.js","sourceRoot":"","sources":["../../../src/modules/workspace/agent-access.gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GACjC,4VAA4V,CAAC;AAE/V;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAe;IAC1C,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,sBAAsB;CACpC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,OAAO,oBAAoB;IACvB,SAAS,GAAG,EAAE,CAAC;IACf,SAAS,GAAG,EAAE,CAAC;IACN,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IAEnD,4DAA4D;IAC5D,qBAAqB,CAAC,IAAY;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAED,iEAAiE;IACjE,qBAAqB,CAAC,IAAY;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAED,oEAAoE;IACpE,aAAa;QACX,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,8EAA8E;IAC9E,oBAAoB;QAClB,OAAO,sBAAsB,GAAG,IAAI,CAAC,SAAS,CAAC;IACjD,CAAC;IAED,mFAAmF;IACnF,QAAQ,CAAC,QAAoB;QAC3B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAEO,QAAQ;QACd,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS;YAAE,QAAQ,EAAE,CAAC;IACpD,CAAC;CACF;AAgBD,gFAAgF;AAChF,SAAS,aAAa,CAAC,GAAgB;IACrC,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,IAAI,GAAG,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CACvB,IAAqB,EACrB,GAAgB,EAChB,MAAc,EACd,MAAe;IAEf,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,gBAAgB;QAAE,OAAO,IAAI,CAAC;IACxE,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAqB,EACrB,GAAgB,EAChB,MAAc,EACd,MAAc;IAEd,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO;IACxB,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,IAAqB,EACrB,GAAgB,EAChB,MAAc,EACd,MAAe;IAEf,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO;IACxB,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/modules/workspace/routine-write-policy.d.ts

@@ -1,9 +1,9 @@
 /**
  * Per-run write restriction for background/routine agents.
  *
- * The ontology-session gate ({@link ../workflow/session-ontology.service}) bounds
- * WHICH ontology a run may write; this narrower gate bounds WHAT KIND of file a
- * run may write, by extension. It exists for the `watchlist_check` routine, which is
+ * The agent-access gate ({@link ./agent-access.gate}) lets a deployment decide
+ * WHETHER a run may write a path at all; this narrower gate bounds WHAT KIND of
+ * file a run may write, by extension. It exists for the `watchlist_check` routine, which is
  * allowed to refresh dashboard views (`.html`) but must never touch the
  * knowledge-graph nodes (`.md`) or any other file — a hard, code-level guarantee
  * rather than a prompt request (a prompt-only rule has already proven insufficient).
@@ -11,9 +11,8 @@
  * Keyed by the agent run's `sessionId` (the background agent passes its run id as
  * the session id, which the internal token then carries onto every loopback tool
  * call as `ctx.sessionId`). A restriction lives only for the duration of one
- * in-process run, so the store is a plain in-memory map — no durability needed,
- * unlike the ontology touched-set which must survive restarts and span the MCP
- * proxy. The executor sets the restriction before streaming and clears it after.
+ * in-process run, so the store is a plain in-memory map — no durability needed.
+ * The executor sets the restriction before streaming and clears it after.
  */
 export interface IRoutineWritePolicy {
     /**

package/dist/modules/workspace/routine-write-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routine-write-policy.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/routine-write-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAC7E,wDAAwD;IACxD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;OAIG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACxE;;;;OAIG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;CACzD;AAED,qBAAa,yBAA0B,YAAW,mBAAmB;IACnE,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;IAE/D,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAI5E,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9B,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAcvE,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;CAQxD"}
+{"version":3,"file":"routine-write-policy.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/routine-write-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAC7E,wDAAwD;IACxD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;OAIG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACxE;;;;OAIG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;CACzD;AAED,qBAAa,yBAA0B,YAAW,mBAAmB;IACnE,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;IAE/D,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAI5E,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9B,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAcvE,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;CAQxD"}

package/dist/modules/workspace/routine-write-policy.js

@@ -1,9 +1,9 @@
 /**
  * Per-run write restriction for background/routine agents.
  *
- * The ontology-session gate ({@link ../workflow/session-ontology.service}) bounds
- * WHICH ontology a run may write; this narrower gate bounds WHAT KIND of file a
- * run may write, by extension. It exists for the `watchlist_check` routine, which is
+ * The agent-access gate ({@link ./agent-access.gate}) lets a deployment decide
+ * WHETHER a run may write a path at all; this narrower gate bounds WHAT KIND of
+ * file a run may write, by extension. It exists for the `watchlist_check` routine, which is
  * allowed to refresh dashboard views (`.html`) but must never touch the
  * knowledge-graph nodes (`.md`) or any other file — a hard, code-level guarantee
  * rather than a prompt request (a prompt-only rule has already proven insufficient).
@@ -11,9 +11,8 @@
  * Keyed by the agent run's `sessionId` (the background agent passes its run id as
  * the session id, which the internal token then carries onto every loopback tool
  * call as `ctx.sessionId`). A restriction lives only for the duration of one
- * in-process run, so the store is a plain in-memory map — no durability needed,
- * unlike the ontology touched-set which must survive restarts and span the MCP
- * proxy. The executor sets the restriction before streaming and clears it after.
+ * in-process run, so the store is a plain in-memory map — no durability needed.
+ * The executor sets the restriction before streaming and clears it after.
  */
 import { ToolError } from '../tool-helpers/tool.contract.js';
 export class RoutineWritePolicyService {

package/dist/modules/workspace/routine-write-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"routine-write-policy.js","sourceRoot":"","sources":["../../../src/modules/workspace/routine-write-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AA0B7D,MAAM,OAAO,yBAAyB;IACpC,wEAAwE;IACvD,YAAY,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE/D,oBAAoB,CAAC,SAAiB,EAAE,UAA6B;QACnE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;IACpF,CAAC;IAED,KAAK,CAAC,SAAiB;QACrB,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED,kBAAkB,CAAC,SAA6B,EAAE,MAAc;QAC9D,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACzE,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;QACnC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,OAAO;QAClC,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,2BAA2B,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,8BAA8B,MAAM,gBAAgB;YACpG,uEAAuE,EACzE,GAAG,CACJ,CAAC;IACJ,CAAC;IAED,kBAAkB,CAAC,SAA6B;QAC9C,IAAI,SAAS,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,SAAS,CACjB,sHAAsH,EACtH,GAAG,CACJ,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"routine-write-policy.js","sourceRoot":"","sources":["../../../src/modules/workspace/routine-write-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AA0B7D,MAAM,OAAO,yBAAyB;IACpC,wEAAwE;IACvD,YAAY,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE/D,oBAAoB,CAAC,SAAiB,EAAE,UAA6B;QACnE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;IACpF,CAAC;IAED,KAAK,CAAC,SAAiB;QACrB,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED,kBAAkB,CAAC,SAA6B,EAAE,MAAc;QAC9D,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACzE,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;QACnC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,OAAO;QAClC,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,2BAA2B,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,8BAA8B,MAAM,gBAAgB;YACpG,uEAAuE,EACzE,GAAG,CACJ,CAAC;IACJ,CAAC;IAED,kBAAkB,CAAC,SAA6B;QAC9C,IAAI,SAAS,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,SAAS,CACjB,sHAAsH,EACtH,GAAG,CACJ,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/modules/workspace/session-sink.d.ts

@@ -1,10 +1,10 @@
 /**
- * Port behind `start_session` (workspace.tools.ts): mints the session id an
- * external agent scopes its ontology boundary under. The workspace module owns
- * the port; WHAT backs the id is the composition root's choice:
+ * Port behind `start_session` (workspace.tools.ts): mints the id an external
+ * agent names its conversation with. The workspace module owns the port; WHAT
+ * backs the id is the composition root's choice:
  *
- * - Core default ({@link UuidSessionSink}): a bare random id — sufficient for
- *   the session-ontology gate, with no app-side session record.
+ * - Core default ({@link UuidSessionSink}): a bare random id — all the
+ *   agent-access hooks need, with no app-side session record.
  * - The enterprise app substitutes a sink that mints a REAL chat thread, so the
  *   same id also works end to end with `ask` (its sessionId IS a chat thread).
  *   See the `start_session` comment in workspace.tools.ts for why that

package/dist/modules/workspace/set-aside-clone.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Moving a working copy of a repository that is no longer the configured one
+ * OUT OF THE WAY, rather than deleting it.
+ *
+ * Two places find such a clone: the KB startup phase, sweeping the whole
+ * workspaces root at boot and on the save that changes the address, and the
+ * workspace service, refusing to adopt one it finds on disk. Both must do the
+ * same thing with it, because what is in it is the same thing: commits that
+ * may exist nowhere else. A clone fetches and pushes through the address in
+ * its own `remote.origin.url`, and two repositories need not share a commit,
+ * so such a clone cannot be re-pointed — but that is a reason not to USE it,
+ * never a reason to destroy it.
+ */
+/**
+ * Where working copies are set aside. NOT under the workspaces root: the
+ * workspace service's orphan sweep removes every folder there that is not a
+ * known branch's, and what is set aside has to outlive that sweep.
+ *
+ * PASS THE OVERRIDE, and pass BOTH CALLERS THE SAME ONE. The fallback is a
+ * sibling of the workspaces root, which is a lasting place only when that
+ * parent is itself a mounted volume — in the shipped compose file it is the
+ * container's own filesystem, so a copy left there is gone at the next
+ * recreate, having been kept on the promise that it would not be. The
+ * composition root therefore roots both the startup phase and the workspace
+ * service at one directory under the backups volume; the fallback is for a
+ * test, or a caller with no deployment layout to speak of.
+ */
+export declare function setAsideRootFor(workspacesRoot: string, override?: string): string;
+/**
+ * One folder per occasion, so what was set aside together stays together and
+ * two replacements never land in each other's folder.
+ */
+export declare function setAsideStamp(at?: Date): string;
+/**
+ * Move the clone at `repoDir` to `dest`. A rename when it can be one; a copy
+ * when it cannot (another volume, a handle held open on it), and only then is
+ * the original removed — so a copy that fails leaves the clone exactly where
+ * it was rather than half of it in each place.
+ *
+ * Throws with what to do about it. The caller decides how much that costs:
+ * the startup phase stops the boot (leaving the clone would fail a step later
+ * with git's words about a repository nobody configured), while a single
+ * branch open refuses that branch.
+ */
+export declare function setAsideClone(repoDir: string, dest: string): Promise<void>;
+//# sourceMappingURL=set-aside-clone.d.ts.map

package/dist/modules/workspace/set-aside-clone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-aside-clone.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/set-aside-clone.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAAE,GAAE,IAAiB,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyChF"}

package/dist/modules/workspace/set-aside-clone.js

@@ -0,0 +1,92 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+/**
+ * Moving a working copy of a repository that is no longer the configured one
+ * OUT OF THE WAY, rather than deleting it.
+ *
+ * Two places find such a clone: the KB startup phase, sweeping the whole
+ * workspaces root at boot and on the save that changes the address, and the
+ * workspace service, refusing to adopt one it finds on disk. Both must do the
+ * same thing with it, because what is in it is the same thing: commits that
+ * may exist nowhere else. A clone fetches and pushes through the address in
+ * its own `remote.origin.url`, and two repositories need not share a commit,
+ * so such a clone cannot be re-pointed — but that is a reason not to USE it,
+ * never a reason to destroy it.
+ */
+/**
+ * Where working copies are set aside. NOT under the workspaces root: the
+ * workspace service's orphan sweep removes every folder there that is not a
+ * known branch's, and what is set aside has to outlive that sweep.
+ *
+ * PASS THE OVERRIDE, and pass BOTH CALLERS THE SAME ONE. The fallback is a
+ * sibling of the workspaces root, which is a lasting place only when that
+ * parent is itself a mounted volume — in the shipped compose file it is the
+ * container's own filesystem, so a copy left there is gone at the next
+ * recreate, having been kept on the promise that it would not be. The
+ * composition root therefore roots both the startup phase and the workspace
+ * service at one directory under the backups volume; the fallback is for a
+ * test, or a caller with no deployment layout to speak of.
+ */
+export function setAsideRootFor(workspacesRoot, override) {
+    return override ?? path.resolve(workspacesRoot, '..', 'replaced-working-copies');
+}
+/**
+ * One folder per occasion, so what was set aside together stays together and
+ * two replacements never land in each other's folder.
+ */
+export function setAsideStamp(at = new Date()) {
+    return at.toISOString().replace(/[:.]/g, '-');
+}
+/**
+ * Move the clone at `repoDir` to `dest`. A rename when it can be one; a copy
+ * when it cannot (another volume, a handle held open on it), and only then is
+ * the original removed — so a copy that fails leaves the clone exactly where
+ * it was rather than half of it in each place.
+ *
+ * Throws with what to do about it. The caller decides how much that costs:
+ * the startup phase stops the boot (leaving the clone would fail a step later
+ * with git's words about a repository nobody configured), while a single
+ * branch open refuses that branch.
+ */
+export async function setAsideClone(repoDir, dest) {
+    // A destination that is already there is somebody's set-aside work, and
+    // never this call's to touch: the copy below cleans up after itself by
+    // removing the destination, which must then be one this call made.
+    const taken = () => new Error(`Could not set aside the working copy at ${repoDir}: ${dest} already holds one. Nothing was deleted or ` +
+        'moved. Try again; the folder is named for the moment it is made.');
+    if (await fs.access(dest).then(() => true, () => false))
+        throw taken();
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    try {
+        await fs.rename(repoDir, dest);
+        return;
+    }
+    catch {
+        // Another volume, or a handle held open on it: copy instead.
+    }
+    // The destination is MADE here, by the one call that will fill it. Two
+    // calls that both found it absent above cannot both make it: the second
+    // is refused by the filesystem, before the cleanup below could ever be
+    // about a folder it did not create.
+    try {
+        await fs.mkdir(dest);
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            throw taken();
+        throw err;
+    }
+    try {
+        // Into the empty folder made above, which is why an existing destination
+        // is not an error here; nothing is overwritten (`force: false`).
+        await fs.cp(repoDir, dest, { recursive: true, errorOnExist: false, force: false, verbatimSymlinks: true });
+    }
+    catch (err) {
+        await fs.rm(dest, { recursive: true, force: true }).catch(() => undefined);
+        throw new Error(`Could not set aside the working copy at ${repoDir}, a clone of a repository that is no longer the ` +
+            `configured one, into ${dest}: ${err instanceof Error ? err.message : String(err)}. Nothing was deleted. ` +
+            'Make room there, or move that folder away by hand, and start again.', { cause: err });
+    }
+    await fs.rm(repoDir, { recursive: true, force: true });
+}
+//# sourceMappingURL=set-aside-clone.js.map

package/dist/modules/workspace/set-aside-clone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-aside-clone.js","sourceRoot":"","sources":["../../../src/modules/workspace/set-aside-clone.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,cAAsB,EAAE,QAAiB;IACvE,OAAO,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,IAAI,EAAE,yBAAyB,CAAC,CAAC;AACnF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAW,IAAI,IAAI,EAAE;IACjD,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAe,EAAE,IAAY;IAC/D,wEAAwE;IACxE,uEAAuE;IACvE,mEAAmE;IACnE,MAAM,KAAK,GAAG,GAAU,EAAE,CACxB,IAAI,KAAK,CACP,2CAA2C,OAAO,KAAK,IAAI,6CAA6C;QACtG,kEAAkE,CACrE,CAAC;IACJ,IAAI,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC;QAAE,MAAM,KAAK,EAAE,CAAC;IACvE,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC/B,OAAO;IACT,CAAC;IAAC,MAAM,CAAC;QACP,6DAA6D;IAC/D,CAAC;IACD,uEAAuE;IACvE,wEAAwE;IACxE,uEAAuE;IACvE,oCAAoC;IACpC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,KAAK,EAAE,CAAC;QACpE,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,IAAI,CAAC;QACH,yEAAyE;QACzE,iEAAiE;QACjE,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7G,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC3E,MAAM,IAAI,KAAK,CACb,2CAA2C,OAAO,kDAAkD;YAClG,wBAAwB,IAAI,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,yBAAyB;YAC1G,qEAAqE,EACvE,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACzD,CAAC"}

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

@@ -10,7 +10,9 @@ import { ClassifiedFailure, type GitFailure } from '../../../shared/git-failure.
  *
  * Fully fail-closed: any failure this phase cannot DECLARE (an unhandled
  * step throw, an unreachable remote, a clone that will not come down, a
- * refused write) throws out of `runAll` and stops the boot. The container's
+ * refused write) throws out of `runAll`. The boot stops on it unless the
+ * host ANSWERED about the repository or the credentials, in which case it
+ * comes up gated instead — see `bootMaySurvive`. The container's
  * restart policy is the retry — each attempt at boot time on quiet trees —
  * so an environmental failure converges without a human the moment the
  * environment returns. The one carve-out: a push rejected because a
@@ -32,6 +34,15 @@ export interface KbStartupRunnerOptions {
     gitRunner: IGitRunner;
     kbRepoUrl: () => string;
     workspacesRoot: string;
+    /**
+     * Where a working copy of a repository that is no longer the configured one
+     * is moved to, under a folder named for the moment it happened — see
+     * `reconcileClonesWithConfiguredRepository`. THE SAME VALUE THE WORKSPACE
+     * SERVICE IS GIVEN.
+     *
+     * Why, in one place: `setAsideRootFor` in `set-aside-clone.ts`.
+     */
+    setAsideRoot?: string;
     kbDirName: string;
     templateDir: string;
     defaultBranch: () => string;
@@ -48,6 +59,47 @@ export interface KbStartupRunnerOptions {
         template `.gitignore` rule can never silently drop a required seed file
         from the commit. */
     buildSeedTree: (dir: string) => Promise<string[]>;
+    /**
+     * Called with the workspace id of each working copy the phase is ABOUT TO
+     * set aside for being a clone of another repository, and awaited first.
+     * Whatever is still queued to be committed into that copy was written
+     * against the repository that was left, so it must be held back before a
+     * fresh clone of another repository appears at the same path.
+     *
+     * A PRECONDITION, so a failure here STOPS THE PHASE with the copy still
+     * where it was. Carrying on would clone the replacement with the queue
+     * untouched, and the worker would then commit those bytes into a
+     * repository they were never meant for. Stopped before anything moved, the
+     * next run finds the same copy and asks again. Optional: a minimal graph
+     * has no queue.
+     */
+    beforeCloneSetAside?: (workspaceId: string) => Promise<void>;
+    /**
+     * Called with the workspace id of each working copy the phase SET ASIDE for
+     * being a clone of another repository. The workspace service keeps a
+     * branch→directory cache and adopts whatever is on disk, so on a RUNNING
+     * server (the save that moves the deployment to another repository) the
+     * copy would otherwise stay in that cache as a path to nothing. Optional:
+     * at boot nothing has been cached yet.
+     *
+     * Never throws into the phase: a listener that fails must not stop a boot.
+     */
+    onCloneDiscarded?: (workspaceId: string) => void | Promise<void>;
+    /**
+     * Called with the workspace id of each working copy the phase CLONED fresh.
+     * A clone has just downloaded every ref, which is a successful fetch by any
+     * measure — but the git layer keeps its own per-workspace record of the last
+     * fetch and whether it worked, and the one that drove the replacement is a
+     * FAILED fetch of the repository that is gone. Left standing, a strict
+     * branch listing inside that record's TTL refuses the new clone's refs as
+     * unproven, having never touched it.
+     *
+     * The ordinary path already says this (`WorkspaceService`'s cloned
+     * listener); the phase clones with git directly, so it has to say it itself.
+     *
+     * Never throws into the phase, for the same reason as above.
+     */
+    onCloneCreated?: (workspaceId: string) => void;
 }
 /**
  * The remote could not be reached or refused us: a host that is down, a DNS
@@ -71,6 +123,15 @@ export declare class KbRemoteUnreachableError extends ClassifiedFailure {
         cause?: unknown;
     });
 }
+/**
+ * Whether the boot may come up GATED on this failure instead of stopping.
+ *
+ * {@link KbRemoteUnreachableError} says so by its type — it is raised where
+ * the remote is first contacted, before any step. A failure raised INSIDE the
+ * phase says so by its classification: the same fetch that stops a boot when
+ * it is the first contact must not stop one when a step happened to make it.
+ */
+export declare function bootMaySurvive(err: unknown): boolean;
 export interface RetryOptions {
     /** First wait before trying again. Default 30s. */
     initialDelayMs?: number;
@@ -150,6 +211,61 @@ export declare class KbStartupRunner {
      */
     private ensureRemote;
     private buildContext;
+    /**
+     * Bring every working copy on disk into line with the configured
+     * repository, WITHOUT DELETING ANYTHING.
+     *
+     * A clone fetches and pushes through the address stored in its own
+     * `remote.origin.url`, which nothing updates when the configured address
+     * changes. After an operator replaced the repository (2026-09-28: the old
+     * one deleted, a new one saved on the setup screen) every surviving clone
+     * kept asking the old address: Save and Retry failed, and the restart
+     * stopped the boot on `repository … not found`, taking the setup screen
+     * with it.
+     *
+     * A clone whose address differs from the configured one is one of two
+     * things, and the histories say which:
+     *
+     *  - THE SAME REPOSITORY AT A NEW ADDRESS — moved, renamed, mirrored. The
+     *    one change the setup screen tells an admin to make ("only change this
+     *    if the same repository was moved or renamed"). Its history is on the
+     *    configured remote, so the clone is pointed at the new address and
+     *    kept, unpushed commits included: they are pushed where they belonged
+     *    all along.
+     *  - ANOTHER REPOSITORY. Re-pointing it would push one repository's
+     *    commits into the other, so it cannot stay where the workspace service
+     *    would adopt it. It is MOVED to {@link KbStartupRunnerOptions.setAsideRoot}
+     *    and the log says where. Never removed: when the old repository is gone
+     *    — as it was that day — these clones are the last copy of the
+     *    knowledge base that exists, and the unpushed work in them exists
+     *    nowhere else at all.
+     *
+     * Every clone under the workspaces root, not only the branches this phase
+     * touches: the workspace service adopts whatever it finds there. A clone
+     * whose address cannot be read is left where it is — "could not tell" is
+     * no reason to move someone's work. One that cannot be set aside stops the
+     * boot with the reason: leaving it would fail the boot a step later with
+     * git's words about a repository nobody configured.
+     */
+    private reconcileClonesWithConfiguredRepository;
+    /**
+     * Whether the configured repository holds history this clone has too —
+     * asked of git, not guessed from the two addresses. The configured
+     * remote's branches are fetched under a namespace of their own and the
+     * clone's HEAD is tested for a common ancestor with any of them.
+     *
+     * "Could not tell" answers false: a fetch that fails, a clone with no
+     * commit to compare. False sets the clone aside, which loses nothing, where
+     * a wrong true would push a stranger's commits into the configured
+     * repository.
+     */
+    private sharesHistoryWithConfigured;
+    /**
+     * Move a working copy out of the workspaces root, whole. A rename where
+     * the two folders share a volume; a copy and then a removal where they do
+     * not (the backups root is a volume of its own in the shipped compose
+     * files), with the original removed only once the copy is complete.
+     */
     /**
      * The branch's working copy at the runtime layout
      * (`<workspacesRoot>/<id>/<kbDirName>`), so the workspace service finds it

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":"AASA,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;;;;OAIG;IACH,SAAS,EAAE,UAAU,CAAC;IACtB,SAAS,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;IA2HxB;;;;;OAKG;YACW,YAAY;IA8F1B,OAAO,CAAC,YAAY;IAuBpB;;;;;;;;OAQG;YACW,WAAW;IAyBzB,6EAA6E;YAC/D,QAAQ;CAkFvB"}
+{"version":3,"file":"kb-startup-runner.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/kb-startup-runner.ts"],"names":[],"mappings":"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"}

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

@@ -10,6 +10,8 @@ import { git, lsRemoteHeads, stampIdentity, withTempDir } from './kb-git.js';
 import { GitRunError } from '../../../shared/git.contract.js';
 import { ClassifiedFailure, classifyGitFailure, failureOf, gitFailure, } from '../../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js';
+import { normalizeRepositoryAddress, sameRepository } from '../../kb-fs/remote-url.js';
+import { setAsideClone, setAsideRootFor, setAsideStamp } from '../set-aside-clone.js';
 /**
  * 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
@@ -33,6 +35,41 @@ export class KbRemoteUnreachableError extends ClassifiedFailure {
         this.name = 'KbRemoteUnreachableError';
     }
 }
+/**
+ * The failure kinds a boot may survive GATED rather than stop on: the remote
+ * ANSWERED (or could not be reached at all), and what it said is about the
+ * repository or the credentials — not about what this deployment would write.
+ *
+ * All four are fixed by an operator somewhere other than this process: the
+ * host comes back, the repository is created or the token is granted access
+ * to it, a rotated token is entered on the setup screen. Refusing to boot
+ * over any of them takes away the very screen the fix is entered on — which
+ * is what happened on 2026-09-28, when a replaced repository answered
+ * `not found` inside a step and the container crash-looped.
+ *
+ * Every OTHER failure still stops the boot: it means a step or the template
+ * would write something wrong, and booting over that is worse than not
+ * booting at all.
+ */
+const GATED_BOOT_KINDS = new Set([
+    'unreachable',
+    'not-found',
+    'credentials-rejected',
+    'write-refused',
+]);
+/**
+ * Whether the boot may come up GATED on this failure instead of stopping.
+ *
+ * {@link KbRemoteUnreachableError} says so by its type — it is raised where
+ * the remote is first contacted, before any step. A failure raised INSIDE the
+ * phase says so by its classification: the same fetch that stops a boot when
+ * it is the first contact must not stop one when a step happened to make it.
+ */
+export function bootMaySurvive(err) {
+    if (err instanceof KbRemoteUnreachableError)
+        return true;
+    return err instanceof ClassifiedFailure && GATED_BOOT_KINDS.has(err.failure.kind);
+}
 export class KbStartupRunner {
     opts;
     constructor(opts) {
@@ -161,7 +198,7 @@ export class KbStartupRunner {
                     // Stopped by either: a failure that is no longer the remote at all
                     // (the knowledge base itself is wrong — asking again will not change
                     // it), or a remote answer that a retry cannot change (see above).
-                    if (!(err instanceof KbRemoteUnreachableError) || !worthRetrying())
+                    if (!bootMaySurvive(err) || !worthRetrying())
                         return stopOnStanding();
                     delay = Math.min(delay * 2, max);
                     log(`remote still unreachable; trying again in ${Math.round(delay / 1000)}s`);
@@ -215,6 +252,10 @@ export class KbStartupRunner {
                     'screen or GITHUB_TOKEN instead.');
             }
             const heads = await this.ensureRemote();
+            // AFTER the remote answered: the configured address is known to be a
+            // repository we can reach, so a clone of a different one is stale, not
+            // a casualty of a typo in the address.
+            await this.reconcileClonesWithConfiguredRepository();
             const ctx = this.buildContext(heads, handles);
             for (const step of this.opts.steps) {
                 const started = Date.now();
@@ -406,6 +447,143 @@ export class KbStartupRunner {
             allBranches: async () => [...heads].sort().map(handleFor),
         };
     }
+    /**
+     * Bring every working copy on disk into line with the configured
+     * repository, WITHOUT DELETING ANYTHING.
+     *
+     * A clone fetches and pushes through the address stored in its own
+     * `remote.origin.url`, which nothing updates when the configured address
+     * changes. After an operator replaced the repository (2026-09-28: the old
+     * one deleted, a new one saved on the setup screen) every surviving clone
+     * kept asking the old address: Save and Retry failed, and the restart
+     * stopped the boot on `repository … not found`, taking the setup screen
+     * with it.
+     *
+     * A clone whose address differs from the configured one is one of two
+     * things, and the histories say which:
+     *
+     *  - THE SAME REPOSITORY AT A NEW ADDRESS — moved, renamed, mirrored. The
+     *    one change the setup screen tells an admin to make ("only change this
+     *    if the same repository was moved or renamed"). Its history is on the
+     *    configured remote, so the clone is pointed at the new address and
+     *    kept, unpushed commits included: they are pushed where they belonged
+     *    all along.
+     *  - ANOTHER REPOSITORY. Re-pointing it would push one repository's
+     *    commits into the other, so it cannot stay where the workspace service
+     *    would adopt it. It is MOVED to {@link KbStartupRunnerOptions.setAsideRoot}
+     *    and the log says where. Never removed: when the old repository is gone
+     *    — as it was that day — these clones are the last copy of the
+     *    knowledge base that exists, and the unpushed work in them exists
+     *    nowhere else at all.
+     *
+     * Every clone under the workspaces root, not only the branches this phase
+     * touches: the workspace service adopts whatever it finds there. A clone
+     * whose address cannot be read is left where it is — "could not tell" is
+     * no reason to move someone's work. One that cannot be set aside stops the
+     * boot with the reason: leaving it would fail the boot a step later with
+     * git's words about a repository nobody configured.
+     */
+    async reconcileClonesWithConfiguredRepository() {
+        const configured = this.opts.kbRepoUrl();
+        let entries;
+        try {
+            entries = await fs.readdir(this.opts.workspacesRoot, { withFileTypes: true });
+        }
+        catch {
+            return; // no workspaces yet
+        }
+        // One folder per run, so what was set aside together stays together.
+        const stamp = setAsideStamp();
+        const setAsideRoot = setAsideRootFor(this.opts.workspacesRoot, this.opts.setAsideRoot);
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const repoDir = path.join(this.opts.workspacesRoot, entry.name, this.opts.kbDirName);
+            const hasGit = await fs.access(path.join(repoDir, '.git')).then(() => true, () => false);
+            if (!hasGit)
+                continue;
+            let origin;
+            try {
+                origin = (await git(this.opts.gitRunner, repoDir, ['config', '--get', 'remote.origin.url'])).trim();
+            }
+            catch {
+                continue;
+            }
+            if (origin === '' || sameRepository(origin, configured))
+                continue;
+            // The normalized form carries no userinfo, and the scrub covers the rest.
+            const was = this.redact(normalizeRepositoryAddress(origin));
+            if (await this.sharesHistoryWithConfigured(repoDir, configured)) {
+                await git(this.opts.gitRunner, repoDir, ['remote', 'set-url', 'origin', configured]);
+                startupLog.warn(`working copy "${entry.name}" was cloned from ${was}, whose history the configured repository holds: ` +
+                    'the same repository at a new address. Pointed at the configured address and kept, unpushed work included.');
+                continue;
+            }
+            const kept = path.join(setAsideRoot, stamp, entry.name);
+            // First, and allowed to stop the phase: see `beforeCloneSetAside`. The
+            // directory name IS the workspace id (`workspaceIdForBranch`).
+            await this.opts.beforeCloneSetAside?.(entry.name);
+            await setAsideClone(repoDir, kept);
+            startupLog.warn(`working copy "${entry.name}" is a clone of another repository (${was}). Set aside at ${kept}; nothing was ` +
+                'deleted, and it will be cloned fresh from the configured one. Work that was never pushed is in that ' +
+                'folder: `git log` there shows it, and `git push <address> <branch>` from there sends it to a repository.');
+            // Setting it aside already removed it from the workspaces root, so the
+            // cached handle the workspace service holds for it now points at
+            // nothing.
+            try {
+                await this.opts.onCloneDiscarded?.(entry.name);
+            }
+            catch (err) {
+                startupLog.warn(`could not finish setting the working copy "${entry.name}" aside:`, {
+                    detail: this.redact(err instanceof Error ? err.message : String(err)),
+                });
+            }
+        }
+    }
+    /**
+     * Whether the configured repository holds history this clone has too —
+     * asked of git, not guessed from the two addresses. The configured
+     * remote's branches are fetched under a namespace of their own and the
+     * clone's HEAD is tested for a common ancestor with any of them.
+     *
+     * "Could not tell" answers false: a fetch that fails, a clone with no
+     * commit to compare. False sets the clone aside, which loses nothing, where
+     * a wrong true would push a stranger's commits into the configured
+     * repository.
+     */
+    async sharesHistoryWithConfigured(repoDir, configured) {
+        const probe = 'refs/hexis-probe';
+        let theirs = [];
+        try {
+            await git(this.opts.gitRunner, repoDir, ['fetch', '--no-tags', '--quiet', configured, `+refs/heads/*:${probe}/*`]);
+            theirs = (await git(this.opts.gitRunner, repoDir, ['for-each-ref', '--format=%(refname)', `${probe}/`]))
+                .split('\n')
+                .map((ref) => ref.trim())
+                .filter(Boolean);
+            if (theirs.length === 0)
+                return false;
+            // One question for all of them: a common ancestor of HEAD and ANY of
+            // their branches is a common ancestor of HEAD and their merge. Capped,
+            // so a remote with thousands of branches cannot outgrow a command line.
+            await git(this.opts.gitRunner, repoDir, ['merge-base', 'HEAD', ...theirs.slice(0, 200)]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            // The probe leaves nothing behind in a clone that stays in use.
+            for (const ref of theirs) {
+                await git(this.opts.gitRunner, repoDir, ['update-ref', '-d', ref]).catch(() => undefined);
+            }
+        }
+    }
+    /**
+     * Move a working copy out of the workspaces root, whole. A rename where
+     * the two folders share a volume; a copy and then a removal where they do
+     * not (the backups root is a volume of its own in the shipped compose
+     * files), with the original removed only once the copy is complete.
+     */
     /**
      * The branch's working copy at the runtime layout
      * (`<workspacesRoot>/<id>/<kbDirName>`), so the workspace service finds it
@@ -423,6 +601,17 @@ export class KbStartupRunner {
             await fs.mkdir(workspaceDir, { recursive: true });
             await fs.rm(repoDir, { recursive: true, force: true });
             await git(this.opts.gitRunner, workspaceDir, ['clone', '-b', branch, this.opts.kbRepoUrl(), repoDir]);
+            // Said as soon as the clone is there, before its configuration: if a
+            // command below fails, the clone stays on disk, and the retry finds it
+            // and never comes back through here.
+            try {
+                this.opts.onCloneCreated?.(workspaceIdForBranch(branch));
+            }
+            catch (err) {
+                startupLog.warn(`could not announce the fresh working copy for "${branch}":`, {
+                    detail: this.redact(err instanceof Error ? err.message : String(err)),
+                });
+            }
             await git(this.opts.gitRunner, repoDir, ['config', 'core.longpaths', 'true']);
             await stampIdentity(this.opts.gitRunner, repoDir);
             return repoDir;