@bridge4dev/runner 0.61.0 → 0.63.0

package/README.md

@@ -49,12 +49,18 @@ it. If you would rather run it in the foreground, or under your own supervisor,
 
 ## What it does on your machine
 
-- Creates a **git worktree and a branch per session**, so an agent never works in your
-  working copy and never touches your current branch.
-- Enforces a local policy layer the dashboard **cannot** raise: an allow/deny list for
-  commands, secret masking in everything it streams, and its own ceiling on how many
-  sessions may run at once. Anything the server asks for is bounded by what this config
-  permits.
+- Runs a session either **in the project folder itself** — the default: the branch it is
+  already on, nothing to apply afterwards — or in a **git worktree on a session branch of
+  its own**, which DevBridge asks for when the folder is busy or a branch was named. Which
+  one a session gets is decided per session, in the dashboard.
+- Enforces a local policy layer. Part of it the dashboard **cannot** raise: secret files and
+  keys are never read, nothing is written into any repository's `.git`, and `sudo`, service
+  control, docker and the firewall are refused in every trust level. Part of it is the bound
+  project's own setting, chosen by a manager in DevBridge: whether the agent may `git push`
+  and to which branches, and whether it may read and change files **outside the project
+  folder** — other projects on the same machine included. Out of the box the agent pushes
+  nothing and stays in its folder. Plus secret masking in everything it streams, and its own
+  ceiling on how many sessions may run at once.
 - Streams the session journal with sequence numbers and acknowledgements, so a restart of
   either side resumes instead of losing work.
 - Never uploads your source. Diffs and file views are requested per file, and files

package/dist/adapters/claude.js

@@ -8,7 +8,7 @@ import { mcpConfigPath } from '../paths.js';
 import { lowerPriority } from '../process-priority.js';
 import { cageSpawn, noteSessionAgentPid, memoryDeathSentence, releaseSessionScope, sessionMemoryEnv, sessionMemoryPromptLine, } from '../session-cage.js';
 import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
-import { availableModes, cardDescription, DIRECT_BRANCH_RULE, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
+import { availableModes, cardDescription, DIRECT_BRANCH_RULE, folderRuleFor, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { percentFromUtilization, RATE_WINDOW_MINUTES, rateWindowKey } from './rate-limits.js';
 import { applyUsagePercentages, lastUsageRows, readUsageRows } from './claude-usage.js';
 import { assertClaudeInstalled, claudeExecutableOption, sessionClaudePath, } from '../agent-binary.js';
@@ -166,14 +166,19 @@ const MODE_TO_PERMISSION = {
  * no line: the agent plans around a restriction that is not there, or walks
  * into one it was told did not exist.
  */
-function systemAppendFor(spec) {
+function systemAppendFor(spec, mode) {
     const pushBanned = spec.gitPolicy?.agentPushBan !== false;
+    // #418: which folder line this session gets, if any — see `folderRuleFor`.
+    const folderRule = folderRuleFor(spec, mode);
     const guarded = spec.gitPolicy?.agentProtectedBranches ?? ['main', 'master'];
     const memoryLine = sessionMemoryPromptLine(spec.sessionId);
     return [
         'You are running inside a DevBridge dev session, controlled from the DevBridge dashboard.',
         'Rules:',
-        '- Work ONLY inside the current working directory.',
+        // #418. The three cases live in `folderRuleFor` — one copy for both
+        // adapters, and the Codex adapter asks the same function whether a mode
+        // switch would change what the agent was told.
+        ...(folderRule === null ? [] : [folderRule]),
         // Session 13: pushing was refused outright by layer 1 in every trust mode,
         // and saying so here saved the agent a turn spent discovering it. Session
         // 18 makes it the project's decision — so the sentence has to follow the
@@ -203,8 +208,8 @@ function systemAppendFor(spec) {
     ].join('\n');
 }
 /** DevBridge's own rules, then whatever this workspace adds (session 13). */
-function composeSystemAppend(spec) {
-    const base = systemAppendFor(spec);
+function composeSystemAppend(spec, mode) {
+    const base = systemAppendFor(spec, mode);
     return spec.workspaceContext ? `${base}\n\n${spec.workspaceContext}` : base;
 }
 /**
@@ -585,7 +590,7 @@ class ClaudeSession {
             systemPrompt: {
                 type: 'preset',
                 preset: 'claude_code',
-                append: composeSystemAppend(spec),
+                append: composeSystemAppend(spec, this.mode),
             },
             canUseTool: (toolName, input, opts) => this.onCanUseTool(toolName, input, opts),
             // Ticket #113: a running subagent forks its own conversation every ~30s

package/dist/adapters/codex.js

@@ -6,7 +6,7 @@ import { RUNNER_VERSION } from '../version.js';
 import { repairCodexAuth } from './codex-home.js';
 import { AppServerClient, asRecord, num, RpcError, RpcTimeoutError, str, } from './codex-protocol.js';
 import { truncate } from './claude.js';
-import { availableModes, cardDescription, DIRECT_BRANCH_RULE, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
+import { availableModes, cardDescription, DIRECT_BRANCH_RULE, folderRuleFor, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { clampPercent, rateWindowKeyFromMinutes } from './rate-limits.js';
 import { answerSummary, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
 // Codex adapter over `codex app-server` (stage C). The normalized AgentEvent
@@ -60,6 +60,37 @@ const MODE_POLICY = {
     // exactly like Claude's bypassPermissions. The dashboard says so.
     full: { approvalPolicy: 'never', sandbox: 'danger-full-access', plan: false },
 };
+/**
+ * Where a `workspace-write` turn may write (#418).
+ *
+ * Codex confines writes in the KERNEL, not in our policy: under `auto` the
+ * sandbox is `workspace-write` with `writableRoots: [cwd]`, so a write outside
+ * fails inside the CLI, comes back as a «retry without sandbox?» approval, and
+ * only then reaches layer 1. With the project's permission on, that round trip
+ * is exactly the refusal the ticket exists to remove — so the ROOT is widened.
+ *
+ * **The sandbox is widened, never dropped**, and that is the whole safety of
+ * this function. `danger-full-access` looks like the simpler answer and is the
+ * wrong one: for Codex the kernel sandbox refusing something IS the only
+ * channel that reaches `evaluateToolUse` (the adapter calls it from
+ * `onApproval` and nowhere else). Remove the sandbox and nothing ever
+ * escalates, so `sudo`, docker, the firewall, secret paths, any repository's
+ * `.git`, the project's prompt file and the project's own git policy would all
+ * stop being enforced for Codex — the very list the setting promises to keep.
+ * Keeping `workspaceWrite` keeps that channel, and keeps `networkAccess: false`
+ * with it, so the permission moves one boundary and no other.
+ *
+ * **STRICT does not widen.** There a step outside must still raise a card, and
+ * the only way to raise one for Codex is to let the sandbox refuse it first.
+ *
+ * Read on every turn rather than captured at launch, because the setting can be
+ * switched while the session runs.
+ */
+function writableRootsFor(spec) {
+    if (spec.trustMode === 'STRICT')
+        return [spec.cwd];
+    return spec.gitPolicy?.agentAllowOutsideFolder === true ? ['/'] : [spec.cwd];
+}
 /**
  * DevBridge's own rules — composed per session since session 18, and kept
  * deliberately in step with `systemAppendFor` in the Claude adapter.
@@ -69,14 +100,19 @@ const MODE_POLICY = {
  * `workMode: DIRECT` (the default since session 16), and the push sentence is
  * only true when the project has «Принудительно запретить push» switched on.
  */
-function systemAppendFor(spec) {
+function systemAppendFor(spec, mode) {
     const pushBanned = spec.gitPolicy?.agentPushBan !== false;
+    // #418: which folder line this session gets, if any — see `folderRuleFor`.
+    const folderRule = folderRuleFor(spec, mode);
     const guarded = spec.gitPolicy?.agentProtectedBranches ?? ['main', 'master'];
     const memoryLine = sessionMemoryPromptLine(spec.sessionId);
     return [
         'You are running inside a DevBridge dev session, controlled from the DevBridge dashboard.',
         'Rules:',
-        '- Work ONLY inside the current working directory.',
+        // #418. The three cases live in `folderRuleFor` — one copy for both
+        // adapters, and the Codex adapter asks the same function whether a mode
+        // switch would change what the agent was told.
+        ...(folderRule === null ? [] : [folderRule]),
         pushBanned
             ? '- Commit your work in the current branch with clear messages. You cannot push: `git push` is blocked for this project. A human presses «Push» and «Apply» in DevBridge when the branch is ready.'
             : guarded.length > 0
@@ -96,8 +132,8 @@ function systemAppendFor(spec) {
     ].join('\n');
 }
 /** DevBridge's own rules, then whatever this workspace adds (session 13). */
-function composeSystemAppend(spec) {
-    const base = systemAppendFor(spec);
+function composeSystemAppend(spec, mode) {
+    const base = systemAppendFor(spec, mode);
     return spec.workspaceContext ? `${base}\n\n${spec.workspaceContext}` : base;
 }
 // Allowlist, not denylist: whatever secrets live in the daemon's environment
@@ -534,8 +570,14 @@ class CodexSession {
         return {
             cwd: this.spec.cwd,
             approvalPolicy: policy.approvalPolicy,
+            // #418 does NOT change this one, and that is deliberate. The thread-level
+            // channel takes the CLI-style MODE string, which has no way to say «this
+            // root»; the mode itself is unchanged (`workspace-write` stays
+            // `workspace-write`), and the roots travel with every turn below. Both
+            // channels therefore still describe the same sandbox, which is what R10
+            // of the plan asks for — there is no second shape to keep in step.
             sandbox: policy.sandbox,
-            developerInstructions: composeSystemAppend(this.spec),
+            developerInstructions: composeSystemAppend(this.spec, this.mode),
             ...(this.model ? { model: this.model } : {}),
             ...(this.spec.mcp ? { config: this.mcpOverlay() } : {}),
         };
@@ -582,7 +624,8 @@ class CodexSession {
             // [] is accepted, null is rejected outright.
             input: [{ type: 'text', text, text_elements: [] }],
             approvalPolicy: policy.approvalPolicy,
-            sandboxPolicy: sandboxPolicyFor(policy.sandbox, this.spec.cwd),
+            // #418: the roots live here and only here — see `writableRootsFor`.
+            sandboxPolicy: sandboxPolicyFor(policy.sandbox, this.spec),
             ...(this.model ? { model: this.model } : {}),
             // "Override the reasoning effort for this turn and subsequent turns" —
             // the same sticky-override channel the model uses (there is still no
@@ -793,12 +836,29 @@ class CodexSession {
         this.refreshCapabilities();
     }
     /**
-     * Codex needs no new process for any mode: `approvalPolicy` and the sandbox
-     * policy travel with the next `turn/start`, so the change is in force from
-     * the next turn whatever it is (ticket #156).
+     * Codex needs no new process for its POLICY: `approvalPolicy` and the sandbox
+     * travel with the next `turn/start`, so the change is in force from the next
+     * turn whatever it is (ticket #156).
+     *
+     * Its RULES are the other half, and they cannot follow (#418). DevBridge's
+     * own instructions reach Codex ONLY as the thread's `developerInstructions`,
+     * fixed when the thread opens: this protocol version has no `settings/update`,
+     * and putting the text on the turn instead is the duplicated-prompt defect of
+     * ticket #179. So a line that has to DISAPPEAR in «Unrestricted» — where
+     * layer 1 is never consulted and the sentence would be the only thing left
+     * enforcing it — can only disappear with a new thread.
+     *
+     * Asked precisely rather than by hard-coding the `full` boundary: would the
+     * folder line actually change? With «may work outside the project folder» ON
+     * the answer is never — the sentence is then the same in every mode — so
+     * those projects keep Codex's free, instant mode switching. Only a session
+     * that would be told something different pays for a new process, and it pays
+     * exactly what a Claude session has always paid for the same move.
      */
-    modeSwitchNeedsRelaunch(_mode) {
-        return false;
+    modeSwitchNeedsRelaunch(mode) {
+        if (!availableModes(this.spec.trustMode).includes(mode))
+            return false;
+        return folderRuleFor(this.spec, mode) !== folderRuleFor(this.spec, this.mode);
     }
     async setMode(mode) {
         if (!availableModes(this.spec.trustMode).includes(mode)) {
@@ -2255,9 +2315,10 @@ class CodexSession {
 }
 class ResumeFailed extends Error {
 }
-function sandboxPolicyFor(mode, cwd) {
+function sandboxPolicyFor(mode, spec) {
     // turn/start takes the structured SandboxPolicy, while thread/start takes the
-    // CLI-style SandboxMode string. Same intent, two shapes.
+    // CLI-style SandboxMode string. Same intent, two shapes — and only this one
+    // can name the writable roots, which is why #418 lives here.
     switch (mode) {
         case 'read-only':
             return { type: 'readOnly', networkAccess: false };
@@ -2266,7 +2327,11 @@ function sandboxPolicyFor(mode, cwd) {
         default:
             return {
                 type: 'workspaceWrite',
-                writableRoots: [cwd],
+                writableRoots: writableRootsFor(spec),
+                // Unchanged by #418, on purpose: the permission is about the file
+                // system, and letting the network out with it would be a second
+                // boundary nobody asked to move. A network command still fails in the
+                // sandbox, still escalates, and still ends at layer 1.
                 networkAccess: false,
                 excludeTmpdirEnvVar: false,
                 excludeSlashTmp: false,

package/dist/adapters/types.d.ts

@@ -322,6 +322,56 @@ export declare function cardDescription(verdict: PolicyDecision, own: string | u
  * into a card.
  */
 export declare const DIRECT_BRANCH_RULE = "- This session works directly in the project folder, which other sessions and people share. Stay on the current branch: do not `git checkout <branch>` or `git switch` here. To put a file back use `git checkout -- <path>` or `git restore <path>`.";
+/**
+ * «Stay in this folder» — the line layer 1 used to back up (#418).
+ *
+ * Here, beside `DIRECT_BRANCH_RULE` and for the same reason: the two
+ * `systemAppendFor` texts are hand-synced copies of each other, and a rule that
+ * has to appear in one of them and not the other is the kind of thing that
+ * drifts silently. Exported so the tests can name the exact string rather than
+ * a substring of it.
+ *
+ * NOT written when the session is «Unrestricted» — there the CLI never asks
+ * layer 1 anything, so this sentence was the only thing left enforcing it, and
+ * a rule with nothing underneath is a rule the agent refuses itself by — nor
+ * when the project has switched «may work outside the project folder» on, where
+ * `outsideFolderRule` takes its place.
+ */
+export declare const WORKING_DIRECTORY_RULE = "- Work ONLY inside the current working directory.";
+/**
+ * What replaces the line above when the project allows work outside the folder
+ * (#418).
+ *
+ * It says three things and no more: where the agent is, that it may go
+ * elsewhere when the task needs it, and what it gives up by doing so — nothing
+ * outside the folder reaches «Changes», «Apply» or a restore point. That last
+ * half is the part the agent cannot discover for itself and the part a person
+ * would otherwise find out from a diff that is missing a file.
+ */
+export declare function outsideFolderRule(cwd: string): string;
+/**
+ * Which of the two lines above this session gets, or neither (#418).
+ *
+ * One function rather than the same three-way choice written out in both
+ * `systemAppendFor` texts — and it has a second caller that made it worth
+ * extracting: the Codex adapter asks it whether a MODE SWITCH would change what
+ * the agent was told, because Codex's developer instructions are fixed when the
+ * thread opens and cannot be edited afterwards.
+ *
+ * The three cases, in order:
+ *  - the project allows work outside the folder → say where the folder is and
+ *    what leaving it costs, in EVERY mode (the permission does not depend on
+ *    the mode, so neither does the sentence);
+ *  - «Unrestricted» → `null`, nothing at all. Layer 1 is never consulted there,
+ *    so this line would be the only thing enforcing the rule: the agent refuses
+ *    itself by a sentence nothing backs up, which is the complaint #418 came
+ *    from;
+ *  - otherwise → the rule as it has always been, with layer 1 behind it.
+ *
+ * The mode passed in must be the one the session is actually IN, not the one it
+ * was asked for: a `full` refused on a STRICT workspace keeps the line.
+ */
+export declare function folderRuleFor(spec: SessionSpec, mode: AgentMode | undefined): string | null;
 /**
  * One question inside an agent's question call (session 12).
  *

package/dist/adapters/types.js

@@ -100,6 +100,65 @@ export function cardDescription(verdict, own) {
  * into a card.
  */
 export const DIRECT_BRANCH_RULE = '- This session works directly in the project folder, which other sessions and people share. Stay on the current branch: do not `git checkout <branch>` or `git switch` here. To put a file back use `git checkout -- <path>` or `git restore <path>`.';
+/**
+ * «Stay in this folder» — the line layer 1 used to back up (#418).
+ *
+ * Here, beside `DIRECT_BRANCH_RULE` and for the same reason: the two
+ * `systemAppendFor` texts are hand-synced copies of each other, and a rule that
+ * has to appear in one of them and not the other is the kind of thing that
+ * drifts silently. Exported so the tests can name the exact string rather than
+ * a substring of it.
+ *
+ * NOT written when the session is «Unrestricted» — there the CLI never asks
+ * layer 1 anything, so this sentence was the only thing left enforcing it, and
+ * a rule with nothing underneath is a rule the agent refuses itself by — nor
+ * when the project has switched «may work outside the project folder» on, where
+ * `outsideFolderRule` takes its place.
+ */
+export const WORKING_DIRECTORY_RULE = '- Work ONLY inside the current working directory.';
+/**
+ * What replaces the line above when the project allows work outside the folder
+ * (#418).
+ *
+ * It says three things and no more: where the agent is, that it may go
+ * elsewhere when the task needs it, and what it gives up by doing so — nothing
+ * outside the folder reaches «Changes», «Apply» or a restore point. That last
+ * half is the part the agent cannot discover for itself and the part a person
+ * would otherwise find out from a diff that is missing a file.
+ */
+export function outsideFolderRule(cwd) {
+    return (`- Your working directory is ${cwd}; you may read and change files elsewhere on this server ` +
+        `when the task needs it. Only what is inside ${cwd} shows up in the DevBridge diff and restore points.`);
+}
+/**
+ * Which of the two lines above this session gets, or neither (#418).
+ *
+ * One function rather than the same three-way choice written out in both
+ * `systemAppendFor` texts — and it has a second caller that made it worth
+ * extracting: the Codex adapter asks it whether a MODE SWITCH would change what
+ * the agent was told, because Codex's developer instructions are fixed when the
+ * thread opens and cannot be edited afterwards.
+ *
+ * The three cases, in order:
+ *  - the project allows work outside the folder → say where the folder is and
+ *    what leaving it costs, in EVERY mode (the permission does not depend on
+ *    the mode, so neither does the sentence);
+ *  - «Unrestricted» → `null`, nothing at all. Layer 1 is never consulted there,
+ *    so this line would be the only thing enforcing the rule: the agent refuses
+ *    itself by a sentence nothing backs up, which is the complaint #418 came
+ *    from;
+ *  - otherwise → the rule as it has always been, with layer 1 behind it.
+ *
+ * The mode passed in must be the one the session is actually IN, not the one it
+ * was asked for: a `full` refused on a STRICT workspace keeps the line.
+ */
+export function folderRuleFor(spec, mode) {
+    // `=== true` — silence keeps the agent in, exactly as `policy.ts` resolves the
+    // same field.
+    if (spec.gitPolicy?.agentAllowOutsideFolder === true)
+        return outsideFolderRule(spec.cwd);
+    return mode === 'full' ? null : WORKING_DIRECTORY_RULE;
+}
 /**
  * The name our MCP server is registered under inside an agent session.
  *

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;