@cocorograph/hub-agent 0.8.48 → 0.8.50

package/src/codex-workspace-dependencies.mjs

@@ -0,0 +1,331 @@
+import { constants as fsConstants } from "node:fs"
+import { access, readFile, realpath, stat } from "node:fs/promises"
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+import os from "node:os"
+import path from "node:path"
+
+export const CODEX_PRIMARY_RUNTIME_BUNDLE_FORMAT = 2
+const execFileAsync = promisify(execFile)
+
+export class CodexWorkspaceDependenciesError extends Error {
+  constructor(code, message, options = {}) {
+    super(message, options)
+    this.name = "CodexWorkspaceDependenciesError"
+    this.code = code
+  }
+}
+
+function fail(code, message, cause) {
+  throw new CodexWorkspaceDependenciesError(code, message, cause ? { cause } : undefined)
+}
+
+function resolveRuntimeRoot(runtimeRootOverride, homedirImpl) {
+  if (runtimeRootOverride !== undefined) {
+    if (typeof runtimeRootOverride !== "string" || !path.isAbsolute(runtimeRootOverride)) {
+      fail("CODEX_RUNTIME_ROOT_INVALID", "runtimeRootOverride must be an absolute path")
+    }
+    return runtimeRootOverride
+  }
+
+  const home = homedirImpl()
+  if (typeof home !== "string" || !path.isAbsolute(home)) {
+    fail("CODEX_RUNTIME_ROOT_INVALID", "OS home directory must be an absolute path")
+  }
+  return path.join(home, ".cache", "codex-runtimes", "codex-primary-runtime")
+}
+
+function requireNonemptyString(manifest, field, { optional = false } = {}) {
+  const value = manifest[field]
+  if (optional && value === undefined) return null
+  if (typeof value !== "string" || value.trim() === "") {
+    fail("CODEX_RUNTIME_MANIFEST_INVALID", `Codex primary runtime manifest field ${field} must be a nonempty string`)
+  }
+  return value
+}
+
+function requireNativeDependencies(manifest) {
+  if (manifest.nativeDependencies === undefined) return []
+  if (
+    !Array.isArray(manifest.nativeDependencies)
+    || manifest.nativeDependencies.some((item) => typeof item !== "string" || item.trim() === "")
+  ) {
+    fail(
+      "CODEX_RUNTIME_MANIFEST_INVALID",
+      "Codex primary runtime manifest field nativeDependencies must be an array of nonempty strings",
+    )
+  }
+  return manifest.nativeDependencies
+}
+
+async function readManifest(manifestPath, readFileImpl) {
+  let raw
+  try {
+    raw = await readFileImpl(manifestPath, "utf8")
+  } catch (error) {
+    const code = error?.code === "ENOENT"
+      ? "CODEX_RUNTIME_MANIFEST_MISSING"
+      : "CODEX_RUNTIME_MANIFEST_UNREADABLE"
+    fail(code, "Codex primary runtime manifest is not readable", error)
+  }
+
+  try {
+    const manifest = JSON.parse(raw)
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+      fail("CODEX_RUNTIME_MANIFEST_INVALID", "Codex primary runtime manifest must be a JSON object")
+    }
+    return manifest
+  } catch (error) {
+    if (error instanceof CodexWorkspaceDependenciesError) throw error
+    fail("CODEX_RUNTIME_MANIFEST_INVALID_JSON", "Codex primary runtime manifest is not valid JSON", error)
+  }
+}
+
+async function requireFile(candidate, label, statImpl) {
+  try {
+    if ((await statImpl(candidate)).isFile()) return
+  } catch (error) {
+    fail("CODEX_RUNTIME_PATH_MISSING", `${label} is missing or inaccessible`, error)
+  }
+  fail("CODEX_RUNTIME_PATH_INVALID", `${label} must be a file`)
+}
+
+async function requireDirectory(candidate, label, statImpl) {
+  try {
+    if ((await statImpl(candidate)).isDirectory()) return
+  } catch (error) {
+    fail("CODEX_RUNTIME_PATH_MISSING", `${label} is missing or inaccessible`, error)
+  }
+  fail("CODEX_RUNTIME_PATH_INVALID", `${label} must be a directory`)
+}
+
+async function requireExecutableFile(candidate, label, executableErrorCode, statImpl, accessImpl) {
+  await requireFile(candidate, label, statImpl)
+  try {
+    await accessImpl(candidate, fsConstants.X_OK)
+  } catch (error) {
+    fail(executableErrorCode, `${label} is not executable`, error)
+  }
+}
+
+function isWithinRoot(candidate, root) {
+  const relative = path.relative(root, candidate)
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))
+}
+
+async function requireContainedRealPath(candidate, label, realRuntimeRoot, realpathImpl) {
+  let resolved
+  try {
+    resolved = await realpathImpl(candidate)
+  } catch (error) {
+    fail("CODEX_RUNTIME_PATH_MISSING", `${label} is missing or inaccessible`, error)
+  }
+  if (typeof resolved !== "string" || !path.isAbsolute(resolved)) {
+    fail("CODEX_RUNTIME_PATH_INVALID", `${label} real path must be absolute`)
+  }
+  if (!isWithinRoot(resolved, realRuntimeRoot)) {
+    fail("CODEX_RUNTIME_PATH_OUTSIDE_ROOT", `${label} resolves outside the Codex primary runtime root`)
+  }
+  return resolved
+}
+
+async function requireContainedManifestPath(manifestPath, realRuntimeRoot, realpathImpl) {
+  let resolved
+  try {
+    resolved = await realpathImpl(manifestPath)
+  } catch (error) {
+    const code = error?.code === "ENOENT"
+      ? "CODEX_RUNTIME_MANIFEST_MISSING"
+      : "CODEX_RUNTIME_MANIFEST_UNREADABLE"
+    fail(code, "Codex primary runtime manifest is not accessible", error)
+  }
+  if (typeof resolved !== "string" || !path.isAbsolute(resolved)) {
+    fail("CODEX_RUNTIME_PATH_INVALID", "Codex primary runtime manifest real path must be absolute")
+  }
+  if (!isWithinRoot(resolved, realRuntimeRoot)) {
+    fail(
+      "CODEX_RUNTIME_PATH_OUTSIDE_ROOT",
+      "Codex primary runtime manifest resolves outside the Codex primary runtime root",
+    )
+  }
+  return resolved
+}
+
+function childEnvWithoutExternalLanguagePaths(env) {
+  const childEnv = { ...env }
+  delete childEnv.NODE_OPTIONS
+  delete childEnv.NODE_PATH
+  delete childEnv.PYTHONHOME
+  delete childEnv.PYTHONPATH
+  return childEnv
+}
+
+/**
+ * Codex standard primary runtime の絶対パスを検証して返す。
+ *
+ * runtime.json 以外から版や配置を推測せず、ローカル npm・system Node・PATH へ
+ * fallback しない。runtimeRoot 自体のsymlinkは追従し、そのrealpathをcontainment rootとする。
+ * host側は成功・失敗をそれぞれ短期cacheするが、cache miss時はここで実体を再検証する。
+ */
+export async function resolveCodexWorkspaceDependencies({
+  env = process.env,
+  platform = process.platform,
+  arch = process.arch,
+  runtimeRootOverride,
+  homedirImpl = os.homedir,
+  readFileImpl = readFile,
+  realpathImpl = realpath,
+  statImpl = stat,
+  accessImpl = access,
+  execFileImpl = execFileAsync,
+} = {}) {
+  const runtimeRoot = resolveRuntimeRoot(runtimeRootOverride, homedirImpl)
+  const manifestPath = path.join(runtimeRoot, "runtime.json")
+  let realRuntimeRoot
+  try {
+    realRuntimeRoot = await realpathImpl(runtimeRoot)
+  } catch (error) {
+    fail("CODEX_RUNTIME_ROOT_UNREADABLE", "Codex primary runtime root is not accessible", error)
+  }
+  if (!path.isAbsolute(realRuntimeRoot)) {
+    fail("CODEX_RUNTIME_ROOT_INVALID", "Codex primary runtime real path must be absolute")
+  }
+  // manifestの内容を読む前に、symlinkを含む実体がruntime root内にあることを確認する。
+  await requireContainedManifestPath(manifestPath, realRuntimeRoot, realpathImpl)
+  const manifest = await readManifest(manifestPath, readFileImpl)
+
+  if (manifest.bundleFormatVersion !== CODEX_PRIMARY_RUNTIME_BUNDLE_FORMAT) {
+    fail(
+      "CODEX_RUNTIME_BUNDLE_FORMAT_UNSUPPORTED",
+      `Unsupported Codex primary runtime bundle format: ${String(manifest.bundleFormatVersion)}`,
+    )
+  }
+  if (manifest.targetPlatform !== platform) {
+    fail("CODEX_RUNTIME_PLATFORM_MISMATCH", "Codex primary runtime target platform does not match this process")
+  }
+  if (manifest.targetArch !== arch) {
+    fail("CODEX_RUNTIME_ARCH_MISMATCH", "Codex primary runtime target architecture does not match this process")
+  }
+  if (platform === "win32") {
+    fail(
+      "CODEX_RUNTIME_PLATFORM_UNSUPPORTED",
+      "Codex primary runtime layout for Windows is not supported by this resolver",
+    )
+  }
+
+  const bundleVersion = requireNonemptyString(manifest, "bundleVersion")
+  requireNonemptyString(manifest, "nodeVersion")
+  requireNonemptyString(manifest, "pythonVersion")
+  requireNonemptyString(manifest, "artifactToolVersion")
+  const pnpmVersion = requireNonemptyString(manifest, "pnpmVersion", { optional: true })
+  const nativeDependencies = requireNativeDependencies(manifest)
+
+  const runtimeNode = path.join(runtimeRoot, "dependencies", "node", "bin", "node")
+  const runtimeNodeModules = path.join(runtimeRoot, "dependencies", "node", "node_modules")
+  const runtimeBinDir = path.join(runtimeRoot, "dependencies", "bin", "override")
+  const runtimePython = path.join(runtimeRoot, "dependencies", "python", "bin", "python3")
+  const runtimePythonPackages = path.join(runtimeRoot, "dependencies", "python")
+  const runtimeFallbackBinDir = path.join(runtimeRoot, "dependencies", "bin", "fallback")
+  const runtimePnpm = pnpmVersion ? path.join(runtimeFallbackBinDir, "pnpm") : null
+  const runtimeGit = nativeDependencies.includes("git") ? path.join(runtimeFallbackBinDir, "git") : null
+
+  for (const [candidate, label] of [
+    [runtimeNode, "Bundled runtime Node"],
+    [runtimeNodeModules, "Bundled runtime node_modules"],
+    [runtimeBinDir, "Bundled runtime binary directory"],
+    [runtimePython, "Bundled runtime Python"],
+    [runtimePythonPackages, "Bundled runtime Python packages"],
+    [runtimeFallbackBinDir, "Bundled runtime fallback binary directory"],
+    [runtimePnpm, "Bundled runtime pnpm"],
+    [runtimeGit, "Bundled runtime git"],
+  ]) {
+    if (candidate) await requireContainedRealPath(candidate, label, realRuntimeRoot, realpathImpl)
+  }
+
+  await requireExecutableFile(
+    runtimeNode,
+    "Bundled runtime Node",
+    "CODEX_RUNTIME_NODE_NOT_EXECUTABLE",
+    statImpl,
+    accessImpl,
+  )
+  await requireDirectory(runtimeNodeModules, "Bundled runtime node_modules", statImpl)
+  await requireDirectory(runtimeBinDir, "Bundled runtime binary directory", statImpl)
+  await requireExecutableFile(
+    runtimePython,
+    "Bundled runtime Python",
+    "CODEX_RUNTIME_PYTHON_NOT_EXECUTABLE",
+    statImpl,
+    accessImpl,
+  )
+  await requireDirectory(runtimePythonPackages, "Bundled runtime Python packages", statImpl)
+  await requireDirectory(runtimeFallbackBinDir, "Bundled runtime fallback binary directory", statImpl)
+  if (runtimePnpm) {
+    await requireExecutableFile(
+      runtimePnpm,
+      "Bundled runtime pnpm",
+      "CODEX_RUNTIME_PNPM_NOT_EXECUTABLE",
+      statImpl,
+      accessImpl,
+    )
+  }
+  if (runtimeGit) {
+    await requireExecutableFile(
+      runtimeGit,
+      "Bundled runtime git",
+      "CODEX_RUNTIME_GIT_NOT_EXECUTABLE",
+      statImpl,
+      accessImpl,
+    )
+  }
+
+  const runtimeChildEnv = childEnvWithoutExternalLanguagePaths(env)
+
+  try {
+    await execFileImpl(
+      runtimeNode,
+      ["--input-type=module", "--eval", "await import('@oai/artifact-tool')"],
+      {
+        cwd: path.dirname(runtimeNodeModules),
+        env: runtimeChildEnv,
+        encoding: "utf8",
+        timeout: 15_000,
+        maxBuffer: 64 * 1024,
+        killSignal: "SIGKILL",
+        windowsHide: true,
+      },
+    )
+  } catch (error) {
+    fail("CODEX_RUNTIME_ARTIFACT_TOOL_UNAVAILABLE", "Bundled @oai/artifact-tool could not be imported", error)
+  }
+
+  try {
+    await execFileImpl(
+      runtimePython,
+      ["-I", "-c", "import docx"],
+      {
+        cwd: runtimePythonPackages,
+        env: runtimeChildEnv,
+        encoding: "utf8",
+        timeout: 15_000,
+        maxBuffer: 64 * 1024,
+        killSignal: "SIGKILL",
+        windowsHide: true,
+      },
+    )
+  } catch (error) {
+    fail("CODEX_RUNTIME_DOCUMENTS_PYTHON_UNAVAILABLE", "Bundled Python could not import docx", error)
+  }
+
+  return {
+    bundleVersion,
+    gitPath: runtimeGit,
+    nodePath: runtimeNode,
+    nodeModulesPath: runtimeNodeModules,
+    pnpmPath: runtimePnpm,
+    pythonPath: runtimePython,
+    pythonLibrariesPath: runtimePythonPackages,
+    overrideBinPath: runtimeBinDir,
+    fallbackBinPath: runtimeFallbackBinDir,
+  }
+}

package/src/main.mjs

@@ -748,6 +748,112 @@ export async function handleBundleSyncRequest(msg, ctx, opts = {}) {
   }
 }
 
+/**
+ * deferred restart の待機状態を一元管理する。要求は同期的に pending 化して即 ACK でき、
+ * Claude/Codex bridge が追跡する turn・queue・command・subagent/background task が
+ * idle → settle → 再確認の後だけ通常 shutdown へ進む。upload/bundle sync はこの
+ * bridge work 契約に含まれず、再送可能な別経路として扱う。
+ */
+export class DeferredRestartCoordinator {
+  constructor({
+    claudeBridge,
+    codexBridge,
+    shutdown,
+    logger,
+    settleMs = 500,
+    pollMs = 50,
+    setTimer = setTimeout,
+    clearTimer = clearTimeout,
+    lifecycle = { restartPending: false, shutdownStarted: false },
+    workProviders = [],
+  } = {}) {
+    this.claudeBridge = claudeBridge
+    this.codexBridge = codexBridge
+    this.shutdown = shutdown
+    this.logger = logger
+    this.settleMs = settleMs
+    this.pollMs = pollMs
+    this.setTimer = setTimer
+    this.clearTimer = clearTimer
+    this.lifecycle = lifecycle
+    this.workProviders = workProviders
+    this.timer = null
+    this.settling = false
+    this.workCheckFailures = 0
+    this.shutdownInvoked = false
+  }
+
+  request() {
+    if (!this.lifecycle.restartPending) {
+      this.lifecycle.restartPending = true
+      this.logger?.info?.({}, "deferred restart accepted")
+      this._schedule(0)
+    }
+    return { ok: true, restart_pending: true }
+  }
+
+  _hasActiveWork() {
+    return !!(
+      this.claudeBridge?.hasActiveWork?.() ||
+      this.codexBridge?.hasActiveWork?.() ||
+      this.workProviders.some((provider) => provider?.hasActiveWork?.())
+    )
+  }
+
+  _schedule(delayMs) {
+    if (this.timer || this.shutdownInvoked || this.lifecycle.shutdownStarted) return
+    this.timer = this.setTimer(() => {
+      this.timer = null
+      void this._check()
+    }, delayMs)
+  }
+
+  async _check() {
+    if (!this.lifecycle.restartPending || this.shutdownInvoked || this.lifecycle.shutdownStarted) return
+    let active
+    try {
+      active = this._hasActiveWork()
+    } catch (err) {
+      // 判定不能時に停止へ倒すと作業を切るため、安全側に待って再試行する。
+      this.workCheckFailures += 1
+      if ((this.workCheckFailures & (this.workCheckFailures - 1)) === 0) {
+        this.logger?.warn?.(
+          { err: err?.message, failures: this.workCheckFailures },
+          "deferred restart work check failed",
+        )
+      }
+      this.settling = false
+      this._schedule(Math.min(this.pollMs * (2 ** (this.workCheckFailures - 1)), 5_000))
+      return
+    }
+    this.workCheckFailures = 0
+    if (active) {
+      this.settling = false
+      this._schedule(this.pollMs)
+      return
+    }
+    if (!this.settling) {
+      this.settling = true
+      this._schedule(this.settleMs)
+      return
+    }
+    // settle 後も idle。main のshutdown が共有 lifecycle を hook await より前に
+    // 更新する。coordinator は二重呼び出しだけを独立に防ぐ。
+    this.shutdownInvoked = true
+    this.logger?.info?.({}, "deferred restart reached idle settle; shutting down")
+    try {
+      await this.shutdown?.("deferred-restart")
+    } catch (err) {
+      this.logger?.error?.({ err: err?.message }, "deferred restart shutdown failed")
+    }
+  }
+
+  stop() {
+    if (this.timer) this.clearTimer(this.timer)
+    this.timer = null
+  }
+}
+
 export async function startDaemon({ version, claudeSdk } = {}) {
   const config = await readConfig()
   if (!config) {
@@ -757,7 +863,9 @@ export async function startDaemon({ version, claudeSdk } = {}) {
   }
 
   const plugins = await loadPlugins(logger)
-  const ctx = { logger, config, plugins }
+  // ctx と dispatchCtx の shallow copy を跨いで共有する lifecycle 正本。
+  const lifecycle = { restartPending: false, shutdownStarted: false }
+  const ctx = { logger, config, plugins, lifecycle }
 
   // 起動時: 保存済み active プロファイルの CLAUDE_CONFIG_DIR を反映してから
   // Claude SDK を初期化する。profiles.json が無ければ既定 (~/.claude) のまま。
@@ -1268,8 +1376,14 @@ export async function startDaemon({ version, claudeSdk } = {}) {
   // 相互依頼のためのローカル IPC 受信口。cwd スコープ capability トークン
   // (src/sibling-token.mjs) で検証した要求のみ claudeBridge/codexBridge.sendToCwd()
   // へ橋渡しする。
-  const siblingInjectBridge = new SiblingInjectBridge({ claudeBridge, codexBridge, logger })
-  await siblingInjectBridge.start()
+  let restartCoordinator = null
+  const siblingInjectBridge = new SiblingInjectBridge({
+    claudeBridge,
+    codexBridge,
+    logger,
+    onRestartRequested: () => restartCoordinator.request(),
+    isInputBlocked: () => lifecycle.restartPending || lifecycle.shutdownStarted,
+  })
   ctx.siblingInjectBridge = siblingInjectBridge
 
   // モデル能力レジストリ (2026-07-11): SDK supportedModels() を起動時に引き、effort
@@ -1293,12 +1407,19 @@ export async function startDaemon({ version, claudeSdk } = {}) {
   }
 
   const shutdown = async (signal) => {
+    if (lifecycle.shutdownStarted) return
+    // hook await より前に立てる。deferred/OS signal の競合でも shutdown は一度だけ。
+    lifecycle.shutdownStarted = true
+    // 新しいローカル注入要求も hook 実行中に turn を開始できないよう入口を先に閉じる。
+    siblingInjectBridge.stop()
     logger.info({ signal }, "shutting down")
+    logger.info({ signal }, "agent stop hooks starting")
     await runHookBroadcast(plugins, "onAgentStop", ctx)
+    logger.info({ signal }, "agent stop hooks completed")
     stateLoop.stop()
     sessionEventLoop?.stop?.()
     readinessLoop?.stop?.()
-    siblingInjectBridge.stop()
+    restartCoordinator?.stop?.()
     claudeBridge?.shutdown?.()
     codexBridge?.shutdown?.()
     client.stop()
@@ -1306,6 +1427,15 @@ export async function startDaemon({ version, claudeSdk } = {}) {
     clearInterval(keepaliveTimer)
     process.exit(0)
   }
+  restartCoordinator = new DeferredRestartCoordinator({
+    claudeBridge,
+    codexBridge,
+    shutdown,
+    logger,
+    lifecycle,
+    workProviders: [siblingInjectBridge],
+  })
+  await siblingInjectBridge.start()
   process.on("SIGINT", () => shutdown("SIGINT"))
   process.on("SIGTERM", () => shutdown("SIGTERM"))
   // dispatch から呼べるように shutdown を ctx に載せる (agent.shutdown 用)。
@@ -2968,6 +3098,17 @@ const codexInflightByInputId = new Map()
 // 同一 input_id がキューに 2 件積まれて drain 後も 1 件残る (送信待ちチップが消えない)。
 const claudeInflightByInputId = new Map()
 
+function inputLifecycleRejection(ctx) {
+  if (!ctx.lifecycle?.restartPending && !ctx.lifecycle?.shutdownStarted) return null
+  const reason = ctx.lifecycle.restartPending ? "restart_pending" : "agent_shutting_down"
+  return {
+    reason,
+    message: reason === "restart_pending"
+      ? "restart pending: new input was not accepted"
+      : "agent shutdown in progress: new input was not accepted",
+  }
+}
+
 /**
  * SDK チャット配達保証 (S2, 2026-07-05): `claude.input` を処理し、browser が付与した
  * `input_id` があれば `claude.input.ack` / `claude.input.nack` を返す。無ければ従来
@@ -3011,6 +3152,21 @@ export function handleClaudeChatInput(msg, ctx) {
     )
     return claudeInflightByInputId.get(input_id)
   }
+  const lifecycleRejection = inputLifecycleRejection(ctx)
+  if (lifecycleRejection) {
+    const { reason, message } = lifecycleRejection
+    if (input_id) {
+      ctx.client.send({ type: "claude.input.nack", stream_id, input_id, reason })
+    } else {
+      ctx.client.send({
+        type: "claude.error",
+        stream_id,
+        error: message,
+        reason,
+      })
+    }
+    return undefined
+  }
   const p = ctx.claudeBridge
     .input({
       stream_id,
@@ -3261,6 +3417,20 @@ export function handleCodexChatInput(msg, ctx) {
     ctx.logger?.info?.({ stream_id, input_id }, "codex.input in-flight dedup (join, no re-dispatch)")
     return codexInflightByInputId.get(input_id)
   }
+  const lifecycleRejection = inputLifecycleRejection(ctx)
+  if (lifecycleRejection) {
+    const { reason, message } = lifecycleRejection
+    if (input_id) {
+      ctx.client.send({ type: "codex.input.nack", stream_id, input_id, reason })
+    }
+    ctx.client.send({
+      type: "codex.error",
+      stream_id,
+      error: message,
+      reason,
+    })
+    return undefined
+  }
   const p = ctx.codexBridge
     .input({
       stream_id,

package/src/service-install.mjs

@@ -314,28 +314,19 @@ export async function installService({ bin } = {}) {
   throw new Error(`unsupported platform: ${process.platform}`)
 }
 
-/**
- * install-service 済みの hub-agent を再起動する。
- *
- * - macOS: `launchctl kickstart -k gui/<uid>/<label>` で SIGTERM + 再起動
- * - Linux: `systemctl --user restart hub-agent.service`
- *
- * service が install されていない場合は分かりやすい error を投げる。
- * (cockpit web UI から `hub-agent restart` 案内が出ても、enroll 直後の
- *  ユーザーが叩くケースを想定)
- */
-export async function restartService() {
+/** install-service 済みかを検査し、後続のrestartが使うservice descriptorを返す。 */
+export async function requireInstalledService() {
   if (process.platform === "darwin") {
     const dest = macPlistPath()
     try {
       await fs.access(dest)
     } catch {
-      throw new Error(
+      const err = new Error(
         `service not installed (${dest} not found). run \`hub-agent install-service\` first`,
       )
+      err.code = "service_not_installed"
+      throw err
     }
-    const uid = ensureUnixUid()
-    run("launchctl", ["kickstart", "-k", `gui/${uid}/${PLIST_LABEL}`])
     return { platform: "darwin", path: dest, label: PLIST_LABEL }
   }
 
@@ -344,15 +335,58 @@ export async function restartService() {
     try {
       await fs.access(dest)
     } catch {
-      throw new Error(
+      const err = new Error(
         `service not installed (${dest} not found). run \`hub-agent install-service\` first`,
       )
+      err.code = "service_not_installed"
+      throw err
     }
-    run("systemctl", ["--user", "restart", SYSTEMD_UNIT_NAME])
     return { platform: "linux", path: dest, unit: SYSTEMD_UNIT_NAME }
   }
 
-  throw new Error(`unsupported platform: ${process.platform}`)
+  const err = new Error(`unsupported platform: ${process.platform}`)
+  err.code = "unsupported_platform"
+  throw err
+}
+
+/** CLI が作業中断を伴う --force を案内してよい失敗か。 */
+export function canSuggestForcedRestart(err) {
+  return err?.code !== "service_not_installed" && err?.code !== "unsupported_platform"
+}
+
+/** 検査済みdescriptor、またはローカル検査結果のserviceを即時再起動する。 */
+export async function restartService(service = null) {
+  const installed = service || await requireInstalledService()
+  if (installed.platform === "darwin") {
+    const uid = ensureUnixUid()
+    run("launchctl", ["kickstart", "-k", `gui/${uid}/${PLIST_LABEL}`])
+  } else if (installed.platform === "linux") {
+    run("systemctl", ["--user", "restart", SYSTEMD_UNIT_NAME])
+  } else {
+    const err = new Error(`unsupported platform: ${installed.platform}`)
+    err.code = "unsupported_platform"
+    throw err
+  }
+  return installed
+}
+
+/** CLI の restart 方針をテスト可能な形に分離する。即時経路は force 明示時だけ選ぶ。 */
+export async function restartWithPolicy({
+  force = false,
+  deferredRestart,
+  immediateRestart = restartService,
+  requireInstalled = requireInstalledService,
+} = {}) {
+  // deferred でも daemon は正常終了するため、KeepAlive/Restart の登録が無ければ先に拒否する。
+  // 判定結果を即時経路へ渡し、同じ filesystem access を二重実行しない。
+  const service = await requireInstalled()
+  if (force) {
+    return { mode: "immediate", result: await immediateRestart(service) }
+  }
+  if (typeof deferredRestart !== "function") {
+    throw new Error("deferred restart transport is unavailable")
+  }
+  return { mode: "deferred", result: await deferredRestart(), service }
 }
 
 export async function uninstallService() {