@mrciphersmith/keryx 0.2.128 → 0.2.131

package/dist/cli.js

@@ -24338,6 +24338,49 @@ var init_trusted_wrap_up = __esm(() => {
   consumed = new WeakSet;
 });
 
+// src/sac/workspace-reference.ts
+function requireWorkspaceReference(raw) {
+  const normalized = normalizeWorkspaceReference(raw);
+  if (!normalized.ok)
+    throw new Error(normalized.reason);
+  return normalized.uri;
+}
+function normalizeWorkspaceReference(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, reason: 'a workspace reference must be a non-empty workspace-relative path, e.g. "./src/harness/search"' };
+  }
+  if (UNSAFE_ABSOLUTE.test(trimmed) || UNSAFE_SCHEME.test(trimmed) || trimmed.includes("\\")) {
+    return {
+      ok: false,
+      reason: `"${trimmed}" is not a workspace-relative path \u2014 an absolute path, a URL and a Windows path are all refused. Use a path inside the project, e.g. "./src/harness/search".`
+    };
+  }
+  const withoutDotSlash = trimmed.startsWith("./") ? trimmed.slice(2) : trimmed;
+  const withoutTrailingSlash = withoutDotSlash.replace(/\/+$/, "");
+  if (withoutTrailingSlash.length === 0) {
+    return { ok: false, reason: `"${trimmed}" names the project root rather than a path inside it \u2014 name a directory or file, e.g. "./src/harness/search".` };
+  }
+  const segments = withoutTrailingSlash.split("/");
+  if (segments.includes("..") || segments.includes(".")) {
+    return { ok: false, reason: `"${trimmed}" contains a "." or ".." path segment \u2014 a workspace reference must stay inside the project.` };
+  }
+  const uri = `./${withoutTrailingSlash}`;
+  if (!WORKSPACE_REFERENCE_PATTERN.test(uri)) {
+    return {
+      ok: false,
+      reason: `"${trimmed}" is not a usable workspace reference. The stored form is "${uri}" if the characters are the problem: ` + 'each path segment may contain only letters, digits, ".", "_" and "-", and no ".." segment is allowed.'
+    };
+  }
+  return { ok: true, uri };
+}
+var WORKSPACE_REFERENCE_PATTERN, UNSAFE_ABSOLUTE, UNSAFE_SCHEME;
+var init_workspace_reference = __esm(() => {
+  WORKSPACE_REFERENCE_PATTERN = /^\.\/(?!(?:.*\/)?\.\.(?:\/|$))(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+  UNSAFE_ABSOLUTE = /^[/\\]/;
+  UNSAFE_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+});
+
 // src/sac/index.ts
 import { access as access2, readFile as readFile50, realpath as realpath6 } from "fs/promises";
 import { createHash as createHash18 } from "crypto";
@@ -25085,11 +25128,12 @@ async function evaluateStrictSacGuard(input) {
 }
 var idPattern, subjectPattern, revisionPattern, correlationPattern, workspacePathPattern, receiptHashPattern, utcPattern, forbiddenPayloadKeys, normativeSchemaFiles, normativeSchemas, NORMATIVE_SCHEMA_DIR, SacReferenceError, trustedActors, roleRank;
 var init_sac = __esm(() => {
+  init_workspace_reference();
   idPattern = /^[a-z][a-z0-9-]{2,63}$/;
   subjectPattern = /^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$/;
   revisionPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
   correlationPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{15,255}$/;
-  workspacePathPattern = /^\.\/(?!.*(?:^|\/)\.\.(?:\/|$))(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+  workspacePathPattern = WORKSPACE_REFERENCE_PATTERN;
   receiptHashPattern = /^[a-f0-9]{64}$/;
   utcPattern = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?Z$/;
   forbiddenPayloadKeys = new Set(["prompt", "transcript", "hiddenReasoning", "secret", "secrets", "rawContent"]);
@@ -51085,7 +51129,7 @@ import path47 from "path";
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.128",
+  version: "0.2.131",
   description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   private: false,
   publishConfig: {
@@ -78293,6 +78337,7 @@ function toMcpTools(ops = METAPROJECT_OPERATIONS, adapterFor = (cwd) => createMe
 }
 
 // src/sac/fwk-service.ts
+init_workspace_reference();
 init_assembly();
 init_sac();
 init_workspace_service();
@@ -78303,6 +78348,7 @@ import { appendFile as appendFile7, mkdir as mkdir59, open as open2, readFile as
 import path174 from "path";
 
 // src/sac/policy-experiment.ts
+init_workspace_reference();
 import { createHash as createHash34, createHmac as createHmac2 } from "crypto";
 
 // src/sac/receipt-integrity.ts
@@ -78366,7 +78412,7 @@ function stableValue(value) {
 }
 var stableJson2 = (value) => JSON.stringify(stableValue(value));
 var sha2564 = (value) => createHash34("sha256").update(stableJson2(value), "utf8").digest("hex");
-var workspacePathPattern2 = /^\.\/(?!.*(?:^|\/)\.\.(?:\/|$))(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+var workspacePathPattern2 = WORKSPACE_REFERENCE_PATTERN;
 var trustedOutcomes = new WeakMap;
 var trustedSandboxEvidence = new WeakMap;
 var trustedSandboxExecutions = new WeakMap;
@@ -78458,7 +78504,7 @@ var metadataOnly = (value) => {
 var nowIso2 = (now) => now().toISOString();
 var reportHashPattern = /^[a-f0-9]{64}$/;
 var immutableVersionPattern = /(?:^|[-_.:])(?:latest|next|head|main|develop)(?:$|[-_.:])/i;
-var workspacePathPattern3 = /^\.\/(?!.*(?:^|\/)\.\.(?:\/|$))(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+var workspacePathPattern3 = WORKSPACE_REFERENCE_PATTERN;
 var policyExperimentConfigPath = [".metaproject", "context-operations", "policy-experiment", "config.json"];
 var stableValue2 = (value) => {
   if (Array.isArray(value))
@@ -79333,6 +79379,7 @@ async function reclaimStaleExternalSlates(cwd, now = () => new Date) {
 init_slate();
 init_workspace_resolve();
 init_redact();
+init_workspace_reference();
 
 // src/mcp/tools.ts
 import { randomUUID as randomUUID19 } from "crypto";
@@ -79545,7 +79592,8 @@ function buildToolRegistry() {
         const title = stringParam2(params, "title")?.trim() ?? "";
         if (title.length === 0)
           throw new Error("sac.workspaceCreate requires a non-empty 'title'");
-        const component = stringParam2(params, "component");
+        const rawComponent = stringParam2(params, "component");
+        const component = rawComponent === undefined ? undefined : requireWorkspaceReference(rawComponent);
         const workspace = await sacWorkspaceService(cwd).create({ request: undefined, requestCorrelationId: randomUUID19(), id: newWorkspaceId(), title, ...component ? { component: { kind: "component", uri: component } } : {} });
         return workspace;
       }
@@ -85129,6 +85177,8 @@ function busInboxFullNotice(droppedTotal) {
   return `bus: inbox full \u2014 ${droppedTotal} older message(s) dropped
 `;
 }
+var BUS_WAKE_CAPPED_NOTICE = `\u25C7 a peer message arrived; automatic wakes are capped, so it will be delivered with your next message.
+`;
 function createLeaseHoldController(opts) {
   let wasHeld = false;
   return {
@@ -86977,7 +87027,8 @@ class SandboxedWebTransport {
       ...request.body !== undefined ? { body: request.body } : {},
       ...request.credential !== undefined ? { credential: request.credential } : {},
       ...request.signal !== undefined ? { signal: request.signal } : {},
-      localOnly: request.capability === "local-search"
+      localOnly: request.capability === "local-search",
+      browserHeaders: request.capability === "public-search"
     });
     if (!raw.ok) {
       return {
@@ -87024,7 +87075,8 @@ class SandboxedWebTransport {
         address: target.value.address,
         method: request.method,
         ...request.body !== undefined ? { body: request.body } : {},
-        ...request.credential !== undefined ? { credential: request.credential } : {}
+        ...request.credential !== undefined ? { credential: request.credential } : {},
+        ...request.browserHeaders === true ? { browserHeaders: true } : {}
       }, request.signal);
       if (!worker.ok)
         return worker;
@@ -87062,6 +87114,54 @@ import { existsSync as existsSync29 } from "fs";
 import { homedir as homedir7 } from "os";
 var WORKER_TIMEOUT_MS = 1e4;
 var MAX_WORKER_OUTPUT_BYTES = 192000;
+var BROWSER_USER_AGENTS = [
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+  "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:133.0) Gecko/20100101 Firefox/133.0",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:133.0) Gecko/20100101 Firefox/133.0",
+  "Mozilla/5.0 (X11; Linux x86_64; rv:132.0) Gecko/20100101 Firefox/132.0",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.1 Safari/605.1.15",
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0"
+];
+var BROWSER_ACCEPT_LANGUAGES = [
+  "en-US,en;q=0.9",
+  "en-US,en;q=0.9,ru;q=0.8",
+  "en-GB,en;q=0.9,en-US;q=0.8",
+  "ru-RU,ru;q=0.9,en-US;q=0.8,en;q=0.7",
+  "en-CA,en;q=0.9,en-US;q=0.8"
+];
+var BROWSER_ACCEPT = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8";
+var BROWSER_STATIC_HEADERS = {
+  "accept-encoding": "identity",
+  connection: "keep-alive",
+  "upgrade-insecure-requests": "1",
+  "sec-fetch-dest": "document",
+  "sec-fetch-mode": "navigate",
+  "sec-fetch-site": "none",
+  "sec-fetch-user": "?1",
+  "cache-control": "max-age=0"
+};
+var BROWSER_HEADERS_SOURCE = [
+  "(function (random) {",
+  "  var userAgents = " + JSON.stringify(BROWSER_USER_AGENTS) + ";",
+  "  var acceptLanguages = " + JSON.stringify(BROWSER_ACCEPT_LANGUAGES) + ";",
+  "  var staticHeaders = " + JSON.stringify(BROWSER_STATIC_HEADERS) + ";",
+  "  var pick = function (list) {",
+  "    var value = list[Math.floor(random() * list.length)];",
+  "    return value === undefined ? list[0] : value;",
+  "  };",
+  "  var headers = {",
+  "    accept: " + JSON.stringify(BROWSER_ACCEPT) + ",",
+  '    "accept-language": pick(acceptLanguages),',
+  '    "user-agent": pick(userAgents),',
+  "  };",
+  "  for (var name in staticHeaders) { headers[name] = staticHeaders[name]; }",
+  '  if (random() < 0.5) headers.dnt = "1";',
+  "  return headers;",
+  "})"
+].join(`
+`);
 var WORKER_SOURCE = String.raw`
 const { request: httpsRequest } = await import("node:https");
 const { request: httpRequest } = await import("node:http");
@@ -87070,7 +87170,10 @@ const input = JSON.parse(await Bun.stdin.text());
 const fail = () => process.stdout.write(JSON.stringify({ ok: false, reason: "request failed or timed out" }));
 try {
   const timer = setTimeout(() => req.destroy(new Error("timeout")), input.timeoutMs);
-  const headers = { accept: "text/html, text/plain, application/json, application/xml, application/xhtml+xml" };
+  const browserHeaders = ${BROWSER_HEADERS_SOURCE};
+  const headers = input.browserHeaders
+    ? browserHeaders(Math.random)
+    : { accept: "text/html, text/plain, application/json, application/xml, application/xhtml+xml" };
   const payload = input.body && typeof input.body === "object" ? { ...input.body } : undefined;
   if (input.credential && input.credential.injection === "header") headers[input.credential.name] = input.credential.value;
   if (input.credential && input.credential.injection === "json-body") {
@@ -87294,7 +87397,7 @@ function webSearchTool(service) {
       const response = await service.search(input.query.trim());
       if (!response.ok) {
         return {
-          output: response.reason === "no-active-provider" ? "web_search: no active connected provider. Use /search-provider to configure one, test it, then use /search-connect to select it." : response.reason === "search-failed" ? "web_search: search failed. Retry later; do not switch providers yourself." : "web_search: active provider is unavailable; reconnect it with /search-provider before retrying.",
+          output: response.reason === "no-active-provider" ? "web_search: no active connected provider. Use /search-provider to configure one, test it, then use /search-connect to select it." : response.reason === "search-failed" ? `web_search: search failed${response.detail !== undefined && response.detail.length > 0 ? ` (${response.detail})` : ""}. Wait a few minutes before trying again, and do not switch providers yourself.` : "web_search: active provider is unavailable; reconnect it with /search-provider before retrying.",
           isError: true
         };
       }
@@ -87412,7 +87515,12 @@ function workspaceCreateTool(cwd, getSessionDir) {
       const title = typeof input.title === "string" ? input.title.trim() : "";
       if (title.length === 0)
         return { output: "workspace_create requires a non-empty 'title'", isError: true };
-      const component = typeof input.component === "string" && input.component.length > 0 ? input.component : undefined;
+      const rawComponent = typeof input.component === "string" && input.component.length > 0 ? input.component : undefined;
+      const normalizedComponent = rawComponent === undefined ? undefined : normalizeWorkspaceReference(rawComponent);
+      if (normalizedComponent !== undefined && !normalizedComponent.ok) {
+        return { output: "workspace_create: " + normalizedComponent.reason, isError: true };
+      }
+      const component = normalizedComponent?.ok === true ? normalizedComponent.uri : undefined;
       try {
         const workspace = await service5(cwd).create({
           request: undefined,
@@ -88096,7 +88204,7 @@ function rememberExactShellGrant(command, sessionAllow, options) {
   if (!offerExact) {
     return "";
   }
-  const stored = allowShellPattern(exact);
+  const stored = allowShellPattern(exact, options?.dir);
   if (stored.length > 0) {
     sessionAllow.add(stored);
   }
@@ -88250,8 +88358,14 @@ var ANOMALY_MARKERS = [
   "/anomaly.js",
   "Unfortunately, bots use DuckDuckGo too"
 ];
-var MIN_GAP_MS = 500;
-var MAX_GAP_MS = 2000;
+var MIN_GAP_MS = 4000;
+var MAX_GAP_MS = 8000;
+var DUCKDUCKGO_ANOMALY_BACKOFF_MS = [5000, 20000];
+var timing = {
+  minGapMs: MIN_GAP_MS,
+  maxGapMs: MAX_GAP_MS,
+  backoffMs: DUCKDUCKGO_ANOMALY_BACKOFF_MS
+};
 var lastSearchAt = 0;
 function duckduckgoLiteUrl(query) {
   return `${DUCKDUCKGO_LITE_ORIGIN}?q=${encodeURIComponent(query)}`;
@@ -88267,7 +88381,8 @@ async function maybeDelayDuckDuckGoSearch(signal) {
     lastSearchAt = now;
     return;
   }
-  const gap = MIN_GAP_MS + Math.floor(Math.random() * (MAX_GAP_MS - MIN_GAP_MS + 1));
+  const { minGapMs, maxGapMs } = timing;
+  const gap = minGapMs + Math.floor(Math.random() * Math.max(0, maxGapMs - minGapMs + 1));
   const wait = gap - (now - lastSearchAt);
   if (wait > 0)
     await sleep2(wait, signal);
@@ -88387,6 +88502,30 @@ function sleep2(ms, signal) {
     signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
+async function waitDuckDuckGoBackoff(attempt, signal) {
+  const wait = timing.backoffMs[attempt];
+  if (wait === undefined)
+    return false;
+  if (wait > 0)
+    await sleep2(wait, signal);
+  return true;
+}
+
+// src/harness/search/connection-message.ts
+function describeConnectionFailure(reason) {
+  switch (reason) {
+    case "missing-credential":
+      return "missing credential";
+    case "rate-limited":
+      return "rate limited \u2014 the provider served its bot page to this machine; retrying will not help";
+    case "incompatible-response":
+      return "the endpoint answered, but not with search results";
+    case "transport-failed":
+    default:
+      return "connection validation failed";
+  }
+}
+var RATE_LIMITED_SEARCH_ERROR = "rate limited: DuckDuckGo served its bot-check page instead of results, even after retrying. Do not retry or rephrase; wait a few minutes or fetch a known URL directly";
 
 // src/harness/search/registry.ts
 var SEARXNG_DOCS_URL = "https://docs.searxng.org/admin/installation.html";
@@ -88497,29 +88636,31 @@ function createSearchProviderRegistry(transport, resolveCredential = () => {
         query: DUCKDUCKGO_HEALTHCHECK_QUERY
       });
       if (isDuckDuckGoAnomaly(response.status, response.text))
-        return { ok: false, reason: "transport-failed" };
+        return { ok: false, reason: "rate-limited" };
       if (!response.ok || response.status < 200 || response.status >= 300)
         return requestFailure(response);
       const parsed = duckduckgoSearchResponse(DUCKDUCKGO_HEALTHCHECK_QUERY, response.text);
-      return parsed.ok ? { ok: true } : { ok: false, reason: "transport-failed" };
+      return parsed.ok ? { ok: true } : { ok: false, reason: "rate-limited" };
     },
     async search(_fields, query, signal) {
-      await maybeDelayDuckDuckGoSearch(signal);
-      const response = await transport.request({
-        providerId: "duckduckgo",
-        capability: "public-search",
-        url: duckduckgoLiteUrl(query),
-        method: "GET",
-        query,
-        ...signal ? { signal } : {}
-      });
-      if (isDuckDuckGoAnomaly(response.status, response.text)) {
-        throw new Error("DuckDuckGo rate-limited this machine");
+      for (let attempt = 0;; attempt += 1) {
+        await maybeDelayDuckDuckGoSearch(signal);
+        const response = await transport.request({
+          providerId: "duckduckgo",
+          capability: "public-search",
+          url: duckduckgoLiteUrl(query),
+          method: "GET",
+          query,
+          ...signal ? { signal } : {}
+        });
+        const parsed = duckduckgoSearchResponse(query, response.text);
+        if (!isDuckDuckGoAnomaly(response.status, response.text) && parsed.ok) {
+          return parsed.value;
+        }
+        if (!await waitDuckDuckGoBackoff(attempt, signal)) {
+          throw new Error(RATE_LIMITED_SEARCH_ERROR);
+        }
       }
-      const parsed = duckduckgoSearchResponse(query, response.text);
-      if (!parsed.ok)
-        throw new Error("DuckDuckGo rate-limited this machine");
-      return parsed.value;
     }
   };
   const searxng = {
@@ -88751,8 +88892,12 @@ class SearchProviderController {
       return { ok: false, reason: "no-active-provider" };
     try {
       return { ok: true, value: await descriptor.search(stored?.fields ?? {}, query, signal) };
-    } catch {
-      return { ok: false, reason: "search-failed" };
+    } catch (error) {
+      return {
+        ok: false,
+        reason: "search-failed",
+        ...error instanceof Error && error.message.length > 0 ? { detail: error.message } : {}
+      };
     }
   }
   config() {
@@ -93181,14 +93326,25 @@ async function classifySession(session) {
         sessionId: session.id,
         ...workspaceId !== undefined ? { workspaceId } : {},
         lastSeenAt: session.updatedAt,
+        reason: "wrap-up-failed",
         wrapUpOutcome: { trigger: wrapUpOutcome.trigger, generatedAt: wrapUpOutcome.generatedAt, groups: wrapUpOutcome.groups }
       }
     };
   }
   if (!await isSlateEngaged(dir))
     return;
-  const workspaceId = (await safeReadSlate(dir))?.workspaceId;
-  return { kind: "unknown", item: { type: "unknown", sessionId: session.id, ...workspaceId !== undefined ? { workspaceId } : {}, lastSeenAt: session.updatedAt } };
+  const slateRead = await readSlateState(dir);
+  const workspaceId = slateRead.state === "ok" ? slateRead.slate.workspaceId : undefined;
+  return {
+    kind: "unknown",
+    item: {
+      type: "unknown",
+      sessionId: session.id,
+      ...workspaceId !== undefined ? { workspaceId } : {},
+      lastSeenAt: session.updatedAt,
+      reason: slateRead.state === "unreadable" ? "slate-unreadable" : "no-resolution-recorded"
+    }
+  };
 }
 async function readExternalUnboundCandidates(cwd) {
   const extDir = externalSlatesDir(cwd);
@@ -93441,6 +93597,17 @@ async function isSlateEngaged(dir) {
     return false;
   }
 }
+async function readSlateState(dir) {
+  try {
+    const slate = await readSlate(dir);
+    return slate === undefined ? { state: "absent" } : { state: "ok", slate };
+  } catch (error) {
+    return isNotFound2(error) ? { state: "absent" } : { state: "unreadable" };
+  }
+}
+function isNotFound2(error) {
+  return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
 async function safeReadSlate(dir) {
   try {
     return await readSlate(dir);
@@ -94114,6 +94281,15 @@ function mountEmptyTranscriptSplash(otui, r, transcript) {
     transcript.remove(box);
   };
 }
+function createSplashLifecycle(opts) {
+  let remove = opts.initialHistoryLength === 0 ? opts.mount() : undefined;
+  return {
+    removeIfShown() {
+      remove?.();
+      remove = undefined;
+    }
+  };
+}
 
 // src/tui/workspace-inspector.ts
 var WORKSPACE_COMMAND = "/workspace";
@@ -94397,7 +94573,7 @@ function summarizeReviewItem(item) {
     case "unbound-candidate":
       return `${item.sessionId} \u2014 ${item.summary}`;
     case "unknown":
-      return `${item.sessionId} \u2014 last seen ${item.lastSeenAt}`;
+      return `${item.sessionId} \u2014 ${unknownReasonLabel(item.reason)} (last seen ${item.lastSeenAt})`;
   }
 }
 function formatReviewListLines(items, selected) {
@@ -94409,6 +94585,26 @@ function formatReviewListLines(items, selected) {
     return `${mark} ${TYPE_LABEL[item.type].padEnd(8)} ${summarizeReviewItem(item)}`;
   });
 }
+function unknownReasonLabel(reason) {
+  switch (reason) {
+    case "wrap-up-failed":
+      return "wrap-up failed";
+    case "slate-unreadable":
+      return "slate.json unreadable";
+    case "no-resolution-recorded":
+      return "no resolution recorded";
+  }
+}
+function unknownReasonDetail(reason) {
+  switch (reason) {
+    case "wrap-up-failed":
+      return "a wrap-up dispatch ran and every group failed - the per-kind reasons are above where recorded; re-run wrap-up after fixing them.";
+    case "slate-unreadable":
+      return "this session's slate.json exists but could not be read. Its record is DAMAGED, not absent: inspect the file before assuming nothing happened.";
+    case "no-resolution-recorded":
+      return "Slate engagement with no proposal, terminal state, unbound-candidate or wrap-up-outcome artifact recorded.";
+  }
+}
 function describeReviewItem(item) {
   switch (item.type) {
     case "proposal":
@@ -94450,7 +94646,7 @@ function describeReviewItem(item) {
       ] : [
         `Session    ${item.sessionId}${item.workspaceId !== undefined ? `  (workspace ${item.workspaceId})` : ""}`,
         `Last seen  ${item.lastSeenAt}`,
-        "No proposal, terminal state, or unbound-candidate artifact recorded.",
+        "Why unknown: " + unknownReasonDetail(item.reason),
         "",
         `Investigate: keryx sessions list / keryx shell -r ${item.sessionId}`
       ];
@@ -101903,6 +102099,44 @@ function parseBusCommand(line) {
   return { kind: "error", reason: `unknown /bus subcommand "${first}"` };
 }
 
+// src/tui/bus-join.ts
+function decideJoinAdoption(input) {
+  if (input.disabled)
+    return "off";
+  if (input.destroyed)
+    return "leave";
+  return "adopt";
+}
+function buildBusJoinCallbacks(deps) {
+  return {
+    onEvent: (event) => {
+      if (deps.isDestroyed())
+        return;
+      deps.onSystemLine(`${formatBusEventLine(event)}
+`);
+      deps.pushToInbox({ ...event, body: event.body ?? "" });
+      deps.markDelivered();
+    },
+    onPeers: (peers) => {
+      if (deps.isDestroyed())
+        return;
+      deps.setFleetPeers(peers.map((peer) => ({
+        name: peer.record.name,
+        state: peer.state,
+        status: peer.record.status,
+        activity: peer.record.activity
+      })));
+      deps.paintFleet();
+      deps.onInboxSizeObserved();
+      deps.paintHoldBanner();
+      deps.onLeaseHoldPoll();
+      const delivered = deps.getDelivered();
+      deps.onBusWakePoll(delivered);
+      deps.resetDelivered();
+    }
+  };
+}
+
 // src/tui/shell-exit.ts
 function leaveBusThenRelease(holder) {
   holder.leaveBus();
@@ -102090,6 +102324,9 @@ var SIDE_WORKER_DENIED_TOOL_NAMES = new Set([
   "shell_job_output",
   "bus_send"
 ]);
+function isToolAvailableToSideWorker(tool) {
+  return tool.definition.risk === "read" && !SIDE_WORKER_DENIED_TOOL_NAMES.has(tool.definition.name);
+}
 function parseGitHubRemote(remote) {
   const trimmed = remote.trim();
   if (trimmed.length === 0) {
@@ -103057,7 +103294,7 @@ function runSearchProviderTestStep(otui, target, controller, provider, fields, c
       }
       if (!tested.ok) {
         settled = "failure";
-        const reason = tested.reason === "missing-credential" ? "missing credential" : "connection validation failed";
+        const reason = describeConnectionFailure(tested.reason);
         status.content = otui.t`${otui.red("\u2717")} ${otui.bold(`'${provider.id}' test failed: ${reason}`)} ${otui.dim("(Esc to go back and retry)")}`;
         return;
       }
@@ -104521,11 +104758,10 @@ async function launchTuiAgentShell(opts) {
     };
     deps = { ...deps, onContextCompaction };
     liveDeps = deps;
-    let removeSplash;
+    let splash = undefined;
     const applyOpened = (opened, previewHistory) => {
       if (opened.history.length > 0) {
-        removeSplash?.();
-        removeSplash = undefined;
+        splash?.removeIfShown();
       }
       liveSession = opened.handle;
       history = previewHistory === true ? opened.history.slice(-SESSION_PREVIEW_MESSAGE_COUNT) : opened.history;
@@ -104683,17 +104919,37 @@ async function launchTuiAgentShell(opts) {
       return true;
     }
     bindSlateToLiveSession();
-    if (history.length === 0) {
-      removeSplash = mountEmptyTranscriptSplash(otui, r, transcript);
-    }
+    splash = createSplashLifecycle({
+      mount: () => mountEmptyTranscriptSplash(otui, r, transcript),
+      initialHistoryLength: history.length
+    });
     if (viewedReadOnly) {
-      removeSplash?.();
-      removeSplash = undefined;
+      splash.removeIfShown();
     }
     refreshWorkspaceSidebar();
     refreshReviewSidebar();
     (async () => {
       try {
+        const { onEvent, onPeers } = buildBusJoinCallbacks({
+          isDestroyed: () => destroyed,
+          onSystemLine: (line) => io.onSystem?.(line),
+          pushToInbox: (event) => busInbox.push(event),
+          markDelivered: () => {
+            busPollDeliveredEvent = true;
+          },
+          setFleetPeers: (peers) => {
+            busFleetPeers = peers;
+          },
+          paintFleet,
+          onInboxSizeObserved: () => busDropNotifier.onInboxSizeObserved(busInbox.size),
+          paintHoldBanner,
+          onLeaseHoldPoll: () => leaseHoldController?.onPoll(),
+          onBusWakePoll: (delivered) => busWakeController?.onPoll(delivered),
+          getDelivered: () => busPollDeliveredEvent,
+          resetDelivered: () => {
+            busPollDeliveredEvent = false;
+          }
+        });
         const joined = await joinBus({
           cwd: sessionCwd,
           sessionId: liveSession.summary.id,
@@ -104708,37 +104964,15 @@ async function launchTuiAgentShell(opts) {
           }),
           onError: makeBusErrorReporter((line) => io.onSystem?.(`${line}
 `)),
-          onEvent: (event) => {
-            if (destroyed)
-              return;
-            io.onSystem?.(`${formatBusEventLine(event)}
-`);
-            busInbox.push({ ...event, body: event.body ?? "" });
-            busPollDeliveredEvent = true;
-          },
-          onPeers: (peers) => {
-            if (destroyed)
-              return;
-            busFleetPeers = peers.map((peer) => ({
-              name: peer.record.name,
-              state: peer.state,
-              status: peer.record.status,
-              activity: peer.record.activity
-            }));
-            paintFleet();
-            busDropNotifier.onInboxSizeObserved(busInbox.size);
-            paintHoldBanner();
-            leaseHoldController?.onPoll();
-            busWakeController?.onPoll(busPollDeliveredEvent);
-            busPollDeliveredEvent = false;
-          }
+          onEvent,
+          onPeers
         });
         if ("disabled" in joined) {
           io.onSystem?.(`bus: off (${joined.disabled})
 `);
           return;
         }
-        if (destroyed) {
+        if (decideJoinAdoption({ destroyed, disabled: false }) === "leave") {
           joined.leave();
           return;
         }
@@ -105560,7 +105794,7 @@ Staying in the current session.
           let answer = "";
           try {
             const base = await opts.makeAgentDeps(currentSel, liveSlateSession, undefined);
-            const tools = base.tools.filter((t) => t.definition.risk === "read" && !SIDE_WORKER_DENIED_TOOL_NAMES.has(t.definition.name));
+            const tools = base.tools.filter(isToolAvailableToSideWorker);
             const sideDeps = {
               ...base,
               tools,
@@ -105636,8 +105870,7 @@ Staying in the current session.
       suggestionGate.cancel("new turn started");
       if (origin === "operator") {
         consecutiveAutoWakes = 0;
-        removeSplash?.();
-        removeSplash = undefined;
+        splash?.removeIfShown();
       }
       const displayLine = summarizeSubmittedLine(line);
       if (chrome.isBusy()) {
@@ -105988,7 +106221,7 @@ Staying in the current session.
             searchProviderController.configure(providerId, { ...descriptor.defaults, ...args.fields }, args.credential);
             const tested = await searchProviderController.test(providerId);
             if (!tested.ok) {
-              const reason = tested.reason === "missing-credential" ? "missing credential" : "connection validation failed";
+              const reason = describeConnectionFailure(tested.reason);
               io.onSystem?.(`Configured '${providerId}' but it is not connected yet: ${reason}. Run /search-provider ${providerId} key=<value> to re-test.
 `);
               return;
@@ -106491,8 +106724,7 @@ Usage: /reasoning <${REASONING_EFFORT_LEVELS.join("|")}>
       cap: () => resolveMaxAutoWake(),
       runWake: () => runLine("", "bus-message"),
       printCapped: () => {
-        io.onSystem?.(`\u25C7 a peer message arrived; automatic wakes are capped, so it will be delivered with your next message.
-`);
+        io.onSystem?.(BUS_WAKE_CAPPED_NOTICE);
       },
       hasBusDeps: () => deps.busInbox !== undefined
     });
@@ -107987,8 +108219,8 @@ async function runAgentRepl(lines, rich, deps, metaprojectPort, sessionOpts, ini
     }
   };
   const searchProviderController = createDefaultSearchProviderController();
-  const sessionShellAllow = new Set(loadShellPermissions().allow);
-  let fingerprintAtStart = shellPermissionsFingerprint();
+  const sessionShellAllow = new Set(loadShellPermissions(configDir).allow);
+  let fingerprintAtStart = shellPermissionsFingerprint(configDir);
   let permissionMigrationShown = false;
   let permissionTamperShown = false;
   const iterator = lines[Symbol.asyncIterator]();
@@ -108225,10 +108457,11 @@ ${GUTTER}${style.yellow(`Run: ${evaled.command}`)} ${style.dim(prompt)}`);
       const approved = always || /^y(es)?$/i.test(answer);
       if (always && approved) {
         const stored = rememberExactShellGrant(evaled.command, sessionShellAllow, {
-          publishLease: evaled.publishLease
+          publishLease: evaled.publishLease,
+          ...configDir !== undefined ? { dir: configDir } : {}
         });
         if (stored.length > 0) {
-          fingerprintAtStart = shellPermissionsFingerprint();
+          fingerprintAtStart = shellPermissionsFingerprint(configDir);
         }
         out(stored.length > 0 ? style.green(`approved \xB7 remembered \u201C${stored}\u201D
 `) : style.yellow(`approved once \xB7 pattern cannot be remembered
@@ -108825,7 +109058,7 @@ ${GUTTER}${turnSeparator()}
         searchProviderController.configure(providerId, { ...descriptor.defaults, ...args.fields }, args.credential);
         const tested = await searchProviderController.test(providerId);
         if (!tested.ok) {
-          const reason = tested.reason === "missing-credential" ? "missing credential" : "connection validation failed";
+          const reason = describeConnectionFailure(tested.reason);
           agentIo.onSystem?.(`Configured '${providerId}' but it is not connected yet: ${reason}. Run /search-provider ${providerId} key=<value> to re-test.
 `);
           continue;
@@ -111528,8 +111761,8 @@ async function runServe(args) {
         resolve();
       });
     };
-    process.once("SIGINT", finish);
-    process.once("SIGTERM", finish);
+    process.on("SIGINT", finish);
+    process.on("SIGTERM", finish);
   });
 }
 function overlay(stored, parsed, port, runtimeAck) {
@@ -115790,7 +116023,8 @@ async function workspaceCommand(args) {
     if (subcommand === "create") {
       rejectUnknownOptions(args.slice(1), new Set(["--title", "--component"]));
       const title = optionValue(args, "--title");
-      const component = optionValue(args, "--component");
+      const rawComponent = optionValue(args, "--component");
+      const component = rawComponent === undefined ? undefined : requireWorkspaceReference(rawComponent);
       if (!title)
         throw new Error("Usage: keryx workspace create --title <title> [--component <workspace-relative-ref>]");
       const workspace = await service6().create({ request: undefined, requestCorrelationId: randomUUID40(), id: newWorkspaceId(), title, ...component ? { component: { kind: "component", uri: component } } : {} });
@@ -115819,11 +116053,11 @@ async function workspaceCommand(args) {
       rejectUnknownOptions(args.slice(2), new Set(["--kind", "--uri", "--revision"]));
       const workspaceId = args[1];
       const kind = optionValue(args, "--kind");
-      const uri = optionValue(args, "--uri");
+      const rawUri = optionValue(args, "--uri");
       const revision = optionValue(args, "--revision");
-      if (!workspaceId || !kind || !uri)
+      if (!workspaceId || !kind || !rawUri)
         throw new Error("Usage: keryx workspace add-resource <workspace-id> --kind <kind> --uri <workspace-relative-ref> [--revision <revision>]");
-      console.log(JSON.stringify(await service6().addResource({ request: undefined, requestCorrelationId: randomUUID40(), workspaceId, resource: { kind, uri, ...revision ? { revision } : {} } }), null, 2));
+      console.log(JSON.stringify(await service6().addResource({ request: undefined, requestCorrelationId: randomUUID40(), workspaceId, resource: { kind, uri: requireWorkspaceReference(rawUri), ...revision ? { revision } : {} } }), null, 2));
       return;
     }
     if (subcommand === "archive") {
@@ -116097,7 +116331,7 @@ function renderCatchUp(report, includeLifecycleFlags = true) {
   sections.push(renderSection("Pending proposals", report.proposals, (item) => `- Accept, reject, or dismiss ${item.kind} proposal ${item.proposalId} in workspace ${item.workspaceId}` + `${item.note !== undefined ? `: "${item.note}"` : ""}? ` + `Recommendation: ${item.fresh ? "evidence is fresh \u2014 review now (`keryx workspace review " + item.workspaceId + " " + item.proposalId + " --decision <accepted|rejected|dismissed>`)" : "evidence has drifted since this proposal was created \u2014 treat as stale, re-run wrap-up before deciding"}.`));
   sections.push(renderSection("Blocked sessions (stopped unattended)", report.blocked, (item) => `- Session ${item.sessionId} stopped unattended (${item.terminalState.reason}) at ${item.terminalState.occurredAt}. Resume it, or archive and move on? ` + `Recommendation: \`keryx shell -r ${item.sessionId}\` to resume and unblock it.`));
   sections.push(renderSection("Unbound candidates (wrap-up ran, no workspace bound)", report.unboundCandidates, (item) => `- Session ${item.sessionId} produced untriaged seeds with no workspace bound (${item.summary}). Bind to a workspace and propose, or discard? ` + `Recommendation: pick a workspace, then \`keryx workspace propose <workspace-id> --kind <kind> --session ${item.sessionId}\` (evidence: ${item.evidencePath}).`));
-  sections.push(renderSection("Unknown (no resolution recorded)", report.unknown, (item) => `- Session ${item.sessionId} was last seen ${item.lastSeenAt} with no proposal, terminal state, or unbound-candidate artifact recorded. Investigate, or ignore? ` + `Recommendation: \`keryx sessions list\` / \`keryx shell -r ${item.sessionId}\` to see what happened.`));
+  sections.push(renderSection("Unknown (no resolution recorded)", report.unknown, (item) => `- Session ${item.sessionId} was last seen ${item.lastSeenAt}: ${describeUnknownReason(item)}. Investigate, or ignore? ` + `Recommendation: \`keryx sessions list\` / \`keryx shell -r ${item.sessionId}\` to see what happened.`));
   sections.push(renderSection("Unreviewed SAC-owned changes (no proposal on record)", report.unreviewedPaths, (item) => `- Session ${item.sessionId} changed ${item.owner} path \`${item.path}\`${item.status !== undefined ? ` (Status: ${item.status})` : ""} at ${item.changedAt} with NO SAC proposal/receipt behind it \u2014 this looks like it bypassed review. Was this reviewed some other way, or should it be? ` + `Recommendation: \`keryx shell -r ${item.sessionId}\` to see what happened; if the content is good, route it through a real proposal (\`keryx workspace propose ...\`) before trusting it as durable knowledge.`));
   if (includeLifecycleFlags) {
     sections.push(renderSection("Lifecycle flags (component no longer in the graph)", report.lifecycleFlags, (item) => `- ${item.kind} \`${item.ref}\` scopes to \`${item.missingComponent}\`, which is no longer in the code graph (flagged ${item.flaggedAt}). Still relevant, or safe to clean up? ` + `Recommendation: this is report-only \u2014 nothing was archived/edited/removed automatically; ${item.kind === "workspace" ? "`keryx workspace archive " + item.ref + "`" : item.kind === "memory-entry" ? "`keryx memory supersede` or edit the entry directly" : "edit or remove the wiki page directly"} if you decide it's actually stale.`));
@@ -116106,6 +116340,16 @@ function renderCatchUp(report, includeLifecycleFlags = true) {
 
 `);
 }
+function describeUnknownReason(item) {
+  switch (item.reason) {
+    case "wrap-up-failed":
+      return "a wrap-up dispatch ran and every group failed (re-run it after fixing credentials/conflicts)";
+    case "slate-unreadable":
+      return "its slate.json is present but could not be read - the session's own record is damaged, not merely unrecorded";
+    case "no-resolution-recorded":
+      return "it has Slate engagement but no proposal, terminal state, unbound-candidate or wrap-up-outcome artifact";
+  }
+}
 function renderSection(title, items, describe) {
   const lines = [`== ${title} ==`];
   if (items.length === 0)

package/dist/core.js

@@ -20387,10 +20387,12 @@ __export(exports_service9, {
   normalizeCollaborationResult: () => normalizeCollaborationResult,
   normalizeFwkResult: () => normalizeFwkResult,
   normalizeProposalLifecycleResult: () => normalizeProposalLifecycleResult,
+  normalizeWorkspaceReference: () => normalizeWorkspaceReference,
   proposalNotePath: () => proposalNotePath,
   readExternalSlate: () => readExternalSlate,
   reclaimStaleExternalSlates: () => reclaimStaleExternalSlates,
   redactSensitiveText: () => redactSensitiveText,
+  requireWorkspaceReference: () => requireWorkspaceReference,
   resolveOrCreateWorkspace: () => resolveOrCreateWorkspace,
   resolvePolicyExperiment: () => resolvePolicyExperiment,
   rollbackPolicyExperiment: () => rollbackPolicyExperiment,
@@ -20401,8 +20403,50 @@ __export(exports_service9, {
 });
 
 // src/sac/fwk-service.ts
-init_assembly();
 import { createHash as createHash15, randomUUID as randomUUID4 } from "crypto";
+
+// src/sac/workspace-reference.ts
+var WORKSPACE_REFERENCE_PATTERN = /^\.\/(?!(?:.*\/)?\.\.(?:\/|$))(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+var UNSAFE_ABSOLUTE = /^[/\\]/;
+var UNSAFE_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+function requireWorkspaceReference(raw) {
+  const normalized = normalizeWorkspaceReference(raw);
+  if (!normalized.ok)
+    throw new Error(normalized.reason);
+  return normalized.uri;
+}
+function normalizeWorkspaceReference(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, reason: 'a workspace reference must be a non-empty workspace-relative path, e.g. "./src/harness/search"' };
+  }
+  if (UNSAFE_ABSOLUTE.test(trimmed) || UNSAFE_SCHEME.test(trimmed) || trimmed.includes("\\")) {
+    return {
+      ok: false,
+      reason: `"${trimmed}" is not a workspace-relative path \u2014 an absolute path, a URL and a Windows path are all refused. Use a path inside the project, e.g. "./src/harness/search".`
+    };
+  }
+  const withoutDotSlash = trimmed.startsWith("./") ? trimmed.slice(2) : trimmed;
+  const withoutTrailingSlash = withoutDotSlash.replace(/\/+$/, "");
+  if (withoutTrailingSlash.length === 0) {
+    return { ok: false, reason: `"${trimmed}" names the project root rather than a path inside it \u2014 name a directory or file, e.g. "./src/harness/search".` };
+  }
+  const segments = withoutTrailingSlash.split("/");
+  if (segments.includes("..") || segments.includes(".")) {
+    return { ok: false, reason: `"${trimmed}" contains a "." or ".." path segment \u2014 a workspace reference must stay inside the project.` };
+  }
+  const uri = `./${withoutTrailingSlash}`;
+  if (!WORKSPACE_REFERENCE_PATTERN.test(uri)) {
+    return {
+      ok: false,
+      reason: `"${trimmed}" is not a usable workspace reference. The stored form is "${uri}" if the characters are the problem: ` + 'each path segment may contain only letters, digits, ".", "_" and "-", and no ".." segment is allowed.'
+    };
+  }
+  return { ok: true, uri };
+}
+
+// src/sac/fwk-service.ts
+init_assembly();
 import { appendFile as appendFile5, mkdir as mkdir28, open as open2, readFile as readFile40, rename as rename6, rm as rm5, stat as stat9, writeFile as writeFile21 } from "fs/promises";
 import path78 from "path";
 
@@ -20415,7 +20459,7 @@ var idPattern = /^[a-z][a-z0-9-]{2,63}$/;
 var subjectPattern = /^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$/;
 var revisionPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
 var correlationPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{15,255}$/;
-var workspacePathPattern = /^\.\/(?!.*(?:^|\/)\.\.(?:\/|$))(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+var workspacePathPattern = WORKSPACE_REFERENCE_PATTERN;
 var receiptHashPattern = /^[a-f0-9]{64}$/;
 var utcPattern = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?Z$/;
 var forbiddenPayloadKeys = new Set(["prompt", "transcript", "hiddenReasoning", "secret", "secrets", "rawContent"]);
@@ -21661,7 +21705,7 @@ var stableJson2 = (value) => JSON.stringify(stableValue(value));
 var sha2562 = (value) => createHash14("sha256").update(stableJson2(value), "utf8").digest("hex");
 var sha256Content = (value) => createHash14("sha256").update(value).digest("hex");
 var pseudonym = (key, value) => createHmac2("sha256", key).update(value, "utf8").digest("hex");
-var workspacePathPattern2 = /^\.\/(?!.*(?:^|\/)\.\.(?:\/|$))(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+var workspacePathPattern2 = WORKSPACE_REFERENCE_PATTERN;
 var trustedOutcomes = new WeakMap;
 var trustedSandboxEvidence = new WeakMap;
 var trustedSandboxExecutions = new WeakMap;
@@ -22138,7 +22182,7 @@ var metadataOnly = (value) => {
 var nowIso = (now) => now().toISOString();
 var reportHashPattern = /^[a-f0-9]{64}$/;
 var immutableVersionPattern = /(?:^|[-_.:])(?:latest|next|head|main|develop)(?:$|[-_.:])/i;
-var workspacePathPattern3 = /^\.\/(?!.*(?:^|\/)\.\.(?:\/|$))(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+var workspacePathPattern3 = WORKSPACE_REFERENCE_PATTERN;
 var policyExperimentConfigPath = [".metaproject", "context-operations", "policy-experiment", "config.json"];
 var stableValue2 = (value) => {
   if (Array.isArray(value))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.128",
+  "version": "0.2.131",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {