tycono 0.3.45-beta.2 → 0.3.45-beta.3

package/packages/server/bin/server.ts

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import net from 'node:net';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const VERSION = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8')
+).version;
+
+function printHelp(): void {
+  console.log(`
+  tycono-server v${VERSION}
+
+  AI team orchestration server. Headless by default.
+
+  Usage:
+    tycono-server [path]       Start API server (default: current directory)
+    tycono-server --help       Show this help
+    tycono-server --version    Show version
+
+  Examples:
+    tycono-server                    Start in current directory
+    tycono-server ./my-company       Start with company directory
+    PORT=3001 tycono-server          Use specific port
+
+  Environment:
+    PORT                     Server port (default: auto-detect free port)
+    COMPANY_ROOT             Company directory (default: current directory)
+`);
+}
+
+function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, () => {
+      const addr = server.address();
+      if (addr && typeof addr === 'object') {
+        const port = addr.port;
+        server.close(() => resolve(port));
+      } else {
+        reject(new Error('Could not find free port'));
+      }
+    });
+    server.on('error', reject);
+  });
+}
+
+function detectEngine(): string {
+  try {
+    execSync('claude --version', { stdio: 'pipe' });
+    return 'claude-cli';
+  } catch {}
+  if (process.env.ANTHROPIC_API_KEY) return 'direct-api';
+  return 'none';
+}
+
+export async function main(args: string[]): Promise<void> {
+  const command = args[0];
+
+  if (command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (command === '--version' || command === '-v') {
+    console.log(VERSION);
+    return;
+  }
+
+  // Load .env
+  const dotenvPath = path.resolve(process.cwd(), '.env');
+  if (fs.existsSync(dotenvPath)) {
+    const { config } = await import('dotenv');
+    config({ path: dotenvPath });
+  }
+
+  // Company root
+  if (command && !command.startsWith('-')) {
+    process.env.COMPANY_ROOT = path.resolve(command);
+  }
+  if (!process.env.COMPANY_ROOT) {
+    process.env.COMPANY_ROOT = process.cwd();
+  }
+
+  // Check for knowledge/ subdirectory pattern
+  const knowledgeDir = path.join(process.env.COMPANY_ROOT, 'knowledge');
+  if (fs.existsSync(path.join(knowledgeDir, 'CLAUDE.md'))) {
+    // Company root is the parent of knowledge/
+  } else if (!fs.existsSync(path.join(process.env.COMPANY_ROOT, 'CLAUDE.md'))) {
+    // Scan one level deep
+    try {
+      const entries = fs.readdirSync(process.env.COMPANY_ROOT, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+        if (fs.existsSync(path.join(process.env.COMPANY_ROOT, entry.name, '.tycono', 'config.json'))) {
+          process.env.COMPANY_ROOT = path.join(process.env.COMPANY_ROOT, entry.name);
+          break;
+        }
+      }
+    } catch {}
+  }
+
+  process.env.NODE_ENV = 'production';
+
+  // Detect engine
+  const engine = detectEngine();
+  process.env.EXECUTION_ENGINE = engine;
+
+  // Port
+  const port = process.env.PORT ? Number(process.env.PORT) : await findFreePort();
+  process.env.PORT = String(port);
+
+  // Company name
+  let companyName = 'My Company';
+  try {
+    const claudeMdPath = path.join(process.env.COMPANY_ROOT, 'CLAUDE.md');
+    if (fs.existsSync(claudeMdPath)) {
+      const content = fs.readFileSync(claudeMdPath, 'utf-8');
+      const match = content.match(/^#\s+(.+)/m);
+      if (match) companyName = match[1].trim();
+    }
+  } catch {}
+
+  const url = `http://localhost:${port}`;
+
+  console.log(`  tycono-server v${VERSION}`);
+  console.log(`  API: ${url}`);
+  console.log(`  Company: ${companyName}`);
+  console.log(`  Engine: ${engine}`);
+  console.log(`  PID: ${process.pid}`);
+
+  // Write headless.json for discovery
+  const headlessInfo = { port, pid: process.pid, url, startedAt: new Date().toISOString() };
+  const headlessPath = path.join(process.env.COMPANY_ROOT, '.tycono', 'headless.json');
+  try {
+    fs.mkdirSync(path.dirname(headlessPath), { recursive: true });
+    fs.writeFileSync(headlessPath, JSON.stringify(headlessInfo, null, 2));
+  } catch {}
+
+  // Start server
+  const { createHttpServer } = await import('../src/api/src/create-server.js');
+  const server = createHttpServer();
+
+  const host = process.env.HOST || '0.0.0.0';
+  server.listen(port, host);
+
+  // Graceful shutdown with active wave guard (BUG-CONCURRENT protection)
+  let forceShutdown = false;
+  let forceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const doShutdown = () => {
+    console.log('\n  Shutting down...');
+    try { fs.unlinkSync(headlessPath); } catch {}
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(1), 5000);
+  };
+
+  const shutdown = async () => {
+    try {
+      const { getActiveWaveCount } = await import('../src/api/src/create-server.js');
+      const activeCount = getActiveWaveCount();
+
+      if (activeCount > 0 && !forceShutdown) {
+        console.log(`\n  ⚠️  ${activeCount} active wave(s) running. Press Ctrl+C again within 5s to force shutdown.`);
+        forceShutdown = true;
+        forceTimer = setTimeout(() => { forceShutdown = false; }, 5000);
+        return;
+      }
+    } catch {
+      // If we can't check, proceed with shutdown
+    }
+
+    if (forceTimer) clearTimeout(forceTimer);
+    doShutdown();
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', doShutdown);
+}

package/{src → packages/server/src}/api/src/create-server.ts

@@ -39,11 +39,18 @@ import { AnthropicProvider, type LLMProvider } from './engine/llm-adapter.js';
 import { readConfig } from './services/company-config.js';
 import { ensureClaudeMd } from './services/claude-md-manager.js';
 
+import { supervisorHeartbeat } from './services/supervisor-heartbeat.js';
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const isProd = process.env.NODE_ENV === 'production';
 const corsOrigin = isProd ? true : /^http:\/\/localhost:\d+$/;
 
+/** Get count of active waves (for shutdown guard) */
+export function getActiveWaveCount(): number {
+  return supervisorHeartbeat.listActive().length;
+}
+
 /* ─── Raw HTTP handler for import-knowledge SSE ─── */
 
 function handleImportKnowledge(req: http.IncomingMessage, res: http.ServerResponse): void {
@@ -101,7 +108,8 @@ export function createHttpServer(): http.Server {
   const app = createExpressApp();
 
   const server = http.createServer((req, res) => {
-    const url = req.url ?? '';
+    const rawUrl = req.url ?? '';
+    const url = rawUrl.split('?')[0]; // Strip query string for route matching
     const method = req.method ?? '';
 
     // GET /api/waves/active — restore active waves after refresh
@@ -150,8 +158,8 @@ export function createHttpServer(): http.Server {
       return;
     }
 
-    // Non-SSE exec/jobs endpoints (GET, DELETE)
-    if ((url.startsWith('/api/exec/') || url.startsWith('/api/jobs')) && (method === 'GET' || method === 'DELETE')) {
+    // Non-SSE exec/jobs/waves endpoints (GET, DELETE)
+    if ((url.startsWith('/api/exec/') || url.startsWith('/api/jobs') || url.startsWith('/api/waves/')) && (method === 'GET' || method === 'DELETE')) {
       setExecCors(req, res);
       handleExecRequest(req, res);
       return;

package/{src → packages/server/src}/api/src/engine/agent-loop.ts

@@ -1,4 +1,4 @@
-import { AnthropicProvider, type LLMProvider, type LLMMessage, type ToolResult, type MessageContent } from './llm-adapter.js';
+import { AnthropicProvider, type LLMProvider, type LLMMessage, type ToolResult, type MessageContent, type SystemPrompt } from './llm-adapter.js';
 import { type OrgTree, getSubordinates } from './org-tree.js';
 import { assembleContext, type TeamStatus } from './context-assembler.js';
 import { validateDispatch, validateConsult } from './authority-validator.js';
@@ -30,6 +30,7 @@ export interface AgentConfig {
   attachments?: ImageAttachment[];  // Image attachments for vision
   targetRoles?: string[];          // Selective dispatch scope
   presetId?: string;               // Wave-scoped preset for knowledge injection
+  priorDispatches?: Array<{ roleId: string; task: string; result: string }>;  // Handoff summary
   // Callbacks
   onText?: (text: string) => void;
   onToolExec?: (name: string, input: Record<string, unknown>) => void;
@@ -163,11 +164,32 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
   const llm = config.llm ?? new AnthropicProvider();
 
   // 1. Assemble context
-  const context = assembleContext(companyRoot, roleId, task, sourceRole, orgTree, { teamStatus: config.teamStatus, targetRoles: config.targetRoles, presetId: config.presetId });
+  const context = assembleContext(companyRoot, roleId, task, sourceRole, orgTree, { teamStatus: config.teamStatus, targetRoles: config.targetRoles, presetId: config.presetId, priorDispatches: config.priorDispatches });
 
   // Trace: capture assembled prompt for debugging
   config.onPromptAssembled?.(context.systemPrompt, task);
 
+  // Build cached system prompt from structured sections (for Anthropic prompt caching)
+  const cachedPrompt: SystemPrompt = (() => {
+    const blocks: Array<{ type: 'text'; text: string; cache_control?: { type: 'ephemeral' } }> = [];
+    let staticBuf = '';
+    for (const s of context.sections) {
+      if (s.cacheable) {
+        staticBuf += (staticBuf ? '\n\n---\n\n' : '') + s.text;
+      } else {
+        if (staticBuf) {
+          blocks.push({ type: 'text', text: staticBuf, cache_control: { type: 'ephemeral' } });
+          staticBuf = '';
+        }
+        blocks.push({ type: 'text', text: s.text });
+      }
+    }
+    if (staticBuf) {
+      blocks.push({ type: 'text', text: staticBuf, cache_control: { type: 'ephemeral' } });
+    }
+    return blocks.length > 0 ? blocks : context.systemPrompt;
+  })();
+
   // 2. Determine tools
   const subordinates = getSubordinates(orgTree, roleId);
   const hasBash = !readOnly && !!config.codeRoot;
@@ -221,6 +243,7 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
         sessionId: config.sessionId,
         model: config.model,
         tokenLedger: config.tokenLedger,
+        priorDispatches: dispatches, // Handoff: pass accumulated results to sub-agent
         onText: (text) => onText?.(`[${targetRoleId}] ${text}`),
         onToolExec,
       });
@@ -323,7 +346,7 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
     }
 
     // Call LLM
-    const response = await llm.chat(context.systemPrompt, messages, tools, abortSignal);
+    const response = await llm.chat(cachedPrompt, messages, tools, abortSignal);
     totalInput += response.usage.inputTokens;
     totalOutput += response.usage.outputTokens;
 
@@ -496,7 +519,7 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
         if (abortSignal?.aborted) break;
         turns++;
 
-        const supResponse = await llm.chat(context.systemPrompt, messages, tools, abortSignal);
+        const supResponse = await llm.chat(cachedPrompt, messages, tools, abortSignal);
         totalInput += supResponse.usage.inputTokens;
         totalOutput += supResponse.usage.outputTokens;
         config.tokenLedger?.record({
@@ -576,7 +599,7 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
 
       if (turns < maxTurns) {
         turns++;
-        const verifyResponse = await llm.chat(context.systemPrompt, messages, tools, abortSignal);
+        const verifyResponse = await llm.chat(cachedPrompt, messages, tools, abortSignal);
         totalInput += verifyResponse.usage.inputTokens;
         totalOutput += verifyResponse.usage.outputTokens;
         config.tokenLedger?.record({
@@ -622,7 +645,7 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
 
           if (turns < maxTurns) {
             turns++;
-            const summaryResponse = await llm.chat(context.systemPrompt, messages, tools, abortSignal);
+            const summaryResponse = await llm.chat(cachedPrompt, messages, tools, abortSignal);
             totalInput += summaryResponse.usage.inputTokens;
             totalOutput += summaryResponse.usage.outputTokens;
             config.tokenLedger?.record({
@@ -676,7 +699,7 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
         if (abortSignal?.aborted) break;
         turns++;
 
-        const postKResponse = await llm.chat(context.systemPrompt, messages, tools, abortSignal);
+        const postKResponse = await llm.chat(cachedPrompt, messages, tools, abortSignal);
         totalInput += postKResponse.usage.inputTokens;
         totalOutput += postKResponse.usage.outputTokens;
         config.tokenLedger?.record({

package/{src → packages/server/src}/api/src/engine/context-assembler.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { readPreferences } from '../services/preferences.js';
 import { readConfig, resolveCodeRoot } from '../services/company-config.js';
@@ -14,8 +15,15 @@ import { extractKeywords, searchRelatedDocs } from './knowledge-gate.js';
 
 /* ─── Types ──────────────────────────────────── */
 
+export interface PromptSection {
+  text: string;
+  cacheable: boolean;
+}
+
 export interface AssembledContext {
   systemPrompt: string;
+  /** Structured sections for prompt caching — cacheable sections get cache_control */
+  sections: PromptSection[];
   task: string;
   sourceRole: string;
   targetRole: string;
@@ -51,60 +59,62 @@ export function assembleContext(
   task: string,
   sourceRole: string,
   orgTree: OrgTree,
-  options?: { teamStatus?: TeamStatus; targetRoles?: string[]; presetId?: string },
+  options?: { teamStatus?: TeamStatus; targetRoles?: string[]; presetId?: string; priorDispatches?: Array<{ roleId: string; task: string; result: string }> },
 ): AssembledContext {
   const node = orgTree.nodes.get(roleId);
   if (!node) {
     throw new Error(`Role not found in org tree: ${roleId}`);
   }
 
-  const sections: string[] = [];
+  const taggedSections: PromptSection[] = [];
+  // Helper: push with cacheability tag
+  const pushSection = (text: string, cacheable: boolean) => taggedSections.push({ text, cacheable });
 
-  // 1. Company Rules (CLAUDE.md + custom-rules.md + company.md)
+  // 1. Company Rules (CLAUDE.md + custom-rules.md + company.md) — CACHEABLE
   const companyRules = loadCompanyRules(companyRoot);
   if (companyRules) {
-    sections.push(companyRules);
+    pushSection(companyRules, true);
   }
 
-  // 2. Org Context
-  sections.push(buildOrgContextSection(orgTree, node));
+  // 2. Org Context — CACHEABLE (static per role)
+  pushSection(buildOrgContextSection(orgTree, node), true);
 
-  // 3. Role Persona
-  sections.push(buildPersonaSection(node));
+  // 3. Role Persona — CACHEABLE
+  pushSection(buildPersonaSection(node), true);
 
-  // 4. Authority Rules
-  sections.push(buildAuthoritySection(node));
+  // 4. Authority Rules — CACHEABLE
+  pushSection(buildAuthoritySection(node), true);
 
-  // 5. Knowledge Scope
-  sections.push(buildKnowledgeSection(node));
+  // 5. Knowledge Scope — CACHEABLE
+  pushSection(buildKnowledgeSection(node), true);
 
-  // 6. SKILL.md (Role-specific + equipped shared skills)
+  // 6. SKILL.md (Role-specific + equipped shared skills) — CACHEABLE
   const skillContent = loadSkillMd(companyRoot, roleId);
   if (skillContent) {
-    sections.push('# Skills & Tools\n\n' + skillContent);
+    pushSection('# Skills & Tools\n\n' + skillContent, true);
   }
 
-  // 6b. Shared Skills (from role.yaml skills field)
+  // 6b. Shared Skills (from role.yaml skills field) — CACHEABLE
   const sharedSkills = loadSharedSkills(companyRoot, node.skills);
   if (sharedSkills) {
-    sections.push('# Equipped Skills\n\n' + sharedSkills);
+    pushSection('# Equipped Skills\n\n' + sharedSkills, true);
   }
 
-  // 7. Hub Docs (요약)
+  // 7. Hub Docs (요약) — CACHEABLE
   const hubSummary = loadHubSummaries(companyRoot, node);
   if (hubSummary) {
-    sections.push('# Reference Documents\n\n' + hubSummary);
+    pushSection('# Reference Documents\n\n' + hubSummary, true);
   }
 
-  // 8. CEO Decisions (전사 공지)
+  // 8. CEO Decisions (전사 공지) — CACHEABLE
   const ceoDecisions = loadCeoDecisions(companyRoot);
   if (ceoDecisions) {
-    sections.push('# CEO Decisions (전사 공지)\n\n' + ceoDecisions);
+    pushSection('# CEO Decisions (전사 공지)\n\n' + ceoDecisions, true);
   }
 
-  // 9. Code Root (코드 프로젝트 경로)
+  // 9. Code Root (코드 프로젝트 경로) — CACHEABLE (static per company)
   const codeRoot = resolveCodeRoot(companyRoot);
-  sections.push(`# Code Project
+  pushSection(`# Code Project
 
 The code repository is located at: \`${codeRoot}\` (env: $TYCONO_CODE_ROOT)
 The AKB (knowledge) directory is at: \`${companyRoot}\` (env: $TYCONO_AKB_ROOT)
@@ -115,19 +125,36 @@ Use the code repository path for all source code work (reading, writing, buildin
 - Your cwd is already set to the code repository. When creating worktrees, use relative paths or \`$TYCONO_CODE_ROOT\`.
 - **NEVER run \`git worktree add\` in \`$TYCONO_AKB_ROOT\`** — the AKB directory is not a code repository.
 - Recommended worktree path: \`$TYCONO_CODE_ROOT/.worktrees/{branch-name}\`
-- Example: \`git worktree add .worktrees/feature-xyz -b feature/xyz\` (from cwd, which is already code repo)`);
+- Example: \`git worktree add .worktrees/feature-xyz -b feature/xyz\` (from cwd, which is already code repo)`, true);
 
-  // 10. Pre-Knowledging: 작업 관련 문서 자동 탐색
+  // 10. Pre-Knowledging: 작업 관련 문서 자동 탐색 — NOT cacheable (task-dependent)
   const preKSection = buildPreKnowledgingSection(companyRoot, task);
   if (preKSection) {
-    sections.push(preKSection);
+    pushSection(preKSection, false);
   }
 
-  // 11. Preset Knowledge (wave-scoped preset docs)
+  // 11. Preset Knowledge (wave-scoped preset docs) — CACHEABLE (static per wave)
   if (options?.presetId && options.presetId !== 'default') {
     const presetKnowledge = loadPresetKnowledge(companyRoot, options.presetId);
     if (presetKnowledge) {
-      sections.push('# Preset Knowledge\n\n' + presetKnowledge);
+      pushSection('# Preset Knowledge\n\n' + presetKnowledge, true);
+    }
+  }
+
+  // 12. Handoff Summary — NOT cacheable (dynamic per dispatch)
+  if (options?.priorDispatches && options.priorDispatches.length > 0) {
+    const sameRole = options.priorDispatches.filter(d => d.roleId === roleId);
+    if (sameRole.length > 0) {
+      const summaries = sameRole.map((d, i) =>
+        `### Session ${i + 1}\n**Task**: ${d.task.slice(0, 200)}\n**Result**: ${d.result.slice(0, 500)}`
+      ).join('\n\n');
+      pushSection(`# Previous Session Results (Handoff Summary)
+
+This role has been dispatched ${sameRole.length} time(s) before in this wave. **DO NOT repeat completed work.**
+
+${summaries}
+
+> Build on these results. Skip investigation that was already done. Focus on NEW or UNFINISHED items only.`, false);
     }
   }
 
@@ -140,23 +167,23 @@ Use the code repository path for all source code work (reading, writing, buildin
     subordinates = subordinates.filter(id => options.targetRoles!.includes(id));
   }
 
-  // Supervision prompt (SV-11, SV-12: C-Level heartbeat mode)
+  // Supervision prompt (SV-11, SV-12: C-Level heartbeat mode) — CACHEABLE
   const heartbeatEnabled = node.heartbeat?.enabled === true;
   if (heartbeatEnabled && subordinates.length > 0) {
-    sections.push(buildSupervisionSection(node));
+    pushSection(buildSupervisionSection(node), true);
   }
 
-  // Knowledge consistency management (C-Level responsibility)
+  // Knowledge consistency management (C-Level responsibility) — CACHEABLE
   if (node.level === 'c-level') {
-    sections.push(buildKnowledgeManagementSection(roleId));
+    pushSection(buildKnowledgeManagementSection(roleId), true);
   }
 
-  // Dispatch 도구 안내 (하위 Role이 있는 경우)
+  // Dispatch 도구 안내 (하위 Role이 있는 경우) — NOT cacheable (teamStatus varies)
   if (subordinates.length > 0) {
-    sections.push(buildDispatchSection(orgTree, roleId, subordinates, options?.teamStatus));
+    pushSection(buildDispatchSection(orgTree, roleId, subordinates, options?.teamStatus), false);
   } else if (node.level === 'c-level') {
     // C-level with no subordinates — clarify authority boundaries
-    sections.push(`# Team Structure
+    pushSection(`# Team Structure
 
 ⚠️ **You have no direct reports.** You are an individual contributor at the C-level.
 
@@ -164,21 +191,21 @@ Use the code repository path for all source code work (reading, writing, buildin
 - You CAN consult other roles for information (see Consult section below)
 - You MUST do the work yourself — research, analyze, write, decide
 - If implementation requires another role (e.g., engineering work), recommend it to CEO
-- Make decisions within your authority autonomously — do NOT ask CEO for decisions you can make yourself`);
+- Make decisions within your authority autonomously — do NOT ask CEO for decisions you can make yourself`, true);
   }
 
-  // Consult 도구 안내 (상담 가능한 Role이 있는 경우)
+  // Consult 도구 안내 — CACHEABLE
   const consultSection = buildConsultSection(orgTree, roleId);
   if (consultSection) {
-    sections.push(consultSection);
+    pushSection(consultSection, true);
   }
 
-  // Language preference (default: English)
+  // Language preference — CACHEABLE
   const prefs = readPreferences(companyRoot);
   const lang = prefs.language && prefs.language !== 'auto' ? prefs.language : 'en';
   const langNames: Record<string, string> = { en: 'English', ko: 'Korean (한국어)', ja: 'Japanese (日本語)' };
   const langName = langNames[lang] ?? lang;
-  sections.push(`# Language (CRITICAL)
+  pushSection(`# Language (CRITICAL)
 
 You MUST respond in **${langName}**.
 
@@ -190,10 +217,10 @@ This applies to ALL output without exception:
 - Git commit messages and PR descriptions
 
 Code (variable names, comments in code) may remain in English for readability.
-Everything else MUST be in ${langName}.`);
+Everything else MUST be in ${langName}.`, true);
 
-  // Execution behavior rules (prevents infinite exploration loops in -p mode)
-  sections.push(`# Execution Rules (CRITICAL)
+  // Execution behavior rules — CACHEABLE
+  pushSection(`# Execution Rules (CRITICAL)
 
 ## Interpreting Tasks
 - A [CEO Wave] is a directive from the CEO. Interpret it based on your role's expertise.
@@ -229,12 +256,13 @@ Everything else MUST be in ${langName}.`);
 - Use a descriptive commit message: \`git commit -m "type(scope): description"\`
 - Common types: feat, fix, refactor, test, chore
 - This ensures your work is not lost in uncommitted changes.
-- Do NOT push — just commit locally. Your superior or the system handles push/PR.`);
+- Do NOT push — just commit locally. Your superior or the system handles push/PR.`, true);
 
-  const systemPrompt = sections.join('\n\n---\n\n');
+  const systemPrompt = taggedSections.map(s => s.text).join('\n\n---\n\n');
 
   return {
     systemPrompt,
+    sections: taggedSections,
     task,
     sourceRole,
     targetRole: roleId,
@@ -271,22 +299,43 @@ ${docList}
 }
 
 /**
- * Load knowledge docs from a preset's knowledge/ directory.
+ * Load knowledge docs from a preset/agency's knowledge/ directory.
+ * 2-Layer Knowledge: merges docs from multiple sources (deduplicated by filename).
+ *
+ * Search order:
+ *   1. {companyRoot}/knowledge/presets/{presetId}/knowledge/  (legacy/local presets)
+ *   2. {companyRoot}/.tycono/agencies/{presetId}/knowledge/   (local agency install)
+ *   3. ~/.tycono/agencies/{presetId}/knowledge/               (global agency install)
+ *
  * Returns concatenated content (capped at 2000 chars per doc).
  */
 function loadPresetKnowledge(companyRoot: string, presetId: string): string | null {
-  const knowledgeDir = path.join(companyRoot, 'knowledge', 'presets', presetId, 'knowledge');
-  if (!fs.existsSync(knowledgeDir)) return null;
-
+  const candidateDirs = [
+    path.join(companyRoot, 'knowledge', 'presets', presetId, 'knowledge'),
+    path.join(companyRoot, '.tycono', 'agencies', presetId, 'knowledge'),
+    path.join(os.homedir(), '.tycono', 'agencies', presetId, 'knowledge'),
+  ];
+
+  // Collect docs from all sources, deduplicate by filename (first wins)
+  const seenFiles = new Set<string>();
   const parts: string[] = [];
-  try {
-    const entries = fs.readdirSync(knowledgeDir).filter(f => f.endsWith('.md'));
-    for (const file of entries.slice(0, 10)) { // Cap at 10 docs
-      const content = fs.readFileSync(path.join(knowledgeDir, file), 'utf-8');
-      const preview = content.slice(0, 2000);
-      parts.push(`## ${file}\n\n${preview}${content.length > 2000 ? '\n\n... (truncated)' : ''}`);
-    }
-  } catch { /* ignore */ }
+
+  for (const knowledgeDir of candidateDirs) {
+    if (!fs.existsSync(knowledgeDir)) continue;
+    try {
+      const entries = fs.readdirSync(knowledgeDir).filter(f => f.endsWith('.md'));
+      for (const file of entries) {
+        if (seenFiles.has(file)) continue; // deduplicate: first source wins
+        seenFiles.add(file);
+        if (seenFiles.size > 10) break; // Cap at 10 docs total
+
+        const content = fs.readFileSync(path.join(knowledgeDir, file), 'utf-8');
+        const preview = content.slice(0, 2000);
+        parts.push(`## ${file}\n\n${preview}${content.length > 2000 ? '\n\n... (truncated)' : ''}`);
+      }
+    } catch { /* ignore unreadable dirs */ }
+    if (seenFiles.size >= 10) break;
+  }
 
   return parts.length > 0 ? parts.join('\n\n---\n\n') : null;
 }
@@ -606,7 +655,23 @@ python3 "$SUPERVISION_CMD" watch ses-aaa${subordinates.length > 1 ? ',ses-bbb' :
 ### ⛔ CRITICAL Rules
 - **NEVER re-dispatch the same task.** If --check shows RUNNING, just keep polling.
 - **NEVER dispatch and immediately finish.** The dispatch→check→review loop must continue until ALL work is complete.
-- **Save the job ID** from each dispatch to use with --check.`;
+- **Save the job ID** from each dispatch to use with --check.
+
+### ⛔ Amend-First Rule (COST CRITICAL)
+When a subordinate needs follow-up work on the SAME topic, **amend instead of re-dispatch**.
+Re-dispatch creates a new session that reloads ALL context from scratch (expensive).
+Amend sends instructions to the existing session — near-zero additional cost.
+
+\`\`\`bash
+# ❌ WRONG: re-dispatch (wastes tokens reloading context)
+python3 "$DISPATCH_CMD" ${exampleSubId} "fix the bug again"
+
+# ✅ CORRECT: amend existing session (keeps context, near-zero cost)
+python3 "$SUPERVISION_CMD" amend ses-xxx "Critic found issue: [details]. Fix it."
+\`\`\`
+
+**When to amend**: Follow-up on same files/code the role already touched.
+**When to dispatch new**: Genuinely unrelated new task scope.`;
 
   // C-level roles get mandatory delegation rules
   if (isCLevel) {