Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
feat(workspace): a local checkout's new run starts from the newer of …
…its base and upstream (FIX-1927)

Before cutting a new branch in a repository listed in localRepositories,
the host fetches that base's upstream branch into its tracking ref only,
then cuts from local when it is equal or ahead, from upstream's commit
when local is behind, and refuses base-diverged when both have moved.
A failed fetch, or an upstream URL that fails the shape check, warns and
compares with the last-fetched copy. Listing the checkout admits its
upstream; remotes.allow isn't asked. place.repo.baseCommit is now set.

checkRemote is split into shared shape rules plus the allowlist gate;
checkRemoteShape asks only the first, reading an absolute path as file://.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GJ9UL2RHLrxJsiGFnkuxjt
  • Loading branch information
claude committed Oct 13, 2026
commit 3ce6403e486fb8a142c7efa40d49e5c75e5c2a7d
161 changes: 141 additions & 20 deletions packages/workspace/src/local-host.ts
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,14 @@
*
* - **A remote is judged before git sees it** (`./remotes`). A refused remote
* starts no process at all, and every process that does start can reach
* only the transports the allowlist names.
* only the transports the allowlist names. The one exception is a listed
* repository's own upstream, which listing it admits: judged for shape
* all the same, and fetched speaking only its own scheme.
* - **Existing work is never discarded.** A checkout already on disk is handed
* back as it is — no fetch, no reset, no rebase — and one this host cannot
* explain is refused, not cleared. Only a NEW branch is cut from a freshly
* fetched remote.
* fetched remote, and in a repository the operator named, from the newer of
* its base and that base's freshly fetched upstream.
* - **The kept files are the record, the directory is not.** `project/` and
* `workspace/` are hydrated from one key prefix of a collection and flushed
* back to it. A directory this process did not hydrate is rebuilt from the
Expand Down Expand Up @@ -80,10 +83,10 @@ import {
import { createHostPlace } from "./host-place";
import { acquireLock, HOST_LOCK_BOUNDS, releaseLock } from "./lock";
import { assertScope, createProjection, type Projection } from "./projection";
import { allowedProtocols, checkRemote, redactRemote, type AllowedRemote } from "./remotes";
import { allowedProtocols, checkRemote, checkRemoteShape, redactRemote, type AllowedRemote } from "./remotes";
import type { RepoRunSource, RunFiles, RunSource, RunSourceAnswer } from "./run-source";
import type { FlushReport, Place } from "./types";
import { gitAnsweredNo, ignoredProblem, provisionWorktree, remainingBudget, type IgnoredDirectory } from "./worktree";
import { firstLine, gitAnsweredNo, ignoredProblem, provisionWorktree, remainingBudget, type IgnoredDirectory } from "./worktree";

/** The directory names inside a place. People and agents read them. */
const CHECKOUT_DIR = "checkout";
Expand Down Expand Up @@ -113,15 +116,22 @@ const LOCAL_LOCK_SUFFIX = ".place.lock";
const HOST_ID_FILE = ".host-id";
/** Where a held snapshot is laid out for a person, beside the checkout. */
const HELD_DIR = "held";
/**
* The share of a provision's remaining budget a local repository's upstream
* fetch may take, so one that hangs still leaves time to cut the branch.
*/
const FETCH_BUDGET_SHARE = 0.5;

/**
* The host would not provision this run, and says why — before anything was
* created and before any agent was paid for.
*
* `reason` is stable: `"invalid-remote"`, `"remote-not-allowed"`,
* `"remote-unreadable"`, or whatever reason a run source refused with. A
* caller should fail the run with it rather than retry: none of these clears
* on its own.
* `"remote-unreadable"`, `"base-diverged"` (a repository on this machine
* whose base and its upstream each have commits the other lacks), or
* whatever reason a run source refused with. A caller should fail the run
* with it rather than retry: none of these clears by itself, and
* `base-diverged` clears once someone pulls or rebases, or pushes, there.
*/
export class WorkspaceRefusedError extends Error {
constructor(
Expand All @@ -146,10 +156,17 @@ export interface LocalWorkspaceHostOptions {
/**
* Repositories on this machine that runs are cut from directly, as their
* absolute paths. A source answering one of these paths as its `repo` gets a
* worktree of that repository itself: no clone, no fetch, and the run's
* branch kept in it. When the source names no kept files, the place's
* directory is the checkout; when it names them, the worktree is the
* place's `checkout/` and the files are in `project/` beside it.
* worktree of that repository itself: no clone, and the run's branch kept
* in it. When the source names no kept files, the place's directory is the
* checkout; when it names them, the worktree is the place's `checkout/` and
* the files are in `project/` beside it.
*
* A NEW branch whose base tracks an upstream is cut from the newer of the
* two, after fetching that one upstream branch into its tracking ref; a
* base and upstream that have each moved are refused as `base-diverged`,
* and a failed fetch falls back to the copy last fetched, with a warning.
* Listing a path admits fetching its own upstream: `remotes.allow` isn't
* asked, though the URL is still judged for shape before git sees it.
*
* Any other bare path is still refused. Listing a path is the operator's
* allowance, judged before any git process, the same as `remotes.allow`.
Expand Down Expand Up @@ -262,7 +279,7 @@ export interface WorkspacePlace {
created: boolean;
/** The branch the run's branch was cut from. Only when `created`. */
baseRef?: string;
/** The commit it was cut at. Only when `created`, and only for a clone. */
/** The commit it was cut at. Only when `created`. */
baseCommit?: string;
};
/** Where a repository place came from. */
Expand Down Expand Up @@ -677,10 +694,12 @@ export function localWorkspaceHost(options: LocalWorkspaceHostOptions): Workspac
/**
* A worktree of a repository the operator named, at `checkout`: the place
* itself when the run keeps no files, `<place>/checkout` when it does. No
* clone and no fetch: the base is read in the repository as it stands, and
* the run's branch stays in it. No lock over the repository: each run has
* its own place and branch, and git keeps concurrent worktrees apart. Called
* holding the place's lock.
* clone: the run's branch stays in the repository. A new branch is cut
* from the base, or from its upstream when that is ahead (`fetchUpstream`);
* the repository's own branches, index and files never move. No lock over
* the repository: each run has its own place and branch, git keeps
* concurrent worktrees apart, and a fetch that loses a ref lock to another
* falls back like any failed fetch. Called holding the place's lock.
*/
async function provisionLocalCheckout(
repo: string,
Expand All @@ -702,16 +721,33 @@ export function localWorkspaceHost(options: LocalWorkspaceHostOptions): Workspac
deadline,
now,
...(ignored !== undefined ? { ignored } : {}),
// Read before anything is made, so a ref the repository doesn't have
// fails naming it and leaves no marker, tree or branch behind.
// Read before anything is made, so a ref the repository doesn't have,
// or a base that has split from its upstream, fails naming it and
// leaves no marker, tree or branch behind. Only a NEW branch gets here.
base: async (left) => {
let local: string;
try {
await git(repo, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`], left());
local = await git(repo, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`], left());
} catch (error) {
if (!gitAnsweredNo(error)) throw error;
throw new WorkspaceRefusedError("remote-unreadable", `${repo} has no "${base}" to cut the run's branch from.`);
}
return { ref: base, commitish: base };
const upstream = await fetchUpstream(repo, base, left);
Comment thread
jhoffner marked this conversation as resolved.
Resolved
// Equal, or local ahead: the person's branch, as it always was.
if (upstream === undefined || (await isAncestor(repo, upstream.commit, local, left))) {
Comment thread
jhoffner marked this conversation as resolved.
Resolved
return { ref: base, commitish: base, commit: local };
}
// Behind: cut at the commit, never the ref's name, so the run's branch
// doesn't come out tracking the person's upstream.
if (await isAncestor(repo, local, upstream.commit, left)) {
return { ref: base, commitish: upstream.commit, commit: upstream.commit };
}
throw new WorkspaceRefusedError(
"base-diverged",
`${repo}: "${base}" (${local}) and its upstream ${upstream.ref} (${upstream.commit}) each have ` +
`commits the other lacks, so neither is the base to cut a run's branch from. To start a run ` +
`from it, pull or rebase, or push, in ${repo}.`,
);
},
});
return {
Expand All @@ -720,9 +756,94 @@ export function localWorkspaceHost(options: LocalWorkspaceHostOptions): Workspac
branch,
created: worktree.created,
...(worktree.baseRef !== undefined ? { baseRef: worktree.baseRef } : {}),
...(worktree.baseCommit !== undefined ? { baseCommit: worktree.baseCommit } : {}),
};
}

/**
* Bring `base`'s upstream up to date in a repository the operator listed,
* and say where it is: its tracking ref and commit, or `undefined` when the
* base has none (a tag, a commit, a detached `HEAD`, a branch tracking
* nothing or another local branch) or none was ever fetched.
*
* Only that one upstream branch is fetched, into its own tracking ref: no
* tags, no `FETCH_HEAD`, no maintenance, no other ref. Listing the
* repository admits its upstream, so `remotes.allow` isn't asked, but the
* URL is judged for shape before git sees it and git may speak only its
* scheme. **A fetch that fails, or a URL that fails the judge, is a warning,
* never a refusal**: the comparison uses the copy last fetched. A probe
* that fails is raised: read as "no upstream", it would cut from a stale
* base without a word.
*/
async function fetchUpstream(
repo: string,
base: string,
left: () => number,
): Promise<{ ref: string; commit: string } | undefined> {
const full = await git(repo, ["rev-parse", "--symbolic-full-name", base], left());
if (!full.startsWith("refs/heads/")) return undefined;
const [ref = "", remoteName = "", remoteRef = ""] = (
await git(repo, ["for-each-ref", "--format=%(upstream)%0a%(upstream:remotename)%0a%(upstream:remoteref)", full], left())
).split("\n");
Comment thread
jhoffner marked this conversation as resolved.
Resolved
if (!ref.startsWith("refs/remotes/") || remoteName === "" || remoteName === ".") return undefined;

const skip = (why: string) =>
console.warn(
`[workspace] ${repo}: ${why}, so "${base}" is compared with the copy of ${ref} last fetched.`,
);
let url: string | undefined;
try {
url = await git(repo, ["remote", "get-url", remoteName], left());
} catch (error) {
skip(`could not read the URL of remote "${remoteName}" (${firstLine(error)})`);
}
if (url !== undefined) {
const judged = checkRemoteShape(url);
if ("reason" in judged) skip(`its upstream was not fetched: ${judged.message}`);
else if (!/^refs\/heads\/[^\s:]+$/.test(remoteRef)) skip(`its upstream was not fetched: "${remoteRef}" is not a branch`);
else {
try {
await run(
"git",
[
"fetch",
"--quiet",
"--no-tags",
"--no-prune",
"--no-write-fetch-head",
"--no-auto-maintenance",
"--no-recurse-submodules",
"--",
judged.url,
`+${remoteRef}:${ref}`,
],
// A slice of what is left, so a fetch that hangs leaves time to cut.
{ cwd: repo, timeoutMs: Math.max(1, Math.floor(left() * FETCH_BUDGET_SHARE)), env: { ...env, GIT_ALLOW_PROTOCOL: judged.scheme } },
);
} catch (error) {
skip(`could not fetch "${redactRemote(judged.url)}" (${firstLine(error)})`);
}
}
}
try {
return { ref, commit: await git(repo, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], left()) };
Comment on lines +933 to +934

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Keep the fallback upstream SHA outside shared refs

When an earlier coding worktree writes its own tip to refs/remotes/origin/main and changes the live remote URL so the fetch is deliberately skipped, this lookup treats that worker-written ref as the "copy last fetched." Because the planted tip descends from local main, the next provision selects it as the newer base and inherits code from the prior run. Git explicitly allows a worktree to update a named ref with git update-ref (git-update-ref), so retain the trusted fallback SHA outside the worker-writable repository and return the isolated fetch's SHA directly after a successful fetch.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: fsd-claude
session: fix-1927
kind: reply

Part of this is fixed in 181cfe5: after a successful fetch, the comparison uses the fetched SHA directly. The fallback path is the same gap as FIX-1934, and I'm leaving it there. A run that can plant refs/remotes/origin/main can also plant refs/heads/main, and the next run is cut from that no matter what upstream says. Keeping a trusted SHA outside the repository closes only one of those two doors. FIX-1934 covers both, together with the restart pins, because they need one place outside the repository that runs can't write.


Generated by Claude Code

} catch (error) {
if (gitAnsweredNo(error)) return undefined;
throw error;
}
}

/** Whether `ancestor` is in `commit`'s history. A probe that failed is raised, never read as no. */
async function isAncestor(repo: string, ancestor: string, commit: string, left: () => number): Promise<boolean> {
try {
await git(repo, ["merge-base", "--is-ancestor", ancestor, commit], left());
return true;
} catch (error) {
if (gitAnsweredNo(error)) return false;
throw error;
}
}

/** The repository a source's `repo` names, when the operator listed it as local. */
function localRepository(repo: string): string | undefined {
if (!isAbsolute(repo)) return undefined;
Expand Down
68 changes: 53 additions & 15 deletions packages/workspace/src/remotes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,14 @@
* The operator's allowlist names hosts, reached over `https` or `ssh`, and
* optionally the word `"file"` to permit `file://` remotes. Nothing else is
* reachable: no `http`, no `git://`, no transport helper, no bare path.
*
* The shape rules and the allowlist are two steps. `checkRemote` asks both;
* `checkRemoteShape` asks only the first, for the upstream of a repository
* the operator listed on this machine, which listing it already admits.
*/
import { createHash } from "node:crypto";
import { isAbsolute } from "node:path";
import { pathToFileURL } from "node:url";

/** A remote that passed: what git is handed, and what the host keys its clone by. */
export interface AllowedRemote {
Expand Down Expand Up @@ -60,17 +66,54 @@ export function redactRemote(remote: string): string {
return remote.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/?#]*@/i, "$1");
}

/**
* A remote that passed the shape rules, before any allowlist is asked: what
* git would be handed, and the host it names (`null` for `file://`). A
* `scheme` this host never speaks carries no clone key.
*/
type ShapedRemote =
| { remote: AllowedRemote; host: string | null }
| { unspoken: string };

/** Judge `remote` against `allow`. Pure: starts nothing, reads nothing. */
export function checkRemote(remote: string, allow: readonly string[]): AllowedRemote | RefusedRemote {
const shown = redactRemote(remote);
const invalid = (why: string): RefusedRemote => ({
reason: "invalid-remote",
message: `the remote "${shown}" is not a usable git remote: ${why}.`,
});
const shaped = shapeOf(remote);
if ("reason" in shaped) return shaped;
const notAllowed = (what: string): RefusedRemote => ({
reason: "remote-not-allowed",
message: `the remote "${shown}" is not allowed on this host: ${what}.`,
message: `the remote "${redactRemote(remote)}" is not allowed on this host: ${what}.`,
});
if ("unspoken" in shaped) return notAllowed(`the host reaches remotes over https or ssh, not ${shaped.unspoken}`);
if (shaped.host === null) {
return allow.includes("file") ? shaped.remote : notAllowed("file:// remotes are off unless the host lists \"file\"");
}
const host = shaped.host;
return allow.some((entry) => entry.toLowerCase() === host) ? shaped.remote : notAllowed(`"${host}" is not a listed host`);
}

/**
* Judge a remote by its shape alone, for a URL the operator's own repository
* configuration names rather than one a run asked for: the same rules as
* `checkRemote`, with no allowlist asked. An absolute path is read as the
* `file://` URL it means, and that URL is what the result hands git.
*/
export function checkRemoteShape(remote: string): AllowedRemote | RefusedRemote {
Comment thread
jhoffner marked this conversation as resolved.
Resolved
const spelled = isAbsolute(remote) ? pathToFileURL(remote).href : remote;
const shaped = shapeOf(spelled);
if ("reason" in shaped) return shaped;
if ("unspoken" in shaped) {
return invalidRemote(spelled, `the host reaches remotes over https, ssh or file, not ${shaped.unspoken}`);
}
return shaped.remote;
}

function invalidRemote(remote: string, why: string): RefusedRemote {
return { reason: "invalid-remote", message: `the remote "${redactRemote(remote)}" is not a usable git remote: ${why}.` };
}

/** The shape rules every remote is held to, whoever admits it. Pure. */
function shapeOf(remote: string): ShapedRemote | RefusedRemote {
const invalid = (why: string): RefusedRemote => invalidRemote(remote, why);

if (remote.startsWith("-")) return invalid("it starts with \"-\", which git reads as an option");
// Whitespace and control characters have no place in a remote and every
Expand All @@ -92,30 +135,26 @@ export function checkRemote(remote: string, allow: readonly string[]): AllowedRe
if (url.password !== "") return invalid("it carries a password");

if (scheme === "file") {
if (!allow.includes("file")) return notAllowed("file:// remotes are off unless the host lists \"file\"");
if (url.hostname !== "" && url.hostname !== "localhost") return invalid("a file:// remote names no host");
let path: string;
try {
path = decodeURIComponent(url.pathname);
} catch {
return invalid("its path holds a malformed %-escape");
}
return { url: remote, scheme: "file", cloneKey: cloneKeyFor("file", path) };
}
if (scheme !== "https" && scheme !== "ssh") {
return notAllowed(`the host reaches remotes over https or ssh, not ${scheme}`);
return { remote: { url: remote, scheme: "file", cloneKey: cloneKeyFor("file", path) }, host: null };
}
if (scheme !== "https" && scheme !== "ssh") return { unspoken: scheme };
if (scheme === "https" && url.username !== "") return invalid("it carries a credential");
const host = url.hostname.toLowerCase();
if (host === "" || host.startsWith("-")) return invalid("its host is missing or starts with \"-\"");
if (!allow.some((entry) => entry.toLowerCase() === host)) return notAllowed(`"${host}" is not a listed host`);
// A non-default port is another server, which can hold an unrelated
// repository at the same path. The URL parser already drops `:443` from
// https; `:22` is ssh's default and is dropped here, so both spellings of
// the default stay one clone with the scp-like form.
const port = scheme === "ssh" && url.port === "22" ? "" : url.port;
const authority = port === "" ? host : `${host}:${port}`;
return { url: remote, scheme, cloneKey: cloneKeyFor(authority, repositoryPath(url.pathname)) };
return { remote: { url: remote, scheme, cloneKey: cloneKeyFor(authority, repositoryPath(url.pathname)) }, host };
}

// Git's scp-like form, `[user@]host:path`, is ssh — but only when the colon
Expand All @@ -124,8 +163,7 @@ export function checkRemote(remote: string, allow: readonly string[]): AllowedRe
if (scp !== null) {
const host = scp[2]!.toLowerCase();
if (host.startsWith("-")) return invalid("its host starts with \"-\"");
if (!allow.some((entry) => entry.toLowerCase() === host)) return notAllowed(`"${host}" is not a listed host`);
return { url: remote, scheme: "ssh", cloneKey: cloneKeyFor(host, repositoryPath(scp[3]!)) };
return { remote: { url: remote, scheme: "ssh", cloneKey: cloneKeyFor(host, repositoryPath(scp[3]!)) }, host };
}

return invalid("a bare path is not a remote — spell a local repository as a file:// URL");
Expand Down
3 changes: 2 additions & 1 deletion packages/workspace/src/worktree.ts
Original file line number Diff line number Diff line change
Expand Up @@ -464,7 +464,8 @@ async function looksHalfBuilt(
}
}

function firstLine(error: unknown): string | undefined {
/** The first line git (or node) said about a failure. */
export function firstLine(error: unknown): string | undefined {
return String((error as { stderr?: unknown })?.stderr || (error as Error)?.message || error)
.split("\n")
.find((line) => line.trim() !== "")
Expand Down
Loading