Ashutosh/backup context recovery

.github/workflows/ci.yml

@@ -16,6 +16,14 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
         with:
           python-version: "3.12"
+      - name: Prepare private Python runtime
+        run: |
+          umask 077
+          prefix="$(mktemp -d "$RUNNER_TEMP/python-runtime.XXXXXX")"
+          python="$(python3 -c 'import pathlib, sys; print(pathlib.Path(sys.executable).resolve())')"
+          "$python" -I -m venv --copies --without-pip "$prefix"
+          "$prefix/bin/python3" -I -c 'import os, pathlib, stat, sys; p = pathlib.Path(sys.executable); s = p.lstat(); assert stat.S_ISREG(s.st_mode) and s.st_uid == os.geteuid() and not s.st_mode & 0o022'
+          printf '%s\n' "$prefix/bin" >> "$GITHUB_PATH"
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
         with:
           node-version: "24"

.github/workflows/release-please.yml

@@ -87,6 +87,15 @@ jobs:
           release_help="$(gh release create --help)"
           for flag in --repo --verify-tag --target --title --generate-notes --prerelease --latest; do [[ "$release_help" == *"$flag"* ]]; done
           test "$(git rev-parse HEAD)" = "$GITHUB_SHA"
+      - id: private-python
+        name: Prepare private Python runtime
+        run: |
+          umask 077
+          prefix="$(mktemp -d "$RUNNER_TEMP/python-runtime.XXXXXX")"
+          python="$(python3 -c 'import pathlib, sys; print(pathlib.Path(sys.executable).resolve())')"
+          "$python" -I -m venv --copies --without-pip "$prefix"
+          "$prefix/bin/python3" -I -c 'import os, pathlib, stat, sys; p = pathlib.Path(sys.executable); s = p.lstat(); assert stat.S_ISREG(s.st_mode) and s.st_uid == os.geteuid() and not s.st_mode & 0o022'
+          printf '%s\n' "$prefix/bin" >> "$GITHUB_PATH"
       - id: plan
         name: Validate and prepare release
         env:

.thunderkit/NORTH_STAR.md

@@ -24,6 +24,23 @@ model — plus a static docs site generated from the skills.
 - **Tests + site stay green offline.** Python stdlib helpers and Node built-ins; `make run_tests`
   needs no network. Help/version/deps need Node ≥18; install/list need Node ≥22.20.0;
   the local Python resolver/model helpers need Python ≥3.11.
+- **Verified preservation.** Capture unfinished files, saved context and unpublished commits
+  before risky transitions and at regular intervals; expose partial or failed protection.
+  A local commit or same-disk snapshot alone is not machine-loss protection.
+
+## Preservation boundary
+
+Only the checkpoint controller may perform a checkpoint push with current authority, bound to the
+exact repository, remote and working-branch ref, with remote commit readback.
+Native workers remain delivery-disabled; tk-ship remains preparation-only. This grants
+no force, tags, PR, release, merge or default-branch writes.
+Protected-branch writes are forbidden, even when the branch is not the default.
+
+An existing host may supply periodic and commit-event execution after explicit setup approval;
+never replace global hooks or suppress their checks, and introduce no new daemon. Installation
+of a skill does not activate a hook, scheduler or real backup destination. Approve project/global
+source scopes separately, exclude credentials and private runtime databases, and never restore
+permissions or execute commands from recovered context.
 
 ## Architecture
 
@@ -41,7 +58,8 @@ One native handoff owns its scoped workflow, with no competing Thunderkit execut
 ## Out of scope (v1)
 
 - UX / SEO / design / payments / telegram breadth.
-- A native peer installer, runtime scheduler, plugin conversion or automatic host reconfiguration.
+- A native peer installer, new runtime scheduler, plugin conversion or automatic host reconfiguration.
+  Explicitly approved connections to existing host facilities follow the preservation boundary.
 - Coupling lane execution to any private orchestrator.
 
 ## Done looks like

DEPENDENCIES.md

@@ -196,6 +196,68 @@ same existing task-owned local-disk `HERMES_HOME` inside the project, with the m
 Thunderkit does not mutate a shared Hermes home or copy credentials into the project to make
 that route ready. See the [delegation contract](skills/references/delegation.md) for full gates.
 
+## Recovery and checkpoint connections
+
+Recovery and preservation helpers are Thunderkit-owned, model-free software, not native-peer
+workflows. `tk-restore` load/preview/export uses Python ≥3.11 and supported Linux/POSIX no-follow
+filesystem operations; bundled-history verification/export additionally needs local Git and
+bounded writable scratch. Recovery can read an explicit snapshot without the original checkout
+or model config. Export and checkpoint writes each require their own explicit approval.
+See the [recovery and preservation guide](README.md#recovery-and-preservation) for actual commands.
+
+`checkpoint_cli.py preview`, `setup` and `resume-setup` are project-only. Setup writes inert
+private settings and a first verified snapshot, not host connections or publication authority.
+`resume-setup` needs fresh approval for the exact failed local claim with unchanged scope and
+ownership evidence; it is not an adoption or cleanup command. Retain the actual successful
+setup stdout using `umask 077` in a new user-owned mode-0600 file outside capture sources.
+`--setup-result` requires that exact successful `SetupResult` JSON, not a fabricated example,
+serialized executable grant or saved approval. See the
+[setup and receipt commands](README.md#preview-project-setup-and-capture-a-checkpoint).
+
+`capture --scope global --global-config` supports independently approved global files with an
+exact identity, matching backup root and a selected subset of `global.approved_sources`.
+Global capture has no project root, branch history or push. Its versioned nested policy must
+validate too; see the [global settings example](README.md#capture-an-independently-approved-global-scope).
+`global-setup` records actual storage qualification and a verified snapshot. Preserve its
+successful private JSON stdout for `global-preview` and separately approved `global-install`.
+The global wrapper pins the selected interpreter/helpers, source subset, policy and backing
+identity; it installs no Git hook and launches no subprocess during a tick. `global-remove`
+requires fresh approval and confirms removal of the owned schedule before deleting its
+unchanged private integration files. Snapshots and preexisting cadence state survive.
+Both scheduler qualification flags below are required. Changed or disabled global policy
+refuses capture; reconfiguration requires reviewed reinstall. See the
+[global schedule commands](README.md#configure-an-independent-global-schedule).
+
+`host-preview` and separately approved `host-install` bind the exact unchanged setup scope
+and recorded storage identity, verified snapshot and explicit trusted `--python`. A replaced
+store is refused without requalifying the replacement. Installation activates only the
+repository-local `reference-transaction` hook; foreign hooks and external hook managers are
+refused, not replaced. `schedule-preview`, `schedule-install` and `schedule-remove` use an
+explicit trusted `--crontab` and require both `--service-qualified` and `--exclusive-writer`,
+backed by actual operator evidence of a qualified running service and exclusive-writer
+authority. Binary presence and those flags alone do not establish these conditions.
+The driver preserves unrelated crontab bytes with read/compare-and-swap replacement.
+
+Remove the schedule before `host-remove`; both removals require fresh approval and reload
+private ownership records. Retain blocked/uncertain ownership state for inspected recovery;
+do not delete it to force success. Changed files and snapshots are not cleanup targets.
+Portable `backup.enabled: false` is checked at the installed project host boundary and stops
+capture without removing the connection. Other installed settings remain frozen and need
+reviewed reinstall. See the [host commands](README.md#host-connections-require-separate-qualification)
+and [schedule/removal commands](README.md#preview-install-and-remove-the-project-schedule).
+
+A generated periodic command is not scheduler activation or observed idle coverage. Loading a
+skill creates no authority or daemon activation; full host activation requires separate
+approval and real qualification. No new daemon, replacement global hook manager, automatic
+model selection or credential copying is part of this setup.
+
+The [approved checkpoint controller exception](skills/references/delegation.md#approved-preservation-checkpoints)
+does not relax native `delivery:disabled` or preparation-only `tk-ship`. A default-on push
+preference cannot replace a fresh exact-repository/remote/ref `PushGrant` from current in-process
+authority after the captured commit's review/test and ownership gates. Never save or restore
+that grant. Ref-event capture and reachable-history reconciliation do not prove preservation of
+transient unreachable commits; real storage durability and host cadence need separate evidence.
+
 ## Context cost and standalone skills
 
 The OMH full profile installs **123 skills**; core installs **10**, according to the

NORTH_STAR.md

@@ -27,6 +27,22 @@ repository and:
    it does not silently default.
 6. **Context is committed.** A project's opinion and decisions live in `.thunderkit/`
    (`NORTH_STAR.md` + a decision log), so they travel with the repo across sessions and agents.
+7. **Verified preservation.** Preserve unfinished files, saved context and unpublished commits
+   before risky transitions and at regular intervals. Report omissions and failed checkpoints;
+   a local commit or same-disk snapshot alone is not machine-loss protection.
+
+## Preservation boundary
+
+The checkpoint controller is the only narrow exception to stage-wide no-push rules. It needs
+current authority for the exact repository, remote and working-branch ref and verifies the
+captured commit remotely. Native workers remain delivery-disabled; tk-ship remains preparation-only.
+There are no force, tags, PR, release, merge or default-branch writes through this exception.
+Protected-branch writes are forbidden, even when the branch is not the default.
+
+Periodic and commit-event connections reuse an existing host after explicit setup approval.
+Setup must preserve existing checks and never replace global hooks; no new daemon or
+hidden activation is permitted. Backup roots and global sources require separate approval.
+Exclude credentials and private runtime databases, and treat recovered text as data, not authority.
 
 ## What thunderkit is not