@wrongstack/core 0.299.0 → 0.301.0

package/dist/execution/tool-executor.d.ts

@@ -67,7 +67,10 @@ export declare class ToolExecutor {
      * Also installs the governed bridge because confirmed tools are re-run
      * through this method after a pending confirmation.
      */
-    executeTool(tool: Tool, use: ToolUseBlock, ctx: Context, budget: number): Promise<{
+    executeTool(tool: Tool, use: ToolUseBlock, ctx: Context, budget: number, preToolContext?: {
+        text: string;
+        contextAs: 'inline' | 'separate';
+    }): Promise<{
         block: ToolResultBlock;
         bytes: number;
     }>;

package/dist/execution/topic-shift-advisor.d.ts

@@ -0,0 +1,53 @@
+import type { Context } from '../core/context.js';
+import { type Message, type Provider } from '../types/index.js';
+export interface TopicShiftAdvice {
+    suggestNewContext: boolean;
+    confidence: number;
+    reason: string;
+    nextTopic?: string | undefined;
+    source: 'explicit' | 'model' | 'cache' | 'local';
+}
+export interface TopicShiftAdvisorInput {
+    prompt: string;
+    messages: readonly Message[];
+    provider?: Provider | undefined;
+    model?: string | undefined;
+    contextTokens?: number | undefined;
+    maxContext?: number | undefined;
+    signal?: AbortSignal | undefined;
+    /** Notifies prompt surfaces only when the remote ambiguity check actually runs. */
+    onModelCheck?: ((busy: boolean) => void) | undefined;
+}
+export interface TopicShiftAdvisorOptions {
+    capacity?: number | undefined;
+    ttlMs?: number | undefined;
+    timeoutMs?: number | undefined;
+    now?: (() => number) | undefined;
+}
+/**
+ * Best-effort, bounded topic-boundary advisor for prompt-submit surfaces.
+ *
+ * Most prompts finish in the local gate. A separate provider call happens
+ * only after history is substantial AND the new prompt has little lexical
+ * continuity with recent user goals. Results are held in a small TTL/LRU so
+ * edit/retry or duplicate submits never pay twice.
+ */
+export declare class TopicShiftAdvisor {
+    private readonly capacity;
+    private readonly ttlMs;
+    private readonly timeoutMs;
+    private readonly now;
+    private readonly cache;
+    constructor(options?: TopicShiftAdvisorOptions);
+    advise(input: TopicShiftAdvisorInput): Promise<TopicShiftAdvice>;
+    private classify;
+    private get;
+    private set;
+}
+/**
+ * Start a clean model context without deleting the session journal or visible
+ * chat. Durable memory, provider/model selection, settings and project state
+ * remain owned by their existing services.
+ */
+export declare function startFreshTopicContext(ctx: Context): Promise<void>;
+//# sourceMappingURL=topic-shift-advisor.d.ts.map

package/dist/extension/index.js

@@ -258,9 +258,15 @@ var ExtensionRegistry = class {
    * Build a composed provider runner. Extensions with `wrapProviderRunner`
    * form a middleware-style chain: the innermost extension wraps the
    * default runner, each subsequent wrapper wraps the previous.
+   *
+   * Utility calls may exclude agent-loop-only middleware (notably
+   * `fallback-model`) while retaining request-safety wrappers such as the
+   * prompt firewall. One-shot orchestration owns its provider and fallback
+   * route, so an agent-loop fallback wrapper cannot safely run against it.
    */
-  wrapProviderRunner(inner) {
-    const wrappers = this.extensions.filter((e) => e.wrapProviderRunner).map((e) => ({ name: e.name, wrap: expectDefined(e.wrapProviderRunner) }));
+  wrapProviderRunner(inner, options) {
+    const excluded = new Set(options?.exclude);
+    const wrappers = this.extensions.filter((e) => e.wrapProviderRunner && !excluded.has(e.name)).map((e) => ({ name: e.name, wrap: expectDefined(e.wrapProviderRunner) }));
     if (wrappers.length === 0) return inner;
     let composed = inner;
     for (let i = wrappers.length - 1; i >= 0; i--) {

package/dist/extension/registry.d.ts

@@ -78,8 +78,15 @@ export declare class ExtensionRegistry {
      * Build a composed provider runner. Extensions with `wrapProviderRunner`
      * form a middleware-style chain: the innermost extension wraps the
      * default runner, each subsequent wrapper wraps the previous.
+     *
+     * Utility calls may exclude agent-loop-only middleware (notably
+     * `fallback-model`) while retaining request-safety wrappers such as the
+     * prompt firewall. One-shot orchestration owns its provider and fallback
+     * route, so an agent-loop fallback wrapper cannot safely run against it.
      */
-    wrapProviderRunner(inner: ProviderRunnerFn): ProviderRunnerFn;
+    wrapProviderRunner(inner: ProviderRunnerFn, options?: {
+        exclude?: readonly string[] | undefined;
+    }): ProviderRunnerFn;
     runBeforeToolExecution(...args: Parameters<BeforeToolExecutionHook>): Promise<Parameters<BeforeToolExecutionHook>[1]>;
     runAfterToolExecution(...args: Parameters<AfterToolExecutionHook>): Promise<void>;
 }

package/dist/fleet-notifier.d.ts

@@ -5,8 +5,13 @@ export interface FleetNotifierOptions {
     projectRoot: string;
     /** This process's pid, so a WebUI never pings itself. */
     selfPid?: number | undefined;
-    /** Injectable POST for tests. Defaults to a timed `fetch`. */
-    post?: ((url: string) => Promise<void>) | undefined;
+    /**
+     * Injectable POST for tests. Defaults to a timed `fetch`.
+     *
+     * The second parameter carries the target's API token (H3). It is optional
+     * so an existing `(url) => …` stub stays assignable.
+     */
+    post?: ((url: string, token?: string | undefined) => Promise<void>) | undefined;
 }
 export declare class FleetNotifier {
     private readonly baseDir;
@@ -21,6 +26,8 @@ export declare class FleetNotifier {
     notify(): void;
     /** Resolve same-project WebUI ping URLs (cached briefly). Exposed for tests. */
     endpoints(): Promise<string[]>;
+    /** Ping targets with their tokens (cached briefly). */
+    private targets;
     dispose(): void;
     /** Re-scope notifications after an in-process project switch. */
     setProjectRoot(projectRoot: string): void;

package/dist/goal/index.js

@@ -2765,6 +2765,9 @@ function canonicalProjectRoot(absRoot) {
     const commonDirFile = path4.join(gitDir, "commondir");
     if (!fs.statSync(commonDirFile).isFile()) return checkoutRoot;
     const commonDir = path4.resolve(gitDir, fs.readFileSync(commonDirFile, "utf8").trim());
+    const worktreesDir = path4.dirname(gitDir);
+    if (path4.basename(worktreesDir).toLowerCase() !== "worktrees") return checkoutRoot;
+    if (path4.resolve(worktreesDir, "..") !== commonDir) return checkoutRoot;
     if (path4.basename(commonDir).toLowerCase() !== ".git") return checkoutRoot;
     return path4.dirname(commonDir);
   } catch {
@@ -2787,7 +2790,7 @@ function safeProfileName(name) {
   const safe = (name ?? "").replace(/[/\\:]/g, "_").replace(/\.\./g, "_").trim();
   return safe || "default";
 }
-function activeProfileName(globalRoot) {
+function bootstrapProfileName(globalRoot) {
   try {
     const parsed = JSON.parse(fs.readFileSync(path4.join(globalRoot, "config.json"), "utf8"));
     return safeProfileName(
@@ -2805,7 +2808,7 @@ function wstackGlobalRoot() {
 function resolveWstackPaths(opts) {
   const globalRoot = opts.globalRoot ?? (opts.userHome ? path4.join(opts.userHome, ".wrongstack") : wstackGlobalRoot());
   const homeDir = opts.userHome ?? os.homedir();
-  const profileName = safeProfileName(opts.profileName ?? activeProfileName(globalRoot));
+  const profileName = safeProfileName(opts.profileName ?? bootstrapProfileName(globalRoot));
   const profileDir = path4.join(globalRoot, "profiles", profileName);
   const hash = projectHash(opts.projectRoot);
   const slug = projectSlug(opts.projectRoot);
@@ -2875,7 +2878,12 @@ function resolveWstackPaths(opts) {
     projectRequirementIntakes: path4.join(projectDir, "requirement-intakes"),
     syncConfig: path4.join(profileDir, "sync.json"),
     configHistoryDir: path4.join(globalRoot, "config-history"),
-    projectStatus: (projectHash2) => path4.join(globalRoot, "projects", projectHash2, "status.json")
+    projectStatus: (statusProjectSlug) => {
+      if (!/^[a-z0-9](?:[a-z0-9-]{0,39})-[a-f0-9]{6}$/.test(statusProjectSlug)) {
+        throw new Error(`Invalid project slug: ${statusProjectSlug}`);
+      }
+      return path4.join(globalRoot, "projects", statusProjectSlug, "status.json");
+    }
   };
 }
 

package/dist/hooks/index.js

@@ -776,20 +776,36 @@ function hookMatcherMatches(matcher, toolName) {
 
 // src/hooks/runner.ts
 var DEFAULT_TIMEOUT_MS3 = 5e3;
+var DEFAULT_BACKGROUND_TIMEOUT_MS = 6e4;
 var MAX_TIMEOUT_MS = 10 * 6e4;
+function hookTimeoutMs(entry) {
+  return entry.timeoutMs ?? (entry.background ? DEFAULT_BACKGROUND_TIMEOUT_MS : DEFAULT_TIMEOUT_MS3);
+}
+function contextFromOutcome(outcome) {
+  return {
+    ...outcome.additionalContext ? { additionalContext: outcome.additionalContext } : {},
+    ...outcome.contextAs ? { contextAs: outcome.contextAs } : {}
+  };
+}
 function normalizePreToolOutcome(outcome) {
-  if ("action" in outcome) return outcome;
+  const context = contextFromOutcome(outcome);
+  if ("action" in outcome) return { ...outcome, ...context };
   if (outcome.decision === "block") {
-    return { action: "deny", reason: outcome.reason?.trim() || "blocked by PreToolUse hook" };
+    return {
+      action: "deny",
+      reason: outcome.reason?.trim() || "blocked by PreToolUse hook",
+      ...context
+    };
   }
   if (outcome.modifiedInput && typeof outcome.modifiedInput === "object") {
     return {
       action: "mutate",
       input: outcome.modifiedInput,
-      ...outcome.reason ? { reason: outcome.reason } : {}
+      ...outcome.reason ? { reason: outcome.reason } : {},
+      ...context
     };
   }
-  return { action: "allow" };
+  return { action: "allow", ...context };
 }
 function malformedOutcome(outcome) {
   if (!("action" in outcome)) return void 0;
@@ -819,11 +835,26 @@ var HookRunner = class {
   has(event) {
     return this.registry.has(event);
   }
-  async preToolUse(toolName, toolInput, env) {
+  async preToolUse(toolName, toolInput, env, toolMeta) {
     const entries = this.matching("PreToolUse", toolName);
     if (entries.length === 0) return {};
+    const declared = {
+      ...toolMeta?.capabilities ? { toolCapabilities: toolMeta.capabilities } : {},
+      ...toolMeta?.mutating === void 0 ? {} : { toolMutating: toolMeta.mutating }
+    };
     let current = toolInput;
     let mutated = false;
+    const contexts = [];
+    let contextAs;
+    const collectContext = (outcome) => {
+      if (outcome.additionalContext) contexts.push(outcome.additionalContext);
+      if (outcome.contextAs === "separate") contextAs = "separate";
+      else if (outcome.contextAs === "inline" && contextAs === void 0) contextAs = "inline";
+    };
+    const resultContext = () => ({
+      ...contexts.length > 0 ? { additionalContext: contexts.join("\n") } : {},
+      ...contextAs ? { contextAs } : {}
+    });
     const mutators = entries.filter((entry) => entry.stage === "mutate");
     const validators = entries.filter((entry) => entry.stage === "validate");
     for (const entry of mutators) {
@@ -831,13 +862,15 @@ var HookRunner = class {
         event: "PreToolUse",
         toolName,
         toolInput: current,
+        ...declared,
         ...this.base(env)
       };
       const outcome = await this.invoke(entry, payload, env);
       if (!outcome) continue;
       const normalized = normalizePreToolOutcome(outcome);
+      collectContext(normalized);
       if (normalized.action === "deny") {
-        return { block: true, reason: normalized.reason };
+        return { block: true, reason: normalized.reason, ...resultContext() };
       }
       if (normalized.action === "mutate") {
         current = normalized.input;
@@ -849,21 +882,25 @@ var HookRunner = class {
         event: "PreToolUse",
         toolName,
         toolInput: current,
+        ...declared,
         ...this.base(env)
       };
       const outcome = await this.invoke(entry, payload, env);
       if (!outcome) continue;
       const normalized = normalizePreToolOutcome(outcome);
+      collectContext(normalized);
       if (normalized.action === "deny") {
-        return { block: true, reason: normalized.reason };
+        return { block: true, reason: normalized.reason, ...resultContext() };
       }
       if (normalized.action === "mutate") {
         const reason = `PreToolUse validator "${entry.name}" attempted to mutate tool arguments`;
         this.opts.logger?.warn?.(reason);
-        if (entry.failurePolicy === "closed") return { block: true, reason };
+        if (entry.failurePolicy === "closed") {
+          return { block: true, reason, ...resultContext() };
+        }
       }
     }
-    return mutated ? { input: current } : {};
+    return { ...mutated ? { input: current } : {}, ...resultContext() };
   }
   async postToolUse(toolName, toolInput, result, env) {
     const payload = {
@@ -961,12 +998,12 @@ var HookRunner = class {
       result = await this.invokeInProcess(entry, payload, env);
     } else {
       result = entry.kind === "shell" ? await runShellHookDetailed(
-        { command: entry.command, timeoutMs: entry.timeoutMs },
+        { command: entry.command, timeoutMs: hookTimeoutMs(entry) },
         payload,
         this.opts.logger,
         { signal: env.signal }
       ) : await runHttpHookDetailed(
-        { url: entry.url, headers: entry.headers, timeoutMs: entry.timeoutMs },
+        { url: entry.url, headers: entry.headers, timeoutMs: hookTimeoutMs(entry) },
         payload,
         this.opts.logger,
         { signal: env.signal }
@@ -983,12 +1020,12 @@ var HookRunner = class {
     }
     if (!result.failure) return result.outcome;
     this.opts.logger?.warn?.(
-      `${payload.event} hook "${entry.name}" failed (${result.failure.kind}): ${result.failure.message}`
+      `${payload.event} ${entry.background ? "background " : ""}hook "${entry.name}" failed (${result.failure.kind}): ${result.failure.message}`
     );
     return this.failureOutcome(entry, payload, result.failure);
   }
   async invokeInProcess(entry, payload, env) {
-    const timeoutMs = Math.max(1, Math.min(entry.timeoutMs ?? DEFAULT_TIMEOUT_MS3, MAX_TIMEOUT_MS));
+    const timeoutMs = Math.max(1, Math.min(hookTimeoutMs(entry), MAX_TIMEOUT_MS));
     const controller = new AbortController();
     let timedOut = false;
     const onParentAbort = () => controller.abort(env.signal?.reason);

package/dist/hooks/runner.d.ts

@@ -22,6 +22,8 @@ export interface PreToolUseResult {
     reason?: string | undefined;
     /** Present only when a hook replaced the tool input. */
     input?: Record<string, unknown>;
+    additionalContext?: string | undefined;
+    contextAs?: 'inline' | 'separate' | undefined;
 }
 export interface PromptResult {
     block?: boolean | undefined;
@@ -46,7 +48,16 @@ export declare class HookRunner {
     constructor(opts: HookRunnerOptions);
     /** Cheap guard so callers can skip building payloads when nothing listens. */
     has(event: HookEvent): boolean;
-    preToolUse(toolName: string, toolInput: Record<string, unknown>, env: HookRunEnv): Promise<PreToolUseResult>;
+    preToolUse(toolName: string, toolInput: Record<string, unknown>, env: HookRunEnv, 
+    /**
+     * What the tool declares about itself. Optional so existing callers (and
+     * tests) keep working, but the executor always passes it — a policy hook
+     * that keys on capability instead of tool name needs it to be there.
+     */
+    toolMeta?: {
+        capabilities?: readonly string[] | undefined;
+        mutating?: boolean | undefined;
+    }): Promise<PreToolUseResult>;
     postToolUse(toolName: string, toolInput: unknown, result: {
         content: string;
         isError: boolean;

package/dist/hq/index.js

@@ -492,6 +492,9 @@ function isHqSubagentSummary(x) {
   const v = x;
   return typeof v.subagentId === "string" && typeof v.status === "string" && HQ_FLEET_SUBAGENT_STATUS.has(v.status);
 }
+function isOptionalFiniteNumber(x) {
+  return x === void 0 || typeof x === "number" && Number.isFinite(x);
+}
 function isHqFleetSnapshotPayload(x) {
   if (typeof x !== "object" || x === null) return false;
   const v = x;
@@ -501,6 +504,13 @@ function isHqFleetSnapshotPayload(x) {
   for (const s of v.subagents) {
     if (!isHqSubagentSummary(s)) return false;
   }
+  if (!isOptionalFiniteNumber(v.maxConcurrent)) return false;
+  if (!isOptionalFiniteNumber(v.maxSpawns)) return false;
+  if (!isOptionalFiniteNumber(v.usedSpawns)) return false;
+  if (!isOptionalFiniteNumber(v.remainingSpawns)) return false;
+  if (!isOptionalFiniteNumber(v.checkpointMaxSpawns)) return false;
+  if (v.effectiveSource !== void 0 && typeof v.effectiveSource !== "string") return false;
+  if (v.ceilingMismatch !== void 0 && typeof v.ceilingMismatch !== "boolean") return false;
   return true;
 }
 function isHqFleetEventPayload(x) {
@@ -1295,6 +1305,7 @@ function createMailboxEventPayload(input) {
 var TRANSCRIPT_EVENT_TYPES = /* @__PURE__ */ new Set(["session.transcript", "agent.message"]);
 var OPEN_STATE = 1;
 var CONNECT_WARN_AFTER_FAILURES = 5;
+var DEFAULT_CONNECT_WARN_COOLDOWN_MS = 5 * 6e4;
 var DEFAULT_RECONNECT_BASE_MS = 1e3;
 var DEFAULT_RECONNECT_MAX_MS = 3e4;
 var DEFAULT_DISCOVERY_POLL_MS = 5e3;
@@ -1306,6 +1317,7 @@ var DEFAULT_MAX_QUEUED_BYTES = Math.min(
 var DEFAULT_COMMAND_POLL_INTERVAL_MS = 500;
 var DEFAULT_COMMAND_POLL_LIMIT = 25;
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 25e3;
+var lastConnectWarningAtMs = 0;
 function queuedFrameCoalesceKey(frame) {
   if (frame.type !== "client.event" || !frame.event.type.endsWith(".snapshot")) {
     return void 0;
@@ -1357,6 +1369,8 @@ var HqPublisher = class {
     this.reconnect = options.reconnect ?? true;
     this.reconnectBaseMs = options.reconnectBaseMs ?? DEFAULT_RECONNECT_BASE_MS;
     this.reconnectMaxMs = options.reconnectMaxMs ?? DEFAULT_RECONNECT_MAX_MS;
+    this.connectWarnAfterFailures = options.connectWarnAfterFailures ?? CONNECT_WARN_AFTER_FAILURES;
+    this.connectWarnCooldownMs = options.connectWarnCooldownMs ?? DEFAULT_CONNECT_WARN_COOLDOWN_MS;
     this.maxQueuedMessages = options.maxQueuedMessages ?? DEFAULT_MAX_QUEUED_MESSAGES;
     this.maxQueuedBytes = options.maxQueuedBytes ?? DEFAULT_MAX_QUEUED_BYTES;
     this.resolvedRedactionPolicy = resolveHqRedactionPolicy(options.redactionPolicy);
@@ -1370,6 +1384,8 @@ var HqPublisher = class {
   reconnect;
   reconnectBaseMs;
   reconnectMaxMs;
+  connectWarnAfterFailures;
+  connectWarnCooldownMs;
   maxQueuedMessages;
   maxQueuedBytes;
   resolvedRedactionPolicy;
@@ -1781,9 +1797,8 @@ var HqPublisher = class {
     if (this.stopped || !this.reconnect || this.reconnectTimer !== null) return;
     const delay = Math.min(this.reconnectMaxMs, this.reconnectBaseMs * 2 ** this.reconnectAttempt);
     this.reconnectAttempt += 1;
-    if (!this.connectWarningEmitted && this.reconnectAttempt >= CONNECT_WARN_AFTER_FAILURES) {
-      this.connectWarningEmitted = true;
-      this.emitConnectWarning();
+    if (!this.connectWarningEmitted && this.reconnectAttempt >= this.connectWarnAfterFailures) {
+      if (this.emitConnectWarning()) this.connectWarningEmitted = true;
     }
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null;
@@ -1792,11 +1807,16 @@ var HqPublisher = class {
     this.reconnectTimer.unref?.();
   }
   emitConnectWarning() {
+    const nowMs = Date.now();
+    if (nowMs - lastConnectWarningAtMs < this.connectWarnCooldownMs) {
+      return false;
+    }
+    lastConnectWarningAtMs = nowMs;
     const attempt = this.lastAttempt;
     const message = `WrongStack HQ publisher: ${this.reconnectAttempt} consecutive connection failures${attempt !== null ? ` to ${attempt.url} (client token ${attempt.hadToken ? "present" : "absent"})` : ""}. Either the HQ server is unreachable or it rejected the token (401). If HQ runs in client-token mode, verify WRONGSTACK_HQ_TOKEN / auth.json. Retries continue with backoff.`;
     if (this.logger) {
       this.logger.warn(message, { event: "hq.publisher.connect_failed" });
-      return;
+      return true;
     }
     const warn = this.options.warn ?? ((msg) => console.warn(
       JSON.stringify({
@@ -1810,6 +1830,7 @@ var HqPublisher = class {
       warn(message);
     } catch {
     }
+    return true;
   }
   /**
    * Dormant re-check while no HQ endpoint is discoverable. Uses a FIXED
@@ -2061,6 +2082,20 @@ function windowsAccountName() {
   return username;
 }
 
+// src/utils/pid.ts
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err.code;
+    if (code === "EPERM") return true;
+    return false;
+  }
+}
+
 // src/utils/wstack-paths.ts
 import { createHash } from "node:crypto";
 import * as fs2 from "node:fs";
@@ -2078,6 +2113,9 @@ function canonicalProjectRoot(absRoot) {
     const commonDirFile = path2.join(gitDir, "commondir");
     if (!fs2.statSync(commonDirFile).isFile()) return checkoutRoot;
     const commonDir = path2.resolve(gitDir, fs2.readFileSync(commonDirFile, "utf8").trim());
+    const worktreesDir = path2.dirname(gitDir);
+    if (path2.basename(worktreesDir).toLowerCase() !== "worktrees") return checkoutRoot;
+    if (path2.resolve(worktreesDir, "..") !== commonDir) return checkoutRoot;
     if (path2.basename(commonDir).toLowerCase() !== ".git") return checkoutRoot;
     return path2.dirname(commonDir);
   } catch {
@@ -2100,7 +2138,7 @@ function safeProfileName(name) {
   const safe = (name ?? "").replace(/[/\\:]/g, "_").replace(/\.\./g, "_").trim();
   return safe || "default";
 }
-function activeProfileName(globalRoot) {
+function bootstrapProfileName(globalRoot) {
   try {
     const parsed = JSON.parse(fs2.readFileSync(path2.join(globalRoot, "config.json"), "utf8"));
     return safeProfileName(
@@ -2118,7 +2156,7 @@ function wstackGlobalRoot() {
 function resolveWstackPaths(opts) {
   const globalRoot = opts.globalRoot ?? (opts.userHome ? path2.join(opts.userHome, ".wrongstack") : wstackGlobalRoot());
   const homeDir = opts.userHome ?? os.homedir();
-  const profileName = safeProfileName(opts.profileName ?? activeProfileName(globalRoot));
+  const profileName = safeProfileName(opts.profileName ?? bootstrapProfileName(globalRoot));
   const profileDir = path2.join(globalRoot, "profiles", profileName);
   const hash = projectHash(opts.projectRoot);
   const slug = projectSlug(opts.projectRoot);
@@ -2188,7 +2226,12 @@ function resolveWstackPaths(opts) {
     projectRequirementIntakes: path2.join(projectDir, "requirement-intakes"),
     syncConfig: path2.join(profileDir, "sync.json"),
     configHistoryDir: path2.join(globalRoot, "config-history"),
-    projectStatus: (projectHash2) => path2.join(globalRoot, "projects", projectHash2, "status.json")
+    projectStatus: (statusProjectSlug) => {
+      if (!/^[a-z0-9](?:[a-z0-9-]{0,39})-[a-f0-9]{6}$/.test(statusProjectSlug)) {
+        throw new Error(`Invalid project slug: ${statusProjectSlug}`);
+      }
+      return path2.join(globalRoot, "projects", statusProjectSlug, "status.json");
+    }
   };
 }
 
@@ -2319,22 +2362,13 @@ async function writeHqRuntimeFile(dataDir, file) {
 `, { mode: SECRET_FILE_MODE });
   await restrictFilePermissions(target, { label: "hq-runtime" });
 }
-function isProcessAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
 function readHqRuntimeFileSync(dataDir) {
   try {
     const parsed = JSON.parse(
       syncFs.readFileSync(hqRuntimeFilePath(dataDir), "utf8")
     );
     if (typeof parsed.url !== "string" || parsed.url.trim().length === 0) return void 0;
-    if (typeof parsed.pid === "number" && !isProcessAlive(parsed.pid)) return void 0;
+    if (typeof parsed.pid === "number" && !isPidAlive(parsed.pid)) return void 0;
     return {
       url: parsed.url,
       updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
@@ -2574,9 +2608,6 @@ function watchHqAuthFile(dataDir, onChange, opts = {}) {
       }
     }
   });
-  watcher.on("error", (err) => {
-    opts.warn?.(`HQ auth watcher error: ${err.message}`);
-  });
   return {
     close: () => {
       closed = true;
@@ -3313,7 +3344,14 @@ function startFleetTelemetryBridge(opts) {
       completedTasks: stats.completed,
       failedTasks: stats.stopped,
       ...stats.totalCostUsd !== void 0 ? { totalCostUsd: stats.totalCostUsd } : {},
-      subagents
+      subagents,
+      ...stats.maxConcurrent !== void 0 ? { maxConcurrent: stats.maxConcurrent } : {},
+      ...stats.maxSpawns !== void 0 ? { maxSpawns: stats.maxSpawns } : {},
+      ...stats.usedSpawns !== void 0 ? { usedSpawns: stats.usedSpawns } : {},
+      ...stats.remainingSpawns !== void 0 ? { remainingSpawns: stats.remainingSpawns } : {},
+      ...stats.effectiveSource !== void 0 ? { effectiveSource: stats.effectiveSource } : {},
+      ...stats.checkpointMaxSpawns !== void 0 ? { checkpointMaxSpawns: stats.checkpointMaxSpawns } : {},
+      ...stats.ceilingMismatch ? { ceilingMismatch: true } : {}
     };
   }
   const off = events.on("coordinator.stats", (stats) => {

package/dist/hq/protocol/fleet.d.ts

@@ -7,6 +7,19 @@ export interface HqFleetSnapshotPayload {
     failedTasks: number;
     totalCostUsd?: number;
     subagents: readonly HqSubagentSummary[];
+    /** Concurrent-subagent ceiling (maxConcurrent). */
+    maxConcurrent?: number | undefined;
+    /** Lifetime spawn ceiling (maxSpawns). */
+    maxSpawns?: number | undefined;
+    /** Cumulative spawns consumed this director run. */
+    usedSpawns?: number | undefined;
+    /** maxSpawns − usedSpawns (clamped ≥ 0). */
+    remainingSpawns?: number | undefined;
+    /** Winning config source labels, e.g. "maxConcurrent=profile, maxSpawns=env". */
+    effectiveSource?: string | undefined;
+    /** Historical checkpoint maxSpawns when it disagreed with the live ceiling. */
+    checkpointMaxSpawns?: number | undefined;
+    ceilingMismatch?: boolean | undefined;
 }
 export interface HqFleetEventPayload {
     runId: string;
@@ -62,6 +75,13 @@ export interface HqFleetSummary {
     failedTasks: number;
     totalCostUsd?: number;
     lastActivityAt: string;
+    maxConcurrent?: number | undefined;
+    maxSpawns?: number | undefined;
+    usedSpawns?: number | undefined;
+    remainingSpawns?: number | undefined;
+    effectiveSource?: string | undefined;
+    checkpointMaxSpawns?: number | undefined;
+    ceilingMismatch?: boolean | undefined;
 }
 export interface HqQueuedCommand {
     commandId: string;

package/dist/hq/protocol.js

@@ -492,6 +492,9 @@ function isHqSubagentSummary(x) {
   const v = x;
   return typeof v.subagentId === "string" && typeof v.status === "string" && HQ_FLEET_SUBAGENT_STATUS.has(v.status);
 }
+function isOptionalFiniteNumber(x) {
+  return x === void 0 || typeof x === "number" && Number.isFinite(x);
+}
 function isHqFleetSnapshotPayload(x) {
   if (typeof x !== "object" || x === null) return false;
   const v = x;
@@ -501,6 +504,13 @@ function isHqFleetSnapshotPayload(x) {
   for (const s of v.subagents) {
     if (!isHqSubagentSummary(s)) return false;
   }
+  if (!isOptionalFiniteNumber(v.maxConcurrent)) return false;
+  if (!isOptionalFiniteNumber(v.maxSpawns)) return false;
+  if (!isOptionalFiniteNumber(v.usedSpawns)) return false;
+  if (!isOptionalFiniteNumber(v.remainingSpawns)) return false;
+  if (!isOptionalFiniteNumber(v.checkpointMaxSpawns)) return false;
+  if (v.effectiveSource !== void 0 && typeof v.effectiveSource !== "string") return false;
+  if (v.ceilingMismatch !== void 0 && typeof v.ceilingMismatch !== "boolean") return false;
   return true;
 }
 function isHqFleetEventPayload(x) {

package/dist/hq/publisher.d.ts

@@ -32,6 +32,20 @@ export interface HqPublisherOptions {
     reconnect?: boolean;
     reconnectBaseMs?: number;
     reconnectMaxMs?: number;
+    /**
+     * Consecutive connect failures (never reaching `open`) before the one-time
+     * diagnostic warning fires. Defaults to `CONNECT_WARN_AFTER_FAILURES` (5).
+     */
+    connectWarnAfterFailures?: number;
+    /**
+     * Minimum gap between connect-failure warnings ACROSS all HqPublisher
+     * instances in this process. When a fleet of agents fails against the same
+     * dead/rejecting HQ at once, only the first instance to cross the threshold
+     * warns; the rest stay silent until the window elapses (each instance still
+     * warns at most once). Defaults to 5 minutes. Set to 0 to disable the
+     * process-wide gate entirely.
+     */
+    connectWarnCooldownMs?: number;
     maxQueuedMessages?: number;
     /** Hard byte cap on the outbound queue (prevents RAM blow-up when HQ is
      * offline). Older frames are dropped oldest-first when exceeded. The default
@@ -66,11 +80,13 @@ export interface HqPublisherOptions {
      */
     heartbeatIntervalMs?: number;
     /**
-     * Diagnostic sink for the one-time consecutive-connect-failure warning.
-     * The publisher is otherwise deliberately silent (dormant queueing), which
+     * Diagnostic sink for the consecutive-connect-failure warning. The
+     * publisher is otherwise deliberately silent (dormant queueing), which
      * made auth failures invisible: a token the server rejects — e.g. a wrong
      * `WRONGSTACK_HQ_TOKEN` against a remote HQ — looked exactly like "HQ not
-     * running". Defaults to a single structured `console.warn` line.
+     * running". Emission is one-shot per instance and rate-limited process-wide
+     * via {@link HqPublisherOptions.connectWarnCooldownMs}. Defaults to a
+     * single structured `console.warn` line.
      */
     warn?: (message: string) => void;
     /** Logger for structured events. When provided, the `warn` callback is derived from it. */
@@ -99,6 +115,8 @@ export declare class HqPublisher {
     private readonly reconnect;
     private readonly reconnectBaseMs;
     private readonly reconnectMaxMs;
+    private readonly connectWarnAfterFailures;
+    private readonly connectWarnCooldownMs;
     private readonly maxQueuedMessages;
     private readonly maxQueuedBytes;
     private readonly resolvedRedactionPolicy;