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

package/tool_scripts/oysterun_service_common.sh

@@ -495,6 +495,13 @@ require_host_port_configured() {
   exit 1
 }
 
+resolve_bound_user_host_pid() {
+  local port_node=""
+  port_node="$(require_node_runtime "Host process binding")" || return 1
+  "${port_node}" "${ROOT_DIR}/tool_scripts/resolve_user_host_port.mjs" \
+    "${CONFIG_PATH}" "${RUN_DIR}/host-runtime.json" "${CONFIG_DIR}" process
+}
+
 configure_stack_runtime() {
   validate_stack
 
@@ -528,7 +535,11 @@ configure_stack_runtime() {
       BACKEND_PORT="8000"
       BACKEND_INTERNAL_URL="http://127.0.0.1:8000"
       BACKEND_PUBLIC_BASE_URL="http://localhost:8000"
-      HOST_PORT="${PRODUCTION_HOST_PORT}"
+      local port_node=""
+      port_node="$(require_node_runtime "Host port resolution")" || return 1
+      HOST_PORT="$("${port_node}" "${ROOT_DIR}/tool_scripts/resolve_user_host_port.mjs" \
+        "${CONFIG_PATH}" "${RUN_DIR}/host-runtime.json" "${CONFIG_DIR}" port \
+        "${HOST_ORIGIN_FILE}" "${HOST_PID_FILE}" "${HOME}/Library/LaunchAgents/${HOST_LABEL}.plist")" || return 1
       ;;
     staging)
       STACK_ROOT="${STACKS_DIR}/${STACK_NAME}"
@@ -1815,7 +1826,6 @@ wait_for_http() {
   local pid="$3"
   local log_file="$4"
   local launch_label="${5:-}"
-  local attempts=0
 
   until curl -fsS "${url}" >/dev/null 2>&1; do
     local current_pid="${pid}"
@@ -1825,15 +1835,6 @@ wait_for_http() {
 
     if [[ -n "${current_pid}" ]] && ! pid_is_running "${current_pid}" 2>/dev/null; then
       if [[ -n "${launch_label}" ]] && launchctl_label_exists "${launch_label}"; then
-        attempts=$((attempts + 1))
-        if [[ "${attempts}" -ge 60 ]]; then
-          echo "[oysterun-service] error: timed out waiting for ${label} at ${url}" >&2
-          if [[ -f "${log_file}" ]]; then
-            echo "[oysterun-service] Last ${label} log lines:" >&2
-            tail -n 40 "${log_file}" >&2 || true
-          fi
-          exit 1
-        fi
         sleep 1
         continue
       fi
@@ -1845,16 +1846,6 @@ wait_for_http() {
       exit 1
     fi
 
-    attempts=$((attempts + 1))
-    if [[ "${attempts}" -ge 60 ]]; then
-      echo "[oysterun-service] error: timed out waiting for ${label} at ${url}" >&2
-      if [[ -f "${log_file}" ]]; then
-        echo "[oysterun-service] Last ${label} log lines:" >&2
-        tail -n 40 "${log_file}" >&2 || true
-      fi
-      exit 1
-    fi
-
     sleep 1
   done
 }
@@ -2013,17 +2004,22 @@ sqlite_sidecar_paths_for_db() {
 stack_host_state_paths() {
   sqlite_sidecar_paths_for_db "${HOST_TRANSCRIPTS_DB_PATH}"
   sqlite_sidecar_paths_for_db "${MATRIX_DB_PATH}"
+  local matrix_sqlite_path node_bin
+  node_bin="$(require_node_runtime "Matrix database holder inspection")" || return 1
+  matrix_sqlite_path="$("${node_bin}" --input-type=module -e 'const { routeCMatrixSQLiteStoragePath } = await import(process.argv[1]); console.log(routeCMatrixSQLiteStoragePath(process.argv[2]));' "${ROOT_DIR}/host-service/routec-matrix-storage-paths.mjs" "${MATRIX_DB_PATH}")" || return 1
+  sqlite_sidecar_paths_for_db "${matrix_sqlite_path}"
 }
 
 stack_host_state_holder_pids() {
   local paths=()
-  local path
+  local path state_paths
+  state_paths="$(stack_host_state_paths)" || return 1
 
   while IFS= read -r path; do
     if [[ -n "${path}" && -e "${path}" ]]; then
       paths+=("${path}")
     fi
-  done < <(stack_host_state_paths)
+  done <<< "${state_paths}"
 
   if (( ${#paths[@]} == 0 )); then
     return 0
@@ -2067,7 +2063,7 @@ stop_stale_stack_host_state_holders() {
   local holders=""
   local candidates=()
 
-  holders="$(stack_host_state_holder_pids)"
+  holders="$(stack_host_state_holder_pids)" || return 1
   if [[ -z "${holders}" ]]; then
     return 0
   fi
@@ -2080,6 +2076,45 @@ stop_stale_stack_host_state_holders() {
       continue
     fi
     if pid_matches_oysterun_host_server "${pid}"; then
+      local holder_node holder_check_status
+      holder_node="$(require_node_runtime "Host database holder ownership")" || return 1
+      if "${holder_node}" --input-type=module -e '
+        import { readFileSync } from "node:fs";
+        const [modulePath, runtimePath, pid, command, cwd, configDir, activePackage, stackName] = process.argv.slice(1);
+        try {
+          const { assertHostStateHolder } = await import(modulePath);
+          const runtime = JSON.parse(readFileSync(runtimePath, "utf8"));
+          const holder = { pid, command, cwd, configDir, activePackage, stackName };
+          try { assertHostStateHolder(runtime, holder); }
+          catch (error) {
+            if (!process.env.OYSTERUN_RETAINED_HOST_CWD) throw error;
+            const { assertReceiptBoundSourceHolder } = await import(`${activePackage}/host-service/retained-host-state-holder.mjs`);
+            assertReceiptBoundSourceHolder(runtime, holder, {
+              operationId: process.env.OYSTERUN_LIFECYCLE_OPERATION_ID,
+              receiptPath: process.env.OYSTERUN_CONTINUITY_RECEIPT,
+              expectedCwd: process.env.OYSTERUN_RETAINED_HOST_CWD,
+            });
+          }
+        } catch (error) {
+          // launchd may have stopped this exact holder between the first
+          // ps/cwd observation and this check. Absence is not a live match.
+          const { processDefinitelyAbsent } = await import(`${activePackage}/host-service/initial-preflight-recovery.mjs`);
+          if (processDefinitelyAbsent(Number(pid))) {
+            console.error("[oysterun-service] Selected database holder exited during cleanup; no process was signalled.");
+            process.exitCode = 3;
+          } else {
+            console.error(`[oysterun-service] ${error.message}`);
+            process.exitCode = 1;
+          }
+        }
+      ' "${ROOT_DIR}/host-service/installer-reinstall-bindings.mjs" "${RUN_DIR}/host-runtime.json" "${pid}" "$(process_command_for_pid "${pid}")" "$(process_cwd_for_pid "${pid}")" "${CONFIG_DIR}" "${ROOT_DIR}" "${STACK_NAME}"; then
+        :
+      else
+        holder_check_status=$?
+        # Internal absence result: exclude it from the later signal list.
+        [[ "${holder_check_status}" -ne 3 ]] || continue
+        return 1
+      fi
       candidates+=("${pid}")
     else
       echo "[oysterun-service] Warning: stack ${STACK_NAME} state files are held by non-Host PID ${pid}; leaving it running" >&2

package/tool_scripts/oysterun_setup_input.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Canonical read-only setup-file/pre-input validation; also embedded in install.sh.
+setup_input_error() { printf '%s\n' "$1" >&2; return 1; }
+setup_config_has() {
+  local file="$1" key="$2" kind="$3" value
+  [[ -f "$file" ]] || return 1
+  if [[ "$(uname -s)" == Darwin ]]; then
+    local expected="$kind"; [[ "$kind" != direct ]] || expected=string
+    value=$(/usr/bin/plutil -extract "$key" raw -expect "$expected" -o - "$file" 2>/dev/null) || return 1
+    case "$kind" in bool) return 0;; direct) [[ "$value" == direct ]];; integer) [[ "$value" =~ ^[0-9]+$ ]] && (( value > 0 && value <= 65535 ));; *) [[ "$value" =~ [^[:space:]] ]];; esac
+  else
+    command -v python3 >/dev/null || { setup_input_error 'Read-only Ubuntu configuration preflight requires python3; no changes made'; return 2; }
+    python3 - "$file" "$key" "$kind" <<'PY'
+import json,sys
+try:
+ c=json.load(open(sys.argv[1]));v=c.get(sys.argv[2]);kind=sys.argv[3];ok=isinstance(v,bool) if kind=='bool' else (type(v)==int and 0<v<=65535) if kind=='integer' else v=='direct' if kind=='direct' else isinstance(v,str) and bool(v.strip())
+except Exception: ok=False
+sys.exit(0 if ok else 1)
+PY
+  fi
+}
+setup_config_ready() {
+  local dir="$1" cfg="$1/config.json"
+  setup_config_has "$cfg" port integer && setup_config_has "$cfg" dashboard_user string && setup_config_has "$cfg" dashboard_password_hash string && setup_config_has "$cfg" default_browse_path string || return 1
+  if setup_config_has "$cfg" connection_mode direct; then
+    setup_config_has "$cfg" direct_host_url string || setup_config_has "$cfg" public_base_url string
+  else
+    setup_config_has "$cfg" managed_endpoint string &&
+      { setup_config_has "$dir/cloud_identity.json" device_id string || setup_config_has "$dir/cloud_identity.json" host_id string || setup_config_has "$cfg" device_id string || setup_config_has "$cfg" host_id string; } &&
+      { setup_config_has "$dir/cloud_identity.json" device_token string || setup_config_has "$dir/cloud_identity.json" host_credential string || setup_config_has "$cfg" device_token string || setup_config_has "$cfg" host_credential string; }
+  fi
+}
+setup_input_validate() {
+  set +x
+  set +a
+  unset setup_input_snapshot
+  setup_input_snapshot=''
+  local source="$1" uid="$2" config="$3" line key value mode owner missing='' seen='|' name='' root='' password='' consent=''
+  export -n password line value
+  if [[ -f "$config/config.json" && "$(uname -s)" == Linux ]] && ! command -v python3 >/dev/null; then setup_input_error "Read-only Ubuntu configuration preflight requires python3; no changes made"; return 1; fi
+  if [[ -f "$config/config.json" ]]; then
+    if [[ "$(uname -s)" == Darwin ]]; then
+      /usr/bin/osascript -l JavaScript -e 'function run(argv) { ObjC.import("Foundation"); const text = $.NSString.stringWithContentsOfFileEncodingError(argv[0], $.NSUTF8StringEncoding, null).js; const value = JSON.parse(text); if (!value || Array.isArray(value) || typeof value !== "object") throw Error("invalid configuration"); return "valid"; }' "$config/config.json" >/dev/null 2>&1 || { setup_input_error 'Existing configuration is invalid JSON; preserve it and restore the configuration before retrying'; return 1; }
+    else
+      python3 -c 'import json,sys; value=json.load(open(sys.argv[1])); assert isinstance(value,dict)' "$config/config.json" >/dev/null 2>&1 || { setup_input_error 'Existing configuration is invalid JSON; preserve it and restore the configuration before retrying'; return 1; }
+    fi
+  fi
+  if [[ -n "$source" ]]; then
+    [[ "$source" == /* && -f "$source" && ! -L "$source" ]] || { setup_input_error 'Setup input must be an absolute regular file, not a symlink'; return 1; }
+    local parent parent_path="${source%/*}"; [[ -n "$parent_path" ]] || parent_path=/
+    parent=$(cd -P "$parent_path" && pwd) || return 1
+    [[ "$parent" == "$parent_path" ]] || { setup_input_error "Setup input path must not traverse symlinks"; return 1; }
+    exec 9< "$source" || { setup_input_error 'Setup input is not readable'; return 1; }
+    local opened=/dev/fd/9; [[ "$(uname -s)" != Linux ]] || opened=/proc/self/fd/9
+    if [[ "$(uname -s)" == Darwin ]]; then
+      owner=$(/usr/bin/stat -Lf %u "$opened"); mode=$(/usr/bin/stat -Lf %Lp "$opened")
+    else
+      owner=$(/usr/bin/stat -Lc %u "$opened"); mode=$(/usr/bin/stat -Lc %a "$opened")
+    fi
+    if ! [[ -f "$opened" && -n "$uid" && "$owner" == "$uid" && ( "$mode" == 600 || "$mode" == 400 ) ]]; then
+      exec 9<&-; setup_input_error 'Setup input must belong to the selected source owner and have private permissions (0600 or 0400)'; return 1
+    fi
+    if IFS= read -r -d '' setup_input_snapshot <&9; then
+      exec 9<&-; unset setup_input_snapshot; setup_input_error 'Setup input must be UTF-8 text without NULs'; return 1
+    fi
+    exec 9<&-
+    builtin printf '%s' "$setup_input_snapshot" | /usr/bin/iconv -f UTF-8 -t UTF-8 >/dev/null 2>&1 || { unset setup_input_snapshot; setup_input_error 'Setup input must be UTF-8 text without NULs'; return 1; }
+    while IFS= read -r line || [[ -n "$line" ]]; do
+      [[ -z "$line" || "$line" == \#* ]] && continue
+      [[ "$line" == *=* ]] || { setup_input_error 'Invalid setup input format'; return 1; }
+      key=${line%%=*}; value=${line#*=}
+      case "$key" in display_name|default_browse_root|dashboard_password|daily_telemetry_enabled) ;; *) setup_input_error 'Unknown setup input field'; return 1;; esac
+      [[ "$seen" != *"|$key|"* ]] || { setup_input_error 'Duplicate setup input field'; return 1; }; seen="$seen$key|"
+      case "$key" in
+        display_name) name="$value" ;;
+        default_browse_root) [[ -z "$value" || "$value" == /* ]] || { setup_input_error 'Setup Browse Root must be absolute'; return 1; }; root="$value" ;;
+        dashboard_password) password="$value" ;;
+        daily_telemetry_enabled) [[ "$value" == true || "$value" == false ]] || { setup_input_error 'Setup telemetry consent must be true or false'; return 1; }; consent="$value" ;;
+      esac
+    done < <(builtin printf '%s' "$setup_input_snapshot")
+    [[ -z "$root" || -d "$root" ]] || { setup_input_error "Setup Browse Root must be an existing directory"; return 1; }
+  fi
+  setup_config_ready "$config" && return 0
+  setup_config_has "$config/config.json" display_name string || [[ "$name" =~ [^[:space:]] ]] || missing="$missing display_name"
+  setup_config_has "$config/config.json" default_browse_path string || [[ -n "$root" ]] || missing="$missing default_browse_root"
+  setup_config_has "$config/config.json" dashboard_password_hash string || [[ "$password" =~ [^[:space:]] ]] || missing="$missing dashboard_password"
+  if ! { setup_config_has "$config/config.json" daily_telemetry_enabled bool && setup_config_has "$config/config.json" daily_telemetry_consent_recorded_at string; } && [[ -z "$consent" ]]; then missing="$missing daily_telemetry_enabled"; fi
+  [[ -z "$missing" ]] || { setup_input_error "Missing onboarding inputs:$missing. Resume the same command from a terminal or with --setup-input-file /absolute/private-file"; return 1; }
+}
+
+# Only the invoking-root account-creation branch may emit this memory snapshot.
+# Anonymous pipes retain root ownership and read-only access in the target child.
+setup_input_emit_for_uid() {
+  set +x
+  builtin printf 'oysterun-root-setup-v1:%s\n' "$1"
+  builtin printf '%s' "$setup_input_snapshot"
+}

package/tool_scripts/oysterun_update_restart_runner.mjs

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { compatibilityEnvironment } from "../host-service/lifecycle-compatibility.mjs";
+import { runContinuityTransaction } from "./oysterun_continuity_transaction.mjs";
 
 import { spawnSync } from "node:child_process";
 import {
@@ -287,7 +289,7 @@ function replaceCliLink({ globalPrefix, packageRoot }) {
   symlinkSync(relative(binDir, join(packageRoot, "bin", "oysterun.mjs")), cliPath);
 }
 
-function runServiceCommand({
+export function runServiceCommand({
   identity,
   activeRoot,
   stack,
@@ -295,6 +297,7 @@ function runServiceCommand({
   operationId,
   expectedRetainedCurrentHostCwd = null,
   expectedTargetServiceDefinitionSha256 = null,
+  continuityPath = null,
 }) {
   const cli = join(activeRoot, "bin", "oysterun.mjs");
   const result = spawnSync(
@@ -317,12 +320,13 @@ function runServiceCommand({
     ],
     {
       cwd: activeRoot,
-      env: buildNodeNpmChildEnvironment(identity, {
+      env: compatibilityEnvironment(process.env.OYSTERUN_CONFIG_DIR || identity.config_dir, buildNodeNpmChildEnvironment(identity, {
         ...process.env,
         OYSTERUN_RELEASE_STACK: stack,
         OYSTERUN_STACK: stack,
         OYSTERUN_LIFECYCLE_OPERATION_ID: operationId,
-      }),
+        ...(continuityPath ? { OYSTERUN_CONTINUITY_RECEIPT: continuityPath } : {}),
+      })),
       encoding: "utf8",
       stdio: "pipe",
     }
@@ -353,6 +357,12 @@ function runServiceCommand({
 }
 
 export async function runRestartOnlyTransaction(args, overrides = {}) {
+  const continuityOperation = readUpdateOperationState({ configDir: args.config_dir });
+  if (continuityOperation.operation_id === args.operation_id && continuityOperation.continuity_path) {
+    return runContinuityTransaction(args, { ...overrides,
+      runCanonicalService: (options) => runServiceCommand(options) });
+  }
+
   const durableOperation = readUpdateOperationState({ configDir: args.config_dir });
   if (durableOperation.operation_id !== args.operation_id) {
     throw new Error("restart-only operation state changed before execution");
@@ -683,6 +693,12 @@ function restorePriorPackage({
 }
 
 export async function runUpdateRestartTransaction(args, overrides = {}) {
+  const continuityOperation = readUpdateOperationState({ configDir: args.config_dir });
+  if (continuityOperation.operation_id === args.operation_id && continuityOperation.continuity_path) {
+    return runContinuityTransaction(args, { ...overrides,
+      runCanonicalService: (options) => runServiceCommand(options) });
+  }
+
   const receipt = readJsonObject(args.result_path, "update preparation receipt");
   const durableOperation = readUpdateOperationState({ configDir: args.config_dir });
   if (

package/tool_scripts/p233_legacy_bootstrap.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+// One-time 1.5.7 -> reviewed beta adapter. This is intentionally not exposed
+// through oysterun's public command table or Host Preferences.
+import { existsSync, lstatSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import {
+  continuityDigest, continuityFailure, continuityReceiptPath, prepareContinuity,
+  bindFreshContinuityBaseline, readContinuity, writeContinuityAtomic, recordContinuityRecovery,
+  qualifyContinuitySessions,
+} from "../host-service/lifecycle-continuity.mjs";
+import { digestContinuityPackage, finalizeContinuityAssets } from "../host-service/lifecycle-continuity-assets.mjs";
+import { createContinuityProbeGrant, fetchContinuityObservation } from "../host-service/lifecycle-continuity-probe.mjs";
+import { resolveNodeNpmRuntimeIdentity, buildNodeNpmChildEnvironment } from "../host-service/node-npm-runtime-identity.mjs";
+import { buildServiceRenderBundle, getServiceDefinitionIdentity } from "../host-service/lifecycle-service-render-bundle.mjs";
+import { assertServiceMigrationInvariants, commitServiceDefinitionMigration, renderServiceDefinition } from "../host-service/service-definition-migration.mjs";
+import { readHostRuntimeMetadata } from "../host-service/host-runtime-diagnostics.mjs";
+import { readHostRestartRestoreState } from "../host-service/restart-restore-state.mjs";
+import { readUpdateOperationState, writeUpdateOperationState } from "../host-service/update-reminder-state.mjs";
+import { installOysterunUpdate } from "./install_oysterun_update.mjs";
+import { runServiceCommand } from "./oysterun_update_restart_runner.mjs";
+import { inspectContinuityListener, runContinuityTransaction } from "./oysterun_continuity_transaction.mjs";
+import { compareOysterunSemver } from "../host-service/npm-update-policy.mjs";
+
+const SCRIPT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const fail = (check, message) => { throw continuityFailure("legacy_bootstrap", check, message); };
+const inside = (parent, child) => { const r = relative(parent, child); return r === "" || (!r.startsWith("..") && !isAbsolute(r)); };
+function privateJson(path, { requirePrivate = true } = {}) {
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || (requirePrivate && (stat.mode & 0o077))) fail("private_plan", "Plan and authentication input must be private regular files.");
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+export function validateP233BootstrapPlan(path, sha256, { controllerRoot = SCRIPT_ROOT } = {}) {
+  if (!isAbsolute(path) || !/^[a-f0-9]{64}$/.test(sha256 || "") || continuityDigest(readFileSync(path)) !== sha256) fail("plan_hash", "The exact reviewed plan hash is required.");
+  const p = privateJson(path);
+  if (p.schema !== "oysterun.p233.legacy_bootstrap.v1" || p.source_version !== "1.5.7" ||
+      !/^1\.6\.0-beta\.\d+$/.test(p.target_version || "") || compareOysterunSemver(p.target_version, "1.6.0-beta.2") !== 1) fail("version_boundary", "P233 only migrates 1.5.7 to the exact newly reviewed 1.6.0 beta.");
+  for (const key of ["prefix", "config_dir", "browser_root", "controller_root", "artifact_path", "credential_path", "node_bin", "npm_cli", "service_definition_path"]) {
+    if (!isAbsolute(p[key] || "")) fail("absolute_geometry", `The reviewed ${key} must be absolute.`);
+  }
+  if (!/^[A-Za-z0-9-]+$/.test(p.operation_id || "") || !Number.isInteger(p.port) || p.port < 1 || p.port > 65535) fail("operation_geometry", "Operation identity or exact port is invalid.");
+  if (resolve(controllerRoot) !== p.controller_root || inside(p.prefix, p.controller_root) || inside(p.prefix, p.artifact_path) ||
+      inside(p.prefix, path) || inside(p.prefix, p.credential_path)) fail("external_control_plane", "Controller, plan, artifact and authentication input must remain outside the active npm prefix.");
+  if (p.mode === "production") {
+    if (p.prefix !== "/opt/homebrew" || p.port !== 8802 || p.stack !== "production" ||
+        p.node_bin !== "/opt/homebrew/opt/node@22/bin/node" ||
+        p.npm_cli !== "/opt/homebrew/opt/node@22/lib/node_modules/npm/bin/npm-cli.js" ||
+        p.config_dir !== join(p.owner_home, ".oysterun") || p.production_release !== "OWNER_RELEASED_P233_EXACT_ARTIFACT" ||
+        p.legacy_maintenance_window?.session_lifecycle_quiesced !== true) fail("production_boundary", "Production requires the exact reviewed legacy geometry, released artifact plan and an exclusive Session lifecycle maintenance window.");
+  } else if (p.mode === "task_owned") {
+    const owner = privateJson(p.ownership_path);
+    if (owner.task !== "P233" || p.port === 8802 || p.stack === "production" ||
+        !inside(owner.task_root, p.prefix) || !inside(owner.task_root, p.config_dir) || !inside(owner.task_root, p.browser_root) ||
+        owner.prefix !== p.prefix || owner.config_dir !== p.config_dir || owner.port !== p.port || owner.stack !== p.stack ||
+        owner.service_definition !== p.service_definition_path) fail("task_ownership", "Rehearsal must bind only fresh P233 task-owned resources.");
+  } else fail("mode", "The plan must explicitly select production or task_owned.");
+  const service = getServiceDefinitionIdentity({ stackName: p.stack, configDir: p.config_dir, homeDir: p.owner_home });
+  if (service.definitionPath !== p.service_definition_path || service.serviceLabel !== p.service_label) fail("definition_geometry", "The service definition does not match the canonical stack geometry.");
+  if (continuityDigest(readFileSync(p.artifact_path)) !== p.artifact_sha256 || digestContinuityPackage(p.controller_root) !== p.controller_tree_sha256) fail("artifact_hash", "Reviewed artifact or immutable external controller changed.");
+  const manifest = spawnSync("/usr/bin/tar", ["-xOf", p.artifact_path, "package/package.json"], { encoding: "utf8" });
+  if (manifest.status !== 0 || JSON.parse(manifest.stdout).version !== p.target_version) fail("artifact_version", "Artifact manifest does not match the exact reviewed target.");
+  const identity = resolveNodeNpmRuntimeIdentity({ nodeBin: p.node_bin, npmCli: p.npm_cli });
+  if (!/^v22\./.test(identity.node_version) || identity.toolchain_identity_digest !== p.runtime_identity_digest ||
+      realpathSync(process.execPath) !== identity.node_realpath) fail("node22_identity", "Controller and Host require the exact reviewed Node 22/npm runtime identity.");
+  const rawConfig = JSON.parse(readFileSync(join(p.config_dir, "config.json"), "utf8"));
+  // Historical setup writes this existing identity with its own mode. Do not
+  // reconfigure the Host merely to read it; new control inputs stay private.
+  const cloudIdentity = privateJson(join(p.config_dir, "cloud_identity.json"), { requirePrivate: false });
+  const config = { ...rawConfig, device_id: cloudIdentity.host_id || cloudIdentity.device_id || rawConfig.device_id };
+  if (config.device_id !== p.device_id || realpathSync(config.default_browse_path) !== p.browser_root ||
+      config.managed_endpoint !== p.managed_endpoint || !p.managed_endpoint?.startsWith("https://")) fail("host_identity", "Existing device, Browser Root or managed route differs from the reviewed plan.");
+  return { plan: p, identity, config, path, sha256 };
+}
+
+export function createNormalHostReader(plan) {
+  const credentials = privateJson(plan.credential_path);
+  if (typeof credentials.username !== "string" || typeof credentials.password !== "string") fail("normal_login_input", "Provide normal Host username/password in the private authentication input.");
+  return async (origin, pathname, { method = "GET", body } = {}) => {
+    if (![new URL(plan.managed_endpoint).origin, `http://127.0.0.1:${plan.port}`].includes(origin)) fail("read_origin", "Read target is outside the retained Host routes.");
+    const login = await fetch(new URL("/auth/login", origin), { method: "POST", headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(credentials), redirect: "error", signal: AbortSignal.timeout(10_000) });
+    if (!login.ok) throw continuityFailure("authentication", "http_status", `Normal Host login returned HTTP ${login.status}.`);
+    const authenticated = await login.json();
+    if (!authenticated.token) fail("login_token", "Normal Host login did not issue a session token.");
+    const response = await fetch(new URL(pathname, origin), { method, headers: { Authorization: `Bearer ${authenticated.token}`, "Content-Type": "application/json" },
+      ...(body ? { body: JSON.stringify(body) } : {}), redirect: "error", signal: AbortSignal.timeout(15_000) });
+    if (!response.ok) throw continuityFailure("legacy_read", "http_status", `Bounded Host operation returned HTTP ${response.status}.`);
+    return response.json();
+  };
+}
+
+export function createP233LegacyObservation({ plan, identity, config, readNormal }) {
+  return async ({ origin, retained = null }) => {
+    const metadata = readHostRuntimeMetadata(plan.config_dir);
+    const pids = inspectContinuityListener(plan.port);
+    if (pids.length !== 1 || pids[0] !== metadata?.pid || metadata.port !== plan.port ||
+        metadata.config_dir !== plan.config_dir || metadata.node_npm_identity_digest !== identity.toolchain_identity_digest) fail("legacy_runtime_identity", "Live legacy Host does not match its retained process/runtime authority.");
+    const rows = (await readNormal(origin, "/sessions?include_previews=false")).sessions;
+    const sessions = [];
+    for (const row of rows.filter((row) => row.alive || row.ready)) {
+      const id = row.sessionId || row.id;
+      const status = await readNormal(origin, `/session/status?session_id=${encodeURIComponent(id)}`);
+      const prior = retained?.sessions.find((entry) => entry.session_id === id);
+      let anchors = prior?.history_anchors;
+      if (!anchors) {
+        const tail = await readNormal(origin, `/session/messages?session_id=${encodeURIComponent(id)}&agent_id=${encodeURIComponent(status.agent_id)}&recent_tail=true&limit=2`);
+        anchors = tail.messages.map((message) => ({ event_id: message.matrix_event_id }));
+      }
+      const history = [];
+      for (const anchor of anchors) {
+        const context = await readNormal(origin, `/session/messages-around?session_id=${encodeURIComponent(id)}&event_id=${encodeURIComponent(anchor.event_id)}&before=0&after=0`);
+        if (!context.target_found) fail("legacy_history", "A retained committed Matrix anchor is missing.");
+        history.push({ event_id: anchor.event_id, sha256: continuityDigest(context.target_message) });
+      }
+      sessions.push({ session_id: id, agent_id: status.agent_id, agent_folder: realpathSync(status.cwd), provider: status.provider,
+        provider_resume_id: status.provider_resume_id, provider_thread_id: status.provider_thread_id || status.provider_resume_id,
+        alive: status.alive, ready: status.ready, history_anchors: history });
+    }
+    const host = { version: metadata.package_version, pid: metadata.pid, port: metadata.port, stack: plan.stack,
+      package_root: metadata.repo_root,
+      process_cwd: (() => {
+        const cwd = spawnSync("/usr/sbin/lsof", ["-a", "-p", String(metadata.pid), "-d", "cwd", "-Fn"], { encoding: "utf8" });
+        const values = cwd.stdout.split("\n").filter((line) => line.startsWith("n")).map((line) => line.slice(1));
+        if (cwd.status !== 0 || values.length !== 1) fail("legacy_process_cwd", "Cannot prove the exact legacy process cwd.");
+        return values[0];
+      })(),
+      node_version: metadata.node_version, runtime_identity_digest: metadata.node_npm_identity_digest,
+      device_id: config.device_id, config_dir: plan.config_dir, host_folder: plan.config_dir, browser_root: plan.browser_root,
+      managed_endpoint: plan.managed_endpoint, direct_host_url: config.direct_host_url || config.public_base_url || null,
+      service_definition_path: plan.service_definition_path, service_definition_sha256: continuityDigest(readFileSync(plan.service_definition_path)) };
+    const restore = readHostRestartRestoreState({ configDir: plan.config_dir });
+    return { host, sessions, baseline: { host, sessions, captured_at: new Date().toISOString() },
+      restore_result: restore?.restore_result, restart_state: restore?.state, restart_id: restore?.restart_id,
+      authenticated_user_path: { pid: metadata.pid }, route: { origin, device_id: plan.device_id,
+        operation_id: plan.operation_id, authenticated: true, http_status: 200, authentication: "normal_dashboard_login" } };
+  };
+}
+
+export async function executeP233Bootstrap(action, reviewed) {
+  if (!["forward", "recover", "rollback", "finalize"].includes(action)) fail("action", "Use exactly forward, recover, rollback or finalize.");
+  const { plan: p, identity, config } = reviewed;
+  const activeRoot = join(p.prefix, "lib", "node_modules", "oysterun");
+  const path = continuityReceiptPath(p.config_dir, p.operation_id);
+  const resultPath = join(p.config_dir, "operation_logs", `p233-${p.operation_id}-preparation.json`);
+  const healthUrl = `http://127.0.0.1:${p.port}/health`;
+  if (action !== "forward") {
+    const retained = readContinuity(path, p.operation_id);
+    if (retained.reviewed_plan_sha256 !== reviewed.sha256 || retained.controller_tree_sha256 !== p.controller_tree_sha256) fail("recovery_authority", "Every continuation, including finalize, requires the exact original reviewed plan and controller.");
+  }
+  Object.assign(process.env, buildNodeNpmChildEnvironment(identity, { ...process.env,
+    OYSTERUN_CONFIG_DIR: p.config_dir, OYSTERUN_PORT: String(p.port), OYSTERUN_STACK: p.stack,
+    OYSTERUN_RELEASE_STACK: p.stack, OYSTERUN_STACKS_DIR: p.stacks_dir,
+    OYSTERUN_UPDATE_REGISTRY_URL: p.registry?.override_active ? p.registry.url : "",
+    OYSTERUN_UPDATE_REGISTRY_STATE_PATH: p.registry_state_path || "",
+  }));
+  if (!p.registry_state_path) delete process.env.OYSTERUN_UPDATE_REGISTRY_STATE_PATH;
+  if (!p.registry?.override_active) delete process.env.OYSTERUN_UPDATE_REGISTRY_URL;
+  if (action === "finalize") return finalizeContinuityAssets({ path, operationId: p.operation_id, configDir: p.config_dir, activePackageRoot: activeRoot });
+  const readNormal = createNormalHostReader(p);
+  const legacyObserve = createP233LegacyObservation({ plan: p, identity, config, readNormal });
+  const observe = async (options) => {
+    const metadata = readHostRuntimeMetadata(p.config_dir);
+    if (metadata?.package_version === "1.5.7") return legacyObserve({ ...options, retained: readContinuity(path, p.operation_id).baseline });
+    await readNormal(options.origin, "/sessions?include_previews=false");
+    return fetchContinuityObservation(options);
+  };
+  if (action === "forward") {
+    if (existsSync(path)) fail("existing_operation", "Forward already has a durable operation; use recover with the same reviewed plan.");
+    const prior = readUpdateOperationState({ configDir: p.config_dir });
+    if (prior.running || prior.continuity_path && !["CLEANED", "ROLLED_BACK_HEALTHY"].includes(readContinuity(prior.continuity_path, prior.operation_id).state)) fail("operation_conflict", "Another running or retained continuity operation owns this Host; no package was changed.");
+    const initial = await legacyObserve({ origin: new URL(healthUrl).origin });
+    if (initial.host.version !== "1.5.7") fail("legacy_source", "This one-time adapter only starts on the exact 1.5.7 source.");
+    if (initial.host.process_cwd !== join(activeRoot, "host-service")) fail("legacy_active_cwd", "Legacy Host must run from its canonical active root before bootstrap.");
+    prepareContinuity({ path, operationId: p.operation_id, transactionKind: "legacy_bootstrap",
+      source: { version: "1.5.7", runtime_identity_digest: p.runtime_identity_digest,
+        package_tree_sha256: digestContinuityPackage(activeRoot), service_definition_sha256: initial.host.service_definition_sha256 },
+      target: { version: p.target_version, runtime_identity_digest: p.runtime_identity_digest, artifact_sha256: p.artifact_sha256 }, baseline: initial.baseline,
+      authority: { reviewed_plan_sha256: reviewed.sha256, controller_tree_sha256: p.controller_tree_sha256 } });
+    createContinuityProbeGrant(p.config_dir, p.operation_id);
+    writeContinuityAtomic(path, { ...readContinuity(path, p.operation_id), reviewed_plan_sha256: reviewed.sha256,
+      controller_tree_sha256: p.controller_tree_sha256 });
+    const sourceBundlePath = `${path}.source-render.json`;
+    const sourceBundle = buildServiceRenderBundle({ toolchain: identity, stackName: p.stack, registry: p.registry,
+      packageRoot: activeRoot, packageVersion: "1.5.7", configDir: p.config_dir,
+      configPath: join(p.config_dir, "config.json"), port: p.port });
+    writeContinuityAtomic(sourceBundlePath, sourceBundle);
+    try {
+      await installOysterunUpdate({ package_spec: p.artifact_path, expected_version: p.target_version,
+        active_package_root: activeRoot, node_bin: p.node_bin, npm_cli: p.npm_cli, identity_digest: p.runtime_identity_digest,
+        config_dir: p.config_dir, result_path: resultPath, operation_id: p.operation_id, retain_for_restart: "1",
+        continuity_path: path, service_definition_path: p.service_definition_path,
+        source_service_bundle_path: sourceBundlePath, service_definition_authority_path: join(p.config_dir, "service-definition-authority.json"),
+      }, { beforeActivation: async () => {
+        // The historical coordinator is asked to prepare while its source
+        // package/definition still agree, before the active-root exchange.
+        const prepared = await readNormal(new URL(healthUrl).origin, "/admin/restart-prepare", {
+          method: "POST", body: { trigger: "p233_one_time_external_bootstrap" } });
+        const fresh = await legacyObserve({ origin: new URL(healthUrl).origin });
+        bindFreshContinuityBaseline(path, p.operation_id, fresh.baseline, prepared.restart_restore?.restart_id,
+          readHostRestartRestoreState({ configDir: p.config_dir }));
+        writeUpdateOperationState({ operation_id: p.operation_id, continuity_path: path, status: "restart_scheduled",
+          transaction_kind: "update_latest_and_restart", current_version: "1.5.7", target_version: p.target_version,
+          restart_id: prepared.restart_restore?.restart_id, running: true, lifecycle_owner_pid: process.pid,
+          restart_attempted: false, result_path: resultPath }, { configDir: p.config_dir });
+      } });
+      const receipt = readContinuity(path, p.operation_id);
+      const targetBundle = buildServiceRenderBundle({ toolchain: identity, stackName: p.stack, registry: p.registry,
+        packageRoot: activeRoot, packageVersion: p.target_version, configDir: p.config_dir, configPath: join(p.config_dir, "config.json"), port: p.port });
+      assertServiceMigrationInvariants(sourceBundle, targetBundle);
+      const rendered = renderServiceDefinition(targetBundle);
+      const snapshot = JSON.parse(readFileSync(receipt.resources.service_definition_snapshot_path, "utf8"));
+      writeContinuityAtomic(path, { ...receipt, target: { ...receipt.target, service_definition_sha256: rendered.sha256 } });
+      commitServiceDefinitionMigration({ definitionPath: p.service_definition_path, snapshot, rendered });
+      writeContinuityAtomic(join(p.config_dir, "service-definition-authority.json"), {
+        schema_version: 1, package_version: p.target_version, package_manifest_sha256: targetBundle.artifact.integrity_sha256,
+        service_label: p.service_label, service_definition_path: p.service_definition_path,
+        service_definition_sha256: rendered.sha256, runtime_identity_digest: p.runtime_identity_digest, committed_at: new Date().toISOString(),
+      });
+    } catch (error) { recordContinuityRecovery(path, p.operation_id, error); }
+  }
+  const retained = readContinuity(path, p.operation_id);
+  if (retained.reviewed_plan_sha256 !== reviewed.sha256 || retained.controller_tree_sha256 !== p.controller_tree_sha256) fail("recovery_authority", "Recovery must use the exact original reviewed plan and retained controller.");
+  const projection = readUpdateOperationState({ configDir: p.config_dir });
+  if (projection.operation_id !== p.operation_id) {
+    if (projection.running || projection.continuity_path && !["CLEANED", "ROLLED_BACK_HEALTHY"].includes(readContinuity(projection.continuity_path, projection.operation_id).state)) fail("operation_conflict", "Another retained lifecycle operation owns this Host.");
+    // An interrupted PREPARED operation may precede the old coordinator's fresh
+    // prepare. Rebind its projection; never mint a new continuity operation.
+    writeUpdateOperationState({ operation_id: p.operation_id, continuity_path: path, running: false,
+      status: "rollback_failed", transaction_kind: "update_latest_and_restart",
+      current_version: "1.5.7", target_version: p.target_version, result_path: resultPath }, { configDir: p.config_dir });
+  }
+  return runContinuityTransaction({ operation_id: p.operation_id, continuity_path: path, result_path: resultPath,
+    active_package_root: activeRoot, config_dir: p.config_dir, node_bin: p.node_bin, npm_cli: p.npm_cli,
+    identity_digest: p.runtime_identity_digest, stack: p.stack, health_url: healthUrl, restart_id: retained.restart_id,
+    ...(action === "rollback" ? { restore_before_restart: "1" } : {}),
+  }, { observeContinuity: observe, runCanonicalService: runServiceCommand,
+    beforeForwardRestart: async (receipt) => {
+      // 1.5.7 has no Session admission reservation. The one-time released
+      // maintenance window is mandatory; this final read also rejects any
+      // observed live Sessions change after the pre-activation snapshot.
+      const live = await legacyObserve({ origin: new URL(healthUrl).origin, retained: receipt.baseline });
+      qualifyContinuitySessions(receipt.baseline.sessions, live.sessions, null, { requireRestore: false });
+    },
+  });
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [action, flag, path, hashFlag, sha256, ...extra] = process.argv.slice(2);
+  if (flag !== "--plan" || hashFlag !== "--sha256" || extra.length) fail("command_geometry", "Usage: node p233_legacy_bootstrap.mjs <forward|recover|rollback|finalize> --plan <absolute-private-plan> --sha256 <reviewed-plan-sha256>");
+  const result = await executeP233Bootstrap(action, validateP233BootstrapPlan(path, sha256));
+  process.stdout.write(`${JSON.stringify({ operation_id: result.operation_id, state: result.state, status: result.status })}\n`);
+}

package/tool_scripts/resolve_user_host_port.mjs

@@ -0,0 +1,15 @@
+import { readUserHostPort, assertUserHostProcess, assertUserHostServicePid } from "../host-service/host-port-resolution.mjs";
+import { readFileSync } from "node:fs";
+try {
+  const [configPath, runtimePath, configDir, mode, ...existingServicePaths] = process.argv.slice(2);
+  if (!configPath || !runtimePath || !configDir) throw new Error("Exact config and runtime paths are required.");
+  const port = readUserHostPort({ configPath, runtimePath, configDir, existingServicePaths });
+  if (mode === "process") {
+    process.stdout.write(String(assertUserHostProcess(JSON.parse(readFileSync(runtimePath, "utf8")), configDir)));
+  } else if (mode === "service-pid") {
+    process.stdout.write(String(assertUserHostServicePid(JSON.parse(readFileSync(runtimePath, "utf8")), configDir, existingServicePaths[0])));
+  } else process.stdout.write(String(port));
+} catch (error) {
+  process.stderr.write(`[oysterun-service] ${error.message}\n`);
+  process.exitCode = 1;
+}

package/tool_scripts/restart_oysterun.sh

@@ -51,8 +51,14 @@ preflight_host_restart_readiness \
   "" \
   "${EXPECTED_TARGET_SERVICE_DEFINITION_SHA256}"
 
+# P233 records the real stop attempt only after every preflight check passed.
+if [[ -n "${OYSTERUN_CONTINUITY_RECEIPT:-}" ]]; then
+  "${OYSTERUN_NODE_BIN:?}" "${SCRIPT_DIR}/../host-service/lifecycle-continuity.mjs" \
+    mark-restart "${OYSTERUN_CONTINUITY_RECEIPT}" "${ALLOW_OPERATION_ID}"
+fi
+
 if [[ "${#SERVICE_ARGS[@]}" -gt 0 ]]; then
-  if ! "${SCRIPT_DIR}/stop_oysterun.sh" "${SERVICE_ARGS[@]}"; then
+  if ! OYSTERUN_RETAINED_HOST_CWD="${EXPECTED_RETAINED_CURRENT_HOST_CWD}" "${SCRIPT_DIR}/stop_oysterun.sh" "${SERVICE_ARGS[@]}"; then
     printf '[oysterun-service] P226_CHECK stage=stop check=canonical_service_stop result=failed code=service_stop_failed\n' >&2
     exit 1
   fi
@@ -62,7 +68,7 @@ if [[ "${#SERVICE_ARGS[@]}" -gt 0 ]]; then
     exit 1
   fi
 else
-  if ! "${SCRIPT_DIR}/stop_oysterun.sh"; then
+  if ! OYSTERUN_RETAINED_HOST_CWD="${EXPECTED_RETAINED_CURRENT_HOST_CWD}" "${SCRIPT_DIR}/stop_oysterun.sh"; then
     printf '[oysterun-service] P226_CHECK stage=stop check=canonical_service_stop result=failed code=service_stop_failed\n' >&2
     exit 1
   fi

package/tool_scripts/stack_dashboard_credentials.mjs

@@ -263,7 +263,8 @@ function readJsonObject(path, { missingFallback = null } = {}) {
 
 function writeJsonObject(path, value) {
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+  if (existsSync(path)) chmodSync(path, 0o600);
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
 }
 
 function normalizeCredentialString(value, label, { required = false } = {}) {