balladeer 1.0.3 → 1.0.4

package/README.md

@@ -41,6 +41,15 @@ already enrolled it connects this machine and writes its MCP configuration; when
 leaves the checkout unchanged and Balladeer shows that enforcement tracking is unavailable until an
 administrator connects a repository.
 
+## If setup cannot save its local connection
+
+Setup needs access to its private credential folder, normally `~/.config/balladeer`. If your
+terminal or coding agent blocks that access, allow the command to access the private folder named in
+the error, then repeat the same setup command with the same flags. Keep your existing saved
+credentials; do not delete the store or move it into your repository. Setup checks local write
+access before requesting a new browser pairing and reports a credential-store error separately from
+a connection failure.
+
 ## Requirements
 
 - Node 22 or newer. The command uses Node builtins and the pinned `@iarna/toml` parser to preserve

package/dist/cli.js

@@ -60,6 +60,10 @@ const USAGE = `balladeer ${CLI_VERSION}
       skipping quietly; --no-claude-desktop leaves that file alone entirely.
       Quit and reopen the app afterwards: it reads its configuration at startup.
 
+      If setup cannot access its private credential folder, allow this command
+      to access the folder named in the error, then repeat the same setup command.
+      Keep existing saved credentials; do not delete the store to retry.
+
   ${CLI_INVOCATION} repositories [--json] [--control-plane <url>]
       List the repositories this machine's GitHub account can see, marking the
       one you are standing in and the ones Balladeer already has.

package/dist/commands/setup.js

@@ -15,7 +15,7 @@ import { findLegacyInstall, legacyMessage } from "../legacy.js";
 import { formatInstant } from "../local-time.js";
 import { checkoutEntryPath, commandLine, runningFromRegistryInstall } from "../release.js";
 import { hostHint, repositoryHint } from "../repository.js";
-import { StoreError, credentialsPath, dropPendingPairing, findPendingPairing, findSession, putAgent, putPendingPairing, putSession, readCredentials, writeCredentials, } from "../store.js";
+import { StoreError, assertStoreWritable, credentialsPath, dropPendingPairing, findPendingPairing, findSession, putAgent, putPendingPairing, putSession, readCredentials, writeCredentials, } from "../store.js";
 import { CLI_VERSION, DELEGATED_SCOPES, } from "../wire.js";
 import { explainText } from "./explain.js";
 import { probeAgentConnection } from "./mcp.js";
@@ -168,10 +168,11 @@ function pendingLines(pending, repository, host, waiting, approvalUri) {
         ...JOIN_OR_CREATE.split("\n").map((line) => (line.length === 0 ? "" : `  ${line}`)),
     ];
 }
-function storeSession(credentials, controlPlane, token, session) {
+function storeSession(credentials, controlPlane, token, session, workspaceChoice) {
     return putSession(dropPendingPairing(credentials, controlPlane), {
         controlPlane,
         sessionId: session.sessionId,
+        ...(workspaceChoice?.startsWith("create:") ? { workspaceChoice } : {}),
         token,
         workspaceId: session.workspaceId,
         workspaceName: session.workspaceName,
@@ -290,23 +291,29 @@ export async function runSetup(options) {
     catch (error) {
         return storeFailure(options, error);
     }
-    // Workspace choice is explicit. Preserve all agent connections and other
-    // origins; persist the session replacement only when a new pairing starts.
+    // A completed create intent resumes only its own authenticated session. The
+    // name is local intent, never a lookup or grant of workspace authority. An
+    // explicit chooser always starts a switch. Keep the old session until the
+    // new pairing is claimed, so a failed start or claim loses no credentials.
     const workspaceChoice = options.createWorkspace !== undefined
         ? `create:${carriedName}`
         : options.chooseWorkspace === true
             ? "choose"
             : undefined;
+    const previousSession = findSession(credentials, controlPlane);
+    const freshChoice = workspaceChoice !== undefined &&
+        (options.chooseWorkspace === true || previousSession?.workspaceChoice !== workspaceChoice);
     if (workspaceChoice !== undefined) {
         credentials = {
             ...credentials,
-            sessions: credentials.sessions.filter((entry) => entry.controlPlane !== controlPlane),
             pendingPairings: credentials.pendingPairings.filter((entry) => entry.controlPlane !== controlPlane || entry.workspaceChoice === workspaceChoice),
         };
+    }
+    if (freshChoice) {
         say(options, "Choose the workspace in the new browser pairing. Existing agent connections remain saved.");
     }
     // A still-valid session carries straight on to the steps that need it.
-    const stored = findSession(credentials, controlPlane);
+    const stored = freshChoice ? undefined : previousSession;
     if (stored && Date.parse(stored.expiresAt) > now().getTime()) {
         try {
             const answer = await request(controlPlane, {
@@ -378,6 +385,9 @@ export async function runSetup(options) {
     }
     let started;
     try {
+        // An unsaved claim secret cannot be recovered by retrying the browser link.
+        // Check local access before creating an unapproved remote pairing.
+        assertStoreWritable(options.environment);
         const { verifier, digest } = newVerifier();
         started = await request(controlPlane, {
             method: "POST",
@@ -450,7 +460,7 @@ async function claimOnce(options, credentials, pending) {
         if (answer.status === "pending") {
             return { kind: "pending", pollIntervalSeconds: answer.pollIntervalSeconds };
         }
-        const updated = storeSession(credentials, options.controlPlane, answer.token, answer.session);
+        const updated = storeSession(credentials, options.controlPlane, answer.token, answer.session, pending.workspaceChoice);
         writeCredentials(updated, options.environment);
         reportPaired(options, answer.session);
         const session = findSession(updated, options.controlPlane);

package/dist/store.d.ts

@@ -15,6 +15,8 @@ export type PendingPairing = Readonly<{
     workspaceChoice?: string;
 }>;
 export type StoredSession = Readonly<{
+    /** Claimed local create intent, not workspace identity or server authority. */
+    workspaceChoice?: string;
     controlPlane: string;
     sessionId: string;
     token: string;
@@ -76,6 +78,8 @@ export declare function credentialsPath(environment?: NodeJS.ProcessEnv): string
  */
 export declare function assertSafeStoreLocation(directory: string, environment?: NodeJS.ProcessEnv, cwd?: string): void;
 export declare function ensureStoreDirectory(environment?: NodeJS.ProcessEnv): string;
+/** Check actual write permission before requesting a pairing whose secret must be saved. */
+export declare function assertStoreWritable(environment?: NodeJS.ProcessEnv): void;
 export declare function readCredentials(environment?: NodeJS.ProcessEnv): Credentials;
 /**
  * Atomic, and never through a path an attacker could have pre-planted: the

package/dist/store.js

@@ -86,12 +86,38 @@ function assertPrivate(path, kind) {
         throw new StoreError("credential_store_unsafe", `${path} is readable by other users. Run: chmod ${kind === "directory" ? "700" : "600"} ${path}`);
     }
 }
+function storeAccessError(error, path, operation) {
+    if (error instanceof StoreError)
+        return error;
+    const code = error?.code;
+    const permissionDenied = code === "EACCES" || code === "EPERM";
+    return new StoreError(operation === "read" ? "credential_store_unreadable" : "credential_store_unwritable", permissionDenied
+        ? `Balladeer cannot ${operation} its local credential store at ${path}. Allow this command to access that private folder in your terminal or coding agent, then rerun the same command. Existing saved credentials were not replaced.`
+        : `Balladeer could not ${operation} its local credential store at ${path} (${code ?? "filesystem error"}). Check that this location is a private, accessible directory, then retry. Existing saved credentials were not replaced.`, { cause: error });
+}
 export function ensureStoreDirectory(environment = process.env) {
     const directory = configHome(environment);
-    assertSafeStoreLocation(directory, environment);
-    mkdirSync(directory, { recursive: true, mode: 0o700 });
-    assertPrivate(directory, "directory");
-    return directory;
+    try {
+        assertSafeStoreLocation(directory, environment);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        assertPrivate(directory, "directory");
+        return directory;
+    }
+    catch (error) {
+        throw storeAccessError(error, directory, "write");
+    }
+}
+/** Check actual write permission before requesting a pairing whose secret must be saved. */
+export function assertStoreWritable(environment = process.env) {
+    const probe = `.write-check-${randomBytes(8).toString("hex")}`;
+    const path = join(configHome(environment), probe);
+    try {
+        writeStoreFile(probe, "", environment);
+        unlinkSync(path);
+    }
+    catch (error) {
+        throw storeAccessError(error, configHome(environment), "write");
+    }
 }
 export function readCredentials(environment = process.env) {
     const path = credentialsPath(environment);
@@ -101,9 +127,10 @@ export function readCredentials(environment = process.env) {
         raw = readFileSync(path, "utf8");
     }
     catch (error) {
-        if (error instanceof StoreError)
-            throw error;
-        return { ...EMPTY, pendingPairings: [], sessions: [], agents: [] };
+        if (error?.code === "ENOENT") {
+            return { ...EMPTY, pendingPairings: [], sessions: [], agents: [] };
+        }
+        throw storeAccessError(error, path, "read");
     }
     try {
         const parsed = JSON.parse(raw);
@@ -164,9 +191,7 @@ export function writeStoreFile(fileName, contents, environment = process.env) {
         catch {
             // The temporary file may never have been created.
         }
-        if (error instanceof StoreError)
-            throw error;
-        throw new StoreError("credential_store_unwritable", `Balladeer could not write ${path}: ${error instanceof Error ? error.message : "unknown reason"}`, { cause: error });
+        throw storeAccessError(error, path, "write");
     }
 }
 /** Origins, not URL strings, so `https://host/../` cannot alias a stored entry. */

package/dist/wire.d.ts

@@ -5,10 +5,10 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export declare const CLI_VERSION = "1.0.3";
+export declare const CLI_VERSION = "1.0.4";
 export declare const CLI_INVOCATION = "npx -y balladeer@latest";
 export declare const CLIENT_HEADER = "x-balladeer-client";
-export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.3";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.4";
 export declare const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
 export type DelegatedScope = "repository:enroll" | "agent:issue" | "ci:connect" | "workspace:invite" | "candidate:propose";
 export declare const DELEGATED_SCOPES: readonly DelegatedScope[];

package/dist/wire.js

@@ -5,7 +5,7 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export const CLI_VERSION = "1.0.3";
+export const CLI_VERSION = "1.0.4";
 export const CLI_INVOCATION = "npx -y balladeer@latest";
 export const CLIENT_HEADER = "x-balladeer-client";
 export const CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "balladeer",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,