@skaile/workspaces 3.7.2 → 3.8.0

package/dist/{chunk-JTBF4OB2.js → chunk-6GDVGAIZ.js}

@@ -1,7 +1,7 @@
 import { resolveAuthRef } from './chunk-3UU3D2Q3.js';
-import { EventNormalizer } from './chunk-VXITGB7G.js';
+import { EventNormalizer } from './chunk-KNPBMR2P.js';
 import { resolveModelTier } from './chunk-V34ZEXSE.js';
-import { createDriver } from './chunk-32TJ55W5.js';
+import { createDriver } from './chunk-BGAAZMBK.js';
 import { pluginRegistry } from './chunk-6E6PKKAD.js';
 import { computeStimulus } from './chunk-IFGTRL2I.js';
 import { resolveNodeBindings, getConsumedOutputSchema, validateConsumedNodeOutput, appendAttempt, resolveTerminalFailureStatus, remainingActiveExecutionMs, interpolateNodeInstruction, deriveCheckEvidence, computeFlowStateFromSnapshots, availableRouterFrontier, evaluateRouterSelection, routerSelectionOutput, planRouterSkips, unsettledRouterBranchIds, countFailedAttempts, hasAutomaticRetryBudget, persistedRouterSelection } from './chunk-OYZIURPH.js';
@@ -17,7 +17,7 @@ import { mkdir, rename, writeFile, readFile, stat, cp, readdir, chmod, realpath
 import * as z4 from 'zod';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { createReadStream, readFileSync, existsSync, mkdirSync, openSync, writeSync, closeSync, chmodSync, renameSync } from 'fs';
+import { createReadStream, existsSync, mkdirSync, openSync, closeSync, chmodSync, utimesSync, readFileSync, writeSync, renameSync } from 'fs';
 import { createServer } from 'http';
 import mime from 'mime';
 import { createRequire } from 'module';
@@ -1323,6 +1323,18 @@ function resolveGitConfig(args) {
 }
 var modeLog = createLogger({ kind: "connector", subkind: "git" });
 var execFileAsync2 = promisify(execFile);
+function redactUrlAuth(text) {
+  return text.replace(/\/\/[^/@\s]*:[^/@\s]*@/g, "//***@");
+}
+function redactError(err) {
+  const original = err instanceof Error ? err : new Error(String(err));
+  const copy = new Error(redactUrlAuth(original.message));
+  copy.name = original.name;
+  copy.stack = original.stack === void 0 ? void 0 : redactUrlAuth(original.stack);
+  return copy;
+}
+var BOOTSTRAP_COMMIT_NAME = "Skaile";
+var BOOTSTRAP_COMMIT_EMAIL = "skaile@local";
 function gitPrefix(cwd) {
   return ["-c", `safe.directory=${cwd}`];
 }
@@ -1482,53 +1494,59 @@ var GitConnector = class extends AbstractConnector {
     if (!isValidGitRefOrSha(branch)) {
       throw new Error(`Git connector: invalid branch name "${branch}"`);
     }
-    this.log.info("mount start", { url, branch, targetDir });
-    const initial = await this.acquireInitialToken(declaration, secrets, tokenMediator);
-    const { session, sync, lifecycle } = resolveGitConfig({
-      mode: declaration.mode,
-      options: opts
-    });
-    const state = {
-      url,
-      branch,
-      activeBranch: branch,
-      token: initial.token,
-      session,
-      sync,
-      lifecycle,
-      targetDir,
-      tokenMediator: initial.authRef?.kind === "backend" ? tokenMediator : void 0
-    };
-    const authUrl = this.authUrl(state);
-    await this.prepareCheckout(targetDir, url, branch, authUrl, started);
-    if (session.enabled && !session.isMain && session.slug) {
-      await this.checkoutSessionBranch(state, session, targetDir);
-    }
-    if (sync.fetchIntervalSec > 0) {
-      this.startPeriodicFetch(state, targetDir);
-    }
-    if (declaration.mount?.exposeAccessToken === true) {
-      try {
-        this.exposeManagedCredential(declaration, state, url, initial);
-      } catch (err) {
-        this.log.error("managed-gitconfig write failed", err, { connectorId: declaration.id });
-        throw err;
+    try {
+      this.log.info("mount start", { url, branch, targetDir });
+      this.clearUnavailableCredentialHelper(declaration.id, url);
+      const initial = await this.acquireInitialToken(declaration, secrets, tokenMediator);
+      const { session, sync, lifecycle } = resolveGitConfig({
+        mode: declaration.mode,
+        options: opts
+      });
+      const state = {
+        url,
+        branch,
+        activeBranch: branch,
+        token: initial.token,
+        session,
+        sync,
+        lifecycle,
+        targetDir,
+        tokenMediator: initial.authRef?.kind === "backend" ? tokenMediator : void 0
+      };
+      const authUrl = this.authUrl(state);
+      await this.prepareCheckout(targetDir, url, branch, authUrl, declaration.access, started);
+      if (session.enabled && !session.isMain && session.slug) {
+        await this.checkoutSessionBranch(state, session, targetDir);
       }
-    }
-    if (state.managedGitconfig) {
-      await this.stripRemoteInlineToken(targetDir);
-    } else {
-      await this.rebakeRemoteAuth(targetDir, state);
-      if (initial.authRef?.kind === "backend" && initial.expiresAt && state.tokenMediator) {
-        this.scheduleRefresh(declaration.id, state, initial.expiresAt);
+      if (sync.fetchIntervalSec > 0) {
+        this.startPeriodicFetch(state, targetDir);
+      }
+      if (declaration.mount?.exposeAccessToken === true) {
+        try {
+          this.exposeManagedCredential(declaration, state, url, initial);
+        } catch (err) {
+          this.log.error("managed-gitconfig write failed", err, { connectorId: declaration.id });
+          throw err;
+        }
+      }
+      if (state.managedGitconfig) {
+        await this.stripRemoteInlineToken(targetDir);
+      } else {
+        await this.rebakeRemoteAuth(targetDir, state);
+        if (initial.authRef?.kind === "backend" && initial.expiresAt && state.tokenMediator) {
+          this.scheduleRefresh(declaration.id, state, initial.expiresAt);
+        }
       }
+      this.log.info("mount ok", {
+        targetDir,
+        activeBranch: state.activeBranch,
+        durationMs: Date.now() - started
+      });
+      return this.makeHandle(declaration, state, targetDir);
+    } catch (err) {
+      this.registerUnavailableCredentialHelper(declaration, url, err);
+      throw err;
     }
-    this.log.info("mount ok", {
-      targetDir,
-      activeBranch: state.activeBranch,
-      durationMs: Date.now() - started
-    });
-    return this.makeHandle(declaration, state, targetDir);
   }
   /**
    * Bring `targetDir` into a usable checkout state for `connect()`.
@@ -1541,40 +1559,58 @@ var GitConnector = class extends AbstractConnector {
    *
    * Three cases:
    *   - `.git` exists       → use as-is. No pull, no reset.
-   *   - dir empty           → fresh clone (only network fetch on connect).
+   *   - 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.
    */
-  async prepareCheckout(targetDir, url, branch, authUrl, started) {
+  async prepareCheckout(targetDir, url, branch, authUrl, access, started) {
     try {
       if (await pathExists(join(targetDir, ".git"))) {
         if (await this.isInitialisedCheckout(targetDir)) {
           this.log.info("found existing checkout \u2014 using as-is", { branch, targetDir });
         } else {
-          this.log.info("found empty .git \u2014 bootstrapping from origin", { branch });
-          await this.bootstrapFromOrigin(targetDir, branch, authUrl);
+          if (await this.countRemoteHeads(targetDir, authUrl) === 0) {
+            this.log.info("empty .git against a ref-less remote \u2014 bootstrapping branch", {
+              branch,
+              access
+            });
+            await this.bootstrapEmptyRemote(targetDir, branch, authUrl, access);
+          } else {
+            this.log.info("found empty .git \u2014 bootstrapping from origin", { branch });
+            await this.bootstrapFromOrigin(targetDir, branch, authUrl);
+          }
           this.log.info("bootstrap ok", { branch, durationMs: Date.now() - started });
         }
       } else {
         await withFsDeadline(`mkdir ${targetDir}`, () => mkdir(targetDir, { recursive: true }));
         if (await isDirEmpty(targetDir)) {
-          this.log.info("clone start", { url, branch });
-          await runGit(
-            [
-              ...gitPrefix(targetDir),
-              "clone",
-              "--branch",
+          if (await this.countRemoteHeads(targetDir, authUrl) === 0) {
+            this.log.info("remote has no refs \u2014 bootstrapping branch", { url, branch, access });
+            await this.bootstrapEmptyRemote(targetDir, branch, authUrl, access);
+            this.log.info("empty-remote bootstrap ok", {
               branch,
-              "--single-branch",
-              "--recurse-submodules",
-              authUrl,
-              targetDir
-            ],
-            { timeout: 12e4 }
-          );
-          this.log.info("clone ok", { branch, durationMs: Date.now() - started });
+              durationMs: Date.now() - started
+            });
+          } else {
+            this.log.info("clone start", { url, branch });
+            await runGit(
+              [
+                ...gitPrefix(targetDir),
+                "clone",
+                "--branch",
+                branch,
+                "--single-branch",
+                "--recurse-submodules",
+                authUrl,
+                targetDir
+              ],
+              { timeout: 12e4 }
+            );
+            this.log.info("clone ok", { branch, durationMs: Date.now() - started });
+          }
         } else {
           this.log.warn("target non-empty without .git \u2014 initialising in place", { targetDir });
           await this.initInPlace(targetDir, authUrl);
@@ -1582,7 +1618,7 @@ var GitConnector = class extends AbstractConnector {
         }
       }
     } catch (err) {
-      this.log.error("connect preparation failed", err, { url, branch });
+      this.log.error("connect preparation failed", redactError(err), { url, branch });
       throw err;
     }
   }
@@ -1964,6 +2000,104 @@ var GitConnector = class extends AbstractConnector {
     }
     return { authRef, token, expiresAt: null };
   }
+  /**
+   * 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.
+   */
+  registerUnavailableCredentialHelper(declaration, url, err) {
+    try {
+      if (!url.startsWith("https://") && !url.startsWith("http://")) return;
+      const gitconfigPath = process.env.GIT_CONFIG_GLOBAL;
+      if (!gitconfigPath) return;
+      const skaileDir = dirname(gitconfigPath);
+      const credentialsPath = join(skaileDir, "git-credentials");
+      const urlPrefix = this.deriveUrlPrefix(url);
+      const helperScriptPath = join(skaileDir, `credential-helper-${declaration.id}.sh`);
+      const refreshAttemptPath = join(skaileDir, `refresh-attempt-${declaration.id}`);
+      const reason = redactUrlAuth(err instanceof Error ? err.message : String(err));
+      this.ensureAttemptStamp(declaration.id, refreshAttemptPath);
+      writeHelperScript(
+        helperScriptPath,
+        renderCredentialHelperScript({
+          credentialsPath,
+          refreshFlagPath: join(skaileDir, "refresh-request"),
+          credentialTag: `# skaile-mount: ${declaration.id}`,
+          refreshAttemptPath,
+          unavailableReason: reason
+        })
+      );
+      writeUnavailableMountBlock({
+        mountId: declaration.id,
+        urlPrefix,
+        gitconfigPath,
+        credentialsPath,
+        helperScriptPath
+      });
+      this.log.warn("registered unavailable credential helper for failed mount", {
+        connectorId: declaration.id,
+        urlPrefix
+      });
+    } catch (writeErr) {
+      this.log.warn("failed to register unavailable credential helper", {
+        connectorId: declaration.id,
+        error: writeErr instanceof Error ? writeErr.message : String(writeErr)
+      });
+    }
+  }
+  /**
+   * 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.
+   */
+  ensureAttemptStamp(connectorId, stampPath) {
+    try {
+      ensureRefreshAttemptStamp(stampPath);
+    } catch (err) {
+      this.log.warn("managed-gitconfig: could not pre-create refresh-attempt stamp", {
+        connectorId,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  /**
+   * 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 URL prefix by a sibling mount that failed earlier in
+   * this `connectAll` (git matches helpers by URL, not by mount id).
+   */
+  clearUnavailableCredentialHelper(connectorId, url) {
+    const gitconfigPath = process.env.GIT_CONFIG_GLOBAL;
+    if (!gitconfigPath) return;
+    let urlPrefix;
+    if (url.startsWith("https://") || url.startsWith("http://")) {
+      try {
+        urlPrefix = this.deriveUrlPrefix(url);
+      } catch {
+      }
+    }
+    try {
+      removeUnavailableMountBlock({
+        mountId: connectorId,
+        gitconfigPath,
+        ...urlPrefix !== void 0 ? { urlPrefix } : {}
+      });
+    } catch (err) {
+      this.log.warn("failed to clear unavailable credential helper", {
+        connectorId,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
   exposeManagedCredential(declaration, state, url, initial) {
     const token = initial.token;
     if (!token) {
@@ -1991,15 +2125,22 @@ var GitConnector = class extends AbstractConnector {
     const urlPrefix = this.deriveUrlPrefix(url);
     const refreshFlagPath = join(skaileDir, "refresh-request");
     const helperScriptPath = join(skaileDir, `credential-helper-${declaration.id}.sh`);
+    const refreshAttemptPath = join(skaileDir, `refresh-attempt-${declaration.id}`);
     const credentialTag2 = `# skaile-mount: ${declaration.id}`;
     const scriptBody = renderCredentialHelperScript({
       credentialsPath,
       refreshFlagPath,
-      credentialTag: credentialTag2
+      credentialTag: credentialTag2,
+      // Passed explicitly on both call sites so the failure path and this one
+      // never disagree about which stamp file bounds this mount's dance.
+      refreshAttemptPath
     });
+    this.ensureAttemptStamp(declaration.id, refreshAttemptPath);
+    let helperWritten = true;
     try {
       writeHelperScript(helperScriptPath, scriptBody);
     } catch (err) {
+      helperWritten = false;
       this.log.warn(
         "managed-gitconfig: failed to write credential-helper script -- falling back to static helper",
         {
@@ -2014,7 +2155,12 @@ var GitConnector = class extends AbstractConnector {
       token,
       gitconfigPath,
       credentialsPath,
-      helperScriptPath
+      // Only point at the script when it was actually written. Pointing at an
+      // unwritten path is not a fallback: the file may still hold a previous
+      // session's *unavailable* body, which would refuse this live credential
+      // with a stale reason. Omitting it selects the static `store --file=`
+      // form, which reads the credential line this call is about to write.
+      ...helperWritten ? { helperScriptPath } : {}
     });
     state.managedGitconfig = { gitconfigPath, credentialsPath, urlPrefix };
     const providerKind = initial.authRef?.kind ?? "pat";
@@ -2163,6 +2309,97 @@ var GitConnector = class extends AbstractConnector {
     }
     await git(["remote", "add", "origin", authUrl], targetDir, 5e3);
   }
+  /**
+   * Count `refs/heads/*` on `authUrl`, 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.
+   */
+  async countRemoteHeads(targetDir, authUrl, branch) {
+    try {
+      const out = await runGit(
+        branch === void 0 ? [...gitPrefix(targetDir), "ls-remote", "--heads", authUrl] : [...gitPrefix(targetDir), "ls-remote", "--heads", authUrl, `refs/heads/${branch}`],
+        { timeout: 3e4 }
+      );
+      return out.length === 0 ? 0 : out.split("\n").length;
+    } catch (err) {
+      this.log.warn("ls-remote probe failed \u2014 assuming a populated remote", {
+        error: redactUrlAuth(err instanceof Error ? err.message : String(err))
+      });
+      return null;
+    }
+  }
+  /**
+   * 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 only the push to
+   * origin is gated on it. 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.
+   */
+  async bootstrapEmptyRemote(targetDir, branch, authUrl, access) {
+    await this.initInPlace(targetDir, authUrl);
+    await git(["symbolic-ref", "HEAD", `refs/heads/${branch}`], targetDir, 5e3);
+    await git(
+      [
+        "-c",
+        `user.name=${BOOTSTRAP_COMMIT_NAME}`,
+        "-c",
+        `user.email=${BOOTSTRAP_COMMIT_EMAIL}`,
+        "commit",
+        "--allow-empty",
+        "-m",
+        "chore: initialize repository"
+      ],
+      targetDir,
+      3e4
+    );
+    if (access === "read-only") {
+      this.log.info("empty remote is read-only \u2014 branch created locally, nothing pushed", {
+        branch
+      });
+      return;
+    }
+    try {
+      await git(["push", "-u", "origin", branch], targetDir, 6e4);
+      this.log.info("empty remote initialised on origin", { branch });
+      return;
+    } catch (err) {
+      this.log.warn("empty-remote publish push failed; deferring to lifecycle push", {
+        branch,
+        error: redactUrlAuth(err instanceof Error ? err.message : String(err))
+      });
+    }
+    const publishedElsewhere = await this.countRemoteHeads(targetDir, authUrl, branch);
+    if (publishedElsewhere === null || publishedElsewhere === 0) return;
+    try {
+      this.log.info("origin gained the branch concurrently \u2014 adopting it", { branch });
+      await this.bootstrapFromOrigin(targetDir, branch, authUrl);
+    } catch (err) {
+      this.log.warn("adopting the concurrently-created branch failed; keeping local branch", {
+        branch,
+        error: redactUrlAuth(err instanceof Error ? err.message : String(err))
+      });
+    }
+  }
   /**
    * True when `<targetDir>/.git` contains at least one resolvable commit
    * (i.e. `HEAD` points at a real object). False when `.git` is an empty
@@ -5804,6 +6041,13 @@ var ConnectorManager = class {
   }
   opts;
   active = /* @__PURE__ */ new Map();
+  /**
+   * Connectors whose `connect()` threw, keyed by id. A failed connector never
+   * enters `active`, so without this map its failure would exist only in the
+   * log store — invisible to the agent that is about to write into a mount
+   * that will never sync. See {@link listFailedConnectors}.
+   */
+  failedConnectors = /* @__PURE__ */ new Map();
   // Allocated absolute mount target → owning connector id; collisions rejected at setup, released on disconnect.
   mountTargets = /* @__PURE__ */ new Map();
   workspaceDir;
@@ -5942,6 +6186,30 @@ var ConnectorManager = class {
     }
     this.mountTargets.set(absPath, id);
   }
+  /**
+   * Remember a connect failure so the agent can be told about it. Called from
+   * both the bulk (`attemptConnect`) and hot-plug (`connect`) failure paths.
+   */
+  recordFailure(decl, error) {
+    if (this.active.has(decl.id)) return;
+    let mountPath;
+    if (decl.mount != null) {
+      try {
+        mountPath = this.resolveMountTarget(decl);
+      } catch {
+      }
+    }
+    this.failedConnectors.set(decl.id, {
+      id: decl.id,
+      driver: decl.driver,
+      access: decl.access,
+      ...decl.label !== void 0 ? { label: decl.label } : {},
+      ...decl.mount?.source !== void 0 ? { source: decl.mount.source } : {},
+      ...mountPath !== void 0 ? { mountPath } : {},
+      required: decl.access === "read-write" && decl.mount != null,
+      error
+    });
+  }
   /** Release every mount target owned by `id` (on disconnect). */
   releaseMountTarget(id) {
     for (const [path, owner] of [...this.mountTargets]) {
@@ -6094,6 +6362,7 @@ var ConnectorManager = class {
         handle,
         declaration: decl
       });
+      this.failedConnectors.delete(decl.id);
       this.opts.onStatusChange?.({
         type: "connector_status",
         connectorId: decl.id,
@@ -6108,6 +6377,7 @@ var ConnectorManager = class {
     } catch (err) {
       if (!this.active.has(decl.id)) this.releaseMountTarget(decl.id);
       const msg = err instanceof Error ? err.message : String(err);
+      this.recordFailure(decl, msg);
       this.mgrLog.error("connect failed", err, { id: decl.id, driver: decl.driver });
       this.opts.onStatusChange?.({
         type: "connector_status",
@@ -6152,6 +6422,7 @@ var ConnectorManager = class {
     }
     this.active.clear();
     this.mountTargets.clear();
+    this.failedConnectors.clear();
     this.mgrLog.info("disconnectAll complete");
   }
   // ── Hot-plug ──────────────────────────────────────────────────────────────────
@@ -6186,6 +6457,7 @@ var ConnectorManager = class {
         () => connector.connect(declaration, ctx)
       );
       this.active.set(declaration.id, { connector, handle, declaration });
+      this.failedConnectors.delete(declaration.id);
       this.opts.onStatusChange?.({
         type: "connector_status",
         connectorId: declaration.id,
@@ -6195,6 +6467,7 @@ var ConnectorManager = class {
     } catch (err) {
       this.releaseMountTarget(declaration.id);
       const msg = err instanceof Error ? err.message : String(err);
+      this.recordFailure(declaration, msg);
       this.opts.onStatusChange?.({
         type: "connector_status",
         connectorId: declaration.id,
@@ -6207,9 +6480,25 @@ var ConnectorManager = class {
   /**
    * Disconnect a single connector by ID and stop its watcher.
    *
-   * @throws {Error} if the connector is not found
+   * A connector that only ever *failed* to connect is not in `active`, so
+   * `get(id)` would throw for it. Removing such a declaration is still a
+   * legitimate host action — and it is the only way to retract its
+   * `## Mount failures` row — so that case is handled as a plain forget rather
+   * than an error.
+   *
+   * @throws {Error} if the connector is neither connected nor recorded as failed
    */
   async disconnect(id) {
+    if (!this.active.has(id) && this.failedConnectors.has(id)) {
+      this.failedConnectors.delete(id);
+      this.releaseMountTarget(id);
+      this.opts.onStatusChange?.({
+        type: "connector_status",
+        connectorId: id,
+        status: "disconnected"
+      });
+      return;
+    }
     const entry = this.get(id);
     if (entry.watchHandle) {
       try {
@@ -6229,6 +6518,7 @@ var ConnectorManager = class {
           await entry.connector.disconnect(entry.handle);
         } finally {
           this.active.delete(id);
+          this.failedConnectors.delete(id);
           this.releaseMountTarget(id);
           this.opts.onStatusChange?.({
             type: "connector_status",
@@ -6344,6 +6634,22 @@ var ConnectorManager = class {
       status: entry.handle.status
     }));
   }
+  /**
+   * Return every connector whose `connect()` threw and that has not since
+   * connected.
+   *
+   * A failed connector is deliberately **absent** from `listConnectors()` and
+   * `get()` — it never entered the active map, and those surfaces describe what
+   * the agent can actually use. That is exactly why this second list exists:
+   * without it a failed mount is invisible to the prompt builder, and the agent
+   * keeps treating a dead directory as a live, synced workspace.
+   *
+   * Entries are cleared by a later successful connect of the same id, by
+   * `disconnect(id)`, and wholesale by `disconnectAll()`.
+   */
+  listFailedConnectors() {
+    return [...this.failedConnectors.values()].map((f) => ({ ...f }));
+  }
   /**
    * Lists git-backed connectors, surfacing the fields prompt-builders and the
    * runner's wake-mid-401 refresh handler need.
@@ -6558,6 +6864,14 @@ var ConnectorManager = class {
   }
 };
 var zStatic = z4.z ?? z4.default ?? z4;
+function readFailedConnectors(manager) {
+  if (typeof manager.listFailedConnectors !== "function") return [];
+  try {
+    return manager.listFailedConnectors();
+  } catch {
+    return [];
+  }
+}
 async function buildSdkConnectorTools(manager, options) {
   const shellAccess = options?.shellAccess ?? true;
   let sdk = options?.sdk;
@@ -6572,11 +6886,14 @@ async function buildSdkConnectorTools(manager, options) {
   const tools = [];
   tools.push({
     name: "connector_list",
-    description: "List all currently registered connectors with their id, driver, access mode, and available operations. Use this to discover connectors that may have been added after session start (e.g. shared-state stores like 'presence' or 'session' pushed by the host).",
+    description: "List connectors as {connected, failed}. `connected` holds the usable connectors with their id, driver, access mode, and available operations; `failed` holds connectors that did not connect this session, with the failure reason \u2014 their mount paths are dead directories, not synced workspaces. Use this to discover connectors that may have been added after session start (e.g. shared-state stores like 'presence' or 'session' pushed by the host).",
     inputSchema: {},
     handler: async () => {
       try {
-        const entries = manager.listConnectors();
+        const entries = {
+          connected: manager.listConnectors(),
+          failed: readFailedConnectors(manager)
+        };
         return { content: [{ type: "text", text: JSON.stringify(entries, null, 2) }] };
       } catch (err) {
         return {
@@ -6814,7 +7131,8 @@ function buildOperationInputSchema(args, z5) {
 function buildConnectorPromptSection(manager, options) {
   const shellAccess = options?.shellAccess ?? true;
   const allConnectors = manager.listConnectors();
-  if (allConnectors.length === 0) return "";
+  const failed = readFailedConnectors(manager);
+  if (allConnectors.length === 0 && failed.length === 0) return "";
   const sections = [];
   const faces = allConnectors.map((c) => {
     try {
@@ -6832,8 +7150,46 @@ function buildConnectorPromptSection(manager, options) {
   if (toolConnectors.length > 0) {
     sections.push(buildToolSection(manager, toolConnectors, shellAccess));
   }
+  if (failed.length > 0) {
+    sections.unshift(buildFailedConnectorSection(failed));
+  }
   return sections.join("\n\n");
 }
+function buildFailedConnectorSection(failed) {
+  const lines = [
+    "## Mount failures \u2014 read this first",
+    "",
+    "The following connectors **failed to connect** in this session. Their directories are ordinary local folders: **not** connected, **not** synced, and **not** backend-managed git worktrees. Any other statement in this prompt \u2014 including the host platform's own description of the workspace \u2014 that describes these paths as a managed, synced, or version-controlled workspace **is superseded by this section**.",
+    "",
+    "| Mount | Driver | Path | Access | Required | Failure |",
+    "|---|---|---|---|---|---|"
+  ];
+  for (const f of failed) {
+    const path = f.mountPath ?? f.source ?? "(no mount)";
+    const required = f.required ? "yes" : "no";
+    lines.push(
+      `| ${f.id} | ${f.driver} | \`${path}\` | ${f.access} | ${required} | ${oneLine(f.error)} |`
+    );
+  }
+  lines.push("");
+  lines.push(
+    "**Work written under these paths is not saved.** The mount's lifecycle automation \u2014 auto-commit, push-after-commit, push-on-hibernate, commit-on-hibernate, push-on-close \u2014 is dead for a failed connector: nothing is committed, nothing is pushed, and the contents do not survive the session. Do not tell the user their work is saved, synced, or pushed. If they ask you to write substantial work into one of these paths, say first that it will be lost. `Required: yes` marks a read-write mount the session was supposed to be built on \u2014 that session did not start degraded, it started with nowhere to save anything."
+  );
+  lines.push("");
+  lines.push(
+    "**There is nothing to fix inside this workspace.** The credential for a mount is minted by the host platform, not by anything in here and not by any project setting \u2014 there is no credential field to fill in. Report the failure text above verbatim to the user and ask them to reconnect the connector's provider link on the platform, then restart the session. Do not retry the connection yourself; a connector that failed at startup stays failed until the session restarts."
+  );
+  if (failed.some((f) => f.driver === "git")) {
+    lines.push("");
+    lines.push(
+      "**Git specifically:** `git fetch` and `git ls-remote` can still succeed against a public remote with no credential at all, so a working read is **not** evidence that auth works. Only writes need the credential. `git push` will fail with `skaile: mount not connected: \u2026`. Do not retry it in a loop and do not attempt to configure git credentials by hand."
+    );
+  }
+  return lines.join("\n");
+}
+function oneLine(text) {
+  return text.replace(/\s*[\r\n]+\s*/g, " ").replace(/\|/g, "\\|").trim();
+}
 function buildFilesystemSection(manager, fsConnectors) {
   const lines = [
     "## Mounts",
@@ -6937,15 +7293,29 @@ function safeHost(source) {
     return source;
   }
 }
-
-// connectors/src/credential-helper-script.ts
+function shQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function singleLine(value) {
+  return value.replace(/[\r\n]+/g, " ").trim();
+}
+function mountIdFromTag(tag) {
+  const match = tag.match(/^#\s*skaile-mount:\s*(.+)$/);
+  return (match?.[1] ?? tag).trim();
+}
+function stampSlug(tag) {
+  return mountIdFromTag(tag).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "mount";
+}
 function renderCredentialHelperScript(opts) {
   const triggerAgeSec = opts.triggerAgeSec ?? 300;
   const waitTimeoutMs = opts.waitTimeoutMs ?? 5e3;
   const waitTimeoutSec = Math.max(1, Math.ceil(waitTimeoutMs / 1e3));
-  const credPath = opts.credentialsPath;
-  const flagPath = opts.refreshFlagPath;
+  const cooldownSec = Math.max(0, Math.trunc(opts.refreshCooldownSec ?? 30));
   const tag = opts.credentialTag;
+  const unavailable = opts.unavailableReason != null && opts.unavailableReason.trim().length > 0;
+  const attemptPath = opts.refreshAttemptPath ?? join(dirname(opts.credentialsPath), `refresh-attempt-${stampSlug(tag)}`);
+  const message = unavailable ? `skaile: mount not connected: ${singleLine(opts.unavailableReason ?? "")}` : `skaile: no credential available for git mount ${mountIdFromTag(tag)} \u2014 the workspace mount is not authenticated.`;
+  const readsStillWorkNote = "skaile: git fetch/ls-remote can still succeed on a public remote; only writes need this credential.";
   return `#!/bin/sh
 # Generated by skaile-runner -- do not edit.
 # Tier-2 git credential helper: serves the latest cached token and triggers a
@@ -6959,15 +7329,29 @@ op="\${1:-}"
 # (none today) also bail silently so we don't break future git versions.
 [ "$op" = "get" ] || exit 0
 
-CRED_FILE='${credPath}'
-FLAG_FILE='${flagPath}'
-TAG='${tag}'
+CRED_FILE=${shQuote(opts.credentialsPath)}
+FLAG_FILE=${shQuote(opts.refreshFlagPath)}
+TAG=${shQuote(tag)}
+ATTEMPT_FILE=${shQuote(attemptPath)}
+MSG=${shQuote(message)}
+UNAVAILABLE=${unavailable ? 1 : 0}
 
 # Drain stdin: git always pipes the request envelope. Leaving it unread can
 # wedge git's helper FD. We don't actually need any of it -- the credentials
 # file already keys by URL prefix via the helper's gitconfig block.
 cat > /dev/null 2>&1 || true
 
+# 'quit=1' is what actually stops git's helper chain. Exiting 0 with no output
+# sends git to the next helper and then the terminal prompt ("could not read
+# Username"); exiting non-zero does the same. Only quit=1 makes git report our
+# reason as the terminal failure.
+if [ "$UNAVAILABLE" -eq 1 ]; then
+  printf '%s\\n' "$MSG" >&2
+  printf '%s\\n' ${shQuote(readsStillWorkNote)} >&2
+  printf 'quit=1\\n'
+  exit 0
+fi
+
 # Cross-platform mtime in epoch seconds: GNU stat -c first (Linux), then BSD
 # stat -f (macOS), then 0 if neither is present (in which case we skip the
 # refresh-flag dance entirely and just serve what we have).
@@ -6985,38 +7369,59 @@ started_empty=0
 [ -s "$CRED_FILE" ] || started_empty=1
 
 if [ "$started_empty" -eq 1 ] || [ "$age" -gt ${triggerAgeSec} ]; then
-  # Touch the refresh-flag (atomic open+close emits 'change' to fs.watch).
-  : > "$FLAG_FILE" 2>/dev/null || true
+  # Bound the dance. A refresh that keeps failing would otherwise cost every
+  # git network op a fresh timeout, forever. The stamp below is written only
+  # when a dance changed nothing, so a working refresh is never throttled.
+  last_attempt=$(get_mtime "$ATTEMPT_FILE")
+  if [ $((now - last_attempt)) -ge ${cooldownSec} ]; then
+    # Touch the refresh-flag (atomic open+close emits 'change' to fs.watch).
+    # The subshell is load-bearing: ':' is a POSIX *special built-in*, so a
+    # redirection error on it terminates a non-interactive dash/ash outright --
+    # '|| true' never runs, and the helper would die before reaching the
+    # quit=1 block below. Run the redirection in a child instead.
+    ( : > "$FLAG_FILE" ) 2>/dev/null || true
 
-  # Poll for the credentials file mtime to advance. usleep gives sub-second
-  # resolution where available; sleep 1 is the portable fallback. Resolve which
-  # once, up front, rather than probing PATH on every iteration.
-  if command -v usleep >/dev/null 2>&1; then
-    have_usleep=1
-  else
-    have_usleep=0
-  fi
-  end=$((now + ${waitTimeoutSec}))
-  while :; do
-    cur=$(date +%s 2>/dev/null || echo 0)
-    if [ "$cur" -ge "$end" ]; then
-      break
-    fi
-    new_mtime=$(get_mtime "$CRED_FILE")
-    if [ "$new_mtime" -gt "$mtime" ]; then
-      break
-    fi
-    # A same-second rewrite doesn't advance the second-resolution mtime, so an
-    # empty file that gained content must break on content, not on mtime.
-    if [ "$started_empty" -eq 1 ] && [ -s "$CRED_FILE" ]; then
-      break
-    fi
-    if [ "$have_usleep" -eq 1 ]; then
-      usleep 200000
+    # Poll for the credentials file mtime to advance. usleep gives sub-second
+    # resolution where available; sleep 1 is the portable fallback. Resolve which
+    # once, up front, rather than probing PATH on every iteration.
+    if command -v usleep >/dev/null 2>&1; then
+      have_usleep=1
     else
-      sleep 1
+      have_usleep=0
+    fi
+    refreshed=0
+    end=$((now + ${waitTimeoutSec}))
+    while :; do
+      cur=$(date +%s 2>/dev/null || echo 0)
+      if [ "$cur" -ge "$end" ]; then
+        break
+      fi
+      new_mtime=$(get_mtime "$CRED_FILE")
+      if [ "$new_mtime" -gt "$mtime" ]; then
+        refreshed=1
+        break
+      fi
+      # A same-second rewrite doesn't advance the second-resolution mtime, so an
+      # empty file that gained content must break on content, not on mtime.
+      if [ "$started_empty" -eq 1 ] && [ -s "$CRED_FILE" ]; then
+        refreshed=1
+        break
+      fi
+      if [ "$have_usleep" -eq 1 ]; then
+        usleep 200000
+      else
+        sleep 1
+      fi
+    done
+    if [ "$refreshed" -eq 0 ]; then
+      # Subshell for the same reason as the flag write above. Here it also
+      # matters in the ordinary case: the stamp lives in a runner-owned
+      # directory, so under uid separation the agent can only truncate a file
+      # the runner pre-created. A missing pre-create must cost the cooldown,
+      # never the quit=1 report.
+      ( : > "$ATTEMPT_FILE" ) 2>/dev/null || true
     fi
-  done
+  fi
 fi
 
 # Find the credential line for THIS mount (matched by the trailing tag) and
@@ -7025,7 +7430,16 @@ fi
 # more than one matching line (shouldn't happen but defence-in-depth), we
 # take the last one (most recently written).
 line=$(grep -F " $TAG" "$CRED_FILE" 2>/dev/null | tail -n 1)
-[ -n "$line" ] || exit 0
+if [ -z "$line" ]; then
+  # No credential to serve. Terminate the chain rather than exiting 0, which
+  # would hand git back to its username prompt -- the misleading error this
+  # helper exists to replace. The same fetch-succeeds/push-fails confusion
+  # applies here as on the known-dead path, so say so either way.
+  printf '%s\\n' "$MSG" >&2
+  printf '%s\\n' ${shQuote(readsStillWorkNote)} >&2
+  printf 'quit=1\\n'
+  exit 0
+fi
 
 # Strip the trailing ' <TAG>' from the URL.
 url=\${line% *}
@@ -7170,6 +7584,7 @@ var ManagedGitconfigCollisionError = class extends Error {
 var blockStart = (mountId) => `# skaile-mount: ${mountId}`;
 var blockEnd = (mountId) => `# skaile-mount: ${mountId} (end)`;
 var credentialTag = (mountId) => `# skaile-mount: ${mountId}`;
+var UNAVAILABLE_MARKER = "# skaile-mount-unavailable";
 function readFileOrEmpty(path) {
   try {
     return readFileSync(path, "utf-8");
@@ -7274,17 +7689,22 @@ function blockUrlPrefix(block) {
   }
   return void 0;
 }
+function isUnavailableBlock(block) {
+  return block.lines.some((l) => l.trim() === UNAVAILABLE_MARKER);
+}
 function writeMountBlock(opts) {
   const { mountId, urlPrefix, token, gitconfigPath, credentialsPath, helperScriptPath } = opts;
   const text = readFileOrEmpty(gitconfigPath);
-  const blocks = parseBlocks(text);
-  for (const b of blocks) {
+  const parsed = parseBlocks(text);
+  for (const b of parsed) {
     if (b.mountId === "" || b.mountId === mountId) continue;
+    if (isUnavailableBlock(b)) continue;
     const otherPrefix = blockUrlPrefix(b);
     if (otherPrefix === urlPrefix) {
       throw new ManagedGitconfigCollisionError(urlPrefix, b.mountId, mountId);
     }
   }
+  const blocks = parsed.filter((b) => !(isUnavailableBlock(b) && blockUrlPrefix(b) === urlPrefix));
   const newBlock = {
     mountId,
     lines: buildBlock(mountId, urlPrefix, credentialsPath, helperScriptPath)
@@ -7302,6 +7722,48 @@ function writeMountBlock(opts) {
   filtered.push(buildCredentialLine(urlPrefix, token, mountId));
   writeCredentialLines(credentialsPath, filtered);
 }
+function writeUnavailableMountBlock(opts) {
+  const { mountId, urlPrefix, gitconfigPath, credentialsPath, helperScriptPath } = opts;
+  const lines = readCredentialLines(credentialsPath);
+  const tag = credentialTag(mountId);
+  const filtered = lines.filter((l) => !l.endsWith(tag));
+  if (filtered.length !== lines.length) {
+    writeCredentialLines(credentialsPath, filtered);
+  }
+  const blocks = parseBlocks(readFileOrEmpty(gitconfigPath));
+  for (const b of blocks) {
+    if (b.mountId === "" || b.mountId === mountId) continue;
+    if (isUnavailableBlock(b)) continue;
+    if (blockUrlPrefix(b) === urlPrefix) return;
+  }
+  const newLines = [
+    blockStart(mountId),
+    UNAVAILABLE_MARKER,
+    `[credential "${urlPrefix}"]`,
+    `	helper = !sh ${helperScriptPath}`,
+    blockEnd(mountId)
+  ];
+  const existing = findExistingBlock(blocks, mountId);
+  if (existing) {
+    existing.lines = newLines;
+  } else {
+    blocks.push({ mountId, lines: newLines });
+  }
+  atomicWrite(gitconfigPath, renderBlocks(blocks), 416);
+}
+function removeUnavailableMountBlock(opts) {
+  const { mountId, gitconfigPath, urlPrefix } = opts;
+  const text = readFileOrEmpty(gitconfigPath);
+  if (text.length === 0) return;
+  const blocks = parseBlocks(text);
+  const doomed = new Set(
+    blocks.filter(
+      (b) => isUnavailableBlock(b) && (b.mountId === mountId || urlPrefix !== void 0 && blockUrlPrefix(b) === urlPrefix)
+    )
+  );
+  if (doomed.size === 0) return;
+  atomicWrite(gitconfigPath, renderBlocks(blocks.filter((b) => !doomed.has(b))), 416);
+}
 function removeMountBlock(opts) {
   const { mountId, gitconfigPath, credentialsPath } = opts;
   const text = readFileOrEmpty(gitconfigPath);
@@ -7319,6 +7781,17 @@ function removeMountBlock(opts) {
 function writeHelperScript(scriptPath, body) {
   atomicWrite(scriptPath, body, 493);
 }
+function ensureRefreshAttemptStamp(stampPath) {
+  if (existsSync(stampPath)) return;
+  const dir = dirname(stampPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 448 });
+  }
+  const fd = openSync(stampPath, "a", 432);
+  closeSync(fd);
+  chmodSync(stampPath, 432);
+  utimesSync(stampPath, 0, 0);
+}
 function atomicReplaceCredential(opts) {
   const { mountId, urlPrefix, token, credentialsPath } = opts;
   const lines = readCredentialLines(credentialsPath);
@@ -10079,6 +10552,6 @@ function createConnector() {
   return new FlowAdapter();
 }
 
-export { AbstractConnector, BUILTIN_CONNECTOR_CATALOG, BoxConnector, ConnectorFieldMissingError, ConnectorManager, ConnectorStartupError, DeployConnector, DevServerConnector, FlowAdapter, GitConnector, GmailConnector, GoogleDriveConnector, LocalConnector, LogBuffer, ManagedGitconfigCollisionError, MattermostConnector, MemoryConnector, MinIOConnector, PortPool, PostgresConnector, S3Connector, SQLiteConnector, SessionInlineSubFlowRunner, SessionNodeExecutor, SessionSubpromptRunner, SharePointConnector, StaticServerConnector, TunnelConnector, WebDAVConnector, XStateConnector, XStateStoreConnector, __test, atomicReplaceCredential, buildConnectorPromptSection, buildFlowPromptEvent, buildSdkConnectorTools, buildSdkFlowTools, createConnector, createConnector10, createConnector11, createConnector12, createConnector13, createConnector14, createConnector15, createConnector16, createConnector17, createConnector18, createConnector19, createConnector2, createConnector20, createConnector3, createConnector4, createConnector5, createConnector6, createConnector7, createConnector8, createConnector9, createFsWatcher, createWorktree, defaultSpawn, driveOrchestratorTurn, ensureDirMode, ensureFleetMounted, findGitRoot, findMissingPackages, getConnector, installNpmPackages, isFleetManaged, isPackageResolvable, listConnectors, listWorktrees, readGitSyncStatus, registerBuiltinConnectors, removeMountBlock, renderCredentialHelperScript, tryGetConnector, worktreeRegistry, writeHelperScript, writeMountBlock };
-//# sourceMappingURL=chunk-JTBF4OB2.js.map
-//# sourceMappingURL=chunk-JTBF4OB2.js.map
+export { AbstractConnector, BUILTIN_CONNECTOR_CATALOG, BoxConnector, ConnectorFieldMissingError, ConnectorManager, ConnectorStartupError, DeployConnector, DevServerConnector, FlowAdapter, GitConnector, GmailConnector, GoogleDriveConnector, LocalConnector, LogBuffer, ManagedGitconfigCollisionError, MattermostConnector, MemoryConnector, MinIOConnector, PortPool, PostgresConnector, S3Connector, SQLiteConnector, SessionInlineSubFlowRunner, SessionNodeExecutor, SessionSubpromptRunner, SharePointConnector, StaticServerConnector, TunnelConnector, WebDAVConnector, XStateConnector, XStateStoreConnector, __test, atomicReplaceCredential, buildConnectorPromptSection, buildFlowPromptEvent, buildSdkConnectorTools, buildSdkFlowTools, createConnector, createConnector10, createConnector11, createConnector12, createConnector13, createConnector14, createConnector15, createConnector16, createConnector17, createConnector18, createConnector19, createConnector2, createConnector20, createConnector3, createConnector4, createConnector5, createConnector6, createConnector7, createConnector8, createConnector9, createFsWatcher, createWorktree, defaultSpawn, driveOrchestratorTurn, ensureDirMode, ensureFleetMounted, ensureRefreshAttemptStamp, findGitRoot, findMissingPackages, getConnector, installNpmPackages, isFleetManaged, isPackageResolvable, listConnectors, listWorktrees, readGitSyncStatus, registerBuiltinConnectors, removeMountBlock, removeUnavailableMountBlock, renderCredentialHelperScript, tryGetConnector, worktreeRegistry, writeHelperScript, writeMountBlock, writeUnavailableMountBlock };
+//# sourceMappingURL=chunk-6GDVGAIZ.js.map
+//# sourceMappingURL=chunk-6GDVGAIZ.js.map