heedvane 0.0.0-stage → 0.1.0

package/dist/backend/credentials.js

@@ -0,0 +1,76 @@
+/**
+ * How this machine calls Heedvane. A developer signs in with `npx heedvane login` (browser OAuth,
+ * src/backend/login.ts); CI and headless machines use an organization API key (`hv_…`) saved with
+ * `npx heedvane auth org` in `<root>/credentials.json`, mode 0600, kept apart from heed.yaml (a file
+ * people share). A machine uses one of them: the login when there is one, else the key.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { isRecord, sha256Hex } from "../guards.js";
+import { loginTokenFor, readLogin } from "./login.js";
+export function credentialsPath(root) {
+    return join(root, "credentials.json");
+}
+/** The stored key; empty when none was saved yet. */
+async function readCredentials(root) {
+    let text;
+    try {
+        text = await readFile(credentialsPath(root), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        throw err;
+    }
+    const value = JSON.parse(text);
+    if (!isRecord(value))
+        throw new Error(`${credentialsPath(root)} is not a JSON object`);
+    const out = {};
+    for (const kind of ["org"]) {
+        if (typeof value[kind] === "string" && value[kind])
+            out[kind] = value[kind];
+    }
+    return out;
+}
+/** Store one key beside the others, 0600. */
+export async function saveCredential(root, kind, key) {
+    const next = { ...(await readCredentials(root)), [kind]: key };
+    await writeFileAtomic(credentialsPath(root), `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+}
+/** Heedvane at `url` when this machine has a sign-in or a key now, else null. The credential is read again on every call. */
+export async function backendAt(root, url, options = {}) {
+    if ((await signInIdentity(root, url)) === null)
+        return null;
+    return {
+        url,
+        identity: () => signInIdentity(root, url),
+        credential: () => credentialAt(root, url, options),
+    };
+}
+/**
+ * The current sign-in's identity: the saved login's organization (else its client) at `url`, else the
+ * saved key's fingerprint; null with neither, or with a login or key file that cannot be read. Read
+ * now, so a login to another organization changes it at once, also for a listener started with a key.
+ */
+export async function signInIdentity(root, url) {
+    return (await currentSignIn(root, url)).identity;
+}
+/** One read of the current sign-in (the login, else the key) and the identity that names it. */
+async function currentSignIn(root, url) {
+    const login = await readLogin(root).catch(() => undefined);
+    if (login === undefined)
+        return { identity: null }; // unreadable: no sign-in to name, nothing is sent
+    if (login !== null) {
+        return login.url === url ? { identity: `${url}|login|${login.organizationId ?? `client:${login.clientId}`}`, login } : { identity: null };
+    }
+    const { org } = await readCredentials(root).catch(() => ({}));
+    return org === undefined ? { identity: null } : { identity: `${url}|key|${sha256Hex(org).slice(0, 16)}`, key: org };
+}
+/** The bearer and the identity of one and the same read of the sign-in. */
+async function credentialAt(root, url, options) {
+    const { identity, login, key } = await currentSignIn(root, url);
+    if (key !== undefined)
+        return { identity, bearer: key };
+    return { identity, bearer: login === undefined ? null : await loginTokenFor(root, login, options) };
+}

package/dist/backend/login.d.ts

@@ -0,0 +1,33 @@
+export interface LoginTokens {
+    url: string;
+    clientId: string;
+    accessToken: string;
+    refreshToken: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+    /** The organization chosen on the consent page (the token's organization claim), when present. */
+    organizationId?: string;
+}
+/** How a login reaches the person: where to send the browser, and progress lines. */
+export interface LoginUi {
+    openBrowser: (url: string) => void;
+    out: (line: string) => void;
+}
+export declare function readLogin(root: string): Promise<LoginTokens | null>;
+/** The lock directory that serializes writes of `login.json` across processes. */
+export declare function loginLockPath(root: string): string;
+/** Sign in through the browser and save the tokens; resolves with the saved login. */
+export declare function login(root: string, url: string, ui: LoginUi): Promise<LoginTokens>;
+export interface LoginTokenOptions {
+    /**
+     * Wait for a refresh (commands). The listener does not: a hook never waits on it, so an expiring
+     * token is used while it lasts, and an expired one means no call until the background refresh lands.
+     */
+    wait?: boolean;
+    /** Where a failed refresh is said, once per backoff. */
+    log?: (message: string) => void;
+}
+/** A current access token for `url`, refreshed before it expires; null without a usable login. */
+export declare function loginToken(root: string, url: string, options?: LoginTokenOptions): Promise<string | null>;
+/** {@link loginToken} for a login the caller has already read, so its identity and token are one snapshot. */
+export declare function loginTokenFor(root: string, saved: LoginTokens, options?: LoginTokenOptions): Promise<string | null>;

package/dist/backend/login.js

@@ -0,0 +1,265 @@
+/**
+ * `npx heedvane login`: the developer signs in to Heedvane in the browser through the same OAuth server
+ * the Heedvane MCP uses (authorization code with PKCE S256, a dynamically registered public client and
+ * a loopback redirect, RFC 8252), and picks the organization on Heedvane's consent page. The tokens are
+ * kept in `<root>/login.json`, mode 0600, and refreshed before they expire. Refresh tokens rotate, so
+ * every refresh saves the new one, and one listener refreshes at a time.
+ *
+ * The access token is a JWT for the resource `<heedvane.url>/api/mcp`, bound to one organization. The
+ * `/api/agent` routes accept it once Heedvane verifies MCP grants there; until then they answer 401,
+ * which `login` and the listener report. While signed in, a saved organization key is not used (src/backend/credentials.ts).
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, readFile, rmdir, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import writeFileAtomic from "write-file-atomic";
+import { errorMessage, isRecord } from "../guards.js";
+const ORGANIZATION_CLAIM = "https://heedvane.com/mcp/organization";
+/** A token this close to expiry is refreshed first. */
+const REFRESH_MARGIN_MS = 60_000;
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+const REQUEST_TIMEOUT_MS = 15_000;
+function loginPath(root) {
+    return join(root, "login.json");
+}
+export async function readLogin(root) {
+    let text;
+    try {
+        text = await readFile(loginPath(root), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const value = JSON.parse(text);
+    if (!isRecord(value) || typeof value["accessToken"] !== "string" || typeof value["refreshToken"] !== "string") {
+        throw new Error(`${loginPath(root)} is not a saved login: run npx heedvane login again`);
+    }
+    return value;
+}
+async function saveLogin(root, tokens) {
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    await writeFileAtomic(loginPath(root), `${JSON.stringify(tokens, null, 2)}\n`, { mode: 0o600 });
+}
+/** The lock directory that serializes writes of `login.json` across processes. */
+export function loginLockPath(root) {
+    return join(root, "login.lock");
+}
+const LOGIN_LOCK_STALE_MS = 10_000;
+const LOGIN_LOCK_WAIT_MS = 5_000;
+const LOGIN_LOCK_POLL_MS = 25;
+/**
+ * Run `work` holding the login lock (a directory, created atomically). A login in one process and a
+ * refresh in another both write `login.json`; the refresh compares what it read against what is there
+ * and writes, and the login writes, so neither may land between the other's compare and write. A lock
+ * older than 10 s was left by a crashed process and is taken over. shortcut: two processes reclaiming
+ * the same stale lock in the same instant can both proceed, which needs a crash plus that coincidence;
+ * upgrade to a lock library if it is ever seen.
+ */
+async function withLoginLock(root, work) {
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const lock = loginLockPath(root);
+    const giveUpAt = Date.now() + LOGIN_LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            await mkdir(lock);
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            const held = await stat(lock).catch(() => null);
+            if (held !== null && Date.now() - held.mtimeMs > LOGIN_LOCK_STALE_MS)
+                await rmdir(lock).catch(() => undefined);
+            else if (Date.now() > giveUpAt)
+                throw new Error(`${lock} is held by another heedvane-hook process; try again, or remove it if no heedvane-hook command is running`, { cause: err });
+            else
+                await sleep(LOGIN_LOCK_POLL_MS);
+        }
+    }
+    try {
+        return await work();
+    }
+    finally {
+        await rmdir(lock).catch(() => undefined);
+    }
+}
+/** Sign in through the browser and save the tokens; resolves with the saved login. */
+export async function login(root, url, ui) {
+    const server = await authorizationServer(url);
+    const callback = await loopbackCallback();
+    try {
+        const redirectUri = `http://127.0.0.1:${callback.port}/callback`;
+        const clientId = await registerClient(server.registration, redirectUri);
+        const verifier = base64Url(randomBytes(32));
+        const state = base64Url(randomBytes(16));
+        const authorize = new URL(server.authorization);
+        authorize.search = new URLSearchParams({
+            response_type: "code",
+            client_id: clientId,
+            redirect_uri: redirectUri,
+            scope: "offline_access",
+            code_challenge: base64Url(createHash("sha256").update(verifier).digest()),
+            code_challenge_method: "S256",
+            state,
+            resource: resourceOf(url),
+        }).toString();
+        ui.out(`  Sign in to Heedvane in your browser. If it does not open, visit:\n    ${authorize.toString()}`);
+        ui.openBrowser(authorize.toString());
+        const code = await callback.code(state);
+        const answer = await tokenRequest(server.token, { grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: clientId, code_verifier: verifier, resource: resourceOf(url) });
+        const tokens = { ...answer, url, clientId };
+        await withLoginLock(root, () => saveLogin(root, tokens));
+        return tokens;
+    }
+    finally {
+        callback.server.close();
+    }
+}
+// One refresh at a time per process: a second refresh with the same (rotated, now revoked) refresh
+// token would fail and could end the grant.
+const refreshing = new Map();
+/** Per heed root, until when a failed refresh is not retried. */
+const refreshFailedUntil = new Map();
+const REFRESH_BACKOFF_MS = 5 * 60_000;
+/** A current access token for `url`, refreshed before it expires; null without a usable login. */
+export async function loginToken(root, url, options = {}) {
+    const saved = await readLogin(root).catch(() => null);
+    return saved === null || saved.url !== url ? null : loginTokenFor(root, saved, options);
+}
+/** {@link loginToken} for a login the caller has already read, so its identity and token are one snapshot. */
+export async function loginTokenFor(root, saved, options = {}) {
+    if (saved.expiresAt - REFRESH_MARGIN_MS > Date.now())
+        return saved.accessToken;
+    const refreshed = refreshOnce(root, saved, options.log);
+    if (options.wait !== false)
+        return refreshed;
+    return saved.expiresAt > Date.now() ? saved.accessToken : null;
+}
+function refreshOnce(root, saved, log) {
+    if ((refreshFailedUntil.get(root) ?? 0) > Date.now())
+        return Promise.resolve(null);
+    let pending = refreshing.get(root);
+    if (pending === undefined) {
+        pending = refresh(root, saved, log).finally(() => refreshing.delete(root));
+        refreshing.set(root, pending);
+    }
+    return pending;
+}
+async function refresh(root, saved, log) {
+    try {
+        const server = await authorizationServer(saved.url);
+        const answer = await tokenRequest(server.token, { grant_type: "refresh_token", refresh_token: saved.refreshToken, client_id: saved.clientId, resource: resourceOf(saved.url) });
+        // A login to another organization while this refresh ran must not be reverted to the old one: the
+        // compare and the write happen together under the lock a login's write also takes.
+        const tokens = await withLoginLock(root, async () => {
+            const current = await readLogin(root).catch(() => null);
+            if (current === null || current.refreshToken !== saved.refreshToken)
+                return null;
+            const refreshed = { ...saved, ...answer };
+            await saveLogin(root, refreshed);
+            return refreshed;
+        });
+        if (tokens === null)
+            return null;
+        refreshFailedUntil.delete(root);
+        return tokens.accessToken;
+    }
+    catch (err) {
+        // Expired or revoked, or Heedvane unreachable: no call carries the login until a later refresh or login.
+        refreshFailedUntil.set(root, Date.now() + REFRESH_BACKOFF_MS);
+        log?.(`[heedvane] could not refresh the sign-in (${errorMessage(err)}); retried in 5 minutes. If it keeps failing, run npx heedvane login`);
+        return null;
+    }
+}
+function resourceOf(url) {
+    return `${url}/api/mcp`;
+}
+async function authorizationServer(url) {
+    const metadata = await getJson(`${url}/.well-known/oauth-authorization-server`);
+    const field = (name) => {
+        const value = metadata[name];
+        if (typeof value !== "string")
+            throw new Error(`Heedvane's OAuth metadata has no ${name}`);
+        return value;
+    };
+    return { authorization: field("authorization_endpoint"), token: field("token_endpoint"), registration: field("registration_endpoint") };
+}
+async function registerClient(registration, redirectUri) {
+    const answer = await postJson(registration, {
+        client_name: "heedvane-hooks",
+        redirect_uris: [redirectUri],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
+    });
+    if (typeof answer["client_id"] !== "string")
+        throw new Error("Heedvane did not register the login client");
+    return answer["client_id"];
+}
+async function tokenRequest(token, form) {
+    const response = await fetch(token, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(form), signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    const json = await response.json().catch(() => null);
+    if (!response.ok || !isRecord(json) || typeof json["access_token"] !== "string" || typeof json["refresh_token"] !== "string") {
+        throw new Error(`Heedvane refused the sign-in (${response.status}): ${JSON.stringify(json)}`);
+    }
+    const expiresIn = typeof json["expires_in"] === "number" ? json["expires_in"] : 3600;
+    const organizationId = organizationClaim(json["access_token"]);
+    return { accessToken: json["access_token"], refreshToken: json["refresh_token"], expiresAt: Date.now() + expiresIn * 1000, ...(organizationId === undefined ? {} : { organizationId }) };
+}
+/** The organization claim of a JWT access token, read without verifying it (Heedvane verifies). */
+function organizationClaim(jwt) {
+    try {
+        const claims = JSON.parse(Buffer.from(jwt.split(".")[1] ?? "", "base64url").toString("utf8"));
+        return isRecord(claims) && typeof claims[ORGANIZATION_CLAIM] === "string" ? claims[ORGANIZATION_CLAIM] : undefined;
+    }
+    catch {
+        return undefined; // not a JWT: the token still works, the organization is just not shown
+    }
+}
+async function getJson(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    const json = await response.json();
+    if (!response.ok || !isRecord(json))
+        throw new Error(`${url} answered ${response.status}`);
+    return json;
+}
+async function postJson(url, body) {
+    const response = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    const json = await response.json().catch(() => null);
+    if (!response.ok || !isRecord(json))
+        throw new Error(`${url} answered ${response.status}: ${JSON.stringify(json)}`);
+    return json;
+}
+function base64Url(bytes) {
+    return bytes.toString("base64url");
+}
+/** A one-shot loopback server for the browser's redirect back with the authorization code. */
+async function loopbackCallback() {
+    let deliver = () => { };
+    const arrived = new Promise((resolve) => (deliver = resolve));
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (url.pathname !== "/callback")
+            return void res.writeHead(404).end();
+        res.writeHead(200, { "content-type": "text/plain; charset=utf-8" }).end("Signed in to Heedvane. You can close this tab.");
+        deliver(url);
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    const port = typeof address === "object" && address !== null ? address.port : 0;
+    const code = async (state) => {
+        const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error("no sign-in within five minutes")), LOGIN_TIMEOUT_MS).unref());
+        const url = await Promise.race([arrived, timeout]);
+        if (url.searchParams.get("state") !== state)
+            throw new Error("the sign-in answer did not match this login (state)");
+        const value = url.searchParams.get("code");
+        if (value === null)
+            throw new Error(`sign-in was not completed: ${url.searchParams.get("error_description") ?? url.searchParams.get("error") ?? "no code"}`);
+        return value;
+    };
+    return { server, port, code };
+}

package/dist/backend/repo-remote.d.ts

@@ -0,0 +1,15 @@
+/** The origin URL for `cwd` without credentials, or "" when it is not a git checkout (cached per cwd). */
+export declare function repoRemote(cwd: string): Promise<string>;
+/**
+ * The absolute top-level folder of the checkout a session works in (`git rev-parse --show-toplevel`),
+ * or "" outside one; resolved once per session and working folder, so session-less events (all filed
+ * under one placeholder session) never share another folder's root.
+ */
+export declare function sessionRepoRoot(session: string, cwd: string): Promise<string>;
+export declare function withoutCredentials(remote: string): string;
+/**
+ * The repository's full path from an origin URL (`owner/name`, or `group/sub/name` for nested groups),
+ * the form the steering endpoint's `repository` takes; "" when it has none. Reads https, `ssh://` and
+ * the scp-like `user@host:path` form, like ingestion's `normalizedRepositoryOrigin`.
+ */
+export declare function repositoryName(remote: string): string;

package/dist/backend/repo-remote.js

@@ -0,0 +1,61 @@
+/**
+ * Which repository an event came from, as its git `origin` URL, so Heedvane can map a developer's
+ * checkout to a connected repository. Credentials in an https URL (`https://user:token@host/…`) never
+ * leave the machine.
+ */
+import { execFile } from "node:child_process";
+const cache = new Map();
+/** The origin URL for `cwd` without credentials, or "" when it is not a git checkout (cached per cwd). */
+export function repoRemote(cwd) {
+    let remote = cache.get(cwd);
+    if (remote === undefined) {
+        remote = readOrigin(cwd).then(withoutCredentials);
+        cache.set(cwd, remote);
+    }
+    return remote;
+}
+function readOrigin(cwd) {
+    return git(cwd, ["remote", "get-url", "origin"]);
+}
+const roots = new Map();
+/**
+ * The absolute top-level folder of the checkout a session works in (`git rev-parse --show-toplevel`),
+ * or "" outside one; resolved once per session and working folder, so session-less events (all filed
+ * under one placeholder session) never share another folder's root.
+ */
+export function sessionRepoRoot(session, cwd) {
+    const key = JSON.stringify([session, cwd]);
+    let root = roots.get(key);
+    if (root === undefined) {
+        root = git(cwd, ["rev-parse", "--show-toplevel"]);
+        roots.set(key, root);
+    }
+    return root;
+}
+function git(cwd, args) {
+    return new Promise((resolve) => {
+        execFile("git", ["-C", cwd, ...args], { timeout: 1000 }, (err, stdout) => {
+            resolve(err ? "" : stdout.trim()); // not a repository, no origin, or no git
+        });
+    });
+}
+export function withoutCredentials(remote) {
+    if (!URL.canParse(remote) || !remote.includes("://"))
+        return remote; // scp-style git@host:owner/name
+    const url = new URL(remote);
+    url.username = "";
+    url.password = "";
+    return url.toString();
+}
+/**
+ * The repository's full path from an origin URL (`owner/name`, or `group/sub/name` for nested groups),
+ * the form the steering endpoint's `repository` takes; "" when it has none. Reads https, `ssh://` and
+ * the scp-like `user@host:path` form, like ingestion's `normalizedRepositoryOrigin`.
+ */
+export function repositoryName(remote) {
+    const trimmed = remote.trim();
+    const colon = trimmed.indexOf(":");
+    const url = URL.parse(trimmed.includes("://") || colon <= 0 ? trimmed : `ssh://${trimmed.slice(0, colon)}/${trimmed.slice(colon + 1)}`);
+    const path = url?.pathname.replace(/\/+$/, "").replace(/\.git$/i, "").replace(/^\/+/, "") ?? "";
+    return path.includes("/") ? path : "";
+}

package/dist/backend/sign-in-change.d.ts

@@ -0,0 +1,12 @@
+/** The file that records whose sign-in the spool, instructions and caches on this machine belong to. */
+export declare function signedInAsPath(root: string): string;
+/**
+ * Make the leftovers match the current sign-in: when the recorded sign-in is not the current one (or none
+ * was recorded), set them aside and record the current one. Returns the current identity; with no sign-in
+ * nothing moves, so the leftovers wait for whoever signs in next.
+ */
+export declare function reconcileSignIn(root: string, url: string): Promise<string | null>;
+/** Run `change` (a command that may sign in as someone else), then reconcile the leftovers with the sign-in it left. */
+export declare function withSignInChange<T>(root: string, url: string, change: () => Promise<T>): Promise<T>;
+/** The pre-rendered instructions and the cached policy of an earlier sign-in; the next sync writes the current one's. */
+export declare function discardSteeringCaches(root: string): Promise<void>;

package/dist/backend/sign-in-change.js

@@ -0,0 +1,72 @@
+/**
+ * What a change of sign-in leaves behind. Everything this machine holds for Heedvane belongs to the
+ * sign-in that produced it, and a hook event carries no sign-in of its own, so when `login` or
+ * `auth org` leaves a different sign-in than it found, what the earlier one left is set aside, never
+ * sent or injected under the new one:
+ *
+ * - the dispatcher's spooled events (`spool/pane-*.jsonl`), which the listener would replay under
+ *   whatever sign-in is current: moved to `spool/other-sign-in/`;
+ * - the pre-rendered organization instructions the dispatcher prints when the listener is down
+ *   (`steering/instructions-*.json`), and the cached steering policy: removed (the next sync writes
+ *   the new organization's).
+ *
+ * The sign-in the leftovers belong to is recorded in `signed-in-as`, so the comparison is against what was
+ * left, not against what one command saw: the listener makes it at its start, before it replays the spool,
+ * and so does every command that changes the sign-in, including a plain deletion of `login.json`.
+ *
+ * The outbox and the caches that carry their sign-in stay with the identity they were stamped with, and
+ * apply only under exactly that identity (src/listener/forward.ts, src/skills/approved.ts,
+ * src/steering/rules.ts).
+ */
+import { mkdir, readdir, readFile, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { signInIdentity } from "./credentials.js";
+import { isPaneSpoolFile, spoolDir } from "../listener/spool.js";
+import { steeringPolicyPath } from "../steering/rules.js";
+/** The file that records whose sign-in the spool, instructions and caches on this machine belong to. */
+export function signedInAsPath(root) {
+    return join(root, "signed-in-as");
+}
+/**
+ * Make the leftovers match the current sign-in: when the recorded sign-in is not the current one (or none
+ * was recorded), set them aside and record the current one. Returns the current identity; with no sign-in
+ * nothing moves, so the leftovers wait for whoever signs in next.
+ */
+export async function reconcileSignIn(root, url) {
+    const current = await signInIdentity(root, url);
+    if (current === null)
+        return null;
+    const recorded = await readFile(signedInAsPath(root), "utf8").then((text) => text.trim(), (err) => {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    });
+    if (recorded !== current) {
+        await setAsideSignInLeftovers(root);
+        await writeFileAtomic(signedInAsPath(root), `${current}\n`, { mode: 0o600 });
+    }
+    return current;
+}
+/** Run `change` (a command that may sign in as someone else), then reconcile the leftovers with the sign-in it left. */
+export async function withSignInChange(root, url, change) {
+    const result = await change();
+    await reconcileSignIn(root, url);
+    return result;
+}
+async function setAsideSignInLeftovers(root) {
+    const spool = spoolDir(root);
+    const names = (await readdir(spool).catch(() => [])).filter(isPaneSpoolFile);
+    if (names.length > 0)
+        await mkdir(join(spool, "other-sign-in"), { recursive: true, mode: 0o700 });
+    for (const name of names)
+        await rename(join(spool, name), join(spool, "other-sign-in", `${Date.now()}-${name}`));
+    await discardSteeringCaches(root);
+}
+/** The pre-rendered instructions and the cached policy of an earlier sign-in; the next sync writes the current one's. */
+export async function discardSteeringCaches(root) {
+    const steering = join(root, "steering");
+    for (const name of (await readdir(steering).catch(() => [])).filter((entry) => entry.startsWith("instructions-")))
+        await unlink(join(steering, name)).catch(() => undefined);
+    await unlink(steeringPolicyPath(root)).catch(() => undefined);
+}

package/dist/best-effort.d.ts

@@ -0,0 +1,4 @@
+/** Delete `path` if it exists; ignore every failure (best-effort cleanup). */
+export declare function unlinkOptional(path: string): Promise<void>;
+/** Write `content` to `path` with `mode`, ignoring every failure (best-effort restore). */
+export declare function writeFileOptional(path: string, content: string | Buffer, mode: number): Promise<void>;

package/dist/best-effort.js

@@ -0,0 +1,25 @@
+/**
+ * Best-effort filesystem cleanup used on failure/cleanup paths: the operation's
+ * failure is swallowed by design because the caller has already decided what to
+ * report (or there is nothing left to report on). Each helper is a bare
+ * try/catch so the intent is visible and greppable in one place.
+ */
+import { unlink, writeFile } from "node:fs/promises";
+/** Delete `path` if it exists; ignore every failure (best-effort cleanup). */
+export async function unlinkOptional(path) {
+    try {
+        await unlink(path);
+    }
+    catch {
+        return; // best-effort: absent or unremovable is the same outcome here
+    }
+}
+/** Write `content` to `path` with `mode`, ignoring every failure (best-effort restore). */
+export async function writeFileOptional(path, content, mode) {
+    try {
+        await writeFile(path, content, { mode });
+    }
+    catch {
+        return; // best-effort: the caller reports the primary failure
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+export interface MainOptions {
+    /** Env override (tests inject HEED_HOME fixtures). Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    /** Output sink; defaults to console.log. */
+    write?: (line: string) => void;
+    /** Stdin as text; defaults to the process stdin (tests inject a key for `auth`). */
+    readStdin?: () => Promise<string>;
+    /** Opens the sign-in page; defaults to the system browser (tests follow the URL themselves). */
+    openBrowser?: (url: string) => void;
+    /** The working folder `memory` reads the repository from; defaults to the process's. */
+    cwd?: string;
+    /** May init/setup start a browser sign-in? Defaults to whether a person is at the terminal. */
+    interactive?: boolean;
+}
+declare function main(argv: string[], opts?: MainOptions): Promise<number>;
+/** All of stdin as text (where `auth` reads its key). */
+/** Open `url` in the system browser; the URL is printed too, so a failure here only costs a click. */
+/**
+ * The command that opens `url` in the default browser. Windows goes through rundll32, not `cmd /c start`:
+ * cmd would cut the sign-in URL at its first `&`.
+ */
+export declare function browserOpener(platform: NodeJS.Platform, url: string): [string, string[]];
+export { main };