fix(pi): enable cloud autosync for gentle-engram

Author: Alan-TheGentleman

docs/AGENT-SETUP.md

@@ -35,12 +35,12 @@ Install Engram's Pi package, the MCP adapter, and Pi MCP config:
 engram setup pi
 ```
 
-`engram setup pi` runs `pi install npm:gentle-engram@0.1.5` and `pi install npm:pi-mcp-adapter`, then ensures Pi settings contain both packages and writes `mcpServers.engram` in the Pi agent MCP config when no Engram server is already configured. Existing `mcpServers.engram` entries are preserved.
+`engram setup pi` runs `pi install npm:gentle-engram@0.1.6` and `pi install npm:pi-mcp-adapter`, then ensures Pi settings contain both packages and writes `mcpServers.engram` in the Pi agent MCP config when no Engram server is already configured. Existing custom `mcpServers.engram` entries are preserved; the known generated older launcher is migrated safely.
 
 Manual equivalent:
 
 ```bash
-pi install npm:gentle-engram@0.1.5
+pi install npm:gentle-engram@0.1.6
 pi install npm:pi-mcp-adapter
 pi-engram init
 ```
@@ -681,6 +681,12 @@ engram mcp
 The process logs `[autosync] started (server=...)` on success. Missing token or server URL logs `[autosync] ERROR: ...` and the process starts normally without autosync.
 For `engram mcp`, autosync runs for the lifetime of the stdio MCP process and is stopped when that process exits.
 
+### Pi `gentle-engram` parity
+
+When Pi starts Engram through `gentle-engram`, the package keeps the sync loop in Engram core but can auto-enable it for Pi-managed child processes. If `ENGRAM_CLOUD_AUTOSYNC` is unset, `ENGRAM_CLOUD_TOKEN` is set, and a Cloud server is configured through `ENGRAM_CLOUD_SERVER` or `${ENGRAM_DATA_DIR:-~/.engram}/cloud.json`, Pi-launched `engram serve` and the `pi-engram init` MCP launcher pass `ENGRAM_CLOUD_AUTOSYNC=1` to the child process.
+
+Set `ENGRAM_CLOUD_AUTOSYNC=0` or another explicit value to opt out for that Pi environment. Project enrollment and Cloud pause controls still decide what can actually sync.
+
 ---
 
 ## Cloud dashboard (templ contributors)

internal/setup/setup.go

@@ -77,7 +77,7 @@ const claudeCodeMarketplace = "Gentleman-Programming/engram"
 
 const openCodeSubagentStatuslinePlugin = "opencode-subagent-statusline"
 
-const piGentleEngramPackage = "npm:gentle-engram@0.1.5"
+const piGentleEngramPackage = "npm:gentle-engram@0.1.6"
 const piMCPAdapterPackage = "npm:pi-mcp-adapter"
 
 // claudeCodeMCPTools are the MCP tool permission names for the agent profile

internal/setup/setup_test.go

@@ -315,7 +315,7 @@ func TestInstallPiInstallsPackagesAndWritesConfig(t *testing.T) {
 	if result.Agent != "pi" || result.Destination != agentDir || result.Files != 2 {
 		t.Fatalf("unexpected install result: %#v", result)
 	}
-	wantCommands := []string{"pi install npm:gentle-engram@0.1.5", "pi install npm:pi-mcp-adapter"}
+	wantCommands := []string{"pi install npm:gentle-engram@0.1.6", "pi install npm:pi-mcp-adapter"}
 	if !reflect.DeepEqual(commands, wantCommands) {
 		t.Fatalf("unexpected pi install commands: got %#v want %#v", commands, wantCommands)
 	}
@@ -330,7 +330,7 @@ func TestInstallPiInstallsPackagesAndWritesConfig(t *testing.T) {
 	if err := json.Unmarshal(settingsRaw, &settings); err != nil {
 		t.Fatalf("parse settings: %v", err)
 	}
-	for _, pkg := range []string{"npm:gentle-engram@0.1.5", "npm:pi-mcp-adapter"} {
+	for _, pkg := range []string{"npm:gentle-engram@0.1.6", "npm:pi-mcp-adapter"} {
 		if !slices.Contains(settings.Packages, pkg) {
 			t.Fatalf("expected settings packages to include %q, got %#v", pkg, settings.Packages)
 		}
@@ -398,7 +398,7 @@ func TestInstallPiPreservesExistingEngramMCPServer(t *testing.T) {
 	if err != nil {
 		t.Fatalf("read settings after install: %v", err)
 	}
-	if !strings.Contains(string(settingsRaw), "npm:existing") || !strings.Contains(string(settingsRaw), "npm:gentle-engram@0.1.5") || !strings.Contains(string(settingsRaw), "npm:pi-mcp-adapter") {
+	if !strings.Contains(string(settingsRaw), "npm:existing") || !strings.Contains(string(settingsRaw), "npm:gentle-engram@0.1.6") || !strings.Contains(string(settingsRaw), "npm:pi-mcp-adapter") {
 		t.Fatalf("expected settings packages to be preserved and extended, got %s", settingsRaw)
 	}
 }
@@ -409,7 +409,7 @@ func TestInstallPiCommandFailure(t *testing.T) {
 		return []byte("boom"), errors.New("exit 1")
 	}
 	_, err := Install("pi")
-	if err == nil || !strings.Contains(err.Error(), "install npm:gentle-engram@0.1.5") {
+	if err == nil || !strings.Contains(err.Error(), "install npm:gentle-engram@0.1.6") {
 		t.Fatalf("expected pi install error, got %v", err)
 	}
 }

openspec/changes/gentle-engram-cloud-autotick/apply-progress.md

@@ -0,0 +1,56 @@
+# Apply Progress: gentle-engram-cloud-autotick
+
+## Implementation summary
+
+Implemented Pi `gentle-engram` Cloud autosync parity by adding a child-process environment helper and wiring it into Pi-managed Engram processes.
+
+## Changes
+
+- Added `plugin/pi/cloud-autosync-env.js`.
+  - Enables `ENGRAM_CLOUD_AUTOSYNC=1` only when token+server are configured and no explicit autosync env exists.
+  - Supports `ENGRAM_CLOUD_SERVER` and persisted `${ENGRAM_DATA_DIR:-~/.engram}/cloud.json` `server_url`.
+- Updated `plugin/pi/index.ts`.
+  - `spawnDetached()` now passes helper-generated env to Engram child processes.
+- Updated `plugin/pi/cli.js` and `plugin/pi/mcp-template.json`.
+  - Generated MCP launcher now applies equivalent auto-enable behavior before running `engram mcp --tools=agent`.
+  - `pi-engram init` now migrates only the known old generated Engram MCP launcher without `--force`; custom configs remain preserved.
+- Added package file entry for the helper.
+- Added Node tests for helper behavior, executable MCP launcher behavior, and safe init migration.
+- Updated Pi/setup docs.
+
+## TDD evidence
+
+RED:
+
+```text
+cd plugin/pi && npm test
+# failed: missing cloud-autosync-env.js, index.ts did not use helper, MCP launcher/template lacked ENGRAM_CLOUD_AUTOSYNC logic
+# later failed: known old generated MCP launcher was kept instead of migrated
+```
+
+GREEN:
+
+```text
+cd plugin/pi && npm test
+# pass: 28 tests
+```
+
+Additional syntax check:
+
+```text
+cd plugin/pi && node --check cli.js && node --check cloud-autosync-env.js
+# pass
+```
+
+## Decisions
+
+- Kept the 30-second tick in Engram core (`internal/cloud/autosync.Manager`).
+- Treated token+server as the Pi-side Cloud opt-in signal.
+- Preserved explicit `ENGRAM_CLOUD_AUTOSYNC` values as authoritative.
+- Did not alter Go core sync behavior.
+- Migrated only the exact old generated launcher shape to avoid overwriting custom user MCP configs.
+
+## Pending
+
+- Round 2 Judgment Day re-review results.
+- Final verify report update.

openspec/changes/gentle-engram-cloud-autotick/design.md

@@ -0,0 +1,81 @@
+# Design: gentle-engram-cloud-autotick
+
+## Summary
+
+Add a tiny Pi-package environment helper and use it anywhere the Pi package starts/configures an Engram child process. The helper turns Cloud token+server configuration into `ENGRAM_CLOUD_AUTOSYNC=1` for the child only when the user has not set an explicit autosync value.
+
+The 30-second tick stays in `internal/cloud/autosync.Manager`.
+
+## Architecture
+
+```text
+Pi session
+  └─ gentle-engram extension
+      ├─ auto-starts `engram serve`
+      │    └─ child env includes ENGRAM_CLOUD_AUTOSYNC=1 when token+server configured
+      └─ pi-engram init writes MCP launcher
+           └─ launcher starts `engram mcp --tools=agent` with same env gate
+
+Engram core process
+  └─ cmd/engram.tryStartAutosync
+       └─ internal/cloud/autosync.Manager
+            └─ 30s poll ticker + dirty debounce + push/pull + lease/backoff
+```
+
+## Files
+
+| File | Action | Purpose |
+|---|---|---|
+| `plugin/pi/cloud-autosync-env.js` | NEW | Pure helper for child-process env derivation. |
+| `plugin/pi/index.ts` | MODIFY | Use helper in `spawnDetached()` for `engram serve` / sync import child processes. |
+| `plugin/pi/cli.js` | MODIFY | Generate MCP launcher with equivalent env auto-enable logic. |
+| `plugin/pi/mcp-template.json` | MODIFY | Keep packaged template aligned with generated launcher. |
+| `plugin/pi/package.json` | MODIFY | Include helper in package files. |
+| `plugin/pi/test/cloud-autosync-env.test.mjs` | NEW | Helper unit tests. |
+| `plugin/pi/test/index-source.test.mjs` | NEW | Source guard for helper usage in extension. |
+| `plugin/pi/test/cli-source.test.mjs` | NEW | Source guard for launcher behavior/template alignment. |
+| `plugin/pi/README.md` | MODIFY | Document Pi Cloud autosync parity. |
+| `docs/AGENT-SETUP.md` | MODIFY | Clarify Pi package behavior vs raw CLI behavior. |
+
+## Helper contract
+
+```js
+cloudAutosyncProcessEnv(baseEnv = process.env) -> env
+```
+
+Rules:
+
+1. If `baseEnv.ENGRAM_CLOUD_AUTOSYNC` is non-blank, return `baseEnv` unchanged.
+2. If `baseEnv.ENGRAM_CLOUD_TOKEN` is blank, return unchanged.
+3. If `baseEnv.ENGRAM_CLOUD_SERVER` is non-blank, return a shallow copy with `ENGRAM_CLOUD_AUTOSYNC: "1"`.
+4. Else inspect `${ENGRAM_DATA_DIR || ~/.engram}/cloud.json` for non-empty `server_url`; if present, return shallow copy with autosync `1`.
+5. On absent/malformed config, return unchanged.
+
+Returning unchanged by reference for no-op paths makes tests easy and avoids unnecessary env object copies. Returning a copy for enabled paths avoids mutating `process.env`.
+
+## MCP launcher
+
+The generated `node -e` launcher cannot import package files reliably, so it should embed equivalent minimal logic. This is acceptable because the launcher is already a generated adapter boundary. Keep it dependency-free and Node built-in only.
+
+## Boundary rationale
+
+- Plugin owns process setup, not Cloud sync behavior.
+- Core `tryStartAutosync()` remains the final authority for startup validation.
+- Core manager remains the only owner of tick interval, network push/pull, policy failure handling, and status.
+- Server-side enrollment/pause remains authoritative.
+
+## Validation
+
+Targeted:
+
+```sh
+cd plugin/pi && npm test
+```
+
+Recommended broader check if time allows:
+
+```sh
+go test ./cmd/engram ./internal/cloud/autosync/...
+```
+
+No Go behavior should be changed by this SDD.

openspec/changes/gentle-engram-cloud-autotick/exploration.md

@@ -0,0 +1,95 @@
+# Exploration: gentle-engram-cloud-autotick
+
+## Status
+
+- SDD mode: auto
+- Artifact store: OpenSpec
+- Worktree: `../engram-gentle-engram-cloud-autotick`
+
+## Question
+
+Pi `gentle-engram` currently connects Pi sessions to Engram memory, but Cloud autosync only starts when the underlying Engram process sees `ENGRAM_CLOUD_AUTOSYNC=1`. The user wants Pi package parity with Engram Cloud's 30-second autosync loop.
+
+## Evidence
+
+### Pi plugin behavior
+
+- `plugin/pi/index.ts` registers Pi-native `mem_*` tools and lifecycle handlers.
+- `initOnce()` starts `engram serve` when `/health` is not reachable and `ENGRAM_URL` is not set.
+- The spawned `engram serve` process inherits the parent environment, but the plugin does not derive or inject `ENGRAM_CLOUD_AUTOSYNC=1` from Cloud configuration.
+- `initOnce()` runs one `engram sync --import` for git-synced chunks when `.engram/manifest.json` exists. This is not Cloud autosync.
+
+### Engram core autosync behavior
+
+- `internal/cloud/autosync/manager.go` owns durable background sync behavior.
+- `DefaultConfig()` sets `PollInterval: 30 * time.Second`.
+- `Run()` uses `time.NewTicker(m.cfg.PollInterval)` and runs `safeRun()` on each poll tick.
+- This manager also supports dirty notification debounce, push/pull, lease, backoff, and status.
+
+### Core process startup gates
+
+- `cmd/engram/main.go::tryStartAutosync()` starts autosync only when `ENGRAM_CLOUD_AUTOSYNC` is exactly `"1"`.
+- It also requires a Cloud server URL and `ENGRAM_CLOUD_TOKEN`.
+- The function is intentionally non-fatal: missing config logs and leaves Engram running without autosync.
+- `engram serve` and `engram mcp` call `tryStartAutosync()`.
+
+### Pi MCP setup behavior
+
+- `plugin/pi/cli.js` writes an MCP server launcher that runs `engram mcp --tools=agent`.
+- The launcher currently inherits the Pi process environment but does not infer `ENGRAM_CLOUD_AUTOSYNC=1` from Cloud token/server configuration.
+
+### Docs behavior
+
+- `docs/AGENT-SETUP.md` documents the current core toggle: users must export `ENGRAM_CLOUD_AUTOSYNC=1`, `ENGRAM_CLOUD_TOKEN`, and `ENGRAM_CLOUD_SERVER`.
+- `plugin/pi/README.md` says Cloud is opt-in and project-scoped, but does not document Pi package autosync parity.
+
+## Findings
+
+### What is missing in Pi parity today?
+
+Pi does not automatically enable the existing Engram core autosync loop for Engram processes it launches/configures. Users who run Pi with Cloud token/server configured still need to know and export `ENGRAM_CLOUD_AUTOSYNC=1`; otherwise the 30-second core ticker never starts.
+
+### Where should the 30-second tick live?
+
+The tick must stay in `internal/cloud/autosync`. The Pi plugin should not implement its own polling or Cloud sync loop. `gentle-engram` should only provide thin process environment wiring so the existing Engram core process starts its own autosync manager.
+
+### What gates preserve opt-in cloud sync?
+
+Recommended plugin-side auto-enable gate:
+
+1. Never override an explicit `ENGRAM_CLOUD_AUTOSYNC` value.
+2. Require `ENGRAM_CLOUD_TOKEN` to be non-empty.
+3. Require either `ENGRAM_CLOUD_SERVER` or persisted local `cloud.json.server_url`.
+4. Let Engram core continue enforcing project enrollment, server policy, pause controls, lease, retry, and status.
+
+This keeps local-first behavior because no token means no Cloud replication; configured token+server is a strong Cloud opt-in signal.
+
+### Tests that should fail first
+
+1. `plugin/pi/test/cloud-autosync-env.test.mjs`
+   - auto-enables when token + `ENGRAM_CLOUD_SERVER` are present;
+   - auto-enables when token + persisted `cloud.json.server_url` are present;
+   - does not enable without token;
+   - does not override explicit `ENGRAM_CLOUD_AUTOSYNC=0` or `1`.
+2. `plugin/pi/test/index-source.test.mjs`
+   - verifies `spawnDetached` uses the cloud-autosync env helper when starting Engram processes.
+3. `plugin/pi/test/cli-source.test.mjs` or CLI helper tests
+   - verifies generated MCP launcher includes equivalent auto-enable env logic for `engram mcp`.
+
+### Docs to update
+
+- `plugin/pi/README.md`: add Pi Cloud autosync parity section.
+- `docs/AGENT-SETUP.md`: clarify that Pi `gentle-engram` can auto-enable autosync for its launched/configured Engram processes when token+server are present, while raw `engram serve`/`engram mcp` still support the explicit env toggle.
+
+## Risks
+
+| Risk | Mitigation |
+|---|---|
+| Plugin violates thin-adapter boundary | Only set child process environment; do not implement sync/polling in plugin. |
+| Surprise Cloud sync | Require token + server and preserve explicit `ENGRAM_CLOUD_AUTOSYNC` overrides. Project enrollment remains authoritative. |
+| Duplicate autosync workers | Existing SQLite lease in core manager prevents duplicate workers from syncing concurrently. |
+| Noisy logs when Cloud partially configured | Gate on token+server before injecting autosync. |
+
+## Recommendation
+
+Implement a small Pi helper that builds child-process env for Engram processes. Use it for `engram serve`, generated `engram mcp` launcher, and any plugin-spawned one-shot sync command where harmless. The helper should only set `ENGRAM_CLOUD_AUTOSYNC=1` when the user has Cloud token + server configured and did not set an explicit autosync value.

openspec/changes/gentle-engram-cloud-autotick/proposal.md

@@ -0,0 +1,60 @@
+# Proposal: gentle-engram-cloud-autotick
+
+## Intent
+
+Give Pi `gentle-engram` parity with Engram Cloud autosync by auto-enabling the existing Engram core 30-second autosync manager for Engram processes launched or configured by the Pi package when Cloud is clearly configured.
+
+The Pi plugin must not implement Cloud sync itself. It should remain a thin adapter that starts/configures Engram processes with the right environment so `internal/cloud/autosync.Manager` owns the actual push/pull tick, lease, backoff, policy handling, and status.
+
+## Scope
+
+### In Scope
+
+- Add a small Pi package helper that decides whether child Engram processes should receive `ENGRAM_CLOUD_AUTOSYNC=1`.
+- Use that helper when `plugin/pi/index.ts` auto-starts `engram serve`.
+- Update the `pi-engram init` MCP launcher so generated `engram mcp --tools=agent` processes get equivalent auto-enable behavior.
+- Update `plugin/pi/mcp-template.json` to match the generated launcher.
+- Add deterministic Node tests for the helper and source-level integration guardrails.
+- Update Pi and setup docs.
+
+### Out of Scope
+
+- Reimplementing the 30-second autosync loop in TypeScript.
+- Changing `internal/cloud/autosync` tick interval or sync algorithm.
+- Changing server-side project enrollment, pause, or auth semantics.
+- Enabling Cloud sync without token+server configuration.
+- Changing raw `engram serve` / `engram mcp` CLI semantics outside Pi package launchers.
+
+## Behavioral Gate
+
+The Pi package should inject `ENGRAM_CLOUD_AUTOSYNC=1` only when all are true:
+
+1. `ENGRAM_CLOUD_AUTOSYNC` is unset/blank.
+2. `ENGRAM_CLOUD_TOKEN` is non-empty.
+3. A Cloud server is configured via either:
+   - `ENGRAM_CLOUD_SERVER`, or
+   - `${ENGRAM_DATA_DIR:-~/.engram}/cloud.json` with a non-empty `server_url`.
+
+Explicit `ENGRAM_CLOUD_AUTOSYNC=0`, `false`, or `1` must be preserved.
+
+## Success Criteria
+
+- Pi-launched `engram serve` starts core autosync automatically when Cloud token+server are configured.
+- Pi-configured `engram mcp --tools=agent` starts core autosync automatically under the same gate.
+- No Cloud token means no auto-enable.
+- Explicit autosync env remains authoritative.
+- Tests cover env-server, persisted-server, missing-token, and explicit override cases.
+- Docs tell users that the 30-second tick remains owned by Engram core.
+
+## Risks and Mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Surprise Cloud replication | Require token+server and preserve explicit overrides; core enrollment still gates projects. |
+| Plugin becomes thick | Only environment derivation lives in plugin; all sync behavior stays in Go core. |
+| MCP launcher drift | Keep `cli.js` and `mcp-template.json` aligned and add source tests. |
+| Partial cloud config causes noise | Do not inject autosync unless both token and server are present. |
+
+## Review Workload Forecast
+
+Estimated change: ~250-450 lines across helper, tests, launcher string, docs, and SDD artifacts. This is under the session budget of 800 changed lines and should fit a single PR.