@songsid/agend 2.1.6-beta.1 → 2.1.6-beta.3

package/dist/apply-job.d.ts

@@ -0,0 +1,114 @@
+/** How long a finished job stays answerable, and how long a key is honoured. */
+export declare const APPLY_JOB_RETENTION_MS: number;
+/**
+ * Wall clock, not a step count: the user is looking at a spinner, and the thing
+ * they need to be told is that it has been N seconds, not which internal phase
+ * it is in. Generous — a reconcile that restarts several agents on a loaded
+ * machine is slow but fine.
+ */
+export declare const APPLY_JOB_DEADLINE_MS = 120000;
+/** Outcome of asking the fleet to restart itself for a Settings change. */
+export type SelfRestartResult = {
+    ok: true;
+    jobId: string;
+    reused?: boolean;
+} | {
+    ok: false;
+    status: 409 | 429 | 503;
+    error: string;
+    retryAfterSeconds?: number;
+};
+/** The row for the fleet process itself, as opposed to one of its agents. */
+export declare const APPLY_FLEET_TARGET = "fleet";
+export type ApplyTargetKind = "hot" | "restart";
+/**
+ * `restart-required` is a terminal state, not a stalled one: the change is saved
+ * and valid, and a running fleet process cannot adopt it. Reporting it as done
+ * would tell the user AgEnD is on the new configuration when it is not.
+ */
+export type ApplyTargetStatus = "pending" | "running" | "done" | "failed" | "restart-required";
+export type ApplyJobStatus = "running" | "done" | "failed";
+export interface ApplyTarget {
+    /** Instance name, or `fleet` for the process-level row. */
+    target: string;
+    kind: ApplyTargetKind;
+    status: ApplyTargetStatus;
+    error?: string;
+    /**
+     * Who finished the row, when it was not this job's own work:
+     * `fleet-restart` — a process restart applied it;
+     * `no-change`     — the plan expected work the reconcile found unnecessary.
+     */
+    settled_by?: "fleet-restart" | "no-change";
+}
+export interface ApplyJob {
+    id: string;
+    /** The client's idempotency key. */
+    key: string;
+    status: ApplyJobStatus;
+    startedAt: number;
+    finishedAt?: number;
+    targets: ApplyTarget[];
+    /** Deadline for "still working" messaging; it never cancels the work. */
+    deadlineMs: number;
+    /** The process that created the job, so a restart is detectable. */
+    pid: number;
+    error?: string;
+    /**
+     * The idempotency key of the self-restart this job's fleet row was consumed
+     * by. Stored on the job rather than in memory because the process it belongs
+     * to is about to be replaced — a retry after the restart has to find it.
+     */
+    restart_key?: string;
+}
+/** Everything a caller needs to render, computed rather than stored so it stays
+ * true while the job is being read long after the last write. */
+export interface ApplyJobView extends ApplyJob {
+    elapsed_ms: number;
+    /** Past the deadline and still working — say so instead of spinning silently. */
+    overdue: boolean;
+    /** Human sentence for the overdue case; empty otherwise. */
+    message: string;
+}
+export declare function viewOf(job: ApplyJob, now?: number): ApplyJobView;
+/**
+ * The jobs file. Small, rewritten whole on every transition — a settings apply
+ * happens at human speed, so the simplest durable thing is the right one.
+ */
+/** Just enough of a logger for the one thing this module has to report. */
+export interface ApplyJobLogger {
+    warn(data: unknown, message: string): void;
+}
+export declare class ApplyJobStore {
+    private readonly dataDir;
+    private readonly now;
+    private readonly logger?;
+    private jobs;
+    constructor(dataDir: string, now?: () => number, logger?: ApplyJobLogger | undefined);
+    private path;
+    private read;
+    private write;
+    private prune;
+    /**
+     * A job created in an earlier process cannot still be running in this one.
+     *
+     * The restart is what applied the config: every agent came up from the saved
+     * file. So rows left pending or running are done — recorded as settled by the
+     * restart rather than by the job, because "who finished this" is exactly what
+     * the user is trying to find out.
+     */
+    settleAfterRestart(): ApplyJob[];
+    get(id: string): ApplyJob | null;
+    /** The job whose fleet row a given self-restart key already consumed. */
+    findByRestartKey(key: string): ApplyJob | null;
+    /** The live job for a key, if the client is retrying rather than re-applying. */
+    findByKey(key: string): ApplyJob | null;
+    create(key: string, targets: Array<Pick<ApplyTarget, "target" | "kind">>, deadlineMs?: number): ApplyJob;
+    /** Mutate one job and persist. Every transition hits the disk, because the
+     * transition we care most about is the last one before the process dies. */
+    update(id: string, mutate: (job: ApplyJob) => void): ApplyJob | null;
+    setTargetStatus(id: string, target: string, status: ApplyTargetStatus, error?: string): void;
+    finish(id: string, error?: string): void;
+    /** Test/introspection seam. */
+    all(): ApplyJob[];
+}

package/dist/apply-job.js

@@ -0,0 +1,214 @@
+/**
+ * A Settings "Apply" that the user can watch, and that survives the restart it
+ * asks for.
+ *
+ * The old path was `POST /api/settings/reload` → SIGHUP → nothing. The page said
+ * "changes applied" the moment the signal was sent, while the reconcile was
+ * still stopping and starting agents behind it, and a change that restarts AgEnD
+ * itself killed the only place the answer lived.
+ *
+ * Two properties carry the whole design:
+ *
+ * 1. **The job is on disk, not in the process.** A fleet-impact change takes the
+ *    fleet process down with it. An in-memory job dies there, `GET` starts
+ *    answering 404, and the page shows "restarting…" forever (#722/#748 are the
+ *    same shape). The replacement process reads the marker, settles whatever was
+ *    still in flight, and can answer for a job it never started.
+ * 2. **The client owns the idempotency key.** A server-minted job id cannot stop
+ *    a duplicate: on a phone the POST leaves, the answer never arrives, and the
+ *    retry is a second request the server has no way to recognise. A key the
+ *    client generates before the first attempt makes the retry identifiable, so
+ *    it returns the original job instead of applying everything twice.
+ */
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+const FILE = "settings-apply-jobs.json";
+/** How long a finished job stays answerable, and how long a key is honoured. */
+export const APPLY_JOB_RETENTION_MS = 30 * 60_000;
+/**
+ * Wall clock, not a step count: the user is looking at a spinner, and the thing
+ * they need to be told is that it has been N seconds, not which internal phase
+ * it is in. Generous — a reconcile that restarts several agents on a loaded
+ * machine is slow but fine.
+ */
+export const APPLY_JOB_DEADLINE_MS = 120_000;
+/** At most this many jobs are kept, newest first. */
+const MAX_JOBS = 20;
+/** The row for the fleet process itself, as opposed to one of its agents. */
+export const APPLY_FLEET_TARGET = "fleet";
+function isTerminal(status) {
+    return status === "done" || status === "failed";
+}
+export function viewOf(job, now = Date.now()) {
+    const elapsed = Math.max(0, (job.finishedAt ?? now) - job.startedAt);
+    const overdue = !isTerminal(job.status) && elapsed > job.deadlineMs;
+    return {
+        ...job,
+        elapsed_ms: elapsed,
+        overdue,
+        message: overdue ? `Still restarting (${Math.round(elapsed / 1000)}s)` : "",
+    };
+}
+export class ApplyJobStore {
+    dataDir;
+    now;
+    logger;
+    jobs = [];
+    constructor(dataDir, now = Date.now, logger) {
+        this.dataDir = dataDir;
+        this.now = now;
+        this.logger = logger;
+        this.jobs = this.read();
+    }
+    path() {
+        return join(this.dataDir, FILE);
+    }
+    read() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.path(), "utf-8"));
+            if (!Array.isArray(parsed.jobs))
+                return [];
+            return parsed.jobs.filter(job => typeof job?.id === "string"
+                && typeof job?.key === "string"
+                && typeof job?.startedAt === "number"
+                && Array.isArray(job?.targets));
+        }
+        catch {
+            // Missing or corrupt: an unreadable history must not stop the user from
+            // applying settings.
+            return [];
+        }
+    }
+    write() {
+        const path = this.path();
+        const temp = `${path}.${process.pid}.${this.now()}.tmp`;
+        try {
+            writeFileSync(temp, JSON.stringify({ jobs: this.jobs }), { mode: 0o600 });
+            renameSync(temp, path);
+        }
+        catch (err) {
+            try {
+                unlinkSync(temp);
+            }
+            catch { /* never created */ }
+            // A full or read-only data dir means this job will not survive a restart.
+            // Swallowing that silently is how the symptom becomes "progress just
+            // vanished" with nothing to look at.
+            this.logger?.warn({ err, path }, "Settings apply job could not be persisted");
+        }
+    }
+    prune() {
+        const cutoff = this.now() - APPLY_JOB_RETENTION_MS;
+        this.jobs = this.jobs
+            .filter(job => (job.finishedAt ?? job.startedAt) >= cutoff)
+            .slice(0, MAX_JOBS);
+    }
+    /**
+     * A job created in an earlier process cannot still be running in this one.
+     *
+     * The restart is what applied the config: every agent came up from the saved
+     * file. So rows left pending or running are done — recorded as settled by the
+     * restart rather than by the job, because "who finished this" is exactly what
+     * the user is trying to find out.
+     */
+    settleAfterRestart() {
+        const settled = [];
+        for (const job of this.jobs) {
+            if (isTerminal(job.status))
+                continue;
+            // Only a job from another process. The health server accepts requests a
+            // little before startup finishes, so an apply started seconds ago in THIS
+            // process would otherwise be declared finished by a restart that already
+            // happened. (A recycled pid would leave such a job running until its
+            // deadline reports it — the harmless direction.)
+            if (job.pid === process.pid)
+                continue;
+            for (const row of job.targets) {
+                if (row.status === "done" || row.status === "failed")
+                    continue;
+                row.status = "done";
+                row.settled_by = "fleet-restart";
+            }
+            job.status = "done";
+            job.finishedAt = this.now();
+            settled.push(job);
+        }
+        if (settled.length)
+            this.write();
+        return settled;
+    }
+    get(id) {
+        return this.jobs.find(job => job.id === id) ?? null;
+    }
+    /** The job whose fleet row a given self-restart key already consumed. */
+    findByRestartKey(key) {
+        return this.jobs.find(job => job.restart_key === key) ?? null;
+    }
+    /** The live job for a key, if the client is retrying rather than re-applying. */
+    findByKey(key) {
+        const cutoff = this.now() - APPLY_JOB_RETENTION_MS;
+        return this.jobs.find(job => job.key === key && (job.finishedAt ?? job.startedAt) >= cutoff) ?? null;
+    }
+    create(key, targets, deadlineMs = APPLY_JOB_DEADLINE_MS) {
+        const job = {
+            id: randomUUID(),
+            key,
+            status: "running",
+            startedAt: this.now(),
+            targets: targets.map(row => ({ ...row, status: "pending" })),
+            deadlineMs,
+            pid: process.pid,
+        };
+        this.jobs.unshift(job);
+        this.prune();
+        this.write();
+        return job;
+    }
+    /** Mutate one job and persist. Every transition hits the disk, because the
+     * transition we care most about is the last one before the process dies. */
+    update(id, mutate) {
+        const job = this.get(id);
+        if (!job)
+            return null;
+        mutate(job);
+        this.write();
+        return job;
+    }
+    setTargetStatus(id, target, status, error) {
+        this.update(id, job => {
+            const row = job.targets.find(item => item.target === target);
+            if (!row)
+                return;
+            row.status = status;
+            if (error)
+                row.error = error;
+        });
+    }
+    finish(id, error) {
+        this.update(id, job => {
+            for (const row of job.targets) {
+                if (row.status !== "pending" && row.status !== "running")
+                    continue;
+                if (error) {
+                    row.status = "failed";
+                    row.error = error;
+                    continue;
+                }
+                // The plan forecast work the reconcile then found unnecessary. Saying
+                // plain "done" would read as "this agent was restarted".
+                row.status = "done";
+                row.settled_by = "no-change";
+            }
+            job.status = error ? "failed" : job.targets.some(row => row.status === "failed") ? "failed" : "done";
+            job.finishedAt = this.now();
+            if (error)
+                job.error = error;
+        });
+    }
+    /** Test/introspection seam. */
+    all() {
+        return this.jobs;
+    }
+}
+//# sourceMappingURL=apply-job.js.map

package/dist/apply-job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-job.js","sourceRoot":"","sources":["../src/apply-job.ts"],"names":[],"mappings":"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"}

package/dist/backend/codex.d.ts

@@ -5,6 +5,8 @@ export declare class CodexBackend implements CliBackend {
     private binaryPath;
     private readonly sharedCodexHome;
     private readonly isolatedCodexHome;
+    /** Which subscription this instance runs on, or null for the shared login. */
+    private credentialProfile;
     constructor(instanceDir: string);
     supportsQueuedInput(): boolean;
     /**
@@ -78,6 +80,16 @@ export declare class CodexBackend implements CliBackend {
      * ~/.codex/config.toml (no toml dependency); other settings untouched.
      */
     private enableContextStatusLine;
+    /** Null when the instance did not ask for a profile — today's behaviour. */
+    private readProfile;
+    /**
+     * Where this instance's `auth.json` comes from.
+     *
+     * The shared home unless a profile says otherwise. A profile owns the file
+     * itself — not a copy, not a link — so codex refreshing the token writes
+     * into that subscription and no other.
+     */
+    private authSourceDir;
     preTrust(workDir: string): void;
     /**
      * Preserve Codex login/session/cache behavior while isolating config.toml.
@@ -88,6 +100,18 @@ export declare class CodexBackend implements CliBackend {
     /** Session dirs every instance must share with the terminal CLI (#506). */
     private static readonly SHARED_SESSION_DIRS;
     private prepareIsolatedHome;
+    /**
+     * Point this home's `auth.json` at whichever login it should use.
+     *
+     * Codex refreshes the token by writing through the link rather than replacing
+     * it — observed across every instance home on a machine that has been running
+     * this arrangement for months, with the shared file's mtime moving. That is
+     * behaviour, though, not a contract: a release that starts renaming over the
+     * file would leave a real file here and quietly fork the login, with refreshes
+     * landing somewhere the profile never sees. So a real file where a link
+     * belongs is treated as exactly that — reported, and put back.
+     */
+    private linkAuthFile;
     /**
      * One-time heal for an instance whose isolated home grew a REAL session dir
      * (#506): merge it into the shared home without overwriting anything, and

package/dist/backend/codex.js

@@ -3,6 +3,8 @@ import { homedir } from "node:os";
 import { lastNonBlankRow } from "../pane-input-residue.js";
 import { basename, dirname, join, resolve } from "node:path";
 import { probeCliVersion, resolveBinary, shellQuote, validateModel, validateProvider, warnIfModelMismatch } from "./types.js";
+import { credentialHomeSpec, credentialProfileHome, prepareCredentialProfileHome, resolveCredentialProfile, } from "./credential-profile.js";
+import { getAgendHome } from "../paths.js";
 import { appendWithMarker, removeMarker } from "./marker-utils.js";
 import { t } from "../locale.js";
 const CODEX_PROJECT_DOC_MAX_BYTES = 32_768;
@@ -95,6 +97,8 @@ function atomicWritePrivate(path, content) {
 }
 // Account-aware models_cache.json is preferred. These documented Codex models
 // are only a last-resort menu when the TUI has not populated its cache yet.
+/** The whole of a codex identity, and the only file a profile owns. */
+const CODEX_AUTH_FILE = "auth.json";
 const CODEX_FALLBACK_MODELS = [
     { id: "gpt-5.6-sol", label: "GPT-5.6 Sol", description: "frontier agentic coding" },
     { id: "gpt-5.6-terra", label: "GPT-5.6 Terra", description: "balanced agentic coding" },
@@ -106,6 +110,8 @@ export class CodexBackend {
     binaryPath;
     sharedCodexHome;
     isolatedCodexHome;
+    /** Which subscription this instance runs on, or null for the shared login. */
+    credentialProfile = null;
     constructor(instanceDir) {
         this.instanceDir = instanceDir;
         this.binaryPath = resolveBinary("codex");
@@ -194,6 +200,7 @@ export class CodexBackend {
     }
     buildCommand(config) {
         this.lastKnownModel = config.model?.trim() || null;
+        this.credentialProfile = this.readProfile(config);
         const approvalFlag = config.skipPermissions !== false
             ? "--dangerously-bypass-approvals-and-sandbox"
             : "--full-auto";
@@ -227,6 +234,9 @@ export class CodexBackend {
         return `CODEX_HOME=${shellQuote(this.isolatedCodexHome)} ${cmd}`;
     }
     writeConfig(config) {
+        // Set before the home is prepared: which login this instance gets is a
+        // property of the home, and the home is built here.
+        this.credentialProfile = this.readProfile(config);
         this.prepareIsolatedHome();
         this.cleanSharedConfig();
         // Copy all user settings but no AgEnD MCP entries into a private base
@@ -356,6 +366,35 @@ export class CodexBackend {
         }
         catch { /* best effort — never block launch on statusline config */ }
     }
+    /** Null when the instance did not ask for a profile — today's behaviour. */
+    readProfile(config) {
+        try {
+            return resolveCredentialProfile(config.backendOptions);
+        }
+        catch {
+            // A malformed name is refused where it is written; launching is not the
+            // place to discover it, and falling back to the shared login is the
+            // behaviour every instance had before profiles existed.
+            return null;
+        }
+    }
+    /**
+     * Where this instance's `auth.json` comes from.
+     *
+     * The shared home unless a profile says otherwise. A profile owns the file
+     * itself — not a copy, not a link — so codex refreshing the token writes
+     * into that subscription and no other.
+     */
+    authSourceDir() {
+        if (!this.credentialProfile)
+            return this.sharedCodexHome;
+        const spec = credentialHomeSpec(this.binaryName);
+        if (!spec)
+            return this.sharedCodexHome;
+        const home = credentialProfileHome(getAgendHome(), this.binaryName, this.credentialProfile);
+        prepareCredentialProfileHome(spec, home);
+        return home;
+    }
     preTrust(workDir) {
         const configPath = join(this.isolatedCodexHome, "config.toml");
         let content = "";
@@ -423,9 +462,16 @@ export class CodexBackend {
         if (healedSidecars.length > 0) {
             console.warn(`[agend] removed unsafe Codex SQLite sidecar links: ${healedSidecars.join(", ")}`);
         }
+        // One file, possibly from somewhere else. Everything below is unchanged:
+        // sessions, the thread/state/memory databases and every cache still come
+        // from the shared home, which is why switching subscription does not throw
+        // the conversation away.
+        this.linkAuthFile();
         for (const name of readdirSync(this.sharedCodexHome)) {
             if (name === "config.toml" || name === AGEND_MCP_CLEANUP_LOCK || name.startsWith(".config.toml."))
                 continue;
+            if (name === CODEX_AUTH_FILE)
+                continue; // handled above, possibly from a profile
             // SQLite resolves a symlinked base DB to the shared path and creates its
             // own adjacent sidecars there. Linking sidecars separately is redundant
             // for shared bases and corrupts the file set for private bases.
@@ -445,6 +491,62 @@ export class CodexBackend {
             }
         }
     }
+    /**
+     * Point this home's `auth.json` at whichever login it should use.
+     *
+     * Codex refreshes the token by writing through the link rather than replacing
+     * it — observed across every instance home on a machine that has been running
+     * this arrangement for months, with the shared file's mtime moving. That is
+     * behaviour, though, not a contract: a release that starts renaming over the
+     * file would leave a real file here and quietly fork the login, with refreshes
+     * landing somewhere the profile never sees. So a real file where a link
+     * belongs is treated as exactly that — reported, and put back.
+     */
+    linkAuthFile() {
+        const source = join(this.authSourceDir(), CODEX_AUTH_FILE);
+        const target = join(this.isolatedCodexHome, CODEX_AUTH_FILE);
+        let existing = null;
+        try {
+            existing = lstatSync(target);
+        }
+        catch { /* absent */ }
+        if (existing?.isSymbolicLink()) {
+            let current = "";
+            try {
+                current = resolve(dirname(target), readlinkSync(target));
+            }
+            catch { /* unreadable */ }
+            if (current === source)
+                return;
+            try {
+                unlinkSync(target);
+            }
+            catch { /* raced */ }
+        }
+        else if (existing) {
+            // Not a link: codex replaced it, or an older AgEnD copied it. Either way
+            // the refreshes it has been collecting are stranded in this instance's
+            // home, so say so rather than deleting them silently.
+            const stranded = `${target}.replaced-${Date.now()}`;
+            try {
+                renameSync(target, stranded);
+                console.warn(`[agend] codex replaced ${CODEX_AUTH_FILE} in ${this.isolatedCodexHome} with a real file — `
+                    + `its login was no longer shared. Kept a copy at ${stranded} and re-linked to ${source}.`);
+            }
+            catch {
+                return; // cannot move it; leave the instance working on what it has
+            }
+        }
+        if (!existsSync(source))
+            return; // not logged in yet; codex will create it
+        try {
+            symlinkSync(source, target, "file");
+        }
+        catch {
+            // EEXIST from a concurrent start is the ordinary case and means the link
+            // is already there.
+        }
+    }
     /**
      * One-time heal for an instance whose isolated home grew a REAL session dir
      * (#506): merge it into the shared home without overwriting anything, and