@dp-pcs/ogp 0.4.2 → 0.4.4

package/README.md

@@ -44,7 +44,18 @@ After installation, install the OGP skills for Claude Code:
 ogp-install-skills
 ```
 
-This auto-discovers and installs all OGP skills from the `skills/` directory.
+This auto-discovers and installs all OGP skills from the `skills/` directory. The installer now replaces each installed skill directory wholesale on upgrade so stale files from older package versions do not survive.
+
+Verify the installed copies after an upgrade:
+
+```bash
+rg -n '^version:' ~/.openclaw/skills/ogp*/SKILL.md ~/.claude/skills/ogp*/SKILL.md 2>/dev/null
+```
+
+For the current `0.4.2` release line, the changed skills should report:
+- `ogp` `2.6.0`
+- `ogp-agent-comms` `0.6.0`
+- `ogp-project` `2.2.0`
 
 ### Multi-Framework Support
 
@@ -251,7 +262,7 @@ After installation, restart your shell or run `source ~/.bashrc` (bash) or `sour
 
 | Command | Description |
 |---------|-------------|
-| `ogp expose` | Launch guided tunnel setup wizard (coming soon) or start cloudflared tunnel in foreground |
+| `ogp expose` | Start a Cloudflare quick tunnel in the foreground; use the `ogp-expose` skill/doc flow for guided setup |
 | `ogp expose --background` | Run tunnel as background process |
 | `ogp expose --method ngrok` | Use ngrok instead of cloudflared |
 | `ogp expose stop` | Stop the tunnel |
@@ -725,25 +736,26 @@ ogp federation agent stan memory-management \
 
 ### 3. Project Intent System (v0.2.0+)
 
-Collaborative project management across federated peers with activity logging and cross-peer queries.
+Projects are optional collaboration boundaries layered on top of federation. They let each person keep their own tools while their agents log high-level project context and query collaborators through OGP when needed.
 
 **Features:**
 - Create projects with contextual setup (repo, workspace, notes, collaborators)
-- Log contributions by entry type (progress, decision, blocker, context)
-- Query local and peer contributions for unified team view
-- Agent-aware: proactive logging and context loading
-- **Auto-registration (v0.2.9+)**: Project IDs auto-register as agent-comms topics for all approved peers
+- Log high-level contributions by entry type (progress, decision, blocker, context)
+- Query local and peer contributions for project-aware coordination
+- Use project IDs as agent-comms topics for collaborator questions and summaries
+- **Auto-registration (v0.2.9+)**: Project IDs auto-register as agent-comms topics for approved peers who are explicit project members
 
 **Example:**
 ```bash
-# Create project (auto-registers as agent-comms topic for all peers)
+# Create project (auto-registers as agent-comms topic for approved project members)
 ogp project create my-app "My App" --description "Expense tracker"
 
 # Log work by entry type
 ogp project contribute my-app progress "Completed authentication"
 ogp project contribute my-app decision "Using PostgreSQL"
 
-# Query peer's project
+# Ask a collaborator or query peer project state
+ogp federation agent alice my-app "My user is about to work on auth. Anything already decided?"
 ogp project query-peer alice shared-app --limit 10
 ```
 
@@ -814,10 +826,10 @@ ogp agent-comms configure --global --topics "general,project-updates" --level su
 
 ### 9. Project Topic Auto-Registration (v0.2.9+)
 
-When you create a project, its ID is automatically registered as an agent-comms topic for all approved peers at `summary` level. When you approve a new peer, all existing local projects are auto-registered as topics for that peer.
+When you create a project, its ID is automatically registered as an agent-comms topic at `summary` level for approved peers who are explicit project members. When you approve a new peer, existing local projects are auto-registered only if that peer is already in the project's member list.
 
 ```bash
-# Creates project AND registers as topic for all peers
+# Creates project AND registers as topic for approved project members
 ogp project create my-app "My Application"
 
 # Approving a peer also registers existing projects as topics
@@ -1114,7 +1126,7 @@ If you are debugging OpenClaw integration directly:
 
 ### State Files
 
-- `~/.ogp/keypair.json` - Public key cache for the OpenClaw instance. On macOS the private key lives in an instance-specific Keychain entry; on non-macOS the file contains the full keypair.
+- `~/.ogp/keypair.json` - Public key cache plus key material metadata. On macOS the private key lives in an instance-specific Keychain entry; on non-macOS OGP encrypts the private key at rest when `OGP_KEYPAIR_SECRET`, `openclawToken`, or `hermesWebhookSecret` is available.
 - `~/.ogp/peers.json` - Federated peer list with scope grants
 - `~/.ogp/intents.json` - Intent registry (built-in + custom)
 - `~/.ogp/projects.json` - Project contexts and contributions
@@ -1122,6 +1134,13 @@ If you are debugging OpenClaw integration directly:
 
 On macOS, deleting `keypair.json` by itself does **not** rotate the gateway identity if the matching private key is still present in Keychain. Use `ogp setup --reset-keypair` when you intentionally want a new identity.
 
+On non-macOS, OGP prefers this secret source order for encrypting the private key at rest:
+- `OGP_KEYPAIR_SECRET`
+- `hermesWebhookSecret`
+- `openclawToken`
+
+If no encryption secret is available, OGP falls back to legacy plaintext key storage and logs a warning. Set one of the secrets above, then run `ogp setup --reset-keypair` to harden the instance.
+
 ## Skills (Claude Code)
 
 OGP includes skills for Claude Code agents. Install them with:
@@ -1130,6 +1149,17 @@ OGP includes skills for Claude Code agents. Install them with:
 ogp-install-skills
 ```
 
+After upgrading, verify the installed skill headers:
+
+```bash
+rg -n '^version:' ~/.openclaw/skills/ogp*/SKILL.md ~/.claude/skills/ogp*/SKILL.md 2>/dev/null
+```
+
+Expected changed skill versions for the `0.4.2` release line:
+- `ogp` `2.6.0`
+- `ogp-agent-comms` `0.6.0`
+- `ogp-project` `2.2.0`
+
 ### Available Skills
 
 | Skill | Purpose |
@@ -1137,9 +1167,9 @@ ogp-install-skills
 | **ogp** | Core protocol: federation setup, peer management, sending messages |
 | **ogp-expose** | Tunnel setup: cloudflared/ngrok configuration |
 | **ogp-agent-comms** | Interactive wizard: configure response policies plus delegated-authority / human-delivery interview |
-| **ogp-project** | Agent-aware project context: interviews, logging, cross-peer summarization |
+| **ogp-project** | Agent-aware project context: interviews, logging, and project-aware peer coordination |
 
-Skills auto-install from the `skills/` directory. The `ogp-agent-comms` skill now uses `ogp agent-comms interview` as the canonical conversational path for delegated-authority / human-delivery configuration, plus the existing per-peer policy commands. The `ogp-project` skill enables conversational project management with context interviews and proactive logging.
+Skills auto-install from the `skills/` directory. The `ogp-agent-comms` skill now uses `ogp agent-comms interview` as the canonical conversational path for delegated-authority / human-delivery configuration, plus the existing per-peer policy commands. The `ogp-project` skill enables conversational project management with context interviews, high-level project logging, and project-aware peer coordination.
 
 ## Documentation
 
@@ -1171,7 +1201,7 @@ Skills auto-install from the `skills/` directory. The `ogp-agent-comms` skill no
 **Best practices:**
 - Treat `~/.ogp/keypair.json` as identity material even when it contains only the public key cache on macOS.
 - On macOS, remember the private key source of truth is the instance-specific Keychain entry, not `keypair.json`; use `ogp setup --reset-keypair` for intentional rotation.
-- On non-macOS, keep `~/.ogp/keypair.json` secure with proper file permissions (`chmod 600`)
+- On non-macOS, provide `OGP_KEYPAIR_SECRET` or a platform secret so OGP can encrypt the private key at rest; `chmod 600` remains enforced but is not sufficient by itself.
 - Verify peer identity out-of-band before approving federation requests
 - Always use HTTPS tunnels (never expose raw HTTP)
 - Monitor OpenClaw logs for suspicious peer activity

package/dist/cli/federation.d.ts

@@ -1,3 +1,16 @@
+import { type OGPConfig } from '../shared/config.js';
+type FederationCard = {
+    displayName?: string;
+    email?: string;
+    gatewayUrl?: string;
+    publicKey?: string;
+};
+export declare function fetchFederationCard(gatewayUrl: string, fetchImpl?: typeof fetch): Promise<{
+    requestedUrl: string;
+    canonicalUrl: string;
+    card: FederationCard;
+}>;
+export declare function ensureLocalGatewayReachable(config: Pick<OGPConfig, 'gatewayUrl'>, actionLabel: string, fetchImpl?: typeof fetch): Promise<boolean>;
 export declare function federationList(status?: 'pending' | 'approved' | 'rejected' | 'removed'): Promise<void>;
 export declare function federationStatus(): Promise<void>;
 export declare function federationRequest(peerUrl: string, peerId: string, alias?: string): Promise<boolean>;
@@ -60,4 +73,5 @@ export declare function federationConnect(pubkey: string, alias?: string): Promi
  * Usage: ogp federation alias <peer-id> <alias>
  */
 export declare function federationSetAlias(peerId: string, alias: string): Promise<void>;
+export {};
 //# sourceMappingURL=federation.d.ts.map

package/dist/cli/federation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"federation.d.ts","sourceRoot":"","sources":["../../src/cli/federation.ts"],"names":[],"mappings":"AAsDA,wBAAsB,cAAc,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAuG5G;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4ItD;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA8EzG;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2HnG;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCpE;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmDpE;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAwErB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+DxE;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAmDf;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CAClB,GACL,OAAO,CAAC,IAAI,CAAC,CA2Hf;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAiCtD;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+CnF;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBrF;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBrF"}
+{"version":3,"file":"federation.d.ts","sourceRoot":"","sources":["../../src/cli/federation.ts"],"names":[],"mappings":"AACA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAgChF,KAAK,cAAc,GAAG;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAiBF,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC,CAY/E;AAED,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EACrC,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,OAAO,CAAC,CAwBlB;AAsDD,wBAAsB,cAAc,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAiI5G;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CA0JtD;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA8FzG;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8LnG;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCpE;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmDpE;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAuFrB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+DxE;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAmDf;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CAClB,GACL,OAAO,CAAC,IAAI,CAAC,CA6Hf;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAiCtD;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+CnF;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBrF;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBrF"}

package/dist/cli/federation.js

@@ -1,4 +1,4 @@
-import { listPeers, loadPeers, getPeer, approvePeer, rejectPeer, updatePeerGrantedScopes } from '../daemon/peers.js';
+import { listPeers, loadPeers, getPeer, approvePeer, rejectPeer, updatePeer, updatePeerGrantedScopes } from '../daemon/peers.js';
 import { requireConfig, loadConfig } from '../shared/config.js';
 import { lookupPeer } from '../daemon/rendezvous.js';
 import { getPublicKey, getPrivateKey, loadOrGenerateKeyPair } from '../daemon/keypair.js';
@@ -20,6 +20,75 @@ function expandTilde(filePath) {
     }
     return filePath;
 }
+function normalizeGatewayUrl(url) {
+    const trimmed = url.trim();
+    if (!trimmed) {
+        return '';
+    }
+    // Add https:// if no protocol specified
+    const withProtocol = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)
+        ? trimmed
+        : `https://${trimmed}`;
+    // Remove trailing slashes
+    return withProtocol.replace(/\/+$/, '');
+}
+export async function fetchFederationCard(gatewayUrl, fetchImpl = fetch) {
+    const requestedUrl = normalizeGatewayUrl(gatewayUrl);
+    const wellKnownUrl = `${requestedUrl}/.well-known/ogp`;
+    const response = await fetchImpl(wellKnownUrl);
+    if (!response.ok) {
+        throw new Error(`Could not fetch ${wellKnownUrl}: ${response.status} ${response.statusText}`);
+    }
+    const card = await response.json();
+    const canonicalUrl = card.gatewayUrl ? normalizeGatewayUrl(card.gatewayUrl) : requestedUrl;
+    return { requestedUrl, canonicalUrl, card };
+}
+export async function ensureLocalGatewayReachable(config, actionLabel, fetchImpl = fetch) {
+    const configuredGatewayUrl = normalizeGatewayUrl(config.gatewayUrl || '');
+    if (!configuredGatewayUrl) {
+        console.error(`Error: gatewayUrl is not set. Run "ogp expose" or update your config before you ${actionLabel}.`);
+        return false;
+    }
+    try {
+        const { canonicalUrl } = await fetchFederationCard(configuredGatewayUrl, fetchImpl);
+        if (canonicalUrl !== configuredGatewayUrl) {
+            console.error(`Error: configured gatewayUrl is stale.`);
+            console.error(`  Config: ${configuredGatewayUrl}`);
+            console.error(`  Live card: ${canonicalUrl}`);
+            console.error(`  Update your config before you ${actionLabel}.`);
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        console.error(`Error: your gatewayUrl is not reachable at ${configuredGatewayUrl}.`);
+        console.error(`  Run "ogp expose" or fix gatewayUrl before you ${actionLabel}.`);
+        console.error(`  Details: ${error.message}`);
+        return false;
+    }
+}
+async function resolvePeerGatewayUrl(gatewayUrl, contextLabel) {
+    try {
+        const { requestedUrl, canonicalUrl, card } = await fetchFederationCard(gatewayUrl);
+        if (canonicalUrl !== requestedUrl) {
+            console.log(`ℹ ${contextLabel}: peer advertises canonical gateway URL ${canonicalUrl}; using it instead of ${requestedUrl}`);
+        }
+        return { gatewayUrl: canonicalUrl, card };
+    }
+    catch (error) {
+        throw new Error(`${contextLabel}: peer gateway is not reachable or missing /.well-known/ogp. ${error.message}`);
+    }
+}
+async function refreshPeerGatewayUrlForApproval(peer) {
+    const { gatewayUrl, card } = await resolvePeerGatewayUrl(peer.gatewayUrl, 'Preflight');
+    if (card.publicKey && peer.publicKey && card.publicKey !== peer.publicKey) {
+        throw new Error(`Preflight: peer gateway identity mismatch. Expected ${peer.publicKey.substring(0, 32)}, got ${card.publicKey.substring(0, 32)}.`);
+    }
+    if (gatewayUrl !== peer.gatewayUrl) {
+        updatePeer(peer.id, { gatewayUrl });
+    }
+    return gatewayUrl;
+}
 /**
  * Resolve a peer identifier (alias, ID, or public key) to a peer ID.
  * Returns the peer ID if found, or null.
@@ -122,9 +191,34 @@ export async function federationList(status) {
         const displayCol = (peer.displayName || '-').slice(0, 20).padEnd(20);
         const keyCol = (peer.publicKey?.substring(0, 16) || '-') + '...';
         const statusCol = peer.status;
-        console.log(`  ${aliasCol} ${displayCol} ${keyCol.padEnd(20)} ${statusCol}`);
+        // Health status indicator
+        let healthIcon = '';
+        if (peer.status === 'approved') {
+            if (peer.healthy === true) {
+                healthIcon = '✓';
+            }
+            else if (peer.healthy === false) {
+                healthIcon = '✗';
+            }
+            else {
+                healthIcon = '?'; // Unknown health status
+            }
+        }
+        console.log(`  ${healthIcon ? healthIcon + ' ' : ''}${aliasCol} ${displayCol} ${keyCol.padEnd(20)} ${statusCol}`);
         console.log(`    Gateway: ${peer.gatewayUrl}`);
         console.log(`    ID: ${peer.id}`);
+        // Show health details for approved peers
+        if (peer.status === 'approved') {
+            if (peer.lastSeenAt) {
+                const lastSeen = new Date(peer.lastSeenAt);
+                const now = new Date();
+                const minutesAgo = Math.floor((now.getTime() - lastSeen.getTime()) / 60000);
+                console.log(`    Last seen: ${minutesAgo < 60 ? minutesAgo + 'm ago' : Math.floor(minutesAgo / 60) + 'h ago'}`);
+            }
+            if (peer.healthCheckFailures && peer.healthCheckFailures > 0) {
+                console.log(`    Health check failures: ${peer.healthCheckFailures}`);
+            }
+        }
         console.log('');
     });
 }
@@ -220,6 +314,10 @@ export async function federationStatus() {
     const pendingPeers = peers.filter(p => p.status === 'pending');
     const rejectedPeers = peers.filter(p => p.status === 'rejected');
     const removedPeers = peers.filter(p => p.status === 'removed');
+    // Health statistics for approved peers
+    const healthyPeers = approvedPeers.filter(p => p.healthy === true);
+    const unhealthyPeers = approvedPeers.filter(p => p.healthy === false);
+    const unknownHealthPeers = approvedPeers.filter(p => p.healthy === undefined);
     console.log('\n📊 FEDERATION STATUS\n');
     // Summary counts
     console.log(`Total peers: ${peers.length}`);
@@ -228,6 +326,14 @@ export async function federationStatus() {
     console.log(`  Rejected: ${rejectedPeers.length}`);
     console.log(`  Removed:  ${removedPeers.length}`);
     console.log('');
+    // Health summary for approved peers
+    if (approvedPeers.length > 0) {
+        console.log('🏥 PEER HEALTH:\n');
+        console.log(`  Healthy:   ${healthyPeers.length} (✓)`);
+        console.log(`  Unhealthy: ${unhealthyPeers.length} (✗)`);
+        console.log(`  Unknown:   ${unknownHealthPeers.length} (?)`);
+        console.log('');
+    }
     // Alias → Public Key mapping section
     if (peers.length > 0) {
         console.log('📝 ALIAS → PUBLIC KEY MAPPING:\n');
@@ -258,8 +364,22 @@ export async function federationStatus() {
 export async function federationRequest(peerUrl, peerId, alias) {
     const config = requireConfig();
     const keypair = loadOrGenerateKeyPair();
+    if (!await ensureLocalGatewayReachable(config, 'send federation requests')) {
+        return false;
+    }
     // BUILD-111: Use public key prefix as peer ID (port-agnostic identity)
     const ourPeerId = keypair.publicKey.substring(0, 16);
+    let resolvedPeerUrl = normalizeGatewayUrl(peerUrl);
+    let peerCard = null;
+    try {
+        const resolved = await resolvePeerGatewayUrl(resolvedPeerUrl, 'Preflight');
+        resolvedPeerUrl = resolved.gatewayUrl;
+        peerCard = resolved.card;
+    }
+    catch (error) {
+        console.error(error.message);
+        return false;
+    }
     // Build our peer info
     const peer = {
         id: ourPeerId, // Public key prefix, not hostname:port
@@ -279,7 +399,7 @@ export async function federationRequest(peerUrl, peerId, alias) {
     const requestBody = { peer, signature, offeredIntents: ourIntents };
     // Send request
     try {
-        const response = await fetch(`${peerUrl}/federation/request`, {
+        const response = await fetch(`${resolvedPeerUrl}/federation/request`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(requestBody)
@@ -296,18 +416,18 @@ export async function federationRequest(peerUrl, peerId, alias) {
         // Store them as a pending peer so we can send intents when approved
         try {
             const { addPeer } = await import('../daemon/peers.js');
-            const cardRes = await fetch(`${peerUrl}/.well-known/ogp`);
-            if (cardRes.ok) {
-                const card = await cardRes.json();
-                const peerHostname = new URL(peerUrl).hostname;
-                const peerPort = new URL(peerUrl).port || '18790';
-                // BUILD-111: Use public key prefix as canonical ID, fall back to hostname:port only if no key
-                const canonicalId = card.publicKey?.substring(0, 16) || `${peerHostname}:${peerPort}`;
+            const card = peerCard;
+            if (card) {
+                const peerHostname = new URL(resolvedPeerUrl).hostname;
+                const peerPort = new URL(resolvedPeerUrl).port || '18790';
+                // BUILD-111: Use a 32-char public key prefix as canonical ID to avoid
+                // duplicate short/full peer IDs across request/approve flows.
+                const canonicalId = card.publicKey?.substring(0, 32) || `${peerHostname}:${peerPort}`;
                 addPeer({
                     id: canonicalId,
                     displayName: card.displayName || peerId,
                     email: card.email || '',
-                    gatewayUrl: peerUrl,
+                    gatewayUrl: resolvedPeerUrl,
                     publicKey: card.publicKey || '',
                     status: 'pending',
                     requestedAt: new Date().toISOString(),
@@ -328,6 +448,9 @@ export async function federationRequest(peerUrl, peerId, alias) {
 }
 export async function federationApprove(peerId, options = {}) {
     const config = requireConfig();
+    if (!await ensureLocalGatewayReachable(config, 'approve federation requests')) {
+        return;
+    }
     // Resolve peer identifier (alias, ID, or public key)
     const resolvedId = resolvePeerId(peerId);
     if (!resolvedId) {
@@ -344,6 +467,15 @@ export async function federationApprove(peerId, options = {}) {
         console.log(`Peer ${peerId} is already approved.`);
         return;
     }
+    let peerGatewayUrl = peer.gatewayUrl;
+    try {
+        peerGatewayUrl = await refreshPeerGatewayUrlForApproval(peer);
+    }
+    catch (error) {
+        console.error(error.message);
+        console.error('Ask the peer to fix their gatewayUrl and resend the federation request.');
+        return;
+    }
     // BUILD-110: Mirror peer's offered intents by default, with user confirmation
     const DEFAULT_INTENTS = ['message', 'agent-comms', 'project.join', 'project.contribute', 'project.query', 'project.status'];
     // If peer offered intents, use those as default (for symmetry)
@@ -392,9 +524,9 @@ export async function federationApprove(peerId, options = {}) {
     approvePeer(peerId);
     console.log(`✓ Approved peer: ${peerId}`);
     // BUILD-102: Auto-register existing local projects as agent-comms topics for this peer
-    const { listProjects } = await import('../daemon/projects.js');
+    const { listProjectsForPeer } = await import('../daemon/projects.js');
     const { setPeerTopicPolicy } = await import('../daemon/peers.js');
-    const projects = listProjects();
+    const projects = listProjectsForPeer(peerId);
     if (projects.length > 0) {
         for (const project of projects) {
             setPeerTopicPolicy(peerId, project.id, 'summary');
@@ -408,11 +540,11 @@ export async function federationApprove(peerId, options = {}) {
     console.log(`  To restrict topics:  ogp agent-comms set-topic ${peerId} general off`);
     console.log(`  To review policies:  ogp agent-comms policies ${peerId}`);
     // Notify the peer — send both formats for maximum compatibility
+    const keypair = loadOrGenerateKeyPair();
+    const ourConfig = requireConfig();
     try {
-        const keypair = loadOrGenerateKeyPair();
-        const ourConfig = requireConfig();
         const nonce = crypto.randomUUID();
-        await fetch(`${peer.gatewayUrl}/federation/approve`, {
+        await fetch(`${peerGatewayUrl}/federation/approve`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
@@ -437,6 +569,55 @@ export async function federationApprove(peerId, options = {}) {
     catch (error) {
         console.error('Failed to notify peer:', error);
     }
+    // Check if this peer has a resync snapshot (gateway URL reused with new keys)
+    const refreshedPeer = getPeer(peerId);
+    if (refreshedPeer?.resyncSnapshot) {
+        const snapshot = refreshedPeer.resyncSnapshot;
+        console.log('\n📋 Federation resync available');
+        console.log(`  This gateway previously had federation with different keys`);
+        console.log(`  Old peer ID: ${snapshot.oldPeerId}`);
+        if (snapshot.oldAlias)
+            console.log(`  Old alias: ${snapshot.oldAlias}`);
+        if (snapshot.oldProjects && snapshot.oldProjects.length > 0) {
+            console.log(`  Old projects: ${snapshot.oldProjects.join(', ')}`);
+        }
+        // Send resync offer via agent-comms
+        try {
+            const resyncMessage = `Hey! We previously had a federation with your gateway (${refreshedPeer.gatewayUrl}) until ${new Date(snapshot.replacedAt).toLocaleDateString()}.
+
+Previous setup:
+${snapshot.oldAlias ? `- Alias: ${snapshot.oldAlias}` : ''}
+${snapshot.oldProjects && snapshot.oldProjects.length > 0 ? `- Projects: ${snapshot.oldProjects.join(', ')}` : '- Projects: none'}
+${snapshot.oldGrantedScopes ? `- Granted scopes: ${snapshot.oldGrantedScopes.scopes.map(s => s.intent).join(', ')}` : '- Granted scopes: none'}
+${snapshot.oldReceivedScopes ? `- Received scopes: ${snapshot.oldReceivedScopes.scopes.map(s => s.intent).join(', ')}` : '- Received scopes: none'}
+
+Would you like me to restore these settings? Reply with "yes" to restore or "no" to start fresh.`;
+            const resyncNonce = crypto.randomUUID();
+            const resyncPayload = {
+                intent: 'agent-comms',
+                from: keypair.publicKey.substring(0, 32),
+                to: peerId,
+                nonce: resyncNonce,
+                timestamp: new Date().toISOString(),
+                topic: 'federation-resync',
+                message: resyncMessage,
+                priority: 'normal'
+            };
+            const { payload: signedPayload, signature } = signObject(resyncPayload, keypair.privateKey);
+            await fetch(`${peerGatewayUrl}/federation/message`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    message: signedPayload,
+                    signature
+                })
+            });
+            console.log('✓ Sent resync offer to peer');
+        }
+        catch (error) {
+            console.warn('Failed to send resync offer:', error);
+        }
+    }
 }
 export async function federationReject(peerId) {
     // Resolve peer identifier (alias, ID, or public key)
@@ -563,11 +744,25 @@ export async function federationSend(peerId, intent, payloadJson, timeoutMs) {
         });
         if (timeoutId)
             clearTimeout(timeoutId);
+        let result = null;
+        try {
+            result = await response.json();
+        }
+        catch {
+            result = null;
+        }
         if (!response.ok) {
+            if (result?.error) {
+                console.error(`Send failed: ${response.status} ${response.statusText} - ${result.error}`);
+                return result;
+            }
             console.error(`Send failed: ${response.status} ${response.statusText}`);
-            return null;
+            return {
+                success: false,
+                error: `Send failed: ${response.status} ${response.statusText}`,
+                statusCode: response.status
+            };
         }
-        const result = await response.json();
         return result;
     }
     catch (error) {
@@ -598,7 +793,7 @@ export async function federationShowScopes(peerId) {
     }
     console.log(`\nSCOPES FOR ${peer.displayName} (${peerId}):\n`);
     console.log('  Status:', peer.status);
-    console.log('  Protocol:', peer.protocolVersion || '0.1.0 (legacy)');
+    console.log('  Wire Protocol:', peer.protocolVersion || '0.1.0 (legacy)');
     console.log('');
     // What I grant TO this peer
     if (peer.grantedScopes) {
@@ -794,10 +989,12 @@ export async function federationSendAgentComms(peerId, topic, messageText, optio
                 }
             }
             console.log('\n⏱ Reply timeout - no response received');
+            process.exit(1);
         }
     }
     catch (error) {
         console.error('Failed to send agent-comms:', error);
+        process.exit(1);
     }
 }
 /**