@qlucent/fishi-core 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -345,6 +345,16 @@ declare function getLearningsManagerScript(): string;
  */
 declare function getDocCheckerScript(): string;
 
+/**
+ * Monitor Emitter Script
+ *
+ * Shared helper that other hooks can import to emit agent observability events.
+ * Also callable directly via CLI for one-off event emission.
+ *
+ * Zero dependencies — uses only Node.js built-ins.
+ */
+declare function getMonitorEmitterScript(): string;
+
 declare function getInitCommand(): string;
 
 declare function getStatusCommand(): string;
@@ -523,4 +533,97 @@ interface McpJson {
 declare function mergeMcpJson(existing: McpJson, fishi: McpJson): McpJson;
 declare function mergeGitignore(existing: string, fishiAdditions: string): string;
 
-export { type AgentDefinition, type AgentRole, type AgentTemplate, type BackupManifest, type BrownfieldAnalysisData, type ClaudeMdOptions, type CommandTemplate, type ConflictCategory, type ConflictMap, type ConflictResolution, type CostMode, type DetectionCheck, type DetectionResult, type DynamicAgentConfig, type ExecutionConfig, type FileConflict, type FileResolutionMap, type FishiConfig, type FishiYamlOptions, type GateConfig, type GateStatus, type GitConfig, type HookTemplate, type InitOptions, type McpConfig, type McpServerConfig, type ModelRoutingConfig, type ModelTier, type ProjectConfig, type ProjectType, type ProjectYamlOptions, type ScaffoldOptions, type ScaffoldResult, type SkillTemplate, type StateConfig, type TaskStatus, type TaskboardConfig, type TemplateContext, architectAgentTemplate, backendAgentTemplate, createBackup, detectConflicts, devLeadTemplate, devopsAgentTemplate, docsAgentTemplate, frontendAgentTemplate, fullstackAgentTemplate, generateScaffold, getAdaptiveTaskGraphSkill, getAgentCompleteHook, getAgentFactoryTemplate, getAgentRegistryTemplate, getApiDesignSkill, getAutoCheckpointHook, getBoardCommand, getBrainstormingSkill, getBrownfieldAnalysisSkill, getBrownfieldDiscoverySkill, getClaudeMdTemplate, getCodeGenSkill, getCoordinatorFactoryTemplate, getDebuggingSkill, getDeploymentSkill, getDocCheckerScript, getDocumentationSkill, getFishiYamlTemplate, getGateCommand, getGateManagerScript, getGitignoreAdditions, getInitCommand, getLearningsManagerScript, getMasterOrchestratorTemplate, getMcpJsonTemplate, getMemoryManagerScript, getModelRoutingReference, getPhaseRunnerScript, getPostEditHook, getPrdCommand, getPrdSkill, getProjectYamlTemplate, getResetCommand, getResumeCommand, getSafetyCheckHook, getSessionStartHook, getSettingsJsonTemplate, getSprintCommand, getStatusCommand, getTaskboardOpsSkill, getTaskboardUpdateHook, getTestingSkill, getTodoManagerScript, getValidateScaffoldScript, getWorktreeManagerScript, getWorktreeSetupHook, marketingAgentTemplate, mergeClaudeMd, mergeClaudeMdTop, mergeGitignore, mergeMcpJson, mergeSettingsJson, opsLeadTemplate, planningAgentTemplate, planningLeadTemplate, qualityLeadTemplate, researchAgentTemplate, securityAgentTemplate, testingAgentTemplate, uiuxAgentTemplate, writingAgentTemplate };
+interface MonitorEvent {
+    type: string;
+    agent: string;
+    data: Record<string, unknown>;
+    timestamp?: string;
+}
+interface MonitorSummary {
+    totalAgentCompletions: number;
+    totalFilesChanged: number;
+    totalTokens: number;
+    tokensByModel: Record<string, number>;
+    tokensByAgent: Record<string, number>;
+    toolsUsed: Record<string, number>;
+    dynamicAgentsCreated: number;
+}
+interface DynamicAgent {
+    name: string;
+    coordinator: string;
+}
+interface MonitorState {
+    events: (MonitorEvent & {
+        timestamp: string;
+    })[];
+    summary: MonitorSummary;
+    dynamicAgents: DynamicAgent[];
+    lastUpdated: string;
+}
+declare function readMonitorState(projectDir: string): MonitorState;
+declare function emitEvent(projectDir: string, event: MonitorEvent): void;
+declare function getAgentSummary(projectDir: string): Record<string, {
+    completions: number;
+    failures: number;
+    filesChanged: number;
+}>;
+
+type SandboxMode = 'docker' | 'process';
+interface SandboxConfig {
+    mode: SandboxMode;
+    dockerAvailable: boolean;
+}
+interface SandboxPolicy {
+    networkAllow: string[];
+    envPassthrough: string[];
+    timeout: number;
+    memory: string;
+    cpus: number;
+}
+interface SandboxRunResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut: boolean;
+}
+/**
+ * Detect if Docker is installed and running.
+ */
+declare function detectDocker(): boolean;
+/**
+ * Read sandbox config from .fishi/fishi.yaml
+ */
+declare function readSandboxConfig(projectDir: string): SandboxConfig;
+/**
+ * Read sandbox policy from .fishi/sandbox-policy.yaml, or return defaults.
+ */
+declare function readSandboxPolicy(projectDir: string): SandboxPolicy;
+/**
+ * Build a restricted env object for process mode.
+ * Strips all env vars except explicitly allowed ones + essentials.
+ */
+declare function buildSandboxEnv(policy: SandboxPolicy): Record<string, string>;
+/**
+ * Run a command in process-mode sandbox.
+ */
+declare function runInProcessSandbox(command: string, args: string[], worktreePath: string, policy: SandboxPolicy): SandboxRunResult;
+/**
+ * Run a command in Docker sandbox.
+ */
+declare function runInDockerSandbox(command: string, args: string[], worktreePath: string, policy: SandboxPolicy, options?: {
+    nodeModulesPath?: string;
+}): SandboxRunResult;
+/**
+ * Run a command in the configured sandbox mode.
+ */
+declare function runInSandbox(command: string, args: string[], worktreePath: string, projectDir: string, options?: {
+    nodeModulesPath?: string;
+}): SandboxRunResult;
+
+declare function getSandboxPolicyTemplate(): string;
+
+declare function getDockerfileTemplate(): string;
+
+declare function getDashboardHtml(): string;
+
+export { type AgentDefinition, type AgentRole, type AgentTemplate, type BackupManifest, type BrownfieldAnalysisData, type ClaudeMdOptions, type CommandTemplate, type ConflictCategory, type ConflictMap, type ConflictResolution, type CostMode, type DetectionCheck, type DetectionResult, type DynamicAgent, type DynamicAgentConfig, type ExecutionConfig, type FileConflict, type FileResolutionMap, type FishiConfig, type FishiYamlOptions, type GateConfig, type GateStatus, type GitConfig, type HookTemplate, type InitOptions, type McpConfig, type McpServerConfig, type ModelRoutingConfig, type ModelTier, type MonitorEvent, type MonitorState, type MonitorSummary, type ProjectConfig, type ProjectType, type ProjectYamlOptions, type SandboxConfig, type SandboxMode, type SandboxPolicy, type SandboxRunResult, type ScaffoldOptions, type ScaffoldResult, type SkillTemplate, type StateConfig, type TaskStatus, type TaskboardConfig, type TemplateContext, architectAgentTemplate, backendAgentTemplate, buildSandboxEnv, createBackup, detectConflicts, detectDocker, devLeadTemplate, devopsAgentTemplate, docsAgentTemplate, emitEvent, frontendAgentTemplate, fullstackAgentTemplate, generateScaffold, getAdaptiveTaskGraphSkill, getAgentCompleteHook, getAgentFactoryTemplate, getAgentRegistryTemplate, getAgentSummary, getApiDesignSkill, getAutoCheckpointHook, getBoardCommand, getBrainstormingSkill, getBrownfieldAnalysisSkill, getBrownfieldDiscoverySkill, getClaudeMdTemplate, getCodeGenSkill, getCoordinatorFactoryTemplate, getDashboardHtml, getDebuggingSkill, getDeploymentSkill, getDocCheckerScript, getDockerfileTemplate, getDocumentationSkill, getFishiYamlTemplate, getGateCommand, getGateManagerScript, getGitignoreAdditions, getInitCommand, getLearningsManagerScript, getMasterOrchestratorTemplate, getMcpJsonTemplate, getMemoryManagerScript, getModelRoutingReference, getMonitorEmitterScript, getPhaseRunnerScript, getPostEditHook, getPrdCommand, getPrdSkill, getProjectYamlTemplate, getResetCommand, getResumeCommand, getSafetyCheckHook, getSandboxPolicyTemplate, getSessionStartHook, getSettingsJsonTemplate, getSprintCommand, getStatusCommand, getTaskboardOpsSkill, getTaskboardUpdateHook, getTestingSkill, getTodoManagerScript, getValidateScaffoldScript, getWorktreeManagerScript, getWorktreeSetupHook, marketingAgentTemplate, mergeClaudeMd, mergeClaudeMdTop, mergeGitignore, mergeMcpJson, mergeSettingsJson, opsLeadTemplate, planningAgentTemplate, planningLeadTemplate, qualityLeadTemplate, readMonitorState, readSandboxConfig, readSandboxPolicy, researchAgentTemplate, runInDockerSandbox, runInProcessSandbox, runInSandbox, securityAgentTemplate, testingAgentTemplate, uiuxAgentTemplate, writingAgentTemplate };

package/dist/index.js

@@ -8217,6 +8217,183 @@ try {
 `;
 }
 
+// src/templates/hooks/monitor-emitter.ts
+function getMonitorEmitterScript() {
+  return `#!/usr/bin/env node
+// monitor-emitter.mjs \u2014 FISHI agent observability event emitter
+//
+// Usage as a library (ESM import in another .mjs hook):
+//   const { emitMonitorEvent } = await import('./.fishi/scripts/monitor-emitter.mjs');
+//   await emitMonitorEvent(process.cwd(), { type: 'agent.completed', agent: 'backend-agent', data: { filesChanged: 3 } });
+//
+// Usage via CLI:
+//   node .fishi/scripts/monitor-emitter.mjs '{"type":"agent.completed","agent":"backend-agent","data":{"filesChanged":3}}'
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+// \u2500\u2500 Constants \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+const MAX_EVENTS = 500;
+
+// \u2500\u2500 State helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+function monitorPath(root) {
+  return join(root, '.fishi', 'state', 'monitor.json');
+}
+
+function emptySummary() {
+  return {
+    totalAgentCompletions: 0,
+    totalFilesChanged: 0,
+    totalTokens: 0,
+    tokensByModel: {},
+    tokensByAgent: {},
+    toolsUsed: {},
+    dynamicAgentsCreated: 0,
+  };
+}
+
+function emptyState() {
+  return {
+    events: [],
+    summary: emptySummary(),
+    dynamicAgents: [],
+    lastUpdated: new Date().toISOString(),
+  };
+}
+
+function readState(root) {
+  const p = monitorPath(root);
+  if (!existsSync(p)) return emptyState();
+  try {
+    return JSON.parse(readFileSync(p, 'utf-8'));
+  } catch {
+    return emptyState();
+  }
+}
+
+function writeState(root, state) {
+  const p = monitorPath(root);
+  const dir = dirname(p);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(p, JSON.stringify(state, null, 2) + '\\n', 'utf-8');
+}
+
+// \u2500\u2500 Summary updater \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+function updateSummary(state, event) {
+  switch (event.type) {
+    case 'agent.completed': {
+      state.summary.totalAgentCompletions++;
+      const files = (event.data && typeof event.data.filesChanged === 'number')
+        ? event.data.filesChanged
+        : 0;
+      state.summary.totalFilesChanged += files;
+      break;
+    }
+    case 'tokens.used': {
+      const input = (event.data && typeof event.data.inputTokens === 'number')
+        ? event.data.inputTokens
+        : 0;
+      const output = (event.data && typeof event.data.outputTokens === 'number')
+        ? event.data.outputTokens
+        : 0;
+      const total = input + output;
+      const model = (event.data && event.data.model) || 'unknown';
+      state.summary.totalTokens += total;
+      state.summary.tokensByModel[model] = (state.summary.tokensByModel[model] || 0) + total;
+      state.summary.tokensByAgent[event.agent] =
+        (state.summary.tokensByAgent[event.agent] || 0) + total;
+      break;
+    }
+    case 'tool.used': {
+      const tool = event.data && event.data.tool;
+      if (tool) {
+        state.summary.toolsUsed[tool] = (state.summary.toolsUsed[tool] || 0) + 1;
+      }
+      break;
+    }
+    case 'agent.created': {
+      if (event.data && event.data.dynamic) {
+        state.summary.dynamicAgentsCreated++;
+        state.dynamicAgents.push({
+          name: event.agent,
+          coordinator: (event.data.coordinator) || 'unknown',
+        });
+      }
+      break;
+    }
+  }
+}
+
+// \u2500\u2500 Public API \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+/**
+ * Emit a monitor event.
+ *
+ * @param {string} root - Project root directory (where .fishi/ lives)
+ * @param {{ type: string, agent: string, data: object, timestamp?: string }} event
+ */
+export function emitMonitorEvent(root, event) {
+  const state = readState(root);
+
+  const timestamped = {
+    ...event,
+    timestamp: event.timestamp || new Date().toISOString(),
+  };
+
+  state.events.push(timestamped);
+  if (state.events.length > MAX_EVENTS) {
+    state.events = state.events.slice(-MAX_EVENTS);
+  }
+
+  updateSummary(state, event);
+
+  state.lastUpdated = new Date().toISOString();
+  writeState(root, state);
+}
+
+// \u2500\u2500 CLI entry point \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+const isMain = process.argv[1] &&
+  (process.argv[1].endsWith('monitor-emitter.mjs') || process.argv[1].endsWith('monitor-emitter'));
+
+if (isMain) {
+  const raw = process.argv[2];
+  if (!raw) {
+    console.error('[FISHI] Usage: node .fishi/scripts/monitor-emitter.mjs '{"type":"...","agent":"...","data":{...}}'');
+    process.exit(1);
+  }
+
+  let event;
+  try {
+    event = JSON.parse(raw);
+  } catch (err) {
+    console.error('[FISHI] monitor-emitter: invalid JSON:', err.message);
+    process.exit(1);
+  }
+
+  if (!event.type || !event.agent) {
+    console.error('[FISHI] monitor-emitter: event must have "type" and "agent" fields');
+    process.exit(1);
+  }
+
+  if (!event.data || typeof event.data !== 'object') {
+    event.data = {};
+  }
+
+  try {
+    emitMonitorEvent(process.cwd(), event);
+    console.log('[FISHI] monitor event emitted:', event.type, '/', event.agent);
+  } catch (err) {
+    console.error('[FISHI] monitor-emitter error:', err.message);
+    process.exit(1);
+  }
+}
+`;
+}
+
 // src/templates/commands/init-command.ts
 function getInitCommand() {
   return `# /fishi-init \u2014 Launch the FISHI Orchestration Pipeline
@@ -10585,7 +10762,8 @@ async function generateScaffold(targetDir, options) {
   await write(".fishi/scripts/memory-manager.mjs", getMemoryManagerScript());
   await write(".fishi/scripts/learnings-manager.mjs", getLearningsManagerScript());
   await write(".fishi/scripts/doc-checker.mjs", getDocCheckerScript());
-  const hookCount = 15;
+  await write(".fishi/scripts/monitor-emitter.mjs", getMonitorEmitterScript());
+  const hookCount = 16;
   const todoTemplate = (name) => `# TODO \u2014 ${name}
 
 ## Active
@@ -10670,6 +10848,12 @@ async function generateScaffold(targetDir, options) {
   await write(".fishi/state/agent-registry.yaml", getAgentRegistryTemplate());
   await write(".fishi/state/task-graph.yaml", "tasks: []\ndependencies: []\n");
   await write(".fishi/state/gates.yaml", "gates: []\n");
+  await write(".fishi/state/monitor.json", JSON.stringify({
+    events: [],
+    summary: { totalAgentCompletions: 0, totalFilesChanged: 0, totalTokens: 0, tokensByModel: {}, tokensByAgent: {}, toolsUsed: {}, dynamicAgentsCreated: 0 },
+    dynamicAgents: [],
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  }, null, 2) + "\n");
   await write(".fishi/mcp-registry.yaml", getMcpRegistryTemplate());
   await write(".fishi/model-routing.md", getModelRoutingReference());
   await write(".fishi/memory/project-context.md", getProjectContextTemplate(ctx));
@@ -10927,7 +11111,7 @@ async function createBackup(targetDir, conflictingFiles) {
       manifestFiles.push({ path: relPath, size: stat.size });
     }
   }
-  const fishiVersion = "0.5.0";
+  const fishiVersion = "0.7.0";
   const manifest = {
     timestamp: now.toISOString(),
     fishi_version: fishiVersion,
@@ -10939,14 +11123,653 @@ async function createBackup(targetDir, conflictingFiles) {
   await rename(tmpPath, manifestPath);
   return backupDir;
 }
+
+// src/generators/monitor.ts
+import { existsSync as existsSync4, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join as join4, dirname as dirname3 } from "path";
+var MAX_EVENTS = 500;
+function monitorPath(projectDir) {
+  return join4(projectDir, ".fishi", "state", "monitor.json");
+}
+function emptySummary() {
+  return {
+    totalAgentCompletions: 0,
+    totalFilesChanged: 0,
+    totalTokens: 0,
+    tokensByModel: {},
+    tokensByAgent: {},
+    toolsUsed: {},
+    dynamicAgentsCreated: 0
+  };
+}
+function emptyState() {
+  return {
+    events: [],
+    summary: emptySummary(),
+    dynamicAgents: [],
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function readMonitorState(projectDir) {
+  const p = monitorPath(projectDir);
+  if (!existsSync4(p)) return emptyState();
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return emptyState();
+  }
+}
+function emitEvent(projectDir, event) {
+  const state = readMonitorState(projectDir);
+  const timestamped = { ...event, timestamp: event.timestamp || (/* @__PURE__ */ new Date()).toISOString() };
+  state.events.push(timestamped);
+  if (state.events.length > MAX_EVENTS) {
+    state.events = state.events.slice(-MAX_EVENTS);
+  }
+  switch (event.type) {
+    case "agent.completed": {
+      state.summary.totalAgentCompletions++;
+      const files = event.data.filesChanged || 0;
+      state.summary.totalFilesChanged += files;
+      break;
+    }
+    case "tokens.used": {
+      const input = event.data.inputTokens || 0;
+      const output = event.data.outputTokens || 0;
+      const total = input + output;
+      const model = event.data.model || "unknown";
+      state.summary.totalTokens += total;
+      state.summary.tokensByModel[model] = (state.summary.tokensByModel[model] || 0) + total;
+      state.summary.tokensByAgent[event.agent] = (state.summary.tokensByAgent[event.agent] || 0) + total;
+      break;
+    }
+    case "tool.used": {
+      const tool = event.data.tool;
+      state.summary.toolsUsed[tool] = (state.summary.toolsUsed[tool] || 0) + 1;
+      break;
+    }
+    case "agent.created": {
+      if (event.data.dynamic) {
+        state.summary.dynamicAgentsCreated++;
+        state.dynamicAgents.push({
+          name: event.agent,
+          coordinator: event.data.coordinator || "unknown"
+        });
+      }
+      break;
+    }
+  }
+  state.lastUpdated = (/* @__PURE__ */ new Date()).toISOString();
+  const dir = dirname3(monitorPath(projectDir));
+  if (!existsSync4(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(monitorPath(projectDir), JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+function getAgentSummary(projectDir) {
+  const state = readMonitorState(projectDir);
+  const agents = {};
+  for (const event of state.events) {
+    if (event.type === "agent.completed") {
+      if (!agents[event.agent]) agents[event.agent] = { completions: 0, failures: 0, filesChanged: 0 };
+      agents[event.agent].completions++;
+      if (event.data.status === "failed") agents[event.agent].failures++;
+      agents[event.agent].filesChanged += event.data.filesChanged || 0;
+    }
+  }
+  return agents;
+}
+
+// src/generators/sandbox.ts
+import { execSync, execFileSync } from "child_process";
+import { existsSync as existsSync5, readFileSync as readFileSync2 } from "fs";
+import { join as join5 } from "path";
+var DEFAULT_POLICY = {
+  networkAllow: ["registry.npmjs.org", "localhost", "127.0.0.1"],
+  envPassthrough: [],
+  timeout: 600,
+  // 10 minutes
+  memory: "2g",
+  cpus: 2
+};
+function detectDocker() {
+  try {
+    execSync("docker info", { stdio: "pipe", timeout: 5e3 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readSandboxConfig(projectDir) {
+  const yamlPath = join5(projectDir, ".fishi", "fishi.yaml");
+  if (!existsSync5(yamlPath)) {
+    return { mode: "process", dockerAvailable: false };
+  }
+  const content = readFileSync2(yamlPath, "utf-8");
+  const modeMatch = content.match(/^\s*mode:\s*(docker|process)/m);
+  const dockerMatch = content.match(/^\s*docker_available:\s*(true|false)/m);
+  return {
+    mode: modeMatch?.[1] || "process",
+    dockerAvailable: dockerMatch?.[1] === "true"
+  };
+}
+function readSandboxPolicy(projectDir) {
+  const policyPath = join5(projectDir, ".fishi", "sandbox-policy.yaml");
+  if (!existsSync5(policyPath)) return { ...DEFAULT_POLICY };
+  const content = readFileSync2(policyPath, "utf-8");
+  const networkAllow = extractYamlList(content, "network_allow") || DEFAULT_POLICY.networkAllow;
+  const envPassthrough = extractYamlList(content, "env_passthrough") || DEFAULT_POLICY.envPassthrough;
+  const timeoutMatch = content.match(/^\s*timeout:\s*(\d+)/m);
+  const memoryMatch = content.match(/^\s*memory:\s*["']?(\S+?)["']?\s*$/m);
+  const cpusMatch = content.match(/^\s*cpus:\s*(\d+)/m);
+  return {
+    networkAllow,
+    envPassthrough,
+    timeout: timeoutMatch ? parseInt(timeoutMatch[1], 10) : DEFAULT_POLICY.timeout,
+    memory: memoryMatch?.[1] || DEFAULT_POLICY.memory,
+    cpus: cpusMatch ? parseInt(cpusMatch[1], 10) : DEFAULT_POLICY.cpus
+  };
+}
+function extractYamlList(content, key) {
+  const regex = new RegExp(`^\\s*${key}:\\s*\\n((?:\\s+-\\s*.+\\n?)*)`, "m");
+  const match = content.match(regex);
+  if (!match) return null;
+  return match[1].split("\n").map((line) => {
+    const m = line.match(/^\s*-\s*["']?(.+?)["']?\s*$/);
+    return m ? m[1] : "";
+  }).filter(Boolean);
+}
+function buildSandboxEnv(policy) {
+  const env = {
+    PATH: process.env.PATH || "",
+    HOME: process.env.HOME || process.env.USERPROFILE || "",
+    NODE_ENV: "development",
+    FISHI_SANDBOX: "true"
+  };
+  for (const key of policy.envPassthrough) {
+    if (process.env[key]) {
+      env[key] = process.env[key];
+    }
+  }
+  return env;
+}
+function runInProcessSandbox(command, args, worktreePath, policy) {
+  const env = buildSandboxEnv(policy);
+  try {
+    const stdout = execFileSync(command, args, {
+      cwd: worktreePath,
+      encoding: "utf-8",
+      timeout: policy.timeout * 1e3,
+      env,
+      stdio: "pipe",
+      maxBuffer: 10 * 1024 * 1024
+      // 10MB
+    });
+    return { stdout, stderr: "", exitCode: 0, timedOut: false };
+  } catch (e) {
+    if (e.killed || e.signal === "SIGTERM") {
+      return { stdout: e.stdout || "", stderr: e.stderr || "", exitCode: 1, timedOut: true };
+    }
+    return {
+      stdout: e.stdout || "",
+      stderr: e.stderr || "",
+      exitCode: e.status ?? 1,
+      timedOut: false
+    };
+  }
+}
+function runInDockerSandbox(command, args, worktreePath, policy, options = {}) {
+  const dockerArgs = [
+    "run",
+    "--rm",
+    "--workdir",
+    "/workspace",
+    "-v",
+    `${worktreePath}:/workspace`
+  ];
+  if (options.nodeModulesPath && existsSync5(options.nodeModulesPath)) {
+    dockerArgs.push("-v", `${options.nodeModulesPath}:/workspace/node_modules:ro`);
+  }
+  dockerArgs.push("--memory", policy.memory);
+  dockerArgs.push("--cpus", String(policy.cpus));
+  dockerArgs.push("-e", "FISHI_SANDBOX=true");
+  dockerArgs.push("-e", "NODE_ENV=development");
+  for (const key of policy.envPassthrough) {
+    if (process.env[key]) {
+      dockerArgs.push("-e", `${key}=${process.env[key]}`);
+    }
+  }
+  dockerArgs.push("--network", "host");
+  dockerArgs.push("fishi-sandbox:latest", command, ...args);
+  try {
+    const stdout = execFileSync("docker", dockerArgs, {
+      encoding: "utf-8",
+      timeout: policy.timeout * 1e3,
+      stdio: "pipe",
+      maxBuffer: 10 * 1024 * 1024
+    });
+    return { stdout, stderr: "", exitCode: 0, timedOut: false };
+  } catch (e) {
+    if (e.killed || e.signal === "SIGTERM") {
+      return { stdout: e.stdout || "", stderr: e.stderr || "", exitCode: 1, timedOut: true };
+    }
+    return {
+      stdout: e.stdout || "",
+      stderr: e.stderr || "",
+      exitCode: e.status ?? 1,
+      timedOut: false
+    };
+  }
+}
+function runInSandbox(command, args, worktreePath, projectDir, options = {}) {
+  const config = readSandboxConfig(projectDir);
+  const policy = readSandboxPolicy(projectDir);
+  if (config.mode === "docker" && config.dockerAvailable) {
+    return runInDockerSandbox(command, args, worktreePath, policy, options);
+  }
+  return runInProcessSandbox(command, args, worktreePath, policy);
+}
+
+// src/templates/configs/sandbox-policy.ts
+function getSandboxPolicyTemplate() {
+  return `# FISHI Sandbox Policy
+# Controls what agents can access inside their sandboxed worktrees
+
+# Network domains agents are allowed to reach
+network_allow:
+  - registry.npmjs.org
+  - localhost
+  - 127.0.0.1
+
+# Environment variables passed into the sandbox
+# Add secrets your agents need (e.g., DATABASE_URL, API_KEY)
+env_passthrough: []
+
+# Maximum time (seconds) a single agent command can run
+timeout: 600
+
+# Docker resource limits (only applies in docker mode)
+memory: "2g"
+cpus: 2
+`;
+}
+
+// src/templates/docker/Dockerfile.ts
+function getDockerfileTemplate() {
+  return `# FISHI Sandbox Runtime
+# Minimal Node.js image for agent execution
+FROM node:22-slim
+
+# Install git and common build tools
+RUN apt-get update && apt-get install -y --no-install-recommends \\
+    git \\
+    ca-certificates \\
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /workspace
+
+# Non-root user for additional safety
+RUN groupadd -r fishi && useradd -r -g fishi -m fishi
+USER fishi
+
+# Default command
+CMD ["node"]
+`;
+}
+
+// src/templates/dashboard/index-html.ts
+function getDashboardHtml() {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>FISHI Agent Dashboard</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      background: #0a0a0f;
+      color: #e2e8f0;
+      font-family: 'Courier New', Courier, monospace;
+      font-size: 14px;
+      min-height: 100vh;
+    }
+
+    /* \u2500\u2500 Header \u2500\u2500 */
+    header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 14px 24px;
+      background: #12121a;
+      border-bottom: 1px solid #1e1e2e;
+    }
+    header h1 { font-size: 18px; color: #06b6d4; letter-spacing: 0.05em; }
+    .status-dot {
+      width: 10px; height: 10px;
+      border-radius: 50%;
+      background: #22c55e;
+      display: inline-block;
+      margin-right: 8px;
+      animation: pulse 2s infinite;
+    }
+    .status-dot.offline { background: #ef4444; animation: none; }
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.4; }
+    }
+    .last-updated { color: #6b7280; font-size: 12px; }
+
+    /* \u2500\u2500 Layout \u2500\u2500 */
+    main { padding: 20px 24px; }
+
+    /* \u2500\u2500 Stat cards \u2500\u2500 */
+    .stat-grid {
+      display: grid;
+      grid-template-columns: repeat(4, 1fr);
+      gap: 12px;
+      margin-bottom: 20px;
+    }
+    @media (max-width: 900px) { .stat-grid { grid-template-columns: repeat(2, 1fr); } }
+    .card {
+      background: #12121a;
+      border: 1px solid #1e1e2e;
+      border-radius: 8px;
+      padding: 16px;
+    }
+    .card-label { color: #6b7280; font-size: 11px; text-transform: uppercase; letter-spacing: 0.08em; margin-bottom: 8px; }
+    .card-value { font-size: 28px; color: #06b6d4; font-weight: bold; }
+
+    /* \u2500\u2500 Phase bar \u2500\u2500 */
+    .phase-section { margin-bottom: 20px; }
+    .phase-bar {
+      display: flex;
+      gap: 4px;
+      flex-wrap: wrap;
+      background: #12121a;
+      border: 1px solid #1e1e2e;
+      border-radius: 8px;
+      padding: 12px 16px;
+    }
+    .phase-pill {
+      padding: 4px 12px;
+      border-radius: 4px;
+      font-size: 12px;
+      color: #6b7280;
+      border: 1px solid #2d2d3d;
+      background: #0a0a0f;
+    }
+    .phase-pill.done { color: #22c55e; border-color: #22c55e; background: rgba(34,197,94,0.08); }
+    .phase-pill.active { color: #06b6d4; border-color: #06b6d4; background: rgba(6,182,212,0.12); font-weight: bold; }
+    .phase-arrow { color: #2d2d3d; align-self: center; }
+
+    /* \u2500\u2500 Main grid \u2500\u2500 */
+    .main-grid {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 16px;
+      margin-bottom: 16px;
+    }
+    @media (max-width: 800px) { .main-grid { grid-template-columns: 1fr; } }
+
+    .panel {
+      background: #12121a;
+      border: 1px solid #1e1e2e;
+      border-radius: 8px;
+      padding: 16px;
+    }
+    .panel-title {
+      color: #94a3b8;
+      font-size: 12px;
+      text-transform: uppercase;
+      letter-spacing: 0.1em;
+      margin-bottom: 12px;
+      border-bottom: 1px solid #1e1e2e;
+      padding-bottom: 8px;
+    }
+
+    /* \u2500\u2500 Events \u2500\u2500 */
+    .event-row {
+      display: flex;
+      gap: 10px;
+      padding: 5px 0;
+      border-bottom: 1px solid #1a1a28;
+      font-size: 12px;
+    }
+    .event-row:last-child { border-bottom: none; }
+    .event-ts { color: #4b5563; min-width: 80px; }
+    .event-type { color: #06b6d4; min-width: 130px; }
+    .event-agent { color: #a78bfa; }
+    .empty-msg { color: #4b5563; font-style: italic; }
+
+    /* \u2500\u2500 Agent activity \u2500\u2500 */
+    .agent-row {
+      display: flex;
+      justify-content: space-between;
+      padding: 6px 0;
+      border-bottom: 1px solid #1a1a28;
+      font-size: 12px;
+    }
+    .agent-row:last-child { border-bottom: none; }
+    .agent-name { color: #a78bfa; }
+    .agent-stats { color: #6b7280; display: flex; gap: 12px; }
+    .stat-ok { color: #22c55e; }
+    .stat-fail { color: #ef4444; }
+    .stat-files { color: #06b6d4; }
+
+    /* \u2500\u2500 Bottom row \u2500\u2500 */
+    .bottom-grid {
+      display: grid;
+      grid-template-columns: 1fr 1fr 1fr;
+      gap: 16px;
+    }
+    @media (max-width: 900px) { .bottom-grid { grid-template-columns: 1fr; } }
+
+    /* \u2500\u2500 KV table \u2500\u2500 */
+    .kv-row {
+      display: flex;
+      justify-content: space-between;
+      padding: 4px 0;
+      border-bottom: 1px solid #1a1a28;
+      font-size: 12px;
+    }
+    .kv-row:last-child { border-bottom: none; }
+    .kv-key { color: #fbbf24; }
+    .kv-val { color: #06b6d4; }
+
+    /* \u2500\u2500 Gates \u2500\u2500 */
+    .gate-row {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      padding: 4px 0;
+      font-size: 12px;
+      border-bottom: 1px solid #1a1a28;
+    }
+    .gate-row:last-child { border-bottom: none; }
+    .gate-dot { width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0; }
+    .gate-dot.passed { background: #22c55e; }
+    .gate-dot.failed { background: #ef4444; }
+    .gate-dot.pending { background: #f59e0b; }
+    .gate-name { color: #e2e8f0; flex: 1; }
+    .gate-status { font-size: 11px; }
+    .gate-status.passed { color: #22c55e; }
+    .gate-status.failed { color: #ef4444; }
+    .gate-status.pending { color: #f59e0b; }
+  </style>
+</head>
+<body>
+  <header>
+    <h1><span class="status-dot" id="statusDot"></span>FISHI Agent Dashboard</h1>
+    <span class="last-updated" id="lastUpdated">Loading...</span>
+  </header>
+  <main>
+    <!-- Stat cards -->
+    <div class="stat-grid">
+      <div class="card"><div class="card-label">Agent Completions</div><div class="card-value" id="statCompletions">\u2014</div></div>
+      <div class="card"><div class="card-label">Files Changed</div><div class="card-value" id="statFiles">\u2014</div></div>
+      <div class="card"><div class="card-label">Total Tokens</div><div class="card-value" id="statTokens">\u2014</div></div>
+      <div class="card"><div class="card-label">Dynamic Agents</div><div class="card-value" id="statDynamic">\u2014</div></div>
+    </div>
+
+    <!-- Phase bar -->
+    <div class="phase-section">
+      <div class="phase-bar" id="phaseBar">Loading phases...</div>
+    </div>
+
+    <!-- Main grid -->
+    <div class="main-grid">
+      <div class="panel">
+        <div class="panel-title">Recent Events</div>
+        <div id="eventsPanel"><span class="empty-msg">No events yet.</span></div>
+      </div>
+      <div class="panel">
+        <div class="panel-title">Agent Activity</div>
+        <div id="agentsPanel"><span class="empty-msg">No agent activity yet.</span></div>
+      </div>
+    </div>
+
+    <!-- Bottom row -->
+    <div class="bottom-grid">
+      <div class="panel">
+        <div class="panel-title">Tokens by Model</div>
+        <div id="tokensPanel"><span class="empty-msg">No data.</span></div>
+      </div>
+      <div class="panel">
+        <div class="panel-title">Tools Used</div>
+        <div id="toolsPanel"><span class="empty-msg">No data.</span></div>
+      </div>
+      <div class="panel">
+        <div class="panel-title">Gates</div>
+        <div id="gatesPanel"><span class="empty-msg">No gates.</span></div>
+      </div>
+    </div>
+  </main>
+
+  <script>
+    const PHASES = ['init', 'discovery', 'planning', 'development', 'testing', 'review', 'deployed'];
+
+    function fmt(n) {
+      if (n >= 1e6) return (n / 1e6).toFixed(1) + 'M';
+      if (n >= 1e3) return (n / 1e3).toFixed(1) + 'K';
+      return String(n);
+    }
+
+    function fmtTime(iso) {
+      try { return new Date(iso).toLocaleTimeString(); } catch { return iso; }
+    }
+
+    function renderPhase(currentPhase) {
+      const idx = PHASES.indexOf(currentPhase);
+      const bar = document.getElementById('phaseBar');
+      let html = '';
+      PHASES.forEach((p, i) => {
+        if (i > 0) html += '<span class="phase-arrow">&#8594;</span>';
+        const cls = i < idx ? 'done' : i === idx ? 'active' : '';
+        html += \`<span class="phase-pill \${cls}">\${p}</span>\`;
+      });
+      bar.innerHTML = html;
+    }
+
+    function renderEvents(events) {
+      const panel = document.getElementById('eventsPanel');
+      const recent = events.slice(-10).reverse();
+      if (!recent.length) { panel.innerHTML = '<span class="empty-msg">No events yet.</span>'; return; }
+      panel.innerHTML = recent.map(ev =>
+        \`<div class="event-row">
+          <span class="event-ts">\${fmtTime(ev.timestamp)}</span>
+          <span class="event-type">\${ev.type}</span>
+          <span class="event-agent">\${ev.agent}</span>
+        </div>\`
+      ).join('');
+    }
+
+    function renderAgents(agentSummary) {
+      const panel = document.getElementById('agentsPanel');
+      const entries = Object.entries(agentSummary);
+      if (!entries.length) { panel.innerHTML = '<span class="empty-msg">No agent activity yet.</span>'; return; }
+      entries.sort((a, b) => b[1].completions - a[1].completions);
+      panel.innerHTML = entries.map(([name, s]) =>
+        \`<div class="agent-row">
+          <span class="agent-name">\${name}</span>
+          <span class="agent-stats">
+            <span class="stat-ok">&#10003; \${s.completions}</span>
+            <span class="stat-fail">\${s.failures > 0 ? '&#10007; ' + s.failures : ''}</span>
+            <span class="stat-files">&#128196; \${s.filesChanged}</span>
+          </span>
+        </div>\`
+      ).join('');
+    }
+
+    function renderKV(data, panelId, keyClass) {
+      const panel = document.getElementById(panelId);
+      const entries = Object.entries(data).sort((a, b) => b[1] - a[1]);
+      if (!entries.length) { panel.innerHTML = '<span class="empty-msg">No data.</span>'; return; }
+      panel.innerHTML = entries.map(([k, v]) =>
+        \`<div class="kv-row"><span class="kv-key">\${k}</span><span class="kv-val">\${fmt(v)}</span></div>\`
+      ).join('');
+    }
+
+    function renderGates(gates) {
+      const panel = document.getElementById('gatesPanel');
+      if (!gates || !gates.length) { panel.innerHTML = '<span class="empty-msg">No gates.</span>'; return; }
+      panel.innerHTML = gates.map(g => {
+        const cls = g.status === 'passed' ? 'passed' : g.status === 'failed' ? 'failed' : 'pending';
+        return \`<div class="gate-row">
+          <span class="gate-dot \${cls}"></span>
+          <span class="gate-name">\${g.name}</span>
+          <span class="gate-status \${cls}">\${g.status}</span>
+        </div>\`;
+      }).join('');
+    }
+
+    async function fetchAndRender() {
+      const dot = document.getElementById('statusDot');
+      const lu = document.getElementById('lastUpdated');
+      try {
+        const res = await fetch('/api/state');
+        if (!res.ok) throw new Error('HTTP ' + res.status);
+        const data = await res.json();
+
+        dot.classList.remove('offline');
+
+        const s = data.summary || {};
+        document.getElementById('statCompletions').textContent = fmt(s.totalAgentCompletions || 0);
+        document.getElementById('statFiles').textContent = fmt(s.totalFilesChanged || 0);
+        document.getElementById('statTokens').textContent = fmt(s.totalTokens || 0);
+        document.getElementById('statDynamic').textContent = fmt(s.dynamicAgentsCreated || 0);
+
+        renderPhase(data.phase || 'init');
+        renderEvents(data.events || []);
+        renderAgents(data.agentSummary || {});
+        renderKV(s.tokensByModel || {}, 'tokensPanel');
+        renderKV(s.toolsUsed || {}, 'toolsPanel');
+        renderGates(data.gates || []);
+
+        lu.textContent = 'Updated: ' + new Date().toLocaleTimeString();
+      } catch (err) {
+        dot.classList.add('offline');
+        lu.textContent = 'Error: ' + err.message;
+      }
+    }
+
+    fetchAndRender();
+    setInterval(fetchAndRender, 2000);
+  </script>
+</body>
+</html>`;
+}
 export {
   architectAgentTemplate,
   backendAgentTemplate,
+  buildSandboxEnv,
   createBackup,
   detectConflicts,
+  detectDocker,
   devLeadTemplate,
   devopsAgentTemplate,
   docsAgentTemplate,
+  emitEvent,
   frontendAgentTemplate,
   fullstackAgentTemplate,
   generateScaffold,
@@ -10954,6 +11777,7 @@ export {
   getAgentCompleteHook,
   getAgentFactoryTemplate,
   getAgentRegistryTemplate,
+  getAgentSummary,
   getApiDesignSkill,
   getAutoCheckpointHook,
   getBoardCommand,
@@ -10963,9 +11787,11 @@ export {
   getClaudeMdTemplate,
   getCodeGenSkill,
   getCoordinatorFactoryTemplate,
+  getDashboardHtml,
   getDebuggingSkill,
   getDeploymentSkill,
   getDocCheckerScript,
+  getDockerfileTemplate,
   getDocumentationSkill,
   getFishiYamlTemplate,
   getGateCommand,
@@ -10977,6 +11803,7 @@ export {
   getMcpJsonTemplate,
   getMemoryManagerScript,
   getModelRoutingReference,
+  getMonitorEmitterScript,
   getPhaseRunnerScript,
   getPostEditHook,
   getPrdCommand,
@@ -10985,6 +11812,7 @@ export {
   getResetCommand,
   getResumeCommand,
   getSafetyCheckHook,
+  getSandboxPolicyTemplate,
   getSessionStartHook,
   getSettingsJsonTemplate,
   getSprintCommand,
@@ -11006,7 +11834,13 @@ export {
   planningAgentTemplate,
   planningLeadTemplate,
   qualityLeadTemplate,
+  readMonitorState,
+  readSandboxConfig,
+  readSandboxPolicy,
   researchAgentTemplate,
+  runInDockerSandbox,
+  runInProcessSandbox,
+  runInSandbox,
   securityAgentTemplate,
   testingAgentTemplate,
   uiuxAgentTemplate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qlucent/fishi-core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Shared templates, types, and generators for the FISHI framework",
   "license": "MIT",
   "type": "module",