Vault Sync Status

vault-sync-status

One-shot detailed health report of vault-sync on the current host. Reports scheduler state, role-specific log/filter/script checks, snapshot guard presence, runtime-manifest / live-verify proof, and Linux fuse-refresh timer status.

When to use

• Quick health check after install
• Debugging sync issues
• CI read-only verification of production hosts (sg01)
• Before and after migration
• Proving installed runtime hashes match package sources after rollout

Steps

1. Resolve vault path once (cwd-independent): VS_VAULT_PATH → WIKI_PATH → skillwiki --human path (absolute only) → $HOME/wiki. All git checks use git -C "$VAULT_PATH".
2. Run vault_sync_ doctor checks* directly (equivalent to skillwiki doctor --only vault_sync but available without skillwiki).
   • Reports vault_sync_conflict_markers so poisoned Markdown is visible before push, pull, or snapshot workflows continue.
3. Read scheduler state:
   • macOS leaf/full hosts: validate the deployed wiki-push and wiki-fetch plist syntax, expected Label, and ProgramArguments[0]; live mode then also checks their launchd registration. A loaded stale label cannot make invalid on-disk configuration pass.
   • Linux leaf/full hosts: wiki-push and wiki-fetch timers.
   • snapshotter hosts: wiki-snapshot.
4. Check terminal helper state for the installed wiki-sync.sh and the convenience ~/bin/wiki-sync.sh symlink. Warn only; do not repair in status mode.
5. Role-specific checks:
   • leaf/full hosts: tail last 20 lines of wiki-push.log and wiki-fetch.log; check wiki-push-filters.txt; read wiki-push-result.state (durable terminal state, H9) as vault_sync_last_push_result — the authoritative last push outcome (OK / refused+reason), since log rotation and P1 cooldown suppression can hide refusals from the log tail.
   • snapshotter hosts: skip leaf push/fetch/filter checks as not applicable; verify the configured vault_sync.snapshot_script or packaged wiki-snapshot.sh contains --max-delete.
6. Runtime proof checks (read-only; never write markers):
   • vault_sync_runtime_manifest — $(platform_share_dir)/runtime-manifest.json present and parseable.
   • vault_sync_runtime_match — SHA-256 of installed scripts match package sources, and recorded macOS LaunchAgent hashes match the actual deployed plist files.
   • vault_sync_runtime_registration — warn when scheduler jobs are enabled but runtime match is not pass.
   • vault_sync_live_verify — pass only when $(platform_share_dir)/live-verify.ok exists; otherwise warn. Status never creates this marker.
7. Resolve S3 reachability without guessing a host-local alias:
   • non-empty process WIKI_REMOTE;
   • otherwise WIKI_REMOTE from ~/.skillwiki/.env;
   • otherwise, for snapshotters, WIKI_REMOTE or CLOUD_REMOTE parsed as data from the snapshot profile path resolved as: VS_SNAPSHOT_PROFILE → vault_sync.snapshot_profile in ~/.skillwiki/.env → /etc/vault-sync/profiles/$(hostname)-snapshotter.env;
   • otherwise report S3 remote not configured — reachability probe skipped. A missing remote is unknown/unconfigured, not unreachable. Only a failed probe of a resolved remote produces an S3 warning. Snapshot profiles are parsed by exact assignment and are never sourced as shell code. Reachability probes (git ls-remote, rclone lsf, optional snapshotter SSH) are hard-bounded via with_timeout: GNU timeout → gtimeout → python3 → bash job+kill. Default bound is 3s; override with VS_REACHABILITY_TIMEOUT=<seconds>. Probes must not hang indefinitely when coreutils timeout is missing.
8. Output:
   • Default: human-readable two-column table.
   • --json: machine-readable record matching the doctor JSON shape.
9. --read-only flag: explicitly forbid any state-changing call. Used by sg01 e2e leg. The skill MUST honor this — no touch, no launchctl print (which on some platforms can spawn helpers), no service restart.
10. --fail-on <lvl> flag: exit nonzero when the summary has error (--fail-on error) or warning+error (--fail-on warn). Default is report-only (exit 0). Used by CI to gate on health without parsing JSON.

Package root for drift checks

Run status from the same package tree used to install (monorepo packages/vault-sync or Claude/Codex plugin root containing skills/vault-sync-status). Do not use random worktrees under ~/.config/superpowers/worktrees/ — they produce false script_drift.

# monorepo
VS_READ_ONLY=1 bash packages/vault-sync/skills/vault-sync-status/status.sh
# plugin root
VS_READ_ONLY=1 bash skills/vault-sync-status/status.sh

Time-bound snapshotter alternative

When wall-clock budget is tight on a snapshotter (FUSE + S3 probes), prefer:

1. systemctl is-active wiki-snapshot.timer wiki-fuse-refresh.timer
2. Tail $(platform_log_dir)/wiki-snapshot.log / wiki-fuse-refresh.log
3. Read $(platform_share_dir)/runtime-manifest.json package_version / package_commit
4. Prefer skillwiki doctor for managed-write prerequisites: pull-helper resolution (vault_sync_pull_helper) and review-required journal backlog (vault_sync_review_required_journals); use skillwiki sync journal list for detail.
5. A resolved handoff (target_oid already in HEAD, no sequencer/unmerged paths) is auto-superseded by managed preflight even with unrelated dirty WIP; a paired dead-owner managed-write lock is recovery-preserved and reclaimed in that same invocation. Treat live owners, active Git operations, unmerged paths, and non-ancestor targets as intentional fail-closed blockers.

Then run full status when time allows.

S3 configuration contract

Rclone remote names such as cloud: or seaweed-wiki: are host-local aliases. Managed leaf hosts should set WIKI_REMOTE explicitly in ~/.skillwiki/.env. Snapshotter services carry their operational source in the systemd profile as CLOUD_REMOTE; status can consume that profile when WIKI_REMOTE is absent. Do not interpret a shared legacy script default as proof that the alias exists on the current host.

Runtime proof and live verification

After install, operators should see:

Exact live-verify path:

• macOS: ~/Library/Application Support/vault-sync/live-verify.ok
• Linux: ~/.local/share/vault-sync/live-verify.ok

Completion gate: repository tests green ≠ work complete. Do not set the vault work item status: completed until live evidence (runtime match + pull log op= lines + live-verify.ok) is recorded in the work retro. See vault-sync-install attended verification checklist.

Read-only contract

When --read-only is passed:

• No files are written (including never writing live-verify.ok).
• No services are restarted.
• No launchctl or systemctl commands that modify state.
• Only read operations: plist validation, file existence checks, log tailing, config reads, hash comparison.

This is the safety lifeline for sg01. Test ruthlessly.

Execution

# Companion script (interactive)
bash packages/vault-sync/skills/vault-sync-status/status.sh
bash packages/vault-sync/skills/vault-sync-status/status.sh --json
bash packages/vault-sync/skills/vault-sync-status/status.sh --read-only   # sg01 safe mode

# Companion script (headless / CI)
VS_READ_ONLY=1 VS_JSON=1 bash packages/vault-sync/skills/vault-sync-status/status.sh
VS_READ_ONLY=1 VS_REACHABILITY_TIMEOUT=3 bash packages/vault-sync/skills/vault-sync-status/status.sh