@juspay/shooter 1.21.0 → 1.23.0

package/src/lib/modules/server/sessions/autopilot-engine.ts

@@ -12,11 +12,18 @@
 import type { AgentProposal, NextStep, SessionSummaryRecord, WireShooterEvent } from '$lib/types';
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { homedir } from 'os';
 import { join } from 'path';
 
 import { ptyManager } from '../terminal/pty-manager.js';
+import { shooterDataDir } from '../utils/shooter-home.js';
 import { onShooterEvent } from '../ws/events-handler.js';
+import { isViewerPresent } from '../ws/presence-store.js';
+import {
+  buildEngineContext,
+  clearEngineGoal,
+  getEngineGoal,
+  setEngineGoal,
+} from './autopilot-context.js';
 import { isLiteLLMConfigured, litellmJson } from './litellm-client.js';
 import { mergeNextStepConsensus } from './next-step-consensus.js';
 import { summaryStore } from './summary-store.js';
@@ -29,27 +36,57 @@ const MIN_INTERVAL_MS = 30_000; // minimum gap between pipeline runs per session
 const PERIODIC_EVERY = 20;
 const ERROR_THRESHOLD = 3;
 const MAX_EVENTS = 60;
-const SUMMARY_MAX_TOKENS = 220;
-const STEPS_MAX_TOKENS = 320;
-const STATE_FILE = join(homedir(), '.shooter', 'autopilot.json');
-
-/** Five DISTINCT lenses — each a different perspective, so votes mean real agreement. */
+const SUMMARY_MAX_TOKENS = 400;
+const STEPS_MAX_TOKENS = 400;
+// How many of the five lenses run concurrently. Kept BELOW the typical LiteLLM key parallel cap so
+// the engine never saturates the key by itself: firing all five at once exhausted a
+// max_parallel_requests=5 key and 429'd every call (empty consensus, silent stall). Default 3
+// leaves headroom for the summary's retry + other callers sharing the key. Tune per key via env.
+const LENS_CONCURRENCY = Math.max(1, Number(process.env.AUTOPILOT_LENS_CONCURRENCY) || 3);
+// Consensus quorum: how many of the 5 distinct lenses must agree for a step to be non-tentative
+// (and thus auto-injectable). The lenses are DIFFERENT perspectives that phrase the same action
+// differently, so the Jaccard clustering systematically undercounts true agreement (observed: 4/5
+// lenses proposed the same fix but only 2 clustered). 2-of-5 + the confidence floor + the eight
+// driver guards (idle-only, managed-only, rate-limit, dedup, circuit-breaker, command-guard,
+// kill-switch, human-grace) is the practical bar; quorum 3 left the autopilot almost never firing.
+const CONSENSUS_QUORUM = 2;
+const STATE_FILE = join(shooterDataDir(), 'autopilot.json');
+
+// The engine does STRUCTURED extraction (one summary + five voting lenses). A reasoning model like
+// `open-large` does this badly: it reasons out loud and ignores response_format, so the JSON never
+// parses and the consensus collapses to tentative garbage. Pin a fast NON-reasoning model for the
+// pipeline, independent of the user's chat model (LITELLM_MODEL). Overridable via AUTOPILOT_MODEL.
+const ENGINE_MODEL = process.env.AUTOPILOT_MODEL?.trim() || 'open-fast';
+
+// Lead with the JSON-only contract; the per-lens perspective is a TRAILING modifier so the model
+// doesn't start "thinking" about a role. No copyable placeholder value in the schema — reasoning
+// models echo it verbatim ("a real shell command or instruction" leaked into real consensus).
+const JSON_API_RULES =
+  'You are a JSON API. Output ONLY one JSON object and nothing else — no prose, no reasoning, no ' +
+  'markdown, no code fences. The first character MUST be { and the last MUST be }.';
+
+/** Five DISTINCT perspectives — each a different angle, so converging votes mean real agreement. */
 const LENSES = [
-  'You are a BLOCKER-detection agent. Identify what is currently preventing progress or is most likely to fail next.',
-  'You are a NEXT-COMMAND planner. Propose the exact shell commands or file edits the agent should run next, in order.',
-  'You are a RISK analyst. Identify what could go wrong if the agent continues on its current path, and what to validate first.',
-  'You are a VALIDATION agent. Propose how to verify the work so far is correct — the tests, checks, or inspections to run.',
-  'You are a PROGRESS agent. Propose the single most direct next step toward completing the session goal.',
+  'what is currently blocking progress, or is most likely to fail next',
+  'the exact shell commands or file edits the agent should run next, in order',
+  'what could go wrong if the agent continues on its current path, and what to validate first',
+  'how to verify the work so far is correct — the tests, checks, or inspections to run',
+  'the single most direct next step toward completing the session goal',
 ] as const;
 
 // ── Per-session state (globalThis-shared) ───────────────────────────
 
 // eslint-disable-next-line no-restricted-syntax -- internal engine state, never exported
 interface EngineSession {
+  cancelled: boolean;
   errorCount: number;
   eventCount: number;
   events: string[];
+  // Highest signal + latest trigger seen during the OPEN grace window — evaluated at FIRE time, not
+  // schedule time, so an agent-idle arriving after a low-signal event still runs as a high trigger.
+  graceIsHigh: boolean;
   graceTimer: null | ReturnType<typeof setTimeout>;
+  graceTrigger: string;
   lastRunAt: number;
   projectName: string;
   running: boolean;
@@ -76,7 +113,7 @@ export function isAutopilotEnabled(): boolean {
 export function setAutopilotEnabled(value: boolean): void {
   enabled = value;
   try {
-    mkdirSync(join(homedir(), '.shooter'), { recursive: true });
+    mkdirSync(shooterDataDir(), { recursive: true });
     writeFileSync(STATE_FILE, JSON.stringify({ enabled: value }), 'utf-8');
   } catch {
     // best-effort persistence
@@ -96,11 +133,30 @@ export function startAutopilotEngine(): void {
   if (unsubscribe) {
     return;
   }
-  const control = { isEnabled: isAutopilotEnabled, setEnabled: setAutopilotEnabled };
+  const control = {
+    getGoal: getEngineGoal,
+    isEnabled: isAutopilotEnabled,
+    setEnabled: setAutopilotEnabled,
+    setGoal: setEngineGoal,
+  };
   (globalThis as Record<string, unknown>).__shooter_autopilot = control;
   unsubscribe = onShooterEvent(handleEvent);
+  // Pre-track sessions for terminals that already exist at startup (e.g. a server restart that
+  // reconnected persisted terminals). Without this a session is only created lazily on its NEXT
+  // event, so an agent that went idle before the engine attached would be invisible until it emits
+  // again. We deliberately do NOT force a pipeline run here — that would risk spurious LLM spend on
+  // a genuinely quiet terminal; we just ensure the session is tracked so the next event triggers.
+  try {
+    for (const term of ptyManager.list()) {
+      if (!sessions.has(term.id)) {
+        createSession(term.id);
+      }
+    }
+  } catch {
+    // ptyManager not ready yet — sessions will be created lazily on first event
+  }
   console.log(
-    `[autopilot] engine started (enabled=${enabled}, litellm=${isLiteLLMConfigured() ? 'configured' : 'absent'})`
+    `[autopilot] engine started (enabled=${enabled}, litellm=${isLiteLLMConfigured() ? 'configured' : 'absent'}, lensConcurrency=${LENS_CONCURRENCY})`
   );
 }
 
@@ -118,7 +174,9 @@ function applyEvent(session: EngineSession, event: WireShooterEvent): void {
     parts.push(`cmd=${event.command.slice(0, 80)}`);
   }
   if ('message' in event && event.message) {
-    parts.push(`msg=${event.message.slice(0, 120)}`);
+    // The agent's last message on idle (the OUTCOME — e.g. "the test failed because…") is the
+    // richest signal the lenses have; keep enough of it to actually ground the next-step votes.
+    parts.push(`msg=${event.message.slice(0, 400)}`);
   }
   session.events.push(parts.join(' '));
   if (session.events.length > MAX_EVENTS) {
@@ -146,10 +204,13 @@ function applyEvent(session: EngineSession, event: WireShooterEvent): void {
 
 function createSession(terminalId: string): EngineSession {
   const session: EngineSession = {
+    cancelled: false,
     errorCount: 0,
     eventCount: 0,
     events: [],
+    graceIsHigh: false,
     graceTimer: null,
+    graceTrigger: '',
     lastRunAt: 0,
     projectName: projectNameFor(terminalId),
     running: false,
@@ -165,8 +226,6 @@ function fallbackSummary(session: EngineSession): string {
   return `${session.status} — ${session.toolCallCount} tool calls, ${session.errorCount} errors`;
 }
 
-// ── Pipeline ─────────────────────────────────────────────────────────
-
 function handleEvent(event: WireShooterEvent): void {
   const terminalId = 'terminalId' in event ? event.terminalId : undefined;
   if (!terminalId) {
@@ -175,10 +234,14 @@ function handleEvent(event: WireShooterEvent): void {
 
   if (event.type === 'terminal-exited') {
     const s = sessions.get(terminalId);
-    if (s?.graceTimer) {
-      clearTimeout(s.graceTimer);
+    if (s) {
+      s.cancelled = true; // signal any in-flight pipeline to stop before persist/push
+      if (s.graceTimer) {
+        clearTimeout(s.graceTimer);
+      }
     }
     sessions.delete(terminalId);
+    clearEngineGoal(terminalId);
     return;
   }
 
@@ -198,15 +261,44 @@ function handleEvent(event: WireShooterEvent): void {
   if (Date.now() - session.lastRunAt < MIN_INTERVAL_MS) {
     return;
   }
-  // Schedule once; do NOT reset on every event (so a burst doesn't delay the run).
+  // Track the strongest signal + latest trigger across the whole window (so a high-signal event
+  // arriving after the timer was armed by a low-signal one is not lost). Schedule the timer ONCE;
+  // do NOT reset it on every event (so a burst doesn't keep delaying the run).
   if (!session.graceTimer) {
+    session.graceIsHigh = isHigh;
+    session.graceTrigger = event.type;
     session.graceTimer = setTimeout(() => {
       session.graceTimer = null;
-      void runPipeline(session, event.type, isHigh);
+      const trigger = session.graceTrigger;
+      const wasHigh = session.graceIsHigh;
+      void runPipeline(session, trigger, wasHigh);
     }, GRACE_MS);
+  } else {
+    session.graceIsHigh = session.graceIsHigh || isHigh;
+    session.graceTrigger = event.type;
   }
 }
 
+// ── Pipeline ─────────────────────────────────────────────────────────
+
+/** Run `fn` over `items` with at most `limit` in flight; preserves input order. */
+async function mapLimit<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T) => Promise<R>
+): Promise<R[]> {
+  const results: R[] = new Array<R>(items.length);
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    while (next < items.length) {
+      const idx = next++;
+      results[idx] = await fn(items[idx]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()));
+  return results;
+}
+
 function persist(
   session: EngineSession,
   summary: string,
@@ -250,6 +342,12 @@ async function push(session: EngineSession, summary: string, steps: NextStep[]):
   if (!top) {
     return;
   }
+  // Presence-aware: when a viewer is foregrounded (watching the live dashboard) skip the
+  // push — they see it in-app. Push only when away. If no presence-aware client ever
+  // reported, isViewerPresent() is false → push proceeds (prior always-push behavior).
+  if (isViewerPresent()) {
+    return;
+  }
   const port = process.env.PORT || '54007';
   const apiKey = process.env.API_KEY;
   if (!apiKey) {
@@ -300,38 +398,45 @@ async function runPipeline(
   session.running = true;
   session.lastRunAt = Date.now();
   try {
-    const context =
-      `Project: ${session.projectName}\nStatus: ${session.status}\nErrors: ${session.errorCount}\n` +
-      `Tool calls: ${session.toolCallCount}\nRecent events: ${session.events.slice(-12).join('; ')}\n` +
-      `Trigger: ${trigger}`;
+    const context = buildEngineContext({
+      errorCount: session.errorCount,
+      events: session.events,
+      goal: getEngineGoal(session.terminalId),
+      projectName: session.projectName,
+      status: session.status,
+      toolCallCount: session.toolCallCount,
+      trigger,
+    });
 
     const summaryResult = await litellmJson<{ summary: string }>({
       maxTokens: SUMMARY_MAX_TOKENS,
-      systemInstruction:
-        'You are a coding-session monitor. Respond ONLY with valid JSON: {"summary":"<one sentence, max 120 chars>"}. No markdown, no prose outside the JSON.',
+      model: ENGINE_MODEL,
+      systemInstruction: `${JSON_API_RULES} The object has one key "summary": a single sentence (max 120 characters) describing the current status of this coding session.`,
       userPrompt: `${context}\n\nSummarise what is happening in this coding session in ONE sentence (max 120 chars).`,
     });
     const summary = summaryResult?.summary?.trim() || fallbackSummary(session);
 
-    const lensResults = await Promise.allSettled(
-      LENSES.map((lens) =>
-        litellmJson<{ steps: AgentProposal[] }>({
-          maxTokens: STEPS_MAX_TOKENS,
-          systemInstruction: `${lens} Respond ONLY with valid JSON: {"steps":[{"text":"<short action>","confidence":0.9}]}. Up to 3 steps, confidence 0-1. No markdown.`,
-          userPrompt: `${context}\n\nGiven the session above, what should happen next from your perspective?`,
-        })
-      )
-    );
-    // Keep all 5 lists (including empty on failure) so quorum stays 3-of-5.
-    const agentLists: AgentProposal[][] = lensResults.map((r) =>
-      r.status === 'fulfilled' ? (r.value?.steps ?? []) : []
-    );
-    const consensus = mergeNextStepConsensus(agentLists);
+    // Run the five lenses at most LENS_CONCURRENCY in flight (default 3) so the engine never
+    // saturates the LiteLLM key's parallel cap by itself. Each failed lens yields an empty list;
+    // a step needs CONSENSUS_QUORUM (2) of the 5 to be non-tentative.
+    const agentLists: AgentProposal[][] = await mapLimit(LENSES, LENS_CONCURRENCY, async (lens) => {
+      const r = await litellmJson<{ steps: AgentProposal[] }>({
+        maxTokens: STEPS_MAX_TOKENS,
+        model: ENGINE_MODEL,
+        systemInstruction: `${JSON_API_RULES} The object has one key "steps": an array of 1 to 3 objects, each {"text": the concrete next action for THIS exact session written in full as a string, "confidence": a number between 0 and 1}. Choose the actions from THIS perspective: ${lens}.`,
+        userPrompt: `${context}\n\nGiven the session above, what should happen next?`,
+      });
+      return r?.steps ?? [];
+    });
+    const consensus = mergeNextStepConsensus(agentLists, { quorum: CONSENSUS_QUORUM });
 
-    if (!enabled) {
-      return;
+    if (!enabled || session.cancelled) {
+      return; // engine disabled or terminal exited mid-pipeline — don't persist/push a dead session
     }
     persist(session, summary, consensus.steps, trigger);
+    // A run consumed the accumulated errors — reset so the error-threshold trigger (errorCount >= 3)
+    // does not stick and re-fire on every subsequent event for the rest of the session's life.
+    session.errorCount = 0;
     if (isHigh && consensus.steps.length > 0 && !consensus.steps[0].tentative) {
       await push(session, summary, consensus.steps);
     }

package/src/lib/modules/server/sessions/litellm-client.ts

@@ -2,7 +2,9 @@
 // directly with the server-side key (process.env) — no proxy, no browser
 // exposure. Used by the always-on autopilot engine.
 
-const REQUEST_TIMEOUT_MS = 20_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_ATTEMPTS = 2;
+const BACKOFF_MS = [800]; // backoff before the single retry (rate-limit / transient failures)
 
 /** Pull the model's JSON out of an OpenAI-shaped chat-completion response. */
 export function extractJsonContent(data: unknown): unknown {
@@ -25,6 +27,8 @@ export function isLiteLLMConfigured(): boolean {
  */
 export async function litellmJson<T>(opts: {
   maxTokens?: number;
+  /** Override the model for this call (e.g. the autopilot engine pins a non-reasoning model). */
+  model?: string;
   systemInstruction: string;
   userPrompt: string;
 }): Promise<null | T> {
@@ -32,34 +36,20 @@ export async function litellmJson<T>(opts: {
   if (!cfg) {
     return null;
   }
-  const controller = new AbortController();
-  const timer = setTimeout(() => {
-    controller.abort();
-  }, REQUEST_TIMEOUT_MS);
-  try {
-    const res = await fetch(`${cfg.base}/chat/completions`, {
-      body: JSON.stringify({
-        max_tokens: opts.maxTokens ?? 400,
-        messages: [
-          { content: opts.systemInstruction, role: 'system' },
-          { content: opts.userPrompt, role: 'user' },
-        ],
-        model: cfg.model,
-      }),
-      headers: { Authorization: `Bearer ${cfg.key}`, 'Content-Type': 'application/json' },
-      method: 'POST',
-      signal: controller.signal,
-    });
-    if (!res.ok) {
-      return null;
+  // Attempt with JSON mode (forces the model to emit ONLY valid JSON — verbose/reasoning models
+  // otherwise wrap prose around it), retrying with backoff for rate-limit / transient burst
+  // failures. If every JSON-mode attempt fails, fall back ONCE without response_format in case the
+  // gateway rejects it — so a non-supporting backend degrades to prior behavior instead of breaking.
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const result = await attemptCompletion<T>(cfg, opts, true);
+    if (result !== null) {
+      return result;
+    }
+    if (attempt < MAX_ATTEMPTS - 1) {
+      await delay(BACKOFF_MS[attempt]);
     }
-    const data: unknown = await res.json();
-    return extractJsonContent(data) as null | T;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timer);
   }
+  return attemptCompletion<T>(cfg, opts, false);
 }
 
 /**
@@ -79,28 +69,94 @@ export function parseJsonResponse(raw: string): unknown {
   try {
     return JSON.parse(cleaned);
   } catch {
-    const start = cleaned.indexOf('{');
-    if (start !== -1) {
+    // Scan for the FIRST balanced {...} region that actually parses. A reasoning model often emits
+    // an invalid brace region (e.g. "{not: valid}") in its preamble BEFORE the real JSON, so on a
+    // failed candidate we must advance to the next "{" and keep scanning — not give up (the old
+    // `return null` here discarded every later region and collapsed consensus to empty).
+    let start = cleaned.indexOf('{');
+    while (start !== -1) {
       let depth = 0;
+      let end = -1;
       for (let i = start; i < cleaned.length; i++) {
         if (cleaned[i] === '{') {
           depth++;
         } else if (cleaned[i] === '}') {
           depth--;
           if (depth === 0) {
-            try {
-              return JSON.parse(cleaned.slice(start, i + 1));
-            } catch {
-              return null;
-            }
+            end = i;
+            break;
           }
         }
       }
+      if (end === -1) {
+        return null; // unbalanced through end of string — nothing more to try
+      }
+      try {
+        return JSON.parse(cleaned.slice(start, end + 1));
+      } catch {
+        start = cleaned.indexOf('{', start + 1);
+      }
     }
     return null;
   }
 }
 
+async function attemptCompletion<T>(
+  cfg: { base: string; key: string; model: string },
+  opts: { maxTokens?: number; model?: string; systemInstruction: string; userPrompt: string },
+  jsonMode: boolean
+): Promise<null | T> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    controller.abort();
+  }, REQUEST_TIMEOUT_MS);
+  try {
+    const body: Record<string, unknown> = {
+      max_tokens: opts.maxTokens ?? 400,
+      messages: [
+        { content: opts.systemInstruction, role: 'system' },
+        { content: opts.userPrompt, role: 'user' },
+      ],
+      model: opts.model?.trim() || cfg.model,
+      temperature: 0,
+    };
+    if (jsonMode) {
+      body.response_format = { type: 'json_object' };
+    }
+    const res = await fetch(`${cfg.base}/chat/completions`, {
+      body: JSON.stringify(body),
+      headers: { Authorization: `Bearer ${cfg.key}`, 'Content-Type': 'application/json' },
+      method: 'POST',
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      // Surface the failure — silently returning null here made the whole autopilot pipeline
+      // produce empty consensus invisibly (no log, no signal). 429 = the LiteLLM key's
+      // max_parallel_requests is exhausted (often by other processes sharing the key).
+      const detail = await res.text().catch(() => '');
+      console.warn(
+        `[litellm] HTTP ${res.status} (model=${body.model as string}, jsonMode=${jsonMode}): ${detail.slice(0, 200)}`
+      );
+      return null;
+    }
+    const data: unknown = await res.json();
+    return extractJsonContent(data) as null | T;
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    // AbortError = our REQUEST_TIMEOUT_MS fired (the gateway hung). Anything else = network/parse.
+    console.warn(`[litellm] request failed (model=${opts.model?.trim() || cfg.model}): ${reason}`);
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
 function litellmConfig(): null | { base: string; key: string; model: string } {
   const base = process.env.LITELLM_BASE_URL?.trim();
   const key = process.env.LITELLM_API_KEY?.trim();

package/src/lib/modules/server/sessions/next-step-consensus.ts

@@ -60,7 +60,14 @@ export function mergeNextStepConsensus(
       // Step 3: find an existing cluster to join.
       const targetCluster = findOrCreateCluster(clusters, norm);
       targetCluster.agentIndices.add(agentIndex);
-      targetCluster.members.push({ confidence: proposal.confidence, text: proposal.text });
+      // Sanitise confidence at ingestion: the type says `number` but the value comes from raw LLM
+      // JSON, so a missing/NaN/Infinity/out-of-range confidence must NOT leak into meanConf (it
+      // would poison the mean and could spuriously clear the downstream 0.7 inject floor). Invalid
+      // → 0 (correctly fails the floor); valid → clamped to [0,1].
+      targetCluster.members.push({
+        confidence: safeConfidence(proposal.confidence),
+        text: proposal.text,
+      });
     }
   }
 
@@ -175,11 +182,29 @@ function normalize(text: string): string {
     .replace(/[.,;:!?]+$/, '');
 }
 
+/** Coerce a raw (untrusted) confidence into a finite number in [0,1]; invalid → 0. */
+function safeConfidence(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, Math.min(1, value));
+}
+
 // ── Private helper ──────────────────────────────────────────────────────────
 
 /**
  * Tokenize a normalized string into a set of tokens.
  */
 function tokenSet(normalized: string): Set<string> {
-  return new Set(normalized.split(/\s+/).filter((t) => t.length > 0));
+  // Strip wrapping punctuation from each token so code-bearing proposals cluster: the lenses phrase
+  // the same action differently and wrap code in backticks/quotes (`return a - b`, "calc.js"), which
+  // otherwise fragments the tokens ("`return" ≠ "return") and makes the Jaccard overlap undercount
+  // real agreement. Pure-punctuation tokens (operators like - / +) drop out, which is fine — we are
+  // grouping intent, not preserving exact syntax.
+  return new Set(
+    normalized
+      .split(/\s+/)
+      .map((t) => t.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, ''))
+      .filter((t) => t.length > 0)
+  );
 }

package/src/lib/modules/server/sessions/summary-store.ts

@@ -14,9 +14,11 @@ import Database from 'better-sqlite3';
 import * as fs from 'fs';
 import * as path from 'path';
 
+import { shooterDataDir } from '../utils/shooter-home.js';
+
 // ── Constants ────────────────────────────────────────────────────────
 
-const DB_DIR = path.join(process.env.HOME || '', '.shooter');
+const DB_DIR = shooterDataDir();
 const DB_PATH = path.join(DB_DIR, 'shooter.db');
 
 // ── Column list ──────────────────────────────────────────────────────

package/src/lib/modules/server/terminal/agent-launch.ts

@@ -0,0 +1,26 @@
+// Inject a default `--permission-mode` into a claude launch, configurable via the
+// SHOOTER_AGENT_PERMISSION_MODE env var, so managed agent terminals can actually act instead of
+// being auto-denied by a restrictive global Claude config. Claude-only (the flag is
+// claude-specific) and never overrides an explicit --permission-mode the caller passed.
+// Pure — unit-tested in tests/agent-launch.test.cjs.
+
+const CLAUDE_COMMANDS = new Set(['claude']);
+
+export function withAgentPermissionMode(
+  command: string,
+  args: string[],
+  mode: string | undefined
+): string[] {
+  const trimmed = (mode ?? '').trim();
+  if (trimmed.length === 0) {
+    return args; // feature off when unset
+  }
+  const base = command.split('/').pop() ?? command;
+  if (!CLAUDE_COMMANDS.has(base)) {
+    return args; // --permission-mode is claude-specific
+  }
+  if (args.includes('--permission-mode')) {
+    return args; // an explicit flag always wins
+  }
+  return [...args, '--permission-mode', trimmed];
+}

package/src/lib/modules/server/terminal/pty-holder.cjs

@@ -114,6 +114,12 @@ try {
   /* best effort */
 }
 ptyEnv.SHOOTER_CLIPBOARD_DIR = clipboardDir;
+// Tag this PTY with its Shooter terminal id so in-agent lifecycle hooks
+// (notifier.cjs) can attribute their events to THIS managed terminal. The
+// autopilot engine + phone driver key on terminalId; a plain shell that a
+// user starts outside Shooter never sees this var, so its behaviour is
+// unchanged.
+ptyEnv.SHOOTER_TERMINAL_ID = id;
 
 // Prepend clipboard shim scripts to PATH so tools find our xclip/wl-paste
 const shimsDir = path.resolve(__dirname, '..', 'scripts', 'clipboard-shims');