@bridge4dev/runner 0.52.0 → 0.54.0

package/dist/checkpoints.js

@@ -362,6 +362,16 @@ function decodeMeta(message) {
                 ? { agentSession: parsed['agentSession'] }
                 : {}),
             ...(typeof parsed['messageSeq'] === 'number' ? { messageSeq: parsed['messageSeq'] } : {}),
+            // A whitelist, so a key absent from THIS list is a key that was written
+            // and is never read again. The mark is the whole point of #310, and a
+            // silently dropped mark reads exactly like «the folder was quiet».
+            ...(Array.isArray(parsed['busySessions'])
+                ? {
+                    busySessions: parsed['busySessions']
+                        .filter((id) => typeof id === 'string')
+                        .slice(0, MAX_BUSY_SESSIONS),
+                }
+                : {}),
         };
     }
     catch {
@@ -379,6 +389,8 @@ export async function createCheckpoint(input) {
     try {
         const store = await ensureStore(worktreePath);
         const indexFile = tempIndexFile(sessionId, 'create');
+        // Both ends of the shutter — see `CreateCheckpointInput.busySessions`.
+        const busyBefore = input.busySessions?.() ?? [];
         const built = await buildIndex(store, worktreePath, indexFile);
         if (built.tooLarge) {
             fs.rmSync(indexFile, { force: true });
@@ -386,6 +398,7 @@ export async function createCheckpoint(input) {
         }
         const { headSha, included, excluded: skippedFiles, byteCount } = built;
         const tree = await gitStore(store, worktreePath, indexFile, 'write-tree');
+        const busySessions = [...new Set([...busyBefore, ...(input.busySessions?.() ?? [])])].slice(0, MAX_BUSY_SESSIONS);
         const stagedPaths = splitZ(await gitIn(worktreePath, 'diff', '--cached', '--name-only', '-z')).filter((file) => !isSecretPath(path.join(worktreePath, file)));
         const meta = {
             kind,
@@ -397,6 +410,9 @@ export async function createCheckpoint(input) {
             ...(input.agentAnchor ? { agentAnchor: input.agentAnchor } : {}),
             ...(input.agentSession ? { agentSession: input.agentSession } : {}),
             ...(input.messageSeq === undefined ? {} : { messageSeq: input.messageSeq }),
+            // Written only when non-empty: an empty array in every ordinary record
+            // would be noise in a commit message that is read by eye during support.
+            ...(busySessions.length > 0 ? { busySessions } : {}),
         };
         const commit = await gitStore(store, worktreePath, indexFile, 'commit-tree', tree, '-m', encodeMeta(meta));
         const ordinal = await nextOrdinal(store, worktreePath, sessionId);
@@ -466,6 +482,15 @@ async function currentTree(store, worktreePath, indexFile) {
         headSha: built.headSha,
     };
 }
+/**
+ * How many neighbour ids a restore point carries (#310).
+ *
+ * The same number as the API's schema and the runner's event: the mark itself
+ * is the warning, the names are a courtesy, and a folder with eleven busy
+ * sessions is not eleven times more dangerous than one with ten. Gotcha 433 —
+ * a cap on a courtesy must degrade, never reject.
+ */
+export const MAX_BUSY_SESSIONS = 10;
 const MAX_PREVIEW_ENTRIES = 5_000;
 /** What a rewind to this checkpoint would do, without doing any of it. */
 export async function previewRewind(input) {
@@ -538,6 +563,13 @@ export async function previewRewind(input) {
         checkpointHeadSha: record.headSha,
         treeOid: tree,
         ...(blockedReason ? { blockedReason } : {}),
+        // Presence, not length (gotcha 433): the KEY is the warning, the ids are a
+        // courtesy that may resolve to no names at all. A marked point whose list
+        // came back empty would otherwise look trustworthy here while `applyRewind`
+        // went on refusing it.
+        ...(record.busySessions !== undefined
+            ? { untrustedFiles: { sessions: record.busySessions } }
+            : {}),
         ...(commitsSince.length ? { commitsSince } : {}),
         ...(total > MAX_PREVIEW_ENTRIES ? { truncated: true, totalChanges: total } : {}),
     };
@@ -574,6 +606,12 @@ export async function applyRewind(input) {
     if (preview.blockedReason) {
         throw new Error(rewindBlockMessage(preview.blockedReason));
     }
+    // #310. Before the safety point, not after: taking one is a write into the
+    // folder, and refusing afterwards would leave a restore point nobody asked
+    // for behind every refusal.
+    if (preview.untrustedFiles) {
+        throw new Error(UNTRUSTED_FILES_MESSAGE);
+    }
     const MOVED = 'The working tree changed while you were looking at it — open the preview again';
     // The whole state, not just the deletions (QA-120 B1). `read-tree --reset -u`
     // writes the RESTORE list as well, and that list is recomputed HERE — so a
@@ -586,7 +624,12 @@ export async function applyRewind(input) {
     if (expected.length !== echoed.length || expected.some((p, i) => p !== echoed[i])) {
         throw new Error(MOVED);
     }
-    const safetyResult = await createCheckpoint({ worktreePath, sessionId, kind: 'SAFETY' });
+    const safetyResult = await createCheckpoint({
+        worktreePath,
+        sessionId,
+        kind: 'SAFETY',
+        ...(input.busySessions ? { busySessions: input.busySessions } : {}),
+    });
     if (!safetyResult.created) {
         throw new Error(safetyResult.reason === 'too-large'
             ? 'The working tree is too large to take a safety point — the rewind was not started'
@@ -617,6 +660,12 @@ export async function applyRewind(input) {
         rewoundToKind: record.kind,
     };
 }
+/**
+ * Said when the files of a restore point cannot be trusted (#310). Its own
+ * sentence rather than a `blockedReason`, for the reason written on
+ * `RewindPreview.untrustedFiles`.
+ */
+export const UNTRUSTED_FILES_MESSAGE = 'The files at this restore point cannot be trusted: another session was working in this folder when it was taken. Only the conversation can be rewound to it.';
 export function rewindBlockMessage(reason) {
     switch (reason) {
         case 'head-moved':

package/dist/git.d.ts

@@ -1,8 +1,42 @@
+/**
+ * Why git stopped, in a sentence a person can act on.
+ *
+ * `git worktree add` prints its progress to stderr as carriage-return-overwritten
+ * frames, so a process killed mid-checkout leaves «Updating files: 1% (51/2693)»
+ * as the last thing anybody sees — a number, with no verb. The real cause lives
+ * on the error object (`killed`, `signal`, `code`) and nobody was reading it
+ * (#360). Keep the last progress frame, because «how far did it get» is the one
+ * useful thing in it, and put the cause in front of it.
+ */
+export declare function describeGitFailure(error: unknown, context?: {
+    timeoutMs?: number;
+}): string;
+/** What went wrong while building the session's workplace, in one machine-readable word. */
+export type WorktreePrepareCode = 'worktree_prepare_failed' | 'branch_taken' | 'worktree_cleanup_failed';
+/**
+ * A preparation failure that already knows its own fork point.
+ *
+ * The fork point matters precisely BECAUSE preparation failed: without it the
+ * API keeps `base_sha = null` for the session's whole life, and «Continue» can
+ * never prove that the branch it is about to adopt is the empty one this very
+ * session created a moment ago (#360, plan Р6).
+ */
+export declare class WorktreePrepareError extends Error {
+    readonly code: WorktreePrepareCode;
+    readonly baseBranch?: string;
+    readonly baseSha?: string;
+    constructor(message: string, code: WorktreePrepareCode, base?: {
+        baseBranch?: string;
+        baseSha?: string;
+    });
+}
 export interface PathValidation {
     ok: boolean;
     exists: boolean;
     isGitRepo: boolean;
     branch?: string;
+    /** The repository's own main branch, as this machine can see it without the network. */
+    defaultBranch?: string;
     error?: string;
 }
 /**
@@ -16,6 +50,23 @@ export interface PathValidation {
  * '/opt/ids'». That sentence is true and unactionable.
  */
 export declare function validateWorkspacePath(workspacePath: string): Promise<PathValidation>;
+/**
+ * The repository's main branch, read locally (ADR 0004).
+ *
+ * `origin/HEAD` is the honest answer and it is already on disk — set by `clone`,
+ * refreshed by `git remote set-head`. Never asked over the network: this runs
+ * inside a 4-second probe budget, and a repository whose origin is unreachable
+ * must still bind.
+ */
+export declare function remoteDefaultBranch(workspacePath: string): Promise<string | null>;
+/**
+ * `main`, then `master`, and only if the repository really has one.
+ *
+ * The order and the list are one decision, not two: `gitops.ts` asks the same
+ * question when «Apply» has no pinned base, and two copies would drift the day
+ * somebody adds `develop` to one of them (ADR 0004).
+ */
+export declare function firstConventionalBranch(workspacePath: string): Promise<string | null>;
 export declare function sessionShortId(sessionId: string): string;
 export declare function sessionWorktreePath(sessionId: string): string;
 /**
@@ -69,6 +120,19 @@ export declare function ensureSessionWorktree(workspacePath: string, sessionId:
     requireExistingBranch?: boolean;
     plan?: BranchPlan;
 }): Promise<SessionWorktree>;
+/**
+ * Delete a session branch that provably carries no commits (#360).
+ *
+ * Shares its safety rungs with {@link deleteSessionBranch} — prune, then the
+ * folder's own branch, then the holder — and adds the one this caller needs:
+ * the tip must still be exactly the fork point we started from. `-D`, not `-d`,
+ * because `-d` asks «is it merged into the branch THIS folder is on», which is
+ * a different question and answers «no» for a branch that is empty.
+ */
+export declare function dropEmptySessionBranch(workspacePath: string, branch: string, expectedSha: string): Promise<{
+    removed: boolean;
+    leftover?: string;
+}>;
 /**
  * DIRECT mode (session 16): the session's workplace IS the project folder.
  *