Add a safe 'sync with an existing jarvOS installation' flow

[levineam]

Goal linkage

Make a fresh jarvOS install able to connect safely to an existing cross-machine secondbrain without writing to the vault or creating divergent canonical state.

Product/release triage

• Product fit: public jarvOS release candidate.
• Version posture: enter the current versionless forming batch; do not assign a public version from memory. Release PR chore(main): release jarvos-bootstrap 0.10.0 #241 is a possible integration point, subject to its release manager and CI.
• Local dogfood path: MacBook checkout at /Users/andrewleveiss/Documents/ChatGPT/jarvOS/public-source against the existing private workspace configuration.
• Rollback: remove the generated local config or revert the feature commit; the sync command never writes to the vault.
• Graduation gate: clean independent review, full test suite, and green PR CI.

Scope boundary

This issue covers the safe jarvos sync command, portable/legacy config convergence, doctor/resolver compatibility, tests, and user-facing install documentation. It does not activate GBrain, Paperclip, schedules, services, or vault mutation; it does not merge or publish a release.

Definition of Done

• jarvos sync supports explicit existing-workspace details plus dry-run and JSON output.
• Existing compatible configs are idempotent and private superset keys are preserved.
• Conflicting, unreadable, or symlinked config targets fail closed.
• The command never writes to the Obsidian vault.
• Bootstrap, resolver, doctor, schema, README, and secondbrain module docs agree.
• The complete public test suite passes.
• An issue-named branch is pushed and a draft PR is open with review evidence and CI.

Constraints and failure modes

• Preserve the current private MacBook workspace and vault v3; no production-vault writes.
• Do not infer remote GBrain or Paperclip continuity while the Mac Mini is inaccessible.
• Detect accidental overwrite, schema divergence, or loss of private extension keys through focused tests and diff review.

Ordered plan

1. Re-run the complete test suite and inspect the committed diff.
2. Obtain independent Terra review of the pinned commit and named safety surfaces.
3. Rename the local branch to include this GitHub issue number, push it, and open a draft PR.
4. Monitor CI and address only supported findings within scope.
5. Record verification and dogfood follow-ups; leave merge/release publication to a later explicit decision.

Documentation Impact

README and module docs: the first-run story and secondbrain configuration behavior change.

Communication Contract

• Success signal: draft PR URL, green checks, and verification summary in the originating Codex task.
• Failure/missed/stale signal: concise blocker in the originating Codex task and on this issue.
• Channels: GitHub issue/PR plus the originating Codex task; Paperclip is unavailable on this MacBook.
• Urgency: immediate for a blocker; otherwise task closeout.
• Dedupe rule: one notice per new terminal state.
• Owner/action if bad: Overseer keeps the PR draft and requests Andrew only for a material product or release decision.
• Evidence required before marking done: test output, independent review, diff sanity, and PR CI.
• Originating channel/thread completion notice: this MacBook Overseer task.
• Human-input blocker prompt: ask Andrew here with the exact decision and issue link.

Paperclip/source-route exception: the Mac Mini-hosted Paperclip service is unavailable; this GitHub issue is the durable tracker and this originating task is the completion route.

[levineam]

Independent Terra review — publication blockers

Pinned commit f70c507173ecc580b703fc32022b679cdd6b2fc0 is not ready to publish yet.

• P1: --workspace or --config can place jarvos.config.json inside the selected vault, violating the no-vault-writes contract.
• P1: final dangling symlinks and symlinked parent directories can bypass the current target check.
• P2: legacy config support converges in the schema/resolver but not the module doctor.
• P2: invalid timezone strings can sync successfully while resolver/journal behavior diverges.
• Dogfood: an already-configured compatible workspace still requires redundant --name and --timezone arguments instead of recognizing its existing config.

The dependency-provisioned full public suite passes on the pinned commit, but the branch stays local until these findings are fixed, independently re-reviewed, and re-tested.

[levineam]

Draft PR and verification update

Draft PR: #249 at pinned head f5fba7227895339c87ad8cacf72af9e39a4ac7d0.

Definition-of-Done evidence now available:

• complete dependency-provisioned local npm test: pass
• real MacBook jarvos sync --workspace /Users/andrewleveiss/clawd --dry-run --json: already-synced
• existing config SHA-256 unchanged before/after dry run
• initial independent Terra review found five blockers; all were fixed in f5fba72
• fresh independent Terra review of the pinned head: no P1/P2 findings
• GitHub CI: unit, smoke, Markdown, links, metadata, secret scan, review trigger, and summary all pass
• diff/worktree clean; branch pushed only to the draft PR
• Documentation impact: README and secondbrain module docs updated

The issue remains open because the PR is intentionally draft and unmerged. No production vault, journal, note, Paperclip, GBrain, scheduler, or release state was changed.

Workflow retrospective: dogfooding before publication materially improved the contract. The key reusable requirement is now tested: a command claiming “no vault writes” must reject config destinations inside the vault and all symlinked path components, not merely avoid direct note/journal writes.

[levineam]

Independent review found a P2 compatibility bug in PR #249: portable-config recognition requires derived optional paths.tags, so a schema-valid existing-install config can be sent to manual-reconcile rather than already-synced. Keep the PR draft until derived-path recognition and a regression are fixed. Tracked in #260.

[levineam]

Fix pushed to draft PR #249 at 142ac5d0610f67824ddd20bd82a7c1b2972584e3. Optional resolver-derived paths may now be omitted when they resolve to the same effective value, while present relative/unsafe paths remain rejected. Config-resolution 47/47, CLI smoke, and Doctor 72/72 pass. No config or Vault mutation occurred. Independent exact-head rereview is running before ready/merge.

[levineam]

Independent Luna/max rereview of 142ac5d: HOLD. P1: sync now accepts omitted resolver-derived paths but module/profile Doctor still treats those raw keys as required, so the same existing install can be already-synced and immediately unhealthy. P2: sync classification ignores divergent JARVOS_*_DIR runtime overrides, allowing persisted-config assessment and effective runtime paths to disagree. Align Doctor with resolved paths and make classification account for effective overrides; add regressions. No P0 findings, no writes observed.

[levineam]

Rereview of 17abb8d: prior P1/P2 resolved, but one P2 remains. A fresh missing config target returns create before effective JARVOS_*_DIR override reconciliation; sync can write a config, then the identical environment immediately reports manual-reconcile and Doctor fails. Fresh-create must reject/flag divergent effective overrides (or encode them explicitly) before publication. Existing-config shape now correctly reports already-synced with unchanged bytes; no P0/P1 findings.

[levineam]

Final rereview of 5e6e55e: fresh-create no-mutation guard works, but one P2 false divergence remains. Effective override comparison uses raw string equality, so semantically identical paths such as /path/Tags/ versus /path/Tags are rejected even though runtime/Doctor normalize them. Normalize equivalent spellings while preserving symlink/containment safety; add regression. No P0/P1 or mutation observed.

[levineam]

Rereview of 9197296: fresh-create normalization is correct, but one P2 remains in the existing-target path. hasPortableRuntimeConfig() still compares effective paths with raw string equality, so a trailing-slash-equivalent override is sent to manual reconciliation. Share the normalized comparison across both paths; divergent overrides must still fail. No P0/P1 or mutation regression.

[levineam]

Rereview of b93ae61: HOLD (P2). Shared lexical path.resolve() can collapse .. across a symlink and treat physically divergent runtime paths as equal, hiding drift and potentially routing later writes outside the configured Vault. Make equivalent-path comparison symlink-aware or reject symlink-bearing traversal before normalization; add regression. All focused tests and private dry-run remain read-only/unchanged; no P0/P1.

[levineam]

Final Luna/max rereview of exact head e6cf68a: no P0-P2 findings; recommendation MERGE. .. traversal now fails closed before normalization, while trailing-slash and . spellings remain equivalent. Config 50/50, Doctor 89/89, CLI smoke, private dry-run immutability, diff check, and full isolated suite pass.