@open-mercato/cezar 0.13.0 → 0.14.0

package/dist/server/star-count.d.ts

@@ -0,0 +1,67 @@
+export declare const CEZAR_REPO_URL = "https://github.com/open-mercato/cezar";
+/** Six hours. A star count moves slowly and nothing here depends on it being exact. */
+export declare const STAR_CACHE_TTL_MS: number;
+/**
+ * Fifteen minutes, and the reason a FAILED read is remembered too.
+ *
+ * `fetchedAtMs` only advances on success, so without this the failure path has no cache at all:
+ * an offline or proxied machine pays the full `TIMEOUT_MS` on every cockpit load forever, and a
+ * rate-limited IP (60/h unauthenticated) keeps spending requests into the very `403` that is
+ * telling it to stop. `inFlight` collapses a concurrent burst, never a sequential one.
+ *
+ * Shorter than the success TTL on purpose — offline is usually temporary and the cost of being
+ * wrong here is one quiet chip, not a stale number.
+ */
+export declare const STAR_FAILURE_BACKOFF_MS: number;
+export interface StarCount {
+    /** `false` whenever there is no number to show — offline, rate-limited, or promos silenced.
+     *  The cockpit renders no chip at all in that case; it never renders an empty one. */
+    available: boolean;
+    /** Only present when `available`. */
+    count?: number;
+    /** Where the ⭐ button points. Always sent, so the link never depends on the count. */
+    url: string;
+}
+export declare function starCachePath(home?: string): string;
+/**
+ * The promo's single off switch (AGENTS.md § Zero config: a network widening needs one, and a
+ * second spelling of an existing switch is a knob rather than a feature). `CEZ_NO_BANNER=1`
+ * already means "no `open-mercato` promo in my terminal"; it now means no star ask anywhere —
+ * no terminal line, no sidebar chip, no toast, and no request to github.com.
+ */
+export declare function starAskSilenced(env?: NodeJS.ProcessEnv): boolean;
+/** One request, zod-validated, silent on every failure. `null` means "nothing known". */
+export declare function fetchStarCount(fetchImpl?: typeof fetch): Promise<number | null>;
+export interface StarCountReaderOptions {
+    fetchImpl?: typeof fetch;
+    /** Injectable so tests never touch a real home. */
+    cachePath?: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+}
+/**
+ * Memoized reader behind `GET /api/v1/star-count`. Mirrors `self-update/registry.ts`'s
+ * `RegistryCache` on purpose — same shape, same guarantees — with a disk tier added because this
+ * value survives a restart usefully and a version document does not.
+ */
+export declare class StarCountReader {
+    private count;
+    private fetchedAtMs;
+    /** `null` — not `0` — means "never failed": a `now()` near the epoch (every test clock) would
+     *  otherwise read as a failure one tick ago and suppress the very first request. */
+    private failedAtMs;
+    private inFlight;
+    private diskRead;
+    private readonly fetchImpl;
+    private readonly cachePath;
+    private readonly env;
+    private readonly now;
+    constructor(options?: StarCountReaderOptions);
+    read(): Promise<StarCount>;
+    /** Once per process: fold a previous run's answer in before deciding to spend a request. */
+    private seedFromDisk;
+    /** Whether the last attempt failed recently enough that another one is not worth its timeout. */
+    private backingOff;
+    /** Always goes to GitHub, and never twice at once — a burst of cockpit tabs is one request. */
+    private refresh;
+}

package/dist/server/star-count.js

@@ -0,0 +1,186 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+/**
+ * cezar's own GitHub star count, for the cockpit's ⭐ ask (sidebar chip + first-run toast).
+ *
+ * The count is read HERE and not in the browser, deliberately. The cockpit has never made a
+ * third-party request and should not start: one cezar process asking once per TTL is strictly
+ * less exposure than every open tab asking, it keeps working in remote mode where the browser
+ * may not reach the internet at all, and it lets the whole promo sit behind one off switch the
+ * server already owns.
+ *
+ * Failure is not exceptional here, it is the common case — offline, rate-limited (60/h per IP
+ * unauthenticated), behind a proxy, `CEZ_NO_BANNER=1`. Every one of them answers
+ * `{ available: false }` the way `server/github.ts` does, never an error and never a throw: a
+ * promo that can break a cockpit is worse than a promo nobody sees.
+ *
+ * Two caches, both cheap: in memory for the life of the process, and a single small JSON file
+ * under `~/.cache/cez/` so a restart (the desktop shell restarts often) paints the count
+ * immediately and does not spend another request. A stale disk entry is still served while the
+ * refresh is in flight — the number is decoration, and a slightly old one is better than a
+ * flicker.
+ */
+const REPO = 'open-mercato/cezar';
+export const CEZAR_REPO_URL = `https://github.com/${REPO}`;
+const API_URL = `https://api.github.com/repos/${REPO}`;
+const TIMEOUT_MS = 5_000;
+/** Six hours. A star count moves slowly and nothing here depends on it being exact. */
+export const STAR_CACHE_TTL_MS = 6 * 60 * 60_000;
+/**
+ * Fifteen minutes, and the reason a FAILED read is remembered too.
+ *
+ * `fetchedAtMs` only advances on success, so without this the failure path has no cache at all:
+ * an offline or proxied machine pays the full `TIMEOUT_MS` on every cockpit load forever, and a
+ * rate-limited IP (60/h unauthenticated) keeps spending requests into the very `403` that is
+ * telling it to stop. `inFlight` collapses a concurrent burst, never a sequential one.
+ *
+ * Shorter than the success TTL on purpose — offline is usually temporary and the cost of being
+ * wrong here is one quiet chip, not a stale number.
+ */
+export const STAR_FAILURE_BACKOFF_MS = 15 * 60_000;
+/** Frozen: `read()` hands this same object to every caller, and a shared mutable answer is a
+ *  bug waiting for its first mutator. */
+const UNAVAILABLE = Object.freeze({ available: false, url: CEZAR_REPO_URL });
+/** The one field we want, validated at the boundary like every other `--json`/API read. */
+const repoSchema = z
+    .object({ stargazers_count: z.number().int().nonnegative() })
+    .passthrough();
+const diskEntrySchema = z.object({
+    count: z.number().int().nonnegative(),
+    fetchedAtMs: z.number().int().nonnegative(),
+});
+export function starCachePath(home = homedir()) {
+    return join(home, '.cache', 'cez', 'star-count.json');
+}
+/**
+ * The promo's single off switch (AGENTS.md § Zero config: a network widening needs one, and a
+ * second spelling of an existing switch is a knob rather than a feature). `CEZ_NO_BANNER=1`
+ * already means "no `open-mercato` promo in my terminal"; it now means no star ask anywhere —
+ * no terminal line, no sidebar chip, no toast, and no request to github.com.
+ */
+export function starAskSilenced(env = process.env) {
+    if (env.CEZ_NO_BANNER === '1')
+        return true;
+    // `npm test` is the fast unit gate: "no server, no browser", and it must stay that way
+    // (AGENTS.md § Validation). Every test today injects its own reader or its own `fetchImpl`, so
+    // nothing reaches github.com — but that is an accident of which routes the suite happens to
+    // request, and `createApp` hands a DEFAULT reader to every case that builds an app. The first
+    // test to call `GET /api/v1/star-count` without meaning to would make the unit gate networked
+    // and non-deterministic, and it would do so silently.
+    //
+    // Same shape and same reasoning as `assertCezarHomeWriteIsSandboxed` (src/paths.ts): under
+    // vitest, reaching the real outside world is a leaked test rather than intent. A case that
+    // genuinely wants the fetch path passes its own `fetchImpl` to `fetchStarCount`, which this
+    // does not gate — only the shared reader's default is closed off.
+    if (env.VITEST)
+        return true;
+    return false;
+}
+/** One request, zod-validated, silent on every failure. `null` means "nothing known". */
+export async function fetchStarCount(fetchImpl = fetch) {
+    try {
+        const res = await fetchImpl(API_URL, {
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+            headers: { accept: 'application/vnd.github+json' },
+        });
+        if (!res.ok)
+            return null;
+        const parsed = repoSchema.safeParse(await res.json());
+        return parsed.success ? parsed.data.stargazers_count : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readDisk(path) {
+    try {
+        const parsed = diskEntrySchema.safeParse(JSON.parse(await readFile(path, 'utf8')));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeDisk(path, entry) {
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, JSON.stringify(entry), 'utf8');
+    }
+    catch {
+        // A read-only home is not a reason to lose the count — the memory cache still holds it.
+    }
+}
+/**
+ * Memoized reader behind `GET /api/v1/star-count`. Mirrors `self-update/registry.ts`'s
+ * `RegistryCache` on purpose — same shape, same guarantees — with a disk tier added because this
+ * value survives a restart usefully and a version document does not.
+ */
+export class StarCountReader {
+    count = null;
+    fetchedAtMs = 0;
+    /** `null` — not `0` — means "never failed": a `now()` near the epoch (every test clock) would
+     *  otherwise read as a failure one tick ago and suppress the very first request. */
+    failedAtMs = null;
+    inFlight = null;
+    diskRead = false;
+    fetchImpl;
+    cachePath;
+    env;
+    now;
+    constructor(options = {}) {
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.cachePath = options.cachePath ?? starCachePath();
+        this.env = options.env ?? process.env;
+        this.now = options.now ?? Date.now;
+    }
+    async read() {
+        if (starAskSilenced(this.env))
+            return UNAVAILABLE;
+        await this.seedFromDisk();
+        if (this.count !== null && this.now() - this.fetchedAtMs < STAR_CACHE_TTL_MS) {
+            return { available: true, count: this.count, url: CEZAR_REPO_URL };
+        }
+        const fresh = this.backingOff() ? null : await this.refresh();
+        // A failed refresh falls back to whatever is still held: a stale number beats no number,
+        // and "no number" here would make the chip disappear on the first flaky minute.
+        const count = fresh ?? this.count;
+        return count === null ? UNAVAILABLE : { available: true, count, url: CEZAR_REPO_URL };
+    }
+    /** Once per process: fold a previous run's answer in before deciding to spend a request. */
+    async seedFromDisk() {
+        if (this.diskRead)
+            return;
+        this.diskRead = true;
+        const entry = await readDisk(this.cachePath);
+        if (!entry)
+            return;
+        this.count = entry.count;
+        this.fetchedAtMs = entry.fetchedAtMs;
+    }
+    /** Whether the last attempt failed recently enough that another one is not worth its timeout. */
+    backingOff() {
+        return this.failedAtMs !== null && this.now() - this.failedAtMs < STAR_FAILURE_BACKOFF_MS;
+    }
+    /** Always goes to GitHub, and never twice at once — a burst of cockpit tabs is one request. */
+    async refresh() {
+        if (this.inFlight)
+            return this.inFlight;
+        this.inFlight = fetchStarCount(this.fetchImpl).then(async (count) => {
+            if (count === null) {
+                this.failedAtMs = this.now();
+            }
+            else {
+                this.count = count;
+                this.fetchedAtMs = this.now();
+                this.failedAtMs = null;
+                await writeDisk(this.cachePath, { count, fetchedAtMs: this.fetchedAtMs });
+            }
+            this.inFlight = null;
+            return count;
+        });
+        return this.inFlight;
+    }
+}
+//# sourceMappingURL=star-count.js.map

package/dist/server/star-count.js.map

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

package/dist/skills-banner.d.ts

@@ -20,3 +20,22 @@ export declare const SKILLS_BANNER_LINES: readonly string[];
 export declare function shouldShowSkillsBanner(repoRoot: string): Promise<boolean>;
 /** The `serve` startup banner. `log` is injectable so the wiring is testable. */
 export declare function printSkillsBanner(repoRoot: string, log?: (line?: string) => void): Promise<void>;
+/**
+ * The star ask's terminal surface: ONE line, under the skills promo, in the same already-chatty
+ * startup block and behind the same two off switches. A request and nothing else — no reward, no
+ * count to beat, nothing about cezar works differently for someone who never clicks it.
+ *
+ * One line is the whole design. The other two surfaces (the sidebar ⭐ chip and the one-time
+ * first-run toast) are where this ask has room to say more; a terminal that prints on every
+ * `serve` is exactly where a promo turns into a nag, so it gets a sentence and no repeat.
+ */
+export declare const STAR_BANNER_LINE = "  \u2B50 Find cezar useful? A star helps others find it: https://github.com/open-mercato/cezar";
+/**
+ * The star line, printed after the skills promo on `serve`.
+ *
+ * It shares `shouldShowSkillsBanner` deliberately rather than growing a switch of its own: the
+ * two lines are one promo block from where the user sits, and someone who silenced that block —
+ * with `CEZ_NO_BANNER=1` or by dismissing it back when the cockpit could — silenced this too.
+ * A second spelling of an existing off switch is a knob, not a feature (AGENTS.md § Zero config).
+ */
+export declare function printStarBanner(repoRoot: string, log?: (line?: string) => void): Promise<void>;

package/dist/skills-banner.js

@@ -38,4 +38,28 @@ export async function printSkillsBanner(repoRoot, log = console.log) {
         log(line);
     log();
 }
+/**
+ * The star ask's terminal surface: ONE line, under the skills promo, in the same already-chatty
+ * startup block and behind the same two off switches. A request and nothing else — no reward, no
+ * count to beat, nothing about cezar works differently for someone who never clicks it.
+ *
+ * One line is the whole design. The other two surfaces (the sidebar ⭐ chip and the one-time
+ * first-run toast) are where this ask has room to say more; a terminal that prints on every
+ * `serve` is exactly where a promo turns into a nag, so it gets a sentence and no repeat.
+ */
+export const STAR_BANNER_LINE = '  ⭐ Find cezar useful? A star helps others find it: https://github.com/open-mercato/cezar';
+/**
+ * The star line, printed after the skills promo on `serve`.
+ *
+ * It shares `shouldShowSkillsBanner` deliberately rather than growing a switch of its own: the
+ * two lines are one promo block from where the user sits, and someone who silenced that block —
+ * with `CEZ_NO_BANNER=1` or by dismissing it back when the cockpit could — silenced this too.
+ * A second spelling of an existing off switch is a knob, not a feature (AGENTS.md § Zero config).
+ */
+export async function printStarBanner(repoRoot, log = console.log) {
+    if (!(await shouldShowSkillsBanner(repoRoot)))
+        return;
+    log(STAR_BANNER_LINE);
+    log();
+}
 //# sourceMappingURL=skills-banner.js.map

package/dist/skills-banner.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills-banner.js","sourceRoot":"","sources":["../src/skills-banner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsB;IACpD,0DAA0D;IAC1D,0EAA0E;IAC1E,iEAAiE;IACjE,uFAAuF;IACvF,8EAA8E;CAC/E,CAAC;AAEF,oDAAoD;AACpD,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,QAAgB;IAC3D,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IACpD,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC,qBAAqB,KAAK,IAAI,CAAC;AAChD,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,GAAG,GAA4B,OAAO,CAAC,GAAG;IAE1C,IAAI,CAAC,CAAC,MAAM,sBAAsB,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO;IACtD,KAAK,MAAM,IAAI,IAAI,mBAAmB;QAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAClD,GAAG,EAAE,CAAC;AACR,CAAC"}
+{"version":3,"file":"skills-banner.js","sourceRoot":"","sources":["../src/skills-banner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsB;IACpD,0DAA0D;IAC1D,0EAA0E;IAC1E,iEAAiE;IACjE,uFAAuF;IACvF,8EAA8E;CAC/E,CAAC;AAEF,oDAAoD;AACpD,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,QAAgB;IAC3D,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IACpD,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC,qBAAqB,KAAK,IAAI,CAAC;AAChD,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,GAAG,GAA4B,OAAO,CAAC,GAAG;IAE1C,IAAI,CAAC,CAAC,MAAM,sBAAsB,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO;IACtD,KAAK,MAAM,IAAI,IAAI,mBAAmB;QAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAClD,GAAG,EAAE,CAAC;AACR,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,2FAA2F,CAAC;AAE9F;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,GAAG,GAA4B,OAAO,CAAC,GAAG;IAE1C,IAAI,CAAC,CAAC,MAAM,sBAAsB,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO;IACtD,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACtB,GAAG,EAAE,CAAC;AACR,CAAC"}

package/dist/workflows/run.d.ts

@@ -7,8 +7,6 @@ import type { QueuedMessage, RunRecord, RunStore } from '../runs/store.ts';
 import type { DispatchInput, DispatchIntent, DispatchReport, RunDispatch } from '../contract/index.js';
 import { WorkspaceSemaphore, type AccountHolds } from '../workspace/semaphore.ts';
 import { type WorkflowDef } from './types.ts';
-/** An interactive session that hears nothing from the user closes itself. */
-export declare const IDLE_TIMEOUT_MS: number;
 /**
  * The text a turn-end marker is matched against: the accumulated turn text with
  * trailing whitespace and trailing task-reference lines removed.

package/dist/workflows/run.js

@@ -24,7 +24,7 @@ import { materializeSkillDir } from '../skills-remote.js';
 import { seedAgentConfigLocalLayer } from '../agent-config/seed.js';
 import { readAgentModelProvider } from '../agent-config/models.js';
 import { loadConfig, resolveWorktreeRetention } from '../config.js';
-import { autosaveCommit, createWorktree, resolveBaseRef, worktreeDiff, worktreeShortstat } from '../git-worktree.js';
+import { autosaveCommit, chooseForkBase, createWorktree, worktreeDiff, worktreeShortstat } from '../git-worktree.js';
 import { getHeadCommit, getRepoInfo } from '../server/git.js';
 import { loadWorkflows } from './load.js';
 import { resolveCapabilities } from '../server/capabilities.js';
@@ -47,8 +47,6 @@ const CHECK_OUTPUT_CAP = 20_000;
 async function configuredModelProvider(backend, repoRoot) {
     return readAgentModelProvider(backend, repoRoot).catch(() => undefined);
 }
-/** An interactive session that hears nothing from the user closes itself. */
-export const IDLE_TIMEOUT_MS = 15 * 60_000;
 /** Maximum time a live provider gets to honor cancellation before its slot is reaped. */
 const CANCEL_GRACE_MS = 1_000;
 /**
@@ -1197,9 +1195,13 @@ export class RunManager {
         if (queuedContinuation && sessionStep?.sessionId) {
             const backend = run.runner ?? 'claude';
             const sessionBackend = sessionStep.backend ?? backend;
+            // Same rule as `continueRun`: a session created under another account than the run's
+            // chosen one cannot be resumed without silently switching the login back.
+            const sessionAccount = sessionStep.profileId ?? DEFAULT_AGENT_ACCOUNT_ID;
+            const accountMatches = run.agentProfile === undefined || run.agentProfile === sessionAccount;
             this.pendingContinuations.set(run.id, {
                 stepId: queuedContinuation.id,
-                sessionId: sessionBackend === backend ? sessionStep.sessionId : undefined,
+                sessionId: sessionBackend === backend && accountMatches ? sessionStep.sessionId : undefined,
                 backend,
                 prompt: RESTART_CONTINUATION_PROMPT,
                 images: [],
@@ -2972,7 +2974,13 @@ export class RunManager {
         // open a fresh conversation while the thread claimed it had resumed. A step that recorded no
         // account predates the feature and therefore ran under the discovered one.
         const sessionAccount = sessionStep.profileId ?? DEFAULT_AGENT_ACCOUNT_ID;
-        const accountSwitched = opts.agentProfile !== undefined && opts.agentProfile !== sessionAccount;
+        // The account this turn must run on: the composer's pick, else the one the run already
+        // chose. The run's own choice counts too — a record whose newest session predates an
+        // account switch (a fresh continuation that recorded no session id) must not be resumed
+        // under the account the user switched away from.
+        const targetAccount = opts.agentProfile
+            ?? (targetRunner === (run.runner ?? 'claude') ? run.agentProfile : undefined);
+        const accountSwitched = targetAccount !== undefined && targetAccount !== sessionAccount;
         const resume = sessionBackend === targetRunner && !accountSwitched;
         // Follow-up runner/model/account override (#401, spec 2026-07-29-agent-profiles): the composer
         // lets the user pick which backend, model and login handle this continuation — the same flat
@@ -3080,6 +3088,13 @@ export class RunManager {
         const portableContext = record && sessionId === undefined
             ? freshContinuationContext(record, this.store.readEvents(runId))
             : undefined;
+        // A fresh session is pinned and recorded up front, exactly like a workflow step's
+        // (`runAgentStep`): Claude emits no `session` event of its own, so an unpinned fresh
+        // continuation left its step without a session id, and the NEXT Continue resumed the last
+        // step that had one — an older session under whatever account created it, silently undoing
+        // the account switch this continuation was opened for. Runners that mint their own id still
+        // overwrite it through the `session` event.
+        const spawnSessionId = sessionId ?? randomUUID();
         // The env is a live ceiling: a run created while the inbox was on must not keep writing
         // follow-ups after it is switched off.
         const generateFollowups = followupsEnabled() && record?.generateFollowups !== false;
@@ -3157,7 +3172,7 @@ export class RunManager {
             status: 'running',
             iterations: 1,
             startedAt: new Date().toISOString(),
-            sessionId,
+            sessionId: spawnSessionId,
             backend,
         });
         this.store.appendEvent(runId, { type: 'step-start', stepId, name: 'Continue', kind: 'agent', iteration: 1 });
@@ -3275,7 +3290,8 @@ export class RunManager {
                 // with `runAgentStep`'s twin turn-end so the two cannot drift — including the shape:
                 // hoisted out of the branch below because the heartbeat at the end of this handler
                 // needs to know whether the turn parked.
-                const nudged = dispatchTurn.rePrompted || (sessionOpen ? this.tryAutonomousNudge(runId, state, stepId, ask, dispatchTurn) : false);
+                const nudged = dispatchTurn.rePrompted ||
+                    (!monitoring && (sessionOpen ? this.tryAutonomousNudge(runId, state, stepId, ask, dispatchTurn) : false));
                 // Compaction alone never means the user owns the next action (#955). Tried LAST, so
                 // every marker, the dispatch rules and the autonomous nudge keep their precedence —
                 // the twin of `runAgentStep`'s call, through the one helper both sites share.
@@ -3288,8 +3304,8 @@ export class RunManager {
                         // `CEZ:ASK` → park `waiting` (attention) AND surface the structured
                         // question as an ask card (#473). `CEZ:MONITORING` → non-attention
                         // `running`/`activity:'monitoring'` (#490). Both share the waiting
-                        // lifecycle (free the slot, keep the idle timer); the autonomous
-                        // nudge above still wins over either.
+                        // lifecycle (free the slot), while only plain waiting keeps the idle timer. Monitoring is
+                        // checked before the autonomous nudge, so it remains non-attention.
                         if (ask)
                             this.recordAsk(runId, sink, ask);
                         if (monitoring) {
@@ -3353,6 +3369,9 @@ export class RunManager {
                 status: 'failed',
                 error: message,
                 finishedAt: failedAt,
+                // The fresh session pinned up front was never created: leaving its id on the step
+                // would make the next Continue `--resume` a conversation that does not exist.
+                ...(sessionId === undefined ? { sessionId: undefined } : {}),
             });
             this.store.updateRun(runId, {
                 status: 'failed',
@@ -3463,7 +3482,7 @@ export class RunManager {
             additionalDirectories: agentDirectories(join(this.dataDir, 'runs'), this.grantableAttachmentLibrary(), continueProfile.env),
             env: continueProfile.env,
             model: continueModel,
-            sessionId,
+            sessionId: spawnSessionId,
             resume: sessionId !== undefined,
             timeoutMs: 0,
         }, onEvent, { onUiEvent: (event) => this.handleRunnerUiEvent(runId, state, sink, event) });
@@ -3595,27 +3614,19 @@ export class RunManager {
             });
             // Fork from the configured base branch (config.json `baseBranch`, e.g.
             // `develop`) — also the target of the eventual draft PR. Unresolvable
-            // (typo, not fetched) → note + the currently checked-out branch.
+            // (typo, not fetched) → note + the currently checked-out branch. Either
+            // way the base goes through `resolveBaseRef` (`chooseForkBase`), which
+            // fetches origin first so a new task forks from the newest tip, never a
+            // stale local ref — while a checked-out branch that diverged from origin
+            // keeps the user's local work.
             //
             // A task that already recorded a fork point keeps it: its worktree is
             // reused as-is, and re-resolving against a since-changed config would
             // silently re-anchor the `merge-base` every diff/shortstat is measured
             // from, shifting "what did this task change" under an existing task.
             const recorded = this.store.getRun(runId)?.baseBranch;
-            let base = recorded ?? repo.branch;
-            const configured = recorded ? undefined : config.baseBranch;
-            if (configured) {
-                const resolved = await resolveBaseRef(this.repoRoot, configured);
-                if (resolved) {
-                    base = resolved;
-                }
-                else {
-                    emit({
-                        type: 'note',
-                        message: `configured base branch "${configured}" not found (locally or on origin) — using "${repo.branch}"`,
-                    });
-                }
-            }
+            const base = recorded ??
+                (await chooseForkBase(this.repoRoot, repo.branch, config.baseBranch, (message) => emit({ type: 'note', message })));
             try {
                 const wt = await createWorktree(this.repoRoot, runId, base);
                 state.cwd = wt.path;
@@ -4090,7 +4101,8 @@ export class RunManager {
                 // that repeats the SAME question after being nudged sets `lastOverriddenAsk` and parks on
                 // the second ask. For every non-autonomous run `tryAutonomousNudge` returns at its first
                 // line, so the park below behaves exactly as #917 designed it.
-                const autoContinued = dispatchTurn.rePrompted || (waiting ? this.tryAutonomousNudge(runId, state, step.id, ask, dispatchTurn) : false);
+                const autoContinued = dispatchTurn.rePrompted ||
+                    (!monitoring && (waiting ? this.tryAutonomousNudge(runId, state, step.id, ask, dispatchTurn) : false));
                 // The compaction continuation (#955), through the same helper `runContinuation` calls.
                 // Deliberately NOT gated on `waiting`: that flag is about who the turn hands control
                 // to, and an ordinary intermediate step never hands control to anyone — it is closed
@@ -4108,7 +4120,7 @@ export class RunManager {
                     // still working on its own downstream work with `CEZ:MONITORING`, which
                     // parks as `running`/`activity:'monitoring'`, a non-attention state,
                     // instead of raising "needs you" (#490). Lifecycle is identical: the
-                    // run frees its slot and keeps the idle timer. The autonomous nudge
+                    // run frees its slot; only plain waiting keeps the idle timer. The autonomous nudge
                     // above still wins over either.
                     if (ask)
                         this.recordAsk(runId, sink, ask);
@@ -4902,15 +4914,19 @@ export class RunManager {
     }
     armIdleTimer(runId, state) {
         this.clearIdleTimer(state);
+        const timeoutMinutes = this.semaphore.idleTimeoutMinutes();
+        if (timeoutMinutes === null || timeoutMinutes === 0)
+            return;
+        const timeoutMs = timeoutMinutes * 60_000;
         state.idleTimer = setTimeout(() => {
             if (state.session?.open && !state.cancelled) {
                 this.store.appendEvent(runId, {
                     type: 'lifecycle',
-                    message: `session closed after ${Math.round(IDLE_TIMEOUT_MS / 60_000)}m of inactivity`,
+                    message: `session closed after ${Math.round(timeoutMs / 60_000)}m of inactivity`,
                 });
                 state.session.end();
             }
-        }, IDLE_TIMEOUT_MS);
+        }, timeoutMs);
         state.idleTimer.unref?.();
     }
     clearIdleTimer(state) {