@matuto-ai/pi-broker-connector 0.2.0 → 0.3.1

package/README.md

@@ -2,12 +2,12 @@
 
 A native Pi extension providing durable, session-bound messaging through the [Psst broker](https://github.com/matuto-ai/psst). Runs **inside the Pi process in your existing sandbox**. No host launcher, local model, provider subscription, or additional service is required by the connector.
 
-**Version 0.2.0:** automatic native delivery, private-file pairing, and transport-auth pause protection. Tested with the official Pi 1.4.0 SDK and a local fixture model; live authenticated user-sandbox acceptance remains a separate step.
+**Version 0.3.1:** native private setup, persistent installation selection and automatic reconnection of independent Pi sessions, retaining automatic native delivery and transport-auth pause protection. Tested with the official Pi 1.4.0 SDK and a local fixture model; live authenticated user-sandbox acceptance remains a separate step.
 
 ## Requirements
 
 - Node **24.19+ within major 24** and Pi **1.4.0** (the tested host version).
-- A reachable HTTPS Psst v1 broker, and an operator-issued **Pi-specific private connection bundle**. `/healthz` success alone does not enroll a client.
+- A reachable HTTPS Psst broker **0.3.0 with pairing enabled**, and one operator-approved **Pi-specific one-time pairing secret** per installation/scope. `/healthz` success or the broker URL alone does not authorize access. Existing connection bundles remain a compatibility option.
 - Writable local persistent storage, not a shared/NFS directory. Preserve it across sandbox recreation if you want to resume the same Pi session.
 
 The connector vendors the broker's dependency-free client; it does not fetch broker code at runtime. Pi supplies `typebox` and its host API as peer dependencies.
@@ -33,12 +33,40 @@ This uses the default branch. To pin a reviewed commit, append `@` and its exact
 ### From npm (only after publication)
 
 ```sh
-pi install npm:@matuto-ai/pi-broker-connector@0.2.0
+pi install npm:@matuto-ai/pi-broker-connector@0.3.1
 ```
 
 The command requires the version to be present on npm. If publication is still pending, use a reviewed checkout instead.
 
-### Connect — automatic native delivery, no restart
+### Connect once inside Pi — no bundle to copy
+
+After installing/updating, use `/reload` in the running Pi, then run
+`/psst-setup` **without arguments** inside Pi. It asks for the HTTPS broker
+URL, explicit authorization confirmation, then an operator-issued one-time secret
+in a focused **masked native field**. Never put that secret in the command, chat,
+a tool argument or ordinary Pi editor. The connector generates its own connection
+credential and keeps the generated files internal; you do not copy a bundle or
+ticket file into the sandbox. This requires a broker with scoped pairing enabled
+and an operator-approved grant for this installation/type/scope. A URL alone is
+not authorization. The initial operator grant and secure handoff remain necessary;
+this is not anonymous enrollment or a completed operator-provisioning UI.
+
+The nonsecret URL is remembered in Pi's agent directory. `PSST_BROKER_URL` is an
+optional explicit URL override; an origin mismatch fails instead of silently
+sending a saved credential elsewhere. After successful setup, new native sessions
+automatically use the saved credential, with independent session identities and
+mailboxes. No setup command, environment edit or re-enrollment is needed for each
+session sharing that persisted agent directory. Different project/profile mounts
+are different installations. Authentication failure or credential expiry never
+uses a leftover pairing secret to mint another identity; explicitly authorize a
+replacement when required. Repeating setup with a connected session asks for
+replacement confirmation and retains the old mailbox.
+
+The memory-input helper is pinned to merged source in [broker PR20](https://github.com/matuto-ai/psst/pull/20). This does not deploy or enable pairing on your broker. Native input is interactive-only;
+RPC/headless contexts cannot fall back to secret text in chat. `/psst-connect` with
+an existing private file remains a compatibility option, not the new setup route.
+
+### Compatibility: connect with an existing private file
 
 With this version loaded, run one command **in the current Pi session**:
 
@@ -46,23 +74,23 @@ With this version loaded, run one command **in the current Pi session**:
 /psst-connect /absolute/path/to/connection.json
 ```
 
-Use the existing bundle path; keep its `token` next to `connection.json`. After connecting, background transport receives messages and the extension automatically delivers them to this Pi session at an idle boundary. `broker_list_clients` lists authorized recipients; `broker_send` sends to an exact client ID. Do not copy the JSON alone. The command connects the current native session and saves **only the absolute path**, as one line in `~/.config/psst/pi-config-path`. It does not copy credentials or alter the process environment. `/reload` reads that TXT again. You can also create that TXT yourself (mode `0600`, directory `0700`) and use `/reload`.
+Use the existing bundle path; keep its `token` next to `connection.json`. After connecting, background transport receives messages and the extension automatically delivers them to this Pi session at an idle boundary. `broker_list_clients` lists authorized recipients; `broker_send` sends to an exact client ID. Do not copy the JSON alone. The command connects the current native session and saves a private installation selection in `${PI_CODING_AGENT_DIR:-~/.pi/agent}/psst/selection.sqlite`. This selection contains a path and nonsecret metadata, not the token. `/reload` reads it again. Old private `pi-config-path` TXT selections remain a read-only compatibility fallback when no new selection exists.
 
 Install or update **inside the same sandbox**, then use `/reload` in the running Pi:
 
 ```sh
-pi install npm:@matuto-ai/pi-broker-connector@0.2.0
+pi install npm:@matuto-ai/pi-broker-connector@0.3.1
 ```
 
 This installer command is not a second agent session. No sandbox recreation or Pi process restart is required. Version 0.1.1 does not have `/psst-connect`; 0.1.2 adds that command, while automatic delivery requires 0.2.0 or later.
 
 Keep `connection.json` and `token` private to the sandbox user (`0600`), directory `0700`. Never paste tokens into prompts, command arguments, Git, or shared config. Paths must refer to real files rather than symlinks. A `/tmp` bundle works for the current container but may disappear on container removal; remembering its path does not make the bundle persistent.
 
-Existing `PSST_CONFIG_FILE` and `PSST_CONFIG` configurations remain supported: on session start/reload, precedence is `PSST_CONFIG_FILE`, then `PSST_CONFIG`, then the saved TXT. `/psst-connect` explicitly selects the path for the current instance; it warns if inherited environment settings will take precedence on the next reload. `PSST_NAME` defaults to `Pi`; `PSST_STATE_DIR` defaults to `~/.local/state/psst/pi`. `/psst-status` displays status and the session's exact client ID. Repeated connect closes the previous runtime before reopening the same session inbox; invalid input leaves the current connection untouched. Connection failures retain the selected path for `/reload` retry.
+Existing `PSST_CONFIG_FILE` and `PSST_CONFIG` configurations remain supported: on session start/reload, precedence is `PSST_CONFIG_FILE`, then `PSST_CONFIG`, then the saved installation selection. `/psst-connect` explicitly selects the path for the current instance; it warns if inherited environment settings will take precedence on the next reload. `PSST_NAME` defaults to `Pi`; `PSST_STATE_DIR` defaults to `${PI_CODING_AGENT_DIR:-~/.pi/agent}/psst` for new installations. `/psst-status` displays status and the session's exact client ID. Repeated connect closes the previous runtime before reopening the same session inbox; invalid input leaves the current connection untouched. Failed new connections leave the previous saved selection unchanged. Successful explicit connection updates use compare-and-swap so concurrent changes are not silently overwritten.
 
-### Pair once with the same command
+### Compatibility: operator-provided pairing files
 
-**Broker dependency:** pairing requires the enrollment API from [Psst PR17](https://github.com/matuto-ai/psst/pull/17) and helper/operator tooling from [PR18](https://github.com/matuto-ai/psst/pull/18). This connector pins the reviewed helper at commit `3e908e79966d886a02d372c103e31dec6e900c1a`; the broker must run a version containing those changes. Vendoring the helper does not deploy or enable the broker endpoint. Legacy bundles remain usable without that endpoint.
+**Broker dependency:** pairing requires the opt-in enrollment API included in broker 0.3.0. This connector vendors the helper at commit `4a9d604e1107a92c94f8b8a2f0e1cb2d1e2ecc39`; the helper runs locally inside Pi, not on the server. Vendoring the helper does not deploy or enable the broker endpoint. Legacy bundles remain usable without that endpoint.
 
 When an operator provides a private **pairing file**, use its path instead of an existing bundle:
 
@@ -72,7 +100,7 @@ When an operator provides a private **pairing file**, use its path instead of an
 
 The extension recognizes `psst-pairing-v1`, generates a unique installation credential locally, saves retry state before contacting `/v1/enrollments`, and remembers the resulting ordinary connection bundle. The pairing secret is read only from the private file: never paste it into a command, prompt, URL, or model tool. No environment variable, new agent, or sandbox restart is needed. Existing connection bundles still work unchanged.
 
-Enrollment files live under the configured state root's `installations/` directory with private permissions. Uncertain responses reuse the same durable enrollment request and token when you repeat the command; they do not silently allocate another identity. An expired/revoked credential requires an explicitly supplied new pairing file, not automatic credential minting. Pairing uses normal verified HTTPS; private-CA override is not currently supported by the shared pairing helper (legacy bundles still support their existing CA option).
+New enrollment files live privately under the native agent directory's `psst/installation-credentials/`. Explicit `PSST_STATE_DIR` uses its `installations/` directory. Existing legacy file-pairing attempts retain their original retry directory. Uncertain responses reuse the same durable enrollment request and token when you repeat the command; they do not silently allocate another identity. An expired/revoked credential requires a newly approved secret through `/psst-setup` (or a new compatibility pairing file), never automatic credential minting. Pairing uses normal verified HTTPS; private-CA override is not currently supported by the shared pairing helper (legacy bundles still support their existing CA option).
 
 Each installation credential is separate from each native Pi session identity. The private enrollment receipt is verified against the broker, client type and token before it can bind local state. Reload of the same native session and enrollment resumes its mailbox; a fresh pairing credential creates a separate mailbox and retains old state rather than adopting it. Legacy bundles without an enrollment receipt retain their original session binding. Pairing completion after a session switch/shutdown cannot attach to the departed session.
 
@@ -132,7 +160,7 @@ Broker `delivered` means committed to the receiver's local durable inbox. `broke
 
 Each native Pi session has its own durable identity, bound to the endpoint and Pi session ID. `/new` gets a separate mailbox. `/reload`, process restart, or `/resume` of the same Pi session can reconnect its identity; no old inbox is silently adopted by another session. Shutdown stops background tasks and releases the local database lock. It leaves the broker lease to expire rather than permanently closing the identity, so reload/resume remains possible. Concurrent ownership of the same local inbox fails closed.
 
-No settings, credentials, enrollment, provider routing, Nginx rules, or host installations are changed by installing this package. Without a bundle the extension stays disconnected. A failed startup is surfaced as a sanitized diagnostic; fix the bundle/network/permissions and `/reload`.
+No settings, credentials, enrollment, provider routing, Nginx rules, or host installations are changed by installing this package. Without a selected credential the extension stays disconnected until native setup. A failed startup is surfaced as a sanitized diagnostic; check network/permissions and use `/reload` to retry the saved credential. Do not re-pair merely to hide an uncertain transport result.
 
 ## Development and verification
 
@@ -149,7 +177,7 @@ Tests cover private bundle validation, exact session isolation, duplicate owners
 
 ## Publishing
 
-This release uses package version `0.2.0` and matching GitHub release tag `v0.2.0`. The release workflow publishes the package only after its checks pass.
+This release uses package version `0.3.1` and matching GitHub release tag `v0.3.1`. The release workflow publishes the package only after its checks pass.
 
 The release workflow follows the existing Pi plugin convention: a published GitHub release triggers checks and npm publishing. It requires a `v<package.version>` tag and runs the native host gate before publishing. Nothing is published by CI on pull requests or ordinary pushes.
 
@@ -165,3 +193,54 @@ pi remove /absolute/path/to/pi-broker-connector
 ```
 
 Restart/reload Pi. State and private enrollment files are deliberately retained for recovery; remove them only when you intend to abandon that mailbox.
+
+## Persistent storage across native sessions
+
+New installations keep enrollment in `installation-credentials/` and independent
+session journals under
+`PI_CODING_AGENT_DIR/psst` (default `~/.pi/agent/psst`). The remembered selection
+is one private SQLite record containing the connection path, broker origin and
+revision. Explicit setup commits it only after successful current-session connect;
+compare-and-swap prevents concurrent setups overwriting a newer selection. This follows the existing
+Pi agent-directory mount in a sandbox; different projects/profiles with different
+agent directories remain separate installations. No host or launcher change is made.
+An explicit `PSST_STATE_DIR` continues to select the inbox/enrollment root.
+
+Existing `~/.local/state/psst/pi` is deliberately preserved, not silently copied
+or moved: old running plugins do not participate in a new migration lock. A
+legacy-storage warning identifies this compatibility mode for inboxes; new
+native setup credentials still go to the persisted agent directory, not that
+legacy inbox root (unless PSST_STATE_DIR explicitly overrides storage). It does **not** mean
+the old path has become durable across sandbox recreation. The old
+`~/.config/psst/pi-config-path` and native `pi-config-path` TXT are still read when
+no SQLite selection exists; writing a new selection leaves those files untouched.
+A native selection wins once explicitly saved, but invalid native selections
+never fall back to old credentials. If both legacy and native roots contain state,
+startup fails with `storage_migration_required` rather than choosing one history.
+Selection database/journal and known private atomic-selection temporaries are
+metadata, not another inbox history; an empty legacy root is conservatively retained.
+An explicit state override can choose the intended existing root. Coordinated
+offline migration remains an operator recovery task; preserve all old state.
+
+Each native session has its own identity, inbox, outgoing retry ledger and owner
+lock. Reopening the same session retains those records; a different session never
+adopts them. This storage change does not authorize first enrollment, mint another
+credential on startup, or remove the current pairing-file onboarding requirement.
+
+Developer-only native setup proof (disposable CA/grants; Python3/PTY and OpenSSL):
+
+```sh
+PI_TEST_INSTALL=/path/to/official-pi-1.4.0 \
+PSST_TEST_BROKER_ROOT=/path/to/reviewed-psst \
+node scripts/native-setup-tls.probe.mjs
+```
+
+This opens the actual Pi UI, enters only a synthetic grant through the masked
+component, connects to a real fixture HTTPS broker, and recreates HOME while
+preserving the agent directory. It asserts one credential and two distinct
+sessions without a second setup. No model turn or authenticated user-sandbox
+acceptance is claimed. The broker checkout must include its enrollment TLS fixture.
+
+### Masked-field keyboard regression tests
+
+`npm test` requires Python 3 on Linux for the real POSIX PTY keyboard tests. They use only synthetic input and the pinned official Pi TUI 1.4.0 development dependency. Runtime imports resolve through Pi’s native extension loader; no terminal keyboard mode is changed by the connector itself. Legacy text/paste and Kitty printable input are supported, while control keys use the public host decoder. This does not claim complete xterm `modifyOtherKeys` printable-key support.

package/package.json

@@ -1,15 +1,50 @@
 {
   "name": "@matuto-ai/pi-broker-connector",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Session-bound Psst broker messaging tools for Pi",
   "type": "module",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/matuto-ai/pi-broker-connector.git" },
-  "engines": { "node": ">=24.19.0 <25" },
-  "keywords": ["pi-package", "pi", "psst", "broker"],
-  "files": ["extensions/", "src/", "vendor/", "README.md", "LICENSE"],
-  "pi": { "extensions": ["./extensions/psst.ts"] },
-  "peerDependencies": { "@earendil-works/pi-coding-agent": "*", "typebox": "*" },
-  "scripts": { "test": "node --test test/*.test.mjs", "check": "node scripts/check.mjs", "test:host": "node --test test/native-host.probe.mjs", "prepack": "npm run check && npm test" },
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matuto-ai/pi-broker-connector.git"
+  },
+  "engines": {
+    "node": ">=24.19.0 <25"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "psst",
+    "broker"
+  ],
+  "files": [
+    "extensions/",
+    "src/",
+    "vendor/",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/psst.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*",
+    "@earendil-works/pi-tui": "^1.4.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "node scripts/check.mjs",
+    "test:host": "node --test test/native-host.probe.mjs",
+    "prepack": "npm run check && npm test"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-tui": "1.4.0"
+  }
 }

package/src/config-path.mjs

@@ -1,43 +1,29 @@
-import { constants, openSync, closeSync, fstatSync, readFileSync, realpathSync, mkdirSync, lstatSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { isAbsolute, join } from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { LocalError } from '../vendor/broker/reference/errors.mjs';
-
-export function validateConfigPath(value) {
-  if (typeof value !== 'string' || !isAbsolute(value) || value.length > 4096 || /[\x00-\x1f\x7f]/.test(value)) throw new LocalError('invalid_configuration');
-  return value;
-}
-
-// This TXT contains a path only, never the bundle or token.
-export function createConfigPathStore(home = homedir()) {
-  const directory = join(home, '.config', 'psst');
-  const file = join(directory, 'pi-config-path');
-  return {
-    read() {
-      let fd;
-      try {
-        try { lstatSync(file); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
-        if (realpathSync(file) !== file) throw new Error();
-        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
-        const stat = fstatSync(fd);
-        if (!stat.isFile() || stat.size > 4097 || (stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid())) throw new Error();
-        return validateConfigPath(readFileSync(fd, 'utf8').replace(/\n$/, ''));
-      } catch { throw new LocalError('invalid_configuration'); }
-      finally { if (fd !== undefined) closeSync(fd); }
-    },
-    write(path) {
-      validateConfigPath(path);
-      let temporary;
-      try {
-        mkdirSync(directory, { recursive: true, mode: 0o700 });
-        const stat = lstatSync(directory);
-        if (realpathSync(directory) !== directory || !stat.isDirectory() || (stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid())) throw new Error();
-        temporary = join(directory, `.pi-config-path-${randomUUID()}`);
-        writeFileSync(temporary, `${path}\n`, { mode: 0o600, flag: 'wx' });
-        renameSync(temporary, file);
-      } catch { throw new LocalError('invalid_configuration'); }
-      finally { if (temporary) { try { unlinkSync(temporary); } catch {} } }
-    },
-  };
+import {constants,openSync,closeSync,fstatSync,readFileSync,realpathSync,mkdirSync,lstatSync,chmodSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {isAbsolute,join} from 'node:path';
+import {randomUUID,createHash} from 'node:crypto';
+import {DatabaseSync} from 'node:sqlite';
+import {storageLayout} from './storage.mjs';
+import {LocalError} from '../vendor/broker/reference/errors.mjs';
+export function validateConfigPath(value){if(typeof value!=='string'||!isAbsolute(value)||value.length>4096||/[\x00-\x1f\x7f]/.test(value))throw new LocalError('invalid_configuration');return value;}
+function privateFile(file){if(realpathSync(file)!==file)throw Error();const fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW);try{const s=fstatSync(fd);if(!s.isFile()||(s.mode&0o077)||(process.getuid&&s.uid!==process.getuid()))throw Error();}finally{closeSync(fd);}}
+export function createConfigPathStore(home=homedir(),env=process.env){
+ const {selectionDirectory:directory,legacySelection}=storageLayout(env,home),file=join(directory,'selection.sqlite'),previous=join(directory,'pi-config-path');
+ function legacy(){for(const candidate of [previous,legacySelection]){try{lstatSync(candidate);}catch(e){if(e.code==='ENOENT')continue;throw e;}privateFile(candidate);if(lstatSync(candidate).size>4097)throw Error();const path=validateConfigPath(readFileSync(candidate,'utf8').replace(/\n$/,''));return{connectionFile:path,brokerUrl:null,revision:'legacy-'+createHash('sha256').update(path).digest('hex')};}return{connectionFile:null,brokerUrl:null,revision:'empty'};}
+ function readDatabase(db){const row=db.prepare('SELECT value FROM selection WHERE id=1').get();if(!row)return legacy();const record=JSON.parse(row.value);validateConfigPath(record.connectionFile);if(typeof record.revision!=='string'||!/^[-a-z0-9]+$/.test(record.revision)||!(record.brokerUrl===null||typeof record.brokerUrl==='string'))throw Error();return record;}
+ function read(){let db;try{try{lstatSync(file);}catch(e){if(e.code==='ENOENT')return legacy();throw e;}privateFile(file);db=new DatabaseSync(file,{readOnly:true});return readDatabase(db);}catch{throw new LocalError('invalid_configuration');}finally{try{db?.close();}catch{}}}
+ return{
+  read(){return read().connectionFile;},snapshot:read,
+  write(path,brokerUrl=null,expectedRevision){
+   validateConfigPath(path);let db;
+   try{
+    mkdirSync(directory,{recursive:true,mode:0o700});const stat=lstatSync(directory);if(realpathSync(directory)!==directory||!stat.isDirectory()||(stat.mode&0o077)||(process.getuid&&stat.uid!==process.getuid()))throw Error();
+    try{privateFile(file);}catch(e){if(e.code!=='ENOENT')throw e;}
+    const fd=openSync(file,constants.O_CREAT|constants.O_WRONLY|constants.O_NOFOLLOW,0o600);closeSync(fd);chmodSync(file,0o600);
+    db=new DatabaseSync(file);db.exec('PRAGMA busy_timeout=2000; PRAGMA synchronous=FULL; BEGIN IMMEDIATE; CREATE TABLE IF NOT EXISTS selection(id INTEGER PRIMARY KEY CHECK(id=1),value TEXT NOT NULL);');
+    const current=readDatabase(db);if(expectedRevision!==undefined&&current.revision!==expectedRevision){db.exec('ROLLBACK');return false;}
+    const value=JSON.stringify({connectionFile:path,brokerUrl,revision:randomUUID()});db.prepare('INSERT INTO selection(id,value) VALUES(1,?) ON CONFLICT(id) DO UPDATE SET value=excluded.value').run(value);db.exec('COMMIT');return true;
+   }catch{throw new LocalError('invalid_configuration');}finally{try{db?.close();}catch{}}
+  },
+ };
 }

package/src/config.mjs

@@ -1,7 +1,7 @@
 import { readEnrollmentReceipt } from '../vendor/broker/reference/enrollment.mjs';
 import { openSync, closeSync, fstatSync, readFileSync, realpathSync, lstatSync } from 'node:fs';
 import { isAbsolute, dirname, resolve, basename } from 'node:path';
-import { homedir } from 'node:os';
+import { storageLayout } from './storage.mjs';
 import { constants } from 'node:fs';
 import { LocalError } from '../vendor/broker/reference/errors.mjs';
 
@@ -39,9 +39,11 @@ export function readConfig(env = process.env, explicitPath) {
     try { credentialId = readEnrollmentReceipt({connectionFile:path,clientType:'pi'}).credentialId; }
     catch (error) { throw new LocalError(error?.code === 'credential_expired' ? 'credential_expired' : 'invalid_configuration'); }
   }
+  const configuredBroker=env.PSST_BROKER_URL;
+  if(configuredBroker){let expected;try{expected=new URL(configuredBroker);}catch{throw new LocalError('invalid_configuration');}if(expected.protocol!=='https:'||expected.username||expected.password||expected.search||expected.hash||expected.pathname!=='/'||expected.origin!==url.origin)throw new LocalError('broker_origin_mismatch');}
   const name = env.PSST_NAME || 'Pi';
   if (name.length > 128 || /[\x00-\x1f\x7f]/.test(name)) throw new LocalError('invalid_configuration');
   return { url: url.href, ...(credentialId ? {credentialId} : {}), tokenFile: resolve(dirname(path), raw.token_file),
     ...(raw.ca_file ? { caFile: resolve(dirname(path), raw.ca_file) } : {}),
-    stateDirectory: resolve(env.PSST_STATE_DIR || resolve(homedir(), '.local/state/psst/pi')), name };
+    ...storageLayout(env), name };
 }

package/src/connect-config.mjs

@@ -1,6 +1,8 @@
 import { LocalError } from '../vendor/broker/reference/errors.mjs';
-import { homedir } from 'node:os';
+import { storageLayout } from './storage.mjs';
 import { resolve, join } from 'node:path';
+import {createHash} from 'node:crypto';
+import {lstatSync} from 'node:fs';
 import { readPrivateJson } from './config.mjs';
 import { validateConfigPath } from './config-path.mjs';
 
@@ -12,9 +14,12 @@ export async function resolveConnectionFile(file, { env = process.env,
   validateConfigPath(file);
   const raw = readPrivateJson(file);
   if (raw.format !== 'psst-pairing-v1') return file;
-  const root = resolve(env.PSST_STATE_DIR || resolve(homedir(), '.local/state/psst/pi'));
+  const layout=storageLayout(env);let directory=layout.installationDirectory;
+  // Only an already-persisted legacy attempt keeps its original retry identity.
+  const previous=join(layout.stateDirectory,'installations');
+  if(previous!==directory&&typeof raw.pairing_secret==='string'){try{lstatSync(join(previous,'enrollments',createHash('sha256').update(raw.pairing_secret).digest('hex'),'attempt.json'));directory=previous;}catch(e){if(e.code!=='ENOENT')throw new LocalError('invalid_configuration');}}
   try {
-    const result = await pairingConnector({pairingFile:file,directory:join(root,'installations'),clientType:'pi'});
+    const result = await pairingConnector({pairingFile:file,directory,clientType:'pi'});
     return validateConfigPath(result.connectionFile);
   } catch (error) {
     const codes = ['credential_expired','unauthenticated','forbidden','idempotency_conflict','rate_limited','enrollment_busy','enrollment_capacity','enrollment_transport_error','invalid_pairing_file','invalid_enrollment_receipt'];

package/src/extension.mjs

@@ -1,3 +1,4 @@
+import {nativeSetup} from './native-setup.mjs';
 import { resolveConnectionFile } from './connect-config.mjs';
 import { NativeDelivery } from './native-delivery.mjs';
 import { createConfigPathStore, validateConfigPath } from './config-path.mjs';
@@ -7,7 +8,7 @@ import { createCooperativeInbox } from './cooperative-inbox.mjs';
 import { createTools, invokeTool } from '../vendor/broker/reference/tools.mjs';
 import { LocalError, safeError } from '../vendor/broker/reference/errors.mjs';
 
-export function installExtension(pi, Type, { configReader = readConfig, pathStore = createConfigPathStore(), env = process.env, connectionResolver = resolveConnectionFile, createSession = options => new PiBrokerSession(options) } = {}) {
+export function installExtension(pi, Type, { configReader = readConfig, env = process.env, pathStore = createConfigPathStore(undefined, env), connectionResolver = resolveConnectionFile, createSession = options => new PiBrokerSession(options), setupConnector = options => import('../vendor/broker/reference/enrollment.mjs').then(m=>m.connectPairingSecret(options)), setupUI = nativeSetup } = {}) {
   let owner = null, facade = null, delivery = null, ready = false, status = 'not_configured';
   let generation = 0, operations = Promise.resolve();
   const schedule = operation => {
@@ -30,6 +31,8 @@ export function installExtension(pi, Type, { configReader = readConfig, pathStor
     try {
       const config = selectedConfig || configReader(env, env.PSST_CONFIG_FILE || env.PSST_CONFIG || pathStore.read());
       if (!config) { status = 'not_configured'; setStatus(ctx); return; }
+      if(!selectedConfig&&!env.PSST_CONFIG_FILE&&!env.PSST_CONFIG){const saved=pathStore.snapshot?.();if(saved?.brokerUrl&&new URL(config.url).origin!==saved.brokerUrl)throw new LocalError('broker_origin_mismatch');}
+      if (config.legacyStorage) notify(ctx, 'Psst is preserving existing legacy inbox storage. It has not been moved into Pi persistent storage; keep that directory until a coordinated offline migration.', 'warning');
       const hostSessionId = ctx.sessionManager.getSessionId();
       const current = createSession({ config, hostSessionId,
         currentSessionId: () => ctx.sessionManager.getSessionId(),
@@ -51,23 +54,45 @@ export function installExtension(pi, Type, { configReader = readConfig, pathStor
       delivery?.stop(); delivery = null;
       const prior = owner; owner = null; facade = null; ready = false;
       if (prior) await prior.close();
-      setStatus(ctx); notify(ctx, `Psst could not connect (${status}). Check the private bundle and use /reload to retry.`, 'warning');
+      setStatus(ctx); notify(ctx, `Psst could not connect (${status}). Use /psst-status and /reload to retry the saved credential; authorize replacement setup only when needed.`, 'warning');
     }
   };
   pi.on('session_start', async (_event, ctx) => schedule(epoch => connect(ctx, epoch)));
   pi.on('session_shutdown', async () => schedule(async () => { await stop(); status = 'stopped'; }));
+  pi.registerCommand('psst-setup', {
+    description: 'Configure broker URL and authorize this installation using native private input',
+    handler: async (args, ctx) => {
+      if(args.trim()){notify(ctx,'Use /psst-setup without arguments. Never put a secret in a command.','warning');return;}
+      try {
+        const initial=generation,nativeId=ctx.sessionManager.getSessionId(),revision=pathStore.snapshot?.().revision;
+        if(ready&&!await ctx.ui.confirm('Replace Psst installation credential?', 'This creates a new credential/mailbox partition. Existing pending messages remain in their old inbox. Continue only with an explicitly approved new pairing secret.'))return;
+        if(initial!==generation||ctx.sessionManager.getSessionId()!==nativeId)throw new LocalError('session_mismatch');
+        const selected=await setupUI(ctx,{env,pairingConnector:setupConnector,stillCurrent:()=>initial===generation&&ctx.sessionManager.getSessionId()===nativeId});
+        if(!selected)return;
+        const path=selected.connectionFile;
+        if(initial!==generation||ctx.sessionManager.getSessionId()!==nativeId)throw new LocalError('session_mismatch');
+        const config=configReader(env,path);
+        if(new URL(config.url).origin!==selected.brokerUrl)throw new LocalError('broker_origin_mismatch');
+        const task=schedule(epoch=>connect(ctx,epoch,config,true)),expected=generation;await task;
+        if(!ready||generation!==expected||ctx.sessionManager.getSessionId()!==nativeId)return;
+        const saved=pathStore.write(path,selected.brokerUrl,revision);
+        notify(ctx,saved===false?'Psst connected for this session. Another setup changed the saved selection; future-session selection was not overwritten.':'Psst installation connected. Future native sessions use the saved credential.');
+      } catch {notify(ctx,'Psst setup did not complete. No secret was displayed; keep local retry state and retry explicitly.','warning');}
+    },
+  });
   pi.registerCommand('psst-connect', {
     description: 'Connect this Pi session using an absolute connection.json path; remember only the path',
     handler: async (args, ctx) => {
       try {
-        const epochBeforePairing = generation, sessionBeforePairing = ctx.sessionManager.getSessionId();
+        const epochBeforePairing = generation, sessionBeforePairing = ctx.sessionManager.getSessionId(),revision=pathStore.snapshot?.().revision;
         const path = await connectionResolver(validateConfigPath(args.trim()), {env});
         if (epochBeforePairing !== generation || ctx.sessionManager.getSessionId() !== sessionBeforePairing) throw new LocalError('session_mismatch');
         const config = configReader(env, path);
-        pathStore.write(path);
-        await schedule(epoch => connect(ctx, epoch, config, true));
+        const task=schedule(epoch => connect(ctx, epoch, config, true)),expected=generation;await task;
+        if(!ready||generation!==expected||ctx.sessionManager.getSessionId()!==sessionBeforePairing)return;
+        const saved=pathStore.write(path,new URL(config.url).origin,revision);
         if (env.PSST_CONFIG_FILE || env.PSST_CONFIG) notify(ctx, 'An existing PSST_CONFIG_FILE/PSST_CONFIG environment setting still takes precedence after /reload.', 'warning');
-        notify(ctx, ready ? 'Psst connected. Configuration path saved; no restart needed.' : 'Psst path saved. Check /psst-status; /reload retries the connection.');
+        notify(ctx,saved===false?'Psst connected for this session. Another setup changed the saved selection; future-session selection was not overwritten.':'Psst connected. Selection saved; no restart needed.');
       } catch (error) { notify(ctx, `Psst could not save configuration (${safeError(error).error?.code || 'invalid_configuration'}). Use /psst-connect /absolute/path/connection.json.`, 'warning'); }
     },
   });
@@ -88,7 +113,7 @@ export function installExtension(pi, Type, { configReader = readConfig, pathStor
   pi.registerCommand('psst-status', {
     description: 'Show this Pi session’s Psst broker status and client ID',
     handler: async (_args, ctx) => {
-      notify(ctx, ready && owner ? `Psst ${status}; client ID ${owner.inbox.identity.client_id}; inbox ${owner.inbox.stats().pending_count} pending. Delivery mode: ${delivery?.mode}. Native acceptance is not model read or action success.` : `Psst ${status}. Use /psst-connect /absolute/path/connection.json. No restart required.`);
+      notify(ctx, ready && owner ? `Psst ${status}; client ID ${owner.inbox.identity.client_id}; inbox ${owner.inbox.stats().pending_count} pending. Delivery mode: ${delivery?.mode}. Native acceptance is not model read or action success.` : `Psst ${status}. Use /psst-setup for native first-time setup. No restart required.`);
     },
   });
   const empty = Type.Object({}, { additionalProperties: false });

package/src/native-setup.mjs

@@ -0,0 +1,31 @@
+import {createConfigPathStore} from './config-path.mjs';
+import {join} from 'node:path';
+import {storageLayout} from './storage.mjs';
+import {LocalError} from '../vendor/broker/reference/errors.mjs';
+import {promptPairingSecret} from './private-input.mjs';
+export function brokerOrigin(value) {
+ let u;try{u=new URL(value);}catch{throw new LocalError('invalid_configuration');}
+ if(typeof value!=='string'||/[\u0000-\u0020\u007f]/.test(value)||u.protocol!=='https:'||u.username||u.password||u.pathname!=='/'||u.search||u.hash)throw new LocalError('invalid_configuration');
+ return u.origin;
+}
+export function nativeBrokerSettings(env=process.env) {
+ const store=createConfigPathStore(undefined,env);
+ return {read(){const url=env.PSST_BROKER_URL||store.snapshot().brokerUrl;return url?brokerOrigin(url):null;}};
+}
+// Called only from an explicit native command, never session_start/auth recovery.
+export async function nativeSetup(ctx,{env=process.env,settings=nativeBrokerSettings(env),privateInput=promptPairingSecret,pairingConnector,stillCurrent=()=>true}={}) {
+ if(!ctx?.hasUI)throw new LocalError('native_private_input_unavailable');
+ const known=settings.read();
+ const entered=await ctx.ui.input('Psst broker HTTPS URL',known||'https://');
+ if(entered===undefined||!stillCurrent())return null;
+ const brokerUrl=brokerOrigin(entered);
+ if(env.PSST_BROKER_URL&&brokerOrigin(env.PSST_BROKER_URL)!==brokerUrl)throw new LocalError('broker_origin_mismatch');
+ if(!await ctx.ui.confirm('Psst first-time authorization',`Connect this installation to ${brokerUrl}? The next field accepts a one-time secret privately; it is not a message.`)||!stillCurrent())return null;
+ let pairingSecret=await privateInput(ctx);
+ if(pairingSecret===undefined||!stillCurrent())return null;
+ try {
+  const result=await pairingConnector({brokerUrl,pairingSecret,directory:storageLayout(env).installationDirectory,clientType:'pi'});
+  if(!stillCurrent())throw new LocalError('session_mismatch');
+  return {connectionFile:result.connectionFile,brokerUrl};
+ } finally {pairingSecret=undefined;}
+}

package/src/private-input.mjs

@@ -0,0 +1,37 @@
+import { matchesKey, isKeyRelease, decodeKittyPrintable } from '@earendil-works/pi-tui';
+import { LocalError } from '../vendor/broker/reference/errors.mjs';
+
+// A focused native component: the value never enters Pi's editor or a message.
+// Use public host decoders for control keys and Kitty printable input; legacy text/paste stays masked.
+export function maskedPairingComponent({done,requestRender}) {
+  let value='',closed=false,pasting=false,paste='',invalidPaste=false,hint=false;
+  const finish=result=>{if(closed)return;closed=true;value='';paste='';done(result);};
+  const append=data=>{if(/^[A-Za-z0-9_-]+$/.test(data)&&value.length+data.length<=43){value+=data;hint=false;}};
+  return {
+    render(width){return ['Psst: enter the one-time pairing secret (hidden)', '*'.repeat(value.length), hint?'Paste the complete 43-character pairing secret.':'Enter: connect   Esc or Ctrl+C: cancel'].map(line=>line.slice(0,Math.max(0,width)));},
+    invalidate(){},
+    handleInput(data){
+      if(closed||typeof data!=='string'||isKeyRelease(data))return;
+      if(matchesKey(data,'escape')||matchesKey(data,'ctrl+c')){finish(undefined);return;}
+      if(matchesKey(data,'enter')){if(!pasting){if(/^[A-Za-z0-9_-]{43}$/.test(value))finish(value);else{hint=true;requestRender();}}return;}
+      if(!pasting&&matchesKey(data,'backspace')){value=value.slice(0,-1);hint=false;requestRender();return;}
+      // Pi normally wraps a whole paste; tolerate marker/body/end delivered separately.
+      if(data.startsWith('\x1b[200~')){pasting=true;paste='';invalidPaste=false;data=data.slice(6);}
+      if(pasting){
+        const end=data.indexOf('\x1b[201~');
+        const body=end<0?data:data.slice(0,end);
+        if(!/^[A-Za-z0-9_-]*$/.test(body)||paste.length+body.length>43)invalidPaste=true;
+        if(!invalidPaste)paste+=body;
+        if(end>=0){if(data.slice(end+6))invalidPaste=true;if(!invalidPaste)append(paste);else hint=true;paste='';pasting=false;invalidPaste=false;}
+      }else{
+        append(decodeKittyPrintable(data)??data);
+      }
+      requestRender();
+    },
+    dispose(){closed=true;value='';paste='';},
+  };
+}
+export async function promptPairingSecret(ctx) {
+  if(!ctx?.hasUI||typeof ctx.ui?.custom!=='function')throw new LocalError('native_private_input_unavailable');
+  return ctx.ui.custom((tui,_theme,_keys,done)=>maskedPairingComponent({done,requestRender:()=>tui.requestRender()}));
+}

package/src/storage.mjs

@@ -0,0 +1,35 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { lstatSync, readdirSync, realpathSync } from 'node:fs';
+import { LocalError } from '../vendor/broker/reference/errors.mjs';
+
+const present = path => { try { lstatSync(path); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw new LocalError('invalid_configuration'); } };
+
+// Match Pi's documented agent-directory scope. Never move a live legacy inbox:
+// old plugin processes do not participate in a new migration lock.
+export function storageLayout(env = process.env, home = homedir()) {
+  const configured = env.PI_CODING_AGENT_DIR;
+  const agent = configured ? resolve(configured === '~' ? home : configured.startsWith('~/') ? join(home, configured.slice(2)) : configured) : join(home, '.pi', 'agent');
+  const nativeRoot = join(agent, 'psst');
+  const legacyRoot = join(home, '.local', 'state', 'psst', 'pi');
+  const legacySelection = join(home, '.config', 'psst', 'pi-config-path');
+  const legacy = !env.PSST_STATE_DIR && present(legacyRoot);
+  if (legacy && present(nativeRoot)) {
+    const stat=lstatSync(nativeRoot);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || realpathSync(nativeRoot)!==nativeRoot || (stat.mode&0o077) || (process.getuid && stat.uid!==process.getuid())) throw new LocalError('invalid_configuration');
+    // A selection pointer alone is not a second mailbox. Any other content may
+    // be enrollment/inbox state: never choose one history and hide the other.
+    if (readdirSync(nativeRoot).some(name => {
+      if (name === 'pi-config-path' || name === 'selection.sqlite' || name === 'selection.sqlite-journal') return false;
+      if(name === 'installation-credentials'){const s=lstatSync(join(nativeRoot,name));if(!s.isDirectory()||s.isSymbolicLink()||realpathSync(join(nativeRoot,name))!==join(nativeRoot,name)||(s.mode&0o077)||(process.getuid&&s.uid!==process.getuid()))throw new LocalError('invalid_configuration');return false;}
+      if (/^\.(?:pi-config-path-|broker-)[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(name)) {
+        try { const temp=lstatSync(join(nativeRoot,name)); return !temp.isFile() || temp.isSymbolicLink() || Boolean(temp.mode&0o077) || Boolean(process.getuid && temp.uid!==process.getuid()); }
+        catch (error) { if (error.code==='ENOENT') return false; throw new LocalError('invalid_configuration'); }
+      }
+      return true;
+    })) throw new LocalError('storage_migration_required');
+  }
+  const stateDirectory = resolve(env.PSST_STATE_DIR || (legacy ? legacyRoot : nativeRoot));
+  const installationDirectory=env.PSST_STATE_DIR?join(stateDirectory,'installations'):join(nativeRoot,'installation-credentials');
+  return { stateDirectory, installationDirectory, selectionDirectory: nativeRoot, legacySelection, legacyStorage: legacy };
+}

package/vendor/broker/ENROLLMENT_UPSTREAM.json

@@ -1,7 +1,7 @@
 {
   "repository": "https://github.com/matuto-ai/psst",
-  "commit": "3e908e79966d886a02d372c103e31dec6e900c1a",
+  "commit": "4a9d604e1107a92c94f8b8a2f0e1cb2d1e2ecc39",
   "path": "reference/enrollment.mjs",
-  "git_blob": "c91341681f21f73ee6d5db31bbb5d976f81d6b37",
-  "sha256": "afeab00d7c2d6768d3537bd7c350e249768897bf81eff9b4ae9796f7c3f9dbe9"
+  "git_blob": "8a9ec6c2747ec9d25765a5ed506a4e43ef3cdd8e",
+  "sha256": "72318244ac7b799570704f59e167a0684b6c567cb6cda90303f32d7056ee0a06"
 }

package/vendor/broker/reference/enrollment.mjs

@@ -56,13 +56,22 @@ function post(url, secret, body) {
   });
 }
 /** Explicit connect only. The optional transport is a test seam, never a user configuration field. */
-export async function connectPairingFile({pairingFile,directory,clientType,brokerUrl}, {transport = post} = {}) {
+export function connectPairingFile(options, testOptions) {
+  return connectPairing({...options, pairingSecret:undefined}, testOptions);
+}
+/** Only a native private-input callback may supply this secret, never a model tool argument. */
+export function connectPairingSecret({brokerUrl,pairingSecret,directory,clientType}, testOptions) {
+  return connectPairing({brokerUrl,pairingSecret,directory,clientType}, testOptions);
+}
+async function connectPairing({pairingFile,pairingSecret,directory,clientType,brokerUrl}, {transport = post} = {}) {
   let lock, lockPath;
   try {
     if (!TYPES.includes(clientType)) fail('invalid_client_type');
-    const pair = JSON.parse(privateRead(pairingFile));
+    const pair = pairingFile === undefined
+      ? {format:'psst-pairing-v1',client_type:clientType,pairing_secret:pairingSecret,broker_url:brokerUrl}
+      : JSON.parse(privateRead(pairingFile));
     if (!pair || pair.format !== 'psst-pairing-v1' || pair.client_type !== clientType || typeof pair.pairing_secret !== 'string'
-      || !/^[A-Za-z0-9_-]{43}$/.test(pair.pairing_secret) || !Number.isFinite(Date.parse(pair.expires_at))) fail('invalid_pairing_file');
+      || !/^[A-Za-z0-9_-]{43}$/.test(pair.pairing_secret) || (pairingFile !== undefined && !Number.isFinite(Date.parse(pair.expires_at)))) fail('invalid_pairing_file');
     const broker = origin(pair.broker_url);
     if (brokerUrl !== undefined && origin(brokerUrl) !== broker) fail('broker_origin_mismatch');
     privateDir(directory);