@skaile/workspaces 5.1.3 → 5.3.0

package/dist/factory-assets/connectors/git/driver.d.ts

@@ -1,193 +1,44 @@
 /**
- * GitConnector — git repository filesystem-face connector.
+ * GitConnector - git repository filesystem-face connector.
  * Mounts a git repo by cloning/pulling to a local directory.
  * Session-aware: auto-branching, lifecycle hooks (hibernate/close), periodic fetch/rebase.
  *
- * Everything in this file that touches `mountPath` is asynchronous and
- * deadline-bounded. Inside the agent container that path is the rclone FUSE
- * mount, and a synchronous `execSync` / `fs` call there parks the entire
- * single-threaded event loop in an uninterruptible kernel wait — a hang, not an
- * error, so `try/catch` never fires and the whole session dies (issue #454).
+ * The connector itself is an adapter: it wires one mount's three collaborators
+ * to the connector contract and holds no git logic of its own.
+ *
+ *   - `credentials.ts` - token acquisition, refresh, the agent-facing gitconfig;
+ *   - `repo.ts`        - every operation on the checkout (clone, commit, merge, push, pull);
+ *   - `lifecycle.ts`   - when those run (timers, hibernate, session close, read-only refresh).
  */
 import type { ConnectContext, ConnectorChangeEvent, ConnectorDeclaration, ConnectorHandle, ConnectorHookReport, FilesystemFace, ToolFace, WatchHandle, WatchOptions } from "@skaile/workspaces/connectors";
 import { AbstractConnector } from "@skaile/workspaces/connectors";
-interface GitSessionConfig {
-    enabled: boolean;
-    slug?: string;
-    isMain: boolean;
-    branchPrefix: string;
-    /**
-     * Starting point for a freshly-created session branch. When set and the
-     * session branch does not already exist on origin, the driver fetches this
-     * ref and branches from it instead of from the base branch tip. Used by
-     * the platform's fork flow so a forked session branches off the source
-     * session's tip rather than off `main`. May be a branch name (e.g.
-     * `skaile/session-source-slug`) or a commit SHA. Ignored when the session
-     * branch already exists on origin (existing branch wins). No-op when
-     * `enabled = false` or `isMain = true` (only branch sessions cut new
-     * branches). The value is validated against `isValidGitRefOrSha` before
-     * use; refs with shell metacharacters are rejected and the driver falls
-     * back to branching off base.
-     */
-    fromRef?: string;
-}
-interface GitSyncConfig {
-    fetchIntervalSec: number;
-    autoRebase: boolean;
-    autoPull: boolean;
-}
-interface GitLifecycleConfig {
-    commitOnHibernate: boolean;
-    pushOnHibernate: boolean;
-    mergeOnClose: boolean;
-    pushOnClose: boolean;
-    /** Auto-commit after N ms of no file changes. 0 = disabled. Default: 30000 (30s). */
-    autoCommitIdleMs: number;
-    /** Push to remote after each auto-commit. */
-    pushAfterCommit: boolean;
-    /** Push freshly-created session branch to origin on connect. Best-effort — push
-     *  failures are swallowed; lifecycle push hooks remain the backstop. */
-    publishOnCreate: boolean;
-}
-/**
- * Resolve the session/sync/lifecycle config blocks for a git connector. `mode`
- * seeds per-block defaults (`agent` / `sync`); explicit `options.{session,sync,
- * lifecycle}` keys still override those defaults. Absent `mode` reproduces the
- * legacy literals exactly, so behavior is unchanged for declarations that set none.
- */
-declare function resolveGitConfig(args: {
-    mode?: "agent" | "sync";
-    options?: Record<string, unknown>;
-}): {
-    session: GitSessionConfig;
-    sync: GitSyncConfig;
-    lifecycle: GitLifecycleConfig;
-};
-/** How long before the minted token's expiry the proactive refresh fires. */
-export declare const REFRESH_LEAD_MS: number;
-/**
- * Shortest refresh re-arm. A mediator that keeps minting tokens already inside
- * {@link REFRESH_LEAD_MS} would otherwise be asked for a new one every second.
- * A token living under this floor lapses until the next tick: Tier-2 recovers
- * sooner through the reactive retry-401 path, Tier-1 (no helper) waits for the
- * tick to put a fresh token in state.
- */
-export declare const MIN_REFRESH_DELAY_MS = 30000;
-/**
- * Longest delay ever handed to `setTimeout`, a margin below its 2^31-1 ms
- * ceiling (above which the delay silently collapses to 1 ms). Same cap the
- * runner's AI-credential scheduler uses.
- */
-export declare const MAX_REARM_MS: number;
-/**
- * The remote a network git command authenticates against. `GitState` satisfies
- * it, and is passed as-is so a rotated token is read at spawn time.
- */
-interface GitRemoteAuth {
-    url: string;
-    token?: string;
-    /**
-     * Scope the header to this repository's URL instead of its host. For the
-     * agent's ops: a same-host `pushurl` / `insteadOf` the agent sets after the
-     * origin check then gets no header. Off for the driver's own commands, whose
-     * relative submodules on the same host need it.
-     */
-    repoScoped?: boolean;
-}
-/**
- * `auth.url` without userinfo when a token will authenticate it — the URL that
- * goes into `origin`. Without a token the declared URL is used unchanged.
- */
-declare function plainRemoteUrl(auth: GitRemoteAuth): string;
-/**
- * Child environment for a network git command: the token as an
- * `http.<origin>.extraHeader` through `GIT_CONFIG_COUNT`, so it reaches git
- * without touching `.git/config`, a credentials file, or the argv (which
- * `/proc/<pid>/cmdline` and git's own error messages expose).
- *
- * Scoped to scheme, host and port, not the repository path: a relative
- * submodule on the same host needs it too, and git does not send it to a host
- * that `origin` or an `insteadOf` rule was re-pointed at.
- */
-declare function networkGitEnv(auth: GitRemoteAuth | undefined, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
-/**
- * Run a git command that talks to a remote, authenticated for this one
- * command only. Every clone, fetch, pull, push, ls-remote and submodule update
- * of this driver goes through here.
- */
-declare function runRemoteGit(args: string[], auth: GitRemoteAuth | undefined, options: {
-    cwd?: string;
-    /**
-     * Child working directory for a command that names its remote by URL and
-     * must not run inside a repository. Unlike `cwd`, the TLS-trust scan does
-     * not treat it as a checkout.
-     */
-    neutralCwd?: string;
-    safeDir: string;
-    timeout: number;
-    env?: NodeJS.ProcessEnv;
-}): Promise<string>;
-/**
- * An https remote without userinfo, query or fragment (as `origin` is written
- * on either tier); any other URL unchanged. Used to compare remotes and as the
- * repository scope of a header.
- */
-declare function comparableRemoteUrl(url: string): string;
-/**
- * Snapshot returned by the `sync_status` tool op. JSON-serialised over the
- * transport; the platform overlays `available`/`containerAwake`/`reason`
- * before handing it to the UI badge.
- */
-export interface GitSyncStatusResult {
-    /** Current branch name, or `null` (detached HEAD / unavailable). */
-    branch: string | null;
-    /** Working tree has uncommitted changes (`git status --porcelain` non-empty). */
-    dirty: boolean;
-    /** Commits on HEAD not on its upstream — i.e. unpushed. */
-    ahead: number;
-    /** Commits on the upstream not on HEAD — i.e. unpulled (since last fetch). */
-    behind: number;
-    /**
-     * Whether the current branch has a configured upstream. `false` ⇒ the branch
-     * has never been pushed; `ahead`/`behind` read as 0 (no remote-tracking ref
-     * to diff against), so this distinguishes "never pushed" from "synced".
-     */
-    hasUpstream: boolean;
-    /** Commits on HEAD not on `origin/<baseBranch>` — diverged ahead of base. */
-    mainAhead: number;
-    /** Commits on `origin/<baseBranch>` not on HEAD — diverged behind base. */
-    mainBehind: number;
-    /** Current HEAD commit SHA, or `null` when unavailable. */
-    commitSha: string | null;
+import { type GitCredentials } from "./credentials.js";
+import { GitLifecycle } from "./lifecycle.js";
+import { GitRepo } from "./repo.js";
+export { readGitSyncStatus } from "./inspect.js";
+export type { GitSyncStatusResult } from "./inspect.js";
+export type { GitRemoteOpResult } from "./repo.js";
+/** A mount this connector runs git for: its three collaborators, plus the change sink `watch` installs. */
+export interface GitOwnedMount {
+    fleetManaged?: undefined;
+    credentials: GitCredentials;
+    repo: GitRepo;
+    lifecycle: GitLifecycle;
+    /** Callback for emitting change events (set by `watch()`). */
+    emitChange?: (event: ConnectorChangeEvent) => void;
 }
-/**
- * Result of the agent-facing `push`, `pull` and `fetch` tool ops, JSON-serialised.
- * An expected outcome the agent must act on (a rejected push, a conflicting
- * pull) is a `status`, not a thrown error; auth or network failures throw.
- */
-export interface GitRemoteOpResult {
-    op: "push" | "pull" | "fetch";
-    /** The mount's branch the op acted on (the session branch on a branching mount). */
+/** A mount whose clone, pull, commit and push the host's GitFleetService owns. */
+export interface GitFleetMount {
+    fleetManaged: true;
+    /** The branch the host's worktree is on (`unknown` when it could not be read). */
     branch: string;
-    status: "pushed" | "rejected" | "fetched" | "merged" | "up-to-date" | "no-upstream" | "conflict" | "blocked";
-    /** What happened and what to do next, in words the agent can act on. */
-    message?: string;
-    /** Files that conflicted, for `status: "conflict"` (the merge itself was aborted). */
-    conflicts?: string[];
-    /** Sync status after the op. */
-    sync: GitSyncStatusResult;
+    /** Callback for emitting change events (set by `watch()`). */
+    emitChange?: (event: ConnectorChangeEvent) => void;
+    /** Auto-started watcher (no auto-commit timer); disposed in `disconnect`. */
+    fleetWatcher?: WatchHandle;
 }
-/**
- * Read git sync status for an in-container checkout. Pure and never throws —
- * every git call degrades to a safe default. No network fetch:
- * ahead/behind reflect locally-known remote-tracking refs ("since last sync").
- * `baseBranch` is the mount's tracked base (e.g. "main"); base divergence is
- * measured against `origin/<baseBranch>`.
- *
- * Asynchronous since v3: every `git` call it makes runs against a path that may
- * be a network mount, and the synchronous version blocked the event loop there.
- */
-export declare function readGitSyncStatus(cwd: string, baseBranch: string): Promise<GitSyncStatusResult>;
+/** What `ConnectorHandle.state` holds for a git mount. */
+export type GitMountState = GitOwnedMount | GitFleetMount;
 /**
  * Filesystem-face connector for git repositories — clones or pulls on connect, supports
  * session branching, periodic fetch/rebase, and lifecycle hooks (hibernate commit/push,
@@ -211,118 +62,12 @@ export declare class GitConnector extends AbstractConnector {
     private _describeOperations;
     private _executeOp;
     /**
-     * Run `fn` after every earlier job on this mount has settled. Network git and
-     * index-writing git on one checkout must not overlap: two of them contend for
-     * `.git/index.lock`, and a push racing a pull can push a half-merged branch.
-     * Not re-entrant — a job must never wait on the lock it runs under.
-     */
-    private withMountLock;
-    /**
-     * The agent's network git: the driver runs it with the mount's credential, so
-     * an agent on a mount without `exposeAccessToken` can push and pull without
-     * ever holding the token. Acts only on the mount's own branch, never forces.
+     * The agent's network git. Refuses unless the mount is connected, owned by
+     * this driver, and (for `push`) not declared read-only; the repo then runs the
+     * op under the mount lock with the mount's credential.
      */
     private agentRemoteOp;
-    /** Fetch origin's base branch and, on a branching mount, the session branch. */
-    private fetchActiveBranch;
-    private agentFetch;
-    private agentPush;
-    private agentPull;
     connect(declaration: ConnectorDeclaration, ctx: ConnectContext): Promise<ConnectorHandle>;
-    /**
-     * Bring `targetDir` into a usable checkout state for `connect()`.
-     *
-     * Minimal-connect policy: `connect()` never auto-syncs with the remote.
-     * The lifecycle hooks (`pushOnHibernate`, `pushAfterCommit`,
-     * `sync.autoPull`) and the explicit `filesystem.sync()` method are the
-     * only paths that touch the network with the existing checkout. Recreating
-     * a container is therefore idempotent — the on-disk dir is preserved.
-     *
-     * Three cases:
-     *   - `.git` exists       → use as-is. No pull, no reset.
-     *   - dir empty           → fresh clone (only network fetch on connect), or
-     *     `bootstrapEmptyRemote` when the remote has no refs at all.
-     *   - dir populated, no `.git` → `git init` + `remote add origin` so
-     *     lifecycle hooks (commit/push) can do their job. No fetch, no
-     *     reset, no clean. Existing files become uncommitted-on-init; the
-     *     agent or `pushAfterCommit` reconciles with remote later.
-     */
-    private prepareCheckout;
-    /**
-     * Create and check out the session branch for a non-main session, updating
-     * `state.activeBranch`. Reuses an existing local branch (unpushed work);
-     * else prefers `origin/<branch>`; otherwise branches off `fromRef` (platform
-     * fork flow) when supplied and valid, else off the currently-checked-out
-     * HEAD (== base branch).
-     */
-    private checkoutSessionBranch;
-    /**
-     * Fetch the session branch into `refs/remotes/origin/<sessionBranch>` and,
-     * when origin has it, map it with a fetch refspec. Never throws: a missing
-     * remote branch is the normal case for a new session, and any other failure
-     * leaves the checkout as it was (the caller creates the branch from the base).
-     *
-     * The refspec is added only once origin has the branch, and removed when
-     * origin does not have it: a configured refspec for a missing branch makes
-     * every plain `git fetch origin` fail. Runs on every connect, so it also
-     * repairs a checkout cloned before the refspec existed.
-     */
-    private trackSessionBranch;
-    /**
-     * Re-point a session branch that this connect cut from the base at
-     * `origin/<sessionBranch>`, once the retried fetch shows origin has it.
-     * Safe because the freshly-cut branch holds no work. Never throws: when the
-     * checkout is refused (for example local changes in the way), the branch
-     * stays as it is and the push later fails as non-fast-forward.
-     */
-    private adoptOriginSessionBranch;
-    /**
-     * Line up a reused local session branch (checked out) with
-     * `origin/<sessionBranch>` after a successful fetch. Never rewrites local
-     * history and never throws:
-     *   - local is an ancestor of origin → fast-forward (another node pushed
-     *     newer work);
-     *   - local has commits that origin does not have → keep them and log a
-     *     warning; when origin also has commits that local lacks (diverged),
-     *     merge origin in with {@link integrateOriginSessionBranch};
-     *   - origin has no such branch → nothing to do.
-     * In the first two cases the upstream is set to `origin/<sessionBranch>`.
-     */
-    private reconcileLocalSessionBranch;
-    /**
-     * Merge `origin/<branch>` into the checked-out session branch when origin
-     * holds commits that the local branch lacks (another node or the agent
-     * pushed, or an older driver rewrote the local branch). A merge, never a
-     * rebase: the commits on origin are published. After this, a push of the
-     * branch is a fast-forward and needs no force. Never throws; a merge that
-     * cannot complete is aborted, and the push that follows fails as before.
-     */
-    private integrateOriginSessionBranch;
-    /**
-     * After a successful push of a session branch: map it with a fetch refspec
-     * and point `refs/remotes/origin/<branch>` at the pushed tip. The push ran
-     * before the refspec existed (a refspec for a branch that origin does not
-     * have yet would break `git fetch origin`), so git did not update the
-     * tracking ref itself. With both, `@{upstream}` resolves and the platform's
-     * hibernate save gate sees `ahead` 0. Never throws.
-     */
-    private recordPushedSessionBranch;
-    /**
-     * Push the active branch. A session branch first gets any commits that are
-     * only on `origin/<branch>` merged in, so the push is a fast-forward and
-     * never needs a force. It is pushed with `-u` and then recorded (see
-     * {@link recordPushedSessionBranch}), so `@{upstream}` resolves — the
-     * platform's hibernate save gate reads exactly that. The base branch is
-     * first brought up to date with origin ({@link integrateOriginBaseBranch}),
-     * so a base branch that origin moved past is pushed rather than rejected.
-     */
-    private pushActiveBranch;
-    /**
-     * Attempt to create `sessionBranch` anchored on `session.fromRef`. Returns
-     * true when the branch was created from the anchor; false when no valid
-     * `fromRef` was supplied or the fetch failed (caller falls back to base).
-     */
-    private branchFromRef;
     /**
      * Fleet-managed connect: verify the host bind, register an explorer watcher,
      * no-op every git lifecycle hook. Spec: `_devlog/specs/2026-05-28-git-fleet-mode-design.md`.
@@ -335,314 +80,19 @@ export declare class GitConnector extends AbstractConnector {
      * `reason: 'retry-401'` so the platform can distinguish proactive refreshes
      * from emergency ones in audit logs.
      *
-     * No-op when:
-     *  - the handle was not minted with `exposeAccessToken: true`
-     *    (no `managedGitconfig` on state), or
-     *  - the connector was not provisioned with a `tokenMediator` (PAT path —
-     *    the script will keep serving the static token and the user must
-     *    rotate the PAT manually).
+     * No-op when the mount's credential is not exposed to the agent
+     * (`exposeAccessToken` off) or was not minted by the mediator (PAT path —
+     * the script keeps serving the static token and the user must rotate the
+     * PAT manually).
      *
      * Spec: `_devlog/specs/2026-05-07-unified-credential-mediation.md` Step 9a.
      */
-    refreshExposedCredential(connectorId: string, handle: ConnectorHandle): Promise<void>;
+    refreshExposedCredential(_connectorId: string, handle: ConnectorHandle): Promise<void>;
     disconnect(handle: ConnectorHandle): Promise<void>;
     private _sync;
     watch(handle: ConnectorHandle, callback: (event: ConnectorChangeEvent) => void, options?: WatchOptions): WatchHandle;
-    /**
-     * Commit and push per the lifecycle config, then report what the checkout
-     * can prove afterwards (`pushState`) so the host can tell whether anything
-     * exists only on local disk. A push that throws still throws (no report).
-     */
     onHibernate(handle: ConnectorHandle): Promise<string | ConnectorHookReport>;
-    /** The commit/push half of {@link onHibernate}; returns its detail line. Runs under the mount lock. */
-    private hibernateSave;
-    /**
-     * What this checkout can prove after a hibernate save, for a host deciding
-     * whether deleting the workspace loses anything. Read-only: never fetches,
-     * pushes, or writes the repo. Every doubt answers in the "keep it" direction.
-     */
-    private readPushState;
-    /**
-     * Whether every commit reachable from a local ref (`refs/heads/*`, `HEAD`
-     * even when detached, `refs/stash`) is reachable from some remote branch
-     * head. The remote heads come from `ls-remote`, because local `origin/*`
-     * refs go stale (a push by URL does not move them); only the ones whose
-     * commit this checkout already holds can be walked, so a head we lack
-     * proves nothing and the answer leans to `false`.
-     *
-     * `false` for any initialised submodule, checked first: a commit pinned only
-     * in its local clone is out of this walk's reach. `null` when the remote
-     * cannot be asked within {@link PUSH_STATE_REMOTE_TIMEOUT_MS}, which includes
-     * a remote the mount reaches only through ambient config (a credential helper,
-     * ssh or CA settings in global/system gitconfig): that config is switched off
-     * here, so such a workspace always reads "cannot tell" and is kept.
-     */
-    private isWorkspaceOnRemote;
-    /**
-     * Hibernate with nothing new to commit: push commits that are still only
-     * local (the agent committed its own work, or an earlier push failed).
-     * "Unpushed" is measured exactly as the platform's hibernate save gate reads
-     * `sync_status`: ahead of the upstream, or, with no upstream, ahead of
-     * `origin/<base>`. Skipping it left the gate refusing to hibernate forever.
-     */
-    private pushUnpushedOnHibernate;
     onSessionClose(handle: ConnectorHandle): Promise<string | undefined>;
-    /**
-     * Scope the credential helper to the sanitized full repository URL.
-     * Userinfo, query, and fragment data must never enter managed gitconfig.
-     */
-    private deriveCredentialScope;
-    /**
-     * Acquire the initial credential for a connector.
-     *
-     * `auth:` accepts the post-2026-05-06 grammar:
-     *   - `backend`         → request a token from the platform mediator
-     *                         (preferred for any platform-backed session).
-     *   - `pat:env:NAME`    → static token from the secrets chain
-     *                         (standalone CLI / non-platform contexts).
-     *
-     * Anonymous connectors (`auth` unset) succeed without a token — the
-     * `git clone`/`git pull` calls still work for public repos.
-     *
-     * @returns The parsed auth ref, the resolved token (when any), and the
-     *   `expiresAt` timestamp surfaced by the mediator (used to schedule a
-     *   refresh tick when the credential is exposed to the agent CLI).
-     */
-    private acquireInitialToken;
-    /**
-     * Register a credential helper that *reports* why there is no credential,
-     * after this connector failed to connect.
-     *
-     * Without it git finds no helper for the host and asks the terminal for a
-     * username, so the agent sees `fatal: could not read Username for
-     * 'https://github.com'` — which names neither the mount nor the cause, and
-     * which only ever appears on a write, since reads against a public remote
-     * keep succeeding. The helper written here makes git stop with the mediator's
-     * actual refusal text instead.
-     *
-     * Entirely best-effort: it runs on the failure path and must never mask the
-     * connect error that is already on its way up.
-     */
-    private registerUnavailableCredentialHelper;
-    /**
-     * Best-effort pre-creation of the helper's refresh-attempt stamp. A missing
-     * stamp only costs the cooldown (the helper dances on every git op instead of
-     * once per window), so a failure here is never worth surfacing.
-     */
-    private ensureAttemptStamp;
-    /**
-     * Best-effort removal of the unavailable-mount blocks that would answer this
-     * connector's git operations: its own from a previous failed session, and any
-     * left under the same repository scope by a sibling mount that failed earlier
-     * in this `connectAll` (git matches helpers by URL, not by mount id).
-     */
-    private clearUnavailableCredentialHelper;
-    private exposeManagedCredential;
-    /**
-     * Schedule the next refresh of the credential file, {@link REFRESH_LEAD_MS}
-     * before `expiresAt`.
-     *
-     * Cancels any existing timer first so re-connects (and the test harness)
-     * do not double-fire. The delay is clamped into
-     * [{@link MIN_REFRESH_DELAY_MS}, {@link MAX_REARM_MS}]: the floor stops a
-     * mediator that keeps minting tokens inside the lead from re-minting every
-     * second, and a delay above the cap is served as re-arms that mint nothing
-     * until the real refresh point — `setTimeout` silently collapses anything
-     * over 2^31-1 ms (~24.8d) to 1 ms, which would mint in a loop.
-     */
-    private scheduleRefresh;
-    private refreshManagedCredential;
-    private teardownManagedCredential;
-    /**
-     * Bring a populated, non-git directory under git tracking without
-     * touching the working tree. Runs only on the "dir populated, no `.git`"
-     * branch of `connect()` — exactly when a previous connect aborted before
-     * `.git` was written, or when the bind-mounted host dir's `.git` FILE
-     * pointed outside the container.
-     *
-     * The intent is to preserve whatever the agent last had on disk. We
-     * therefore:
-     *   - `git init` — creates `.git/`; does not modify any existing file.
-     *   - `git remote add origin <remoteUrl>` — wires up the remote so the
-     *     normal lifecycle hooks (`pushOnHibernate`, `pushAfterCommit`)
-     *     have a target.
-     *
-     * Deliberately omitted:
-     *   - `fetch` — would touch the network on every recreate. The lifecycle
-     *     handles sync explicitly (periodic `fetch`/`pull` via
-     *     `sync.autoPull`, push on hibernate, etc.).
-     *   - `checkout -f` / `reset --hard` / `clean -fd` — would discard the
-     *     user's last on-disk state. The agent or autocommit reconciles
-     *     with the remote later.
-     *
-     * `remoteUrl` carries no credential; network commands authenticate per
-     * command (see `runRemoteGit`).
-     */
-    private initInPlace;
-    /**
-     * Count `refs/heads/*` on the remote, optionally narrowed to one `branch`.
-     *
-     * Returns `null` when the probe itself fails (network, auth, bad URL).
-     * "Cannot tell" must never collapse into "no refs": the empty-remote
-     * fallback WRITES to origin, and every caller therefore treats `null` as
-     * "assume populated" and falls through to the path that fails loudly.
-     */
-    private countRemoteHeads;
-    /**
-     * Bootstrap a checkout against a remote that has no refs at all — the state
-     * of a GitHub repo created without "Add a README".
-     *
-     * A plain `git clone` is NOT a substitute: cloning a ref-less remote leaves
-     * local HEAD on git's `init.defaultBranch` (`master`), not the declared
-     * branch, so the branch is created explicitly here.
-     *
-     * The root commit is created REGARDLESS of `access` and `publish`; only the
-     * push to origin is gated on them (`publish` is false when every lifecycle
-     * push flag is off). An unborn HEAD is not a stable resting state: the
-     * next connect sees `.git` with no resolvable HEAD, routes to
-     * `bootstrapFromOrigin`, and its `fetch origin <branch>` dies on the still
-     * ref-less remote — turning a fixed first connect into a broken second one.
-     * A local commit costs a read-only connector nothing (it is never pushed)
-     * and makes reconnect take the cheap "use as-is" path.
-     *
-     * With the push done, `origin/<branch>` exists for everything downstream —
-     * notably `checkoutSessionBranch`, whose publish-on-create push needs a
-     * commit to point at.
-     *
-     * Invariant: this method never throws on a failed push. The session must
-     * come up with a usable checkout even when origin is unreachable — the
-     * lifecycle hooks (`pushAfterCommit`, hibernate/close push) publish later.
-     */
-    private bootstrapEmptyRemote;
-    /**
-     * True when `<targetDir>/.git` contains at least one resolvable commit
-     * (i.e. `HEAD` points at a real object). False when `.git` is an empty
-     * shell — e.g. just-initialised but never fetched, or all refs deleted.
-     *
-     * Used by `connect()` to tell the difference between a working agent
-     * checkout (preserve, don't touch) and a half-initialised one
-     * (bootstrap by fetching from origin).
-     */
-    private isInitialisedCheckout;
-    /**
-     * One-shot bootstrap path for the "`.git` exists but is empty" state.
-     *
-     * Runs `fetch --depth=1 origin <branch>` followed by `checkout -B
-     * <branch> origin/<branch>` so the working tree gets the remote
-     * content. Before the checkout, any untracked file whose path also
-     * exists in the remote tree is renamed to `<path>.local` so the user
-     * (or previous agent run) does not lose data. Other untracked files
-     * are left in place.
-     *
-     * Deliberately not destructive: we never `clean -fd` and never
-     * `reset --hard`. Files that do not conflict with the remote stay
-     * exactly where they are.
-     *
-     * A pre-existing `origin` is replaced with the declared URL, which also
-     * drops a token an older driver wrote into it.
-     */
-    private bootstrapFromOrigin;
-    /**
-     * Walk the remote tree at `origin/<branch>` and rename any untracked
-     * working-tree file whose path also exists there. Renames go to
-     * `<path>.local`; on `.local` collision a millisecond suffix is
-     * appended so nothing is overwritten.
-     *
-     * This makes the subsequent `git checkout -B <branch> origin/<branch>`
-     * safe: without it, `checkout` aborts with "untracked working tree
-     * files would be overwritten" the moment any local file collides with
-     * a tracked path on the remote.
-     *
-     * Files in the local tree whose paths are NOT in the remote tree are
-     * left untouched — they are pure local additions and survive the
-     * bootstrap.
-     */
-    private preserveConflictingUntracked;
-    /**
-     * Align `origin` with the exact sanitized URL used by the Tier-2 helper.
-     * Git does not normalize query/fragment data, path case, or `.git` aliases
-     * when matching `credential.<url>` sections, so the two strings must agree.
-     * The declared mount source remains authoritative over an existing remote.
-     */
-    private alignRemoteWithCredentialScope;
-    /**
-     * Point `origin` at the declared URL, without a credential in it.
-     *
-     * Clones made before the driver authenticated per command hold
-     * `https://x-access-token:<token>@…` in `.git/config`, where the agent can
-     * read it; this is what removes it, on the first connect after an upgrade.
-     * With a token in hand `origin` is set to the declared URL, as the old
-     * re-bake did. Without one only a token-bearing origin is rewritten: a URL
-     * the user declared with their own userinfo is theirs to keep.
-     */
-    private reconcileRemoteUrl;
-    /**
-     * Set `remote.origin.pushurl` to {@link READ_ONLY_PUSH_URL} on a read-only
-     * mount, and remove it again (only that value) once the mount is read-write,
-     * because the driver's own pushes go through `origin` and would hit it too.
-     */
-    private applyPushGuard;
-    /**
-     * Bring a read-only mount to origin's base branch tip and drop every local
-     * change: edits, untracked files (ignored ones stay, so `.skaile/` and build
-     * output survive), local commits, an unfinished merge or rebase, and a branch
-     * switch. Replaces the pull, so the rebase and merge-conflict paths never run.
-     *
-     * With `tolerateFetchFailure` (connect), an unreachable origin is logged and
-     * the checkout is reset to the last fetched `origin/<base>` instead, so a
-     * mount that was usable stays usable. With `skipWhenAtTarget` (periodic tick)
-     * a checkout already on origin's tip is left as it is. While
-     * `readOnlySaveOwed` is set the work is saved first ({@link preserveLocalWork});
-     * when that fails nothing is discarded. The first reset after a save sets the
-     * push block. Runs under the mount lock. True when the checkout was reset.
-     */
-    private refreshReadOnly;
-    /**
-     * Save what the first read-only discard would destroy on a checkout that was
-     * used read-write: local commits on the base branch or a detached HEAD go to a
-     * `skaile/pre-read-only-<time>` branch, uncommitted edits and untracked files
-     * to a stash. Other local branches are left alone by the discard anyway.
-     * False (logged) when the stash fails, e.g. over unmerged paths.
-     */
-    private preserveLocalWork;
-    private startPeriodicFetch;
-    /** One periodic-fetch tick. Bails out at each resumption point once disconnected. */
-    private runPeriodicFetch;
-    /**
-     * `git fetch origin` for the periodic tick. When origin no longer has a
-     * branch that a session refspec names (for example a session branch deleted
-     * after a merge, or one from an earlier session on this checkout), that
-     * refspec fails the whole fetch. Drop it and fetch again. The base branch
-     * refspec is never dropped.
-     */
-    private fetchOrigin;
-    /**
-     * Merge `origin/<base>` into a published session branch (periodic tick with
-     * `autoRebase`). No-op when the base is already contained. Conflicts are
-     * handled like the merge on close: keep "ours" (the session branch) and
-     * save "theirs" as `.conflict` files.
-     */
-    private mergeBaseIntoSessionBranch;
-    /**
-     * True (and logged) when a merge or rebase is already open in the checkout,
-     * so a driver merge must not start: its failure path would abort or resolve
-     * the agent's own operation.
-     */
-    private skipOverUnfinishedOperation;
-    /**
-     * Attempt to resolve merge/rebase conflicts by keeping "ours" and copying
-     * "theirs" to a .conflict file. If resolution fails entirely, abort.
-     * Returns true if conflicts were resolved, false if aborted.
-     */
-    private resolveConflictsOrAbort;
-    /**
-     * For a single conflicted file: keep "ours", save "theirs" as .conflict file.
-     */
-    private resolveFileConflict;
-    private stripConflictKeepOurs;
-    private resetAutoCommitTimer;
-    private performAutoCommit;
-    private generateCommitMessage;
 }
 /**
  * Creates a new GitConnector instance.
@@ -650,13 +100,4 @@ export declare class GitConnector extends AbstractConnector {
  * @docLink packages/factory-assets/api-reference#git-connector-factory
  */
 export declare function createConnector(): GitConnector;
-/** Test-only surface for unit assertions. */
-export declare const __test: {
-    resolveGitConfig: typeof resolveGitConfig;
-    networkGitEnv: typeof networkGitEnv;
-    plainRemoteUrl: typeof plainRemoteUrl;
-    runRemoteGit: typeof runRemoteGit;
-    comparableRemoteUrl: typeof comparableRemoteUrl;
-};
-export {};
 //# sourceMappingURL=driver.d.ts.map