Skip to content

Add core snapshot CLI#94717

Closed
giodl73-repo wants to merge 1 commit into
giodl/snapshot-provider-prooffrom
giodl/snapshot-cli-pr2
Closed

Add core snapshot CLI#94717
giodl73-repo wants to merge 1 commit into
giodl/snapshot-provider-prooffrom
giodl/snapshot-cli-pr2

Conversation

@giodl73-repo

@giodl73-repo giodl73-repo commented Jun 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Adds a core openclaw snapshot CLI surface, not a plugin/extension command.
  • Wires snapshot create, snapshot list, snapshot verify, and snapshot restore to the local SQLite snapshot provider from PR 1.
  • Makes the safe-sync-file workflow user-accessible: create a verified SQLite artifact + manifest that a file-syncing host can persist instead of syncing the live SQLite working set.
  • Registers snapshot in the core command descriptor catalog, lazy command registry, and command startup policy.
  • Positions the CLI as the proof surface for refactor(sqlite): land database-first memory and proxy alignment #94646's database-first SQLite layout: today it accepts explicit DB paths, and later PRs can map friendly names to global/control-plane and per-agent/data-plane DBs.
  • Covers command registration plus create/list/verify/restore command behavior against a real SQLite database.

Stack

Scope

This PR keeps snapshot explicit and opt-in, but core-owned. It does not make every OpenClaw SQLite database automatically durable, does not add object storage, does not add scheduling, and does not change the runtime database choice.

The point is narrower: give operators and Scout/Lobster-style hosts a command surface that can produce and verify the completed artifact set. Hosts should sync that artifact set, not live *.sqlite, *.sqlite-wal, *.sqlite-shm, or *.sqlite-journal churn. WAL bundles remain a metrics-gated Phase 2 after the full snapshot command is proven.

Verification

  • node scripts/run-vitest.mjs run src/commands/snapshot.test.ts src/snapshot/snapshot-provider.test.ts src/cli/program/register.snapshot.test.ts - passed, 3 files / 13 tests
  • node scripts/run-vitest.mjs run src/cli/program/register.backup.test.ts src/cli/program/subcli-descriptors.test.ts - passed, 2 files / 8 tests
  • node_modules\.bin\oxlint src\commands\snapshot.ts src\commands\snapshot.test.ts src\snapshot src\cli\program\register.snapshot.ts src\cli\program\register.snapshot.test.ts src\cli\program\core-command-descriptors.ts src\cli\program\command-registry-core.ts src\cli\command-catalog.ts - passed
  • git diff --check - passed

Real behavior proof

Behavior or issue addressed:
Core openclaw snapshot command handlers can create, list, verify, and restore SQLite-safe snapshot artifacts. This is the CLI proof layer for the safe sync artifact boundary and the database-first SQLite target model from #94646.

Real environment tested:
Windows source checkout at C:\src\openclaw-snapshot-pr1, Node/Vitest source harness, core Commander registration tests, and snapshot command functions backed by a real node:sqlite database.

Exact steps or command run after this patch:

  1. node scripts/run-vitest.mjs run src/commands/snapshot.test.ts src/snapshot/snapshot-provider.test.ts src/cli/program/register.snapshot.test.ts
  2. node scripts/run-vitest.mjs run src/cli/program/register.backup.test.ts src/cli/program/subcli-descriptors.test.ts
  3. node_modules\.bin\oxlint src\commands\snapshot.ts src\commands\snapshot.test.ts src\snapshot src\cli\program\register.snapshot.ts src\cli\program\register.snapshot.test.ts src\cli\program\core-command-descriptors.ts src\cli\program\command-registry-core.ts src\cli\command-catalog.ts
  4. git diff --check

Evidence after fix:

  • Snapshot command/provider/registration tests passed: 3 files / 13 tests.
  • Backup registration and sub-CLI descriptor regression tests passed: 2 files / 8 tests.
  • Oxlint completed cleanly for the changed core command/provider files.
  • git diff --check completed with no whitespace errors.

Observed result after fix:
The core snapshot command group is registered with create, list, verify, and restore. The command functions create a snapshot from a real SQLite database, list it, verify manifest/hash/integrity, restore it, and read the restored row successfully.

What was not tested:
Full packaged CLI execution was not tested in this PR; the source harness covers command registration and command behavior directly. Cloud/object-store snapshot repositories, friendly target names for global/per-agent DBs, backup integration, file-sync host integration, SQLite-aware WAL bundles, and failover integration remain follow-up work.

@openclaw-barnacle openclaw-barnacle Bot added size: M maintainer Maintainer-authored PR labels Jun 19, 2026
@clawsweeper

clawsweeper Bot commented Jun 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge. Reviewed June 19, 2026, 2:10 AM ET / 06:10 UTC.

Summary
Adds a core openclaw snapshot command group with create/list/verify/restore handlers, command registration, startup policy wiring, and SQLite-backed tests.

PR surface: Source +285, Tests +253. Total +538 across 7 files.

Reproducibility: not applicable. as a bug reproduction; this is a feature PR. The PR body reports source tests against a real SQLite database, but it does not show packaged openclaw snapshot command execution.

Review metrics: 2 noteworthy metrics.

  • Root CLI Surface Added: 1 command group, 4 subcommands added. A new root operator command becomes a public CLI contract once merged.
  • Startup Policy Added: 1 command path added with config-guard bypass. The command can run before normal config validation, so maintainers should confirm that recovery/startup behavior is intentional.

Stored data model
Persistent data-model change detected: database schema: src/commands/snapshot.test.ts, serialized state: src/commands/snapshot.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: canonical
Canonical: #94717
Summary: This PR is the current CLI layer for the snapshot stack; related items are its provider base, follow-up target/docs layers, or broader adjacent storage discussions.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof from a real setup is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P1] Add redacted terminal/live output from real openclaw snapshot create, list, verify, and restore runs.
  • Resolve or land Add core snapshot provider proof #94694 before merging this CLI layer.
  • Get maintainer approval for the root command and flag contract, with docs if accepted.

Proof guidance:

  • [P1] Needs real behavior proof before merge: The PR body provides Vitest/oxlint/source-harness evidence only and explicitly says full packaged CLI execution was not tested; add redacted terminal/live output from real openclaw snapshot commands before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

  • [P1] Merging this would add a new public root openclaw snapshot command with subcommands, flags, and startup policy, so maintainers need to accept that CLI/API shape before it becomes a compatibility contract.
  • [P1] The PR is stacked on Add core snapshot provider proof #94694, which is still open and draft; its provider/storage behavior is not on current main and has its own unresolved review concerns.
  • [P1] Contributor proof is source-harness tests and lint only; there is no redacted terminal/live output from real packaged openclaw snapshot create, list, verify, and restore commands.
  • [P1] Public docs for the snapshot command are not in this PR; Add SQLite snapshot artifacts under backup #94805 is an open follow-up rather than merged documentation.

Maintainer options:

  1. Resolve Base And Prove CLI (recommended)
    Land or otherwise resolve the provider base, retarget this branch to the accepted base, and attach redacted real openclaw snapshot terminal/live output before merge.
  2. Accept The Root Command Contract
    Maintainers can explicitly accept the public command names, flags, startup policy, artifact model, and documentation requirement if they want this durability surface in core.
  3. Pause Until Snapshot Direction Settles
    Keep the draft paused or close it if the RFC/provider shape should not become a bundled core CLI surface yet.

Next step before merge

  • [P1] Protected maintainer label, draft status, missing real CLI proof, open provider base, and a new core CLI/storage contract require maintainer review rather than an automated repair.

Security
Cleared: No concrete security or supply-chain concern was found in this PR diff; it adds local CLI handlers/tests and no dependencies, workflows, lockfiles, secrets, or downloaded code execution paths.

Review details

Best possible solution:

Resolve and accept the provider base first, then merge a documented openclaw snapshot CLI only after maintainers approve the root command contract and the contributor adds real command proof.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction; this is a feature PR. The PR body reports source tests against a real SQLite database, but it does not show packaged openclaw snapshot command execution.

Is this the best way to solve the issue?

Unclear as merge-ready. The CLI wiring is plausible, but the best solution still needs an accepted provider base, maintainer approval of the public command contract, documentation, and real CLI proof.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against afd9cb0c1056.

Label changes

Label changes:

  • add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
  • remove rating: 🦪 silver shellfish: Current PR rating is rating: 🧂 unranked krab, so this older rating label is no longer current.

Label justifications:

  • P2: This is a normal-priority draft feature with bounded operator/storage scope and no urgent live-user outage.
  • merge-risk: 🚨 compatibility: The PR adds a new root CLI command, subcommands, flags, and startup policy that become compatibility surface after merge.
  • merge-risk: 🚨 other: The remaining risk is maintainer acceptance of a new core snapshot durability workflow and its open provider base, which green CI cannot decide.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body provides Vitest/oxlint/source-harness evidence only and explicitly says full packaged CLI execution was not tested; add redacted terminal/live output from real openclaw snapshot commands before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed

PR surface:

Source +285, Tests +253. Total +538 across 7 files.

View PR surface stats
Area Files Added Removed Net
Source 5 285 0 +285
Tests 2 253 0 +253
Docs 0 0 0 0
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 7 538 0 +538

What I checked:

  • Root policy read and applied: Root AGENTS.md was read fully; its protected-label, real-behavior-proof, public CLI/API, storage, and docs-for-behavior review guidance applies to this PR. (AGENTS.md:28, afd9cb0c1056)
  • No scoped AGENTS.md for touched paths: The touched src/cli and src/commands paths have no narrower scoped AGENTS.md; root policy is the applicable repository guide. (afd9cb0c1056)
  • PR head adds snapshot command registration: The PR head registers a new snapshot root command with create, verify, restore, and list subcommands. (src/cli/program/register.snapshot.ts:17, a341086a2681)
  • PR head adds startup policy: The PR adds snapshot to the startup command catalog with config-guard bypass and network-proxy bypass. (src/cli/command-catalog.ts:263, a341086a2681)
  • Current main does not already implement this CLI: Current main has no src/commands/snapshot, src/snapshot, register.snapshot, or docs/cli/snapshot.md paths, so the PR is not obsolete on main. (afd9cb0c1056)
  • Latest release does not contain this CLI: The latest release tag v2026.6.8 also has no snapshot CLI/provider/doc paths, so this is still unshipped work. (844f405ac1be)

Likely related people:

  • steipete: GitHub path history for the core command registry, descriptor catalog, and command catalog shows repeated recent root-CLI work by this contributor. (role: recent CLI descriptor contributor; confidence: high; commits: f7e54acec1ba, 6fb1f386c6d6, 41905d9fd701; files: src/cli/program/command-registry-core.ts, src/cli/program/core-command-descriptors.ts, src/cli/command-catalog.ts)
  • vincentkoc: Recent path history and the merged database-first alignment stack point to this contributor for backup SQLite snapshots, memory-host storage, and SQLite state layout work that the snapshot CLI builds on. (role: recent SQLite/storage contributor; confidence: high; commits: b6cb3d2901d2, 386b0e6c7457, 88bc08c124a5; files: src/infra/backup-create.ts, packages/memory-host-sdk/src/engine-storage.ts, packages/memory-host-sdk/src/host/sqlite-vec.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 other 🚨 Merging this PR has meaningful risk outside the owned taxonomy. labels Jun 19, 2026
@giodl73-repo
giodl73-repo force-pushed the giodl/snapshot-provider-proof branch from 592e0c5 to 3d1a406 Compare June 19, 2026 02:10
@giodl73-repo
giodl73-repo force-pushed the giodl/snapshot-cli-pr2 branch from 4fdd1ef to d8c5d9a Compare June 19, 2026 02:13
@giodl73-repo

giodl73-repo commented Jun 19, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

Restacked on the rebased #94694 head and updated the PR body to frame openclaw snapshot as the opt-in CLI surface for the database-first SQLite targets from #94646. Latest head: d8c5d9a5a6.

@giodl73-repo giodl73-repo mentioned this pull request Jun 19, 2026
Closed
@clawsweeper

clawsweeper Bot commented Jun 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. and removed proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jun 19, 2026
@giodl73-repo
giodl73-repo force-pushed the giodl/snapshot-cli-pr2 branch from d8c5d9a to a341086 Compare June 19, 2026 03:54
@openclaw-barnacle openclaw-barnacle Bot added cli CLI command changes commands Command implementations size: L and removed size: M labels Jun 19, 2026
@giodl73-repo giodl73-repo changed the title Add snapshot plugin CLI Add core snapshot CLI Jun 19, 2026
This was referenced Jun 19, 2026
Closed
Closed
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels Jun 19, 2026
@giodl73-repo giodl73-repo mentioned this pull request Jun 19, 2026
Closed
@giodl73-repo

giodl73-repo commented Jun 19, 2026

Copy link
Copy Markdown
Contributor Author

Closing this stack slice in favor of the consolidated core snapshot PR: #94805.

We collapsed the previous PR1-4 chain into one reviewable feature PR so reviewers can evaluate the provider, CLI, named targets, and safe-sync artifact proof together. The stress harness remains a separate follow-up in #94967.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

cli CLI command changes commands Command implementations maintainer Maintainer-authored PR merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 other 🚨 Merging this PR has meaningful risk outside the owned taxonomy. P2 Normal backlog priority with limited blast radius. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. size: L status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@giodl73-repo