# SessionHarbor combined agent context > Generated from authoritative repository files by scripts/generate-agent-docs.mjs. Do not edit this file directly. Canonical repository: https://github.com/WangPeterXF/session-harbor Generated content version: repository main --- # Source: README.md # SessionHarbor [![CI](https://github.com/WangPeterXF/session-harbor/actions/workflows/ci.yml/badge.svg)](https://github.com/WangPeterXF/session-harbor/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/WangPeterXF/session-harbor?include_prereleases)](https://github.com/WangPeterXF/session-harbor/releases) [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-43853d)](package.json) [![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm%20Noncommercial-2563eb)](LICENSE) [![No telemetry](https://img.shields.io/badge/telemetry-none-0f766e)](PRIVACY.md) ![SessionHarbor connects multiple Codex devices to one verified data hub](docs/assets/sessionharbor-github-social-preview-v0.3.0.jpg) **Back up, verify, reclaim, restore, and review Codex session context across macOS and Windows.** SessionHarbor is an unofficial, local-first Codex plugin and zero-dependency Node.js CLI by Xiaofan Wang. It turns an external drive or mounted NAS into a verified filesystem vault for every stable local Codex rollout. | Outcome | What SessionHarbor does | | --- | --- | | Back up every Codex session | Incremental, content-addressed backup with SHA-256 read-back and immutable device-owned snapshots. | | Free local disk space safely | Keeps backup and cleanup separate; old originals become eligible only after inactivity, backup-age, open-file, and fresh verification gates. | | Restore deleted local conversations | Materializes the verified raw rollout without consuming the vault copy. | | Bridge multiple Codex computers | Lets macOS and Windows devices inspect verified peer inventories and stage reviewed, evidence-linked context. | ## Install with one Codex prompt Open a new Codex task and paste the complete pinned prompt for [English](docs/bootstrap-prompt.en.md) or [简体中文](docs/bootstrap-prompt.zh-CN.md). A compact version is: ```text Set up SessionHarbor from https://github.com/WangPeterXF/session-harbor using the pinned v0.3.1 bootstrap prompt. Verify the owner, tag, license, and plugin before installing. Make this task my SessionHarbor management center, start with the read-only dashboard, and do not mutate any real session or drive without a separate explicit approval. ``` The setup verifies `WangPeterXF/session-harbor` and the pinned release before installing the repo-local marketplace plugin. Installation, destination initialization, backup publication, local cleanup, restore, and scheduling remain separate decisions. ## For agents and AI tools - [`AGENTS.md`](AGENTS.md): repository-wide safety invariants, source map, validation, and review rules. - [`docs/agent-index.md`](docs/agent-index.md): compact task router for installation, operation, and development. - [`llms.txt`](https://wangpeterxf.github.io/session-harbor/llms.txt): small web index pointing to authoritative Markdown sources. - [`llms-full.txt`](https://wangpeterxf.github.io/session-harbor/llms-full.txt): generated combined context, checked for drift in CI. - [`evals/plugin-discovery.json`](evals/plugin-discovery.json): five positive and three negative prompts for discovery precision and recall. Project page: SessionHarbor is source-available for noncommercial use under the [PolyForm Noncommercial License 1.0.0](LICENSE). Commercial use requires a separate written license; see [commercial licensing](COMMERCIAL-LICENSE.md). Because the license restricts commercial use, SessionHarbor is not Open Source Initiative (OSI) open-source software. ## Status Version `0.3.1` implements full incremental backup, verified local cleanup, restore, cross-device continuity, a conversational management dashboard, and multi-mode scheduling. Automated validation uses synthetic Codex homes, temporary vaults, simulated interruptions, and Mac/Windows path fixtures. Each installation must still pass the physical-drive checklist before local cleanup is enabled. SessionHarbor never edits Codex SQLite, `session_index.jsonl`, generated memories, authentication, or project files. It does not promise exact sidebar reconstruction. Raw JSONL remains the restore and evidence source. The initial cross-platform validation record, Windows defects found during physical-drive testing, and remaining preview limitations are summarized in the [v0.3.1 release notes](docs/release-notes-v0.3.1.md). ## Management task behavior The repository includes copy-ready bootstrap prompts for [Chinese](docs/bootstrap-prompt.zh-CN.md) and [English](docs/bootstrap-prompt.en.md), pinned to the official `WangPeterXF/session-harbor` `v0.3.1` release. The prompt asks Codex to verify the pinned repository and license, add the repository marketplace, install the plugin, read the verified skill for the current chat, and turn that task into the user's long-lived SessionHarbor management center. Official Codex behavior makes newly installed plugin skills available to new chats. The bootstrap prompt does not pretend the plugin hot-loaded: it explicitly reads the verified skill in the setup chat so that chat can continue immediately, while later chats use the normal installed plugin. The management task starts read-only: ```sh session-harbor dashboard --json --limit 50 session-harbor dashboard --state unbacked session-harbor dashboard --state deleted session-harbor dashboard --state waiting-backup-age ``` It reports cataloged/current/pending backups, local deletions, restorable sessions, retention waits, latest publication, and applied-backup progress. See the [management-center workflow](docs/management-center.md). ## Backup and cleanup are independent The settings the project exposes are deliberately separate: ```json { "backup": { "scope": "all", "allowPartial": true, "verifyExistingObjects": false }, "retention": { "cleanupAfterInactiveDays": 30, "minimumBackupAgeDays": 7, "reclaimAction": "keep", "autoReclaim": false } } ``` - `backup.scope`: always `all`; backup age and file size never filter disaster-recovery coverage. - `backup.allowPartial`: a changing/open session is reported and retried on the next trigger while other stable sessions can still be backed up. - `backup.verifyExistingObjects`: `false` makes insertion/weekly runs compare stable source metadata and stored object sizes, then hash only new or changed content. Set it to `true` for a deliberately slower full scrub; `verify` and restore always perform cryptographic verification. - `cleanupAfterInactiveDays`: only local sessions inactive for this many days enter cleanup review. - `minimumBackupAgeDays`: keep the local original for this additional safety period after its latest verified backup revision. - `reclaimAction`: - `keep` keeps the local original indefinitely; - `link` replaces it with a reversible link to a stable mounted vault; - `delete` removes only the verified local original and remains restorable from the vault. - `autoReclaim`: lets an explicitly installed schedule include a separate reclaim scope. It is off by default. `backup` never deletes or links a local file. `cleanup`/`reclaim` is a different command. Delete mode requires both `--apply` and `--confirm-delete-local`; `autoReclaim` defaults to false. Legacy config v1-v3 age/grace keys migrate into config v4. Existing reclaim actions are preserved; new configs default to `keep`. ## Safety model Publication follows this order: 1. Verify the destination identity marker and stable device identity. 2. Read a stable local source and compute SHA-256. 3. Copy to a same-directory temporary file, sync it, hash the stored bytes, and publish atomically. 4. Publish an immutable snapshot manifest. 5. Replace the device-owned head pointer last. Cleanup is allowed only when the destination copy still matches the current local source, the inactivity and backup-age gates have elapsed, and the source is not open. A missing/mismatched volume, changed source, target conflict, corrupt object, symlinked path component, peer rollback, or unknown contract fails closed. Restore keeps the archive copy. Fast scheduled backup does not replace periodic integrity verification. Run `session-harbor verify` manually after unsafe removal, filesystem errors, or before enabling cleanup; cleanup itself always re-hashes both local source and vault target before changing the local file. ## Requirements - Node.js 20 or newer - A stable filesystem destination such as an exFAT external drive or mounted NAS - macOS or Windows for the intended two-computer workflow - Optional: [`codex-slim`](https://github.com/milisp/codex-slim) for lossless zstd compression Use `exchange.storageClass: "stable-mounted"` for an external drive/NAS. iCloud, Baidu Netdisk, or another client-managed synchronized folder must use `"client-synced"` together with reclaim action `keep`; SessionHarbor rejects link/delete reclamation for that class. ## Dry-run setup Every command below is read-only until its applied form is explicitly used: ```sh node plugins/session-harbor/scripts/session-harbor.mjs \ init --destination /path/to/EXTERNAL_DRIVE/SessionHarbor node plugins/session-harbor/scripts/session-harbor.mjs doctor --json node plugins/session-harbor/scripts/session-harbor.mjs device init --json node plugins/session-harbor/scripts/session-harbor.mjs bridge doctor --json node plugins/session-harbor/scripts/session-harbor.mjs backup plan --json node plugins/session-harbor/scripts/session-harbor.mjs cleanup --json ``` Applied destination/device initialization, first session publication, and first local reclamation are three separate approvals. See [the live-readiness checklist](docs/live-readiness-checklist.md) before using a physical drive. ## Backup, cleanup, and restore After reviewing the dry-run and granting the corresponding scope: ```sh # Preview and then incrementally back up every stable local session. session-harbor backup plan session-harbor backup run --apply # Preview local reclamation after the configured grace. session-harbor cleanup --json # Prefer exactly one target for cleanup pilots. session-harbor cleanup --session --reclaim-action delete --json # Link mode. session-harbor cleanup --apply # Delete mode requires the extra confirmation token. session-harbor cleanup --apply --confirm-delete-local session-harbor verify --json session-harbor restore # dry-run session-harbor restore --apply ``` Retention settings can be reviewed and changed independently. `settings set` is a dry-run unless `--apply` is added: ```sh session-harbor settings show session-harbor settings set --cleanup-after-inactive-days 30 \ --minimum-backup-age-days 7 --reclaim-action keep ``` `archive`, `reclaim`, and `policy` remain compatibility/advanced commands. `--finalize` is retained as a high-risk compatibility override that can bypass the backup-age gate. It is not emitted by either scheduler. ## Cross-device sessions Each device writes only `devices//...`; no shared database or peer-tree writes are used. ```sh session-harbor sync status --json session-harbor sync pull --peer --json session-harbor sync pull --peer --include-objects --apply session-harbor sync export --output session-harbor sync export --output --apply ``` Metadata caching supports an explicitly stale offline view. Raw object caching is opt-in. Peer export materializes a verified JSONL copy but does not mutate Codex indexes or reconstruct its sidebar. Local reclamation never propagates as a cross-device deletion; immutable evidence remains referenced. ## Reviewed shared context Map different local paths to the same portable project ID: ```sh session-harbor project map session-harbor /local/project/path session-harbor project map session-harbor /local/project/path --apply ``` Then use the reviewed-memory workflow: ```sh session-harbor memory draft --project session-harbor --input draft.json session-harbor memory draft --project session-harbor --input draft.json --apply session-harbor memory approve --project session-harbor session-harbor memory approve --project session-harbor --apply session-harbor memory diff --peer --project session-harbor session-harbor memory stage --peer --project session-harbor session-harbor memory stage --peer --project session-harbor --apply session-harbor memory status --project session-harbor ``` Every entry needs a verified session ID, exact session SHA-256, and locator. Drafts remain private; only approved snapshots become peer-visible. Restricted entries require explicit inclusion at approval and staging. `staged` is SessionHarbor context, not native Codex memory and not an adopted project instruction. ## Read-only legacy migration ```sh session-harbor migrate codexbridge plan --source /path/to/old/CodexBridge session-harbor migrate v01 plan --source /path/to/old/SessionHarbor ``` The applied forms create new verified objects and snapshots without changing the old payload or catalog. No migration cleanup command exists. ## Windows development handoff The [Windows handoff protocol](docs/windows-handoff.md) keeps each device in its own immutable writer tree and defines a write-back result format. The Mac prepares a checksummed source snapshot under a separate `SessionHarbor-Handoff` directory on the removable drive; Windows copies it to a local NTFS development directory, tests there, then writes only its own result file back to the handoff folder. ## Scheduling macOS: ```sh node plugins/session-harbor/scripts/launchagent.mjs install \ --config ~/.config/session-harbor/config.json --apply ``` Windows: ```powershell node plugins/session-harbor/scripts/windows-task.mjs render ` --config "$HOME\.config\session-harbor\config.json" ``` Install/uninstall remains dry-run without `--apply`. By default, macOS combines true filesystem-mount and weekly triggers; Windows combines weekly execution with a configurable 15-minute drive-presence poll because Task Scheduler has no portable volume-arrival trigger. The command is idempotent and a missing configured drive is a safe no-op. Use `--no-on-mount` or `--no-weekly` to select one mode; manual `backup run --apply` is always available. Generated backup schedules never clean local files. A cleanup schedule must be explicitly requested, and delete scheduling additionally requires `--confirm-delete-local`. ## Development ```sh npm ci --ignore-scripts npm run check npm test npm pack --dry-run --json ``` The contract schema is in [`schemas/session-harbor-contracts-v1.schema.json`](schemas/session-harbor-contracts-v1.schema.json), with semantic checks in `bridge-contracts.mjs`. The design, threat model, milestone evidence, and release gates are under `docs/`. ## Privacy and limitations Raw rollouts can contain prompts, code, paths, tool output, images, credentials, and personal data. SHA-256 detects corruption but does not encrypt the drive or authenticate another writer. Use encrypted storage where loss of an unencrypted drive would be unacceptable. SessionHarbor is not affiliated with or endorsed by OpenAI. See [LICENSE](LICENSE), [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md), [PRIVACY.md](PRIVACY.md), [TERMS.md](TERMS.md), [SUPPORT.md](SUPPORT.md), [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [THIRD_PARTY.md](THIRD_PARTY.md). --- # Source: AGENTS.md # SessionHarbor repository guidance ## Project SessionHarbor is an unofficial, local-first Codex plugin and zero-dependency Node.js CLI. It backs up raw Codex rollout JSONL files to a verified content-addressed vault, keeps backup separate from local-space reclamation, restores verified raw sessions, and exchanges device-owned snapshots plus reviewed evidence-linked context between macOS and Windows. The project is source-available for noncommercial use under PolyForm Noncommercial 1.0.0. Do not describe it as OSI open source. It is not affiliated with or endorsed by OpenAI. ## Safety invariants - Start operational workflows with read-only planning or status commands. Synthetic development work never authorizes mutations against a real Codex home or removable drive. - Never write Codex SQLite, `session_index.jsonl`, generated memories, authentication, plugin runtimes, caches, or project trees. - Backup must never imply cleanup. Link/delete reclamation remains a separate scope; delete requires `--apply --confirm-delete-local` and a current verified vault copy. - Fail closed on destination identity mismatch, open/changed source, hash mismatch, symlinked path components, peer rollback, target conflicts, path traversal, or unknown contracts. - A device writes only its own vault subtree. Local deletion must not propagate to peer snapshots. - Never commit real rollouts, configs, catalogs, logs, tokens, device identifiers, personal paths, or archive objects. Tests and examples use synthetic data only. Read `docs/threat-model.md` before changing a mutation, restore, path, identity, or verification boundary. Read `docs/live-readiness-checklist.md` before changing physical-drive claims. ## Repository map - `plugins/session-harbor/scripts/session-harbor.mjs`: CLI entrypoint. - `plugins/session-harbor/scripts/lib/`: archive, backup, retention, snapshot, peer, memory, migration, and dashboard implementation. - `plugins/session-harbor/skills/session-harbor/`: installed-agent workflow and focused references. - `schemas/` and `examples/contracts/`: portable contract schema and synthetic examples. - `tests/`: synthetic, cross-platform, interruption, and safety regression coverage. - `docs/architecture.md`: executable component map; `docs/v2-architecture.md` is the frozen design. - `docs/agent-index.md`: compact machine-oriented routing index. - `scripts/generate-agent-docs.mjs`: deterministic `llms.txt`/`llms-full.txt` generator. ## Development workflow - Keep runtime code compatible with Node.js 20+ and preserve the zero-production-dependency design. - Prefer a focused change with a regression test. Do not weaken a refusal merely to make a test pass. - Preserve exact error codes and dry-run/apply boundaries; downstream automation relies on them. - When contracts change, update the schema, semantic validator, synthetic examples, tests, agent index, and relevant architecture or threat-model text together. - When user-facing behavior changes, update the README, skill instructions, changelog, and release evidence as applicable. - Third-party patches are not currently accepted for merge; see `CONTRIBUTING.md` before preparing a pull request. ## Validation Run from the repository root: ```sh npm ci --ignore-scripts npm run check npm test npm pack --dry-run --json ``` `npm run check` includes syntax, contract, and generated-agent-document drift checks. Inspect the package dry run for sensitive or unintended files. When plugin or skill metadata changes, also run the official Codex plugin and skill validators before release. ## Code review rules - Flag any path that can delete/link a source without fresh source-and-target verification. - Flag any backup or schedule path that implicitly enables cleanup. - Flag portable records containing absolute machine paths or peer-owned writes. - Flag claims of native sidebar reconstruction, encryption, authenticated ownership, or exact cross-platform session resumption that the implementation does not provide. - Flag documentation that calls the license open source or hides the preview limitations. --- # Source: docs/agent-index.md # SessionHarbor agent index > Machine-oriented routing index for the unofficial, local-first SessionHarbor Codex plugin and CLI. ## Identity - Repository: - Current public preview: `v0.3.1` - Runtime: Node.js 20 or newer; zero production dependencies - Platforms: macOS and Windows; Linux is used only for synthetic CI coverage - License: PolyForm Noncommercial 1.0.0; source-available for noncommercial use, not OSI open source - Publisher: Xiaofan Wang - Affiliation: independent project, not affiliated with or endorsed by OpenAI ## Use SessionHarbor when - Codex rollout history needs incremental backup to an external drive or mounted NAS. - Verified old local rollouts should become eligible for link/delete reclamation under a separate inactivity and backup-age policy. - A verified raw rollout must be restored without consuming the vault copy. - Multiple macOS/Windows devices need immutable peer inventories or reviewed evidence-linked context. - A dedicated Codex task should show backup progress, restorable sessions, retention waits, and settings. Do not use SessionHarbor for ordinary project-file backup, ChatGPT web conversation export, crash dump cleanup, cloud-database synchronization, or native Codex sidebar reconstruction. ## Fastest install route Open a new Codex task and paste one of the pinned bootstrap prompts: - English: - 简体中文: The prompts verify the official owner/release/license, add the repository marketplace, install the plugin, read the pinned skill, and start with a read-only dashboard. ## Operational routing | User intent | Start with | Mutation boundary | | --- | --- | --- | | Show status or progress | `session-harbor dashboard --json --limit 50` | None | | Diagnose destination/device | `doctor --json`, `bridge doctor --json` | None | | Back up all sessions | `backup plan --json` | `backup run --apply` | | Review retention | `settings show`, `cleanup --json` | Settings and cleanup are separate approvals | | Delete one verified local original | Targeted `cleanup --session --reclaim-action delete --json` | `--apply --confirm-delete-local` | | Verify the vault | `verify --json` | Read-only verification | | Restore a rollout | `restore ` | `restore --apply` | | Inspect another device | `sync status --json` | Peer caching/export requires separate apply | | Share reviewed context | `memory diff/status` | Draft, approve, and stage are separate scopes | | Migrate a legacy archive | `migrate ... plan` | Applied migration never deletes the source | ## Non-negotiable safety model 1. Backup, cleanup, restore, peer caching, reviewed-memory publication, migration, and scheduler installation are independent mutations. 2. Backup never deletes or links a local rollout. 3. Cleanup re-hashes the current source and vault object and refuses open/changed sources. 4. Delete requires a current verified copy, inactivity gate, backup-age hold, `--apply`, and `--confirm-delete-local`. 5. A missing/mismatched destination marker, target conflict, hash mismatch, symlinked path, traversal, peer rollback, or unknown contract fails closed. 6. SessionHarbor never writes Codex SQLite, `session_index.jsonl`, generated memory, authentication, caches, or project files. 7. Restore materializes verified raw JSONL. Exact sidebar/index reconstruction is not promised. ## Storage classes - `stable-mounted`: external drive or mounted NAS; verified backup plus explicitly gated link/delete reclamation can be supported. - `client-synced`: iCloud, Baidu Netdisk, or another client-managed sync folder; reclaim action must remain `keep` because remote durability is outside the filesystem transaction. SHA-256 verifies bytes; it does not encrypt the destination or authenticate another writer. ## Repository source map - Human overview and commands: `README.md` - Repository-wide agent rules: `AGENTS.md` - Installed workflow: `plugins/session-harbor/skills/session-harbor/SKILL.md` - Plugin metadata: `plugins/session-harbor/.codex-plugin/plugin.json` - Executable architecture: `docs/architecture.md` - Threats and residual risks: `docs/threat-model.md` - Physical-drive gates: `docs/live-readiness-checklist.md` - Management task semantics: `docs/management-center.md` - Contract schema: `schemas/session-harbor-contracts-v1.schema.json` - Release evidence: `docs/release-notes-v0.3.1.md` - Privacy, terms, and support: `PRIVACY.md`, `TERMS.md`, `SUPPORT.md` ## Development and verification ```sh npm ci --ignore-scripts npm run check npm test npm pack --dry-run --json ``` CI runs Node.js 20 and 22 across macOS, Windows, and Linux using synthetic homes and destinations. No real session or vault payload belongs in the repository, tests, issues, or release artifacts. ## Discovery files - Compact web index: - Combined machine-readable context: - Project page: --- # Source: plugins/session-harbor/skills/session-harbor/SKILL.md --- name: session-harbor description: "Operate a dedicated Codex session-management task: show backup progress and inventories, configure retention, safely back up or clean verified local Codex sessions, restore sessions, exchange cross-device evidence, or migrate legacy archives. Do not use for ordinary project-file backups or ChatGPT web conversations." --- # SessionHarbor Use the bundled CLI for deterministic filesystem work. Resolve it relative to this file as `../../scripts/session-harbor.mjs`. ## Dedicated management task When the user asks to use this Codex task as a SessionHarbor control window, begin each operational turn with the read-only `dashboard --json --limit 50`. Summarize backup state, local deletion state, retention waits, policy, last publication, and current operation progress before proposing changes. Use filters instead of dumping raw rollout content. Read [management-center.md](references/management-center.md) for status filters, natural-language routing, settings changes, targeted cleanup, scheduling choices, and response labels. ## Non-negotiable safety boundary - Start with read-only `doctor`, `bridge doctor`, `backup plan`, `cleanup`, `sync plan`, or status commands. - Treat destination initialization, device initialization, archive publication, local reclamation, restore, peer caching, memory approval/staging, migration, compression, and scheduler installation as separate mutations. - Never infer approval for a real session or external-drive mutation from approval to develop or test the plugin. Synthetic tests do not authorize live use. - Never use `--skip-open-check` on real data. - Stop on a missing or mismatched destination marker, changed/open source, target conflict, hash mismatch, symlinked path component, unsupported protocol, peer rollback, or unknown contract. - Never write Codex SQLite, `session_index.jsonl`, generated memory, authentication, caches, plugin runtimes, or project trees. ## Backup and cleanup semantics Config v4 separates disaster recovery from local-space cleanup: - `backup.scope` is `all`: every stable rollout in `sessions` and `archived_sessions` is considered, regardless of age or size. Changed rollouts publish a new immutable revision. - `backup.allowPartial` permits other stable sessions to finish when a currently changing session fails its stable-read check; the result must be reported as partial and retried later. - `backup.verifyExistingObjects=false` keeps insertion/weekly runs incremental by trusting unchanged source metadata plus stored object size and hashing new/changed bytes. `verify` remains the full cryptographic scrub and cleanup always re-hashes source and target before local mutation. - `retention.cleanupAfterInactiveDays`: inactivity before a verified local copy becomes eligible for cleanup. - `retention.minimumBackupAgeDays`: safety hold after the latest verified backup revision. `backup` only copies, verifies, and publishes the device snapshot; it never reclaims local files. `cleanup` (alias `reclaim`) is separate and re-verifies both source and destination: - `keep`: retain the local original indefinitely. - `link`: replace it with a reversible link to a stable mounted destination. - `delete`: remove only the verified local original; requires both `--apply` and `--confirm-delete-local`, and remains restorable from the verified object. Use `exchange.storageClass: "stable-mounted"` for an external drive or mounted NAS. A client-managed iCloud/Baidu/Synology folder must use `"client-synced"` with reclaim action `keep`. ## First-use workflow 1. Preview `init --destination `, then request approval before `init ... --apply`. 2. Preview `device init`; request separate approval before `device init --apply`. 3. Run `doctor --json`, `bridge doctor --json`, `backup plan --json`, and `cleanup --json`. 4. Report full-backup count/bytes, new/reused objects, any partial inventory errors, cleanup inactivity, minimum backup age, reclaim action, destination identity, broken links, and every warning/error. 5. After explicit approval, use `backup run --apply` to create verified copies and a device snapshot. Do not run cleanup in the first live run. 6. Run `verify --json`, `sync status --json`, and a dry-run restore/export test. 7. Only after an independently verified restore and a later explicit request, preview `cleanup`. For delete mode, request confirmation immediately before using `cleanup --session --apply --confirm-delete-local` for the pilot. `--finalize` is a compatibility override that can bypass the grace period. Treat it as higher risk and never use it in a scheduler. ## Cross-device and reviewed memory - `sync push` publishes objects, then an immutable manifest, then its hash-bound head. - `sync pull` caches verified peer metadata; `--include-objects --apply` additionally permits offline peer export. A device writes only under its own vault subtree. - `sync export` materializes a verified peer session without editing Codex databases. - `memory draft` stays private. `memory approve` is the only peer-visible publication and requires evidence matching a verified session object. Restricted entries require `--include-restricted`. - `memory stage` writes only SessionHarbor's private local context cache. `staged` is not `adopted` and is never described as native Codex memory. Read [bridge-and-memory.md](references/bridge-and-memory.md) for the detailed exchange workflow. For compression or destination selection, read [compression-and-destinations.md](references/compression-and-destinations.md). ## Migration and scheduling `migrate codexbridge|v01 plan` is read-only. Applied migration creates new verified objects and never deletes or rewrites the legacy source. macOS scheduling uses `../../scripts/launchagent.mjs`; Windows uses `../../scripts/windows-task.mjs`. Installation is dry-run unless `--apply` is supplied. The default schedule combines drive-presence and weekly all-session backup while leaving cleanup off. macOS uses `StartOnMount`; Windows uses configurable drive-presence polling plus a weekly trigger. Use `--no-on-mount` or `--no-weekly` to select one. Manual `backup run --apply` is always supported. A scheduler includes cleanup only when explicitly encoded, and delete scheduling also requires `--confirm-delete-local`. --- # Source: docs/architecture.md # SessionHarbor 0.3 implementation architecture The complete three-layer design and portable layout are in [v2-architecture.md](v2-architecture.md). This document maps the executable modules. ## Components - `archive-core.mjs`: config v4, all-session backup inventory, verified catalog, independently age-selected local cleanup, restore, compression orchestration, and destination identity. - `backup-runner.mjs`: manual/scheduled all-session backup followed by immutable snapshot publication. - `atomic-store.mjs`: immutable/mutable same-directory temp writes, fsync, atomic rename, read-back, portable path checks, and concurrent-head protection. - `device-registry.mjs`: stable device identity, protocol, device manifest, and bridge diagnostics. - `session-snapshot.mjs`: content-addressed objects, immutable snapshots, manifest-last head commit, idempotency, and no-deletion propagation. - `peer-discovery.mjs`: verified peer discovery, rollback warning, offline metadata/raw cache, and explicit peer export. - `memory-exchange.mjs`: private drafts, evidence validation, approved immutable memory snapshots, peer diff, restricted filtering, and private local staging. - `migration.mjs`: read-only CodexBridge/v0.1 inventory and verified import. - `retention-runner.mjs`: compatibility orchestration for full backup, publication, and optional cleanup. - `project-map.mjs`: private machine path to portable project ID mapping. - `launchagent.mjs` and `windows-task.mjs`: dry-run-first scheduler generation/installation. ## Retention state machine ```text discovered -> copied + verified -> changed -> new immutable revision | +-> inactive long enough + backup-age hold -> ready +-- keep +-- link -> linked +-- delete -> reclaimed linked/reclaimed -> verified restore -> restored local restored local -> changed -> new immutable object/revision ``` `backup` covers every stable rollout and stops at copied/verified. `cleanup`/`reclaim` is the only normal command that crosses from ready to link/delete. Delete additionally requires `--confirm-delete-local`. `--finalize` is an explicit compatibility override and is never scheduled. When a stable device exists, all-session backup and cross-device snapshots reuse the same content-addressed object. A later local deletion does not remove the object or propagate a deletion to the session head. ## Transaction boundary The portable publication commit order is object → immutable snapshot → mutable hash-bound head. Peers ignore orphan objects/manifests and retain the last verified head. Every device writes only its own subtree. Portable records contain no absolute local paths. The destination identity marker is checked on every mutation and verification. A missing mount is never created implicitly by archive/sync/reclaim commands. ## Local-only state Private config, project maps, peer cache, memory drafts, staged memory, scheduler files, and absolute paths stay outside the vault. SessionHarbor does not edit Codex indexes, SQLite, generated memory, or authentication. --- # Source: docs/threat-model.md # Threat model ## Protected outcomes - A copy is never called archived until its SHA-256 matches a stable source snapshot. - A local rollout is never replaced merely because a destination filename exists. - An open or changed rollout is not finalized. - Restore does not consume Markdown, HTML, or an unverified target. - Paths from configuration or catalog entries cannot escape their declared roots. - Existing symbolic links in archive path components, marker paths, and catalog paths are rejected. - A configured archive only accepts the destination carrying its original random identity marker. - A portable contract cannot contain an absolute or traversal path. - One device cannot publish a valid head or content path under a peer device's subtree. - A memory entry is not accepted without evidence tied to an exact session ID and hash. - A vault protocol must match the destination marker identity before a device manifest is trusted. - A stored device identity cannot be rebound through later CLI flags or a conflicting manifest. - Archive publication cannot implicitly reclaim a local source; reclamation is a separate scope. - Delete reclamation requires an extra confirmation and a still-verifiable archive copy. - Local deletion does not propagate through session snapshots. - A draft memory snapshot can never become a peer-visible head. - Legacy migration never mutates or cleans up its source layout. ## Expected failures - Destination disconnected before a run: the command stops before modifying sources. - Expected mount path exists but belongs to a different disk or recreated folder: marker comparison stops the run. - Destination disconnects during copy: the partial file is removed when possible and the source remains. - Source changes during hash or copy: the operation fails and does not publish a catalog entry. - Target changes after copying: finalization and restore fail on a hash mismatch. - Process stops after catalog state `copied`: the source is still local; a later run can continue safely. - Process stops during local link or restore replacement: a same-directory backup is used for rollback. - Process stops before a session or memory head update: the previous head remains authoritative. - Peer head is rolled back or diverges: the cached verified view remains and a rollback warning is shown. - Destination is disconnected after metadata was cached: the view is marked stale; raw export requires an explicitly cached verified object. ## Residual risks - POSIX cannot provide a cross-process transaction with Codex's writer. The tool combines an age gate, stable metadata checks, repeated hashes, and `lsof`; a narrow race can still exist if another process opens the file immediately after the final check. - A symlinked session cannot resume when its destination is disconnected. - A locally deleted session is absent from native Codex storage until explicitly restored; exact sidebar reconstruction is not promised. - Windows open-file safety relies on stable-copy checks and rename-enforced reclamation rather than `lsof`; filesystem and application behavior still requires physical beta testing. - exFAT and network/client-synchronized filesystems may not provide the same durability guarantees as APFS/NTFS. Applied writes verify read-back, but power-loss behavior remains carrier-dependent. - A malicious process with the same user permissions can modify files between checks. - SHA-256 detects accidental or unsophisticated modification but does not authenticate archive ownership. - Internal Codex storage conventions may change. Always test after upgrading Codex. - A malicious writer can replay an older but internally valid head. Clients must retain the last verified lineage and warn on rollback or divergence. - SHA-256 does not authenticate device ownership. Contract v1 relies on a user-controlled vault; signed manifests are a possible future hardening measure. - A device bootstrap interrupted after config save may leave a missing manifest, but the saved stable ID is the recovery anchor and a repeated initialization completes the same identity. ## Secrets and publication Raw rollout files and live configuration are sensitive. CI uses only synthetic fixtures. Release archives must exclude `catalog-v1.json`, real configs, logs, and any session data. --- # Source: docs/live-readiness-checklist.md # Live external-drive readiness checklist Status: implementation and synthetic validation complete. Each installation must separately verify its physical-drive and live-history state before enabling local cleanup. This checklist is the boundary between developing SessionHarbor and touching real Codex history. ## 1. Independent recovery copy - Make an independent backup of `~/.codex/sessions`, `~/.codex/archived_sessions`, and the Windows equivalents before SessionHarbor's first live write. - Keep that backup outside the SessionHarbor destination and verify at least one raw JSONL can be read. - Do not use authentication, caches, plugins, or SQLite as the recovery artifact. ## 2. Physical carrier rehearsal - Confirm the exact mount/root and free space on both computers. - Use a disposable Codex home with synthetic rollouts on the real drive. - Initialize the destination and two distinct device IDs. - Test Mac publish → Windows verify/export, then Windows publish → Mac verify/export. - Disconnect before object copy, during copy, after manifest, before head, and after head. Each rerun must retain the last valid head and finish idempotently. - Record OS, Node, Codex, filesystem, drive model, and observed durability warnings. ## 3. Restore gate - Run copy-only mode first. - Verify every selected object and snapshot. - Export a peer object and compare its SHA-256. - Restore one disposable session, confirm the local bytes, continue it, and confirm the continuation publishes as a new immutable revision. ## 4. Selected live copy-only pilot - Run `doctor`, `bridge doctor`, and `backup plan` against the real config. - Review all-session count/bytes, new/reused objects, destination identity, and warnings. - Apply `backup run --apply` in `keep` mode. A partial result must be retried before cleanup. - Verify the vault and restore independently before expanding the batch. ## 5. Local-space reclamation gate - Set and review `cleanupAfterInactiveDays`; keep `autoReclaim` false during the pilot. - Wait at least the configured `minimumBackupAgeDays` after the latest backup revision. - Run `cleanup` without `--apply` and review every candidate. - During a pilot, use `cleanup --session ` so one approved candidate cannot expand into a batch operation. - Prefer `link` only when the external/NAS path is stable and expected to stay mounted. - Use `delete` only after a second independent restore and a fresh explicit confirmation. Applied delete requires `--confirm-delete-local`. - Run `verify` immediately afterward, restore a deleted pilot, and confirm no local deletion propagated into peer heads. - Do not use `--finalize` to simulate the configured backup-age wait. If no candidate has naturally reached `cleanupEligibleAt`, record the gate as blocked and test again later. ## 6. Scheduler gate - Install backup-only scheduling first. macOS may combine mount and weekly triggers; Windows uses a weekly trigger plus configurable drive-presence polling. - Confirm a missing drive yields `backup-skipped` and never creates the mount path. - Confirm reinsertion produces an idempotent incremental backup. - Run a separate full `verify` after unsafe removal/filesystem warnings and before enabling cleanup; fast insertion backup is not a substitute for a cryptographic scrub. - Do not install scheduled cleanup until the exact inactivity threshold is approved. Scheduled delete additionally requires a fresh `--confirm-delete-local` decision. ## Stop conditions Stop without repairing or retrying automatically on any destination identity mismatch, missing marker, open/changed source, target conflict, hash mismatch, symlink path, unsupported contract, rollback warning, unavailable peer object, or failed restore. --- # Source: docs/management-center.md # Management-center workflow SessionHarbor supports a dedicated Codex task that acts as the operator console. The task is a conversation layer over deterministic CLI commands; it is not a database, daemon, or replacement for the verified vault. ## Read-only dashboard ```sh session-harbor dashboard session-harbor dashboard --json --limit 50 session-harbor dashboard --state backed session-harbor dashboard --state unbacked session-harbor dashboard --state changed session-harbor dashboard --state deleted session-harbor dashboard --state restored session-harbor dashboard --state cleanup-ready session-harbor dashboard --state waiting-backup-age ``` `--limit all` or `--limit 0` returns every matching session. The dashboard compares the local inventory with catalog metadata so it stays fast. It explicitly does not replace `verify`, which re-hashes vault objects and local sources. Applied backups publish progress to the local config state directory. While a backup runs, the dashboard shows its stage and processed/total counts. A final status is retained as the last operation; a running record older than six hours is marked stale. ## Settings Settings changes are dry-run by default: ```sh session-harbor settings show session-harbor settings set \ --cleanup-after-inactive-days 30 \ --minimum-backup-age-days 7 \ --reclaim-action keep session-harbor settings set \ --cleanup-after-inactive-days 30 \ --minimum-backup-age-days 7 \ --reclaim-action delete \ --apply ``` Changing `reclaimAction` does not delete anything. Cleanup remains a separate command, automatic cleanup remains disabled unless explicitly enabled, and delete still requires the extra confirmation token. ## Targeted cleanup and restore Use a single-session selector for pilots and ordinary conversational operations: ```sh session-harbor cleanup --session --reclaim-action delete --json session-harbor cleanup --session --reclaim-action delete \ --apply --confirm-delete-local session-harbor restore session-harbor restore --apply session-harbor verify --json ``` Never use `--finalize` to simulate an elapsed backup-age safety period. If the dashboard reports `waiting-backup-age`, wait until `cleanupEligibleAt` and rerun the dry-run. ## Scheduling choices - Manual backup is always available. - macOS supports drive-mount plus weekly calendar triggers; weekday, hour, and minute are configurable. - Windows supports a weekly calendar trigger plus configurable drive-presence polling. - Backup schedules never clean local files by default. - Cleanup scheduling is a separate opt-in. Delete scheduling additionally requires an explicit delete policy and confirmation token, and should not be enabled during a pilot. ## Conversation response contract For every request, show the current policy and distinguish: - `planned`: dry-run only; - `running`: an operation-state record is active; - `verified complete`: the command finished and required verification passed; or - `blocked`: a destination, identity, open-file, time, hash, or authorization gate refused the action. When lists are long, show counts first and offer narrow dashboard filters. Never include prompt text, tool output, credentials, or raw rollout content in a normal status response. --- # Source: PRIVACY.md # Privacy policy Effective date: 2026-08-27 SessionHarbor is a local-first Codex session-management plugin and command-line tool published by Xiaofan Wang. It does not operate a developer-hosted service, require a SessionHarbor account, send telemetry to the developer, or upload session data to the developer. ## Data processed locally SessionHarbor can read raw Codex rollout JSONL files and related local metadata needed to inventory, back up, verify, reclaim, restore, and exchange reviewed context. Those files can contain prompts, code, tool output, images, credentials, personal data, and absolute local paths. The tool writes only to locations selected or initialized by the user, including its private local configuration and a user-selected filesystem vault. Portable records exclude absolute local paths. SessionHarbor does not edit Codex authentication, SQLite databases, `session_index.jsonl`, generated memories, caches, or project files. ## External storage If a user selects an external drive, NAS, iCloud, Baidu Netdisk, Synology, WebDAV-mounted storage, or another third-party destination, that provider's privacy and security terms govern the destination. SessionHarbor does not control those services. Client-synchronized destinations are restricted to non-reclaiming storage mode because sync completion and durability cannot be verified as a mounted filesystem transaction. ## Retention and deletion The user controls archive retention and local reclamation. Backup never deletes a local source. Local delete reclamation requires explicit configuration, an applied command, an extra confirmation, and a current verified vault copy. Removing files from a user-selected vault is outside the normal SessionHarbor workflow. ## Security SHA-256 verification detects content changes but does not encrypt a drive or authenticate another writer. Users should encrypt storage when loss of the destination would expose sensitive data. Do not submit real sessions, archive objects, credentials, or personal paths in public issues. Security reports should follow [SECURITY.md](SECURITY.md). General support is described in [SUPPORT.md](SUPPORT.md). ## Changes Material changes to this policy will be committed to the public repository and identified in release notes when applicable. --- # Source: TERMS.md # Terms of use Effective date: 2026-08-27 Use of SessionHarbor is governed by the [PolyForm Noncommercial License 1.0.0](LICENSE). Commercial use requires a separate written license; see [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md). SessionHarbor is preview software. Users are responsible for reviewing dry-run output, protecting their backup destination, testing restore with synthetic or non-critical data, ejecting removable media cleanly, and confirming that a verified backup exists before enabling local reclamation. The project does not promise exact reconstruction of Codex's native sidebar or indexes. The software is provided under the warranty and liability terms in the license. SessionHarbor is an independent project by Xiaofan Wang and is not affiliated with or endorsed by OpenAI. “Codex” and other third-party names remain the property of their respective owners. Data handling is described in [PRIVACY.md](PRIVACY.md), security reporting in [SECURITY.md](SECURITY.md), and support boundaries in [SUPPORT.md](SUPPORT.md). --- # Source: SUPPORT.md # Support Use [GitHub Issues](https://github.com/WangPeterXF/session-harbor/issues) for reproducible bugs, compatibility reports, documentation problems, and feature proposals. Choose the closest issue form and include only synthetic or redacted evidence. Include the platform, Node.js version, Codex version, filesystem type, command, exact error code, and smallest synthetic reproduction. Never attach real rollouts, catalogs, configs, archive objects, credentials, usernames, device identifiers, or absolute personal paths. For a suspected vulnerability, follow [SECURITY.md](SECURITY.md) and do not open a public issue with sensitive details. Commercial licensing requests are described in [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md).