oysterun 1.6.0-beta.2 → 1.6.0-beta.21

package/host-service/cli/product-cli.mjs

@@ -5,6 +5,8 @@ import {
   getConfigPath,
   readRawConfigSource,
 } from "../config.mjs";
+import { parseSessionTagsCliValue } from "../session-tags.mjs";
+import { parseSchedulerRunTimeoutDuration } from "../scheduler-run-timeout-policy.mjs";
 
 export const P86_CLI_CONTRACT = "p86_product_cli_module_action_v1";
 export const P86_CLI_PROFILE_CONTRACT = "p86_cli_profile_0600_token_fallback_v1";
@@ -610,10 +612,10 @@ async function readCurrentSessionMessagesAround({ options, env, fetchFn }) {
     session_id: resolvedSessionId,
     session_ref: body?.session_ref || sessionTarget.session_ref || null,
     agent_id: normalizeString(body?.agent_id) || agentId,
-    cross_session_search: crossSessionContext,
-    context_surface: crossSessionContext
+    cross_session_search: body?.cross_session_search ?? crossSessionContext,
+    context_surface: body?.context_surface || (crossSessionContext
       ? "session_messages_matrix_target_session"
-      : "session_messages_matrix_current_session",
+      : "session_messages_matrix_current_session"),
   };
 }
 
@@ -671,6 +673,14 @@ function boolPayload(options, sourceKey, targetKey, payload) {
   }
 }
 
+function applySessionTagsOptions(options, body) {
+  const hasTags = Object.prototype.hasOwnProperty.call(options, "tags");
+  const clearTags = parseBooleanOption(options, "clearTags", false);
+  if (hasTags && clearTags) fail("--tags and --clear-tags are mutually exclusive");
+  if (hasTags) body.tags = parseSessionTagsCliValue(options.tags);
+  if (clearTags) body.tags = [];
+}
+
 function sessionStartPayload(options, env = process.env) {
   const body = {
     agent_id: requireAgentId(options, env),
@@ -706,6 +716,7 @@ function sessionStartPayload(options, env = process.env) {
     body.telegram_allowed_users =
       allowedUsers === "." ? ["."] : allowedUsers.split(",").map((entry) => entry.trim()).filter(Boolean);
   }
+  applySessionTagsOptions(options, body);
   return body;
 }
 
@@ -720,6 +731,7 @@ function commaListOption(options, ...keys) {
 
 function sessionProfileUpdatePayload(options, env = process.env) {
   const body = {};
+  applySessionTagsOptions(options, body);
   boolPayload(options, "notificationsEnabled", "notifications_enabled", body);
   boolPayload(options, "webEnabled", "web_enabled", body);
   const webAccess = optionalOption(options, "webAccess", "access");
@@ -868,40 +880,15 @@ function resolveSessionUrlIdFromStatus(status, sessionTarget) {
   return resolvedSessionId;
 }
 
-async function resolveSessionMessagesTarget({ options, env, fetchFn }) {
+async function resolveSessionMessagesTarget({ options, env }) {
   const sessionTarget = requireSessionTarget(options, env);
+  // Host resolves durable target ownership. Explicit agent is only an assertion.
   const explicitAgentId = resolveAgentId(options, {});
-  const envSessionId = normalizeString(env.OYSTERUN_SESSION_ID);
-  const envAgentId = normalizeString(env.OYSTERUN_AGENT_ID);
-  if (
-    sessionTarget.session_id &&
-    (explicitAgentId || (envAgentId && sessionTarget.session_id === envSessionId))
-  ) {
-    return {
-      sessionTarget,
-      sessionId: sessionTarget.session_id,
-      agentId: explicitAgentId || envAgentId,
-    };
-  }
-  const status = await resolveLiveSessionTargetStatus({
-    options,
-    env,
-    fetchFn,
-    sessionTarget,
-  });
-  const statusAgentId = normalizeString(status?.agent_id);
-  if (explicitAgentId && statusAgentId && explicitAgentId !== statusAgentId) {
-    fail("target session agent id does not match explicit --agent-id");
-  }
-  const agentId =
-    explicitAgentId ||
-    statusAgentId ||
-    resolveAgentId(options, env);
-  if (!agentId) fail("target session agent id is required");
+  const sameCurrent = sessionTarget.session_id === normalizeString(env.OYSTERUN_SESSION_ID);
   return {
     sessionTarget,
-    sessionId: normalizeString(status?.session_id) || sessionTarget.session_id || null,
-    agentId,
+    sessionId: sessionTarget.session_id || null,
+    agentId: explicitAgentId || (sameCurrent ? normalizeString(env.OYSTERUN_AGENT_ID) : ""),
   };
 }
 
@@ -1052,6 +1039,7 @@ async function runSessions({ action, rest, options, env, fetchFn }) {
         session_id: status.session_id || sessionTarget.session_id || null,
         session_ref: sessionTarget.session_ref || null,
         session_name: status.session_name || null,
+        tags: Array.isArray(status.tags) ? status.tags : [],
         agent_id: status.agent_id || null,
         profile_config: status.profile_config || {},
         notification_settings: status.notification_settings || null,
@@ -1103,6 +1091,9 @@ async function runSessions({ action, rest, options, env, fetchFn }) {
         })).data;
         result.profile_config_update = profileResult;
         result.session_id = profileResult.session_id || result.session_id;
+        result.tags = Array.isArray(profileResult.tags)
+          ? profileResult.tags
+          : [];
       }
       if (!sessionName && !hasSessionProfileUpdateBody(profileBody)) {
         fail("profile update requires at least one typed field");
@@ -1362,6 +1353,7 @@ async function runChat({ action, rest, options, env, fetchFn }) {
         agent_id: targetContext.agentId,
         limit: optionalOption(options, "limit"),
         after_seq: optionalOption(options, "afterSeq"),
+        next_batch: optionalOption(options, "nextBatch"),
       })}`,
       options,
       env,
@@ -1471,6 +1463,15 @@ function schedulerPayload(options) {
   const weekdays = commaListOption(options, "weekdays", "selectedWeekdays");
   if (weekdays) body.weekdays = weekdays;
   boolPayload(options, "enabled", "enabled", body);
+  if (Object.prototype.hasOwnProperty.call(options, "runTimeout")) {
+    try {
+      body.run_timeout_seconds = parseSchedulerRunTimeoutDuration(
+        options.runTimeout
+      );
+    } catch (error) {
+      fail(error.message);
+    }
+  }
   return body;
 }
 

package/host-service/cli/reconcile-initial-preflight.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Offline compatibility entry for Hosts predating initial-preflight terminalization.
+// The service must be stopped; this never owns a restore, install, or snapshot.
+import { readHostRuntimeMetadata } from "../host-runtime-diagnostics.mjs";
+import { processDefinitelyAbsent, reconcileFailedInitialPreflight } from "../initial-preflight-recovery.mjs";
+import { isUpdateOperationBlocking } from "../update-reminder-state.mjs";
+const args = process.argv.slice(2);
+if (args.length !== 4 || args[0] !== "--config-dir" || args[2] !== "--operation-id") {
+  throw new Error("Required: --config-dir <exact stopped Host config> --operation-id <exact failed attempt>");
+}
+const configDir = args[1];
+const runtime = readHostRuntimeMetadata(configDir);
+if (!runtime || !processDefinitelyAbsent(runtime.pid)) {
+  throw new Error("Offline reconciliation requires affirmative stopped Host process evidence.");
+}
+const operation = reconcileFailedInitialPreflight({ configDir, currentVersion: runtime.package_version, expectedOperationId: args[3] });
+if (isUpdateOperationBlocking(operation) || operation.status !== "update_check_failed" ||
+    operation.reconciliation_outcome !== "abandoned_initial_preflight_failed") throw new Error("Retained operation is not a proven abandoned initial-preflight failure.");
+console.log(JSON.stringify({ operation_id: operation.operation_id, status: operation.status, reconciliation_outcome: operation.reconciliation_outcome }));

package/host-service/cli/recover-installer-lifecycle.mjs

@@ -0,0 +1,24 @@
+import { join, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { readUserHostPort } from "../host-port-resolution.mjs";
+import { readUpdateOperationState, isUpdateOperationBlocking } from "../update-reminder-state.mjs";
+import { continuityReceiptPath } from "../lifecycle-continuity.mjs";
+import { runStagedLifecycleRecovery } from "./run-staged-lifecycle-recovery.mjs";
+try {
+  const [configDir, activePackage] = process.argv.slice(2);
+  const port = readUserHostPort({ configPath: join(configDir, "config.json"), runtimePath: join(configDir, "run", "host-runtime.json"), configDir });
+  const operation = readUpdateOperationState({ configDir });
+  if (operation.continuity_path !== continuityReceiptPath(configDir, operation.operation_id)) throw new Error("Retained lifecycle has no exact continuity receipt; preserve it and use its reported recovery path.");
+  const receipt = JSON.parse(readFileSync(operation.continuity_path, "utf8"));
+  if (receipt.baseline?.host?.port !== port ||
+      resolve(receipt.baseline?.host?.config_dir || "") !== resolve(configDir) ||
+      resolve(receipt.baseline?.host?.package_root || "") !== resolve(activePackage) ||
+      resolve(receipt.resources?.active_package_root || "") !== resolve(activePackage)) {
+    throw new Error("Retained recovery differs from the selected Host port/config/package; its package was preserved.");
+  }
+  await runStagedLifecycleRecovery({ configDir, stack: "production", port: String(port) });
+  if (isUpdateOperationBlocking(readUpdateOperationState({ configDir }))) throw new Error("Retained lifecycle cleanup is still blocking; preserve its package and receipts.");
+} catch (error) {
+  console.error(`Installer lifecycle recovery failed: ${error.message}`);
+  process.exitCode = 1;
+}

package/host-service/cli/run-host-lifecycle.mjs

@@ -61,6 +61,8 @@ function printBoundedStatus(payload) {
   const operation = payload.update_operation || payload.operation || {};
   const fields = {
     status: payload.status || operation.status || "unknown",
+    operation_status:
+      operation.status || payload.operation_status || null,
     operation_id: operation.operation_id || payload.operation_id || null,
     transaction_kind:
       operation.transaction_kind || payload.transaction_kind || null,

package/host-service/cli/run-staged-lifecycle-recovery.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { buildHostLifecycleRecoveryPlan } from "../host-lifecycle-recovery.mjs";
+import { readContinuity, continuityReceiptPath } from "../lifecycle-continuity.mjs";
+import {
+  verifyPersistedNodeNpmRuntimeIdentityAuthoritatively,
+} from "../node-npm-runtime-identity.mjs";
+import {
+  readUpdateOperationState,
+} from "../update-reminder-state.mjs";
+import { runHostLifecycleTransaction } from "../../tool_scripts/oysterun_update_restart_runner.mjs";
+
+function normalizeString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function isProcessRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error?.code === "ESRCH") return false;
+    throw error;
+  }
+}
+
+function parseJsonObject(path, label) {
+  const value = JSON.parse(readFileSync(path, "utf8"));
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must contain a JSON object`);
+  }
+  return value;
+}
+
+export async function runStagedLifecycleRecovery({
+  configDir = process.env.OYSTERUN_CONFIG_DIR,
+  stack = process.env.OYSTERUN_RELEASE_STACK || "production",
+  port = process.env.OYSTERUN_PORT || null,
+  readOperation = readUpdateOperationState,
+  readReceipt = readContinuity,
+  buildRecoveryPlan = buildHostLifecycleRecoveryPlan,
+  verifyIdentity = verifyPersistedNodeNpmRuntimeIdentityAuthoritatively,
+  readPreparation = parseJsonObject,
+  runnerIsAlive = isProcessRunning,
+  runTransaction = runHostLifecycleTransaction,
+} = {}) {
+  const exactConfigDir = normalizeString(configDir);
+  if (!exactConfigDir || resolve(exactConfigDir) !== exactConfigDir) {
+    throw new Error("OYSTERUN_CONFIG_DIR must be an absolute path");
+  }
+  const operation = readOperation({ configDir: exactConfigDir });
+  const expectedContinuityPath = continuityReceiptPath(
+    exactConfigDir,
+    operation.operation_id
+  );
+  if (
+    !operation.operation_id ||
+    operation.continuity_path !== expectedContinuityPath
+  ) {
+    throw new Error("retained lifecycle operation has no exact continuity binding");
+  }
+  const receipt = readReceipt(
+    operation.continuity_path,
+    operation.operation_id
+  );
+  const runnerAlive = runnerIsAlive(operation.runner_pid);
+  const recoveryPlan = buildRecoveryPlan({
+    operation,
+    continuityReceipt: receipt,
+    runnerAlive,
+  });
+  if (
+    recoveryPlan?.blocking !== true ||
+    recoveryPlan?.user_action?.kind !== "restore_and_restart" ||
+    operation.running === true ||
+    runnerAlive
+  ) {
+    throw new Error(
+      "retained lifecycle operation is not eligible for staged restore"
+    );
+  }
+  const baseline = receipt.baseline?.host || {};
+  const resources = receipt.resources || {};
+  const exactPort = Number(port || baseline.port);
+  if (
+    receipt.transaction_kind === "restart_only" ||
+    resolve(baseline.config_dir || "") !== exactConfigDir ||
+    baseline.stack !== stack ||
+    !Number.isInteger(exactPort) ||
+    exactPort !== baseline.port ||
+    resolve(resources.active_package_root || "") !==
+      resolve(baseline.package_root || "") ||
+    operation.result_path !== resources.result_path
+  ) {
+    throw new Error("staged recovery geometry differs from the retained Host");
+  }
+  const preparation = readPreparation(
+    operation.result_path,
+    "retained update preparation receipt"
+  );
+  if (
+    preparation.operation_id !== operation.operation_id ||
+    resolve(preparation.active_package_root || "") !==
+      resolve(resources.active_package_root)
+  ) {
+    throw new Error("retained preparation receipt differs from the operation");
+  }
+  const identity = verifyIdentity({
+    configDir: exactConfigDir,
+  });
+  if (
+    identity.toolchain_identity_digest !== receipt.source?.runtime_identity_digest
+  ) {
+    throw new Error("retained recovery Node/npm identity changed");
+  }
+  const result = await runTransaction({
+    transaction_kind: receipt.transaction_kind,
+    operation_id: operation.operation_id,
+    active_package_root: resources.active_package_root,
+    config_dir: exactConfigDir,
+    node_bin: identity.node_path,
+    npm_cli: identity.npm_cli_path,
+    identity_digest: identity.toolchain_identity_digest,
+    stack,
+    health_url: `http://127.0.0.1:${exactPort}/health`,
+    result_path: operation.result_path,
+    restart_id: receipt.restart_id,
+    login_gate_id: operation.login_gate_id || null,
+    continuity_path: operation.continuity_path,
+    restore_before_restart: "1",
+  });
+  return result;
+}
+
+async function main() {
+  const result = await runStagedLifecycleRecovery();
+  process.stdout.write(
+    `${JSON.stringify({
+      status: result?.status || "recovered",
+      operation_id: result?.operation_id || null,
+      operation_cleanup_completed:
+        result?.operation_cleanup_completed === true,
+      secret_fields_redacted: true,
+    }, null, 2)}\n`
+  );
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))
+) {
+  main().catch((error) => {
+    process.stderr.write(`[oysterun-recovery] ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/host-service/codex-model-discovery.mjs

@@ -1,4 +1,4 @@
-import { spawn } from "child_process";
+import { ownDiscoveryProcess, spawnDiscoveryProcess, collectDiscoveryCleanup } from "./model-discovery-process.mjs";
 import { execFileSync } from "child_process";
 import { EventEmitter } from "events";
 import { existsSync } from "fs";
@@ -89,6 +89,7 @@ class JsonRpcLineClient extends EventEmitter {
     this.stdoutBuffer = "";
     this.nextId = 1;
     this.pending = new Map();
+    this.terminalError = null;
     proc.stdout.on("data", (chunk) => this.consumeStdout(String(chunk)));
     proc.stderr.on("data", (chunk) => {
       this.emit("stderr", String(chunk));
@@ -98,20 +99,16 @@ class JsonRpcLineClient extends EventEmitter {
         "codex_app_server_exit",
         `Codex app-server exited during discovery (code=${code}, signal=${signal || "none"})`
       );
-      for (const pending of this.pending.values()) {
-        pending.reject(error);
-      }
-      this.pending.clear();
+      this.terminalError ||= error;
+      this.failPending(this.terminalError);
     });
     proc.on("error", (err) => {
       const error = new CodexModelDiscoveryError(
         "codex_app_server_error",
         err.message
       );
-      for (const pending of this.pending.values()) {
-        pending.reject(error);
-      }
-      this.pending.clear();
+      this.terminalError ||= error;
+      this.failPending(this.terminalError);
     });
   }
 
@@ -169,9 +166,11 @@ class JsonRpcLineClient extends EventEmitter {
 
   request(method, params = {}) {
     const id = String(this.nextId++);
-    this.writeJson({ jsonrpc: "2.0", id, method, params });
     return new Promise((resolve, reject) => {
+      if (this.terminalError) { reject(this.terminalError); return; }
       this.pending.set(id, { resolve, reject });
+      try { this.writeJson({ jsonrpc: "2.0", id, method, params }); }
+      catch (error) { this.pending.delete(id); reject(error); }
     });
   }
 
@@ -180,6 +179,7 @@ class JsonRpcLineClient extends EventEmitter {
   }
 
   writeJson(payload) {
+    if (this.terminalError) throw this.terminalError;
     if (!this.proc.stdin?.writable) {
       throw new CodexModelDiscoveryError(
         "codex_app_server_stdin_unavailable",
@@ -189,11 +189,6 @@ class JsonRpcLineClient extends EventEmitter {
     this.proc.stdin.write(`${JSON.stringify(payload)}\n`);
   }
 
-  close() {
-    if (typeof this.proc.kill === "function") {
-      this.proc.kill("SIGTERM");
-    }
-  }
 }
 
 function extractModelEntries(result) {
@@ -249,7 +244,7 @@ export async function discoverCodexProviderModels(options = {}) {
     ? options.timeoutMs
     : 5000;
   const maxPages = Number.isInteger(options.maxPages) ? options.maxPages : 20;
-  const spawnFn = options.spawnFn || spawn;
+  const spawnFn = options.spawnFn || spawnDiscoveryProcess;
   const commandResolution = resolveCodexDiscoveryCommand(options);
   const proc = spawnFn(commandResolution.resolved_command, [
     "app-server",
@@ -258,10 +253,15 @@ export async function discoverCodexProviderModels(options = {}) {
   ], {
     cwd: options.cwd || process.cwd(),
     stdio: ["pipe", "pipe", "pipe"],
+    detached: true,
+    ...(options.signal ? { signal: options.signal } : {}),
     env: { ...process.env, ...(options.env || {}) },
   });
-  const client = new JsonRpcLineClient(proc);
+  const ownedProcess = ownDiscoveryProcess(proc, options.processCleanup);
+  const processCleanup = {};
+  let discoveryError;
   try {
+    const client = new JsonRpcLineClient(proc);
     await withTimeout(
       client.request("initialize", {
         clientInfo: {
@@ -300,6 +300,7 @@ export async function discoverCodexProviderModels(options = {}) {
           rawModels.map(normalizeCodexDiscoveryModel)
         );
         return {
+          process_cleanup: processCleanup,
           provider: "codex",
           command_available: true,
           resolved_command_redacted: redactCommand(
@@ -315,7 +316,11 @@ export async function discoverCodexProviderModels(options = {}) {
       "codex_model_list_pagination_limit",
       `Codex model/list exceeded ${maxPages} pages`
     );
+  } catch (err) {
+    discoveryError = err;
+    throw err;
   } finally {
-    client.close();
+    Object.assign(processCleanup, await collectDiscoveryCleanup(ownedProcess));
+    if (discoveryError) discoveryError.details = { ...discoveryError.details, process_cleanup: processCleanup };
   }
 }

package/host-service/complete-cli-uninstall.mjs

@@ -0,0 +1,176 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { constants, accessSync, existsSync, lstatSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { userInfo } from "node:os";
+import { resolveNodeNpmRuntimeIdentity, buildNodeNpmChildEnvironment, assertNodeNpmRuntimeIdentityMatches } from "./node-npm-runtime-identity.mjs";
+
+function inside(parent, child) {
+  const r = relative(parent, child);
+  return !r || (!r.startsWith("..") && !isAbsolute(r));
+}
+function canonical(path) {
+  if (!isAbsolute(path) || /[\r\n\t\0]/u.test(path)) throw new Error("Uninstall requires exact absolute paths without control characters.");
+  if (existsSync(path)) return realpathSync(path);
+  return join(canonical(dirname(path)), path.slice(dirname(path).length + 1));
+}
+function checkedRun(spawn, command, args, options) {
+  const r = spawn(command, args, { encoding: "utf8", ...options });
+  if (r.error || r.status !== 0) throw new Error(`${command}: ${r.error?.message || String(r.stderr || r.stdout || `exit ${r.status}`).trim()}`);
+  return String(r.stdout || "").trim();
+}
+function writableRemoval(path, uid) {
+  if (!existsSync(path)) return;
+  if (statSync(path).uid !== uid) throw new Error(`Selected removal target is not owned by the running OS user: ${path}`);
+  accessSync(dirname(path), constants.W_OK | constants.X_OK);
+}
+
+// npm enables Node's compile cache even for --version. Keep this policy local
+// to identity/resolver probes; lifecycle and the actual npm uninstall retain
+// the caller's normal child environment.
+export function buildUninstallProbeEnvironment(env) {
+  const probeEnv = { ...env, NODE_DISABLE_COMPILE_CACHE: "1" };
+  delete probeEnv.NODE_COMPILE_CACHE;
+  return probeEnv;
+}
+
+export function resolveLaunchingCli({ cliPath, env = process.env, spawn = spawnSync } = {}) {
+  const cli = realpathSync(cliPath);
+  const root = dirname(dirname(cli));
+  const prefix = dirname(dirname(dirname(root)));
+  if (root !== join(prefix, "lib", "node_modules", "oysterun") || cli !== join(root, "bin", "oysterun.mjs")) {
+    throw new Error("Complete uninstall requires the installed global Oysterun CLI, not a checkout or npm link. Run the exact installed prefix/bin/oysterun.");
+  }
+  const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const bin = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.oysterun;
+  if (manifest.name !== "oysterun" || bin !== "bin/oysterun.mjs" || canonical(join(prefix, "bin", "oysterun")) !== cli) {
+    throw new Error("Launching Oysterun package/bin identity disagrees; repair this exact global installation before uninstalling.");
+  }
+  const identity = resolveNodeNpmRuntimeIdentity({ nodeBin: process.execPath, env: buildUninstallProbeEnvironment(env), spawnSyncFn: spawn });
+  const childEnv = buildNodeNpmChildEnvironment(identity, env);
+  const probeEnv = buildUninstallProbeEnvironment(childEnv);
+  // The removal arguments remain unchanged. Read-only npm root must also avoid
+  // cache directory creation, log cleanup, timing output and update checks.
+  // /dev/null is a non-directory on the supported Unix global-install layout.
+  const npmArgs = ["--global", "--prefix", prefix, "--ignore-scripts", "--logs-max=0", "--no-audit", "--no-fund"];
+  const modules = checkedRun(spawn, identity.node_path, [identity.npm_cli_path, "root", ...npmArgs, "--cache=/dev/null", "--logs-dir=/dev/null", "--update-notifier=false", "--timing=false"], { env: probeEnv });
+  if (canonical(modules) !== canonical(join(prefix, "lib", "node_modules")) || canonical(join(modules, "oysterun")) !== root) {
+    throw new Error("Matching npm does not address the launching Oysterun prefix; no service or config was changed.");
+  }
+  const osUser = userInfo();
+  if (process.getuid() !== osUser.uid || process.geteuid() !== osUser.uid) throw new Error("Running OS user identity is ambiguous; run uninstall as the installation owner without escalation.");
+  writableRemoval(root, osUser.uid);
+  accessSync(join(prefix, "bin"), constants.W_OK | constants.X_OK);
+  return { cli, root, prefix, manifestSha256: createHash("sha256").update(readFileSync(join(root, "package.json"))).digest("hex"), bin: join(prefix, "bin", "oysterun"), identity, childEnv, probeEnv, user: { uid: osUser.uid, name: osUser.username }, npmArgs };
+}
+
+// This only reads the canonical service resolver; it never executes lifecycle.
+export function resolveUninstallServices({ repoRoot, stack, env, spawn = spawnSync }) {
+  const stacks = stack === "all" ? ["production", "staging"] : [stack];
+  const source = `source "$1"; shift
+for target in "$@"; do
+  STACK_NAME="$target"; configure_stack_runtime
+  printf '%s\\t%s\\t%s\\t%s\\t%s\\t%s\\t%s\\n' "$STACK_NAME" "$CONFIG_DIR" "$HOST_LABEL" "$HOST_PORT" "$HOST_PID_FILE" "$HOST_ORIGIN_FILE" "$HOME/Library/LaunchAgents/$HOST_LABEL.plist"
+done`;
+  const raw = checkedRun(spawn, "/bin/bash", ["--noprofile", "--norc", "-eu", "-c", source, "--", join(repoRoot, "tool_scripts", "oysterun_service_common.sh"), ...stacks], { env, cwd: repoRoot });
+  const targets = raw.split("\n").map(line => {
+    const [name, config, label, port, pidFile, originFile, plist] = line.split("\t");
+    if (!name || !config || !label || !pidFile || !originFile || !plist) throw new Error("Canonical service resolver returned an incomplete uninstall target.");
+    return { name, config: canonical(config), label, port, pidFile, originFile, plist,
+      pid: existsSync(pidFile) ? Number(readFileSync(pidFile, "utf8").trim()) : null };
+  });
+  if (targets.length !== stacks.length || targets.some((t, i) => t.name !== stacks[i])) throw new Error("Canonical uninstall stack selection drifted.");
+  return targets;
+}
+
+export function preflightCompleteUninstall({ cliPath, configDir, stack, env = process.env, spawn = spawnSync, resolveServices = resolveUninstallServices }) {
+  const installation = resolveLaunchingCli({ cliPath, env, spawn });
+  const services = resolveServices({ repoRoot: installation.root, stack, env: { ...installation.probeEnv, OYSTERUN_NODE_BIN: installation.identity.node_path }, spawn });
+  const config = canonical(resolve(configDir));
+  if (!services.some(t => t.config === config)) throw new Error("Selected config does not match the selected service stack(s); set OYSTERUN_CONFIG_DIR and --stack/OYSTERUN_RELEASE_STACK to the same installation. No changes made.");
+  writableRemoval(config, installation.user.uid);
+  const protectedPaths = [installation.prefix, installation.root, installation.identity.node_realpath, installation.identity.npm_cli_realpath, canonical(userInfo().homedir)];
+  for (const filename of ["config.json", "session-history.json", "loops.json"]) {
+    const path = join(config, filename);
+    if (!existsSync(path)) continue;
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    const collect = value => {
+      if (!value || typeof value !== "object") return;
+      for (const [key, item] of Object.entries(value)) {
+        if (["default_browse_path", "agent_folder", "start_folder", "cwd"].includes(key) && typeof item === "string" && item) protectedPaths.push(canonical(resolve(item)));
+        else if (item && typeof item === "object") collect(item);
+      }
+    };
+    collect(raw);
+  }
+  if (protectedPaths.some(p => inside(config, p)) || protectedPaths.slice(5).some(p => inside(installation.root, p))) throw new Error("Config removal overlaps the CLI/toolchain, user home, Default Browse Root or Agent/project data. Move the protected data outside this config before complete uninstall; no changes made.");
+  for (const service of services) {
+    // all preserves both service selections; only the selected config must
+    // belong to the launching package, since only that config is deleted.
+    if (service.config === config) {
+      const runtimePath = join(dirname(service.pidFile), "host-runtime.json");
+      if (existsSync(runtimePath)) {
+        const runtime = JSON.parse(readFileSync(runtimePath, "utf8"));
+        if (canonical(runtime.config_dir) !== config || canonical(runtime.repo_root) !== installation.root || (runtime.stack_name ?? "production") !== service.name) throw new Error("Selected Host runtime belongs to another package/config/stack; no changes made.");
+      }
+      if (process.platform === "darwin" && existsSync(service.plist)) {
+        const plist = JSON.parse(checkedRun(spawn, "/usr/bin/plutil", ["-convert", "json", "-o", "-", service.plist], { env: installation.probeEnv }));
+        const args = plist.ProgramArguments || []; const pe = plist.EnvironmentVariables || {};
+        if (plist.Label !== service.label || canonical(args[0] || "") !== join(installation.root, "tool_scripts", "run_oysterun_host.sh") || args[args.indexOf("--stack") + 1] !== service.name ||
+            ![installation.root, join(installation.root, "host-service")].includes(canonical(plist.WorkingDirectory || "")) ||
+            (pe.OYSTERUN_CONFIG_DIR && canonical(pe.OYSTERUN_CONFIG_DIR) !== config) || (pe.HOME && canonical(pe.HOME) !== canonical(userInfo().homedir))) throw new Error("Selected service definition belongs to another package/config/user; no changes made.");
+      }
+    }
+    if (process.platform === "darwin") writableRemoval(service.plist, installation.user.uid);
+  }
+  return { ...installation, config, services, stack };
+}
+
+export function verifyUninstallServices(plan, { spawn = spawnSync } = {}) {
+  for (const t of plan.services) {
+    if (existsSync(t.pidFile) || existsSync(t.originFile) || (process.platform === "darwin" && existsSync(t.plist))) throw new Error(`Service state remains for ${t.name}.`);
+    if (Number.isInteger(t.pid) && t.pid > 0) {
+      try { process.kill(t.pid, 0); throw new Error(`Service PID ${t.pid} remains alive.`); }
+      catch (error) { if (error.code !== "ESRCH") throw error; }
+    }
+  }
+  const source = `source "$1"; shift
+for target in "$@"; do
+ STACK_NAME="$target"; configure_stack_runtime
+ if is_macos && launch_service_is_loaded "$HOST_LABEL"; then echo "Service remains loaded: $HOST_LABEL" >&2; exit 1; fi
+ if [[ -n "$HOST_PORT" ]]; then owners="$(listener_pids_for_port "$HOST_PORT")"; [[ -z "$owners" ]] || { echo "Service port remains occupied: $HOST_PORT" >&2; exit 1; }; fi
+done`;
+  checkedRun(spawn, "/bin/bash", ["--noprofile", "--norc", "-eu", "-c", source, "--", join(plan.root, "tool_scripts", "oysterun_service_common.sh"), ...plan.services.map(t => t.name)], { env: buildUninstallProbeEnvironment(plan.childEnv), cwd: plan.root });
+}
+
+export function executeCompleteUninstall(plan, { spawn = spawnSync, remove = rmSync, verifyServices = verifyUninstallServices, log = console.log } = {}) {
+  const steps = { service: "incomplete", services: Object.fromEntries(plan.services.map(t => [t.name, "incomplete"])), config: "incomplete", cli: "incomplete", userData: "preserved" };
+  let current = "service";
+  try {
+    for (const target of plan.services) {
+      checkedRun(spawn, "/bin/bash", [join(plan.root, "tool_scripts", "oysterun_release_service.sh"), "uninstall", "--stack", target.name], { env: plan.childEnv, cwd: plan.root, stdio: "inherit" });
+      verifyServices({ ...plan, services: [target] }, { spawn });
+      steps.services[target.name] = "removed/absent";
+    }
+    steps.service = "removed/absent";
+    current = "config";
+    remove(plan.config, { recursive: true, force: true });
+    if (existsSync(plan.config)) throw new Error("Selected config directory remains.");
+    steps.config = "removed/absent";
+    current = "cli";
+    // Recheck the exact installation after earlier work; never switch prefixes.
+    if (realpathSync(plan.cli) !== plan.cli || canonical(plan.bin) !== plan.cli || realpathSync(plan.root) !== plan.root) throw new Error("Launching CLI identity changed during cleanup.");
+    if (createHash("sha256").update(readFileSync(join(plan.root, "package.json"))).digest("hex") !== plan.manifestSha256) throw new Error("Launching package changed during cleanup.");
+    assertNodeNpmRuntimeIdentityMatches(plan.identity, resolveNodeNpmRuntimeIdentity({ nodeBin: plan.identity.node_path, npmCli: plan.identity.npm_cli_path, env: buildUninstallProbeEnvironment(plan.childEnv), spawnSyncFn: spawn }));
+    checkedRun(spawn, plan.identity.node_path, [plan.identity.npm_cli_path, "uninstall", ...plan.npmArgs, "oysterun"], { env: plan.childEnv, cwd: plan.prefix, stdio: "inherit" });
+    if (existsSync(plan.root) || existsSync(plan.bin) || (() => { try { lstatSync(plan.bin); return true; } catch (e) { if (e.code === "ENOENT") return false; throw e; } })()) throw new Error("npm completed but the exact Oysterun package/bin remains.");
+    steps.cli = "removed/absent";
+    log("Complete uninstall succeeded: service removed, configuration removed, CLI removed; user data preserved.");
+    return { exitCode: 0, steps };
+  } catch (error) {
+    log(`Complete uninstall failed at ${current}: ${error.message}`);
+    log(`Services: ${Object.entries(steps.services).map(([name, status]) => `${name}=${status}`).join("; ")}.`);
+    log(`Completed/incomplete steps: service=${steps.service}; config=${steps.config}; CLI=${steps.cli}; user data=${steps.userData}.`);
+    return { exitCode: 1, steps, error: error.message };
+  }
+}