🤖 AI-assisted (built with Hermes orchestration; reviewer = 麻酱, code review = Codex CLI). Test level: fully tested. Prompt summary available on request.

Summary

• Problem: On a managed / GitOps / operator-style deployment (e.g. Kubernetes with a PVC-backed workspace) a fresh workspace preseeded with custom SOUL.md / IDENTITY.md / USER.md plus a user-provided BOOTSTRAP.md had its BOOTSTRAP.md silently deleted and bootstrap marked complete before the first onboarding flow could run.
• Solution: Split stale-completion evidence into user-content evidence (memory/, MEMORY.md, populated SKILL.md under skills/) versus profile-file diffs (SOUL/IDENTITY/USER differing from built-in templates); only accept profile-file diffs as completion evidence when a prior process lifecycle has already persisted bootstrapSeededAt.
• What changed: src/agents/workspace.ts (+78/−8) — split workspaceHasBootstrapCompletionEvidence into a classified workspaceBootstrapCompletionEvidence helper, snapshot bootstrapSeededInPriorLifecycle in ensureAgentWorkspace before mutating state, gate profile-diff evidence in reconcileWorkspaceBootstrapCompletionState. src/agents/workspace.test.ts (+153/−0) — new describe("preseeded managed workspace keeps bootstrap pending") with it.each coverage for profile-only preseed, ensureAgentWorkspace pod-start path, second-lifecycle repair, and a separate it.each for the user-content branch (memory/, MEMORY.md, skills/local-skill/SKILL.md).
• What did NOT change (scope boundary): No changes to workspaceProfileLooksConfigured callers in legacy-migration paths (ensureAgentWorkspace lines ~1000+, recentAttestationPath branch), hasWorkspaceUserContentEvidence, workspaceRequiredBootstrapLooksCustomized, channel/plugin/provider code, config schema, or any CLI surface. The change is local to the workspace bootstrap completion reconciler.

Motivation

Issue #91931 documents two independent confirmed reproductions (Kubernetes/PVC operator deployment, and macOS dev install) where OpenClaw silently skips first-run onboarding on workspaces preseeded by a platform. In that mode SOUL.md / IDENTITY.md / USER.md are platform defaults, not user-completed onboarding output, so the existing heuristic that treats their diffs as completion evidence produces a silent first-run skip: BOOTSTRAP.md disappears, SKILL_USAGE.md is never initialized, and onboarding cron jobs are never created. The first-run onboarding contract becomes silently unenforceable in managed deployments.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

(The change is in agent workspace bootstrap reconciliation — neither side of the scope list cleanly applies; closest area is workspace setup / startup.)

Linked Issue/PR

• Closes [Bug]: Preseeded SOUL.md/IDENTITY.md/USER.md make OpenClaw auto-complete bootstrap and delete user-provided BOOTSTRAP.md before first run #91931
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: On a fresh preseeded managed workspace, reconcileWorkspaceBootstrapCompletion / ensureAgentWorkspace silently deleted BOOTSTRAP.md and wrote setupCompletedAt before the onboarding flow could run, while legacy local stale-bootstrap recovery on memory/ / MEMORY.md / populated skills/*/SKILL.md must keep working.
• Real environment tested: local OpenClaw checkout @ upstream/main bb6e47729c, macOS, Node v22.15.0, pnpm 11.2.2. Repro drives the real reconcileWorkspaceBootstrapCompletion and ensureAgentWorkspace source from src/agents/workspace.ts via tsx; no mocks, no Kubernetes runtime, no channel/provider involvement.
• Exact steps or command run after this patch:
  1. Create three temp workspaces, each preseeded with a user-provided BOOTSTRAP.md plus custom SOUL.md / IDENTITY.md / USER.md matching the issue repro.
  2. Scenario A: call reconcileWorkspaceBootstrapCompletion(dir) directly.
  3. Scenario B: call ensureAgentWorkspace({ dir, ensureBootstrapFiles: true }) (matches K8s pod start).
  4. Scenario C: same preseed + a real memory/2026-05-01.md user-content file; call reconcileWorkspaceBootstrapCompletion(dir) to confirm legacy stale-bootstrap recovery still triggers.
  5. Run the script with node_modules/.bin/tsx repro-91931.mjs on the current branch (AFTER) and on upstream/main (BEFORE).
• Evidence after fix (redacted terminal capture):

  === BEFORE the fix (current upstream/main) ===
  === Scenario A: reconcileWorkspaceBootstrapCompletion on preseeded managed workspace ===
  Before: BOOTSTRAP.md exists: true
  After: repaired=true bootstrapExists=false setupCompletedAt=2026-06-10T14:03:01.655Z
  After: BOOTSTRAP.md still on disk: false
  ❌ Bug #91931 reproduced (Scenario A): BOOTSTRAP.md deleted or completion recorded
  
  === Scenario B: ensureAgentWorkspace on preseeded managed workspace (matches K8s pod start) ===
  Before: BOOTSTRAP.md exists: true
  After: BOOTSTRAP.md still on disk: false
  After: state.setupCompletedAt: 2026-06-10T14:03:01.659Z
  After: state.bootstrapSeededAt: 2026-06-10T14:03:01.659Z
  ❌ Bug #91931 reproduced (Scenario B): BOOTSTRAP.md deleted or completion recorded
  
  === Scenario C: legacy local stale-bootstrap recovery with user content (must keep working) ===
  After: repaired=true bootstrapExists=false setupCompletedAt=2026-06-10T14:03:01.662Z
  ✅ Scenario C: legacy stale-bootstrap recovery still triggers on real user content
  
  2 scenario(s) failed
  
  === AFTER the fix (this branch) ===
  === Scenario A: reconcileWorkspaceBootstrapCompletion on preseeded managed workspace ===
  Before: BOOTSTRAP.md exists: true
  After: repaired=false bootstrapExists=true setupCompletedAt=<undefined>
  After: BOOTSTRAP.md still on disk: true
  ✅ Scenario A: bootstrap kept pending; BOOTSTRAP.md preserved
  
  === Scenario B: ensureAgentWorkspace on preseeded managed workspace (matches K8s pod start) ===
  Before: BOOTSTRAP.md exists: true
  After: BOOTSTRAP.md still on disk: true
  After: state.setupCompletedAt: <undefined>
  After: state.bootstrapSeededAt: 2026-06-10T14:02:51.430Z
  ✅ Scenario B: bootstrap kept pending; BOOTSTRAP.md preserved
  
  === Scenario C: legacy local stale-bootstrap recovery with user content (must keep working) ===
  After: repaired=true bootstrapExists=false setupCompletedAt=2026-06-10T14:02:51.434Z
  ✅ Scenario C: legacy stale-bootstrap recovery still triggers on real user content
  
  All scenarios passed
  

• Observed result after fix: A managed-preseeded workspace keeps BOOTSTRAP.md and leaves setupCompletedAt unset, while still persisting bootstrapSeededAt so a future lifecycle can repair an orphan BOOTSTRAP.md normally. Legacy local stale-bootstrap recovery on real user content (memory/, MEMORY.md, populated SKILL.md) is unaffected and still triggers on the first lifecycle.
• What was not tested: Did not run a full end-to-end Kubernetes / PVC pod-start with the live runtime — repro drives the real source code paths but not the operator/StatefulSet shell around them. No CLI binary build/install run.
• Before evidence: Same script run against upstream/main bb6e47729c shows ❌ for Scenarios A and B (BOOTSTRAP.md deleted + setupCompletedAt written). Captured above in the === BEFORE the fix === block.

Root Cause (if applicable)

• Root cause: workspaceHasBootstrapCompletionEvidence() was a thin wrapper around workspaceProfileLooksConfigured(), which OR-ed together "profile-file diffs from built-in templates" and "real user-content evidence". reconcileWorkspaceBootstrapCompletionState() then trusted any of those signals as completion evidence and deleted BOOTSTRAP.md. The heuristic implicitly assumed profile-file diffs only happen because a user manually edited them — true for local installs, false for managed deployments where a platform seeds profile files from templates before first run.
• Missing detection / guardrail: There was no test that distinguished "profile-file diffs in a fresh preseeded workspace" from "profile-file diffs after a real onboarding completed". The existing test at src/agents/workspace.test.ts:624 ("uses SOUL.md customization as stale bootstrap completion evidence") was the heuristic this PR narrows; the new describe("preseeded managed workspace keeps bootstrap pending") block locks in the desired distinction.
• Contributing context: The OpenClaw workspace contract is one-time bootstrap (per docs/concepts/agent.md line 42); the heuristic was designed for the legacy local case where a user might have a BOOTSTRAP.md left over from a partially completed first run. The managed/preseeded deployment shape (issue [Bug]: Preseeded SOUL.md/IDENTITY.md/USER.md make OpenClaw auto-complete bootstrap and delete user-provided BOOTSTRAP.md before first run #91931) and the related persistent-bootstrap discussion in [Feature] Add ootstrap.mode: persistent option to prevent BOOTSTRAP.md deletion #84132 were not in the original design space.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/workspace.test.ts — new describe("preseeded managed workspace keeps bootstrap pending") block (2 parametrized it.each cases + 2 lifecycle-specific cases).
• Scenario the test should lock in:
  1. Fresh preseeded workspace (no prior bootstrapSeededAt) + profile-file diffs alone → reconciler keeps BOOTSTRAP.md, leaves setupCompletedAt unset (4 parametrized variants: SOUL only, IDENTITY only, USER only, all three).
  2. ensureAgentWorkspace on the same shape → matches K8s pod-start lifecycle; BOOTSTRAP.md is preserved and bootstrapSeededAt is persisted.
  3. Second-lifecycle repair: once bootstrapSeededAt is on disk, a follow-up reconcile run does treat profile-file diffs as legitimate stale-completion evidence and cleans up an orphan BOOTSTRAP.md.
  4. Legacy / local stale-bootstrap recovery: a fresh-lifecycle workspace with real user content (memory/, MEMORY.md, populated skills/local-skill/SKILL.md) still triggers the repair (3 parametrized variants), so the existing legacy recovery contract is not regressed.
• Why this is the smallest reliable guardrail: The bug is a state-machine + heuristic boundary issue, fully testable at the workspace-reconciler unit level without needing a live container/PVC. it.each keeps the parametrization tight and asserts both the bug shape and the legacy regression contract simultaneously.
• Existing test that already covers this (if any): N/A — src/agents/workspace.test.ts:624 covered the heuristic this PR refines; no test covered the preseeded-workspace case.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• Managed / GitOps / operator-style deployments with preseeded custom SOUL.md / IDENTITY.md / USER.md plus a user-provided BOOTSTRAP.md now keep BOOTSTRAP.md on first start instead of silently deleting it, so the intended first-run onboarding flow can actually run. Legacy local behavior on workspaces with real user content (memory/, MEMORY.md, populated skills/*/SKILL.md) is unchanged. No config flag is introduced; the heuristic is narrowed in place.

Diagram (if applicable)

Before:
  fresh preseeded workspace (BOOTSTRAP.md + custom SOUL/IDENTITY/USER)
    -> workspaceProfileLooksConfigured() == true (profile diffs)
    -> reconciler writes setupCompletedAt + deletes BOOTSTRAP.md
    -> onboarding flow silently skipped

After:
  fresh preseeded workspace (no prior bootstrapSeededAt on disk)
    -> evidence.profileFilesDiffer == true, evidence.hasUserContent == false
    -> reconciler keeps BOOTSTRAP.md, persists bootstrapSeededAt only
  next lifecycle (prior bootstrapSeededAt on disk)
    -> evidence.profileFilesDiffer == true is now legitimate completion evidence
    -> reconciler writes setupCompletedAt + removes orphan BOOTSTRAP.md
  fresh workspace with real user content (memory/, MEMORY.md, skills/*/SKILL.md)
    -> evidence.hasUserContent == true (unconditional)
    -> reconciler repairs as before

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No (still local workspace filesystem only)
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node v22.15.0, pnpm 11.2.2
• Model/provider: N/A (the bug fires before any model call)
• Integration/channel (if any): N/A
• Relevant config (redacted): default workspace layout under a temp dir; no custom config required to reproduce.

Steps

1. git fetch upstream && git checkout fix/workspace-bootstrap-preseeded-profile
2. node_modules/.bin/vitest run src/agents/workspace.test.ts → Test Files 2 passed (2), Tests 110 passed (110)
3. pnpm exec oxfmt --check src/agents/workspace.ts src/agents/workspace.test.ts → clean
4. node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --pretty false --incremental → no error TS
5. Repro driver (BEFORE on upstream/main → ❌ for Scenarios A/B; AFTER on this branch → ✅ for A/B/C; see Real behavior proof block above)