@ricsam/r5d-worker 0.0.100 → 0.0.103

package/dist/types/main.d.ts

@@ -185,6 +185,11 @@ type WorkerClientMessage = {
     requestId: string;
     result?: WorkerOperationResult;
     error?: string;
+} | {
+    /** Immediate receipt for a branch create/delete; `queuePosition` is 0 when it runs at once. */
+    type: "operation_queued";
+    requestId: string;
+    queuePosition: number;
 } | {
     type: "exec_result";
     requestId: string;
@@ -290,13 +295,18 @@ type WorkerServerMessage = {
     requiredAncestorHeads?: string[];
 } | {
     /**
-     * Content-derived tokens naming each canonical project repository's
-     * observable ref state, keyed by project id. Replace-all: projects
-     * absent from a message have no advertised token and observation falls
-     * back to fetching. See `project-mirror-fetch-policy.ts`.
+     * Content-derived tokens naming ref state the server read from disk:
+     * `tokens` per canonical project repository, `mountTokens` per
+     * checked-out project branch (keyed by project id then branch name),
+     * and the current head of the hidden workspace repository. Replace-all:
+     * anything absent from a message has no advertised token and the
+     * corresponding fetch runs. Older servers send `tokens` only. See
+     * `project-mirror-fetch-policy.ts`.
      */
     type: "project_mirror_refs_tokens";
     tokens: Record<string, string>;
+    mountTokens?: Record<string, Record<string, string>>;
+    workspaceHead?: string;
 } | {
     type: "create_project_branch";
     requestId: string;
@@ -304,6 +314,8 @@ type WorkerServerMessage = {
     projectId: string;
     sourceBranch: string;
     targetBranch: string;
+    /** `carry` copies the source checkout's uncommitted changes; `clean` checks out its commit only. */
+    workingTree: "carry" | "clean";
 } | {
     type: "delete_project_branch";
     requestId: string;
@@ -618,14 +630,17 @@ export declare const workerPtyTestHarness: {
     removeEnvFiles: typeof removePtyEnvFiles;
     resolveEnvFileReferences: typeof resolvePtyEnvFileReferences;
     commandHasWorkspaceEffect: typeof workerCommandHasWorkspaceEffect;
+    targetProcessEnv: typeof targetProcessEnv;
     canonicalSyncTerminalHead: typeof canonicalSyncTerminalHead;
     ptyIsWorkspaceBusy: typeof workerPtyIsWorkspaceBusy;
     parseLinuxForegroundBusy: typeof parseLinuxPtyForegroundBusy;
 };
 export type WorkerBuiltInToolPaths = {
-    artifactsDir?: string;
-    plansDir?: string;
-    activePlanFile?: string;
+    rootDir?: string;
+    sessionId?: string;
+    projectId?: string;
+    branchName?: string;
+    activePlanId?: string;
 };
 export declare function isArtifactEnvPath(filePath: string): boolean;
 export declare function syncSessionArtifacts(input: {
@@ -638,11 +653,11 @@ export declare function prepareArtifactEnvForShell(input: {
     baseUrl: string;
     token: string;
     sessionId?: string;
-    artifactRoot: string;
+    rootDir: string;
 }): Promise<Record<string, string>>;
 export declare function preparePlanEnvForShell(input: {
     target: WorkerSessionTarget;
-    planRoot: string;
+    rootDir: string;
     activePlanId?: string;
 }): Record<string, string>;
 type ResolvedWorkerFilePath = {
@@ -943,8 +958,7 @@ export declare function prepareBuiltInToolPathsForTarget(input: {
     token: string;
     sessionId?: string;
     activePlanId?: string;
-    artifactRoot: string;
-    planRoot: string;
+    rootDir: string;
     access: "read" | "write";
 }): Promise<WorkerBuiltInToolPaths | undefined>;
 export declare function readWorkerTextFile(branchPath: string, filePath: string, offset?: number, limit?: number, builtInPaths?: WorkerBuiltInToolPaths): WorkerReadFileResult;
@@ -960,8 +974,7 @@ declare function executeWriteFileOperation(input: {
     resolvedTarget: ResolvedWorkerSessionTarget;
     baseUrl: string;
     token: string;
-    artifactRoot: string;
-    planRoot: string;
+    rootDir: string;
     assertAdmission: () => void;
 }): Promise<WorkerWriteFileResult>;
 declare function executeEditFileOperation(input: {
@@ -971,8 +984,7 @@ declare function executeEditFileOperation(input: {
     resolvedTarget: ResolvedWorkerSessionTarget;
     baseUrl: string;
     token: string;
-    artifactRoot: string;
-    planRoot: string;
+    rootDir: string;
     assertAdmission: () => void;
 }): Promise<WorkerEditFileResult>;
 export declare function grepWorkerFiles(branchPath: string, input: {
@@ -992,14 +1004,14 @@ export declare function listWorkerDirectory(branchPath: string, inputPath?: stri
 export declare function listWorkerCodeDirectory(branchPath: string, inputPath: string): WorkerCodeListResult;
 export declare function readWorkerCodeFile(branchPath: string, inputPath: string): WorkerCodeReadResult;
 export declare function readWorkerImageFile(branchPath: string, filePath: string, builtInPaths?: WorkerBuiltInToolPaths): WorkerViewFileBytesResult;
+declare function targetProcessEnv(rootDir: string, target: WorkerSessionTarget): Record<string, string>;
 export declare function prepareShellEnvForTarget(input: {
     target: WorkerSessionTarget;
     baseUrl: string;
     token: string;
     sessionId?: string;
     activePlanId?: string;
-    artifactRoot: string;
-    planRoot: string;
+    rootDir: string;
 }): Promise<Record<string, string>>;
 declare function createNodePtyBridge(options: {
     file: string;

package/dist/types/project-mirror-fetch-policy.d.ts

@@ -1,20 +1,28 @@
 /**
- * Decides whether a periodic observation must fetch a project's hidden mirror
- * or may reuse the locally cached mirror refs. The server advertises a
- * content-derived token per project (hash of the exact ref namespaces the
- * observation fetch would transfer); when the advertised token equals the
- * token the local refs already cover, the fetch would be a no-op.
+ * Decides which part of a project's hidden mirror a periodic observation must
+ * fetch, from the tokens the server advertises and the tokens the worker's
+ * own mirror refs cover (both computed with `project-mirror-refs-token.ts`).
  *
- * Skipping is fail-open: any missing or mismatched information fetches. The
- * backstop bounds the damage of a server-side token bug (for example a token
- * computed against the wrong repository path) to one interval; every
- * git-transport writer is observed by the server's on-disk recompute, so the
- * backstop is insurance against bugs, not against known unobserved writers.
+ * Skipping is fail-open: any missing or mismatched information fetches.
+ *
+ * There is deliberately no timed backstop refetch for matching tokens. The
+ * server recomputes every advertised token from the canonical repository on
+ * disk on each heartbeat sweep, so a matching token is a fresh statement that
+ * the fetch would transfer nothing, whoever moved the refs. The worker
+ * records the tokens it covers from its own refs after every fetch and lease
+ * push, with the same shared formula, so a skip can only be stale if the
+ * canonical repository moved after the sweep that produced the advertisement
+ * — which the next sweep corrects, exactly like a tip that lands mid-cycle —
+ * or if the formula itself were wrong, which the shared module and its locked
+ * vectors guard and a periodic blind fetch would only hide. A project or
+ * mount the server advertises no token for fetches every cycle, as before
+ * tokens existed.
  */
-export declare const PROJECT_MIRROR_FETCH_BACKSTOP_MS: number;
+/** Why a fetch runs. `fail_closed` is never decided here: reset and remediation observation bypasses the gate. */
+export type ProjectMirrorFetchReason = "skipping_disabled" | "no_advertised_token" | "never_fetched" | "token_changed" | "fail_closed";
 export type ProjectMirrorFetchDecision = {
     fetch: true;
-    reason: "skipping_disabled" | "no_advertised_token" | "never_fetched" | "token_changed" | "backstop_elapsed";
+    reason: ProjectMirrorFetchReason;
 } | {
     fetch: false;
     reason: "token_match";
@@ -22,8 +30,55 @@ export type ProjectMirrorFetchDecision = {
 export declare function projectMirrorFetchDecision(input: {
     advertisedToken: string | undefined;
     fetchedToken: string | undefined;
-    lastFetchAtMs: number | undefined;
-    nowMs: number;
     skippingEnabled: boolean;
-    backstopMs?: number;
 }): ProjectMirrorFetchDecision;
+export type ProjectMirrorObservationFetchPlan = 
+/** Fetch every canonical ref of the project, as observation always did before per-mount tokens. */
+{
+    scope: "project";
+    reason: ProjectMirrorFetchReason;
+}
+/** Fetch only the named mounts' branch heads and handoff refs. */
+ | {
+    scope: "mounts";
+    mounts: Array<{
+        branchName: string;
+        reason: ProjectMirrorFetchReason;
+    }>;
+}
+/** Every token the observation depends on matches; reuse the local refs. */
+ | {
+    scope: "none";
+};
+/**
+ * Plan one project's observation fetch. With per-mount tokens advertised for
+ * the project, each mount decides for itself and only changed mounts fetch;
+ * without them (an older server) the project token decides for the whole
+ * mirror.
+ */
+export declare function planProjectMirrorObservationFetch(input: {
+    branchNames: readonly string[];
+    advertisedProjectToken: string | undefined;
+    /** Per-mount tokens for this project, keyed by branch name; undefined when the server advertised none. */
+    advertisedMountTokens: ReadonlyMap<string, string> | undefined;
+    fetchedProjectToken: string | undefined;
+    fetchedMountTokens: ReadonlyMap<string, string>;
+    skippingEnabled: boolean;
+}): ProjectMirrorObservationFetchPlan;
+export type ProjectMirrorRefsTokensAdvertisement = {
+    /** One token per project id. */
+    projectTokens: Map<string, string>;
+    /** Per-mount tokens keyed by project id then branch name; a project is present only when the server advertised mount tokens for it. */
+    mountTokens: Map<string, Map<string, string>>;
+    /** Current head of the user's hidden workspace repository, when advertised. */
+    workspaceHead: string | undefined;
+};
+/**
+ * Read a `project_mirror_refs_tokens` message. Older servers send only
+ * `tokens`; malformed entries are dropped, which fails open into fetching.
+ */
+export declare function parseProjectMirrorRefsTokensMessage(message: {
+    tokens?: unknown;
+    mountTokens?: unknown;
+    workspaceHead?: unknown;
+}): ProjectMirrorRefsTokensAdvertisement;

package/dist/types/project-mirror-refs-token.d.ts

@@ -1,15 +1,40 @@
+/** Canonical namespaces the token hashes; also the observation fetch's sources. */
+export declare const PROJECT_MIRROR_REFS_TOKEN_NAMESPACES: readonly ["refs/heads/", "refs/r5d/server-synced/"];
+/** Worker-local copy of a canonical `refs/heads/*` ref. */
 export declare const PROJECT_MIRROR_REF_PREFIX = "refs/r5d/mirror/";
 export declare const PROJECT_SERVER_SYNCED_REF_PREFIX = "refs/r5d/server-synced/";
+/** `git for-each-ref` format both sides list refs with; see parseProjectMirrorRefListing. */
+export declare const PROJECT_MIRROR_REF_LISTING_FORMAT = "--format=%(objectname) %(refname)";
 export type ProjectMirrorRef = {
     refname: string;
     objectName: string;
 };
+/** One checked-out project branch, identified by its durable incarnation id. */
+export type ProjectMirrorMount = {
+    branchName: string;
+    branchId: string;
+};
+export type ProjectMirrorRefsTokens = {
+    /** Hash over every ref in the observed namespaces. */
+    project: string;
+    /** Hash over one mount's branch head plus its handoff refs, keyed by branch name. */
+    mounts: Map<string, string>;
+};
 /**
  * Hash a ref listing into a mirror-refs token. Both sides sort here rather
  * than trusting git's listing order: renaming `refs/r5d/mirror/*` back to
  * `refs/heads/*` changes sort neighborhoods.
  */
 export declare function hashProjectMirrorRefs(refs: readonly ProjectMirrorRef[]): string;
+/**
+ * Parse `git for-each-ref` output produced with
+ * PROJECT_MIRROR_REF_LISTING_FORMAT. Malformed rows throw rather than being
+ * dropped: a caller that cannot trust its listing must not produce a token.
+ * With `namespaces`, rows outside them throw too.
+ */
+export declare function parseProjectMirrorRefListing(output: string, options?: {
+    namespaces?: readonly string[];
+}): ProjectMirrorRef[];
 /**
  * Rename locally fetched mirror refs into the namespaces the server hashes.
  * Rows outside the two observed namespaces are dropped; the caller lists only
@@ -17,3 +42,12 @@ export declare function hashProjectMirrorRefs(refs: readonly ProjectMirrorRef[])
  * it can only make tokens differ — which fails open into a fetch.
  */
 export declare function canonicalizeLocalProjectMirrorRefs(refs: readonly ProjectMirrorRef[]): ProjectMirrorRef[];
+/** The canonical refs one mount's token covers: its branch head and its server-synced handoff refs. */
+export declare function projectMirrorMountRefs(refs: readonly ProjectMirrorRef[], mount: ProjectMirrorMount): ProjectMirrorRef[];
+/**
+ * Compute the project token and one token per mount from one canonical ref
+ * listing. A mount's token is the project formula applied to the mount's own
+ * refs, so a mount whose branch is the only ref of its project has the same
+ * token as the project.
+ */
+export declare function projectMirrorRefsTokens(refs: readonly ProjectMirrorRef[], mounts: readonly ProjectMirrorMount[]): ProjectMirrorRefsTokens;

package/dist/types/project-worktrees.d.ts

@@ -1,3 +1,4 @@
+import { type ProjectMirrorMount, type ProjectMirrorRefsTokens } from "./project-mirror-refs-token";
 export declare const PROJECT_WORKTREE_SNAPSHOT_PREFIX = "r5d-project-worktrees-";
 declare const PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION: 1;
 type ProjectWorktreeSnapshotManifest = {
@@ -124,10 +125,17 @@ export declare function ensureProjectWorktrees(input: {
     onSnapshotProgress?: (progress: ProjectWorktreeSnapshotProgress) => void;
 }): Promise<ProjectWorktreeState[]>;
 export declare function projectWorktreeOperationInProgress(checkoutPath: string): boolean;
+/**
+ * How a new linked worktree's working tree starts. `carry` materializes the
+ * source checkout's Git-visible working state, uncommitted changes included;
+ * `clean` checks out the source branch's current commit and nothing else.
+ */
+export type ProjectWorktreeWorkingTreeMode = "carry" | "clean";
 export declare function createLinkedProjectBranch(input: {
     projectRoot: string;
     sourceBranchName: string;
     branchName: string;
+    workingTree: ProjectWorktreeWorkingTreeMode;
 }): {
     branchPath: string;
     baseCommitHash: string;
@@ -143,6 +151,7 @@ export declare function createOrRetryLinkedProjectBranch(input: {
     primaryBranchName: string;
     sourceBranchName: string;
     branchName: string;
+    workingTree: ProjectWorktreeWorkingTreeMode;
     pendingRetry: boolean;
 }): {
     branchPath: string;
@@ -225,19 +234,28 @@ export declare function observeProjectMirrorHeads(input: Omit<ProjectMirrorHeadU
     allowNonFastForward: boolean;
     branchIds?: ReadonlyMap<string, string>;
     refreshRemote?: boolean;
+    /**
+     * Fetch only these mounts' branch heads and handoff refs, because
+     * per-mount token gating found every other mount current. Undefined
+     * fetches the whole mirror; an empty set fetches nothing, exactly like
+     * `refreshRemote: false`.
+     */
+    fetchOnlyBranches?: ReadonlySet<string>;
 }): Promise<ProjectMirrorHeadObservation[]>;
 /**
- * Compute the mirror-refs token for the locally cached mirror state — the
- * token the server will advertise once it hashes the same refs. After a
- * successful lease push (which updates `refs/r5d/mirror/*` above), this
- * matches the server's next advertisement unless something else also moved
- * the canonical repository, in which case the mismatch fails open into a
- * fetch. Formula twin: `server/git/project-mirror-refs-token.ts`.
+ * Compute the tokens the locally cached mirror state covers — the project
+ * token and one token per mount — from one listing of `refs/r5d/mirror/*` and
+ * `refs/r5d/server-synced/*`, with the formula shared with the server. After a
+ * fetch these name exactly the canonical state the fetch transferred; after a
+ * successful lease push (which updates `refs/r5d/mirror/*` above) they predict
+ * the server's next advertisement unless something else also moved the
+ * canonical repository, in which case the mismatch fails open into a fetch.
  */
-export declare function computeLocalProjectMirrorRefsToken(input: {
+export declare function computeLocalProjectMirrorRefsTokens(input: {
     projectRoot: string;
     primaryBranchName: string;
-}): Promise<string>;
+    mounts: readonly ProjectMirrorMount[];
+}): Promise<ProjectMirrorRefsTokens>;
 /** Apply only previously observed object ids; this function never refetches. */
 export declare function applyObservedProjectMirrorHeads(input: {
     projectRoot: string;

package/dist/types/working-tree-mirror.d.ts

@@ -12,6 +12,44 @@ export type TreeEntry = {
     kind: "symlink";
     mode: number;
     target: string;
+}
+/**
+ * A submodule (D4): the enclosing repository records a commit at this path
+ * and never its contents. A leaf for every operation here: nothing beneath
+ * it is inspected, copied, captured, removed, or restored.
+ */
+ | {
+    kind: "gitlink";
+    objectId: string;
+};
+export type WorkingTreeGitlink = {
+    relativePath: string;
+    objectId: string;
+};
+/** One index record of a Git checkout, in the form `git update-index --index-info` accepts back. */
+export type WorkingTreeIndexRecord = {
+    mode: string;
+    objectId: string;
+    stage: number;
+    relativePath: string;
+};
+/**
+ * Index entries a Git-target mirror changes: the records it removes or
+ * overwrites (a restore puts them back) and the gitlinks it writes (a restore
+ * drops them first).
+ */
+export type WorkingTreeIndexChanges = {
+    removed: WorkingTreeIndexRecord[];
+    written: WorkingTreeGitlink[];
+};
+export type WorkingTreeInspectionOptions = {
+    /**
+     * Gitlinks the enclosing repository records under an all-mode root, keyed
+     * by relative path. Git checks a submodule out as an empty directory, so
+     * the filesystem alone cannot show one; the entry replaces whatever is on
+     * disk at that path. Ignored in Git mode, where the index is read directly.
+     */
+    gitlinks?: ReadonlyMap<string, string>;
 };
 /**
  * Destructive native-tree moves cannot silently apply the Git-target filter:
@@ -20,19 +58,14 @@ export type TreeEntry = {
  * every portable alias must be remediated before the old tree is retired.
  */
 export declare function assertWorkingTreeHasNoPortableGitMetadataAliases(root: string): void;
-export declare function inspectWorkingTree(root: string, mode: WorkingTreeSourceMode, options?: {
-    /**
-     * Leave an uninitialized submodule (index gitlink whose directory is
-     * empty) out of a Git-mode inspection. Its empty directory is what keeps
-     * `git status` clean, so a deletion set must never remove it.
-     */
-    omitUnpopulatedGitlinks?: boolean;
-}): Map<string, TreeEntry>;
+export declare function inspectWorkingTree(root: string, mode: WorkingTreeSourceMode, options?: WorkingTreeInspectionOptions): Map<string, TreeEntry>;
 export declare function mirrorWorkingTree(input: {
     sourceRoot: string;
     targetRoot: string;
     sourceMode: WorkingTreeSourceMode;
     deletionMode: WorkingTreeDeletionMode;
+    /** Gitlinks the enclosing repository records for an all-mode source (see `inspectWorkingTree`). */
+    sourceGitlinks?: ReadonlyMap<string, string>;
     /**
      * Defer destination fsync only while building an unpublished private tree.
      * The caller must durably fsync that complete tree before publishing it or
@@ -41,20 +74,28 @@ export declare function mirrorWorkingTree(input: {
     durability?: WorkingTreeMirrorDurability;
 }): {
     paths: string[];
+    gitlinks: WorkingTreeGitlink[];
 };
 /** Canonical relative form used by mirror plans and scopes, or null when the value is unsafe. */
 export declare function normalizeWorkingTreeRelativePath(value: string): string | null;
 export type WorkingTreeMirrorPlan = {
-    /** Every target path the mirror creates, rewrites, or verifies, ancestor directories included. */
+    /**
+     * Every target path the mirror creates, rewrites, or verifies, ancestor
+     * directories included. A gitlink is verified as a directory; paths a
+     * submodule directory on the target shields are left out.
+     */
     desired: Map<string, TreeEntry>;
     /**
      * Target entries the mirror removes or overwrites, as they are before it
      * runs. A directory entry means the whole subtree goes, ignored files
-     * included; entries beneath it are folded into it.
+     * included; entries beneath it are folded into it. Never a gitlink: a
+     * submodule directory stays, and only its index entry can change.
      */
     replaced: Map<string, TreeEntry>;
     /** Desired paths that have no target entry yet. */
     absent: string[];
+    /** Index entries the mirror changes on a Git target; empty for any other target. */
+    index: WorkingTreeIndexChanges;
 };
 /**
  * Compute exactly which target entries `mirrorWorkingTree` would remove,
@@ -63,19 +104,23 @@ export type WorkingTreeMirrorPlan = {
  * A desired path replaces its target entry when the kinds differ, a symlink
  * points elsewhere, or a file's bytes or mode differ; an equal entry is left
  * alone, so the plan covers only what the mirror actually touches. A Git
- * target's ignored trees appear only where a desired path lands on them.
+ * target's ignored trees appear only where a desired path lands on them, and
+ * its submodule directories only as index changes.
  */
 export declare function planWorkingTreeMirror(input: {
     sourceRoot: string;
     targetRoot: string;
     sourceMode: WorkingTreeSourceMode;
     deletionMode: WorkingTreeDeletionMode;
+    sourceGitlinks?: ReadonlyMap<string, string>;
 }): WorkingTreeMirrorPlan;
 export type WorkingTreeMirrorScope = {
     /** Desired paths that did not exist before the mirror ran; a restore removes them. */
     absent: string[];
     /** Directories captured whole; a restore makes them identical to the snapshot again. */
     trees: string[];
+    /** Index entries the mirror changed on a Git target; a restore drops the written gitlinks and puts the removed records back. */
+    index?: WorkingTreeIndexChanges;
 };
 /**
  * Copy the entries a mirror plan replaces into `snapshotRoot` at their

package/dist/types/workspace-git-sync.d.ts

@@ -1,4 +1,4 @@
-import { type WorkingTreeSourceMode } from "./working-tree-mirror";
+import { type WorkingTreeGitlink, type WorkingTreeSourceMode } from "./working-tree-mirror";
 export declare const WORKSPACE_GIT_BRANCH = "main";
 export declare const MAX_WORKSPACE_GIT_DIFF_BYTES: number;
 export declare const WORKSPACE_GIT_CONFIRMED_LARGE_DIFF_PUSH_OPTION = "r5d-confirm-large-diff-v1";
@@ -38,6 +38,14 @@ export type WorkspaceGitMount = {
     busy?: () => boolean;
     /** Monotonic/opaque visible-mutation token used to catch short writes that begin and end between busy checks. */
     mutationToken?: () => string;
+    /**
+     * The token a completed cycle observed when it last projected this mount.
+     * While the current token still equals it and the mount's hydration basis
+     * is the outer HEAD being projected, the outer subtree already carries the
+     * visible bytes and the mirror copy is skipped. This is a cross-cycle skip
+     * only; the per-cycle busy and token re-checks are unchanged.
+     */
+    lastProjectedMutationToken?: string;
     /** Activity-only fence used before checkout readiness is established on reconnect. */
     busyForRecovery?: () => boolean;
 };
@@ -86,8 +94,12 @@ export type WorkspaceGitSyncResult = {
     affectedPaths: string[];
     activeMountIds: string[];
     skippedMountIds: string[];
+    /** Token each active mount carried when this cycle projected it; recorded by the caller to skip unchanged mounts later. */
+    projectedMutationTokens?: Record<string, string>;
     /** Creator-local mounts whose first outer publication was measured against their source subtree. */
     initialPublicationMountIds?: string[];
+    /** Network fetches of the outer workspace head this cycle ran; zero when the advertised head proved them unnecessary. */
+    remoteHeadFetches?: number;
     conflictPaths?: string[];
     conflictSnapshotRefs?: {
         local: string;
@@ -150,11 +162,23 @@ export declare function ensureWorkspaceGitClone(input: {
         email: string;
     };
     preserveResolutionInProgress?: boolean;
+    /** Server-advertised head of the workspace remote; see resolveWorkspaceRemoteHead. */
+    advertisedRemoteHead?: string | null;
 }): Promise<{
     localHead: string | null;
     remoteHead: string | null;
+    remoteHeadFetched: boolean;
 }>;
-declare function mirrorMountsToWorkspace(workspacePath: string, mounts: readonly WorkspaceGitMount[]): void;
+type ProjectedMountGitlinks = {
+    mount: WorkspaceGitMount;
+    gitlinks: WorkingTreeGitlink[];
+};
+/**
+ * Mirror each mount's visible tree into the outer worktree. A submodule
+ * arrives as an empty directory plus a gitlink the caller must stage with
+ * `stageWorkspaceGitlinks` before `git add -A`, which can never create one.
+ */
+declare function mirrorMountsToWorkspace(workspacePath: string, mounts: readonly WorkspaceGitMount[]): ProjectedMountGitlinks[];
 export declare function hydrateWorkspaceGitMounts(workspacePath: string, mounts: readonly WorkspaceGitMount[], options?: {
     ignoreBusy?: boolean;
     hydrationHooks?: WorkspaceHydrationTransactionHooks;
@@ -188,8 +212,14 @@ export declare function resetWorkspaceGit(input: {
     activeMountIds: string[];
     skippedMountIds: string[];
 }>;
+/**
+ * Bytes of the raw `git diff --binary` between two revisions, capped at
+ * `limit + 1`. `pathspecs` narrows what is measured; callers pass
+ * `:(exclude,literal)<path>` for paths whose text is not publication content,
+ * such as a subtree a gitlink replaces (see `pathsReplacedByGitlinks`).
+ */
 declare function diffSizeBytes(workspacePath: string, baseRevision: string | null, headRevision: string, limit: number, pathspecs?: readonly string[]): Promise<number>;
-export declare function synchronizeWorkspaceGit(input: {
+export type SynchronizeWorkspaceGitInput = {
     attemptId?: string;
     workerLabel: string;
     workspacePath: string;
@@ -209,6 +239,12 @@ export declare function synchronizeWorkspaceGit(input: {
     skipMountMirror?: boolean;
     /** Positive ancestry proof required before a remediation may integrate, publish, or hydrate. */
     requiredAncestorHeads?: readonly string[];
+    /**
+     * Head of the workspace remote as the server last read it from disk. Equal
+     * to the local remote-tracking ref, it lets the cycle skip its workspace
+     * head fetches; see resolveWorkspaceRemoteHead. Omit to always fetch.
+     */
+    advertisedRemoteHead?: string | null;
     /** Revalidate the worker/config/incident generation after every async boundary. */
     assertStillAdmitted?: () => void;
     /** Test seam for exercising an incident transition during asynchronous diff measurement. */
@@ -219,7 +255,8 @@ export declare function synchronizeWorkspaceGit(input: {
     }) => void | Promise<void>;
     /** Announces each synchronous hydration transaction of this cycle; see WorkspaceHydrationTransactionHooks. */
     hydrationHooks?: WorkspaceHydrationTransactionHooks;
-}): Promise<WorkspaceGitSyncResult>;
+};
+export declare function synchronizeWorkspaceGit(input: SynchronizeWorkspaceGitInput): Promise<WorkspaceGitSyncResult>;
 export declare const workspaceGitSyncTestHarness: {
     commandArgs: typeof gitCommandArgs;
     workspaceCloneCommandArgs: typeof workspaceCloneCommandArgs;

package/dist/types/workspace-mutation-gate.d.ts

@@ -3,9 +3,20 @@ export type WorkspaceMutationLease = () => void;
  * Coordinates project worktrees with the outer workspace Git clone.
  *
  * Ordinary worktree activity may overlap other ordinary activity, but a sync
- * gets exclusive access. Once a sync is queued, later mutations wait behind it
- * so a queued sync cannot be starved by later short mutations. Long-running
- * long-running project commands do not enter this gate; outer-workspace
+ * gets exclusive access. Once a sync is queued, later ordinary mutations wait
+ * behind it so a queued sync cannot be starved by later short mutations.
+ *
+ * Branch creation and deletion use their own lane: a branch mutation never
+ * waits behind a queued sync, only behind a sync that is already running.
+ * Every sync still gets exclusive access, so hydration cannot overlap a
+ * worktree being created or removed; the lane only decides ordering between
+ * cycles. Branch operations are short and rare, so the queued sync they
+ * step in front of waits at most their own duration. Without the lane a
+ * branch operation queued behind a backlog of syncs waited for every one of
+ * them, outlived the server's operation timeout, and then ran anyway against
+ * a request the server had already rolled back.
+ *
+ * Long-running project commands do not enter this gate; outer-workspace
  * remediation commands do because they operate on the sync clone itself.
  */
 export declare class WorkspaceMutationGate {
@@ -15,6 +26,16 @@ export declare class WorkspaceMutationGate {
     acquireMutation(): Promise<WorkspaceMutationLease>;
     runMutation<T>(operation: () => Promise<T> | T): Promise<T>;
     runSync<T>(operation: () => Promise<T> | T): Promise<T>;
+    /** A worktree create/delete lease; see the branch lane in the class comment. */
+    acquireBranchMutation(): Promise<WorkspaceMutationLease>;
+    runBranchMutation<T>(operation: () => Promise<T> | T): Promise<T>;
+    /**
+     * Operations a branch mutation requested now would wait for: the running
+     * sync, if any, plus branch mutations queued behind it. Zero means it runs
+     * at once. Ordinary waiters are not counted because the branch lane admits
+     * ahead of them.
+     */
+    branchMutationQueuePosition(): number;
     private drain;
     private releaseMutation;
     private releaseSync;