agent-relay-orchestrator 0.91.3 → 0.92.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.91.3",
+  "version": "0.92.0",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "src/**/*.ts",
     "!src/**/*.test.ts",
+    "vendor/**",
     "README.md"
   ],
   "scripts": {
@@ -16,7 +17,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.70"
+    "agent-relay-sdk": "0.2.72"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/control.ts

@@ -4,7 +4,7 @@ import type { ManagedAgentReport, RelayClient, RelayCommand } from "./relay";
 import { handleSelfUpgrade } from "./self-upgrade";
 import { readLocalProviderConfigs } from "./provider-config-migration";
 import { spawnAgent, stopSession, type SpawnOptions } from "./spawn";
-import { cleanupWorkspace, discardRecoveryBranch, mergeWorkspace, pruneWorktrees, reconcileWorkspace, refreshWorkspaceDeps, workspacesRoot } from "./workspace-probe";
+import { cleanupWorkspace, discardRecoveryBranch, idleRefreshWorktree, mergeWorkspace, pruneWorktrees, reconcileWorkspace, refreshWorkspaceDeps, workspacesRoot } from "./workspace-probe";
 import { armWorkspacePrAutoMerge, mergeWorkspacePr, refreshWorkspacePrBranch } from "./workspace-pr";
 import type { WorkspaceMergeResult } from "agent-relay-sdk";
 
@@ -195,6 +195,16 @@ export function createControlHandler(
           force: command.params.force === true,
         });
         await relay.updateCommand(command.id, "succeeded", result as unknown as Record<string, unknown>);
+      } else if (command.type === "workspace.idle-refresh") {
+        const result = idleRefreshWorktree({
+          id: typeof command.params.workspaceId === "string" ? command.params.workspaceId : undefined,
+          repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,
+          worktreePath: typeof command.params.worktreePath === "string" ? command.params.worktreePath : undefined,
+          branch: typeof command.params.branch === "string" ? command.params.branch : undefined,
+          baseRef: typeof command.params.baseRef === "string" ? command.params.baseRef : undefined,
+          baseSha: typeof command.params.baseSha === "string" ? command.params.baseSha : undefined,
+        });
+        await relay.updateCommand(command.id, result.error ? "failed" : "succeeded", result as unknown as Record<string, unknown>, result.error);
       } else if (command.type === "workspace.prune") {
         const result = pruneWorktrees({
           repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,
@@ -289,6 +299,7 @@ function spawnOptionsFromRecord(source: Record<string, any>, config: Orchestrato
     automationId: typeof source.automationId === "string" ? source.automationId : undefined,
     automationRunId: typeof source.automationRunId === "string" ? source.automationRunId : undefined,
     requestedVia: typeof source.requestedVia === "string" ? source.requestedVia : undefined,
+    resumeWorkspace: parseResumeWorkspace(source.resumeWorkspace),
   };
 }
 
@@ -308,3 +319,18 @@ function stringRecord(value: unknown): Record<string, string> | undefined {
 function stringArray(value: unknown): string[] | undefined {
   return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : undefined;
 }
+
+function parseResumeWorkspace(value: unknown): import("./workspace-probe/types").ResumeWorkspaceTarget | undefined {
+  if (!isRecord(value)) return undefined;
+  const branch = typeof value.branch === "string" ? value.branch : undefined;
+  const mode = value.mode === "attach" || value.mode === "branch-from" ? value.mode : undefined;
+  if (!branch || !mode) return undefined;
+  return {
+    branch,
+    mode,
+    worktreePath: typeof value.worktreePath === "string" ? value.worktreePath : undefined,
+    workspaceId: typeof value.workspaceId === "string" ? value.workspaceId : undefined,
+    baseRef: typeof value.baseRef === "string" ? value.baseRef : undefined,
+    baseSha: typeof value.baseSha === "string" ? value.baseSha : undefined,
+  };
+}

package/src/index.ts

@@ -4,7 +4,7 @@ import { loadConfig, initConfigFile } from "./config";
 import { createRelayClient } from "./relay";
 import type { ManagedSessionExitDiagnostics } from "./relay";
 import { createControlHandler } from "./control";
-import { diagnoseSessionExit, hydrateTerminalGuests, isSessionAlive, reapTerminalGuests, refreshManagedAgentReport } from "./spawn";
+import { diagnoseSessionExit, hydrateTerminalGuests, managedSessionLiveness, reapTerminalGuests, refreshManagedAgentReport } from "./spawn";
 import { startApiServer } from "./api";
 import { recoverManagedAgents } from "./recovery";
 import { ProviderProbeCache } from "./provider-probe";
@@ -166,8 +166,12 @@ async function healthCheck(): Promise<void> {
       changed = true;
     }
     const sessionName = refreshed.sessionName ?? refreshed.tmuxSession;
-    const alive = isSessionAlive(sessionName);
-    if (!alive) {
+    const liveness = managedSessionLiveness(sessionName);
+    if (liveness === "unknown") {
+      console.error(`[orchestrator] Session liveness unknown: ${sessionName}; preserving and retrying next health check`);
+      continue;
+    }
+    if (liveness === "dead") {
       const diagnostics = diagnoseSessionExit({
         agentId: refreshed.agentId,
         policyName: refreshed.policyName,

package/src/shared-callmux.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { errMessage, isRecord } from "agent-relay-sdk";
 import type { OrchestratorConfig } from "./config";
 import { agentRelayHome } from "./config";
@@ -54,6 +54,15 @@ export interface SharedCallmuxSupervisorDeps {
   setTimeout(fn: () => void, ms: number): Timer;
   clearTimeout(timer: Timer): void;
   log(message: string): void;
+  report(snapshot: SharedCallmuxHealthSnapshot): void;
+}
+
+export interface SharedCallmuxHealthSnapshot {
+  state: "disabled" | "missing" | "starting" | "running" | "unhealthy" | "restarting" | "stopped";
+  url: string;
+  command?: string;
+  reason?: string;
+  pid?: number;
 }
 
 export function sharedCallmuxOptionsFromEnv(env: Record<string, string | undefined> = process.env): SharedCallmuxOptions {
@@ -63,14 +72,13 @@ export function sharedCallmuxOptionsFromEnv(env: Record<string, string | undefin
   const port = numberEnv(env[SHARED_CALLMUX_PORT_ENV]) ?? parsed?.port ?? DEFAULT_SHARED_CALLMUX_PORT;
   const url = explicitUrl ?? `http://${host}:${port}/mcp`;
   return {
-    // PATH/env-resolved callmux must be >=0.21.0; generated config uses exposeMetaTools.
-    command: env[SHARED_CALLMUX_COMMAND_ENV] || "callmux",
+    command: env[SHARED_CALLMUX_COMMAND_ENV] || bundledCallmuxCommand() || "callmux",
     host,
     port,
     url,
     configPath: env[SHARED_CALLMUX_CONFIG_ENV] || join(agentRelayHome(), "callmux", "shared-listener.json"),
     sourceConfigPath: env[SHARED_CALLMUX_SOURCE_CONFIG_ENV] || env.CALLMUX_CONFIG || join(homedir(), ".config", "callmux", "config.json"),
-    enabled: env[SHARED_CALLMUX_ENABLE_ENV] === "1",
+    enabled: !envOff(env[SHARED_CALLMUX_ENABLE_ENV]),
   };
 }
 
@@ -118,14 +126,17 @@ export class SharedCallmuxSupervisor {
 
   start(): void {
     if (!this.opts.enabled) {
-      this.deps.log("[orchestrator] shared callmux listener disabled (set AGENT_RELAY_SHARED_CALLMUX_ENABLE=1 to enable)");
+      this.deps.log("[orchestrator] shared callmux listener disabled by AGENT_RELAY_SHARED_CALLMUX_ENABLE=0");
+      this.report("disabled", "global kill-switch");
       return;
     }
     this.deps.log(`[orchestrator] Shared callmux listener: ${this.opts.url}`);
     if (!this.deps.which(this.opts.command)) {
       this.deps.log("[orchestrator] shared callmux not found — shared listener dormant");
+      this.report("missing", "command not found");
       return;
     }
+    this.report("starting");
     this.spawn();
     this.healthTimer = this.deps.setInterval(() => {
       void this.checkHealth();
@@ -156,9 +167,11 @@ export class SharedCallmuxSupervisor {
     }
     if (ok) {
       this.backoffMs = this.timing.restartBaseMs ?? 1_000;
+      this.report("running", undefined, this.proc?.pid);
       return true;
     }
     this.deps.log(`[orchestrator] Shared callmux readiness failed at ${readyUrl}; restarting`);
+    this.report("unhealthy", "readiness failed", this.proc?.pid);
     this.restart("readiness failed");
     return false;
   }
@@ -177,20 +190,24 @@ export class SharedCallmuxSupervisor {
       proc = this.deps.spawn(this.opts.command, args, { env, cwd: homedir() });
     } catch (err) {
       this.deps.log(`[orchestrator] Shared callmux listener failed to start: ${errMessage(err)}; scheduling restart`);
+      this.report("restarting", errMessage(err));
       this.scheduleRestart();
       return;
     }
     this.proc = proc;
     this.deps.log(`[orchestrator] Started shared callmux listener pid=${proc.pid ?? "unknown"}`);
+    this.report("running", undefined, proc.pid);
     proc.exited.then((code) => {
       if (this.proc !== proc || this.stopping) return;
       this.proc = null;
       this.deps.log(`[orchestrator] Shared callmux listener exited (${code ?? "signal"}); scheduling restart`);
+      this.report("restarting", `exited ${code ?? "signal"}`);
       this.scheduleRestart();
     }).catch((err) => {
       if (this.proc !== proc || this.stopping) return;
       this.proc = null;
       this.deps.log(`[orchestrator] Shared callmux listener exit watcher failed: ${err}`);
+      this.report("restarting", errMessage(err));
       this.scheduleRestart();
     });
   }
@@ -201,9 +218,20 @@ export class SharedCallmuxSupervisor {
       this.proc.kill("SIGTERM");
       this.proc = null;
     }
+    this.report("restarting", reason);
     this.scheduleRestart();
   }
 
+  private report(state: SharedCallmuxHealthSnapshot["state"], reason?: string, pid?: number): void {
+    this.deps.report({
+      state,
+      url: this.opts.url,
+      command: this.opts.command,
+      ...(reason ? { reason } : {}),
+      ...(pid ? { pid } : {}),
+    });
+  }
+
   private scheduleRestart(): void {
     if (this.stopping || this.restartTimer) return;
     const delay = this.backoffMs;
@@ -238,15 +266,26 @@ function defaultDeps(): SharedCallmuxSupervisorDeps {
     setTimeout: (fn, ms) => setTimeout(fn, ms),
     clearTimeout: (timer) => clearTimeout(timer),
     log: (message) => console.error(message),
+    report: (snapshot) => console.error(`[orchestrator] shared callmux status ${snapshot.state}${snapshot.reason ? `: ${snapshot.reason}` : ""}`),
   };
 }
 
+export function bundledCallmuxCommand(): string | null {
+  const candidate = resolve(import.meta.dir, "../vendor/callmux/bin/callmux.js");
+  return existsSync(candidate) ? candidate : null;
+}
+
 function resolveCommand(command: string): string | null {
   if (isAbsolute(command)) return existsSync(command) ? command : null;
   if (command.includes("/")) return existsSync(command) ? command : null;
   return Bun.which(command);
 }
 
+function envOff(value: string | undefined): boolean {
+  if (value === undefined || value === null || value === "") return false;
+  return ["0", "false", "off", "no"].includes(value.trim().toLowerCase());
+}
+
 function readJsonObject(path: string): Record<string, unknown> {
   if (!existsSync(path)) return {};
   const parsed = JSON.parse(readFileSync(path, "utf8"));

package/src/spawn/runtime.ts

@@ -5,7 +5,7 @@ import type { ManagedAgentReport } from "../relay";
 import { isPidAlive, parseProcStateIsZombie } from "agent-relay-sdk/process-utils";
 import { tmuxHasSession } from "agent-relay-sdk/tmux-utils";
 import { LOG_DIR, RUNNER_INFO_DIR, SESSION_DIR, STATE_FILE } from "./constants";
-import { systemdMainPid } from "./systemd";
+import { systemdMainPid, systemdUnitLiveness, type SystemdUnitLiveness } from "./systemd";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import type { RunnerInfo, SessionRecord, SessionSupervisor } from "./types";
 
@@ -66,12 +66,15 @@ export function sessionSupervisor(record?: Pick<SessionRecord, "supervisor">): S
 }
 
 export function isSessionRecordAlive(record: SessionRecord): boolean {
+  return sessionRecordLiveness(record) === "alive";
+}
+
+export function sessionRecordLiveness(record: SessionRecord): SystemdUnitLiveness {
   const supervisor = sessionSupervisor(record);
   if (supervisor.type === "systemd" && supervisor.unit) {
-    const pid = systemdMainPid(supervisor.unit);
-    return pid > 0 && isPidAlive(pid);
+    return systemdUnitLiveness(supervisor.unit);
   }
-  return isPidAlive(record.pid);
+  return isPidAlive(record.pid) ? "alive" : "dead";
 }
 
 export function currentSessionPid(record: SessionRecord): number {

package/src/spawn/sessions.ts

@@ -4,7 +4,7 @@ import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { shellEscape } from "agent-relay-sdk/shell-utils";
 import { tmuxHasSession } from "agent-relay-sdk/tmux-utils";
 import { cleanupSessionRecord } from "./supervisor";
-import { currentSessionPid, findSessionRecord, isSessionRecordAlive, loadState, readRunnerInfo, saveState, sessionReportFields, sessionSupervisor } from "./runtime";
+import { currentSessionPid, findSessionRecord, isSessionRecordAlive, loadState, readRunnerInfo, saveState, sessionRecordLiveness, sessionReportFields, sessionSupervisor } from "./runtime";
 import type { SessionInfo, SessionRecord } from "./types";
 
 export function listSessions(prefix: string): SessionInfo[] {
@@ -31,6 +31,11 @@ export function isSessionAlive(name: string): boolean {
   return record ? isSessionRecordAlive(record) : false;
 }
 
+export function managedSessionLiveness(name: string): "alive" | "dead" | "unknown" {
+  const record = loadState().find((r) => r.name === name);
+  return record ? sessionRecordLiveness(record) : "dead";
+}
+
 export function refreshManagedAgentReport(agent: ManagedAgentReport): ManagedAgentReport {
   const record = findSessionRecord({
     tmuxSession: agent.sessionName ?? agent.tmuxSession,
@@ -56,7 +61,10 @@ export async function recoverExistingSessions(
   const alive: SessionRecord[] = [];
 
   for (const record of records) {
-    if (!isSessionRecordAlive(record)) {
+    const liveness = sessionRecordLiveness(record);
+    if (liveness === "unknown") {
+      console.error(`[orchestrator] Session liveness unknown: ${record.name} (pid ${record.pid}) — preserving`);
+    } else if (liveness === "dead") {
       console.error(`[orchestrator] Stale session: ${record.name} (pid ${record.pid} dead) — removing`);
       cleanupSessionRecord(record);
       continue;

package/src/spawn/supervisor.ts

@@ -11,7 +11,7 @@ import { SESSION_DIR } from "./constants";
 import { disableSystemdSupervisor, forceSystemdSupervisor } from "../config";
 import { logLines } from "./log-utils";
 import { currentSessionPid, ensureSessionDir, findSessionRecord, isSessionRecordAlive, loadState, logFilePath, readRunnerInfo, removeSessionRecord, sessionSupervisor } from "./runtime";
-import { systemdMainPid, systemdUnitName } from "./systemd";
+import { systemdMainPid, systemdUnitDiagnostics, systemdUnitName } from "./systemd";
 import type { SessionRecord, SessionSupervisor, SpawnedRunner } from "./types";
 
 export function spawnRunner(name: string, command: string[], cwd: string, env: Record<string, string>, logFile: string): SpawnedRunner {
@@ -123,44 +123,6 @@ function waitForSystemdMainPid(unit: string, timeoutMs: number): number {
   return 0;
 }
 
-function systemdUnitDiagnostics(unit: string): NonNullable<ManagedSessionExitDiagnostics["systemd"]> {
-  const result = Bun.spawnSync([
-    "systemctl", "--user", "show", `${unit}.service`,
-    "-p", "ActiveState",
-    "-p", "SubState",
-    "-p", "Result",
-    "-p", "ExecMainCode",
-    "-p", "ExecMainStatus",
-    "-p", "MainPID",
-  ], {
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  if (result.exitCode !== 0) {
-    return {
-      unit,
-      unavailable: result.stderr.toString().trim() || `systemctl show exited with ${result.exitCode}`,
-    };
-  }
-  const props = new Map<string, string>();
-  for (const line of result.stdout.toString().split("\n")) {
-    const index = line.indexOf("=");
-    if (index <= 0) continue;
-    props.set(line.slice(0, index), line.slice(index + 1));
-  }
-  const mainPid = Number(props.get("MainPID"));
-  return {
-    unit,
-    activeState: props.get("ActiveState") || undefined,
-    subState: props.get("SubState") || undefined,
-    result: props.get("Result") || undefined,
-    execMainCode: props.get("ExecMainCode") || undefined,
-    execMainStatus: props.get("ExecMainStatus") || undefined,
-    mainPid: Number.isFinite(mainPid) && mainPid > 0 ? mainPid : undefined,
-  };
-}
-
 function logFileDiagnostics(logFile: string): Pick<ManagedSessionExitDiagnostics, "logBytes" | "logEmpty" | "logTail"> & { logUnavailable?: string } {
   try {
     const stat = statSync(logFile);

package/src/spawn/systemd.ts

@@ -1,17 +1,84 @@
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import { isPidAlive } from "agent-relay-sdk/process-utils";
+
+export type SystemdUnitLiveness = "alive" | "dead" | "unknown";
+
+export interface SystemdUnitDiagnostics {
+  unit: string;
+  activeState?: string;
+  subState?: string;
+  result?: string;
+  execMainCode?: string;
+  execMainStatus?: string;
+  mainPid?: number;
+  unavailable?: string;
+}
 
 export function systemdUnitName(session: string): string {
   const safe = sanitizeFsName(session, { replacement: "-", trimEdge: true, fallback: "agent" });
   return `agent-relay-managed-${safe}`.slice(0, 180);
 }
 
-export function systemdMainPid(unit: string): number {
-  const result = Bun.spawnSync(["systemctl", "--user", "show", `${unit}.service`, "-p", "MainPID", "--value"], {
+export function systemdUnitDiagnostics(unit: string): SystemdUnitDiagnostics {
+  const result = Bun.spawnSync([
+    "systemctl", "--user", "show", `${unit}.service`,
+    "-p", "ActiveState",
+    "-p", "SubState",
+    "-p", "Result",
+    "-p", "ExecMainCode",
+    "-p", "ExecMainStatus",
+    "-p", "MainPID",
+  ], {
     stdin: "ignore",
     stdout: "pipe",
-    stderr: "ignore",
+    stderr: "pipe",
   });
-  if (result.exitCode !== 0) return 0;
-  const pid = Number(result.stdout.toString().trim());
-  return Number.isFinite(pid) ? pid : 0;
+  if (result.exitCode !== 0) {
+    return {
+      unit,
+      unavailable: result.stderr.toString().trim() || `systemctl show exited with ${result.exitCode}`,
+    };
+  }
+  const props = new Map<string, string>();
+  for (const line of result.stdout.toString().split("\n")) {
+    const index = line.indexOf("=");
+    if (index <= 0) continue;
+    props.set(line.slice(0, index), line.slice(index + 1));
+  }
+  const mainPid = Number(props.get("MainPID"));
+  return {
+    unit,
+    activeState: props.get("ActiveState") || undefined,
+    subState: props.get("SubState") || undefined,
+    result: props.get("Result") || undefined,
+    execMainCode: props.get("ExecMainCode") || undefined,
+    execMainStatus: props.get("ExecMainStatus") || undefined,
+    mainPid: Number.isFinite(mainPid) && mainPid > 0 ? mainPid : undefined,
+  };
+}
+
+export function systemdUnitLivenessFromDiagnostics(
+  diagnostics: SystemdUnitDiagnostics,
+  isAlive: (pid: number) => boolean,
+): SystemdUnitLiveness {
+  if (diagnostics.mainPid && isAlive(diagnostics.mainPid)) return "alive";
+  if (diagnostics.unavailable) return "unknown";
+
+  const activeState = diagnostics.activeState?.toLowerCase();
+  const subState = diagnostics.subState?.toLowerCase();
+  if (activeState === "inactive" || activeState === "failed" || subState === "dead" || subState === "failed") {
+    return "dead";
+  }
+  if (activeState === "active" || activeState === "activating" || activeState === "reloading" || activeState === "deactivating") {
+    return "unknown";
+  }
+  return "unknown";
+}
+
+export function systemdUnitLiveness(unit: string): SystemdUnitLiveness {
+  return systemdUnitLivenessFromDiagnostics(systemdUnitDiagnostics(unit), isPidAlive);
+}
+
+export function systemdMainPid(unit: string): number {
+  return systemdUnitDiagnostics(unit).mainPid ?? 0;
 }

package/src/spawn/types.ts

@@ -1,5 +1,6 @@
 import type { OrchestratorConfig } from "../config";
 import type { AgentLifecycle, WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
+import type { ResumeWorkspaceTarget } from "../workspace-probe/types";
 
 export interface SpawnOptions {
   provider: "claude" | "codex";
@@ -29,6 +30,8 @@ export interface SpawnOptions {
   /** How the spawn was requested (`mcp` = an agent via the MCP surface, else dashboard/CLI). Drives
    * the origin tag so an MCP-spawned worker isn't mislabeled `dashboard-spawned` (#330). */
   requestedVia?: string;
+  /** #635 — attach to or branch off an existing worktree instead of creating a fresh one. */
+  resumeWorkspace?: ResumeWorkspaceTarget;
 }
 
 export interface SessionInfo {

package/src/workspace-probe/idle-refresh.ts

@@ -0,0 +1,110 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { git } from "../git";
+import { refreshWorkspaceDeps } from "./deps";
+import { syncBaseFromOrigin } from "./git-state";
+import { nextBranchName } from "./names";
+import { shortBranch } from "./parse";
+import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
+
+export interface IdleRefreshResult {
+  workspaceId?: string;
+  /** True when the worktree was successfully refreshed to origin/main. */
+  refreshed: boolean;
+  /** New branch name after refresh (`nextBranchName` --N). Present when `refreshed`. */
+  newBranch?: string;
+  /** SHA of origin/main the worktree now sits on. Present when `refreshed`. */
+  baseSha?: string;
+  /** Human-readable skip reason when `refreshed` is false and there is no error. */
+  reason?: string;
+  /** Git/system error that prevented the refresh. */
+  error?: string;
+  depsRefresh?: WorkspaceDepsRefreshResult;
+}
+
+/**
+ * Proactively refresh an idle branch-agent worktree to the current upstream tip
+ * (origin/main or equivalent), making it current before the agent's next turn.
+ *
+ * Safety predicates — ALL must hold before the worktree is touched:
+ *   1. Worktree is clean (zero uncommitted/untracked changes, re-verified live).
+ *   2. No commits ahead of base (nothing to lose on a branch reset).
+ *   3. A remote upstream is configured for the base branch (we know who to follow).
+ *   4. HEAD is an ancestor of the upstream tip (FF-only; divergence = skip).
+ *   5. HEAD is not already AT the upstream tip (skip if already current).
+ *
+ * On success: `checkout -B <fresh> <upstream>`, old branch deleted, deps refreshed.
+ * On any predicate failure: returns `{ refreshed: false, reason }` — never mutates.
+ */
+export function idleRefreshWorktree(input: {
+  id?: string;
+  worktreePath?: string;
+  repoRoot?: string;
+  branch?: string;
+  baseRef?: string;
+  baseSha?: string;
+}): IdleRefreshResult {
+  if (!input.worktreePath) return { refreshed: false, error: "worktreePath required" };
+  const worktreePath = resolve(input.worktreePath);
+  if (!existsSync(worktreePath)) return { workspaceId: input.id, refreshed: false, reason: "worktree missing" };
+  const repoRoot = input.repoRoot ? resolve(input.repoRoot) : worktreePath;
+
+  // Predicate 1: re-check live dirty count (stored metadata may be stale).
+  const status = git(["status", "--porcelain"], worktreePath);
+  if (!status.ok) return { workspaceId: input.id, refreshed: false, error: status.stderr || "git status failed" };
+  const dirty = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
+  if (dirty > 0) return { workspaceId: input.id, refreshed: false, reason: "worktree has uncommitted changes" };
+
+  const base = input.baseRef;
+  if (!base) return { workspaceId: input.id, refreshed: false, reason: "no base ref" };
+
+  // Predicate 2: no commits ahead of base.
+  const countResult = git(["rev-list", "--count", `${base}..HEAD`], worktreePath);
+  const ahead = countResult.ok ? Number(countResult.stdout.trim()) : NaN;
+  if (!Number.isFinite(ahead)) return { workspaceId: input.id, refreshed: false, reason: "could not determine ahead count" };
+  if (ahead > 0) return { workspaceId: input.id, refreshed: false, reason: "workspace has commits ahead of base" };
+
+  // Predicate 3: fetch origin and resolve an upstream ref.
+  const startRef = syncBaseFromOrigin(worktreePath, base);
+  if (!startRef || startRef === base) {
+    return { workspaceId: input.id, refreshed: false, reason: "no upstream configured for base branch" };
+  }
+
+  // Predicate 5: skip if already current (HEAD SHA == upstream tip).
+  const headSha = git(["rev-parse", "HEAD"], worktreePath).stdout.trim();
+  const upstreamSha = git(["rev-parse", startRef], worktreePath).stdout.trim();
+  if (headSha && headSha === upstreamSha) {
+    return { workspaceId: input.id, refreshed: false, reason: "already current with origin" };
+  }
+
+  // Predicate 4: FF-only guard — HEAD must be an ancestor of the upstream tip.
+  // If not, the base has diverged; leave it for the conflict scan.
+  if (!git(["merge-base", "--is-ancestor", "HEAD", startRef], worktreePath).ok) {
+    return { workspaceId: input.id, refreshed: false, reason: "diverged from origin — leaving for conflict scan" };
+  }
+
+  // All predicates passed — safe to advance.
+  const liveBranch = shortBranch(git(["symbolic-ref", "--quiet", "--short", "HEAD"], worktreePath).stdout || undefined);
+  const branch = liveBranch ?? input.branch;
+  if (!branch) return { workspaceId: input.id, refreshed: false, reason: "could not determine current branch" };
+
+  const fresh = nextBranchName(repoRoot, branch);
+  if (!git(["checkout", "-B", fresh, startRef], worktreePath).ok) {
+    return { workspaceId: input.id, refreshed: false, error: "git checkout failed" };
+  }
+
+  // Old branch is now orphaned (no commits of its own) — safe to delete.
+  git(["branch", "-D", branch], repoRoot);
+
+  const baseSha = git(["rev-parse", "HEAD"], worktreePath).stdout.trim() || undefined;
+  const depsRefresh = refreshWorkspaceDeps(repoRoot, worktreePath);
+  const reportDeps = depsRefresh.refreshed || depsRefresh.stale || depsRefresh.error;
+
+  return {
+    workspaceId: input.id,
+    refreshed: true,
+    newBranch: fresh,
+    ...(baseSha ? { baseSha } : {}),
+    ...(reportDeps ? { depsRefresh } : {}),
+  };
+}

package/src/workspace-probe/index.ts

@@ -1,5 +1,6 @@
 export * from "./cleanup";
 export * from "./deps";
+export * from "./idle-refresh";
 export * from "./git-state";
 export * from "./merge";
 export * from "./names";

package/src/workspace-probe/merge.ts

@@ -373,7 +373,11 @@ function resolveNoopMerge(
     const base = preview.baseRef;
     if (base && branch) {
       const fresh = nextBranchName(repoRoot, branch);
-      const start = startRef ?? base;
+      // #478 — cut from the FETCHED upstream tip so even a plain noop recycle (no
+      // startRef) advances to origin/main, not the stale local base. The PR-land
+      // recycle (#423) already passes startRef (the verified upstream sha); this
+      // makes the rebase-ff noop path equally multi-host-correct.
+      const start = startRef ?? syncBaseFromOrigin(worktreePath, base) ?? base;
       if (git(["checkout", "-B", fresh, start], worktreePath).ok) {
         // Old branch's tree is already in base (that's what noop means) — safe to drop.
         const oldDeleted = git(["branch", "-D", branch], repoRoot).ok;