@bridge4dev/runner 0.22.1 → 0.26.0

package/dist/auth-relay.d.ts

@@ -39,11 +39,41 @@ export declare class AuthRelay {
     cancel(): void;
 }
 /**
- * Claude: the subscription token's expiry is recorded in the CLI's own
- * credentials file. The RUNNER reads it (its own host user's file) — the
- * agent itself is still denied this path by layer-1 policy.
+ * Claude: the subscription login is recorded in the CLI's own credentials file.
+ * The RUNNER reads it (its own host user's file) — the agent itself is still
+ * denied this path by layer-1 policy.
+ *
+ * `expiresAt` is NOT the login. It is the expiry of a short-lived access token
+ * (~8 hours on a live file), and next to it sits `refreshToken` with
+ * `refreshTokenExpiresAt` ~26 days out, which the CLI spends silently on its
+ * next run. Judging the login by `expiresAt` alone is why every server nobody
+ * had touched since the morning reported "login expired — re-login needed"
+ * over a login that was good for another three weeks (#121). Codex has carried
+ * exactly this guard since day one (`readCodexCredential`); Claude did not.
+ *
+ * Deliberately NOT asking the CLI. `claude auth status --json` looks like an
+ * arbiter and is not one: measured live (SDK binary 2.1.218), it answers
+ * `loggedIn: true` for a credential whose access token has expired AND which
+ * carries no refresh token at all — i.e. for a genuinely dead login. It never
+ * leaves the machine, so it cannot see a server-side revocation either. It
+ * would have cost a ~800 ms / ~300 MB subprocess per poll under `MemoryMax=2G`
+ * (gotcha #100) and echoed the account's e-mail and org name to every member of
+ * the organization, in exchange for no truth at all. A revoked login is caught
+ * instead by `noteAgentAuthFailure` below — from a real refusal, not a guess.
  */
 export declare function claudeAuthStatus(homedir?: string): Promise<AgentAuthStatus>;
+/** A session just failed to authenticate as this agent. */
+export declare function noteAgentAuthFailure(agent: RelayAgent): void;
+/** The agent just worked — whatever was wrong with the sign-in is not. */
+export declare function clearAgentAuthFailure(agent: RelayAgent): void;
+/**
+ * Is a refusal still being held against this agent?
+ *
+ * Exported so the wiring in `supervisor.ts` can be pinned by a test without
+ * shelling out to the agent CLIs: this predicate IS the mechanism the panel's
+ * demotion reads, and three unguarded lines were carrying it (QA-117 M6).
+ */
+export declare function agentAuthFailureActive(agent: RelayAgent): boolean;
 /**
  * Codex reports its own login state via an exit code (0 signed in / 1 not).
  * Probed against the RUNNER's home: the host user can be signed in while our

package/dist/auth-relay.js

@@ -92,6 +92,12 @@ export class AuthRelay {
             try {
                 if (code === 0 && adoptLoginResult(stagingCodexHomePath())) {
                     log.info('codex: device login completed — credential adopted');
+                    // The ONLY place a Codex sign-in can be reported as finished. Its
+                    // flow never sends `login_code` (device auth needs no paste-back),
+                    // so without this line a refusal we recorded earlier would keep the
+                    // panel demanding a re-login the user has just done — #121's own
+                    // complaint, reproduced on the other half of the panel (QA-117 H1).
+                    clearAgentAuthFailure('codex');
                 }
                 else {
                     discardStagingHome();
@@ -174,35 +180,192 @@ export class AuthRelay {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-// ─── Auth health probe ───────────────────────────────────────────────
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * A millisecond timestamp we are willing to hand to `new Date(...)`.
+ *
+ * The bound is not decoration: `new Date(1e21).toISOString()` throws
+ * `RangeError`, and thrown out of here it takes BOTH agents' verdicts down
+ * with it (they share one `Promise.all`) on every poll, forever, because only
+ * successes are cached (QA-117 M1).
+ */
+const MAX_TIMESTAMP_MS = 8.64e15;
+function asTimestamp(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return undefined;
+    return Math.abs(value) <= MAX_TIMESTAMP_MS ? value : undefined;
+}
 /**
- * Claude: the subscription token's expiry is recorded in the CLI's own
- * credentials file. The RUNNER reads it (its own host user's file) — the
- * agent itself is still denied this path by layer-1 policy.
+ * Claude: the subscription login is recorded in the CLI's own credentials file.
+ * The RUNNER reads it (its own host user's file) — the agent itself is still
+ * denied this path by layer-1 policy.
+ *
+ * `expiresAt` is NOT the login. It is the expiry of a short-lived access token
+ * (~8 hours on a live file), and next to it sits `refreshToken` with
+ * `refreshTokenExpiresAt` ~26 days out, which the CLI spends silently on its
+ * next run. Judging the login by `expiresAt` alone is why every server nobody
+ * had touched since the morning reported "login expired — re-login needed"
+ * over a login that was good for another three weeks (#121). Codex has carried
+ * exactly this guard since day one (`readCodexCredential`); Claude did not.
+ *
+ * Deliberately NOT asking the CLI. `claude auth status --json` looks like an
+ * arbiter and is not one: measured live (SDK binary 2.1.218), it answers
+ * `loggedIn: true` for a credential whose access token has expired AND which
+ * carries no refresh token at all — i.e. for a genuinely dead login. It never
+ * leaves the machine, so it cannot see a server-side revocation either. It
+ * would have cost a ~800 ms / ~300 MB subprocess per poll under `MemoryMax=2G`
+ * (gotcha #100) and echoed the account's e-mail and org name to every member of
+ * the organization, in exchange for no truth at all. A revoked login is caught
+ * instead by `noteAgentAuthFailure` below — from a real refusal, not a guess.
  */
 export async function claudeAuthStatus(homedir = os.homedir()) {
     if (process.env['CLAUDE_CODE_OAUTH_TOKEN']) {
         return { status: 'ok', detail: 'CLAUDE_CODE_OAUTH_TOKEN is configured' };
     }
     const file = path.join(homedir, '.claude', '.credentials.json');
+    let raw;
     try {
-        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
-        const oauth = parsed.claudeAiOauth;
-        if (!oauth)
-            return { status: 'missing', detail: 'No subscription login found' };
-        const expiresAt = oauth.expiresAt ? new Date(oauth.expiresAt).toISOString() : undefined;
-        if (oauth.expiresAt && oauth.expiresAt < Date.now()) {
-            return { status: 'expired', ...(expiresAt ? { expiresAt } : {}) };
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        // Never signed in here is a different answer from "we could not look".
+        // EACCES on somebody else's HOME used to read as "not signed in", which
+        // sends the user re-authenticating a credential that is sitting right
+        // there (the same mistake #121 is about, one layer down).
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+            return { status: 'missing', detail: 'No Claude login on this server' };
         }
+        // No `log.warn` here: this probe is on a 60-second timer since #121, and a
+        // machine with EACCES on that file would write the same line forever.
+        // `logVerdictChange` already reports the `unknown`, once, when it starts
+        // (QA-117 L5).
         return {
-            status: 'ok',
-            ...(expiresAt ? { expiresAt } : {}),
-            ...(oauth.subscriptionType ? { detail: `subscription ${oauth.subscriptionType}` } : {}),
+            status: 'unknown',
+            detail: `could not read the login on this server (${code ?? 'unknown error'})`,
         };
     }
+    let oauth;
+    try {
+        oauth = JSON.parse(raw).claudeAiOauth;
+    }
     catch {
-        return { status: 'missing', detail: 'No Claude login on this server' };
+        // Truncated or hand-edited file: the CLI cannot use it either, and signing
+        // in again is the fix — so say `missing` (which offers that button) rather
+        // than `unknown` (which offers nothing).
+        return { status: 'missing', detail: 'the stored login could not be read — sign in again' };
+    }
+    // A parseable file is not a credential. `{"claudeAiOauth":{}}` is what a
+    // partial write and a hand-edit both leave behind, and reading it as a
+    // healthy login puts a green dot and NO way out on the panel — «I cannot
+    // tell» turned into «all good», which is the rule this ticket exists to
+    // uphold, upside down (QA-117 M2).
+    if (!oauth || typeof oauth !== 'object' || Array.isArray(oauth)) {
+        return { status: 'missing', detail: 'the stored login could not be read — sign in again' };
+    }
+    const hasAccess = isNonEmptyString(oauth.accessToken);
+    const hasRefresh = isNonEmptyString(oauth.refreshToken);
+    const now = Date.now();
+    const accessExpiry = asTimestamp(oauth.expiresAt);
+    const refreshExpiry = asTimestamp(oauth.refreshTokenExpiresAt);
+    // Nothing recognisable in the blob at all — no token, not even a date. That
+    // is «never signed in here», and it must offer the button that fixes it.
+    if (!hasAccess && !hasRefresh && accessExpiry === undefined) {
+        return { status: 'missing', detail: 'No subscription login found' };
+    }
+    // A date we can read outranks the token beside it (the pre-#121 contract, and
+    // the reason a dated-but-token-less fixture still reads as expired); with no
+    // readable date, the presence of the token is all we have.
+    const accessLive = accessExpiry === undefined ? hasAccess : accessExpiry > now;
+    // No `refreshTokenExpiresAt` next to a refresh token means the CLI did not
+    // record one — that is not evidence of death, so we do not read it as death.
+    const refreshLive = hasRefresh && (refreshExpiry === undefined || refreshExpiry > now);
+    // Report the date this login actually dies on, not the one that moves every
+    // eight hours: a panel reading "token until <today>" is alarming and wrong.
+    // Only while the refresh token is the operative one, though — a live access
+    // token beside a dead refresh token dies on its OWN date. And when the CLI
+    // recorded no date for a live refresh token we say NOTHING: printing the
+    // access token's lapsed date beside the word «signed in» is the very screen
+    // this function's docblock promises not to draw (QA-117 M3).
+    const effectiveExpiry = refreshLive ? refreshExpiry : accessExpiry;
+    const expiresAt = effectiveExpiry === undefined ? undefined : new Date(effectiveExpiry).toISOString();
+    if (!accessLive && !refreshLive) {
+        return {
+            status: 'expired',
+            ...(expiresAt ? { expiresAt } : {}),
+            detail: 'the stored login has expired',
+        };
+    }
+    return {
+        status: 'ok',
+        ...(expiresAt ? { expiresAt } : {}),
+        // Only a plain string, and only a short one: this value is read off disk
+        // and printed in every member's panel.
+        ...(isNonEmptyString(oauth.subscriptionType)
+            ? { detail: `subscription ${oauth.subscriptionType.slice(0, 40)}` }
+            : {}),
+    };
+}
+// ─── What the agent actually experienced ─────────────────────────────
+//
+// The credentials file cannot tell us the provider revoked this login: the
+// refresh token still sits there, dated. The one authority on that is a real
+// refusal from a real run — so a session that failed to authenticate demotes
+// the file's verdict for a while, and any successful turn clears it again.
+//
+// Process memory on purpose: no protocol, no disk. The consequence is worth
+// naming — restarting the daemon forgets the refusal and the panel goes back
+// to trusting the file until the next session tries.
+const AUTH_FAILURE_TTL_MS = 15 * 60_000;
+const authFailures = new Map();
+/** A session just failed to authenticate as this agent. */
+export function noteAgentAuthFailure(agent) {
+    authFailures.set(agent, Date.now());
+    log.warn('auth-relay: agent sign-in refused during a session', { agent });
+}
+/** The agent just worked — whatever was wrong with the sign-in is not. */
+export function clearAgentAuthFailure(agent) {
+    if (authFailures.delete(agent)) {
+        log.info('auth-relay: agent sign-in is working again', { agent });
+    }
+}
+/**
+ * Is a refusal still being held against this agent?
+ *
+ * Exported so the wiring in `supervisor.ts` can be pinned by a test without
+ * shelling out to the agent CLIs: this predicate IS the mechanism the panel's
+ * demotion reads, and three unguarded lines were carrying it (QA-117 M6).
+ */
+export function agentAuthFailureActive(agent) {
+    return hasRecentAuthFailure(agent);
+}
+function hasRecentAuthFailure(agent) {
+    const at = authFailures.get(agent);
+    if (at === undefined)
+        return false;
+    if (Date.now() - at > AUTH_FAILURE_TTL_MS) {
+        authFailures.delete(agent);
+        return false;
     }
+    return true;
+}
+/** Last verdict we published per agent — logged only when it changes. */
+const lastVerdict = new Map();
+function logVerdictChange(agent, status) {
+    const previous = lastVerdict.get(agent);
+    if (previous === status.status)
+        return;
+    lastVerdict.set(agent, status.status);
+    // Without this line there is no way to confirm on a live server that the
+    // verdict changed — and no way to see it flapping (lesson from #103).
+    log.info('auth-relay: login verdict', {
+        agent,
+        from: previous ?? 'none',
+        to: status.status,
+        ...(status.expiresAt ? { expiresAt: status.expiresAt } : {}),
+    });
 }
 /**
  * Codex reports its own login state via an exit code (0 signed in / 1 not).
@@ -282,8 +445,28 @@ function readCodexCredential(homePath) {
         return null;
     }
 }
+/**
+ * A verdict read off disk, overruled by what a real session experienced.
+ *
+ * Only ever downgrades: a refusal we witnessed outranks a file that looks fine,
+ * and never the other way round — a file saying `expired` is not made `ok` by
+ * the absence of failures.
+ */
+function withObservedFailures(agent, status) {
+    if (status.status !== 'ok' || !hasRecentAuthFailure(agent))
+        return status;
+    return {
+        status: 'expired',
+        ...(status.expiresAt ? { expiresAt: status.expiresAt } : {}),
+        detail: 'the agent was refused with this sign-in — re-login needed',
+    };
+}
 export async function agentAuthStatuses() {
-    const [claude, codex] = await Promise.all([claudeAuthStatus(), codexAuthStatus()]);
+    const [claudeRaw, codexRaw] = await Promise.all([claudeAuthStatus(), codexAuthStatus()]);
+    const claude = withObservedFailures('claude', claudeRaw);
+    const codex = withObservedFailures('codex', codexRaw);
+    logVerdictChange('claude', claude);
+    logVerdictChange('codex', codex);
     return { claude, codex };
 }
 //# sourceMappingURL=auth-relay.js.map

package/dist/environment.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Everything that depends on WHICH USER the runner runs as.
+ *
+ * The install instructions offer a choice — root or a dedicated user — and both
+ * are legitimate. What is not legitimate is the way the second choice used to
+ * fail: silently, later, and in the agent's voice. A dedicated user typically
+ * owns none of the project directories, has an empty `$HOME` where the agent
+ * CLIs keep their login and settings, and reaches systemd only with
+ * `XDG_RUNTIME_DIR` set. Each of those produces a symptom that reads like a
+ * broken runner ("agent can't do anything", "not signed in", "service is fine"
+ * with exit code 0) while the real cause is a permission nobody was told about.
+ *
+ * This module turns each of them into a fact with a command next to it.
+ */
+export interface RunnerIdentity {
+    user: string;
+    uid: number;
+    gid: number;
+    home: string;
+    isRoot: boolean;
+}
+export declare function runnerIdentity(): RunnerIdentity;
+export interface PathAccess {
+    path: string;
+    exists: boolean;
+    isDirectory: boolean;
+    /** uid of the owner, or -1 when we could not stat it. */
+    ownerUid: number;
+    ownedByUs: boolean;
+    readable: boolean;
+    writable: boolean;
+    /**
+     * True when we could not even look — a directory ABOVE this one denies us
+     * traversal. Distinct from `!exists` on purpose: those are opposite answers
+     * to the person reading them («create it» vs «grant access»), and `statSync`
+     * reports both by throwing.
+     */
+    unreachable: boolean;
+}
+export declare function inspectPath(target: string): PathAccess;
+/**
+ * The first directory on this path the runner cannot enter.
+ *
+ * «Permission denied» on `/srv/apps/shop` is usually not about `shop` at all —
+ * it is about `/srv/apps`, and naming the wrong one sends the person to chmod
+ * a directory that was never the problem.
+ */
+export declare function firstUnreachableAncestor(target: string): string | null;
+/**
+ * Git refuses to work in a repository owned by somebody else — since 2022, and
+ * with no exception for root. So the "obvious" fix for a dedicated user (chown
+ * the project to it) breaks git for the person who was committing there before,
+ * and the exception has to be added on BOTH sides.
+ */
+export declare function safeDirectoryCommand(repoPath: string): string;
+export declare function looksLikeDubiousOwnership(message: string): boolean;
+/** Is this path already excused in the current user's git config? */
+export declare function hasSafeDirectory(repoPath: string): Promise<boolean>;
+export declare function addSafeDirectory(repoPath: string): Promise<void>;
+/**
+ * What the agent will find in this user's home besides a login.
+ *
+ * Copying only `.credentials.json` to a fresh user is the usual half-measure:
+ * the agent starts, and then behaves like a stranger — no permission allowlist,
+ * no slash commands, no plugins, default model. From the outside that reads as
+ * «the runner can't do anything», which is why this is worth reporting BEFORE
+ * the first session rather than diagnosing after it.
+ */
+export interface AgentConfigContour {
+    home: string;
+    claudeDir: boolean;
+    settings: boolean;
+    localSettings: boolean;
+    /** Number of entries in `permissions.allow`, or null when unreadable. */
+    allowRules: number | null;
+    commands: number;
+    plugins: boolean;
+    codexDir: boolean;
+    codexConfig: boolean;
+}
+export declare function agentConfigContour(home?: string): AgentConfigContour;
+/**
+ * Another user's home that already has an agent set up.
+ *
+ * Only reported, never copied: a copied OAuth credential means two accounts
+ * share one refresh token, and a rotation in either one silently invalidates
+ * the other. Signing in as the runner's own user is the clean answer; the copy
+ * is the fast one, and the person choosing between them deserves to be told
+ * which is which.
+ */
+export declare function otherHomeWithAgents(me?: RunnerIdentity): string | null;
+/**
+ * `systemctl --user` talks over a per-user D-Bus socket, and finds it through
+ * `XDG_RUNTIME_DIR`. Under `sudo -iu <user>` that variable is not set, and the
+ * failure is worse than an error: it prints «Failed to connect to bus» and
+ * exits **0**, so a health check reads it as success.
+ */
+export declare function systemdUserEnv(): NodeJS.ProcessEnv;
+/** True when the user bus is actually reachable — `systemctl --user` lies with exit 0. */
+export declare function systemdUserBusReachable(): Promise<boolean>;
+/** The command form that works under `sudo -iu <user>` — printed in hints. */
+export declare function systemctlHint(args: string): string;
+/**
+ * Remembered from binding and from session starts, so `doctor` can check the
+ * permissions of real projects instead of asking the person to name them.
+ * Best-effort on purpose: a runner that cannot write its own state directory
+ * has bigger problems than a diagnostic list, and none of them should turn a
+ * session start into an error.
+ */
+export declare function rememberWorkspacePath(workspacePath: string): void;
+export declare function knownWorkspacePaths(): string[];
+export interface ToolCheck {
+    /** `null` when the tool is not installed at all. */
+    path: string | null;
+    version?: string;
+    /** Set when the tool is there but this user cannot use it. */
+    problem?: string;
+}
+/**
+ * Node, as THIS user sees it.
+ *
+ * A dedicated user does not automatically inherit a Node installed for
+ * somebody else — fnm, nvm and a root-only prefix are all per-user by design.
+ * The runner itself is running, so node clearly exists somewhere; the question
+ * this answers is whether it is on the daemon user's own PATH, because that is
+ * what agent tooling and `npm install -g` will look at.
+ */
+export declare function nodeCheck(): Promise<ToolCheck>;
+/**
+ * Docker, as THIS user sees it.
+ *
+ * Reported rather than judged: plenty of projects never touch it. But when the
+ * project's own workflow is `docker compose`, a dedicated user without access
+ * to the socket produces a session that fails on its first command, and the
+ * error will be about a socket rather than about a group nobody was added to.
+ *
+ * Worth stating where it is stated: being in the `docker` group is equivalent
+ * to root on this machine. That is a fact for the owner to accept knowingly.
+ */
+export declare function dockerCheck(): Promise<ToolCheck>;
+/**
+ * Does the service survive a logout?
+ *
+ * `loginctl enable-linger` is what keeps a user's systemd services running with
+ * nobody logged in. `install-service` turns it on, but a unit installed by hand
+ * — or a user created afterwards — can miss it, and the failure looks like
+ * «the server goes offline whenever I close the terminal».
+ */
+export declare function lingerEnabled(): Promise<boolean | null>;
+/**
+ * Make the agent CLIs findable, without taking anything away.
+ *
+ * A systemd user service starts with the manager's PATH, which is the
+ * distribution default — `/usr/bin` and friends. Both agent CLIs are commonly
+ * installed somewhere else: `~/.local/bin` for a per-user install, and a
+ * node managed by fnm/nvm/volta lives under its own version directory. When
+ * `codex` sits there, the runner scans PATH, does not find it, and reports to
+ * the dashboard that this machine has no Codex at all — the agent the person
+ * installed simply never appears.
+ *
+ * Deliberately APPEND-ONLY, and deliberately in the process rather than in the
+ * unit file. Writing `Environment=PATH=…` into the unit would REPLACE whatever
+ * systemd gives the service today (`/snap/bin`, anything set through
+ * `environment.d`), trading something that works for something that is
+ * missing. Here nothing can be lost: entries are only added when they are
+ * absent and the directory actually exists.
+ *
+ * Returns what it added, so the caller can say so once at startup.
+ */
+export declare function ensureAgentPath(): string[];
+//# sourceMappingURL=environment.d.ts.map