Method tryWarmWorktreeAdd

src/node/runtime/SSHRuntime.ts:2571–2753

* Result returned by `tryWarmWorktreeAdd()` on a warm-path hit. * `gitmodulesPresent` is reported by the fused SSH command so the caller * can skip the post-worktree submodule-sync probe (another SSH RT) when * the workspace has no `.gitmodules`.

(
    params: WorkspaceInitParams,
    nhp: string
  )

   * the workspace has no `.gitmodules`.
   */
  private async tryWarmWorktreeAdd(
    params: WorkspaceInitParams,
    nhp: string
  ): Promise<{ gitmodulesPresent: boolean } | null> {
    const { projectPath, branchName, trunkBranch, workspacePath, initLogger, abortSignal } = params;

    // Local prerequisites — all computed without any SSH calls.
    //
    // STARTUP-PERF: We deliberately use only the snapshot **digest** to gate
    // the warm path (no separate ref-manifest check). The digest is the
    // sha256 of `git show-ref --heads` output: if it matches the digest
    // persisted on the remote at sync time, the local heads MUST be the same
    // (modulo a sha256 collision). Skipping the manifest verification saves
    // both an SSH round-trip and a `git show-ref` parse pass — both are pure
    // overhead on the warm path because they always agree when the digests
    // match. If a digest mismatch happens, we fall through to the slow path,
    // which independently re-verifies via the full manifest before pushing.
    const layout = this.getProjectLayout(projectPath);
    // Try the fs-direct fast reader first; fall back to `git show-ref` only
    // when the cheap path can't handle the project layout. The fallback keeps
    // the warm path correct against worktree gitdir indirection, reftables,
    // and symref'd branch heads, which `fastReadGitHeadsRefs` deliberately
    // refuses to interpret.
    const headsOutput =
      (await fastReadGitHeadsRefs(projectPath)) ?? (await readGitHeadsRefs(projectPath));
    if (headsOutput == null || headsOutput.length === 0) {
      // No local refs means a freshly-init'd local repo (no commits) or a
      // non-git directory. Either way the slow path needs to run.
      return null;
    }
    const snapshotDigest = crypto.createHash("sha256").update(headsOutput).digest("hex");
    const baseRepoPathArg = expandTildeForSSH(layout.baseRepoPath);
    const baseRepoUnbornHeadArg = shescape.quote(BASE_REPO_UNBORN_HEAD_REF);
    const currentSnapshotPathArg = expandTildeForSSH(layout.currentSnapshotPath);
    const workspacePathArg = expandTildeForSSH(workspacePath);
    const workspaceParentArg = expandTildeForSSH(
      workspacePath.includes("/") ? workspacePath.substring(0, workspacePath.lastIndexOf("/")) : "~"
    );

    // CORRECTNESS (origin-freshness): When the local project has an `origin`
    // remote, the slow path always prefers `origin/<trunkBranch>` over the
    // bundle ref so new workspaces base on the freshest upstream tip — see
    // `resolveFreshWorkspaceSourceBase()`. The warm path must match this or
    // it would silently check out a stale local snapshot when upstream has
    // advanced. We fold the same `git fetch origin <trunk>` into the fused
    // SSH script (single round-trip on the wire; the network hop to the
    // upstream stays on the datacenter side, so adding it preserves the
    // single-SSH-RTT envelope on the *client* side).
    const { originUrl } = await this.getOriginUrlForSync(projectPath, initLogger);

    // The remote bundle ref to base the worktree on. Prefer an exact match for
    // the requested branch (most projects use `main` or the trunk branch name
    // as the bundle ref), and we can let the remote script pick the first
    // available bundle ref as a fallback.
    const bundleRefArg = shescape.quote(`${BUNDLE_REF_PREFIX}${trunkBranch}`);
    const bundleRefFallbackPrefix = shescape.quote(BUNDLE_REF_PREFIX);

    const branchArg = shescape.quote(branchName);