pi-git-auth 1.1.1 → 1.2.3

package/README.md

@@ -2,7 +2,7 @@
 
 A [pi](https://github.com/badlogic/pi-mono) (coding-agent) extension that 
 gives the agent **git forges authentication** for **GitHub and GitLab**: login tokens are stored in the
-OS keyring, switch account, and every `git`command 
+OS keyring (kwallet), switch account, and every `git`command 
 the agent runs is transparently authenticated with that account's
 token for its host. It also manages accounts and repositories through each
 service's REST API.
@@ -54,6 +54,7 @@ github.ts    GitHub REST client
 gitlab.ts    GitLab REST client
 details.ts   read-only repo details overlay (tree + commits + metadata)
 git-gate.ts  command rewriting that injects the token for a host
+git-helpers.ts detection of file-persisting credential helpers (status note)
 redact.ts    secret redaction of tool outputs (PAT / URL-credential patterns)
 ```
 
@@ -121,15 +122,28 @@ use that account's token for the account's host (`github.com` or
 
 ```
 export GIT_TERMINAL_PROMPT=0 \
-  GIT_CONFIG_COUNT=1 \
+  GIT_CONFIG_COUNT=2 \
   GIT_CONFIG_KEY_0="url.https://x-access-token:<token>@<host>/.insteadOf" \
-  GIT_CONFIG_VALUE_0="https://<host>/" && <command>
+  GIT_CONFIG_VALUE_0="https://<host>/" \
+  GIT_CONFIG_KEY_1="credential.helper" \
+  GIT_CONFIG_VALUE_1="" && <command>
 ```
 
 Forging hosts' git-over-HTTPS endpoints ignore `Authorization` headers
 and only accept URL-embedded credentials, hence the `insteadOf` rewrite.
 Only the active host is touched; other remotes are untouched.
 
+The empty `credential.helper` entry disables git's credential helpers for
+the instrumented process only (env config is read after all file configs,
+and an empty value clears previously defined helpers). This is required so
+that git's post-auth store phase does not persist the injected token — e.g.
+a user-configured `credential.helper = store` would otherwise write it
+plaintext to `~/.git-credentials`. All other standard auth mechanisms
+(URL-embedded credentials, `credential.<url>.*` config, `.netrc`, SSH) are
+unaffected; helpers remain fully active everywhere the gate does not run.
+If a file-persisting helper is detected in the user's config, `/auth
+status` notes it passively (one line, no prompt).
+
 ## Token storage
 
 Tokens are **never stored plaintext on disk**. Two backends are
@@ -138,9 +152,11 @@ available; the extension picks one at load time.
 ### OS keyring (preferred)
 The token lives in the session keyring, addressed by the
 [freedesktop Secret Service API](https://specifications.freedesktop.org/secret-service/)
-(`org.freedesktop.secrets` over D-Bus). This covers KWallet (via
-`ksecretd`), GNOME Keyring, KeePassXC, and any other Secret Service
-provider.
+(`org.freedesktop.secrets` over D-Bus). Any provider that implements
+that API over D-Bus is targeted: KWallet (via `ksecretd`) is the one
+verified end-to-end (including the interactive unlock dialog); GNOME
+Keyring and KeePassXC are covered by the same generic code path but
+have not been tested.
 
 - The embedded python3 client (a small script that `keyring.ts` keeps
   in sync in the state dir) opens a D-Bus session and talks
@@ -163,18 +179,31 @@ absolute minimum:
 - **Lookup never prompts.** A read on a locked collection returns
   `locked` without touching the collection — no stacked prompts, no kded
   "Repeated attempts to access a wallet have occurred" warning.
-- **Store is a single roundtrip** (delete matching items + create the new
-  one, at most one unlock attempt) and only runs when a token actually
+- **Interactive unlock uses the Secret Service Prompt protocol.**
+  `Service.Unlock()` on a locked `ksecretd` collection returns a Prompt
+  object; the "KDE Wallet Service" password dialog is only shown once the
+  client calls `Prompt.Prompt()` on that object. The client does both:
+  trigger the dialog, then poll the collection's `Locked` property until it
+  actually opens (or the wait expires).
+- **Store is a single roundtrip** (create the new item + delete any older
+  matches, at most one unlock attempt) and only runs when a token actually
   changed. `/auth switch`, `status`, and plain git use perform **zero**
-  keyring writes.
-- **When the wallet is locked (or the keyring is otherwise unreachable)
-  while writing**, the token is transparently kept in the encrypted file
-  instead of leaving a dead `wallet:v1:` marker — the token stays
-  available. Once the wallet unlocks, the next token change moves it back
-  into the keyring.
-- If the wallet is locked when pi starts, the in-memory token is empty for
-  that session (git auth is disabled meanwhile) and `/auth status` says so
-  explicitly instead of showing a bare `(none)`.
+  keyring writes. On an interactive save (login) the client **waits up to
+  20 s for the unlock prompt to be answered** — without the wait the token
+  would silently fall back to the file every time the wallet happens to be
+  locked.
+- **When the wallet is still locked (or the keyring is otherwise
+  unreachable) after the wait**, the token is transparently kept in the
+  encrypted file instead of leaving a dead `wallet:v1:` marker — the token
+  stays available. Once the wallet unlocks, the token moves back into the
+  keyring on the next load.
+- If the wallet is locked when pi starts, the in-memory token is empty
+  (git auth is disabled meanwhile) and `/auth status` says so explicitly
+  instead of showing a bare `(none)`. The lookup is retried automatically
+  (throttled, prompt-safe) on the next `/auth status` or git-gate hit, so
+  the token recovers as soon as the wallet unlocks — no re-login needed.
+- `/auth status` reports where the active token **actually** lives
+  (keyring vs. encrypted file), not just which backend was selected.
 
 ### Encrypted file (fallback)
 When python3 / D-Bus / a keyring are unavailable (headless server, no

package/auth.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { loadStore, saveStore, maskToken, activeAccount, accountKey, purgeAccountStorage, storeBackend, keyringUnavailableAtLoadFlag, type StoreData } from "./store";
+import { loadStore, saveStore, maskToken, activeAccount, accountKey, purgeAccountStorage, storeBackend, activeTokenStorage, keyringUnavailableAtLoadFlag, type StoreData } from "./store";
 import { SERVICES, type Platform, type Service } from "./forge";
 
 /** The subset of ctx.ui the auth flows need. */
@@ -117,7 +117,7 @@ export function activeService(data: StoreData): Service | undefined {
 }
 
 /** Human-readable status block: all accounts, details for the active one. */
-export function statusDetail(data: StoreData): string {
+export function statusDetail(data: StoreData, opts?: { credHelperSink?: { helper: string; target: string } }): string {
   const keys = Object.keys(data.accounts);
   if (keys.length === 0) return "No git accounts. Run /auth login.";
   const lines = ["Git accounts:"];
@@ -132,11 +132,26 @@ export function statusDetail(data: StoreData): string {
   }
   const activeKey = data.activeLogin;
   if (activeKey) lines.push("");
-  const backend = storeBackend() === "keyring" ? "OS keyring (Secret Service)" : "encrypted file";
-  const kwLocked = storeBackend() === "keyring" && keyringUnavailableAtLoadFlag();
-  lines.push(`Store: ${backend}${kwLocked ? " (locked/unreachable on load)" : ""}`);
-  if (activeKey) lines.push("");
+  const backendIsKeyring = storeBackend() === "keyring";
+  const kwLocked = backendIsKeyring && keyringUnavailableAtLoadFlag();
   const active = activeKey ? data.accounts[activeKey] : undefined;
+  let storeLine = backendIsKeyring
+    ? "Store: OS keyring (Secret Service)"
+    : "Store: encrypted file (fallback)";
+  if (!backendIsKeyring) {
+    storeLine +=
+      process.env.PI_GIT_AUTH_STORE?.toLowerCase() === "file"
+        ? " — forced by PI_GIT_AUTH_STORE=file"
+        : " — keyring unavailable";
+  } else if (!active?.accessToken && kwLocked) {
+    storeLine += " (wallet locked on load — token unavailable)";
+  }
+  lines.push(storeLine);
+  if (opts?.credHelperSink) {
+    lines.push(
+      `Git: credential.helper=${opts.credHelperSink.helper} detected — git may also cache gate tokens in ${opts.credHelperSink.target} (the gate itself keeps the token keyring-only)`,
+    );
+  }
   if (active && activeKey) {
     lines.push("");
     lines.push(`Active: @${active.user ?? activeKey.slice(activeKey.indexOf(":") + 1)}  (${active.platform})`);
@@ -144,6 +159,15 @@ export function statusDetail(data: StoreData): string {
       lines.push(
         "Token: (none) — keyring locked: the token is stored in the keyring and is available again once the wallet unlocks (git auth is disabled meanwhile)"
       );
+    } else if (active.accessToken) {
+      const inKeyring = backendIsKeyring && activeTokenStorage() === "keyring";
+      lines.push(
+        inKeyring
+          ? `Token: ${maskToken(active.accessToken)}  (stored in OS keyring)`
+          : `Token: ${maskToken(active.accessToken)}  (stored in encrypted file${
+              backendIsKeyring ? " — wallet was locked at save" : ""
+            })`,
+      );
     } else {
       lines.push(`Token: ${maskToken(active.accessToken)}`);
     }

package/commands.ts

@@ -1,17 +1,20 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { loadStore, activeAccount, type StoreData } from "./store";
+import { loadStore, activeAccount, retryKeyringLoad, type StoreData } from "./store";
 import { SERVICES, type Service, type TreeEntry } from "./forge";
 import { buildDetailsText, RepoDetailsPanel } from "./details";
 import { activeService, accountName, loginWithPastedToken, removeAccount, setActiveAccount, statusDetail } from "./auth";
+import { detectCredHelperSink } from "./git-helpers";
 
 type Ctx = ExtensionCommandContext;
 
 async function showStatus(ctx: Ctx): Promise<void> {
+  retryKeyringLoad(); // prompt-safe: recovers the token once the wallet unlocks
   const data = loadStore();
   if (Object.keys(data.accounts).length === 0) {
     ctx.ui.notify("git auth: not connected — run /auth login", "info");
   } else {
-    ctx.ui.notify(statusDetail(data), "info");
+    const sink = await detectCredHelperSink(); // cached, fail-silent
+    ctx.ui.notify(statusDetail(data, { credHelperSink: sink }), "info");
   }
 }
 

package/git-gate.ts

@@ -6,9 +6,11 @@
  * for that host, regardless of git's own credential configuration:
  *
  *   export GIT_TERMINAL_PROMPT=0 \
- *     GIT_CONFIG_COUNT=1 \
+ *     GIT_CONFIG_COUNT=2 \
  *     GIT_CONFIG_KEY_0="url.https://x-access-token:<token>@<host>/.insteadOf" \
- *     GIT_CONFIG_VALUE_0="https://<host>/" && <command>
+ *     GIT_CONFIG_VALUE_0="https://<host>/" \
+ *     GIT_CONFIG_KEY_1="credential.helper" \
+ *     GIT_CONFIG_VALUE_1="" && <command>
  *
  * Forging hosts' git-over-HTTPS endpoints ignore Authorization headers
  * and only accept URL-embedded (Basic) credentials, hence the insteadOf
@@ -19,6 +21,14 @@
  *  - GIT_TERMINAL_PROMPT=0: a failed auth surfaces as a clean error
  *    instead of an interactive prompt hanging the TUI.
  *  - Deterministic: no credential-helper races, same behavior every run.
+ *  - The token is never persisted by git's credential helpers: the empty
+ *    credential.helper entry (read after all file configs, where an empty
+ *    value clears previously defined helpers) disables helpers for the
+ *    instrumented process only. Without it, git's post-auth store phase
+ *    would hand the injected token to file-based helpers such as `store`,
+ *    persisting it plaintext to ~/.git-credentials. All other standard
+ *    auth mechanisms (URL-embedded credentials, credential.<url>.* config,
+ *    .netrc, SSH) are unaffected.
  *  - SSH-style URLs for the host are rewritten to HTTPS so the token applies.
  */
 
@@ -37,8 +47,10 @@ export function instrumentGit(command: string, host: string, token: string): str
     .replace(new RegExp(`git@${host}:`, "g"), `https://${host}/`);
   const prefix =
     `export GIT_TERMINAL_PROMPT=0 ` +
-    `GIT_CONFIG_COUNT=1 ` +
+    `GIT_CONFIG_COUNT=2 ` +
     `GIT_CONFIG_KEY_0="url.https://x-access-token:${token}@${host}/.insteadOf" ` +
-    `GIT_CONFIG_VALUE_0="https://${host}/" && `;
+    `GIT_CONFIG_VALUE_0="https://${host}/" ` +
+    `GIT_CONFIG_KEY_1="credential.helper" ` +
+    `GIT_CONFIG_VALUE_1="" && `;
   return prefix + rewritten;
 }

package/git-helpers.ts

@@ -0,0 +1,77 @@
+/**
+ * Detection of file-persisting git credential helpers.
+ *
+ * The git gate keeps its token out of helpers by disabling them for the
+ * instrumented process (see git-gate.ts). This module is the *advisory*
+ * side: it detects whether the user's normal git configuration would have
+ * persisted the injected token (e.g. `credential.helper = store` →
+ * ~/.git-credentials) so the status view can note it. Passive only — no
+ * prompt, no blocking, fail-silent (any error → `undefined`).
+ */
+import { execFile } from "node:child_process";
+
+export interface CredHelperSink {
+  /** The `credential.helper` value as configured (e.g. "store"). */
+  helper: string;
+  /** Where that helper persists credentials, for the status line. */
+  target: string;
+}
+
+const TTL_MS = 60_000;
+const TIMEOUT_MS = 3_000;
+
+let cache: { at: number; sink: CredHelperSink | undefined } | undefined;
+let inFlight: Promise<CredHelperSink | undefined> | undefined;
+
+function sinkFor(value: string): CredHelperSink | undefined {
+  const v = value.trim();
+  const base = v.split("/").pop() ?? v;
+  if (v === "store" || base === "credential-store" || v.endsWith("!store")) {
+    return { helper: v, target: "~/.git-credentials (plaintext)" };
+  }
+  if (v === "netrc" || base === "credential-netrc" || v.endsWith("!netrc")) {
+    return { helper: v, target: "~/.netrc" };
+  }
+  return undefined; // OS wallets (gnome-keyring, osxkeychain, …): fine, no note
+}
+
+/**
+ * Detect a file-persisting credential helper in the user's normal git
+ * config. Cached for 60 s, deduplicated in flight, and fail-silent:
+ * missing git, timeout, or no such helper → `undefined`.
+ */
+export function detectCredHelperSink(): Promise<CredHelperSink | undefined> {
+  const now = Date.now();
+  if (cache && now - cache.at < TTL_MS) return Promise.resolve(cache.sink);
+  if (inFlight) return inFlight;
+  inFlight = new Promise<CredHelperSink | undefined>((resolve) => {
+    let done = false;
+    const finish = (sink: CredHelperSink | undefined) => {
+      if (done) return;
+      done = true;
+      cache = { at: Date.now(), sink };
+      inFlight = undefined;
+      resolve(sink);
+    };
+    const timer = setTimeout(() => finish(undefined), TIMEOUT_MS);
+    execFile(
+      "git",
+      ["config", "--get-all", "--show-origin", "credential.helper"],
+      { timeout: TIMEOUT_MS },
+      (err, stdout) => {
+        clearTimeout(timer);
+        if (err) return finish(undefined);
+        // Lines: "<origin>\t<value>". Prefer the last (most specific) match.
+        let sink: CredHelperSink | undefined;
+        for (const line of stdout.split("\n")) {
+          const idx = line.indexOf("\t");
+          if (idx < 0) continue;
+          const found = sinkFor(line.slice(idx + 1));
+          if (found) sink = found;
+        }
+        finish(sink);
+      },
+    );
+  });
+  return inFlight;
+}

package/index.ts

@@ -1,10 +1,11 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { loadStore, activeAccount } from "./store";
+import { loadStore, activeAccount, retryKeyringLoad } from "./store";
 import { SERVICES } from "./forge";
 import { findAccounts, setActiveAccount, statusDetail } from "./auth";
 import { instrumentGit } from "./git-gate";
+import { detectCredHelperSink } from "./git-helpers";
 import { redactSecrets } from "./redact";
 import { handleAuthCommand } from "./commands";
 
@@ -15,6 +16,7 @@ export default function (pi: ExtensionAPI) {
   // ------------------------------------------------------------------
   pi.on("tool_call", async (event, ctx) => {
     if (!isToolCallEventType("bash", event)) return;
+    retryKeyringLoad(); // prompt-safe: recovers the token once the wallet unlocks
     const acc = activeAccount(loadStore());
     if (!acc?.accessToken) return;
     const host = SERVICES[acc.platform].host;
@@ -86,9 +88,11 @@ export default function (pi: ExtensionAPI) {
 
       switch (params.action) {
         case "status": {
+          retryKeyringLoad(); // prompt-safe: recovers the token once the wallet unlocks
           const data = loadStore();
           if (Object.keys(data.accounts).length === 0) return { ...text(notConnected), isError: true };
-          return text(statusDetail(data));
+          const sink = await detectCredHelperSink(); // cached, fail-silent
+          return text(statusDetail(data, { credHelperSink: sink }));
         }
 
         case "switch": {

package/keyring.ts

@@ -9,16 +9,25 @@
  * a process argument list — only in the parent process's memory.
  *
  * KWallet/ksecretd (KDE Plasma) notes:
- *   - ksecretd triggers a KWallet unlock dialog for every D-Bus operation
- *     on a LOCKED collection. To keep this from stacking prompts (and
- *     tripping kded's "Repeated attempts to access a wallet have
- *     occurred" warning):
+ *   ksecretd implements the Secret Service "Prompt" protocol: calling
+ *   Service.Unlock() on a locked collection returns a Prompt object, and
+ *   the unlock dialog (the real "KDE Wallet Service" password dialog,
+ *   shown by ksecretd itself) only appears when the client then calls
+ *   Prompt.Prompt(window_id) on it. We do exactly that (with an empty
+ *   window id — headless) and then wait `wait` seconds (default 20) for
+ *   the collection to actually unlock:
  *       * "lookup" on a locked collection returns {"locked": true} and
- *         never touches the collection;
- *       * "upsert" does delete+create in ONE D-Bus roundtrip with at most
- *         ONE explicit unlock attempt (only when a non-empty secret is
- *         actually being written);
+ *         never touches the collection (no prompt — reads happen in the
+ *         background during git operations);
+ *       * "upsert" creates the new item (with its secret) FIRST and only
+ *         then deletes the previously matched ones — kill-safe: an
+ *         interrupted upsert never destroys the keyring copy; when the
+ *         collection is locked and a non-empty secret is being written it
+ *         triggers ONE interactive unlock (Service.Unlock + Prompt) and
+ *         waits for it to complete;
  *       * delete-only ("clear" / empty secret) never unlocks.
+ * Non-interactive callers (bulk migration/repair at load) pass wait=0 and
+ * get the old instant-fallback behavior.
  *
  * Two API generations are auto-detected at runtime by introspection:
  *   - modern 0.0.1 (gnome-keyring, kwallet --secretservice):
@@ -37,6 +46,10 @@ import { join } from "node:path";
 export const STATE_DIR = join(homedir(), ".pi", "agent", "pi-git-auth");
 const PY_PATH = join(STATE_DIR, "wallet-tool.py");
 const TIMEOUT_MS = 8000;
+/** Default seconds to wait for an interactive wallet unlock on write. */
+export const UNLOCK_WAIT_S = 20;
+/** Upserts may block on an interactive unlock: give the wait room. */
+const UPSERT_TIMEOUT_MS = (UNLOCK_WAIT_S + 15) * 1000;
 
 /** Outcome of a keyring write: ok, keyring locked, or unreachable. */
 export type WalletResult = "ok" | "locked" | "unreachable";
@@ -54,19 +67,28 @@ const PY = `#!/usr/bin/env python3
 
 Protocol: one JSON request on stdin, one JSON response line on stdout.
   {"cmd": "available"}
-  {"cmd": "upsert", "attrs": {...}, "secret": "..."}   # empty secret = delete only
+  {"cmd": "upsert", "attrs": {...}, "secret": "...", "wait": 20}
+      # empty secret = delete only; wait = seconds to wait for an
+      # interactive unlock while writing (0 = never wait)
   {"cmd": "lookup", "attrs": {...}}
   {"cmd": "clear",  "attrs": {...}}
 
 Auto-detects the Secret Service API generation (modern 0.0.1 vs legacy
 0.0.0/ksecretd) by introspecting the service.
 
-KWallet/ksecretd (KDE) note: every D-Bus operation on a LOCKED collection
-triggers a KWallet unlock dialog. So:
+KWallet/ksecretd (KDE) note: ksecretd implements the Secret Service Prompt
+protocol. Service.Unlock() on a locked collection returns a Prompt object;
+the "KDE Wallet Service" password dialog (shown by ksecretd itself) only
+appears once the client calls Prompt.Prompt() on it. We do that (empty
+window id — we are headless) and then wait "wait" seconds for the
+collection to actually unlock.
   - "lookup" on a locked collection returns {"locked": true} and never
-    touches the collection;
-  - "upsert" does delete+create in ONE roundtrip with at most ONE explicit
-    unlock attempt, and only when a non-empty secret is written;
+    touches the collection (no prompt);
+  - "upsert" creates the new item (with its secret) FIRST and only then
+    deletes the previously matched ones — kill-safe: an interrupted
+    upsert never destroys the keyring copy; when locked and a non-empty
+    secret is written it triggers ONE interactive unlock (Service.Unlock
+    + Prompt.Prompt) and waits for it;
   - delete-only never unlocks.
 This keeps the client from stacking unlock prompts, which is what makes
 kded warn "Repeated attempts to access a wallet have occurred".
@@ -74,6 +96,9 @@ kded warn "Repeated attempts to access a wallet have occurred".
 import sys
 import json
 import re
+import time
+
+UNLOCK_WAIT_S = 20.0
 
 
 def out(obj):
@@ -160,6 +185,46 @@ def main():
             ))
             return [str(k) for k in list(u)], bool(locked)
 
+        def is_locked_now():
+            """Authoritative collection lock state, via the Locked
+            property. (SearchItems only reports locking through items that
+            match the query — a locked collection with NO matching items
+            would otherwise look unlocked!)"""
+            if MODERN:
+                return False
+            try:
+                return bool(dbus.Interface(
+                    bus.get_object(owner, str(coll)),
+                    "org.freedesktop.DBus.Properties",
+                ).Get("org.freedesktop.Secret.Collection", "Locked"))
+            except Exception:
+                return bool(find_items()[1])
+
+        def unlock_with_prompt():
+            """Trigger ksecretd's interactive unlock flow. Service.Unlock()
+            returns (unlocked collections, prompt object path); the dialog
+            is only shown once Prompt.Prompt(window_id) is called on that
+            object — and it is shown by ksecretd itself, so it survives
+            this process exiting."""
+            if MODERN:
+                return  # modern (0.0.1) API has no locking
+            try:
+                res = dbusi.Unlock([dbus.ObjectPath(str(coll))])
+                prompt = str(res[1]) if res and len(res) > 1 else "/"
+            except Exception:
+                return
+            if prompt and prompt != "/":
+                try:
+                    piface = dbus.Interface(
+                        bus.get_object(owner, prompt),
+                        "org.freedesktop.Secret.Prompt",
+                    )
+                    # Empty window id: ksecretd still shows the dialog,
+                    # unparented, kept above all windows.
+                    piface.Prompt("")
+                except Exception:
+                    pass
+
         def get_content(path):
             """Return the secret bytes for an item path, or None."""
             try:
@@ -198,7 +263,9 @@ def main():
                 pass
 
         if cmd in ("upsert", "store", "clear"):
+            wait = max(0.0, float(req.get("wait", UNLOCK_WAIT_S)))
             paths, is_locked = find_items()
+            is_locked = is_locked_now() or is_locked
             writing = cmd != "clear" and bool(secret)
             if is_locked:
                 if not writing:
@@ -207,22 +274,38 @@ def main():
                     out({"ok": False, "locked": True,
                          "error": "keyring is locked"})
                     return
-                # writing while locked: exactly ONE unlock attempt (one
-                # prompt), then re-check.
-                try:
-                    dbusi.Unlock([coll])
-                except Exception:
+                if wait <= 0:
+                    # Non-interactive caller: NEVER prompt. Fall through to
+                    # the write attempt below — it may still succeed if the
+                    # wallet is being unlocked in parallel; otherwise the
+                    # IsLocked D-Bus error is caught below and reported as
+                    # "locked".
                     pass
-                paths, is_locked = find_items()
-                if is_locked:
-                    out({"ok": False, "locked": True,
-                         "error": "keyring is locked"})
-                    return
-            for path in paths:
-                item_delete(path)
+                else:
+                    # Writing while locked: trigger the interactive unlock
+                    # (Service.Unlock + Prompt — ksecretd shows the "KDE
+                    # Wallet Service" password dialog) and wait for the
+                    # collection to actually unlock.
+                    unlock_with_prompt()
+                    deadline = time.time() + wait
+                    while is_locked_now() and time.time() < deadline:
+                        time.sleep(1)
+                    if is_locked_now():
+                        out({"ok": False, "locked": True,
+                             "error": "keyring is locked"})
+                        return
+                    paths, is_locked = find_items()
             if cmd == "clear" or not secret:
+                for path in paths:
+                    item_delete(path)
                 out({"ok": True})
                 return
+            # Kill-safe order: create the new item (with its secret) first,
+            # then delete the previously matched items. Even if this process
+            # is killed mid-upsert the keyring copy is never destroyed
+            # (worst case: orphan items remain; the next upsert cleans them
+            # up, and lookups take the first non-empty secret).
+            new_path = ""
             if MODERN:
                 item = "/org/freedesktop/secrets/0/item/" + re.sub(
                     r"[^A-Za-z0-9_]", "_", "%s_%s" % (
@@ -262,6 +345,7 @@ def main():
                         "sv",
                     ),
                 )
+                new_path = item
             else:
                 coll_obj = dbus.Interface(
                     bus.get_object(owner, str(coll)),
@@ -282,11 +366,33 @@ def main():
                             {k: v for k, v in attrs.items()}, "ss"
                         ),
                 }, "sv")
-                coll_obj.CreateItem(props, secret_arg, True)
+                create_res = coll_obj.CreateItem(props, secret_arg, True)
+                # ksecretd returns (item_path, prompt) — the item comes
+                # FIRST (the 0.0.1 spec says (session, item)); scan the
+                # whole reply for a path under this collection instead of
+                # trusting a fixed index.
+                for cand in (
+                    create_res if isinstance(create_res, tuple) else ()
+                ):
+                    s = str(cand)
+                    if s.startswith(str(coll) + "/"):
+                        new_path = s
+                        break
+            if new_path:
+                for path in paths:
+                    if path != new_path:
+                        item_delete(path)
+            # else: can't tell which pre-matched item was updated in place —
+            # keep them all (orphans are harmless); deleting blindly would
+            # destroy the copy we just wrote.
             out({"ok": True})
             return
 
         if cmd == "lookup":
+            if is_locked_now():
+                out({"ok": False, "locked": True,
+                     "error": "keyring is locked"})
+                return
             paths, is_locked = find_items()
             for path in paths:
                 content = get_content(path)
@@ -307,10 +413,18 @@ def main():
 
         out({"ok": False, "error": "unknown command"})
     except Exception as e:
+        name = ""
+        try:
+            name = e.get_dbus_name() or ""  # D-Bus error name (python-dbus)
+        except Exception:
+            pass
         msg = str(e)
         if secret:
             msg = msg.replace(secret, "***")
-        out({"ok": False, "error": msg or e.__class__.__name__})
+        if "IsLocked" in name or "IsLocked" in msg:
+            out({"ok": False, "locked": True, "error": "keyring is locked"})
+        else:
+            out({"ok": False, "error": msg or e.__class__.__name__})
 
 
 main()
@@ -374,14 +488,19 @@ export function walletAvailable(): boolean {
 let lastLookupLocked = false;
 
 /**
- * Upsert a secret for the given attrs in ONE D-Bus roundtrip: existing
- * matching items are deleted, then (when secret is non-empty) the new item
- * is created. An empty secret deletes only (best-effort, never prompts).
- * "locked" = the keyring exists but is locked (KWallet): the token must be
- * kept in the file fallback; "unreachable" = no keyring/D-Bus at all.
+ * Upsert a secret for the given attrs in ONE D-Bus roundtrip: the new item
+ * is created (with its secret) first, then the previously matched items are
+ * deleted — an interrupted upsert never destroys the keyring copy. An empty
+ * secret deletes only (best-effort, never prompts).
+ * `waitSec` is how long to wait for an interactive unlock when the
+ * keyring is locked while writing (default UNLOCK_WAIT_S for interactive
+ * callers such as login; pass 0 for non-interactive paths so they fall
+ * back to the file instantly). "locked" = the keyring exists but is
+ * locked (KWallet): the token must be kept in the file fallback;
+ * "unreachable" = no keyring/D-Bus at all.
  */
-export function walletUpsert(attrs: Record<string, string>, secret: string): WalletResult {
-  const r = call({ cmd: "upsert", attrs, secret });
+export function walletUpsert(attrs: Record<string, string>, secret: string, waitSec = UNLOCK_WAIT_S): WalletResult {
+  const r = call({ cmd: "upsert", attrs, secret, wait: waitSec }, Math.max(UPSERT_TIMEOUT_MS, (waitSec + 15) * 1000));
   if (!r) return "unreachable";
   if (r.ok) return "ok";
   if (r.locked) return "locked";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-git-auth",
-  "version": "1.1.1",
+  "version": "1.2.3",
   "description": "pi coding-agent extension: git auth for GitHub and GitLab: keyring-stored login tokens, account switching, transparent git auth, repo list/create with details overlay",
   "license": "MIT",
   "author": "Carlo Onofrio",

package/store.ts

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import type { Platform } from "./forge";
-import { STATE_DIR, walletAvailable, walletUpsert, walletLookup, walletAttrs } from "./keyring";
+import { STATE_DIR, walletAvailable, walletUpsert, walletLookup, walletAttrs, UNLOCK_WAIT_S } from "./keyring";
 
 /**
  * Credential persistence for pi-git-auth (multi-account, multi-service).
@@ -20,6 +20,15 @@ import { STATE_DIR, walletAvailable, walletUpsert, walletLookup, walletAttrs } f
  *
  * Migration is transparent: legacy plaintext or `enc:v1:` tokens are moved
  * into the keyring on first load (a `.bak` copy of the file is kept).
+ * This is also the self-heal: a token kept in the file after a locked
+ * wallet goes back to the keyring on the next load while it is reachable
+ * (load-time writes use wait=0, so a still-locked wallet never delays
+ * startup).
+ *
+ * If the keyring is locked on load, the token for `wallet:v1:` accounts
+ * is "" for this process but is retried (throttled, prompt-safe) via
+ * retryKeyringLoad() on the next status/git-gate hit, so it recovers
+ * automatically once the wallet unlocks.
  *
  * Env override: PI_GIT_AUTH_STORE = auto (default) | wallet | file
  *
@@ -73,6 +82,10 @@ let diskData: StoreData | null = null;
 let storedPlaintext: Record<string, string> = {};
 /** A `wallet:v1:` token could not be read on load (keyring locked/absent). */
 let keyringUnavailableAtLoad = false;
+/** Accounts with a `wallet:v1:` marker that failed to read on load. */
+let loadFailedKeys: string[] = [];
+let lastRetryAt = 0;
+const RETRY_THROTTLE_MS = 10_000;
 
 const ENC_PREFIX = "enc:v1:";
 const WALLET_PREFIX = "wallet:v1:";
@@ -178,8 +191,13 @@ function decryptToken(enc: string): string {
  * keyring writes (no prompts, no "repeated wallet access" warnings).
  * When the keyring is locked/unreachable the token is kept in the
  * encrypted file instead of leaving a dead `wallet:v1:` marker behind.
+ *
+ * `waitSec` = how long a keyring write may wait for an interactive
+ * wallet unlock. Interactive callers (login) pass UNLOCK_WAIT_S so the
+ * user can answer the KWallet prompt; load-time migration/repair passes
+ * 0 so a locked wallet never delays startup.
  */
-function persist(data: StoreData, forceStore = false): void {
+function persist(data: StoreData, forceStore = false, waitSec = 0): void {
   const mode = storeMode();
   const accounts: Record<string, AccountRecord> = {};
   const nowPlaintext: Record<string, string> = {};
@@ -189,7 +207,7 @@ function persist(data: StoreData, forceStore = false): void {
     let stored: string;
     if (changed && a.accessToken) {
       // Single keyring roundtrip (delete matching items + create).
-      const r = mode === "wallet" ? walletUpsert(recAttrs(a, k), a.accessToken) : null;
+      const r = mode === "wallet" ? walletUpsert(recAttrs(a, k), a.accessToken, waitSec) : null;
       stored = r === "ok" ? WALLET_PREFIX + k : encryptToken(a.accessToken);
     } else if (diskStored) {
       stored = diskStored; // unchanged: keep the existing marker/envelope
@@ -228,6 +246,7 @@ export function loadStore(): StoreData {
   // plaintext tokens that absorb decrypts into the same objects.
   diskData = raw.accounts && typeof raw.accounts === "object" ? JSON.parse(JSON.stringify(raw)) : null;
   keyringUnavailableAtLoad = false;
+  loadFailedKeys = [];
   const data: StoreData = { accounts: {} };
   let migrated = false;
 
@@ -237,9 +256,11 @@ export function loadStore(): StoreData {
       const got = walletLookup(recAttrs(rec, key));
       if (got === null) {
         // keyring locked/cleared: keep the marker on disk, run this
-        // process without the token, and flag it for the status output.
+        // process without the token, and flag it for the status output
+        // and for retryKeyringLoad().
         rec.accessToken = "";
         keyringUnavailableAtLoad = true;
+        loadFailedKeys.push(key);
       } else {
         rec.accessToken = got;
       }
@@ -292,8 +313,49 @@ export function loadStore(): StoreData {
   return cache;
 }
 
+/**
+ * Persist after an interactive change (login): keyring writes may wait
+ * up to UNLOCK_WAIT_S for the user to answer the wallet unlock prompt.
+ */
 export function saveStore(data: StoreData): void {
-  persist(data);
+  persist(data, false, UNLOCK_WAIT_S);
+}
+
+/**
+ * Lazy recovery for tokens that could not be read on load (keyring
+ * locked): retry the lookup, throttled. Prompt-safe — a lookup never
+ * touches a locked collection, so this cannot stack unlock prompts.
+ * No-op once nothing is pending. Call it from hot paths (git gate,
+ * /auth status) so the token recovers as soon as the wallet unlocks.
+ */
+export function retryKeyringLoad(): void {
+  if (loadFailedKeys.length === 0) return;
+  const now = Date.now();
+  if (now - lastRetryAt < RETRY_THROTTLE_MS) return;
+  lastRetryAt = now;
+  const data = cache;
+  if (!data) return;
+  for (const k of [...loadFailedKeys]) {
+    const rec = data.accounts[k];
+    if (!rec || rec.accessToken) {
+      loadFailedKeys = loadFailedKeys.filter((x) => x !== k);
+      continue;
+    }
+    const got = walletLookup(recAttrs(rec, k));
+    if (got !== null) {
+      rec.accessToken = got;
+      storedPlaintext[k] = got;
+      loadFailedKeys = loadFailedKeys.filter((x) => x !== k);
+    }
+  }
+  if (loadFailedKeys.length === 0) keyringUnavailableAtLoad = false;
+}
+
+/** Where the active account's token actually lives on disk right now. */
+export function activeTokenStorage(): "keyring" | "file" {
+  const key = cache?.activeLogin;
+  const stored = key ? diskData?.accounts[key]?.accessToken : undefined;
+  return stored?.startsWith(WALLET_PREFIX) ? "keyring" : "file";
 }
 
 /** True when a `wallet:v1:` token could not be read on load (keyring