@bridge4dev/runner 0.62.0 → 0.63.0

package/dist/checkpoints.d.ts

@@ -18,6 +18,17 @@ export interface CheckpointRecord {
     kind: CheckpointKind;
     /** HEAD of the worktree when the checkpoint was taken. */
     headSha: string;
+    /**
+     * #137: there was no commit at all when this point was taken — an empty
+     * `headSha` that MEANS something.
+     *
+     * Written down rather than inferred, because the empty string is already the
+     * value `decodeMeta` invents for a record whose metadata it could not read.
+     * Those two states need opposite treatment: «nothing was committed yet» can
+     * say truthfully what arrived since (all of it), while «we do not know what
+     * HEAD was» must not claim the whole history arrived after the point.
+     */
+    unborn?: boolean;
     /** Paths that were staged in the project's index at that moment. */
     stagedPaths: string[];
     createdAt: number;

package/dist/checkpoints.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { promisify } from 'node:util';
 import { createHash } from 'node:crypto';
 import { checkpointsDir } from './paths.js';
+import { EMPTY_TREE_SHA } from './gitops.js';
 import { isSecretPath } from './policy.js';
 import { log } from './log.js';
 const execFileAsync = promisify(execFile);
@@ -410,8 +411,30 @@ async function runBatched(store, worktreePath, indexFile, args, paths) {
 async function buildIndex(store, worktreePath, indexFile) {
     fs.mkdirSync(path.dirname(indexFile), { recursive: true, mode: 0o700 });
     fs.rmSync(indexFile, { force: true });
-    const headSha = await gitIn(worktreePath, 'rev-parse', 'HEAD');
-    await gitStore(store, worktreePath, indexFile, 'read-tree', headSha);
+    // #137: a repository with no commits has no HEAD to build the index from,
+    // and the bare `rev-parse HEAD` threw git's manual page — which the refusal
+    // classifier then read as «this folder is not a git repository», so every
+    // single step of every session in a fresh `git init` folder wrote that
+    // sentence into the feed. It is the wrong sentence twice over: the folder IS
+    // a repository, and a restore point in it is perfectly possible.
+    //
+    // The empty tree is what git itself compares a first commit against, so it is
+    // the honest starting index — and `gitStatus` in DIRECT mode has been using
+    // exactly this constant for the same reason since session 16.
+    //
+    // The exit code is READ, not caught away — the same rule `headState` follows
+    // in `git.ts`, and for a bigger reason here. A bare `.catch` would read a
+    // timeout, an OOM kill or a lost `safe.directory` as «no commits yet» on a
+    // repository that has plenty: the point would then be built from the empty
+    // tree, look perfectly normal in the feed, and a rewind to it would offer to
+    // DELETE every file the checkpoint did not happen to cover. «git could not
+    // look» must abort the point, exactly as it did before #137.
+    const headSha = await gitIn(worktreePath, 'rev-parse', '--verify', '--quiet', 'HEAD').then((sha) => sha, (error) => {
+        if (error.code === 1)
+            return '';
+        throw error;
+    });
+    await gitStore(store, worktreePath, indexFile, 'read-tree', headSha || EMPTY_TREE_SHA);
     const { paths, secrets } = await changedPaths(worktreePath);
     const excluded = new Set(secrets);
     const included = [];
@@ -496,6 +519,7 @@ function decodeMeta(message) {
         return {
             kind: kind === 'SAFETY' || kind === 'MANUAL' ? kind : 'TURN',
             headSha: typeof parsed['headSha'] === 'string' ? parsed['headSha'] : '',
+            ...(parsed['unborn'] === true ? { unborn: true } : {}),
             stagedPaths: Array.isArray(parsed['stagedPaths'])
                 ? parsed['stagedPaths'].filter((p) => typeof p === 'string')
                 : [],
@@ -549,7 +573,13 @@ export async function createCheckpoint(input) {
 /** An error on the way to a restore point, read as a reason to report. */
 function checkpointRefusal(sessionId, error) {
     const detail = String(error instanceof Error ? error.message : error).slice(0, 300);
-    if (/not a git repository|ambiguous argument 'HEAD'|unknown revision/i.test(detail)) {
+    // #137: «ambiguous argument 'HEAD'» is git's answer to a repository with no
+    // commits in it, and reading it as «not a git repository» produced the one
+    // sentence in the feed that was flatly untrue — on a folder the person had
+    // just created and bound. An unborn HEAD does not reach here at all any more
+    // (`buildIndex` starts from the empty tree), and if some other unborn-HEAD
+    // read ever does, «git refused» is the honest bucket for it, not «not a repo».
+    if (/not a git repository/i.test(detail)) {
         return { created: false, reason: 'not-a-repo', detail };
     }
     log.warn('checkpoints: could not create a restore point', { sessionId, error: detail });
@@ -573,6 +603,10 @@ async function takeCheckpoint(store, input) {
         const meta = {
             kind,
             headSha,
+            // Only when it is true: an absent key is what every record written before
+            // this release carries, and those were all taken on a repository with a
+            // HEAD.
+            ...(headSha ? {} : { unborn: true }),
             stagedPaths,
             createdAt: Date.now(),
             fileCount: included.length,
@@ -721,10 +755,35 @@ async function buildPreview(store, indexFile, input) {
     const total = restore.length + remove.length + recreate.length;
     let blockedReason = total > MAX_PREVIEW_ENTRIES ? 'too-many-changes' : undefined;
     const commitsSince = [];
-    if (!blockedReason && record.headSha && record.headSha !== headSha) {
+    // #137: an empty string is «there was no commit at all when this point was
+    // taken» — a real state now that a repository with no commits can hold a
+    // session. It must still count as movement: the first commit arriving between
+    // the point and the rewind moves HEAD exactly as any later one does, and the
+    // old `record.headSha &&` guard read that case as «HEAD has not moved» and
+    // let the rewind run without a word.
+    if (!blockedReason && record.headSha !== headSha) {
         blockedReason = 'head-moved';
         try {
-            const listed = await gitIn(worktreePath, 'log', '--format=%h%x00%s', '--max-count=20', `${record.headSha}..${headSha}`);
+            // A range needs two ends. With no commit at all behind the point, «what
+            // arrived since» is the whole history that exists — the first commit and
+            // whatever followed it — so the range collapses to one end. An empty
+            // left side would NOT do that: `..<sha>` means `HEAD..<sha>` to git,
+            // which is a different question and usually an empty answer.
+            //
+            // The one-ended form is used ONLY for a point that recorded «there was
+            // nothing here yet». A record whose metadata could not be read carries
+            // the same empty `headSha` and means something else entirely — listing
+            // the repository's whole history under «what arrived since this point»
+            // would be a confident, wrong answer. That record still refuses the
+            // rewind, which is the safe direction; it simply names no commits.
+            const range = record.headSha
+                ? `${record.headSha}..${headSha}`
+                : record.unborn
+                    ? headSha
+                    : null;
+            const listed = headSha && range
+                ? await gitIn(worktreePath, 'log', '--format=%h%x00%s', '--max-count=20', range)
+                : '';
             for (const line of listed.split('\n')) {
                 if (!line.trim())
                     continue;

package/dist/git.d.ts

@@ -30,11 +30,67 @@ export declare class WorktreePrepareError extends Error {
         baseSha?: string;
     });
 }
+/**
+ * A repository with no commits cannot hand out a copy of itself (#137).
+ *
+ * The mirror of `NO_COMMITS_YET_MESSAGE` in `@devbridge/shared`, which this
+ * package cannot import — it is published to npm on its own, and the import
+ * would make the tarball unresolvable (`recipe-schema.ts` explains it in full).
+ * Same arrangement as the level-event constants and the session limits: the
+ * text lives twice and a test pins the two copies together, because the API
+ * refuses this case before a session exists and the runner refuses it again if
+ * one ever gets that far — and the person must read one sentence, not two.
+ *
+ * `git.test.ts` compares this against the shared copy byte for byte.
+ */
+export declare const NO_COMMITS_YET_MESSAGE = "This repository has no commits yet \u2014 start a session in the project folder itself; a branch of its own becomes possible after the first commit";
+/**
+ * Where HEAD points — with the three states told apart properly (#137).
+ *
+ * `rev-parse --abbrev-ref HEAD` cannot answer this and never could. On a
+ * repository straight out of `git init` it exits 128 with git's own manual
+ * page («ambiguous argument 'HEAD'»), and it ALSO prints the literal word
+ * `HEAD` — the same word it prints on a detached HEAD. So the one call that
+ * everything here used to be built on both throws where it should not and,
+ * caught, answers «detached» for a folder that is plainly on a branch. That is
+ * the whole of #137: a directory with no commits in it could not be bound, its
+ * first session refused to start, and its restore points reported «this is not
+ * a git repository».
+ *
+ * Two calls answer it honestly, and both are cheap:
+ *
+ *   `symbolic-ref --short HEAD`      — the branch NAME, whether or not it has a
+ *                                      commit; fails only on a detached HEAD.
+ *   `rev-parse --verify --quiet HEAD` — is there a commit at all.
+ *
+ *   branch + commit → an ordinary checkout
+ *   branch, no commit → unborn: a legitimate, fully workable state. The person
+ *                       ran `git init` and has not committed yet; nobody makes
+ *                       that first commit for them (#137, plan S3a).
+ *   no branch, commit → detached: the refusal that was always meant here.
+ *   neither           → not a repository. Every caller establishes that
+ *                       separately, so this simply reports nothing.
+ */
+export interface HeadState {
+    /** The branch HEAD is on, including one that has no commit yet. */
+    branch: string | null;
+    /** On a branch that has no commit yet — a fresh `git init`. */
+    unborn: boolean;
+    /** On a commit rather than on a branch. */
+    detached: boolean;
+}
+export declare function headState(workspacePath: string): Promise<HeadState>;
 export interface PathValidation {
     ok: boolean;
     exists: boolean;
     isGitRepo: boolean;
     branch?: string;
+    /**
+     * #137: the branch has no commit on it yet. `branch` above is still its name
+     * and the directory still binds — this says «do not expect a HEAD here», and
+     * it is what lets every reader downstream stop guessing «detached».
+     */
+    unborn?: boolean;
     /** The repository's own main branch, as this machine can see it without the network. */
     defaultBranch?: string;
     error?: string;

package/dist/git.js

@@ -94,6 +94,44 @@ export class WorktreePrepareError extends Error {
             this.baseSha = base.baseSha;
     }
 }
+/**
+ * A repository with no commits cannot hand out a copy of itself (#137).
+ *
+ * The mirror of `NO_COMMITS_YET_MESSAGE` in `@devbridge/shared`, which this
+ * package cannot import — it is published to npm on its own, and the import
+ * would make the tarball unresolvable (`recipe-schema.ts` explains it in full).
+ * Same arrangement as the level-event constants and the session limits: the
+ * text lives twice and a test pins the two copies together, because the API
+ * refuses this case before a session exists and the runner refuses it again if
+ * one ever gets that far — and the person must read one sentence, not two.
+ *
+ * `git.test.ts` compares this against the shared copy byte for byte.
+ */
+// #region no-commits-yet-mirror
+export const NO_COMMITS_YET_MESSAGE = 'This repository has no commits yet — start a session in the project folder itself; a branch of its own becomes possible after the first commit';
+export async function headState(workspacePath) {
+    const [symbolic, commit] = await Promise.all([
+        git(workspacePath, 'symbolic-ref', '--short', 'HEAD').catch(() => null),
+        // `--verify --quiet` is the whole point: an unborn HEAD is exit 1 and
+        // SILENCE here, where the plain form is exit 128 and three lines of git.
+        //
+        // And the exit code is read rather than caught away, the same way the
+        // branch probe in `looksHalfCreated` reads it and for the same reason:
+        // exit 1 is «there is no commit», while 128, a signal or a
+        // dubious-ownership fatal is git failing to LOOK. `unborn` authorises
+        // real things — it is what offers the project folder for work and what
+        // makes a restore point start from the empty tree — so «could not look»
+        // must never arrive here dressed as «no commits yet».
+        git(workspacePath, 'rev-parse', '--verify', '--quiet', 'HEAD').then((sha) => ({ sha, absent: false }), (error) => ({
+            sha: null,
+            absent: error.code === 1,
+        })),
+    ]);
+    const branch = symbolic ? symbolic.trim() : '';
+    if (!branch)
+        return { branch: null, unborn: false, detached: Boolean(commit.sha) };
+    return { branch, unborn: commit.absent, detached: false };
+}
 /**
  * Can this runner actually work in this directory — as the user it runs as?
  *
@@ -190,17 +228,27 @@ export async function validateWorkspacePath(workspacePath) {
                 `Give that user write access to the repository (for example \`chown -R ${me.user} ${workspacePath}\`), then try again.`,
         };
     }
-    const branch = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD');
+    // #137: read through `headState`, not `rev-parse --abbrev-ref HEAD`. The old
+    // call was the LAST thing this function did and the only one of six branch
+    // reads in this file left uncaught — so a directory with `git init` and no
+    // commit in it failed binding with git's manual page forwarded to a browser,
+    // after every real check above had already passed.
+    const head = await headState(workspacePath);
     // Binding is the one moment we are guaranteed to be looking at this repository
     // with somebody waiting for the answer, so it is where the main branch is
     // learned (ADR 0004). `branch` above is «what the folder is on right now» — a
     // drifting value, and the reason #361 exists; these two must not be confused.
+    //
+    // On a repository with no commits there is no branch to learn: nothing has
+    // been pushed anywhere and no conventional branch exists yet, so the binding's
+    // `main_branch` stays «not known yet» and learns itself later (ADR 0004).
     const defaultBranch = await remoteDefaultBranch(workspacePath);
     return {
         ok: true,
         exists: true,
         isGitRepo: true,
-        branch,
+        ...(head.branch ? { branch: head.branch } : {}),
+        ...(head.unborn ? { unborn: true } : {}),
         ...(defaultBranch ? { defaultBranch } : {}),
     };
 }
@@ -308,6 +356,18 @@ export function sanitizeBranch(hint) {
  * in the workspace repo, so the work survives worktree cleanup.
  */
 export async function ensureSessionWorktree(workspacePath, sessionId, branchHint, options = {}) {
+    // #137: a repository with no commits cannot have a copy of itself, and this
+    // is the only honest place to say so. Git refuses both halves of the
+    // arrangement — `worktree add -b x main|HEAD` is «invalid reference», and
+    // `merge --squash` into an unborn HEAD is «Squash commit into empty head not
+    // supported yet» — so a session started this way would be created, would
+    // fail here in git's own words, and, had it survived, could never be applied.
+    // The plan's decision (S3a) is to refuse early rather than to make the copy
+    // work: nobody makes the person's first commit for them.
+    const head = await headState(workspacePath);
+    if (head.unborn) {
+        throw new Error(NO_COMMITS_YET_MESSAGE);
+    }
     const short = sessionShortId(sessionId);
     // A ticket group gets a branch named after its tickets so the work reads as
     // one thing in git history. The worktree DIRECTORY stays id-derived — it is
@@ -743,16 +803,27 @@ export async function prepareDirectWorkspace(workspacePath) {
     if (inside !== 'true') {
         throw new Error(`${workspacePath} is not a git work tree`);
     }
-    const branch = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null);
-    if (!branch || branch === 'HEAD') {
+    // #137: `rev-parse --abbrev-ref HEAD` answered the literal word `HEAD` for a
+    // detached checkout AND threw for a repository with no commits, so caught it
+    // collapsed both into the detached refusal below — and a folder sitting
+    // perfectly well on `main`, one `git init` old, was told to «check a branch
+    // out there», which it already had. `headState` tells the two apart.
+    const head = await headState(workspacePath);
+    if (!head.branch) {
         throw new Error('The project folder is not on a branch (detached HEAD) — check a branch out there before starting a session');
     }
     const top = await git(workspacePath, 'rev-parse', '--show-toplevel').catch(() => null);
-    const baseSha = await git(workspacePath, 'rev-parse', 'HEAD').catch(() => undefined);
+    // No commits yet means no fork point, and that is not a failure: DIRECT mode
+    // forks from nothing anyway — the session's workplace IS this folder and this
+    // branch. The field simply stays absent, which is what it already did for
+    // every other reason a base sha could be missing.
+    const baseSha = head.unborn
+        ? undefined
+        : await git(workspacePath, 'rev-parse', 'HEAD').catch(() => undefined);
     return {
-        branch,
+        branch: head.branch,
         worktreePath: top || workspacePath,
-        baseBranch: branch,
+        baseBranch: head.branch,
         ...(baseSha ? { baseSha } : {}),
     };
 }

package/dist/gitops.d.ts

@@ -1,3 +1,9 @@
+/**
+ * git's own name for «nothing», and the only thing a repository without a
+ * single commit can be diffed against. Constant in every git repository ever
+ * made — it is the SHA-1 of the empty tree object.
+ */
+export declare const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 export interface GitFileEntry {
     path: string;
     /** A | M | D | R (git name-status letter). */
@@ -324,6 +330,22 @@ export interface GitBranchesResult {
     branches: GitBranchEntry[];
     /** What the project folder is on right now. */
     currentBranch: string | null;
+    /**
+     * #137: `currentBranch` above is a branch with no commit on it yet, so it is
+     * in no list here — `for-each-ref refs/heads/` has nothing to list until the
+     * first commit exists. Without this field the API sees a branch name that is
+     * absent from the branches and refuses the session as «Branch main does not
+     * exist in this project»; with it, the folder is offered and a copy of its
+     * own is refused early and in words.
+     */
+    unborn: boolean;
+    /**
+     * #137: HEAD is a commit rather than a branch. `currentBranch` is null for
+     * this AND for «the runner could not read the folder», and the wizard has to
+     * tell them apart: one is fixed by checking a branch out, the other is not
+     * the person's to fix at all.
+     */
+    detached: boolean;
     currentSha: string | null;
     /**
      * The repository's own main branch (ADR 0004) — not the same question as
@@ -537,6 +559,13 @@ export declare function gitRefs(workspacePath: string): Promise<GitRefsResult>;
 export interface WorkspaceStateResult {
     /** The branch the project folder is on; null when HEAD is detached. */
     branch: string | null;
+    /**
+     * #137: that branch has no commit on it yet. `branch` is still its name and
+     * the folder is still perfectly workable — this is what stops every reader
+     * downstream from turning «no sha» into «detached HEAD», which is what the
+     * run's precondition and the session feed were both doing.
+     */
+    unborn: boolean;
     sha: string | null;
     subject: string;
     /** Committer date of that commit, ISO-8601. */

package/dist/gitops.js

@@ -2,7 +2,7 @@ import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { firstConventionalBranch, remoteDefaultBranch, sanitizeBranch } from './git.js';
+import { firstConventionalBranch, headState, remoteDefaultBranch, sanitizeBranch } from './git.js';
 import { isSecretPath, maskString } from './policy.js';
 const execFileAsync = promisify(execFile);
 const GIT_TIMEOUT_MS = 30_000;
@@ -13,7 +13,7 @@ const DIFF_CAP_BYTES = 200_000;
  * single commit can be diffed against. Constant in every git repository ever
  * made — it is the SHA-1 of the empty tree object.
  */
-const EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+export const EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
 /**
  * Global git switches every call in this module needs.
  *
@@ -246,8 +246,21 @@ async function resolveBase(workspacePath, sessionBranch, pinnedBase) {
     return { ...(await guessBase(workspacePath, sessionBranch)), pinned: false, baseMissing: false };
 }
 async function guessBase(workspacePath, sessionBranch) {
-    const current = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD');
-    if (current !== sessionBranch && current !== 'HEAD') {
+    // #137: this read had no `.catch` at all, so on a repository with no commits
+    // git's own manual page («ambiguous argument 'HEAD'») travelled out of the
+    // runner, through the API and into a 409 toast. Every refusal that can be
+    // reached from a screen leaves here as a sentence somebody can act on.
+    const head = await headState(workspacePath);
+    // #137: NOT the branch-picker's sentence. That one says «start a session in
+    // the project folder itself», which is advice for somebody choosing where a
+    // session will work — and whoever reads THIS is already inside one, looking
+    // at a file list or a history tab. True but unactionable is the exact shape
+    // this ticket is about, so each place says the thing its own reader can do.
+    if (head.unborn) {
+        throw new Error('This repository has no commits yet, so there is nothing to compare this session against. Make the first commit and it will start working.');
+    }
+    const current = head.branch;
+    if (current && current !== sessionBranch) {
         return { baseBranch: current, baseRef: current };
     }
     // One list, one order, one place — the same helper the binding uses to learn
@@ -255,7 +268,9 @@ async function guessBase(workspacePath, sessionBranch) {
     const conventional = await firstConventionalBranch(workspacePath);
     if (conventional)
         return { baseBranch: conventional, baseRef: conventional };
-    throw new Error(`Cannot determine the base branch (workspace is on ${current})`);
+    throw new Error(current
+        ? `Cannot determine the base branch (the project folder is on ${current}, the session's own branch)`
+        : 'Cannot determine the base branch: the project folder is not on a branch (a detached HEAD) — check one out there');
 }
 /** How far apart two refs are, in one call: `[behind, ahead]`. */
 async function aheadBehind(cwd, baseRef, branchRef) {
@@ -1136,7 +1151,27 @@ async function applySessionImpl(input) {
             error: WORKSPACE_DIRTY_MESSAGE,
         };
     }
-    const workspaceBranch = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD');
+    // #137: read through `headState`. The bare call threw git's manual page into
+    // the «Apply» toast on a repository with no commits, and answered the literal
+    // word `HEAD` on a detached one — a value that then went on to be compared
+    // with a branch name and merged into.
+    const workspaceHead = await headState(workspacePath);
+    if (workspaceHead.unborn) {
+        // Its own sentence, for the same reason as `guessBase` above: whoever
+        // pressed «Apply» is not choosing where to work, and telling them to start
+        // a session in the project folder answers a question they did not ask.
+        return {
+            applied: false,
+            error: 'The project folder has no commits yet, and git cannot fold work into a branch that has none. Make the first commit there, then apply.',
+        };
+    }
+    const workspaceBranch = workspaceHead.branch;
+    if (!workspaceBranch) {
+        return {
+            applied: false,
+            error: 'The project folder is not on a branch (a detached HEAD), so there is nowhere to apply this to — check a branch out there first',
+        };
+    }
     if (workspaceBranch === sessionBranch) {
         return { applied: false, error: 'The workspace is checked out on the session branch itself' };
     }
@@ -1156,6 +1191,7 @@ async function applySessionImpl(input) {
         await git(worktreePath, 'commit', '-m', 'chore(devbridge): session changes before apply');
     }
     const branchSha = await git(workspacePath, 'rev-parse', sessionBranch);
+    // Safe unconditionally now: an unborn HEAD left through the refusal above.
     const baseShaBefore = await git(workspacePath, 'rev-parse', 'HEAD');
     // Captured BEFORE anything is written, so a failed merge can tell its own
     // leftovers from somebody's work that appeared meanwhile.
@@ -1339,10 +1375,15 @@ const MAX_BRANCHES = 200;
  * not after the worktree command fails.
  */
 export async function gitBranches(workspacePath) {
-    const [rawBranches, rawWorktrees, currentBranch, remotesRaw] = await Promise.all([
+    const [rawBranches, rawWorktrees, head, remotesRaw] = await Promise.all([
         git(workspacePath, 'for-each-ref', `--count=${MAX_BRANCHES + 1}`, '--sort=-committerdate', '--format=%(refname:short)%00%(objectname)%00%(committerdate:iso-strict)%00%(subject)', 'refs/heads/'),
         git(workspacePath, 'worktree', 'list', '--porcelain').catch(() => ''),
-        git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null),
+        // #137: through `headState`, not `rev-parse --abbrev-ref HEAD`. Caught, that
+        // call answered `null` for a folder one `git init` old and the literal word
+        // `HEAD` for a detached one — so the wizard could not tell a repository
+        // waiting for its first commit from a checkout nobody should commit into,
+        // and greyed out «In the project folder» for both.
+        headState(workspacePath),
         git(workspacePath, 'remote').catch(() => ''),
     ]);
     // `worktree list --porcelain` emits stanzas: `worktree <path>` … `branch <ref>`.
@@ -1380,8 +1421,12 @@ export async function gitBranches(workspacePath) {
         branch.merged = mergedSet.has(branch.name);
     return {
         branches,
-        currentBranch: currentBranch === 'HEAD' ? null : currentBranch,
-        currentSha: await git(workspacePath, 'rev-parse', 'HEAD').catch(() => null),
+        currentBranch: head.branch,
+        unborn: head.unborn,
+        detached: head.detached,
+        currentSha: head.unborn
+            ? null
+            : await git(workspacePath, 'rev-parse', 'HEAD').catch(() => null),
         defaultBranch: await remoteDefaultBranch(workspacePath).catch(() => null),
         remotes: remotesRaw.split('\n').filter(Boolean).slice(0, 20),
         truncated,
@@ -1886,11 +1931,16 @@ const MAX_REFS = 500;
  * short name.
  */
 export async function gitRefs(workspacePath) {
-    const [raw, rawWorktrees, currentBranch, currentSha, remotesRaw] = await Promise.all([
+    const [raw, rawWorktrees, head, currentSha, remotesRaw] = await Promise.all([
         git(workspacePath, 'for-each-ref', `--count=${MAX_REFS + 1}`, '--sort=-committerdate', '--format=%(refname)%00%(objectname)%00%(committerdate:iso-strict)%00%(upstream:short)%00%(subject)', 'refs/heads', 'refs/remotes', 'refs/tags'),
         git(workspacePath, 'worktree', 'list', '--porcelain').catch(() => ''),
-        git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null),
-        git(workspacePath, 'rev-parse', 'HEAD').catch(() => null),
+        // #137: the fifth reader of the same question, and the one left behind by
+        // the first pass. Caught, so no raw git escapes — but it answered «no
+        // branch» for a folder the wizard, the run's precondition and the session
+        // feed all report as standing on `main`, and one screen disagreeing with
+        // three about the same folder is how this class of bug starts again.
+        headState(workspacePath),
+        git(workspacePath, 'rev-parse', '--verify', '--quiet', 'HEAD').catch(() => null),
         git(workspacePath, 'remote').catch(() => ''),
     ]);
     const checkedOut = new Map();
@@ -1925,7 +1975,7 @@ export async function gitRefs(workspacePath) {
         refs.push({
             name: name.slice(0, 200),
             type,
-            isHead: type === 'head' && name === currentBranch,
+            isHead: type === 'head' && name === head.branch,
             sha,
             subject: maskString(subjectParts.join('\0')).slice(0, 300),
             date: (date ?? '').slice(0, 40),
@@ -1935,7 +1985,7 @@ export async function gitRefs(workspacePath) {
     }
     return {
         refs,
-        currentBranch: currentBranch === 'HEAD' ? null : currentBranch,
+        currentBranch: head.branch,
         currentSha,
         remotes: remotesRaw.split('\n').filter(Boolean).slice(0, 20),
         truncated,
@@ -1949,21 +1999,26 @@ export async function gitRefs(workspacePath) {
  * question behind «how do I know docker was not rebuilt». Read-only.
  */
 export async function workspaceState(workspacePath) {
-    const [branchRaw, sha, porcelain, upstreamRaw, remotesRaw, meta] = await Promise.all([
-        git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null),
-        git(workspacePath, 'rev-parse', 'HEAD').catch(() => null),
+    const [head, sha, porcelain, upstreamRaw, remotesRaw, meta] = await Promise.all([
+        // #137: `rev-parse --abbrev-ref HEAD` could not tell «no commits yet» from
+        // «detached HEAD» — both arrived here as `null` — and this value is what the
+        // run's precondition reads, so a fresh `git init` was refused with a
+        // sentence about checking a branch out that it could not act on.
+        headState(workspacePath),
+        git(workspacePath, 'rev-parse', '--verify', '--quiet', 'HEAD').catch(() => null),
         git(workspacePath, 'status', '--porcelain').catch(() => ''),
         git(workspacePath, 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}').catch(() => null),
         git(workspacePath, 'remote').catch(() => ''),
         git(workspacePath, 'log', '-1', '--format=%s%x00%cI', 'HEAD', '--').catch(() => ''),
     ]);
-    const branch = branchRaw === 'HEAD' ? null : branchRaw;
+    const branch = head.branch;
     const upstream = upstreamRaw ? sanitizeBranch(upstreamRaw) : null;
     const distance = upstream ? await aheadBehind(workspacePath, upstream, 'HEAD') : null;
     const [subject, date] = meta.split('\0');
     const dirtyLines = porcelain.split('\n').filter(Boolean);
     return {
         branch,
+        unborn: head.unborn,
         sha,
         subject: maskString(subject ?? '').slice(0, SUBJECT_CAP),
         date: (date ?? '').slice(0, 40),

package/dist/index.js

@@ -393,6 +393,19 @@ function runnerCapabilities(apiUrlOverride) {
          * machine in the fleet is up to date.
          */
         agentOutsideFolder: true,
+        /**
+         * #137: this runner can read a repository that has no commits yet.
+         *
+         * Announced for one reason, and it is a message rather than a refusal: when
+         * an OLDER runner meets that repository it answers with git's own manual
+         * page, and the API turns anything it cannot parse into «run `git status`
+         * on that server and see». For this particular case that advice is a dead
+         * end — `git status` there prints «On branch main / No commits yet», which
+         * looks perfectly healthy, and the person is none the wiser. With this flag
+         * the API can say the true thing instead: the runner on that machine is too
+         * old for this, update it.
+         */
+        unbornHead: true,
         /**
          * Session 16: git is git.
          *

package/dist/protocol.d.ts

@@ -783,6 +783,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         branchPlan?: unknown;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
+    type: "hello_ack";
     sessions: {
         mode: "ask" | "plan" | "auto" | "full";
         agent: "CLAUDE" | "CODEX";
@@ -835,11 +836,11 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             baseSha?: string | undefined;
         } | undefined;
     }[];
-    type: "hello_ack";
     serverName: string;
     serverId: string;
     maxSessions?: number | undefined;
 }, {
+    type: "hello_ack";
     sessions: {
         agent: "CLAUDE" | "CODEX";
         status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
@@ -887,7 +888,6 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         branchHint?: unknown;
         branchPlan?: unknown;
     }[];
-    type: "hello_ack";
     serverName: string;
     serverId: string;
     maxSessions?: unknown;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.62.0";
+export declare const RUNNER_VERSION = "0.63.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.62.0';
+export const RUNNER_VERSION = '0.63.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",