@openclawbrain/openclaw 0.2.3 → 0.3.0

package/dist/src/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, readSync, openSync, closeSync, realpathSync, rmSync, statSync, writeFileSync, appendFileSync, symlinkSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -9,11 +9,13 @@ import { parseDaemonArgs, runDaemonCommand } from "./daemon.js";
 import { exportBrain, importBrain } from "./import-export.js";
 import { buildNormalizedEventExport } from "@openclawbrain/contracts";
 import { buildTeacherSupervisionArtifactsFromNormalizedEventExport, createAlwaysOnLearningRuntimeState, describeAlwaysOnLearningRuntimeState, drainAlwaysOnLearningRuntime, loadOrInitBaseline, materializeAlwaysOnLearningCandidatePack, persistBaseline } from "@openclawbrain/learner";
-import { inspectActivationState, promoteCandidatePack, readLearningSpineLogEntries, stageCandidatePack } from "@openclawbrain/pack-format";
+import { inspectActivationState, loadPackFromActivation, promoteCandidatePack, readLearningSpineLogEntries, stageCandidatePack } from "@openclawbrain/pack-format";
 import { resolveActivationRoot } from "./resolve-activation-root.js";
-import { buildNormalizedEventExportFromScannedEvents, bootstrapRuntimeAttach, buildOperatorSurfaceReport, compileRuntimeContext, createAsyncTeacherLiveLoop, createOpenClawLocalSessionTail, createRuntimeEventExportScanner, describeCurrentProfileBrainStatus, formatBootstrapRuntimeAttachReport, formatOperatorRollbackReport, loadRuntimeEventExportBundle, rollbackRuntimeAttach, resolveAsyncTeacherLiveLoopSnapshotPath, scanLiveEventExport, scanRecordedSession, summarizeLearningPathFromMaterialization, summarizeNormalizedEventExportLabelFlow, writeScannedEventExportBundle } from "./index.js";
+import { buildNormalizedEventExportFromScannedEvents, bootstrapRuntimeAttach, buildOperatorSurfaceReport, compileRuntimeContext, createAsyncTeacherLiveLoop, createOpenClawLocalSessionTail, createRuntimeEventExportScanner, describeCurrentProfileBrainStatus, formatBootstrapRuntimeAttachReport, formatOperatorRollbackReport, loadWatchTeacherSnapshotState, loadRuntimeEventExportBundle, persistWatchTeacherSnapshot, rollbackRuntimeAttach, resolveOperatorTeacherSnapshotPath, resolveAsyncTeacherLiveLoopSnapshotPath, resolveWatchSessionTailCursorPath, resolveWatchStateRoot, resolveWatchTeacherSnapshotPath, scanLiveEventExport, scanRecordedSession, summarizeLearningPathFromMaterialization, summarizeNormalizedEventExportLabelFlow, writeScannedEventExportBundle } from "./index.js";
+import { appendLearningUpdateLogs } from "./learning-spine.js";
 import { buildPassiveLearningSessionExportFromOpenClawSessionStore } from "./local-session-passive-learning.js";
 import { discoverOpenClawSessionStores, loadOpenClawSessionIndex, readOpenClawSessionFile } from "./session-store.js";
+import { readOpenClawBrainProviderConfig } from "./provider-config.js";
 function quoteShellArg(value) {
     return `'${value.replace(/'/g, `"'"'`)}'`;
 }
@@ -27,7 +29,7 @@ function normalizeOptionalCliString(value) {
 function getCliHomeDir() {
     return process.env.HOME ?? process.env.USERPROFILE ?? "~";
 }
-function discoverSetupCandidateOpenClawHomes(homeDir = getCliHomeDir()) {
+function discoverInstallCandidateOpenClawHomes(homeDir = getCliHomeDir()) {
     const resolvedHomeDir = path.resolve(homeDir);
     let entries;
     try {
@@ -42,7 +44,7 @@ function discoverSetupCandidateOpenClawHomes(homeDir = getCliHomeDir()) {
         .filter((candidate) => existsSync(path.join(candidate, "openclaw.json")))
         .sort((left, right) => left.localeCompare(right));
 }
-function formatSetupOpenClawHomeSource(source) {
+function formatInstallOpenClawHomeSource(source) {
     switch (source) {
         case "explicit":
             return "--openclaw-home";
@@ -54,7 +56,7 @@ function formatSetupOpenClawHomeSource(source) {
             return source;
     }
 }
-function resolveSetupOpenClawHome(explicitOpenclawHome) {
+function resolveInstallOpenClawHome(explicitOpenclawHome) {
     const normalizedExplicitHome = normalizeOptionalCliString(explicitOpenclawHome);
     if (normalizedExplicitHome !== null) {
         return {
@@ -69,7 +71,7 @@ function resolveSetupOpenClawHome(explicitOpenclawHome) {
             openclawHomeSource: "env"
         };
     }
-    const discoveredHomes = discoverSetupCandidateOpenClawHomes();
+    const discoveredHomes = discoverInstallCandidateOpenClawHomes();
     if (discoveredHomes.length === 1) {
         return {
             openclawHome: path.resolve(discoveredHomes[0]),
@@ -85,14 +87,14 @@ function resolveSetupOpenClawHome(explicitOpenclawHome) {
         })
             .join("\n");
         throw new Error([
-            "Refusing ambiguous live OpenClaw targets for install/setup.",
+            "Refusing ambiguous live OpenClaw targets for install.",
             targetChoices,
             "Pass --openclaw-home <path> or set OPENCLAW_HOME to pin one profile."
         ].join("\n"));
     }
     throw new Error("No OpenClaw profile home found. Pass --openclaw-home <path> or set OPENCLAW_HOME.");
 }
-function resolveSetupActivationRoot(openclawHome, explicitActivationRoot) {
+function resolveInstallActivationRoot(openclawHome, explicitActivationRoot) {
     const normalizedExplicitActivationRoot = normalizeOptionalCliString(explicitActivationRoot);
     if (normalizedExplicitActivationRoot !== null) {
         return {
@@ -105,7 +107,7 @@ function resolveSetupActivationRoot(openclawHome, explicitActivationRoot) {
         source: "default_from_openclaw_home"
     };
 }
-function resolveSetupWorkspaceId(openclawHome, explicitWorkspaceId) {
+function resolveInstallWorkspaceId(openclawHome, explicitWorkspaceId) {
     const normalizedExplicitWorkspaceId = normalizeOptionalCliString(explicitWorkspaceId);
     if (normalizedExplicitWorkspaceId !== null) {
         return {
@@ -124,7 +126,7 @@ function resolveSetupWorkspaceId(openclawHome, explicitWorkspaceId) {
         }
     }
     catch {
-        // Fall back to the profile-home name when setup is pointed at an incomplete or not-yet-readable profile.
+        // Fall back to the profile-home name when install is pointed at an incomplete or not-yet-readable profile.
     }
     const dirName = path.basename(openclawHome);
     if (dirName === ".openclaw") {
@@ -145,13 +147,13 @@ function resolveSetupWorkspaceId(openclawHome, explicitWorkspaceId) {
         source: "fallback"
     };
 }
-function formatSetupActivationRootSource(source) {
+function formatInstallActivationRootSource(source) {
     if (source === "explicit") {
         return "explicit --activation-root";
     }
     return "default beside --openclaw-home";
 }
-function formatSetupWorkspaceIdSource(source) {
+function formatInstallWorkspaceIdSource(source) {
     switch (source) {
         case "explicit":
             return "explicit --workspace-id";
@@ -262,7 +264,7 @@ function buildDoctorDeletedMessage(args) {
     const jsonCommand = buildStatusReplacementCommand(replacementInput, true);
     const lines = [
         "`doctor` is no longer a separate operator surface.",
-        'Use `openclawbrain status` as the human answer to "How\'s the brain?" and `status --json` for the canonical current-profile object.',
+        'Use `openclawbrain status --activation-root <path>` as the human answer to "How\'s the brain?" and `status --json` for the canonical current-profile object.',
         "Use `describeAttachStatus()` or the proof helpers only when you need deeper activation diagnostics."
     ];
     if (json && jsonCommand !== null) {
@@ -276,36 +278,42 @@ function buildDoctorDeletedMessage(args) {
     }
     return lines.join(" ");
 }
+function buildSetupDeletedMessage() {
+    return [
+        "`setup` has been removed.",
+        "Use `openclawbrain install` instead.",
+        "The install command still accepts the explicit targeting flags that setup used: `--openclaw-home`, `--activation-root`, `--workspace-id`, and `--shared`."
+    ].join(" ");
+}
 function operatorCliHelp() {
     return [
         "Usage:",
         "  openclawbrain install [--openclaw-home <path>] [options]",
-        "  openclawbrain setup [--openclaw-home <path>] [options]              # compatibility alias",
         "  openclawbrain detach --openclaw-home <path> [options]",
         "  openclawbrain uninstall --openclaw-home <path> [--keep-data|--purge-data] [options]",
         "  openclawbrain attach --activation-root <path> [options]",
-        "  openclawbrain <status|rollback> --activation-root <path> [options]",
-        "  openclawbrain context \"message\" [--activation-root <path>]",
-        "  openclawbrain history [--activation-root <path>] [--limit N] [--json]",
+        "  openclawbrain <status|rollback> [--activation-root <path>|--openclaw-home <path>] [options]",
+        "  openclawbrain context \"message\" [--activation-root <path>|--openclaw-home <path>]",
+        "  openclawbrain history [--activation-root <path>|--openclaw-home <path>] [--limit N] [--json]",
         "  openclawbrain scan --session <trace.json> --root <path> [options]",
         "  openclawbrain scan --live <event-export-path> --workspace <workspace.json> [options]",
-        "  openclawbrain learn [--activation-root <path>] [--json]",
-        "  openclawbrain watch [--activation-root <path>] [--scan-root <path>] [--interval <seconds>]",
-        "  openclawbrain daemon <start|stop|status|logs> [--activation-root <path>]",
-        "  openclawbrain-ops <status|rollback> --activation-root <path> [options]  # compatibility alias",
+        "  openclawbrain learn [--activation-root <path>|--openclaw-home <path>] [--json]",
+        "  openclawbrain watch --activation-root <path> [--scan-root <path>] [--interval <seconds>]",
+        "  openclawbrain daemon <start|stop|status|logs> --activation-root <path> [--json]",
+        "  openclawbrain-ops <status|rollback> [--activation-root <path>|--openclaw-home <path>] [options]  # compatibility alias",
         "  openclawbrain-ops scan --session <trace.json> --root <path> [options]    # compatibility alias",
         "",
         "Options:",
-        "  --openclaw-home <path>      OpenClaw profile home dir for install/setup/detach/uninstall (e.g. ~/.openclaw-Tern). Auto-selects for install/setup when OPENCLAW_HOME is set or exactly one live profile home exists.",
-        "  --shared                    Set brain-attachment-policy to shared instead of dedicated (install/setup only).",
-        "  --activation-root <path>    Activation root for attach/detach/uninstall; install/setup defaults to sibling .openclawbrain/activation next to the selected OpenClaw home.",
+        "  --openclaw-home <path>      OpenClaw profile home dir for install/detach/uninstall (e.g. ~/.openclaw-Tern). Also pins status/rollback/context/history/learn to that installed profile when applicable.",
+        "  --shared                    Set brain-attachment-policy to shared instead of dedicated (install only).",
+        "  --activation-root <path>    Explicit activation root for attach/watch/daemon and other stateful commands; install defaults to sibling .openclawbrain/activation next to the selected OpenClaw home.",
         "  --keep-data                 Preserve activation data on uninstall; detach always behaves this way.",
         "  --purge-data                Remove activation data on uninstall; requires the installed profile hook or --activation-root.",
         "  --restart <never|safe|external>  Restart guidance mode for detach/uninstall. 'safe' is conservative; 'never' leaves restart entirely to the operator.",
         "  --pack-root <path>          Initial pack root directory (attach only; defaults to <activation-root>/packs/initial).",
-        "  --workspace-id <id>         Workspace identifier for attach/install/setup provenance; install/setup defaults to openclaw.json.profile or the profile name, attach defaults to 'workspace'.",
+        "  --workspace-id <id>         Workspace identifier for attach/install provenance; install defaults to openclaw.json.profile or the profile name, attach defaults to 'workspace'.",
         "  --event-export <path>       Event-export bundle root or normalized export JSON payload.",
-        "  --teacher-snapshot <path>   Async teacher snapshot JSON from teacherLoop.snapshot()/flush(); keeps live-first, principal-priority, and passive-backfill learner truth explicit.",
+        "  --teacher-snapshot <path>   Canonical watch teacher snapshot JSON or raw async teacher snapshot JSON; keeps live-first, principal-priority, and passive-backfill learner truth explicit.",
         "  --updated-at <iso>          Observation time to use for freshness checks.",
         "  --brain-attachment-policy <undeclared|dedicated|shared>  Override attachment policy semantics for status inspection.",
         "  --detailed                   Show verbose diagnostic output for status (default is human-friendly summary).",
@@ -329,14 +337,15 @@ function operatorCliHelp() {
         "  0. uninstall   openclawbrain uninstall --openclaw-home <path> --keep-data|--purge-data — remove the profile hook and choose the data outcome explicitly",
         "  0. context     openclawbrain context \"hello\" — preview the brain context that would be injected for a message",
         "  0. attach      openclawbrain attach --activation-root <path>",
-        "  1. status          answer \"How's the brain?\" for the current profile on that activation root",
-        "  2. status --json   read the canonical current_profile_brain_status.v1 object for that same boundary",
-        "  3. rollback --dry-run   preview active <- previous, active -> candidate",
-        "  4. rollback             apply the rollback when the preview says ready",
+        "  1. status          openclawbrain status --activation-root <path> — answer \"How's the brain?\" for that boundary",
+        "  2. status --json   openclawbrain status --activation-root <path> --json — read the canonical current_profile_brain_status.v1 object",
+        "  3. rollback --dry-run   openclawbrain rollback --activation-root <path> --dry-run — preview active <- previous, active -> candidate",
+        "  4. rollback             openclawbrain rollback --activation-root <path> — apply the rollback when the preview says ready",
         "  5. scan --session   replay one sanitized session trace across no_brain, seed_pack, and learned_replay",
         "  6. scan --live      scan one live event export into teacher/learner state without claiming a daemon is running",
         "  status --teacher-snapshot keeps the current live-first / principal-priority / passive-backfill learner order visible when that snapshot exists",
-        "  watch/daemon persist that snapshot at <activation-root>/async-teacher-live-loop.snapshot.json; --teacher-snapshot overrides the default path",
+        "  watch/daemon persist their operator snapshot at <activation-root>/watch/teacher-snapshot.json; --teacher-snapshot overrides the default path",
+        "  watch Ollama teacher labels: set OPENCLAWBRAIN_TEACHER_PROVIDER=ollama plus optional OPENCLAWBRAIN_TEACHER_BASE_URL, OPENCLAWBRAIN_TEACHER_MODEL, and OPENCLAWBRAIN_TEACHER_* budget vars",
         "",
         "Exit codes:",
         "  status: 0 on successful inspection, 1 on input/read failure.",
@@ -398,6 +407,7 @@ function formatCurrentProfileStatusSummary(status, report) {
         `host        runtime=${status.host.runtimeOwner} activation=${status.host.activationRoot}`,
         `profile     selector=${status.profile.selector}${profileIdSuffix} attachment=${status.attachment.state} policy=${status.attachment.policyMode}`,
         `manyProfile surface=${report.manyProfile.operatorSurface} policy=${report.manyProfile.declaredAttachmentPolicy} intent=${report.manyProfile.sameGatewayIntent} checkedProof=${report.manyProfile.checkedInProofTopology} sameGatewayProof=${yesNo(report.manyProfile.sameGatewayProof)} sharedWriteProof=${yesNo(report.manyProfile.sharedWriteSafetyProof)}`,
+        `activation  state=${status.brainStatus.activationState} detail=${status.brain.detail}`,
         `brain       pack=${status.brain.activePackId ?? "none"} state=${status.brain.state} init=${status.brain.initMode ?? "unknown"} routeFreshness=${status.brain.routeFreshness} lastPromotion=${status.brain.lastPromotionAt ?? "none"} router=${status.brain.routerIdentity ?? "none"}`,
         `serve       state=${status.brainStatus.serveState} failOpen=${yesNo(status.brainStatus.failOpen)} hardFail=${yesNo(report.servePath.hardRequirementViolated)} usedRouteFn=${yesNo(status.brainStatus.usedLearnedRouteFn)} awaitingFirstExport=${yesNo(status.brainStatus.awaitingFirstExport)} detail=${status.brainStatus.detail}`,
         `route       router=${report.servePath.routerIdentity ?? status.brain.routerIdentity ?? "none"} supervision=${report.servePath.refreshStatus ?? status.brain.routeFreshness} freshness=${report.servePath.freshnessChecksum ?? "none"}`,
@@ -409,7 +419,8 @@ function formatCurrentProfileStatusSummary(status, report) {
         `graph       source=${report.graph.runtimePlasticitySource ?? "none"} ops=${formatStructuralOps(report)} changed=${yesNo(report.graph.changed)} pruned=${report.graph.prunedBlockCount ?? "none"} strongest=${report.graph.strongestBlockId ?? "none"} summary=${report.graph.operatorSummary ?? report.graph.detail}`,
         `path        ${formatLearningPathSummary(report.learningPath)}`,
         `learning    state=${report.learning.backlogState} bootstrapped=${yesNo(report.learning.bootstrapped)} mode=${report.learning.mode} next=${report.learning.nextPriorityLane} priority=${report.learning.nextPriorityBucket} pending=${report.learning.pendingLive ?? "none"}/${report.learning.pendingBackfill ?? "none"} buckets=${formatLearningBuckets(report)} warn=${formatLearningWarnings(report)} lastPack=${report.learning.lastMaterializedPackId ?? "none"} detail=${report.learning.detail}`,
-        `teacher     snapshot=${report.teacherLoop.sourcePath ?? "none"} started=${report.teacherLoop.startedAt ?? "none"} heartbeat=${report.teacherLoop.lastHeartbeatAt ?? "none"} scan=${report.teacherLoop.lastScanAt ?? report.teacherLoop.lastProcessedAt ?? "none"} queue=${report.teacherLoop.queueDepth ?? "none"}/${report.teacherLoop.queueCapacity ?? "none"} running=${yesNo(report.teacherLoop.running)} lastJob=${report.teacherLoop.lastAppliedMaterializationJobId ?? "none"} lastPack=${report.teacherLoop.lastMaterializedPackId ?? "none"}`,
+        `teacher     snapshot=${report.teacherLoop.sourcePath ?? "none"} kind=${report.teacherLoop.sourceKind} lastRun=${report.teacherLoop.lastRunAt ?? "none"} artifacts=${report.teacherLoop.artifactCount ?? "none"} freshness=${report.teacherLoop.latestFreshness} queue=${report.teacherLoop.queueDepth ?? "none"}/${report.teacherLoop.queueCapacity ?? "none"} running=${yesNo(report.teacherLoop.running)} noOp=${report.teacherLoop.lastNoOpReason} failure=${report.teacherLoop.failureMode}${report.teacherLoop.failureDetail === null ? "" : `(${report.teacherLoop.failureDetail})`}`,
+        `passive     cadence=${report.teacherLoop.learningCadence} scan=${report.teacherLoop.scanPolicy} slices=${report.teacherLoop.liveSlicesPerCycle ?? "none"}/${report.teacherLoop.backfillSlicesPerCycle ?? "none"} replayed=${report.teacherLoop.replayedBundleCount ?? "none"}/${report.teacherLoop.replayedEventCount ?? "none"} exported=${report.teacherLoop.exportedBundleCount ?? "none"}/${report.teacherLoop.exportedEventCount ?? "none"} tail=${report.teacherLoop.sessionTailSessionsTracked ?? "none"}/${report.teacherLoop.sessionTailBridgedEventCount ?? "none"} tailState=${report.teacherLoop.localSessionTailNoopReason ?? "none"} lastJob=${report.teacherLoop.lastAppliedMaterializationJobId ?? "none"} lastPack=${report.teacherLoop.lastMaterializedPackId ?? "none"}`,
         `rollback    ready=${yesNo(report.rollback.allowed)} state=${report.rollback.state} previous=${report.rollback.previousPackId ?? "none"}`,
         `proof       lastExport=${status.brain.lastExportAt ?? "none"} lastLearningUpdate=${status.brain.lastLearningUpdateAt ?? "none"} lastPromotion=${status.brain.lastPromotionAt ?? "none"}`,
         `logs        root=${status.brain.logRoot ?? "none"}`,
@@ -445,20 +456,27 @@ function buildCleanupRestartGuidance(restart) {
     return "If this OpenClaw profile is currently running, restart it before expecting the new hook state to take effect. If it is stopped, the next launch will pick it up.";
 }
 function buildStatusNextStep(status, report) {
+    const activationRootArg = quoteShellArg(status.host.activationRoot);
+    if (status.brainStatus.activationState === "broken_install") {
+        return "Repair or replace the activation root before trusting serve-path status again.";
+    }
+    if (status.brainStatus.activationState === "stale_incomplete") {
+        return "Clean up or repair the retained activation state before reattaching or promoting packs.";
+    }
     if (status.brainStatus.status === "fail") {
-        return "Run `openclawbrain status --detailed` before changing lifecycle state so the serve-path failure is explicit.";
+        return `Run \`openclawbrain status --activation-root ${activationRootArg} --detailed\` before changing lifecycle state so the serve-path failure is explicit.`;
     }
     if (status.brainStatus.awaitingFirstExport) {
-        return "Let the attached OpenClaw profile emit a real export, then rerun `openclawbrain status`.";
+        return `Let the attached OpenClaw profile emit a real export, then rerun \`openclawbrain status --activation-root ${activationRootArg}\`.`;
     }
     if (report.learning.warningStates.includes("principal_live_backlog") ||
         report.learning.warningStates.includes("active_pack_behind_latest_principal")) {
         return "A newer principal correction is still pending promotion; keep the current pack conservative until learner promotion lands.";
     }
     if (report.rollback.allowed) {
-        return "Use `openclawbrain rollback --dry-run` before restoring the previous pack.";
+        return `Use \`openclawbrain rollback --activation-root ${activationRootArg} --dry-run\` before restoring the previous pack.`;
     }
-    return "Use `openclawbrain status --detailed` when you need the full lifecycle, serve-path, and backlog proof.";
+    return `Use \`openclawbrain status --activation-root ${activationRootArg} --detailed\` when you need the full lifecycle, serve-path, and backlog proof.`;
 }
 function formatHumanFriendlyStatus(status, report) {
     // Brain status line
@@ -482,10 +500,11 @@ function formatHumanFriendlyStatus(status, report) {
         `Pack:  ${packShort} (${state})`,
         `Activation: ${activationPath}`,
         `Policy: ${policy}`,
-        `Lifecycle: attachment=${status.attachment.state} serve=${status.brainStatus.serveState} awaitingFirstExport=${yesNo(status.brainStatus.awaitingFirstExport)}`,
+        `Lifecycle: activation=${status.brainStatus.activationState} attachment=${status.attachment.state} serve=${status.brainStatus.serveState} awaitingFirstExport=${yesNo(status.brainStatus.awaitingFirstExport)}`,
         `Rollback: state=${report.rollback.state} ready=${yesNo(report.rollback.allowed)} previous=${report.rollback.previousPackId ?? "none"}`,
         `Backlog: principal=${principalFrontier} live=${pendingLive} backfill=${pendingBackfill} next=${nextLane}/${nextBucket}`,
         `Labels: ${formatLabelFlowSummary(report.labelFlow)}`,
+        `Teacher: lastRun=${report.teacherLoop.lastRunAt ?? "none"} artifacts=${report.teacherLoop.artifactCount ?? "none"} exported=${report.teacherLoop.exportedBundleCount ?? "none"}/${report.teacherLoop.exportedEventCount ?? "none"} cadence=${report.teacherLoop.learningCadence}/${report.teacherLoop.scanPolicy} failure=${report.teacherLoop.failureMode}`,
         `Learning: ${formatLearningPathSummary(report.learningPath)}`
     ];
     // Add learning/serve warnings if relevant
@@ -498,11 +517,22 @@ function formatHumanFriendlyStatus(status, report) {
     lines.push(`Next: ${buildStatusNextStep(status, report)}`);
     return lines.join("\n");
 }
-function requireActivationRoot(input, _command) {
-    // Use the shared auto-detect chain for ALL commands:
-    //   explicit flag → ~/.openclawbrain/activation → extension scan → clear error
+function requireActivationRoot(input, openclawHome, command) {
+    const explicitActivationRoot = input.activationRoot.trim().length > 0 ? input.activationRoot : null;
+    if (explicitActivationRoot !== null) {
+        return path.resolve(explicitActivationRoot);
+    }
+    if (openclawHome !== null) {
+        return resolveActivationRoot({
+            openclawHome
+        });
+    }
+    throw new Error(`${command} requires --activation-root <path> or --openclaw-home <path>; unpinned host auto-resolution is no longer supported for ${command}.`);
+}
+function resolveCliActivationRoot(explicitActivationRoot, openclawHome) {
     return resolveActivationRoot({
-        explicit: input.activationRoot.trim().length > 0 ? input.activationRoot : null,
+        explicit: explicitActivationRoot,
+        openclawHome
     });
 }
 function readJsonFile(filePath) {
@@ -571,11 +601,14 @@ export function parseOperatorCliArgs(argv) {
     if (args[0] === "doctor") {
         throw new Error(buildDoctorDeletedMessage(args.slice(1)));
     }
+    if (args[0] === "setup") {
+        throw new Error(buildSetupDeletedMessage());
+    }
     if (args[0] === "daemon") {
         args.shift();
         return parseDaemonArgs(args);
     }
-    if (args[0] === "status" || args[0] === "rollback" || args[0] === "scan" || args[0] === "attach" || args[0] === "install" || args[0] === "setup" || args[0] === "detach" || args[0] === "uninstall" || args[0] === "context" || args[0] === "history" || args[0] === "learn" || args[0] === "watch" || args[0] === "export" || args[0] === "import" || args[0] === "reset") {
+    if (args[0] === "status" || args[0] === "rollback" || args[0] === "scan" || args[0] === "attach" || args[0] === "install" || args[0] === "detach" || args[0] === "uninstall" || args[0] === "context" || args[0] === "history" || args[0] === "learn" || args[0] === "watch" || args[0] === "export" || args[0] === "import" || args[0] === "reset") {
         command = args.shift();
     }
     if (command === "learn") {
@@ -598,6 +631,15 @@ export function parseOperatorCliArgs(argv) {
                 index += 1;
                 continue;
             }
+            if (arg === "--openclaw-home") {
+                const next = args[index + 1];
+                if (next === undefined) {
+                    throw new Error("--openclaw-home requires a value");
+                }
+                openclawHome = next;
+                index += 1;
+                continue;
+            }
             if (arg.startsWith("--")) {
                 throw new Error(`unknown argument for learn: ${arg}`);
             }
@@ -607,7 +649,7 @@ export function parseOperatorCliArgs(argv) {
         }
         return {
             command,
-            activationRoot: resolveActivationRoot({ explicit: activationRoot }),
+            activationRoot: resolveCliActivationRoot(activationRoot, openclawHome),
             json,
             help
         };
@@ -663,9 +705,12 @@ export function parseOperatorCliArgs(argv) {
         if (help) {
             return { command, activationRoot: "", scanRoot: null, interval: 30, json, help };
         }
+        if (activationRoot === null || activationRoot.trim().length === 0) {
+            throw new Error("watch requires --activation-root <path>");
+        }
         return {
             command,
-            activationRoot: resolveActivationRoot({ explicit: activationRoot }),
+            activationRoot: path.resolve(activationRoot),
             scanRoot: watchScanRoot,
             interval: watchInterval,
             json,
@@ -693,6 +738,15 @@ export function parseOperatorCliArgs(argv) {
                 index += 1;
                 continue;
             }
+            if (arg === "--openclaw-home") {
+                const next = args[index + 1];
+                if (next === undefined) {
+                    throw new Error("--openclaw-home requires a value");
+                }
+                openclawHome = next;
+                index += 1;
+                continue;
+            }
             if (arg.startsWith("--")) {
                 throw new Error(`unknown argument for context: ${arg}`);
             }
@@ -707,7 +761,7 @@ export function parseOperatorCliArgs(argv) {
         return {
             command,
             message: messageParts.join(" "),
-            activationRoot: resolveActivationRoot({ explicit: activationRoot }),
+            activationRoot: resolveCliActivationRoot(activationRoot, openclawHome),
             json,
             help
         };
@@ -733,6 +787,15 @@ export function parseOperatorCliArgs(argv) {
                 index += 1;
                 continue;
             }
+            if (arg === "--openclaw-home") {
+                const next = args[index + 1];
+                if (next === undefined) {
+                    throw new Error("--openclaw-home requires a value");
+                }
+                openclawHome = next;
+                index += 1;
+                continue;
+            }
             if (arg === "--limit") {
                 const next = args[index + 1];
                 if (next === undefined) {
@@ -755,7 +818,7 @@ export function parseOperatorCliArgs(argv) {
         }
         return {
             command,
-            activationRoot: resolveActivationRoot({ explicit: activationRoot }),
+            activationRoot: resolveCliActivationRoot(activationRoot, openclawHome),
             limit: historyLimit,
             json,
             help
@@ -781,6 +844,14 @@ export function parseOperatorCliArgs(argv) {
                 index += 1;
                 continue;
             }
+            if (arg === "--openclaw-home") {
+                const next = args[index + 1];
+                if (next === undefined)
+                    throw new Error("--openclaw-home requires a value");
+                openclawHome = next;
+                index += 1;
+                continue;
+            }
             if (arg === "-o" || arg === "--output") {
                 const next = args[index + 1];
                 if (next === undefined)
@@ -798,7 +869,7 @@ export function parseOperatorCliArgs(argv) {
             throw new Error("export requires -o <output.tar.gz>");
         return {
             command,
-            activationRoot: resolveActivationRoot({ explicit: activationRoot }),
+            activationRoot: resolveCliActivationRoot(activationRoot, openclawHome),
             outputPath: path.resolve(outputPath),
             json,
             help,
@@ -829,6 +900,14 @@ export function parseOperatorCliArgs(argv) {
                 index += 1;
                 continue;
             }
+            if (arg === "--openclaw-home") {
+                const next = args[index + 1];
+                if (next === undefined)
+                    throw new Error("--openclaw-home requires a value");
+                openclawHome = next;
+                index += 1;
+                continue;
+            }
             if (arg.startsWith("--"))
                 throw new Error(`unknown argument for import: ${arg}`);
             if (archivePath === null) {
@@ -845,7 +924,7 @@ export function parseOperatorCliArgs(argv) {
         return {
             command,
             archivePath: path.resolve(archivePath),
-            activationRoot: resolveActivationRoot({ explicit: activationRoot }),
+            activationRoot: resolveCliActivationRoot(activationRoot, openclawHome),
             force,
             json,
             help,
@@ -875,13 +954,21 @@ export function parseOperatorCliArgs(argv) {
                 index += 1;
                 continue;
             }
+            if (arg === "--openclaw-home") {
+                const next = args[index + 1];
+                if (next === undefined)
+                    throw new Error("--openclaw-home requires a value");
+                openclawHome = next;
+                index += 1;
+                continue;
+            }
             throw new Error(`unknown argument for reset: ${arg}`);
         }
         if (help)
             return { command, activationRoot: "", yes: false, json, help };
         return {
             command,
-            activationRoot: resolveActivationRoot({ explicit: activationRoot }),
+            activationRoot: resolveCliActivationRoot(activationRoot, openclawHome),
             yes,
             json,
             help
@@ -1065,7 +1152,7 @@ export function parseOperatorCliArgs(argv) {
     if (command !== "uninstall" && purgeData) {
         throw new Error("--purge-data only applies to uninstall");
     }
-    if (command === "install" || command === "setup") {
+    if (command === "install") {
         if (help) {
             return {
                 command,
@@ -1080,9 +1167,9 @@ export function parseOperatorCliArgs(argv) {
                 help
             };
         }
-        const resolvedOpenclawHome = resolveSetupOpenClawHome(openclawHome);
-        const resolvedActivationRoot = resolveSetupActivationRoot(resolvedOpenclawHome.openclawHome, activationRoot);
-        const resolvedWorkspaceId = resolveSetupWorkspaceId(resolvedOpenclawHome.openclawHome, workspaceId);
+        const resolvedOpenclawHome = resolveInstallOpenClawHome(openclawHome);
+        const resolvedActivationRoot = resolveInstallActivationRoot(resolvedOpenclawHome.openclawHome, activationRoot);
+        const resolvedWorkspaceId = resolveInstallWorkspaceId(resolvedOpenclawHome.openclawHome, workspaceId);
         return {
             command,
             openclawHome: resolvedOpenclawHome.openclawHome,
@@ -1219,6 +1306,7 @@ export function parseOperatorCliArgs(argv) {
             updatedAt,
             brainAttachmentPolicy
         },
+        openclawHome: normalizeOptionalCliString(openclawHome),
         json,
         help,
         dryRun,
@@ -1282,6 +1370,36 @@ const LOCAL_WORKSPACE_EXTENSION_PACKAGES = [
     "provenance",
     "workspace-metadata"
 ];
+const OPENCLAWBRAIN_EXTENSION_TARBALL_DIR_ENV = "OPENCLAWBRAIN_EXTENSION_TARBALL_DIR";
+function resolveNpmCommand() {
+    return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+function resolveExtensionInstallReleaseTarballs() {
+    const configuredDir = normalizeOptionalCliString(process.env[OPENCLAWBRAIN_EXTENSION_TARBALL_DIR_ENV]);
+    if (configuredDir === null) {
+        return null;
+    }
+    const artifactDir = path.resolve(configuredDir);
+    let entries;
+    try {
+        entries = readdirSync(artifactDir, { withFileTypes: true });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`${OPENCLAWBRAIN_EXTENSION_TARBALL_DIR_ENV} is unreadable: ${artifactDir} (${detail})`);
+    }
+    const tarballs = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".tgz"))
+        .map((entry) => path.join(artifactDir, entry.name))
+        .sort((left, right) => left.localeCompare(right));
+    if (tarballs.length === 0) {
+        throw new Error(`${OPENCLAWBRAIN_EXTENSION_TARBALL_DIR_ENV} has no .tgz release artifacts: ${artifactDir}`);
+    }
+    return {
+        artifactDir,
+        tarballs
+    };
+}
 function resolveLocalWorkspaceRootForExtensionInstall() {
     const candidates = [
         path.resolve(__dirname, "..", "..", "..", ".."),
@@ -1458,6 +1576,85 @@ function buildHistoryEntry(record, slot, isActive) {
         current: isActive
     };
 }
+function formatInspectionFindings(findings) {
+    return findings.join("; ");
+}
+function buildInstallRefusalError(parsed, detail) {
+    const purgeCommand = `openclawbrain uninstall --openclaw-home ${quoteShellArg(parsed.openclawHome)} ` +
+        `--activation-root ${quoteShellArg(parsed.activationRoot)} --purge-data`;
+    return new Error(`Refusing to reuse activation root ${path.resolve(parsed.activationRoot)}: ${detail}. ` +
+        "Install only repairs an empty first-state root; it will not overwrite populated or broken activation state. " +
+        `Inspect: ${buildInstallStatusCommand(parsed.activationRoot)}. ` +
+        `Reset: ${purgeCommand}.`);
+}
+function inspectInstallActivationPlan(parsed) {
+    const resolvedActivationRoot = path.resolve(parsed.activationRoot);
+    const activationPointersPath = path.join(resolvedActivationRoot, "activation-pointers.json");
+    if (!existsSync(resolvedActivationRoot)) {
+        return {
+            createActivationRoot: true,
+            action: "bootstrap",
+            resolution: "new_root",
+            inspectionStep: "Activation state inspection: activation root is missing; bootstrapping first state.",
+            activePackId: null
+        };
+    }
+    const activationRootStats = statSync(resolvedActivationRoot);
+    if (!activationRootStats.isDirectory()) {
+        throw buildInstallRefusalError(parsed, "activation root path exists but is not a directory");
+    }
+    if (!existsSync(activationPointersPath)) {
+        return {
+            createActivationRoot: false,
+            action: "bootstrap",
+            resolution: "missing_pointers",
+            inspectionStep: "Activation state inspection: activation root exists but activation-pointers.json is missing; bootstrapping first state.",
+            activePackId: null
+        };
+    }
+    let inspection;
+    try {
+        inspection = inspectActivationState(resolvedActivationRoot, new Date().toISOString());
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw buildInstallRefusalError(parsed, `activation pointers could not be inspected (${detail})`);
+    }
+    if (inspection.active === null && inspection.candidate === null && inspection.previous === null) {
+        return {
+            createActivationRoot: false,
+            action: "bootstrap",
+            resolution: "empty_pointers",
+            inspectionStep: "Activation state inspection: activation pointers are present but all slots are empty; bootstrapping first state.",
+            activePackId: null
+        };
+    }
+    const unhealthySlots = [inspection.active, inspection.candidate, inspection.previous]
+        .filter((slot) => slot !== null && !slot.activationReady)
+        .map((slot) => `${slot.slot}: ${formatInspectionFindings(slot.findings)}`);
+    if (unhealthySlots.length > 0) {
+        throw buildInstallRefusalError(parsed, `activation state contains unhealthy slots (${unhealthySlots.join(" | ")})`);
+    }
+    if (inspection.active === null) {
+        const populatedSlots = [inspection.candidate, inspection.previous]
+            .filter((slot) => slot !== null)
+            .map((slot) => slot.slot);
+        throw buildInstallRefusalError(parsed, `activation state is populated without an active pack (${populatedSlots.join(", ")})`);
+    }
+    if (inspection.candidate !== null && !inspection.promotion.allowed) {
+        throw buildInstallRefusalError(parsed, `candidate slot is stale or incoherent (${formatInspectionFindings(inspection.promotion.findings)})`);
+    }
+    if (inspection.previous !== null && !inspection.rollback.allowed) {
+        throw buildInstallRefusalError(parsed, `previous slot is stale or incoherent (${formatInspectionFindings(inspection.rollback.findings)})`);
+    }
+    return {
+        createActivationRoot: false,
+        action: "keep",
+        resolution: "healthy_existing",
+        inspectionStep: `Activation state inspection: active pack ${inspection.active.packId} is healthy; keeping existing activation state.`,
+        activePackId: inspection.active.packId
+    };
+}
 function runHistoryCommand(parsed) {
     const activationRoot = parsed.activationRoot;
     const pointersPath = path.join(activationRoot, "activation-pointers.json");
@@ -1539,29 +1736,25 @@ function runHistoryCommand(parsed) {
     }
     return 0;
 }
-function runSetupCommand(parsed) {
+function runInstallCommand(parsed) {
     const steps = [];
     const commandLabel = parsed.command.toUpperCase();
-    const activationRootCreated = !existsSync(parsed.activationRoot);
-    let bootstrapped = false;
-    steps.push(`Target OpenClaw profile home: ${parsed.openclawHome} (${formatSetupOpenClawHomeSource(parsed.openclawHomeSource)})`);
+    steps.push(`Target OpenClaw profile home: ${parsed.openclawHome} (${formatInstallOpenClawHomeSource(parsed.openclawHomeSource)})`);
     // 1. Validate --openclaw-home exists and has openclaw.json
     validateOpenClawHome(parsed.openclawHome);
-    // 2. Create activation root if needed
-    if (activationRootCreated) {
+    // 2. Inspect the activation root before writing profile hook artifacts.
+    const activationPlan = inspectInstallActivationPlan(parsed);
+    // 3. Create activation root if needed
+    if (activationPlan.createActivationRoot) {
         mkdirSync(parsed.activationRoot, { recursive: true });
         steps.push(`Created activation root: ${parsed.activationRoot}`);
     }
     else {
         steps.push(`Activation root exists: ${parsed.activationRoot}`);
     }
-    // 3. Run bootstrapRuntimeAttach if not already attached
-    const activationPointersPath = path.join(parsed.activationRoot, "activation-pointers.json");
-    if (existsSync(activationPointersPath)) {
-        steps.push("Brain already attached (activation-pointers.json exists), skipping bootstrap.");
-    }
-    else {
-        bootstrapped = true;
+    steps.push(activationPlan.inspectionStep);
+    // 4. Bootstrap only for safe empty first-state roots; otherwise keep the inspected healthy state.
+    if (activationPlan.action === "bootstrap") {
         const packRoot = path.resolve(parsed.activationRoot, "packs", "initial");
         mkdirSync(packRoot, { recursive: true });
         const brainAttachmentPolicy = parsed.shared ? "shared" : "dedicated";
@@ -1570,27 +1763,30 @@ function runSetupCommand(parsed) {
             brainAttachmentPolicy,
             activationRoot: parsed.activationRoot,
             packRoot,
-            packLabel: "setup-cli",
+            packLabel: "install-cli",
             workspace: {
                 workspaceId: parsed.workspaceId,
-                snapshotId: `${parsed.workspaceId}@setup-${new Date().toISOString().slice(0, 10)}`,
+                snapshotId: `${parsed.workspaceId}@install-${new Date().toISOString().slice(0, 10)}`,
                 capturedAt: new Date().toISOString(),
                 rootDir: parsed.openclawHome,
-                revision: "cli-setup-v1"
+                revision: "cli-install-v1"
             },
             interactionEvents: [],
             feedbackEvents: []
         });
-        steps.push(`Bootstrapped brain attach: ${result.status}`);
+        steps.push(`Bootstrapped brain attach: state=${result.currentProfile.brain.state} awaitingFirstExport=${yesNo(result.currentProfile.brainStatus.awaitingFirstExport)}`);
+    }
+    else {
+        steps.push(`Kept inspected activation state: active pack ${activationPlan.activePackId}`);
     }
-    // 4-7. Write extension files
+    // 5-8. Write extension files
     const extensionDir = path.join(parsed.openclawHome, "extensions", "openclawbrain");
     mkdirSync(extensionDir, { recursive: true });
-    // 4. Write index.ts
+    // 5. Write index.ts
     const indexTsPath = path.join(extensionDir, "index.ts");
     writeFileSync(indexTsPath, buildExtensionIndexTs(parsed.activationRoot), "utf8");
     steps.push(`Wrote extension: ${indexTsPath}`);
-    // 4b. Write runtime-guard files (imported by index.ts as ./runtime-guard.js)
+    // 5b. Write runtime-guard files (imported by index.ts as ./runtime-guard.js)
     const runtimeGuardPaths = resolveExtensionRuntimeGuardPath();
     if (runtimeGuardPaths.ts !== null) {
         const runtimeGuardTsPath = path.join(extensionDir, "runtime-guard.ts");
@@ -1600,17 +1796,31 @@ function runSetupCommand(parsed) {
     const runtimeGuardJsPath = path.join(extensionDir, "runtime-guard.js");
     writeFileSync(runtimeGuardJsPath, readFileSync(runtimeGuardPaths.js, "utf8"), "utf8");
     steps.push(`Wrote extension runtime-guard: ${runtimeGuardJsPath}`);
-    // 5. Write package.json
+    // 6. Write package.json
     const packageJsonPath = path.join(extensionDir, "package.json");
     writeFileSync(packageJsonPath, buildExtensionPackageJson(), "utf8");
     steps.push(`Wrote package.json: ${packageJsonPath}`);
-    // 6. npm install
+    // 7. npm install
+    const releaseTarballInstall = resolveExtensionInstallReleaseTarballs();
     try {
-        execSync("npm install --ignore-scripts", { cwd: extensionDir, stdio: "pipe" });
-        steps.push("Ran npm install --ignore-scripts");
+        if (releaseTarballInstall !== null) {
+            execFileSync(resolveNpmCommand(), ["install", "--ignore-scripts", "--no-save", ...releaseTarballInstall.tarballs], { cwd: extensionDir, stdio: "pipe" });
+            steps.push(`Installed extension dependencies from release artifacts: ${releaseTarballInstall.tarballs.length} tarballs from ${releaseTarballInstall.artifactDir}`);
+        }
+        else {
+            execSync("npm install --ignore-scripts", { cwd: extensionDir, stdio: "pipe" });
+            steps.push("Ran npm install --ignore-scripts");
+            const linkedPackages = installExtensionFromLocalWorkspaceBuild(extensionDir);
+            if (linkedPackages !== null) {
+                steps.push(`Linked coherent local workspace packages: ${linkedPackages.join(", ")}`);
+            }
+        }
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        if (releaseTarballInstall !== null) {
+            throw new Error(`Extension dependency install from release artifacts failed: ${message}`);
+        }
         const linkedPackages = installExtensionFromLocalWorkspaceBuild(extensionDir);
         if (linkedPackages !== null) {
             steps.push(`Linked coherent local workspace packages: ${linkedPackages.join(", ")}`);
@@ -1619,19 +1829,19 @@ function runSetupCommand(parsed) {
             steps.push(`npm install failed (non-fatal): ${message}`);
         }
     }
-    // 7. Write plugin manifest
+    // 8. Write plugin manifest
     const manifestPath = path.join(extensionDir, "openclaw.plugin.json");
     writeFileSync(manifestPath, buildExtensionPluginManifest(), "utf8");
     steps.push(`Wrote manifest: ${manifestPath}`);
-    // 8. Write BRAIN.md to workspace directories
+    // 9. Write BRAIN.md to workspace directories
     const brainMdContent = [
         "## OpenClawBrain",
         `You have a learning brain attached at ${parsed.activationRoot}.`,
         "- It learns automatically from your conversations",
         '- Corrections matter — "no, actually X" teaches the brain X',
         "- You don't manage it — background daemon handles learning",
-        "- Check: `openclawbrain status`",
-        "- Rollback: `openclawbrain rollback`",
+        `- Check: \`openclawbrain status --activation-root ${quoteShellArg(parsed.activationRoot)}\``,
+        `- Rollback: \`openclawbrain rollback --activation-root ${quoteShellArg(parsed.activationRoot)}\``,
         '- See what brain knows: `openclawbrain context "your question"`',
         ""
     ].join("\n");
@@ -1705,16 +1915,24 @@ function runSetupCommand(parsed) {
         `Check status: ${buildInstallStatusCommand(parsed.activationRoot)}`
     ];
     const lifecycleSummary = [
-        `OpenClaw profile: ${shortenPath(parsed.openclawHome)} (${formatSetupOpenClawHomeSource(parsed.openclawHomeSource)})`,
-        `Activation root: ${shortenPath(parsed.activationRoot)} (${formatSetupActivationRootSource(parsed.activationRootSource)})`,
-        `Workspace ID: ${parsed.workspaceId} (${formatSetupWorkspaceIdSource(parsed.workspaceIdSource)})`,
+        `OpenClaw profile: ${shortenPath(parsed.openclawHome)} (${formatInstallOpenClawHomeSource(parsed.openclawHomeSource)})`,
+        `Activation root: ${shortenPath(parsed.activationRoot)} (${formatInstallActivationRootSource(parsed.activationRootSource)})`,
+        `Workspace ID: ${parsed.workspaceId} (${formatInstallWorkspaceIdSource(parsed.workspaceIdSource)})`,
         `Profile hook: installed at ${shortenPath(extensionDir)}`,
-        activationRootCreated
+        activationPlan.resolution === "new_root"
             ? `Activation data: initialized at ${shortenPath(parsed.activationRoot)}`
-            : `Activation data: reused at ${shortenPath(parsed.activationRoot)}`,
-        bootstrapped
-            ? "Brain attach: bootstrapped a seed/current-profile attach"
-            : "Brain attach: existing activation state kept in place"
+            : activationPlan.resolution === "missing_pointers"
+                ? `Activation data: repaired missing pointers at ${shortenPath(parsed.activationRoot)}`
+                : activationPlan.resolution === "empty_pointers"
+                    ? `Activation data: repaired empty pointers at ${shortenPath(parsed.activationRoot)}`
+                    : `Activation data: reused healthy state at ${shortenPath(parsed.activationRoot)}`,
+        activationPlan.action === "bootstrap"
+            ? activationPlan.resolution === "new_root"
+                ? "Brain attach: bootstrapped a seed/current-profile attach"
+                : activationPlan.resolution === "missing_pointers"
+                    ? "Brain attach: repaired missing activation pointers and bootstrapped a seed/current-profile attach"
+                    : "Brain attach: repaired empty activation pointers and bootstrapped a seed/current-profile attach"
+            : `Brain attach: kept healthy active pack ${activationPlan.activePackId} in place`
     ];
     // 9. Print summary
     if (parsed.json) {
@@ -2341,16 +2559,9 @@ function formatTimestamp() {
 function watchLog(message) {
     console.log(`${formatTimestamp()} ${message}`);
 }
-function resolveOperatorTeacherSnapshotPath(activationRoot, explicitPath) {
-    if (explicitPath !== null && explicitPath !== undefined) {
-        return explicitPath;
-    }
-    const asyncSnapshotPath = resolveAsyncTeacherLiveLoopSnapshotPath(activationRoot);
-    return existsSync(asyncSnapshotPath) ? asyncSnapshotPath : null;
+function formatWatchError(error) {
+    return error instanceof Error ? error.message : String(error);
 }
-const WATCH_STATE_DIRNAME = "watch";
-const WATCH_SESSION_TAIL_CURSOR_BASENAME = "session-tail-cursor.json";
-const WATCH_TEACHER_SNAPSHOT_BASENAME = "teacher-snapshot.json";
 function sanitizeWatchPathSegment(value) {
     const sanitized = value
         .replace(/[^a-zA-Z0-9._-]+/g, "-")
@@ -2358,15 +2569,6 @@ function sanitizeWatchPathSegment(value) {
         .slice(0, 96);
     return sanitized.length > 0 ? sanitized : "session";
 }
-function resolveWatchStateRoot(activationRoot) {
-    return path.resolve(activationRoot, WATCH_STATE_DIRNAME);
-}
-function resolveWatchSessionTailCursorPath(activationRoot) {
-    return path.join(resolveWatchStateRoot(activationRoot), WATCH_SESSION_TAIL_CURSOR_BASENAME);
-}
-function resolveWatchTeacherSnapshotPath(activationRoot) {
-    return path.join(resolveWatchStateRoot(activationRoot), WATCH_TEACHER_SNAPSHOT_BASENAME);
-}
 function readOptionalJsonFile(filePath) {
     if (!existsSync(filePath)) {
         return null;
@@ -2400,28 +2602,8 @@ function persistWatchSessionTailCursor(cursorPath, cursor) {
         cursor
     });
 }
-function loadWatchTeacherSnapshotState(snapshotPath) {
-    const parsed = readOptionalJsonFile(snapshotPath);
-    return {
-        lastHandledMaterializationPackId: parsed !== null && typeof parsed.lastHandledMaterializationPackId === "string"
-            ? parsed.lastHandledMaterializationPackId
-            : null
-    };
-}
-function persistWatchTeacherSnapshot(snapshotPath, input) {
-    writeJsonFile(snapshotPath, {
-        contract: "openclaw_watch_teacher_snapshot.v1",
-        runtimeOwner: "openclaw",
-        updatedAt: new Date().toISOString(),
-        scanRoot: input.scanRoot,
-        replayedBundleCount: input.replayedBundleCount,
-        replayedEventCount: input.replayedEventCount,
-        exportedBundleCount: input.exportedBundleCount,
-        exportedEventCount: input.exportedEventCount,
-        localSessionTailNoopReason: input.localSessionTailNoopReason,
-        lastHandledMaterializationPackId: input.lastHandledMaterializationPackId,
-        snapshot: input.snapshot
-    });
+function countWatchCursorBridgedEvents(cursor) {
+    return cursor.reduce((sum, entry) => sum + entry.bridgedEventCount, 0);
 }
 function listWatchRuntimeEventExportBundleRoots(scanRoot) {
     if (!existsSync(scanRoot)) {
@@ -2528,7 +2710,8 @@ function applyWatchMaterialization(activationRoot, snapshot, lastHandledMaterial
         return {
             lastHandledMaterializationPackId,
             logLine: null,
-            materializedPackId: null
+            materializedPackId: null,
+            failure: null
         };
     }
     const packId = typeof materialization?.candidate?.summary?.packId === "string"
@@ -2538,14 +2721,28 @@ function applyWatchMaterialization(activationRoot, snapshot, lastHandledMaterial
         return {
             lastHandledMaterializationPackId,
             logLine: null,
-            materializedPackId: packId
+            materializedPackId: packId,
+            failure: null
         };
     }
     const shortPackId = packId.length > 16 ? packId.slice(0, 16) : packId;
     try {
         const candidateRootDir = path.resolve(activationRoot, "packs", packId);
         mkdirSync(candidateRootDir, { recursive: true });
-        materializeAlwaysOnLearningCandidatePack(candidateRootDir, materialization);
+        let activeBeforePack = null;
+        try {
+            activeBeforePack = loadPackFromActivation(activationRoot, "active", { requireActivationReady: true });
+        }
+        catch {
+            activeBeforePack = null;
+        }
+        const candidateDescriptor = materializeAlwaysOnLearningCandidatePack(candidateRootDir, materialization);
+        appendLearningUpdateLogs({
+            activationRoot,
+            materialization,
+            activeBeforePack,
+            candidateDescriptor
+        });
         const now = new Date().toISOString();
         stageCandidatePack(activationRoot, candidateRootDir, {
             updatedAt: now,
@@ -2560,13 +2757,15 @@ function applyWatchMaterialization(activationRoot, snapshot, lastHandledMaterial
             return {
                 lastHandledMaterializationPackId: packId,
                 materializedPackId: packId,
-                logLine: `Promoted ${shortPackId} → active`
+                logLine: `Promoted ${shortPackId} → active`,
+                failure: null
             };
         }
         return {
             lastHandledMaterializationPackId: packId,
             materializedPackId: packId,
-            logLine: `Staged ${shortPackId} (promotion blocked: ${inspection.promotion.findings.join(", ")})`
+            logLine: `Staged ${shortPackId} (promotion blocked: ${inspection.promotion.findings.join(", ")})`,
+            failure: null
         };
     }
     catch (error) {
@@ -2574,26 +2773,77 @@ function applyWatchMaterialization(activationRoot, snapshot, lastHandledMaterial
         return {
             lastHandledMaterializationPackId,
             materializedPackId: packId,
-            logLine: `Promotion failed for ${shortPackId}: ${message}`
+            logLine: `Promotion failed for ${shortPackId}: ${message}`,
+            failure: {
+                mode: "materialization_failed",
+                detail: message,
+                at: new Date().toISOString()
+            }
+        };
+    }
+}
+function resolveWatchTeacherLabelerConfig(input) {
+    if (input !== undefined) {
+        return {
+            teacherLabeler: input,
+            warnings: []
         };
     }
+    const providerConfig = readOpenClawBrainProviderConfig(process.env);
+    const warnings = providerConfig.warnings.filter((warning) => /OPENCLAWBRAIN_TEACHER_/u.test(warning));
+    if (providerConfig.teacher.provider !== "ollama") {
+        return {
+            teacherLabeler: null,
+            warnings
+        };
+    }
+    return {
+        teacherLabeler: {
+            provider: "ollama",
+            baseUrl: providerConfig.teacherBaseUrl,
+            model: providerConfig.teacher.model,
+            ...(providerConfig.teacher.timeoutMs === undefined ? {} : { timeoutMs: providerConfig.teacher.timeoutMs }),
+            ...(providerConfig.teacher.maxPromptChars === undefined ? {} : { maxPromptChars: providerConfig.teacher.maxPromptChars }),
+            ...(providerConfig.teacher.maxResponseChars === undefined ? {} : { maxResponseChars: providerConfig.teacher.maxResponseChars }),
+            ...(providerConfig.teacher.maxOutputTokens === undefined ? {} : { maxOutputTokens: providerConfig.teacher.maxOutputTokens }),
+            ...(providerConfig.teacher.maxArtifactsPerExport === undefined
+                ? {}
+                : { maxArtifactsPerExport: providerConfig.teacher.maxArtifactsPerExport }),
+            ...(providerConfig.teacher.maxInteractionsPerExport === undefined
+                ? {}
+                : { maxInteractionsPerExport: providerConfig.teacher.maxInteractionsPerExport })
+        },
+        warnings
+    };
 }
 export async function createWatchCommandRuntime(input) {
     const activationRoot = path.resolve(input.activationRoot);
+    const bootstrapObservedAt = new Date().toISOString();
     const scanRoot = input.scanRoot !== undefined && input.scanRoot !== null
         ? path.resolve(input.scanRoot)
         : path.resolve(activationRoot, "event-exports");
     const sessionTailCursorPath = resolveWatchSessionTailCursorPath(activationRoot);
     const teacherSnapshotPath = resolveWatchTeacherSnapshotPath(activationRoot);
+    const restoredTeacherState = loadWatchTeacherSnapshotState(teacherSnapshotPath);
     const log = input.log ?? watchLog;
+    const startupWarnings = [];
     mkdirSync(scanRoot, { recursive: true });
     mkdirSync(resolveWatchStateRoot(activationRoot), { recursive: true });
     log(`Watch starting — activation: ${shortenPath(activationRoot)}`);
     log(`Scan root: ${shortenPath(scanRoot)}`);
     log(`State: cursor=${shortenPath(sessionTailCursorPath)} snapshot=${shortenPath(teacherSnapshotPath)}`);
+    const resolvedTeacherLabeler = resolveWatchTeacherLabelerConfig(input.teacherLabeler);
+    const teacherLabeler = resolvedTeacherLabeler.teacherLabeler;
+    for (const warning of resolvedTeacherLabeler.warnings) {
+        startupWarnings.push(`teacher_env_warning:${warning}`);
+        log(`Teacher env warning: ${warning}`);
+    }
+    if (teacherLabeler?.provider === "ollama") {
+        log(`Teacher labeler: provider=ollama model=${teacherLabeler.model ?? "qwen3.5:9b"}`);
+    }
     const scanner = createRuntimeEventExportScanner({ scanRoot });
     let lastServeTimeFallbackReason = null;
-    const teacherLoop = createAsyncTeacherLiveLoop({
+    const baseTeacherLoopInput = {
         packLabel: "watch-cli",
         workspace: {
             workspaceId: "watch-cli",
@@ -2603,6 +2853,7 @@ export async function createWatchCommandRuntime(input) {
             revision: "watch-cli-v2"
         },
         learnedRouting: true,
+        ...(teacherLabeler !== null ? { teacherLabeler } : {}),
         resolveLearnedRoutingState: () => {
             const resolved = resolveServeTimeLearningRuntimeInput(activationRoot);
             if (resolved.fallbackReason !== null && resolved.fallbackReason !== lastServeTimeFallbackReason) {
@@ -2620,11 +2871,38 @@ export async function createWatchCommandRuntime(input) {
                 persistBaseline(activationRoot, state);
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                log(`Baseline persist failed: ${message}`);
+                log(`Baseline persist failed: ${formatWatchError(error)}`);
             }
         }
-    });
+    };
+    let teacherLoop;
+    let lastHandledMaterializationPackId = restoredTeacherState.lastHandledMaterializationPackId;
+    if (restoredTeacherState.error !== null) {
+        const message = restoredTeacherState.error;
+        startupWarnings.push(`teacher_snapshot_reset:${message}`);
+        lastHandledMaterializationPackId = null;
+        log(`Teacher snapshot reset: ${message}`);
+        teacherLoop = createAsyncTeacherLiveLoop(baseTeacherLoopInput);
+    }
+    else {
+        try {
+            teacherLoop = createAsyncTeacherLiveLoop({
+                ...baseTeacherLoopInput,
+                ...(restoredTeacherState.snapshot !== null ? { resumeFromSnapshot: restoredTeacherState.snapshot } : {})
+            });
+        }
+        catch (error) {
+            const message = formatWatchError(error);
+            startupWarnings.push(`teacher_snapshot_reset:${message}`);
+            lastHandledMaterializationPackId = null;
+            log(`Teacher snapshot reset: ${message}`);
+            teacherLoop = createAsyncTeacherLiveLoop(baseTeacherLoopInput);
+        }
+    }
+    if (restoredTeacherState.snapshot !== null && startupWarnings.length === 0) {
+        const restoredSeenExportCount = restoredTeacherState.snapshot.state?.seenExportDigests.length ?? 0;
+        log(`Restored teacher snapshot: seen=${restoredSeenExportCount} artifacts=${restoredTeacherState.snapshot.teacher.artifactCount}`);
+    }
     let restoredCursor = loadWatchSessionTailCursor(sessionTailCursorPath);
     let localSessionTail;
     try {
@@ -2644,8 +2922,18 @@ export async function createWatchCommandRuntime(input) {
         });
         persistWatchSessionTailCursor(sessionTailCursorPath, []);
     }
-    let lastHandledMaterializationPackId = loadWatchTeacherSnapshotState(teacherSnapshotPath).lastHandledMaterializationPackId;
-    const replayState = await replayWatchScanRootIntoTeacherLoop(teacherLoop, scanRoot);
+    let replayState = {
+        replayedBundleCount: 0,
+        replayedEventCount: 0
+    };
+    try {
+        replayState = await replayWatchScanRootIntoTeacherLoop(teacherLoop, scanRoot);
+    }
+    catch (error) {
+        const message = formatWatchError(error);
+        startupWarnings.push(`teacher_replay_failed:${message}`);
+        log(`Async teacher replay fail-open: ${message}`);
+    }
     if (replayState.replayedBundleCount > 0) {
         log(`Replayed ${replayState.replayedBundleCount} stored export bundle${replayState.replayedBundleCount === 1 ? "" : "s"} (${replayState.replayedEventCount} event${replayState.replayedEventCount === 1 ? "" : "s"})`);
     }
@@ -2656,14 +2944,25 @@ export async function createWatchCommandRuntime(input) {
         log(replayPromotion.logLine);
         bootstrapSnapshot = teacherLoop.snapshot();
     }
+    const bootstrapCursor = localSessionTail.snapshot();
     persistWatchTeacherSnapshot(teacherSnapshotPath, {
+        lastRunAt: bootstrapObservedAt,
         scanRoot,
+        sessionTailCursorPath,
+        sessionTailCursorUpdatedAt: bootstrapObservedAt,
+        sessionTailSessionsTracked: bootstrapCursor.length,
+        sessionTailBridgedEventCount: countWatchCursorBridgedEvents(bootstrapCursor),
+        scannerCheckpointPath: scanner.checkpointPath,
+        scannerCheckpoint: scanner.snapshot(),
         replayedBundleCount: replayState.replayedBundleCount,
         replayedEventCount: replayState.replayedEventCount,
         exportedBundleCount: 0,
         exportedEventCount: 0,
+        startupWarnings,
+        lastTeacherError: null,
         localSessionTailNoopReason: null,
         lastHandledMaterializationPackId,
+        failure: replayPromotion.failure,
         snapshot: bootstrapSnapshot
     });
     return {
@@ -2671,6 +2970,8 @@ export async function createWatchCommandRuntime(input) {
         scanRoot,
         sessionTailCursorPath,
         teacherSnapshotPath,
+        startupWarnings,
+        lastTeacherError: null,
         replayState,
         lastHandledMaterializationPackId,
         scanner,
@@ -2684,6 +2985,7 @@ export async function runWatchCommandPass(runtime, options = {}) {
     const localPoll = runtime.localSessionTail.pollOnce({
         observedAt
     });
+    const scannerCheckpointBeforeScan = runtime.scanner.snapshot();
     const exported = exportLocalSessionTailChangesToScanRoot({
         scanRoot: runtime.scanRoot,
         polledAt: localPoll.polledAt,
@@ -2703,31 +3005,71 @@ export async function runWatchCommandPass(runtime, options = {}) {
     const totalEvents = scanResult.selected.reduce((sum, hit) => sum + hit.eventRange.count, 0);
     let snapshot = runtime.teacherLoop.snapshot();
     let materializedPackId = null;
+    let failure = null;
     if (totalSelected === 0) {
         log("Scanning... no changes");
     }
     else {
         log(`Scanning... ${totalSelected} export bundle${totalSelected === 1 ? "" : "s"} selected, ${totalEvents} event${totalEvents === 1 ? "" : "s"}`);
-        const ingestResult = await runtime.teacherLoop.ingestRuntimeEventExportScannerScan(scanResult);
-        snapshot = ingestResult.snapshot;
-        const promotion = applyWatchMaterialization(runtime.activationRoot, snapshot, runtime.lastHandledMaterializationPackId);
-        runtime.lastHandledMaterializationPackId = promotion.lastHandledMaterializationPackId;
-        materializedPackId = promotion.materializedPackId;
-        if (promotion.logLine !== null) {
-            log(promotion.logLine);
+        try {
+            const ingestResult = await runtime.teacherLoop.ingestRuntimeEventExportScannerScan(scanResult);
+            runtime.lastTeacherError = null;
+            snapshot = ingestResult.snapshot;
+            const promotion = applyWatchMaterialization(runtime.activationRoot, snapshot, runtime.lastHandledMaterializationPackId);
+            runtime.lastHandledMaterializationPackId = promotion.lastHandledMaterializationPackId;
+            materializedPackId = promotion.materializedPackId;
+            failure = promotion.failure;
+            if (promotion.logLine !== null) {
+                log(promotion.logLine);
+                snapshot = runtime.teacherLoop.snapshot();
+            }
+        }
+        catch (error) {
+            const message = formatWatchError(error);
+            runtime.lastTeacherError = message;
+            failure = {
+                mode: "teacher_fail_open",
+                detail: message,
+                at: observedAt
+            };
+            log(`Async teacher fail-open: ${message}`);
+            try {
+                runtime.scanner.restoreCheckpoint(scannerCheckpointBeforeScan);
+            }
+            catch (restoreError) {
+                const restoreMessage = formatWatchError(restoreError);
+                runtime.lastTeacherError = `${message}; scanner checkpoint restore failed: ${restoreMessage}`;
+                failure = {
+                    mode: "teacher_fail_open",
+                    detail: runtime.lastTeacherError,
+                    at: observedAt
+                };
+                log(`Scanner checkpoint restore failed: ${restoreMessage}`);
+            }
             snapshot = runtime.teacherLoop.snapshot();
         }
     }
     persistWatchTeacherSnapshot(runtime.teacherSnapshotPath, {
+        lastRunAt: observedAt,
         scanRoot: runtime.scanRoot,
+        sessionTailCursorPath: runtime.sessionTailCursorPath,
+        sessionTailCursorUpdatedAt: observedAt,
+        sessionTailSessionsTracked: localPoll.cursor.length,
+        sessionTailBridgedEventCount: countWatchCursorBridgedEvents(localPoll.cursor),
+        scannerCheckpointPath: runtime.scanner.checkpointPath,
+        scannerCheckpoint: runtime.scanner.snapshot(),
         replayedBundleCount: runtime.replayState.replayedBundleCount,
         replayedEventCount: runtime.replayState.replayedEventCount,
         exportedBundleCount: exported.exportedBundleCount,
         exportedEventCount: exported.exportedEventCount,
+        startupWarnings: runtime.startupWarnings,
+        lastTeacherError: runtime.lastTeacherError,
         localSessionTailNoopReason: localPoll.noopReason,
         lastHandledMaterializationPackId: runtime.lastHandledMaterializationPackId,
+        failure,
         snapshot
     });
+    const persistedScannerCheckpoint = runtime.scanner.snapshot();
     if (options.json) {
         console.log(JSON.stringify({
             timestamp: observedAt,
@@ -2739,6 +3081,10 @@ export async function runWatchCommandPass(runtime, options = {}) {
             events: totalEvents,
             live: scanResult.live.length,
             backfill: scanResult.backfill.length,
+            sessionTailSessionsTracked: localPoll.cursor.length,
+            sessionTailBridgedEvents: countWatchCursorBridgedEvents(localPoll.cursor),
+            scannerProcessedBundles: persistedScannerCheckpoint.processedExportDigests.length,
+            scannerLiveAfter: persistedScannerCheckpoint.live.after?.exportDigest ?? null,
             materialized: materializedPackId,
             diagnostics: snapshot.diagnostics ?? null,
             localSessionTailNoopReason: localPoll.noopReason
@@ -2842,12 +3188,13 @@ function resetActivationRoot(activationRoot) {
 function runResetCommand(parsed) {
     if (parsed.help) {
         console.log([
-            "Usage: openclawbrain reset [--activation-root <path>] [--yes] [--json]",
+            "Usage: openclawbrain reset [--activation-root <path>|--openclaw-home <path>] [--yes] [--json]",
             "",
             "Wipes all learned state and returns the brain to seed state.",
             "",
             "Options:",
             "  --activation-root <path>  Activation root (auto-detected if omitted)",
+            "  --openclaw-home <path>   Pin auto-detection to one installed OpenClaw profile",
             "  --yes, -y                 Skip confirmation prompt",
             "  --json                    Emit machine-readable JSON output",
             "  --help                    Show this help"
@@ -2898,7 +3245,7 @@ function runResetCommand(parsed) {
         }
         console.log("  Activation pointers reset to seed state.");
         console.log(`\nBrain at ${shortenPath(activationRoot)} is now in seed state.`);
-        console.log("Run `openclawbrain status` to verify.");
+        console.log(`Run \`openclawbrain status --activation-root ${quoteShellArg(activationRoot)}\` to verify.`);
     }
     return 0;
 }
@@ -2973,8 +3320,8 @@ export function runOperatorCli(argv = process.argv.slice(2)) {
         });
         return 0;
     }
-    if (parsed.command === "install" || parsed.command === "setup") {
-        return runSetupCommand(parsed);
+    if (parsed.command === "install") {
+        return runInstallCommand(parsed);
     }
     if (parsed.command === "detach") {
         return runDetachCommand(parsed);
@@ -3044,7 +3391,7 @@ export function runOperatorCli(argv = process.argv.slice(2)) {
     }
     // At this point only status/rollback commands remain
     const statusOrRollback = parsed;
-    const activationRoot = requireActivationRoot(statusOrRollback.input, statusOrRollback.command);
+    const activationRoot = requireActivationRoot(statusOrRollback.input, statusOrRollback.openclawHome, statusOrRollback.command);
     if (statusOrRollback.command === "rollback") {
         const result = rollbackRuntimeAttach({
             activationRoot,