@synap-core/cli 1.10.0 → 1.12.2

package/dist/lib/directory-lens.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-DIRECTORY lens — the durable default scope for a working tree.
+ *
+ * RATIFIED MODEL: a directory's `.synap/lens.json` is where a lens normally
+ * lives; the per-Claude-session lens (`session-lens.ts`) is an explicit
+ * OVERRIDE on top of it.
+ *
+ * The session lens alone could not express "this repo is always Builder" — it
+ * dies with the tab, so every new session started pod-wide (or, worse, on
+ * whatever the global config happened to hold) and the operator re-pinned by
+ * hand. A directory lens is discovered the way git discovers `.git`: walk UP
+ * from the cwd until a `.synap/lens.json` turns up.
+ *
+ * Full precedence, highest first (assembled in `hub-client.ts`):
+ *
+ *   explicit flag  ›  session lens  ›  DIRECTORY LENS  ›  env var  ›  global config
+ *
+ * ── Pod qualification ────────────────────────────────────────────────────────
+ * Workspace and project ids are POD-LOCAL: sending workspace W (pod A) to pod B
+ * is the "Access denied to workspace" 403. A directory lens is exposed to that
+ * hazard MORE than a session lens is, because it outlives many `synap pods use`
+ * switches. It therefore carries the same `podUrl` stamp and is compared
+ * through the SAME door — {@link lensMatchesPod} from `session-lens.ts`. There
+ * is deliberately no second comparison implementation here; a duplicated
+ * "is this the right pod" rule that drifts is the bug, not the fix.
+ *
+ * ── Write safety ─────────────────────────────────────────────────────────────
+ * Writes never escape the user's own tree: the target is either an EXISTING
+ * lens found on the upward walk (only when it sits at or below the home dir) or
+ * the cwd itself. A lens is never created in an ancestor, never above the home
+ * dir, and never at the filesystem root.
+ */
+import { type SessionLens } from "./session-lens.js";
+/** A directory lens is the same shape as a session lens — same fields, different lifetime. */
+export type DirectoryLens = SessionLens;
+export interface FoundDirectoryLens {
+    lens: DirectoryLens;
+    /** Absolute path to the `.synap/lens.json` that supplied it — shown by `synap lens`. */
+    file: string;
+    /** The directory that owns it (the one containing `.synap/`). */
+    dir: string;
+}
+/**
+ * Every directory to consider, nearest first: the cwd, then each ancestor.
+ * The walk STOPS after the home dir (a lens above `~` would apply to every
+ * unrelated project on the machine) and at the filesystem root.
+ */
+export declare function lensSearchPath(startDir?: string): string[];
+/**
+ * The nearest directory lens at or above `startDir`, ignoring pod qualification.
+ * Callers that are about to SEND ids must use {@link resolveDirectoryLensForPod}.
+ */
+export declare function findDirectoryLens(startDir?: string): FoundDirectoryLens | null;
+/**
+ * The nearest directory lens, but ONLY if it belongs to `podUrl`.
+ *
+ * A lens stamped with a different pod returns null so the caller falls through
+ * to the next rung (env var, then the pod-qualified global config) instead of
+ * sending a foreign workspace id. Comparison is delegated to `lensMatchesPod`
+ * — including its deliberate leniency for lenses written before the `podUrl`
+ * stamp existed.
+ */
+export declare function resolveDirectoryLensForPod(podUrl: string | undefined, startDir?: string): FoundDirectoryLens | null;
+/**
+ * The fields of a directory lens that are in force for THIS process.
+ *
+ * Workspace and project are the tree's durable scope and always apply. The
+ * focus SESSION does not, inside a Claude Code conversation: a session is the
+ * conversation's own, and `attachActiveSessionId` writes it to the session lens
+ * there for exactly that reason. Read through, a directory-lens session —
+ * attached from a plain terminal, or migrated from a `.synap-session` — was
+ * sent as `X-Session-Id` by every conversation opened in the tree, long after
+ * it went quiet, so each one's writes were filed into that old session (and a
+ * stale one was revived by them). Outside Claude Code there is no conversation
+ * to own a session, so the directory lens still carries it.
+ */
+export declare function effectiveDirectoryLens(lens: DirectoryLens): DirectoryLens;
+/**
+ * Where would a write land? An existing lens on the upward walk wins (so
+ * `synap use` from a subdirectory re-pins the repo's lens rather than seeding a
+ * nested one), but only when that lens sits at or below the home dir. Otherwise
+ * the cwd — a lens is never CREATED in an ancestor.
+ */
+export declare function directoryLensWriteTarget(startDir?: string): string;
+/**
+ * Merge-write the directory lens. Returns the file it wrote, so the caller can
+ * TELL the user which path now owns their scope — a silently-resolved lens is
+ * exactly what produced the 403 class this module exists to make legible.
+ */
+export declare function writeDirectoryLens(patch: Partial<DirectoryLens>, startDir?: string): {
+    lens: DirectoryLens;
+    file: string;
+    dir: string;
+};
+/**
+ * Clear one field (or the whole lens) from the nearest directory lens.
+ * Returns the file touched, or null when there was nothing to clear.
+ */
+export declare function clearDirectoryLensField(field?: keyof DirectoryLens, startDir?: string): string | null;

package/dist/lib/directory-lens.js

@@ -0,0 +1,187 @@
+/**
+ * Per-DIRECTORY lens — the durable default scope for a working tree.
+ *
+ * RATIFIED MODEL: a directory's `.synap/lens.json` is where a lens normally
+ * lives; the per-Claude-session lens (`session-lens.ts`) is an explicit
+ * OVERRIDE on top of it.
+ *
+ * The session lens alone could not express "this repo is always Builder" — it
+ * dies with the tab, so every new session started pod-wide (or, worse, on
+ * whatever the global config happened to hold) and the operator re-pinned by
+ * hand. A directory lens is discovered the way git discovers `.git`: walk UP
+ * from the cwd until a `.synap/lens.json` turns up.
+ *
+ * Full precedence, highest first (assembled in `hub-client.ts`):
+ *
+ *   explicit flag  ›  session lens  ›  DIRECTORY LENS  ›  env var  ›  global config
+ *
+ * ── Pod qualification ────────────────────────────────────────────────────────
+ * Workspace and project ids are POD-LOCAL: sending workspace W (pod A) to pod B
+ * is the "Access denied to workspace" 403. A directory lens is exposed to that
+ * hazard MORE than a session lens is, because it outlives many `synap pods use`
+ * switches. It therefore carries the same `podUrl` stamp and is compared
+ * through the SAME door — {@link lensMatchesPod} from `session-lens.ts`. There
+ * is deliberately no second comparison implementation here; a duplicated
+ * "is this the right pod" rule that drifts is the bug, not the fix.
+ *
+ * ── Write safety ─────────────────────────────────────────────────────────────
+ * Writes never escape the user's own tree: the target is either an EXISTING
+ * lens found on the upward walk (only when it sits at or below the home dir) or
+ * the cwd itself. A lens is never created in an ancestor, never above the home
+ * dir, and never at the filesystem root.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getClaudeSessionId, lensMatchesPod } from "./session-lens.js";
+import { writeSecretFile } from "./atomic-file.js";
+/** The directory name a lens lives in, and the file inside it. */
+const LENS_DIR_NAME = ".synap";
+const LENS_FILE_NAME = "lens.json";
+function lensFileIn(dir) {
+    return path.join(dir, LENS_DIR_NAME, LENS_FILE_NAME);
+}
+/** Is `dir` the home dir or inside it? Used to bound where a lens may be WRITTEN. */
+function isAtOrBelowHome(dir) {
+    const home = path.resolve(os.homedir());
+    const target = path.resolve(dir);
+    if (target === home)
+        return true;
+    return target.startsWith(home + path.sep);
+}
+/**
+ * Every directory to consider, nearest first: the cwd, then each ancestor.
+ * The walk STOPS after the home dir (a lens above `~` would apply to every
+ * unrelated project on the machine) and at the filesystem root.
+ */
+export function lensSearchPath(startDir = process.cwd()) {
+    const home = path.resolve(os.homedir());
+    const dirs = [];
+    let dir = path.resolve(startDir);
+    for (;;) {
+        dirs.push(dir);
+        if (dir === home)
+            break;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return dirs;
+}
+/** Read + parse one candidate, or null when absent/corrupt. A malformed lens must not crash the CLI. */
+function readLensFile(dir) {
+    const file = lensFileIn(dir);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        return { lens: parsed, file, dir };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The nearest directory lens at or above `startDir`, ignoring pod qualification.
+ * Callers that are about to SEND ids must use {@link resolveDirectoryLensForPod}.
+ */
+export function findDirectoryLens(startDir) {
+    for (const dir of lensSearchPath(startDir)) {
+        const found = readLensFile(dir);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/**
+ * The nearest directory lens, but ONLY if it belongs to `podUrl`.
+ *
+ * A lens stamped with a different pod returns null so the caller falls through
+ * to the next rung (env var, then the pod-qualified global config) instead of
+ * sending a foreign workspace id. Comparison is delegated to `lensMatchesPod`
+ * — including its deliberate leniency for lenses written before the `podUrl`
+ * stamp existed.
+ */
+export function resolveDirectoryLensForPod(podUrl, startDir) {
+    const found = findDirectoryLens(startDir);
+    if (!found)
+        return null;
+    return lensMatchesPod(found.lens, podUrl) ? found : null;
+}
+/**
+ * The fields of a directory lens that are in force for THIS process.
+ *
+ * Workspace and project are the tree's durable scope and always apply. The
+ * focus SESSION does not, inside a Claude Code conversation: a session is the
+ * conversation's own, and `attachActiveSessionId` writes it to the session lens
+ * there for exactly that reason. Read through, a directory-lens session —
+ * attached from a plain terminal, or migrated from a `.synap-session` — was
+ * sent as `X-Session-Id` by every conversation opened in the tree, long after
+ * it went quiet, so each one's writes were filed into that old session (and a
+ * stale one was revived by them). Outside Claude Code there is no conversation
+ * to own a session, so the directory lens still carries it.
+ */
+export function effectiveDirectoryLens(lens) {
+    if (!getClaudeSessionId())
+        return lens;
+    const { focusSessionId: _conversationOwned, ...scope } = lens;
+    return scope;
+}
+/**
+ * Where would a write land? An existing lens on the upward walk wins (so
+ * `synap use` from a subdirectory re-pins the repo's lens rather than seeding a
+ * nested one), but only when that lens sits at or below the home dir. Otherwise
+ * the cwd — a lens is never CREATED in an ancestor.
+ */
+export function directoryLensWriteTarget(startDir = process.cwd()) {
+    const found = findDirectoryLens(startDir);
+    if (found && isAtOrBelowHome(found.dir))
+        return found.dir;
+    return path.resolve(startDir);
+}
+/**
+ * Merge-write the directory lens. Returns the file it wrote, so the caller can
+ * TELL the user which path now owns their scope — a silently-resolved lens is
+ * exactly what produced the 403 class this module exists to make legible.
+ */
+export function writeDirectoryLens(patch, startDir) {
+    const dir = directoryLensWriteTarget(startDir);
+    const prev = readLensFile(dir)?.lens ?? {};
+    const next = { ...prev, ...patch, updatedAt: Date.now() };
+    const file = lensFileIn(dir);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    writeSecretFile(file, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    return { lens: next, file, dir };
+}
+/**
+ * Clear one field (or the whole lens) from the nearest directory lens.
+ * Returns the file touched, or null when there was nothing to clear.
+ */
+export function clearDirectoryLensField(field, startDir) {
+    const found = findDirectoryLens(startDir);
+    if (!found)
+        return null;
+    if (!field) {
+        try {
+            fs.unlinkSync(found.file);
+        }
+        catch {
+            return null;
+        }
+        return found.file;
+    }
+    if (!(field in found.lens))
+        return null;
+    const next = { ...found.lens };
+    delete next[field];
+    next.updatedAt = Date.now();
+    try {
+        writeSecretFile(found.file, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    }
+    catch {
+        return null;
+    }
+    return found.file;
+}
+//# sourceMappingURL=directory-lens.js.map

package/dist/lib/directory-lens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-lens.js","sourceRoot":"","sources":["../../src/lib/directory-lens.ts"],"names":[],"mappings":"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"}

package/dist/lib/exporter-coverage.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What `--from-workspace` / `--from-project` do NOT carry out of a live pod.
+ * ==========================================================================
+ *
+ * `synap market publish --from-workspace <id>` serialises a LIVE workspace
+ * through the pod's `workspaceToPackageDefinition`
+ * (synap-backend/packages/api/src/services/workspace-to-package-definition.ts)
+ * and posts the result. `--from-project` walks the same serialiser for every
+ * workspace a project `uses`, then composes a suite — so the same drop-list
+ * applies to each constituent. That serialiser is a **lossy projection**: it
+ * emits 21 of `packageDefinitionSchema`'s keys and has no projection at all
+ * for the ones below. A workspace carrying them exports WITHOUT them — no
+ * error, no signal.
+ *
+ * Loops stay here deliberately: there is no durable loop row to reverse-
+ * serialise (`createLoopFromDefinition` dissolves into playbooks + triggers).
+ *
+ * `TEMPLATE-DEV-GUIDE.md` used to assert, unqualified, that a
+ * `PackageDefinition` "round-trips". It does not, in this direction, and the
+ * consequence is the shape this repo keeps paying for: an author who built one
+ * of the things below publishes their workspace, ships a thinner-than-expected
+ * package, and gets a success message. Same class as `status ?? "installed"` —
+ * a claim of completeness nobody verified. (Cards authored in Card Studio USED
+ * to be one of these — `workspaceToPackageDefinition` now emits them into
+ * `cells[]`, so that loss is fixed; the list below is what remains.)
+ *
+ * ── WHY THIS LIST IS UNCONDITIONAL, NOT DETECTED ────────────────────────────
+ * The CLI never sees the workspace, only the projection's OUTPUT. "key absent
+ * because the workspace had none" and "key absent because the serialiser cannot
+ * emit it" are indistinguishable from here, and reporting a count would be
+ * inventing a fact. So this warns about the DOOR ("this door does not carry
+ * these"), which is true on every call, rather than about the payload.
+ *
+ * Keeping it honest across the repo boundary is
+ * `test/exporter-coverage-parity.test.ts`, which reads the exporter's own
+ * source and fails if a key listed here has gained an assignment (the list is
+ * stale and over-warns) or if a key it claims to emit has lost one.
+ */
+/** A `packageDefinitionSchema` key the workspace serialiser cannot emit. */
+export interface UnemittedKey {
+    /** The `PackageDefinition` key, verbatim. */
+    key: string;
+    /** What an author actually loses, in product words (Card, not cell). */
+    loses: string;
+}
+/**
+ * Keys with real user-authored content behind them that the serialiser drops.
+ *
+ * DELIBERATELY EXCLUDED, and why — these are absent from the export too, but
+ * warning about them would be noise rather than a loss:
+ *   • `icon` / `color` / `domain` / `workspaceType` — a live workspace has no
+ *     field to read them from (the exporter says so at L107-109). Honest
+ *     under-convergence, not a silent drop.
+ *   • `suggestedEntities` / `suggestedRelations` / `phases` / `composesFrom` —
+ *     authoring-time seed hints and composition metadata. A live workspace has
+ *     real entities, not "suggestions"; there is nothing to derive them from.
+ *   • `capability` / `sourcePackage` / `contentHash` — a non-workspace package
+ *     body and publish-time provenance. Not this door's business.
+ */
+export declare const EXPORTER_UNEMITTED_KEYS: readonly UnemittedKey[];
+/**
+ * The keys the serialiser DOES emit. Not consumed at runtime — it is the other
+ * half of the parity tripwire's assertion, so that "emits" and "does not emit"
+ * are pinned by the same read of the same source and cannot disagree.
+ */
+export declare const EXPORTER_EMITTED_KEYS: readonly string[];
+/**
+ * One human line per dropped key, for `--json`'s `warnings[]` and for the
+ * terminal hint list. Deliberately phrased as a property of the DOOR.
+ */
+export declare function exporterDropWarnings(): string[];

package/dist/lib/exporter-coverage.js

@@ -0,0 +1,97 @@
+/**
+ * What `--from-workspace` / `--from-project` do NOT carry out of a live pod.
+ * ==========================================================================
+ *
+ * `synap market publish --from-workspace <id>` serialises a LIVE workspace
+ * through the pod's `workspaceToPackageDefinition`
+ * (synap-backend/packages/api/src/services/workspace-to-package-definition.ts)
+ * and posts the result. `--from-project` walks the same serialiser for every
+ * workspace a project `uses`, then composes a suite — so the same drop-list
+ * applies to each constituent. That serialiser is a **lossy projection**: it
+ * emits 21 of `packageDefinitionSchema`'s keys and has no projection at all
+ * for the ones below. A workspace carrying them exports WITHOUT them — no
+ * error, no signal.
+ *
+ * Loops stay here deliberately: there is no durable loop row to reverse-
+ * serialise (`createLoopFromDefinition` dissolves into playbooks + triggers).
+ *
+ * `TEMPLATE-DEV-GUIDE.md` used to assert, unqualified, that a
+ * `PackageDefinition` "round-trips". It does not, in this direction, and the
+ * consequence is the shape this repo keeps paying for: an author who built one
+ * of the things below publishes their workspace, ships a thinner-than-expected
+ * package, and gets a success message. Same class as `status ?? "installed"` —
+ * a claim of completeness nobody verified. (Cards authored in Card Studio USED
+ * to be one of these — `workspaceToPackageDefinition` now emits them into
+ * `cells[]`, so that loss is fixed; the list below is what remains.)
+ *
+ * ── WHY THIS LIST IS UNCONDITIONAL, NOT DETECTED ────────────────────────────
+ * The CLI never sees the workspace, only the projection's OUTPUT. "key absent
+ * because the workspace had none" and "key absent because the serialiser cannot
+ * emit it" are indistinguishable from here, and reporting a count would be
+ * inventing a fact. So this warns about the DOOR ("this door does not carry
+ * these"), which is true on every call, rather than about the payload.
+ *
+ * Keeping it honest across the repo boundary is
+ * `test/exporter-coverage-parity.test.ts`, which reads the exporter's own
+ * source and fails if a key listed here has gained an assignment (the list is
+ * stale and over-warns) or if a key it claims to emit has lost one.
+ */
+/**
+ * Keys with real user-authored content behind them that the serialiser drops.
+ *
+ * DELIBERATELY EXCLUDED, and why — these are absent from the export too, but
+ * warning about them would be noise rather than a loss:
+ *   • `icon` / `color` / `domain` / `workspaceType` — a live workspace has no
+ *     field to read them from (the exporter says so at L107-109). Honest
+ *     under-convergence, not a silent drop.
+ *   • `suggestedEntities` / `suggestedRelations` / `phases` / `composesFrom` —
+ *     authoring-time seed hints and composition metadata. A live workspace has
+ *     real entities, not "suggestions"; there is nothing to derive them from.
+ *   • `capability` / `sourcePackage` / `contentHash` — a non-workspace package
+ *     body and publish-time provenance. Not this door's business.
+ */
+export const EXPORTER_UNEMITTED_KEYS = [
+    { key: "commands", loses: "workspace commands" },
+    { key: "relationDefs", loses: "relation definitions" },
+    { key: "loops", loses: "loops" },
+    { key: "widgets", loses: "widget definitions" },
+    { key: "dependencies", loses: "declared package dependencies" },
+    { key: "defaultSources", loses: "declared workspace sources" },
+    { key: "sourceRoles", loses: "source roles" },
+];
+/**
+ * The keys the serialiser DOES emit. Not consumed at runtime — it is the other
+ * half of the parity tripwire's assertion, so that "emits" and "does not emit"
+ * are pinned by the same read of the same source and cannot disagree.
+ */
+export const EXPORTER_EMITTED_KEYS = [
+    "_meta",
+    "workspaceName",
+    "description",
+    "workspaceSubtype",
+    "workspaceVisibility",
+    "workspaceCapabilities",
+    "onboarding",
+    "profileEntityBentoTemplates",
+    "profiles",
+    "bentoLayout",
+    "bentoViewBlocks",
+    "bentoViewName",
+    "views",
+    "entityLinks",
+    "displayTemplates",
+    "automations",
+    "playbooks",
+    "capabilities",
+    "layoutConfig",
+    "actionPlacements",
+    "cells",
+];
+/**
+ * One human line per dropped key, for `--json`'s `warnings[]` and for the
+ * terminal hint list. Deliberately phrased as a property of the DOOR.
+ */
+export function exporterDropWarnings() {
+    return EXPORTER_UNEMITTED_KEYS.map((k) => `${k.key} — ${k.loses} (not exported: no projection)`);
+}
+//# sourceMappingURL=exporter-coverage.js.map

package/dist/lib/exporter-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter-coverage.js","sourceRoot":"","sources":["../../src/lib/exporter-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAUH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA4B;IAC9D,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,oBAAoB,EAAE;IAChD,EAAE,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,sBAAsB,EAAE;IACtD,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE;IAChC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,oBAAoB,EAAE;IAC/C,EAAE,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,+BAA+B,EAAE;IAC/D,EAAE,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,4BAA4B,EAAE;IAC9D,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,cAAc,EAAE;CAC9C,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,OAAO;IACP,eAAe;IACf,aAAa;IACb,kBAAkB;IAClB,qBAAqB;IACrB,uBAAuB;IACvB,YAAY;IACZ,6BAA6B;IAC7B,UAAU;IACV,aAAa;IACb,iBAAiB;IACjB,eAAe;IACf,OAAO;IACP,aAAa;IACb,kBAAkB;IAClB,aAAa;IACb,WAAW;IACX,cAAc;IACd,cAAc;IACd,kBAAkB;IAClB,OAAO;CACR,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,uBAAuB,CAAC,GAAG,CAChC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,KAAK,gCAAgC,CAC7D,CAAC;AACJ,CAAC"}

package/dist/lib/hub-client.d.ts

@@ -1,4 +1,4 @@
-import { HubRestClient } from "@synap/hub-rest-client";
+import { HubRestClient } from "@synap-core/hub-rest-client";
 /**
  * A failed Hub call, carrying the structured facts callers need to branch on.
  *
@@ -16,6 +16,10 @@ export declare class HubError extends Error {
     readonly rawBody: string;
     readonly path: string;
     readonly method: string;
+    /** Origin of the pod this call actually hit — for cross-pod diagnostics. */
+    readonly podUrl?: string;
+    /** Workspace this call actually sent — for cross-pod 403 diagnostics. */
+    readonly workspaceId?: string;
     constructor(init: {
         message: string;
         status: number;
@@ -25,6 +29,8 @@ export declare class HubError extends Error {
         rawBody: string;
         path: string;
         method: string;
+        podUrl?: string;
+        workspaceId?: string;
     });
 }
 /**
@@ -53,11 +59,18 @@ export declare class HubNetworkError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Append a one-line "need help?" footer with a clickable Discord invite. Prints
+ * to stderr (same stream as the error it follows, so `2>/dev/null` hides both)
+ * and only once per process. The invite is an OSC-8 hyperlink on an interactive
+ * terminal, a plain URL when the stream is redirected/piped.
+ */
+export declare function discordHelpLine(): void;
 /**
  * Print a failed Hub call: its humanized message plus a hint for the classes
  * where the cause is not obvious from the message alone. Lives here rather than
  * in utils/logger so the logger stays domain-agnostic and the taxonomy and its
- * presentation sit in one file.
+ * presentation sit in one file. Always closes with the one-time Discord footer.
  */
 export declare function renderHubError(err: unknown): void;
 export interface HubConfig {
@@ -76,12 +89,33 @@ export declare function resolveHubConfig(opts?: {
     podUrl?: string;
     apiKey?: string;
 }): Promise<HubConfig>;
-/** Read the active session ID for this terminal from CWD or env var. */
-export declare function readActiveSessionId(): string | undefined;
-/** Attach a session to this terminal — writes .synap-session in CWD. */
-export declare function writeActiveSessionId(sessionId: string): void;
-/** Detach the active session from this terminal — removes .synap-session. */
-export declare function clearActiveSessionId(): void;
+/**
+ * The focus session every hub call should be tagged with.
+ *
+ * Both lens rungs are pod-qualified: a focus-session id is POD-LOCAL, so a lens
+ * stamped with another pod must not leak into `X-Session-Id`. (Lenses written
+ * before the stamp existed have no `podUrl` and match leniently — see
+ * `lensMatchesPod`.)
+ */
+export declare function resolveActiveSessionId(podUrl?: string): string | undefined;
+/** Where an attach landed — reported so the user knows what owns their scope. */
+export type SessionAttachTarget = "session-lens" | "directory-lens";
+/**
+ * Attach a focus session to this terminal.
+ *
+ * Inside Claude Code the SESSION lens wins — per-tab isolation is the point
+ * (tab A on session X, tab B on session Y, same directory). Outside it there is
+ * no `CLAUDE_CODE_SESSION_ID` to key on, so the DIRECTORY lens is the
+ * legitimate fallback: the same per-working-tree scope the retired
+ * `.synap-session` had. `attach` therefore never silently no-ops.
+ */
+export declare function attachActiveSessionId(sessionId: string): SessionAttachTarget;
+/**
+ * Detach — clear the focus session from BOTH lens rungs, and return whatever
+ * was active. Clearing only the top rung would "detach" into the lower one,
+ * which reads as the command failing.
+ */
+export declare function detachActiveSessionId(podUrl?: string): string | undefined;
 export declare function hubGet(path: string, params: Record<string, string | number | undefined>, cfg: HubConfig): Promise<unknown>;
 export declare function hubPost(path: string, body: unknown, cfg: HubConfig, timeoutMs?: number): Promise<unknown>;
 /**
@@ -105,4 +139,4 @@ export declare function hubDelete(path: string, cfg: HubConfig): Promise<unknown
  * Hub Protocol coverage with a shared client contract — eliminating drift.
  */
 export declare function makeHubClient(cfg: HubConfig): HubRestClient;
-export { HubRestClient } from "@synap/hub-rest-client";
+export { HubRestClient } from "@synap-core/hub-rest-client";