@bridge4dev/runner 0.62.0 → 0.64.1

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

@@ -3,7 +3,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { createHash } from 'node:crypto';
+import { cleanGitEnv } from './environment.js';
 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);
@@ -89,7 +91,7 @@ async function gitIn(cwd, ...args) {
         // The project's own environment must not leak in: a GIT_INDEX_FILE or
         // GIT_DIR inherited from a parent process would silently retarget every
         // command below at the wrong repository.
-        env: cleanEnv(),
+        env: cleanGitEnv(),
     });
     return stdout.replace(/\n$/, '');
 }
@@ -106,7 +108,7 @@ async function gitStore(store, worktreePath, indexFile, ...args) {
         timeout: GIT_TIMEOUT_MS,
         maxBuffer: 32 * 1024 * 1024,
         env: {
-            ...cleanEnv(),
+            ...cleanGitEnv(),
             GIT_DIR: store,
             GIT_WORK_TREE: worktreePath,
             GIT_INDEX_FILE: indexFile,
@@ -118,22 +120,13 @@ async function gitStore(store, worktreePath, indexFile, ...args) {
     });
     return stdout.replace(/\n$/, '');
 }
-function cleanEnv() {
-    const env = { ...process.env };
-    delete env['GIT_DIR'];
-    delete env['GIT_WORK_TREE'];
-    delete env['GIT_INDEX_FILE'];
-    delete env['GIT_OBJECT_DIRECTORY'];
-    delete env['GIT_ALTERNATE_OBJECT_DIRECTORIES'];
-    return env;
-}
 async function ensureStore(worktreePath) {
     const { store, objectDir } = await storeFor(worktreePath);
     if (!fs.existsSync(store)) {
         fs.mkdirSync(path.dirname(store), { recursive: true, mode: 0o700 });
         await execFileAsync('git', ['init', '--quiet', '--bare', store], {
             timeout: GIT_TIMEOUT_MS,
-            env: cleanEnv(),
+            env: cleanGitEnv(),
         });
         fs.chmodSync(store, 0o700);
     }
@@ -325,7 +318,7 @@ async function gitRefs(store, ...args) {
     const { stdout } = await execFileAsync('git', [...GIT_GLOBAL_ARGS, '--git-dir', store, ...args], {
         timeout: GIT_TIMEOUT_MS,
         maxBuffer: 32 * 1024 * 1024,
-        env: cleanEnv(),
+        env: cleanGitEnv(),
     });
     return stdout.replace(/\n$/, '');
 }
@@ -410,8 +403,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 +511,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 +565,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 +595,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 +747,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/environment.d.ts

@@ -20,6 +20,21 @@ export interface RunnerIdentity {
     isRoot: boolean;
 }
 export declare function runnerIdentity(): RunnerIdentity;
+/**
+ * The environment git must be run in, with the caller's own repository scrubbed
+ * out of it.
+ *
+ * A `GIT_DIR` or `GIT_INDEX_FILE` inherited from a parent process silently
+ * retargets every git command at a DIFFERENT repository — the runner is started
+ * by systemd, but a session's agent is not, and neither is a test. The restore
+ * points have run this way since #126; #417 needs the same guarantee for a much
+ * blunter reason: `git init` under an inherited `GIT_DIR` initialises somewhere
+ * else entirely and reports success.
+ *
+ * Here rather than in `checkpoints.ts`, where it was written, because it is now
+ * the answer to «how does this package run git» and has two callers.
+ */
+export declare function cleanGitEnv(): NodeJS.ProcessEnv;
 export interface PathAccess {
     path: string;
     exists: boolean;

package/dist/environment.js

@@ -19,6 +19,29 @@ export function runnerIdentity() {
     }
     return { user, uid, gid, home: os.homedir(), isRoot: uid === 0 };
 }
+/**
+ * The environment git must be run in, with the caller's own repository scrubbed
+ * out of it.
+ *
+ * A `GIT_DIR` or `GIT_INDEX_FILE` inherited from a parent process silently
+ * retargets every git command at a DIFFERENT repository — the runner is started
+ * by systemd, but a session's agent is not, and neither is a test. The restore
+ * points have run this way since #126; #417 needs the same guarantee for a much
+ * blunter reason: `git init` under an inherited `GIT_DIR` initialises somewhere
+ * else entirely and reports success.
+ *
+ * Here rather than in `checkpoints.ts`, where it was written, because it is now
+ * the answer to «how does this package run git» and has two callers.
+ */
+export function cleanGitEnv() {
+    const env = { ...process.env };
+    delete env['GIT_DIR'];
+    delete env['GIT_WORK_TREE'];
+    delete env['GIT_INDEX_FILE'];
+    delete env['GIT_OBJECT_DIRECTORY'];
+    delete env['GIT_ALTERNATE_OBJECT_DIRECTORIES'];
+    return env;
+}
 /** As root every access check passes, which is true and worth saying out loud. */
 function canAccess(target, mode) {
     try {

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;
@@ -50,6 +106,42 @@ export interface PathValidation {
  * '/opt/ids'». That sentence is true and unactionable.
  */
 export declare function validateWorkspacePath(workspacePath: string): Promise<PathValidation>;
+/**
+ * What became of «create this folder and put git in it» (#417).
+ *
+ * `created` and `exists` are separate answers on purpose: a folder that was
+ * already there is not a failure — the wizard simply goes on and binds it —
+ * while `created: false, exists: false` is never a success.
+ */
+export interface ProjectDirInit {
+    ok: boolean;
+    /** This call made the directory. */
+    created: boolean;
+    /** There was already a directory at this path when we looked. */
+    exists: boolean;
+    /** The branch the new repository is on, read back rather than assumed. */
+    branch?: string;
+    error?: string;
+}
+/**
+ * Create the project folder and initialise git in it, from the binding window
+ * (#417).
+ *
+ * Two things and no more: ONE directory — the last segment of the path, never a
+ * chain of parents — and `git init` with `main` as the branch. No first commit:
+ * an empty repository is a legitimate state (#137, and the runner has known how
+ * to work in one since 0.63.0), while an «Initial commit» nobody asked for is
+ * the thing that makes `git pull` from an existing remote refuse with
+ * «unrelated histories» later on.
+ *
+ * Its own refusal list, because `validateWorkspacePath` has none to share: that
+ * function asks «can the runner work here», which is a question about
+ * permissions, and every answer it gives is about reaching, reading and writing.
+ * «Should anything be created here at all» is a different question and this is
+ * the only place that asks it. The API cannot ask it either — it sees the
+ * runner's verdict and nothing of the machine — so the list lives here.
+ */
+export declare function initProjectDir(target: string): Promise<ProjectDirInit>;
 /**
  * The repository's main branch, read locally (ADR 0004).
  *

package/dist/git.js

@@ -2,8 +2,10 @@ import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { previewsDir, worktreesDir } from './paths.js';
-import { firstUnreachableAncestor, inspectPath, looksLikeDubiousOwnership, runnerIdentity, safeDirectoryCommand, } from './environment.js';
+import { previewsDir, stateDir, worktreesDir } from './paths.js';
+import { cleanGitEnv, firstUnreachableAncestor, inspectPath, looksLikeDubiousOwnership, runnerIdentity, safeDirectoryCommand, } from './environment.js';
+import { isGitInternalPath, isInsideWorktree, isSecretPath } from './policy.js';
+import { log } from './log.js';
 const execFileAsync = promisify(execFile);
 const GIT_TIMEOUT_MS = 30_000;
 /**
@@ -14,12 +16,27 @@ const GIT_TIMEOUT_MS = 30_000;
  * Ninety seconds is the owner's number (plan §9, 06.09.2026).
  */
 const WORKTREE_ADD_TIMEOUT_MS = 90_000;
+/**
+ * Every git call in this file names its repository with `cwd` and nothing else,
+ * so an inherited `GIT_DIR` (or index, or object store) can only ever point
+ * somewhere we did not mean — see `cleanGitEnv`. Free everywhere; load-bearing
+ * in `initProjectDir`, where `git init` under an inherited `GIT_DIR` would
+ * initialise a different directory and report success (#417).
+ */
 async function git(cwd, ...args) {
-    const { stdout } = await execFileAsync('git', args, { cwd, timeout: GIT_TIMEOUT_MS });
+    const { stdout } = await execFileAsync('git', args, {
+        cwd,
+        timeout: GIT_TIMEOUT_MS,
+        env: cleanGitEnv(),
+    });
     return stdout.trim();
 }
 async function gitSlow(cwd, timeoutMs, ...args) {
-    const { stdout } = await execFileAsync('git', args, { cwd, timeout: timeoutMs });
+    const { stdout } = await execFileAsync('git', args, {
+        cwd,
+        timeout: timeoutMs,
+        env: cleanGitEnv(),
+    });
     return stdout.trim();
 }
 /**
@@ -94,6 +111,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,20 +245,335 @@ 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 } : {}),
     };
 }
+/**
+ * The branch a repository created from the binding window starts on (#417).
+ *
+ * One name, here, because two calls ask for it — `git init --initial-branch`
+ * and the `symbolic-ref` that stands in for it on a git older than 2.28 — and a
+ * folder that came out on `master` because the two disagreed would be a bug
+ * nobody sees until a push.
+ */
+const INITIAL_BRANCH = 'main';
+/**
+ * Directories a project folder is never created inside (#417).
+ *
+ * The root itself and the trees a Linux system is assembled from. Deliberately
+ * a short, literal list rather than a clever rule: everything here is a place
+ * where `mkdir` succeeding is worse than it failing, and a person who typed one
+ * of them meant something else. `/opt`, `/srv`, `/home`, `/var/www` are NOT on
+ * it — those are exactly where projects live.
+ *
+ * `/usr/local` and friends are covered by their parents: the test is «is this
+ * path at or below one of these».
+ */
+const SYSTEM_DIRECTORIES = [
+    '/etc',
+    '/usr',
+    '/bin',
+    '/sbin',
+    '/lib',
+    '/lib32',
+    '/lib64',
+    '/libx32',
+    '/boot',
+    '/proc',
+    '/sys',
+    '/dev',
+    '/run',
+];
+function refuseInit(error) {
+    return { ok: false, created: false, exists: false, error };
+}
+/**
+ * Why this path may not be created, or `null` — asked of a STRING (#417).
+ *
+ * Pulled out of `initProjectDir` because it has to be asked twice: once about
+ * what the person typed, and again about where that path really lands once the
+ * filesystem has had its say. See `realLandingPlace`.
+ */
+function pathClassRefusal(candidate) {
+    if (isGitInternalPath(candidate)) {
+        return `${candidate} is inside a .git directory, which belongs to git itself — pick a folder for the project instead`;
+    }
+    if (candidate === path.sep || SYSTEM_DIRECTORIES.some((dir) => isAtOrBelow(candidate, dir))) {
+        return `${candidate} is a system directory on this server — pick a folder for the project instead`;
+    }
+    // Said separately from the line above, because it would not be true there:
+    // `~/.ssh` is not a system directory, and a refusal that misnames what it is
+    // refusing teaches the person the wrong thing about their own machine.
+    if (isSecretPath(candidate)) {
+        return `${candidate} is on this server's protected list — pick a folder for the project instead`;
+    }
+    // `isSecretPath` cannot answer this one: the runner tree is on its list, but
+    // `worktrees/` and `previews/` are excused from it so an agent can read its
+    // own workspace. Everything under the state directory is the runner's own
+    // bookkeeping either way, and a project living inside it would be rewritten by
+    // the next session cleanup. Both sides go through the real filesystem, because
+    // `stateDir()` is built from `os.homedir()` and a symlinked home would
+    // otherwise make the two paths look unrelated.
+    const state = realPathOf(stateDir());
+    if (isAtOrBelow(candidate, state)) {
+        return `${candidate} is inside the runner's own state directory — pick a folder for the project instead`;
+    }
+    return null;
+}
+/** `realpathSync` where it works, the path itself where it does not. */
+function realPathOf(target) {
+    try {
+        return fs.realpathSync(target);
+    }
+    catch {
+        return path.resolve(target);
+    }
+}
+/**
+ * Where `mkdir` would actually land, symlinks and all (#417).
+ *
+ * Every refusal above is string work — `path.resolve` does not follow symlinks,
+ * `isSecretPath` normalises nothing, and containment is `path.relative`. The
+ * kernel disagrees: on a stock Debian `/var/run` IS `/run`, so `/var/run/shop`
+ * passes a list that exists to refuse exactly that, and the repository ends up
+ * on tmpfs and is gone at the next reboot.
+ *
+ * `policy.ts` solves the same problem in `normalize()` by resolving the parent
+ * and putting the last segment back on. That is not enough here, because this
+ * is asked BEFORE anything about the parent is known: with `/tmp/link -> /etc`
+ * and the path `/tmp/link/new/project`, the parent does not exist, its
+ * `realpath` fails, and the fallback is the unresolved string — which would then
+ * earn the advice «create /tmp/link/new first», i.e. make a folder in `/etc`. So
+ * the walk goes up to the deepest ancestor that DOES exist, resolves that, and
+ * puts every missing segment back on.
+ */
+function realLandingPlace(resolved) {
+    const missing = [];
+    let existing = resolved;
+    for (;;) {
+        try {
+            const real = fs.realpathSync(existing);
+            return path.join(real, ...missing.reverse());
+        }
+        catch {
+            const up = path.dirname(existing);
+            if (up === existing)
+                return resolved;
+            missing.push(path.basename(existing));
+            existing = up;
+        }
+    }
+}
+/**
+ * Is `target` at or below `root`?
+ *
+ * `isInsideWorktree` is the containment helper this package already has, and it
+ * answers exactly this question — the name says worktree because that was its
+ * first caller, not because it knows anything about worktrees.
+ */
+function isAtOrBelow(target, root) {
+    return isInsideWorktree(target, root);
+}
+/**
+ * Create the project folder and initialise git in it, from the binding window
+ * (#417).
+ *
+ * Two things and no more: ONE directory — the last segment of the path, never a
+ * chain of parents — and `git init` with `main` as the branch. No first commit:
+ * an empty repository is a legitimate state (#137, and the runner has known how
+ * to work in one since 0.63.0), while an «Initial commit» nobody asked for is
+ * the thing that makes `git pull` from an existing remote refuse with
+ * «unrelated histories» later on.
+ *
+ * Its own refusal list, because `validateWorkspacePath` has none to share: that
+ * function asks «can the runner work here», which is a question about
+ * permissions, and every answer it gives is about reaching, reading and writing.
+ * «Should anything be created here at all» is a different question and this is
+ * the only place that asks it. The API cannot ask it either — it sees the
+ * runner's verdict and nothing of the machine — so the list lives here.
+ */
+export async function initProjectDir(target) {
+    const me = runnerIdentity();
+    // The same rule the API's `WorkspacePathSchema` applies, re-derived here: the
+    // runner is the process that actually calls `mkdir`, and it must not trust the
+    // wire (QA-99 MAJOR-4 is the same argument for `validate_path`).
+    if (!target.startsWith('/') || target.split('/').includes('..')) {
+        return refuseInit('The project folder must be an absolute path with no ".." segments');
+    }
+    const resolved = path.resolve(target);
+    // The cheap pass, on what the person typed: nothing touches the disk for a
+    // path that is obviously not a project folder.
+    const typedRefusal = pathClassRefusal(resolved);
+    if (typedRefusal)
+        return refuseInit(typedRefusal);
+    // The second pass, and the one that decides: where would `mkdir` LAND? A
+    // symlinked ancestor otherwise walks straight through every refusal above,
+    // and `/var/run/shop` on a stock Debian is not a hypothetical: that directory
+    // IS `/run`, and the repository would sit on tmpfs until the next reboot.
+    //
+    // Asked BEFORE any permission check, and that order is the point (the 0.64.0
+    // build had it the other way round and was never published): for a runner that is
+    // not root, `/tmp/link -> /etc` failed «can the runner write to the parent»
+    // first — and the refusal then advised `chown <runner> /tmp/link`, which is
+    // `chown` on `/etc`. «This is a system directory» must win over «grant
+    // yourself access to it».
+    const landing = realLandingPlace(resolved);
+    if (landing !== resolved) {
+        const realRefusal = pathClassRefusal(landing);
+        // Both paths named, in that order: the person recognises what they typed,
+        // and then learns where it actually goes — which is the fact they have to
+        // act on.
+        if (realRefusal)
+            return refuseInit(`${resolved} leads to ${realRefusal}`);
+    }
+    const here = inspectPath(resolved);
+    if (here.unreachable) {
+        const blocked = firstUnreachableAncestor(resolved) ?? resolved;
+        return refuseInit(`The runner runs as ${me.user} and is not allowed into ${blocked}, so it cannot create ${resolved}. ` +
+            `Grant that user access to the directory (for example \`chmod o+x ${blocked}\`, ` +
+            `or \`setfacl -m u:${me.user}:x ${blocked}\`), then try again.`);
+    }
+    if (here.exists) {
+        // Not a refusal, and deliberately not a `mkdir` either: a directory that is
+        // already there is the ordinary case of pressing the button twice, and the
+        // window's next move — bind it — is the right one.
+        if (here.isDirectory)
+            return { ok: true, created: false, exists: true };
+        return refuseInit(`${resolved} already exists and is not a directory`);
+    }
+    const parent = path.dirname(resolved);
+    const above = inspectPath(parent);
+    if (above.unreachable) {
+        const blocked = firstUnreachableAncestor(parent) ?? parent;
+        return refuseInit(`The runner runs as ${me.user} and is not allowed into ${blocked}, so it cannot create ${resolved}. ` +
+            `Grant that user access to the directory (for example \`chmod o+x ${blocked}\`, ` +
+            `or \`setfacl -m u:${me.user}:x ${blocked}\`), then try again.`);
+    }
+    if (!above.exists || !above.isDirectory) {
+        return refuseInit(`${parent} does not exist on this server, and the runner creates only the last folder of the path. ` +
+            `Create ${parent} there first (\`mkdir -p ${parent}\` as a user who may write to it), then try again.`);
+    }
+    if (!above.writable) {
+        return refuseInit(`The runner runs as ${me.user} and cannot write to ${parent}, so it cannot create ${resolved} there. ` +
+            `Give that user write access (for example \`setfacl -m u:${me.user}:rwx ${parent}\`, ` +
+            `or \`chown ${me.user} ${parent}\` if the directory is meant to be theirs), then try again.`);
+    }
+    try {
+        // Deliberately NOT `recursive: true`: the chain of parents is somebody
+        // else's decision about the layout of their machine, and a button that
+        // quietly makes `/opt/a/b/c` out of a typo is worse than one that says the
+        // folder above is missing.
+        fs.mkdirSync(resolved);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'EEXIST') {
+            // Somebody else got there between `inspectPath` and here — or the name was
+            // never free at all: `mkdir(2)` answers EEXIST for ANY existing name, and
+            // a dangling symlink is invisible to the `statSync` above, which follows
+            // it and reports «not there». Look again rather than assume: «a directory
+            // is there» is what the window binds on next.
+            const now = inspectPath(resolved);
+            if (now.exists && now.isDirectory)
+                return { ok: true, created: false, exists: true };
+            return refuseInit(`${resolved} already exists and is not a directory`);
+        }
+        return refuseInit(`The runner runs as ${me.user} and could not create ${resolved} (${code ?? 'unknown error'}). ` +
+            `Check that ${parent} is writable by that user, then try again.`);
+    }
+    try {
+        await initRepositoryOnMain(resolved);
+    }
+    catch (error) {
+        // All-or-nothing, like laying out a worktree (#360): a folder that exists
+        // but is not a repository binds and then fails on «Not a git work tree»,
+        // which is a worse place to learn about it. `rmdirSync` refuses a directory
+        // with anything in it, which is exactly the safety wanted here — we are only
+        // ever removing the empty one made three lines up.
+        let takenBack = true;
+        try {
+            fs.rmdirSync(resolved);
+        }
+        catch {
+            // It is not empty, so it is not only ours to remove. Leave it — and say
+            // so, because the two outcomes want opposite things from the person.
+            takenBack = false;
+        }
+        // Git's own words go to the runner's log, where the person who can act on
+        // them is; the sentence that travels names the folder and what to do next.
+        // `describeGitFailure` would have carried `fatal: …` into a browser, and
+        // the API's net for that (`actionableRunnerRefusal`) rewrites the WHOLE
+        // text — so forwarding it would have cost this sentence as well.
+        log.warn('init_project_dir: git init failed', {
+            path: resolved,
+            takenBack,
+            error: describeGitFailure(error),
+        });
+        const said = takenBack
+            ? `Git would not start in ${resolved}, so the folder was removed again and nothing was left behind. ` +
+                `The runner's log on this server has git's own words — check that git is installed and that the disk is writable, then try again.`
+            : `${resolved} was created, but git would not start in it, and the folder is still there. ` +
+                `The runner's log on this server has git's own words. Run \`git init -b main\` in that folder yourself, or remove it and try again.`;
+        return { ok: false, created: !takenBack, exists: !takenBack, error: said };
+    }
+    // Read back rather than reported from intent: on a git old enough to need the
+    // fallback below, «main» is something we asked for, not something we saw.
+    const head = await headState(resolved);
+    return {
+        ok: true,
+        created: true,
+        exists: true,
+        ...(head.branch ? { branch: head.branch } : {}),
+    };
+}
+/**
+ * `git init` with `main` as the initial branch, on every git the fleet has.
+ *
+ * `--initial-branch` arrived in git 2.28 (2020); Debian 10 and CentOS 7 ship
+ * older ones and are still out there. The fallback is not a lesser outcome —
+ * `symbolic-ref` on a repository with no commits in it is exactly what `-b`
+ * does — it just takes two calls.
+ *
+ * Tried rather than version-parsed on purpose: the question is whether THIS git
+ * accepts the flag, and the flag itself answers it in one cheap call.
+ */
+async function initRepositoryOnMain(repoPath) {
+    try {
+        await git(repoPath, 'init', '--quiet', '--initial-branch', INITIAL_BRANCH);
+        return;
+    }
+    catch {
+        // Falls through: either the flag is unknown, or `git init` itself failed —
+        // and the plain form below tells the two apart by either working or
+        // throwing the real reason to the caller.
+    }
+    await git(repoPath, 'init', '--quiet');
+    // Best effort, and deliberately not fatal: `git init` has already made a
+    // working repository, and the caller reads the branch back off it rather than
+    // trusting this call. Throwing here would throw away a folder that is fine.
+    await git(repoPath, 'symbolic-ref', 'HEAD', `refs/heads/${INITIAL_BRANCH}`).catch(() => undefined);
+}
 /**
  * The repository's main branch, read locally (ADR 0004).
  *
@@ -308,6 +678,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 +1125,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.
          *
@@ -553,6 +566,11 @@ function runnerCapabilities(apiUrlOverride) {
             // это чтение, а не установка, и машину, чей владелец запретил ставить из
             // дашборда, спросить о том, что на ней стоит, по-прежнему можно.
             'agent_versions_refresh',
+            // #417: create the project folder and `git init` in it, from the
+            // binding window. Announced here and nowhere else — the API refuses the
+            // button on a machine that does not name this command, because an older
+            // runner drops a command it cannot parse and never answers.
+            'init_project_dir',
             // #396. Listed unconditionally, unlike the `restart` flag above: the
             // flag is what the dashboard draws a button from, and this list is what
             // `runCommand` dispatches on. A machine that cannot restart still

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/supervisor.js

@@ -9,7 +9,7 @@ import { classifyFailure, isRepeatOfSameFailure, MAX_RETRIES_PER_SESSION, retryD
 import { evaluateRecipeCommand, maskSecrets, maskString } from './policy.js';
 import { agentPromptSizeLabel, inspectAgentPrompt, quotePath, readAgentPrompt, } from './agent-prompt.js';
 import { JournalStore } from './journal.js';
-import { deleteSessionBranch, ensurePreviewWorktree, ensureSessionWorktree, prepareDirectWorkspace, previewWorktreePath, removePreviewWorktree, removeSessionWorktree, repoKeyFor, sessionWorktreePath, validateWorkspacePath, WorktreePrepareError, } from './git.js';
+import { deleteSessionBranch, ensurePreviewWorktree, ensureSessionWorktree, initProjectDir, prepareDirectWorkspace, previewWorktreePath, removePreviewWorktree, removeSessionWorktree, repoKeyFor, sessionWorktreePath, validateWorkspacePath, WorktreePrepareError, } from './git.js';
 import { readRecipeProposal } from './recipe.js';
 import { RECIPE_STEP_NAMES, parseProjectRecipe } from './recipe-schema.js';
 import { proposeCommitMessage } from './commit-message.js';
@@ -6140,6 +6140,37 @@ export class Supervisor {
                         ...(validation.ok ? {} : { error: validation.error }),
                     });
                 }
+                /**
+                 * «Create this folder and put git in it», from the binding window
+                 * (#417).
+                 *
+                 * Next to `validate_path` because it is the same conversation: that
+                 * command answers «the folder is not there», and this one is what the
+                 * person presses next. Everything it is allowed and not allowed to do
+                 * is decided in `initProjectDir` — the API sees a verdict and never the
+                 * machine.
+                 *
+                 * Under the repository lock like every other operation on a folder,
+                 * even though there is no repository yet: `repoKeyFor` falls back to the
+                 * path itself when git cannot answer, so two presses of the button
+                 * serialise against each other rather than racing into one `mkdir`.
+                 */
+                case 'init_project_dir': {
+                    const path = typeof frame.args?.['path'] === 'string' ? frame.args['path'] : null;
+                    if (!path)
+                        return void reply({ ok: false, error: 'path argument is required' });
+                    const init = await this.withRepoLockFor(path, () => initProjectDir(path));
+                    // Remembered for the same reason `validate_path` remembers it: this
+                    // is a real project directory now, and `devbridge-runner doctor`
+                    // checks the permissions of the ones it knows about.
+                    if (init.ok)
+                        rememberWorkspacePath(path);
+                    return void reply({
+                        ok: init.ok,
+                        result: init,
+                        ...(init.ok ? {} : { error: init.error }),
+                    });
+                }
                 case 'clean': {
                     const sessionId = frame.sessionId;
                     if (!sessionId)

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.62.0";
+export declare const RUNNER_VERSION = "0.64.1";
 //# 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.64.1';
 //# sourceMappingURL=version.js.map

package/package.json

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