sentinelayer-cli 0.33.0 → 0.34.1

package/README.md

@@ -712,6 +712,16 @@ Architecture references: local stdio runtime and incident response live in
 [docs/mcp-hosted-connector.md](docs/mcp-hosted-connector.md); Senti room
 coordination behavior lives in [docs/sessions.md](docs/sessions.md).
 
+Worked MCP examples:
+
+```bash
+sl mcp list --json
+sl mcp registry init-session --force
+sl mcp server init --id sentinelayer-session --registry-file .sentinelayer/mcp/tool-registry.session-tools.json
+sl mcp server run --path .
+sl mcp registry init-cli --json
+```
+
 ### MCP Live Entry Point Map
 
 - Local stdio server: `sl mcp server run --path .`, configured from
@@ -820,7 +830,7 @@ gh secret set SENTINELAYER_TOKEN --repo <owner/repo>
 gh secret list --repo <owner/repo>
 ```
 
-3. For manual setup details: `https://sentinelayer.com/docs/getting-started/install-workflow`
+3. For manual setup details: `https://github.com/mrrCarter/create-sentinelayer#manual-fallback-if-auto-injection-is-skipped`
 
 4. BYOK mode (no Sentinelayer token):
    - keep generated `docs/spec.md`, `docs/build-guide.md`, `prompts/execution-prompt.md`, and `tasks/todo.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.33.0",
+  "version": "0.34.1",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/mcp.js

@@ -31,6 +31,8 @@ import {
 import { requestHostedMcpAccessToken } from "../mcp/token-service.js";
 import { buildSentinelayerCliRegistryTemplate } from "../mcp/cli-registry.js";
 import { runMcpStdioServer } from "../mcp/session-stdio-server.js";
+import { runMcpDoctorProbes } from "../mcp/doctor.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
 import { resolveOutputRoot } from "../config/service.js";
 
 function shouldEmitJson(options, command) {
@@ -66,8 +68,52 @@ function formatApiError(error) {
   return `${error.message} [${error.code}] status=${error.status}${requestId}`;
 }
 
+export async function resolveMcpDoctorApiBaseUrl({
+  explicitApiUrl = "",
+  cwd = process.cwd(),
+  env = process.env,
+  resolveActiveAuthSessionImpl = resolveActiveAuthSession,
+} = {}) {
+  const directApiUrl = String(explicitApiUrl || "").trim();
+  if (directApiUrl) {
+    return directApiUrl;
+  }
+
+  // Probes are unauthenticated, but the API base URL can live in the CLI auth
+  // config. Read it without token rotation so doctor remains side-effect-free.
+  try {
+    const session = await resolveActiveAuthSessionImpl({
+      cwd,
+      env,
+      autoRotate: false,
+    });
+    return String((session && session.apiUrl) || "").trim();
+  } catch {
+    return "";
+  }
+}
+
 export function registerMcpCommand(program) {
-  const mcp = program.command("mcp").description("Manage Sentinelayer MCP registry schemas and adapters");
+  const mcp = program
+    .command("mcp")
+    .description("Manage local MCP registries, stdio servers, and guarded CLI bridge metadata")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  sl mcp list --json
+  sl mcp registry init-session --force
+  sl mcp server init --id sentinelayer-session --registry-file .sentinelayer/mcp/tool-registry.session-tools.json
+  sl mcp server run --path .
+  sl mcp registry init-cli --json
+
+Notes:
+  Local stdio MCP works for clients that can spawn the CLI process.
+  Hosted Claude/ChatGPT connectors require the separate HTTPS/OAuth hosted connector contract.
+  Generated CLI bridge tools are metadata only until a bridge host enforces auth, approval, and runtime policy.
+
+Docs: https://github.com/mrrCarter/create-sentinelayer/blob/main/docs/mcp.md`,
+    );
 
   mcp
     .command("list")
@@ -184,6 +230,65 @@ export function registerMcpCommand(program) {
       console.log(pc.gray("Secret value hidden in text output; use --json when you need the bearer value."));
     });
 
+  mcp
+    .command("doctor")
+    .description(
+      "Diagnose hosted MCP auth: probe the OAuth discovery chain (PRM, AS metadata, JWKS) and verify unauthenticated /mcp is rejected"
+    )
+    .option(
+      "--api-url <url>",
+      "Sentinelayer API base URL to probe (default: resolved from your CLI auth session)"
+    )
+    .option("--timeout-ms <ms>", "Per-probe request timeout in milliseconds", String(DEFAULT_REQUEST_TIMEOUT_MS))
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const emitJson = shouldEmitJson(options, command);
+      const parsedTimeout = Number(options.timeoutMs);
+      const timeoutMs =
+        Number.isFinite(parsedTimeout) && parsedTimeout > 0 ? parsedTimeout : DEFAULT_REQUEST_TIMEOUT_MS;
+
+      const apiBaseUrl = await resolveMcpDoctorApiBaseUrl({
+        explicitApiUrl: options.apiUrl,
+        cwd: process.cwd(),
+        env: process.env,
+      });
+      if (!apiBaseUrl) {
+        throw new Error(
+          "Could not resolve the Sentinelayer API URL. Pass --api-url <url>, or run `sl auth login` first."
+        );
+      }
+
+      const result = await runMcpDoctorProbes({ apiBaseUrl, timeoutMs });
+
+      if (emitJson) {
+        console.log(JSON.stringify({ command: "mcp doctor", ...result }, null, 2));
+      } else {
+        console.log(pc.bold(`MCP auth doctor — ${result.apiBaseUrl}`));
+        for (const probe of result.probes) {
+          const mark =
+            probe.verdict === "PASS"
+              ? pc.green("PASS")
+              : probe.verdict === "WARN"
+                ? pc.yellow("WARN")
+                : pc.red("FAIL");
+          console.log(`  [${mark}] ${probe.label}  (HTTP ${probe.status})`);
+          console.log(pc.gray(`         ${probe.url}`));
+          if (probe.detail) {
+            console.log(pc.gray(`         ${probe.detail}`));
+          }
+        }
+        console.log(
+          result.ok
+            ? pc.green("All critical MCP auth probes passed.")
+            : pc.red("One or more MCP auth probes FAILED — remote agents may not authenticate correctly.")
+        );
+      }
+
+      if (!result.ok) {
+        process.exitCode = 1;
+      }
+    });
+
   const schema = mcp.command("schema").description("Inspect or materialize MCP tool-registry schema");
   schema
     .command("show")
@@ -371,7 +476,7 @@ export function registerMcpCommand(program) {
 
   registry
     .command("init-cli")
-    .description("Write a generated MCP registry for every SentinelLayer CLI leaf command")
+    .description("Write guarded sl.* CLI bridge metadata for bridge-capable MCP hosts")
     .option("--path <path>", "Destination file path override")
     .option("--output-dir <path>", "Optional artifact output root override")
     .option("--force", "Overwrite destination file if it already exists")
@@ -399,7 +504,8 @@ export function registerMcpCommand(program) {
       }
       console.log(pc.green(`Wrote SentinelLayer CLI MCP registry template: ${writtenPath}`));
       console.log(pc.gray(`${template.tools.length} CLI leaf commands exposed as bridge tools.`));
-      console.log(pc.gray("Execution requires a bridge-capable MCP host; local stdio run still exposes session tools."));
+      console.log(pc.gray("Execution requires a bridge-capable MCP host with auth, approval, and runtime policy."));
+      console.log(pc.gray("Sensitive token, export, and identity-mutation commands are runtime-blocked."));
     });
 
   registry

package/src/commands/session.js

@@ -755,6 +755,14 @@ function formatHumanAskLine(event = {}) {
   return `${sequenceLabel} ${humanAskAgentId(event)}${ts ? ` ${ts}` : ""}${suffix}`;
 }
 
+function formatRemoteHydrateAppendWarning(result = {}) {
+  const count = Number(result?.appendFailureCount || 0);
+  if (!Number.isFinite(count) || count <= 0) return "";
+  const reason = normalizeString(result.appendFailureReason) || "local_append_failed";
+  const noun = count === 1 ? "event" : "events";
+  return `Remote hydrate could not persist ${count} ${noun} locally (${reason}); affected cursors were not advanced.`;
+}
+
 function eventTimestampMs(event = {}) {
   for (const key of ["ts", "timestamp", "createdAt", "at"]) {
     const epoch = Date.parse(normalizeString(event?.[key]));
@@ -5481,6 +5489,10 @@ export function registerSessionCommand(program) {
                 ),
               );
             }
+            const appendWarning = formatRemoteHydrateAppendWarning(hydration);
+            if (appendWarning) {
+              console.log(pc.yellow(appendWarning));
+            }
           } else {
             console.log(
               pc.yellow(
@@ -5847,6 +5859,8 @@ export function registerSessionCommand(program) {
         eventsCursor: result.eventsCursor,
         materializedLocalSession: result.materializedLocalSession,
         localAppendComplete: result.localAppendComplete,
+        appendFailureCount: result.appendFailureCount,
+        appendFailureReason: result.appendFailureReason,
         access: access || undefined,
       };
       if (shouldEmitJson(options, command)) {
@@ -5857,6 +5871,10 @@ export function registerSessionCommand(program) {
         console.log(
           `Hydrated session ${normalizedSessionId}: relayed=${result.relayed} dropped=${result.dropped}.`,
         );
+        const appendWarning = formatRemoteHydrateAppendWarning(result);
+        if (appendWarning) {
+          console.log(pc.yellow(appendWarning));
+        }
         if (access && !access.accessible) {
           if (access.reason === "session_not_found") {
             console.log(

package/src/legacy-cli.js

@@ -292,7 +292,13 @@ function printUsage() {
   console.log("  sl auth login && npx create-sentinelayer my-app && cd my-app");
   console.log("  # Then hand docs/spec.md to your coding agent");
   console.log("");
-  console.log("Docs: https://sentinelayer.com/docs");
+  console.log("Examples:");
+  console.log("  sl session read <id> --remote --agent <agent> --tail 20");
+  console.log("  sl session react <id> ack --target-sequence <seq> --agent <agent>");
+  console.log("  sl mcp registry init-session --force && sl mcp server run --path .");
+  console.log("  sl mcp registry init-cli --json");
+  console.log("");
+  console.log("Docs: https://github.com/mrrCarter/create-sentinelayer#readme");
 }
 
 function normalizeInterviewInput(

package/src/mcp/doctor.js

@@ -0,0 +1,247 @@
+/**
+ * `sl mcp doctor` probe logic.
+ *
+ * Diagnoses whether the hosted Sentinelayer MCP server is correctly set up for
+ * remote-agent (ChatGPT / Claude) OAuth authentication. All probes are
+ * UNAUTHENTICATED on purpose: they read public OAuth discovery documents and
+ * confirm the resource server REJECTS an unauthenticated call. No bearer token
+ * is sent and no token is minted, so the command is side-effect-free and safe
+ * to run before `sl auth login`.
+ *
+ * Checks (RFCs map to the WARDEN hosted-MCP-auth build-spec §2/§4):
+ *   1. Protected Resource Metadata  GET /.well-known/oauth-protected-resource  (RFC 9728)
+ *   2. Authorization Server Metadata GET /.well-known/oauth-authorization-server (RFC 8414)
+ *   3. JSON Web Key Set             GET /.well-known/jwks.json
+ *   4. Enforcement                  POST /mcp with no Authorization -> must 401 + WWW-Authenticate
+ */
+
+export const DEFAULT_DOCTOR_TIMEOUT_MS = 10_000;
+
+const PASS = "PASS";
+const WARN = "WARN";
+const FAIL = "FAIL";
+
+function joinUrl(base, suffix) {
+  const normalizedBase = String(base || "").replace(/\/+$/, "");
+  const normalizedSuffix = String(suffix || "").replace(/^\/+/, "");
+  return `${normalizedBase}/${normalizedSuffix}`;
+}
+
+async function probeRequest(fetchImpl, url, { method = "GET", headers, body, timeoutMs } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(url, { method, headers, body, signal: controller.signal });
+    const text = await response.text().catch(() => "");
+    let json = null;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = null;
+      }
+    }
+    return { reached: true, status: response.status, headers: response.headers, json };
+  } catch (error) {
+    const aborted = Boolean(error) && error.name === "AbortError";
+    return {
+      reached: false,
+      status: 0,
+      detail: aborted ? `timed out after ${timeoutMs}ms` : String((error && error.message) || error),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function headerValue(headers, name) {
+  if (headers && typeof headers.get === "function") {
+    return String(headers.get(name) || "");
+  }
+  if (headers && typeof headers === "object") {
+    return String(headers[name] || headers[name.toLowerCase()] || "");
+  }
+  return "";
+}
+
+/**
+ * Run the hosted MCP auth discovery + enforcement probes.
+ *
+ * @param {{ apiBaseUrl: string, timeoutMs?: number, fetchImpl?: typeof fetch }} params
+ * @returns {Promise<{ apiBaseUrl: string, ok: boolean, probes: Array<{id:string,label:string,url:string,status:number,verdict:string,detail:string}> }>}
+ */
+export async function runMcpDoctorProbes({
+  apiBaseUrl,
+  timeoutMs = DEFAULT_DOCTOR_TIMEOUT_MS,
+  fetchImpl = fetch,
+} = {}) {
+  const base = String(apiBaseUrl || "").trim().replace(/\/+$/, "");
+  if (!base) {
+    throw new Error("apiBaseUrl is required to run MCP doctor probes.");
+  }
+
+  const probes = [];
+  // Whether PRM advertised an authorization server changes how severe an
+  // AS-metadata 503 is: advertised pointer + 503 is a broken chain (FAIL),
+  // while omitted pointer + 503 is a consistent fail-closed state (WARN).
+  let prmAdvertisesAuthServer = false;
+
+  // 1. Protected Resource Metadata (RFC 9728)
+  {
+    const url = joinUrl(base, "/.well-known/oauth-protected-resource");
+    const result = await probeRequest(fetchImpl, url, { timeoutMs });
+    let verdict = FAIL;
+    let detail;
+    if (!result.reached) {
+      detail = result.detail;
+    } else if (result.status === 200 && result.json && typeof result.json.resource === "string" && result.json.resource) {
+      verdict = PASS;
+      const count = Array.isArray(result.json.authorization_servers)
+        ? result.json.authorization_servers.length
+        : 0;
+      prmAdvertisesAuthServer = count > 0;
+      detail = `resource=${result.json.resource}; authorization_servers=${count}`;
+    } else if (result.status === 200) {
+      verdict = WARN;
+      detail = "200 but missing the required 'resource' field";
+    } else {
+      detail = `expected 200, got HTTP ${result.status}`;
+    }
+    probes.push({
+      id: "protected_resource_metadata",
+      label: "Protected Resource Metadata (RFC 9728)",
+      url,
+      status: result.status,
+      verdict,
+      detail,
+    });
+  }
+
+  // 2. Authorization Server Metadata (RFC 8414)
+  {
+    const url = joinUrl(base, "/.well-known/oauth-authorization-server");
+    const result = await probeRequest(fetchImpl, url, { timeoutMs });
+    let verdict = FAIL;
+    let detail;
+    if (!result.reached) {
+      detail = result.detail;
+    } else if (result.status === 200) {
+      verdict = PASS;
+      detail =
+        result.json && result.json.token_endpoint
+          ? `token_endpoint=${result.json.token_endpoint}`
+          : "advertised";
+    } else if (result.status === 503) {
+      if (prmAdvertisesAuthServer) {
+        // Broken discovery chain: PRM points clients at an authorization server
+        // that then returns 503. Clients WILL follow the pointer and fail.
+        verdict = FAIL;
+        detail =
+          "PRM advertises authorization_servers but AS metadata is 503 — remote clients will follow the advertised pointer to an unconfigured authorization server (broken discovery chain)";
+      } else {
+        // Consistent fail-closed: no AS advertised, AS metadata not configured.
+        verdict = WARN;
+        detail =
+          "503 unconfigured and PRM does not advertise an authorization server (fail-closed, consistent) — set MCP_OAUTH_AUTHORIZATION_ENDPOINT + MCP_OAUTH_TOKEN_ENDPOINT to enable remote auto-discovery";
+      }
+    } else {
+      detail = `expected 200, got HTTP ${result.status}`;
+    }
+    probes.push({
+      id: "authorization_server_metadata",
+      label: "Authorization Server Metadata (RFC 8414)",
+      url,
+      status: result.status,
+      verdict,
+      detail,
+    });
+  }
+
+  // 3. JSON Web Key Set
+  {
+    const url = joinUrl(base, "/.well-known/jwks.json");
+    const result = await probeRequest(fetchImpl, url, { timeoutMs });
+    let verdict = FAIL;
+    let detail;
+    if (!result.reached) {
+      detail = result.detail;
+    } else if (result.status === 200 && result.json && Array.isArray(result.json.keys) && result.json.keys.length > 0) {
+      const keys = result.json.keys;
+      // A PUBLIC JWKS must only ever publish ASYMMETRIC public keys. A symmetric
+      // key (kty "oct" / HS* alg) here IS the shared HMAC signing secret — anyone
+      // who can read it can forge MCP access tokens. Treat that as a hard failure.
+      const symmetricKeys = keys.filter((key) => {
+        const kty = String((key && key.kty) || "").toLowerCase();
+        const alg = String((key && key.alg) || "").toUpperCase();
+        return kty === "oct" || alg.startsWith("HS");
+      });
+      if (symmetricKeys.length > 0) {
+        verdict = FAIL;
+        detail = `CRITICAL: ${symmetricKeys.length} symmetric key(s) (kty=oct / HS*) published in the public JWKS — that is the HMAC signing secret and lets anyone forge MCP access tokens`;
+      } else {
+        verdict = PASS;
+        const algs = [
+          ...new Set(keys.map((key) => String((key && key.alg) || (key && key.kty) || "?"))),
+        ].join(", ");
+        detail = `${keys.length} asymmetric signing key(s) published (${algs})`;
+      }
+    } else if (result.status === 200) {
+      verdict = WARN;
+      detail = "200 but no signing keys published (expected for HS256/non-prod; production must publish an RS256 JWKS)";
+    } else {
+      detail = `expected 200, got HTTP ${result.status}`;
+    }
+    probes.push({
+      id: "jwks",
+      label: "JSON Web Key Set",
+      url,
+      status: result.status,
+      verdict,
+      detail,
+    });
+  }
+
+  // 4. Enforcement: an unauthenticated /mcp call must be rejected with a
+  //    401 + WWW-Authenticate challenge that points back at the PRM document.
+  {
+    const url = joinUrl(base, "/mcp");
+    const result = await probeRequest(fetchImpl, url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: "mcp-doctor", method: "ping" }),
+      timeoutMs,
+    });
+    let verdict = FAIL;
+    let detail;
+    if (!result.reached) {
+      detail = result.detail;
+    } else if (result.status === 401) {
+      const challenge = headerValue(result.headers, "www-authenticate");
+      if (challenge && /resource_metadata=/i.test(challenge)) {
+        verdict = PASS;
+        detail = "401 + WWW-Authenticate challenge advertises the protected-resource metadata";
+      } else if (challenge) {
+        verdict = WARN;
+        detail = "401 but the WWW-Authenticate challenge omits resource_metadata (clients cannot auto-discover the AS)";
+      } else {
+        verdict = WARN;
+        detail = "401 but no WWW-Authenticate header (clients cannot auto-discover the AS)";
+      }
+    } else if (result.status === 200) {
+      detail = "CRITICAL: unauthenticated /mcp returned 200 — the resource server is NOT enforcing authentication";
+    } else {
+      detail = `expected 401, got HTTP ${result.status}`;
+    }
+    probes.push({
+      id: "mcp_enforcement",
+      label: "Unauthenticated /mcp is rejected",
+      url,
+      status: result.status,
+      verdict,
+      detail,
+    });
+  }
+
+  const ok = probes.every((probe) => probe.verdict !== FAIL);
+  return { apiBaseUrl: base, ok, probes };
+}

package/src/scan/generator.js

@@ -498,7 +498,7 @@ export function buildSecretSetupInstructions(
     `- gh secret set ${normalizedSecret} --repo ${resolvedRepoSlug}`,
     `- Verify secret visibility: gh secret list --repo ${resolvedRepoSlug}`,
     "- Commit and push .github/workflows/omar-gate.yml",
-    "- For manual setup: https://sentinelayer.com/docs/getting-started/install-workflow",
+    "- For manual setup: https://github.com/mrrCarter/create-sentinelayer#manual-fallback-if-auto-injection-is-skipped",
   ];
 }
 

package/src/session/recap.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import fsp from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
@@ -72,6 +73,25 @@ function normalizePositiveInteger(value, fallbackValue) {
   return Math.max(1, Math.floor(normalized));
 }
 
+function buildWorkPlanSourceContext(targetPath = process.cwd(), { sourceReason = "caller_target_path" } = {}) {
+  const workspacePath = path.resolve(String(targetPath || "."));
+  const workspaceLabel = normalizeString(path.basename(workspacePath)) || ".";
+  const workspaceFingerprint = createHash("sha256")
+    .update(workspacePath)
+    .digest("hex")
+    .slice(0, 8);
+  const sourceLabel = `${WORK_PLAN_RELATIVE_PATH} from ${workspaceLabel}#${workspaceFingerprint}`;
+  return {
+    workspacePath,
+    filePath: path.join(workspacePath, WORK_PLAN_RELATIVE_PATH),
+    path: WORK_PLAN_RELATIVE_PATH,
+    workspaceLabel,
+    workspaceFingerprint,
+    sourceLabel,
+    sourceReason: normalizeString(sourceReason),
+  };
+}
+
 function toEpoch(value, fallbackIso = new Date().toISOString()) {
   return Date.parse(normalizeIsoTimestamp(value, fallbackIso)) || 0;
 }
@@ -407,9 +427,13 @@ function emptyTaskLedgerSummary() {
   };
 }
 
-function emptyWorkPlanSummary() {
+function emptyWorkPlanSummary(sourceContext = {}) {
   return {
-    path: WORK_PLAN_RELATIVE_PATH,
+    path: normalizeString(sourceContext.path) || WORK_PLAN_RELATIVE_PATH,
+    workspaceLabel: normalizeString(sourceContext.workspaceLabel),
+    workspaceFingerprint: normalizeString(sourceContext.workspaceFingerprint),
+    sourceLabel: normalizeString(sourceContext.sourceLabel),
+    sourceReason: normalizeString(sourceContext.sourceReason),
     exists: false,
     truncated: false,
     detailSuppressed: false,
@@ -434,8 +458,11 @@ function shortWorkPlanText(value) {
   return `${text.slice(0, 97)}...`;
 }
 
-function summarizeWorkPlanMarkdown(raw = "", { limit = DEFAULT_WORK_PLAN_SUMMARY_LIMIT, truncated = false } = {}) {
-  const summary = emptyWorkPlanSummary();
+function summarizeWorkPlanMarkdown(
+  raw = "",
+  { limit = DEFAULT_WORK_PLAN_SUMMARY_LIMIT, truncated = false, sourceContext = {} } = {}
+) {
+  const summary = emptyWorkPlanSummary(sourceContext);
   summary.exists = true;
   summary.truncated = Boolean(truncated);
   if (summary.truncated) {
@@ -487,15 +514,19 @@ function summarizeWorkPlanMarkdown(raw = "", { limit = DEFAULT_WORK_PLAN_SUMMARY
   return summary;
 }
 
-async function readWorkPlanSummary({ targetPath = process.cwd(), limit = DEFAULT_WORK_PLAN_SUMMARY_LIMIT } = {}) {
-  const filePath = path.join(path.resolve(String(targetPath || ".")), WORK_PLAN_RELATIVE_PATH);
+async function readWorkPlanSummary({
+  targetPath = process.cwd(),
+  limit = DEFAULT_WORK_PLAN_SUMMARY_LIMIT,
+  sourceReason = "caller_target_path",
+} = {}) {
+  const sourceContext = buildWorkPlanSourceContext(targetPath, { sourceReason });
   try {
-    const stats = await fsp.stat(filePath);
+    const stats = await fsp.stat(sourceContext.filePath);
     let source = "";
     let truncated = false;
     if (stats.size > MAX_WORK_PLAN_BYTES) {
       truncated = true;
-      const handle = await fsp.open(filePath, "r");
+      const handle = await fsp.open(sourceContext.filePath, "r");
       try {
         const buffer = Buffer.alloc(MAX_WORK_PLAN_BYTES);
         const position = Math.max(0, stats.size - MAX_WORK_PLAN_BYTES);
@@ -505,14 +536,18 @@ async function readWorkPlanSummary({ targetPath = process.cwd(), limit = DEFAULT
         await handle.close();
       }
     } else {
-      source = await fsp.readFile(filePath, "utf-8");
+      source = await fsp.readFile(sourceContext.filePath, "utf-8");
     }
-    return summarizeWorkPlanMarkdown(source, { limit, truncated });
+    return summarizeWorkPlanMarkdown(source, {
+      limit,
+      truncated,
+      sourceContext,
+    });
   } catch (error) {
     if (error && typeof error === "object" && error.code === "ENOENT") {
-      return emptyWorkPlanSummary();
+      return emptyWorkPlanSummary(sourceContext);
     }
-    return emptyWorkPlanSummary();
+    return emptyWorkPlanSummary(sourceContext);
   }
 }
 
@@ -733,9 +768,24 @@ function buildWorkPlanText(workPlan = emptyWorkPlanSummary()) {
   }
   const open = Number(workPlan.open || 0);
   const completed = Number(workPlan.completed || 0);
-  const pathText = normalizeString(workPlan.path) || WORK_PLAN_RELATIVE_PATH;
+  const sourceText =
+    normalizeString(workPlan.sourceLabel) ||
+    (() => {
+      const pathText = normalizeString(workPlan.path) || WORK_PLAN_RELATIVE_PATH;
+      const workspaceLabel = normalizeString(workPlan.workspaceLabel);
+      const workspaceFingerprint = normalizeString(workPlan.workspaceFingerprint);
+      if (!workspaceLabel) {
+        return pathText;
+      }
+      const workspaceText = workspaceFingerprint
+        ? `${workspaceLabel}#${workspaceFingerprint}`
+        : workspaceLabel;
+      return `${pathText} from ${workspaceText}`;
+    })();
+  const sourceReason = normalizeString(workPlan.sourceReason);
+  const sourceReasonText = sourceReason ? ` (${sourceReason})` : "";
   if (workPlan.detailSuppressed || workPlan.truncated) {
-    return `Plan: ${open} open / ${completed} done in recent ${pathText} window. Current/next items suppressed because the plan file is large.`;
+    return `Plan: ${open} open / ${completed} done in recent ${sourceText} window${sourceReasonText}. Current/next items suppressed because the plan file is large.`;
   }
   const currentSection = normalizeString(workPlan.currentSection);
   const currentText = currentSection ? ` Current: ${currentSection}.` : "";
@@ -752,7 +802,7 @@ function buildWorkPlanText(workPlan = emptyWorkPlanSummary()) {
           .join("; ")}.`
       : "";
   const truncatedText = workPlan.truncated ? " Recent window only." : "";
-  return `Plan: ${open} open / ${completed} done in ${pathText}.${currentText}${nextText}${truncatedText}`;
+  return `Plan: ${open} open / ${completed} done in ${sourceText}${sourceReasonText}.${currentText}${nextText}${truncatedText}`;
 }
 
 function roundCurrency(value) {
@@ -911,6 +961,12 @@ export async function buildSessionRecap(
   } catch {
     sessionMetadata = null;
   }
+  const sessionWorkspaceTargetPath = path.resolve(
+    normalizeString(sessionMetadata?.targetPath) || normalizedTargetPath,
+  );
+  const workPlanSourceReason = normalizeString(sessionMetadata?.targetPath)
+    ? "session_metadata_target_path"
+    : "caller_target_path";
   const sortedEvents = sortEventsByConversationTime(dedupeSessionEvents(allEvents), normalizedNow);
   const usageSummary = normalizeUsageSummary(sortedEvents);
   const events = sortedEvents.slice(-normalizedMaxEvents);
@@ -955,7 +1011,8 @@ export async function buildSessionRecap(
     targetPath: normalizedTargetPath,
   });
   const workPlan = await readWorkPlanSummary({
-    targetPath: normalizedTargetPath,
+    targetPath: sessionWorkspaceTargetPath,
+    sourceReason: workPlanSourceReason,
   });
   const snippets = summarizeRecentActivity(actorEvents, {
     forAgentId: normalizedForAgentId,

package/src/session/remote-hydrate.js

@@ -38,6 +38,7 @@ import { isSessionControlEvent } from "./control-events.js";
 const EVENTS_CURSOR_SUFFIX = "events";
 const DEFAULT_EVENT_PAGE_LIMIT = 200;
 const DEFAULT_MAX_EVENT_PAGES = 25;
+const MAX_APPEND_FAILURE_REASON_LENGTH = 160;
 
 function indexRelayEventIdentityKeys(indexByKey, eventList = [], event = {}, index = -1) {
   if (!indexByKey || !Array.isArray(eventList) || index < 0) return;
@@ -163,6 +164,28 @@ function normalizePositiveInteger(value, fallbackValue) {
   return Math.floor(normalized);
 }
 
+function localAppendFailureReason(error) {
+  const message = error?.message || String(error || "");
+  let reason = String(message).trim();
+  if (!reason) return "local_append_failed";
+  reason = reason.replace(
+    /(["'])(?:[A-Za-z]:\\|\/(?:Users|home|tmp|var|private|mnt|workspace)\/).*?\1/g,
+    "$1[path]$1",
+  );
+  reason = reason.replace(/[A-Za-z]:\\[^,;\r\n)]+/g, "[path]");
+  reason = reason.replace(/(^|[\s"'(])\/(?:Users|home|tmp|var|private|mnt|workspace)\/[^\s,;)"']+/g, "$1[path]");
+  reason = reason.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]");
+  reason = reason.replace(
+    /\b([A-Za-z0-9_-]*(?:api[_-]?key|authorization|password|secret|token)[A-Za-z0-9_-]*)\s*[:=]\s*(?:"[^"]+"|'[^']+'|[^\s,;]+)/gi,
+    "$1=[REDACTED]",
+  );
+  reason = reason.replace(/\b[A-Za-z0-9._~+/=-]{32,}\b/g, "[REDACTED]");
+  if (reason.length > MAX_APPEND_FAILURE_REASON_LENGTH) {
+    reason = `${reason.slice(0, MAX_APPEND_FAILURE_REASON_LENGTH - 3)}...`;
+  }
+  return reason || "local_append_failed";
+}
+
 async function pollSessionEventPages({
   sessionId,
   targetPath,
@@ -436,6 +459,8 @@ export async function hydrateSessionFromRemote({
     mergeExisting: eventsNeedingMerge.has(event),
   }));
   const failedRelayKeys = new Set();
+  let appendFailureCount = 0;
+  let appendFailureReason = "";
   for (const { event, mergeExisting } of appendEvents) {
     try {
       const persisted = await _append(sessionId, event, {
@@ -453,7 +478,11 @@ export async function hydrateSessionFromRemote({
         persistedEvent,
         existingRelayEvents.length - 1,
       );
-    } catch {
+    } catch (error) {
+      appendFailureCount += 1;
+      if (!appendFailureReason) {
+        appendFailureReason = localAppendFailureReason(error);
+      }
       addSessionEventIdentityKeys(failedRelayKeys, event);
       // Append errors are observable via the stream but should not
       // abort the rest of the batch — partial relay is still progress.
@@ -492,6 +521,8 @@ export async function hydrateSessionFromRemote({
     eventsBackfillReason: eventsResult?.complete === false ? eventsResult?.reason || "" : "",
     materializedLocalSession,
     localAppendComplete: humanCursorSafe && eventsCursorSafe,
+    appendFailureCount,
+    appendFailureReason,
     remoteStatus: remoteStatus || null,
   };
 }

package/src/session/store.js

@@ -407,6 +407,7 @@ export function isSessionCacheExpired(metadata, nowIso = new Date().toISOString(
 function buildSessionPayload(metadata, paths, nowIso = new Date().toISOString()) {
   return {
     sessionId: metadata.sessionId,
+    targetPath: metadata.targetPath,
     sessionDir: paths.sessionDir,
     metadataPath: paths.metadataPath,
     streamPath: paths.streamPath,