@songsid/agend 2.1.4-beta.7 → 2.1.4-beta.9

package/dist/fleet-manager.js

@@ -135,6 +135,8 @@ const CANCEL_BTN_LEDGER_FILE = "cancel-buttons.json";
  * exactly one progress message per turn, and it is the cancel button itself.
  */
 const PROGRESS_UPDATE_INTERVAL_MS = 60_000;
+/** Floor between tool-progress-driven bubble edits (Telegram flood safety). */
+const TOOL_PROGRESS_EDIT_MIN_MS = 4_000;
 /** Elapsed time is only shown once work has clearly outlasted a quick answer. */
 /**
  * Default delay before the button starts showing elapsed time. Configurable via
@@ -253,6 +255,8 @@ export class FleetManager {
     replyDeduper = new ReplyDeduper();
     /** instanceName → what it is doing right now, when the backend can tell us. */
     instanceActivity = new Map();
+    /** instanceName → this turn's tool list (multi-line), for the bubble. */
+    instanceProgress = new Map();
     /** instanceName → tail of deliveries waiting for its IPC to come back. */
     ipcWaitTails = new Map();
     /** instanceName → restart currently executing; concurrent callers join it. */
@@ -1074,19 +1078,34 @@ export class FleetManager {
             this.logger.info({ name }, "Instance already running, skipping");
             return;
         }
+        const backend = config.backend ?? this.fleetConfig?.defaults?.backend ?? "claude-code";
         if (config.general_topic) {
             // antigravity (agy) does not read MCP instructions — fleet context and
             // routing instructions are not injected, so it cannot act as a dispatcher.
-            const backend = config.backend ?? this.fleetConfig?.defaults?.backend ?? "claude-code";
             if (backend === "antigravity") {
                 this.logger.warn({ name }, "antigravity backend does not support MCP instructions — general dispatcher will not work correctly");
                 this.notifyInstanceTopic(name, "⚠️ antigravity backend is not supported for General instances (no MCP instructions injection). Switch to claude-code or kiro-cli.");
             }
-            this.ensureGeneralInstructions(config.working_directory, config.backend);
+            this.ensureGeneralInstructions(config.working_directory, backend, name);
+        }
+        else if (kind === "fleet-topic") {
+            // Workers get only role-eligible on-demand skills. Classic instances are
+            // deliberately excluded: their workspace and conversation lifecycle are
+            // managed independently from fleet-topic workers.
+            try {
+                const skillsWorkDir = this.resolveKnowledgeWorkDir(config.working_directory, backend, name);
+                this.syncRoleSkills(skillsWorkDir, backend, "worker");
+            }
+            catch (err) {
+                // Skill publishing is additive. A read-only or temporarily unavailable
+                // workspace must not turn an otherwise valid worker startup into a
+                // fleet outage.
+                this.logger.warn({ err, name, backend }, "Failed to sync worker skills — continuing startup");
+            }
         }
         await this.lifecycle.start(name, config, topicMode, {
             kind,
-            backend: config.backend ?? this.fleetConfig?.defaults?.backend ?? "claude-code",
+            backend,
             model: this.resolveInstanceModel(name).display,
         });
         // Only clear a stale process status after a real start succeeded.  Clearing
@@ -1661,7 +1680,7 @@ export class FleetManager {
             const generalDir = join(getAgendHome(), name);
             mkdirSync(generalDir, { recursive: true });
             const backendName = fleet.defaults.backend ?? "claude-code";
-            this.ensureGeneralInstructions(generalDir, backendName);
+            this.ensureGeneralInstructions(generalDir, backendName, name);
             fleet.instances[name] = {
                 ...DEFAULT_INSTANCE_CONFIG,
                 working_directory: generalDir,
@@ -2220,6 +2239,26 @@ export class FleetManager {
                 const result = await this.topicCommands.sendCompact(name);
                 await data.respond(result);
             }
+            else if (data.command === "steer") {
+                const name = this.resolveSlashTarget(data.channelId, adapterId);
+                if (!name) {
+                    await data.respond(t("classic.no_agent"));
+                    return;
+                }
+                const steerText = String(data.options?.message ?? "").trim();
+                if (!steerText) {
+                    await data.respond(t("steer.usage"));
+                    return;
+                }
+                // chat_id/message_id stay empty: a slash interaction has no channel
+                // message to react to, and an empty chat_id keeps updateLastChat from
+                // rerouting the instance's replies to the slash context.
+                const result = this.topicCommands.sendSteer(name, steerText, {
+                    chatId: "", messageId: "", username: data.username ?? "user",
+                    userId: data.userId ?? "", threadId: undefined, adapterId, source: "discord",
+                });
+                await data.respond(result);
+            }
             else if (data.command === "clear") {
                 await this.handleClearSlash(data, adapterId);
             }
@@ -2344,6 +2383,26 @@ export class FleetManager {
                 const result = await this.topicCommands.sendCompact(name);
                 await data.respond(result);
             }
+            else if (data.command === "steer") {
+                const name = this.resolveSlashTarget(data.channelId, adapterId);
+                if (!name) {
+                    await data.respond(t("classic.no_agent"));
+                    return;
+                }
+                const steerText = String(data.options?.message ?? "").trim();
+                if (!steerText) {
+                    await data.respond(t("steer.usage"));
+                    return;
+                }
+                // chat_id/message_id stay empty: a slash interaction has no channel
+                // message to react to, and an empty chat_id keeps updateLastChat from
+                // rerouting the instance's replies to the slash context.
+                const result = this.topicCommands.sendSteer(name, steerText, {
+                    chatId: "", messageId: "", username: data.username ?? "user",
+                    userId: data.userId ?? "", threadId: undefined, adapterId, source: "discord",
+                });
+                await data.respond(result);
+            }
         }, this.logger, "adapter.slash_command"));
         await this.topicCommands.registerBotCommands().catch(e => this.logger.warn({ err: e }, "registerBotCommands failed (non-fatal)"));
         // Background-probe each backend's CLI env (version/models) → cli-env cache.
@@ -2626,6 +2685,26 @@ export class FleetManager {
                 const result = await this.topicCommands.sendCompact(name);
                 await data.respond(result);
             }
+            else if (data.command === "steer") {
+                const name = this.resolveSlashTarget(data.channelId, adapterId);
+                if (!name) {
+                    await data.respond(t("classic.no_agent"));
+                    return;
+                }
+                const steerText = String(data.options?.message ?? "").trim();
+                if (!steerText) {
+                    await data.respond(t("steer.usage"));
+                    return;
+                }
+                // chat_id/message_id stay empty: a slash interaction has no channel
+                // message to react to, and an empty chat_id keeps updateLastChat from
+                // rerouting the instance's replies to the slash context.
+                const result = this.topicCommands.sendSteer(name, steerText, {
+                    chatId: "", messageId: "", username: data.username ?? "user",
+                    userId: data.userId ?? "", threadId: undefined, adapterId, source: "discord",
+                });
+                await data.respond(result);
+            }
         }, this.logger, `adapter[${adapterId}].slash_command`));
         await adapter.start();
         if (channelConfig.group_id) {
@@ -2743,6 +2822,9 @@ export class FleetManager {
                 else if (msg.type === "instance_activity") {
                     this.cacheInstanceActivity(name, msg.activity);
                 }
+                else if (msg.type === "instance_progress") {
+                    this.cacheInstanceProgress(name, msg.progress || null);
+                }
                 else if (msg.type === "instance_state" || msg.type === "instance_state_response") {
                     this.cacheInstanceExecutionState(name, msg);
                     if (msg.type === "instance_state_response") {
@@ -3190,6 +3272,24 @@ export class FleetManager {
                     await msgAdapter?.sendText(chatId, result);
                     return;
                 }
+                // /steer — interject into the running turn. Not admin-gated: anyone who
+                // can talk to this agent can send it a message; steer only changes when
+                // it lands, and it keeps the full [user:] formatting (unlike /raw).
+                if (text === "/steer" || text.startsWith("/steer ") || text.startsWith("/steer@")) {
+                    const steerName = this.classicChannels.getInstanceByChannel(chatId, msg.adapterId);
+                    if (!steerName) {
+                        await msgAdapter?.sendText(chatId, t("classic.no_agent_start"));
+                        return;
+                    }
+                    const steerContent = text.replace(/^\/steer(@\S+)?/, "").trim();
+                    if (!steerContent) {
+                        await msgAdapter?.sendText(chatId, t("steer.usage"));
+                        return;
+                    }
+                    const result = this.topicCommands.sendSteer(steerName, steerContent, msg);
+                    await msgAdapter?.sendText(chatId, result);
+                    return;
+                }
                 // Handle /clear command (admin only) — unlike /compact this starts a
                 // fresh conversation and intentionally discards the current history.
                 if (text === "/clear" || text.startsWith("/clear@")) {
@@ -5115,6 +5215,80 @@ export class FleetManager {
         else
             this.instanceActivity.delete(name);
     }
+    /**
+     * Cache the turn's tool-progress list and push it into the instance's live
+     * bubble, coalesced so a burst of tool events cannot flood the Bot API
+     * (Telegram's flood limit is per-chat across ALL forum topics, so edits are
+     * rate-limited per bubble AND ride behind the daemon-side 3s coalescer).
+     */
+    cacheInstanceProgress(name, progress) {
+        if (progress)
+            this.instanceProgress.set(name, progress);
+        else
+            this.instanceProgress.delete(name);
+        for (const entry of this.cancelButtons.values()) {
+            if (entry.instanceName === name)
+                this.scheduleProgressEdit(entry);
+        }
+    }
+    /** At most one progress-driven edit per bubble per TOOL_PROGRESS_EDIT_MIN_MS. */
+    scheduleProgressEdit(entry) {
+        const since = Date.now() - (entry.lastProgressEditAt ?? 0);
+        if (since >= TOOL_PROGRESS_EDIT_MIN_MS) {
+            this.refreshBubble(entry);
+            return;
+        }
+        if (entry.progressEditTimer)
+            return; // trailing edit already scheduled
+        entry.progressEditTimer = setTimeout(() => {
+            entry.progressEditTimer = undefined;
+            this.refreshBubble(entry);
+        }, TOOL_PROGRESS_EDIT_MIN_MS - since);
+        entry.progressEditTimer.unref?.();
+    }
+    /**
+     * The ONE composer for the bubble text. Both writers — the elapsed-time
+     * ticker and the tool-progress push — go through here; two independent
+     * renderers editing the same message is how the progress list used to get
+     * wiped by the next elapsed tick (#528 trap 2).
+     */
+    composeBubbleText(entry) {
+        return FleetManager.bubbleText(Date.now() - (entry.startedAt ?? Date.now()), this.instanceActivity.get(entry.instanceName), this.progressMinElapsedMs(), this.instanceProgress.get(entry.instanceName));
+    }
+    /** Pure composition of header + tool list, exposed for tests. */
+    static bubbleText(elapsedMs, activity, minElapsedMs, progress) {
+        const header = FleetManager.progressText(elapsedMs, 
+        // The single-line activity detail is redundant once a tool list exists.
+        progress ? undefined : activity, minElapsedMs);
+        return progress ? `${header}\n${progress}` : header;
+    }
+    /** Recompose and edit the bubble in place; skips when nothing changed. */
+    refreshBubble(entry) {
+        if (!this.cancelButtons.has(entry.messageId)) {
+            clearInterval(entry.progressTimer);
+            return;
+        }
+        const text = this.composeBubbleText(entry);
+        if (text === entry.lastProgressText)
+            return; // nothing changed — skip the API call
+        const adapter = this.getAdapterForInstance(entry.instanceName) ?? this.adapter;
+        if (!adapter?.editAlert)
+            return;
+        entry.lastProgressText = text;
+        entry.lastProgressEditAt = Date.now();
+        adapter.editAlert(entry.chatId, entry.messageId, {
+            type: "cancel",
+            instanceName: entry.instanceName,
+            message: text,
+            choices: [{ id: `cancel:${entry.instanceName}`, label: t("cancel.button") }],
+        }, entry.threadId ? { threadId: entry.threadId } : undefined)
+            .catch(err => {
+            // A failed progress edit must never escalate: the button still works and
+            // the next tick retries. Common causes are a deleted message or a
+            // rate limit.
+            this.logger.debug({ err, instanceName: entry.instanceName }, "Progress edit failed");
+        });
+    }
     /**
      * Refresh the button's text in place while the instance keeps working.
      *
@@ -5132,31 +5306,7 @@ export class FleetManager {
         return PROGRESS_MIN_ELAPSED_MS;
     }
     startProgressTicker(entry) {
-        const tick = () => {
-            if (!this.cancelButtons.has(entry.messageId)) {
-                clearInterval(entry.progressTimer);
-                return;
-            }
-            const text = FleetManager.progressText(Date.now() - (entry.startedAt ?? Date.now()), this.instanceActivity.get(entry.instanceName), this.progressMinElapsedMs());
-            if (text === entry.lastProgressText)
-                return; // nothing changed — skip the API call
-            const adapter = this.getAdapterForInstance(entry.instanceName) ?? this.adapter;
-            if (!adapter?.editAlert)
-                return;
-            entry.lastProgressText = text;
-            adapter.editAlert(entry.chatId, entry.messageId, {
-                type: "cancel",
-                instanceName: entry.instanceName,
-                message: text,
-                choices: [{ id: `cancel:${entry.instanceName}`, label: t("cancel.button") }],
-            }, entry.threadId ? { threadId: entry.threadId } : undefined)
-                .catch(err => {
-                // A failed progress edit must never escalate: the button still works and
-                // the next tick retries. Common causes are a deleted message or a
-                // rate limit.
-                this.logger.debug({ err, instanceName: entry.instanceName }, "Progress edit failed");
-            });
-        };
+        const tick = () => this.refreshBubble(entry);
         entry.progressTimer = setInterval(tick, PROGRESS_UPDATE_INTERVAL_MS);
         entry.progressTimer.unref?.();
         // One extra tick right when the threshold passes, so a 30s threshold shows
@@ -5224,6 +5374,8 @@ export class FleetManager {
             clearInterval(entry.idleCheckTimer);
         if (entry.progressTimer)
             clearInterval(entry.progressTimer);
+        if (entry.progressEditTimer)
+            clearTimeout(entry.progressEditTimer);
         if (entry.replyGraceTimer)
             clearTimeout(entry.replyGraceTimer);
         this.cancelButtons.delete(entry.messageId);
@@ -5482,6 +5634,10 @@ export class FleetManager {
         "gemini-cli": "GEMINI.md",
         "opencode": "AGENTS.md",
         "kiro-cli": ".kiro/steering/project.md",
+        // Grok reads AGENTS.md project docs; agy reads .agents/agents.md — the
+        // same files their writeConfig() appends fleet instructions to.
+        "grok": "AGENTS.md",
+        "antigravity": ".agents/agents.md",
         "mock": "CLAUDE.md",
     };
     static GENERAL_INSTRUCTIONS = `# Fleet Coordinator
@@ -5491,146 +5647,33 @@ You route tasks, manage instances, enforce policies, and synthesize results.
 Do NOT modify project files directly — delegate file changes to the project's instance.
 You CAN write code snippets, explain code, and answer technical questions directly.
 
------
-
-## Task Classification
-
-Classify every incoming request before acting.
-
-### Handle Directly (ALL conditions must be true)
-
-- No file system access needed
-- No external execution needed
-- Answerable from static knowledge
-- ≤ 2 reasoning steps
-
-Examples: Q&A, translation, fleet status queries, explaining a concept, writing code snippets.
-
-### Delegate to 1 Instance
-
-- Task scoped to a single project or repo
-- Requires file access, code changes, or execution
-
-### Coordinate Multiple Instances
-
-- Task spans multiple repos or domains
-- Requires outputs from one instance to feed into another
-- Benefits from parallel execution (max 3 instances per task)
-
------
-
-## Instance Discovery (in this order)
-1. list_teams()        → reuse existing teams first
-2. list_instances()    → find by working_directory, description, or tags
-3. describe_instance() → confirm capabilities before delegating
-4. create_instance()   → only if no suitable instance exists
-
-Rules: prefer reuse over creation. Do NOT create duplicates of running instances.
-
------
-
-## Delegation Protocol
+## Task Routing
 
-Every delegation via send_to_instance() MUST include:
+- **Handle directly**: no file/exec access needed, answerable from knowledge, ≤2 reasoning steps (Q&A, translation, status queries, code snippets).
+- **Delegate to 1 instance**: scoped to one project/repo, needs file access or execution.
+- **Coordinate multiple**: spans repos, outputs feed each other, or parallel helps (max 3 per task).
 
-1. Task scope — what exactly to do, bounded clearly
-2. Expected output — what to return and in what form
-3. Policy reminder — "Follow Development Workflow policy" (for code tasks)
+Instance discovery order: list_teams() → list_instances() → describe_instance() → create_instance() only if nothing fits. Prefer reuse; never duplicate a running instance.
 
-### Loop Prevention
+## Reply Contract
 
-- Never re-delegate a task back to the instance that sent it to you
-- If a task has bounced 3 times, stop and solve locally or reduce scope
-
-### Execution Strategy
-
-Parallel — use only when tasks are independent with no shared state
-Sequential — use when one task's output feeds into the next
-
------
-
-## Result Handling
-
-When an instance reports back, classify the outcome:
-
-- Success → Summarize key results for user. Omit internal coordination noise.
-- Partial → State what succeeded, what remains, proposed next steps.
-- Failure → Retry up to 2 times. If still failing: try alternative instance, reduce scope, or return partial result clearly marked.
-- No response → Ping again after reasonable wait. If still silent: report to user with options.
-
-### Output to User
-
-Every final response to the user should contain:
-
-- Result — the actual answer or deliverable
-- Gaps — anything incomplete or unresolved (omit if none)
-
------
-
-## Shared Decisions
-
-Use post_decision() / list_decisions() for any choice that affects more than 1 instance, changes an API contract, introduces a new dependency, or alters deployment process.
-
-When instances disagree, collect both viewpoints, make a decision, and record it via post_decision.
-
------
+Every final response to the user contains: the result (the actual answer or deliverable) and gaps (anything incomplete — omit if none). Summarize instance reports; omit internal coordination noise.
 
 ## After Restart
 
-After a restart, run this sequence BEFORE processing any new messages:
-1. list_instances()   → rebuild fleet awareness
-2. list_teams()       → restore team structure
-3. list_decisions()   → reload policies and conventions
-
-Only then handle incoming requests.
-
------
-
-## Development Workflow Policy
-
-All code changes across the fleet should follow this workflow.
-The coordinator enforces compliance but does not perform these steps directly.
-Remind instances of this policy when delegating code tasks.
-
-### Workflow Stages
-Design Proposed → Design Approved → Implementation → Submit for Review → Under Review → Approved → Merge
-
-### Policy Rules
-
-1. Design before code — developer sends design proposal to reviewer before implementation. Consensus required before proceeding.
-2. Challenger pairing — every code task should have a developer + reviewer. Reviewer actively questions decisions and finds risks.
-3. Verify by execution — backend/CLI changes must be tested by running them. Do not trust documentation alone.
-4. Independent review — every merge requires code review from someone other than the author.
-5. Root cause first — bug fixes require confirmed root cause before proposing a fix.
-6. Merge conditions: tests pass, reviewer approved, branch and worktree cleaned up.
+BEFORE processing any new messages: 1. list_instances() 2. list_teams() 3. list_decisions(). Only then handle requests.
 
-### Specialist Instance Rules
+## Playbooks (on-demand skills)
 
-- Execute within defined scope only
-- Return structured output: result, assumptions, uncertainties, verification status
-- Do NOT create new instances without coordinator approval
-
------
-
-## Team Management
-
-- Always check existing teams before creating new ones
-- Default to ephemeral teams (created for a specific task, dissolved after completion)
-- Clean up ephemeral teams and instances after task completion
-
------
-
-## Instance Configuration Tips
-
-When users create specialized instances, suggest these configurations:
-
-- **Reviewer instances**: Add \`pre_task_command: "/chat load reviewer-base"\` to reset context before each review, preventing influence from previous conversations.
-- **Collab mode**: For multi-bot channels, use \`/collab\` to enable @mention-based triggering.
-- **Cost control**: Set per-instance \`cost_guard\` for expensive backends.
+Detailed procedures live in your skills — consult them when the situation comes up rather than from memory:
+- **delegation-playbook** — delegation protocol, loop prevention, parallel vs sequential, result/failure handling, team management, instance configuration tips.
+- **development-workflow** — the fleet-wide code-change policy you enforce when delegating code tasks.
+Plus the operational skills (fleet-health, instance-lifecycle, scheduling, session-management, …).
 `;
     /** Ensure the general instance has its project instructions file + knowledge */
-    ensureGeneralInstructions(workDir, backendName) {
+    ensureGeneralInstructions(workDir, backendName, instanceName) {
         const backend = backendName ?? "claude-code";
+        workDir = this.resolveKnowledgeWorkDir(workDir, backend, instanceName);
         const filename = FleetManager.INSTRUCTIONS_FILENAME[backend] ?? "CLAUDE.md";
         const filePath = join(workDir, filename);
         mkdirSync(dirname(filePath), { recursive: true });
@@ -5638,60 +5681,238 @@ When users create specialized instances, suggest these configurations:
             writeFileSync(filePath, FleetManager.GENERAL_INSTRUCTIONS, "utf-8");
             this.logger.info({ filePath }, "Created general instance instructions file");
         }
-        // Sync bundled knowledge files to general's steering directory
+        // Sync bundled knowledge files to general's steering and skills directories.
         this.syncGeneralKnowledge(workDir, backend);
     }
-    /** Copy general-knowledge steering + skills to the general instance's workspace */
+    /** Resolve the workspace path a backend actually uses before publishing knowledge. */
+    resolveKnowledgeWorkDir(workDir, backend, instanceName) {
+        // Some backends relocate their real cwd (agy moves hidden paths to
+        // ~/agend-workspaces/<name>). Instructions and skills must land where the
+        // CLI actually runs, not where fleet.yaml points.
+        try {
+            const resolved = createBackend(backend, join(getAgendHome(), "cli-env"))
+                .resolveWorkingDirectory?.(workDir, instanceName);
+            if (resolved)
+                workDir = resolved;
+        }
+        catch { /* unknown backend name — keep the raw path */ }
+        return workDir;
+    }
+    /**
+     * Where each backend natively loads on-demand skills from, relative to the
+     * workspace. Backends without a native skill mechanism (opencode, grok,
+     * antigravity, gemini-cli) are deliberately absent: dropping files a CLI
+     * never reads is clutter, not capability. Unknown directories are ignored
+     * by older CLI versions, so publishing is fail-open across upgrades.
+     */
+    static SKILLS_DIR_SEGMENTS = {
+        "kiro-cli": [".kiro", "skills"],
+        "claude-code": [".claude", "skills"],
+        "codex": [".agents", "skills"],
+        // Live-verified: OpenCode and Antigravity scan .agents/skills; Grok's
+        // vendor-canonical location is .grok/skills.
+        "opencode": [".agents", "skills"],
+        "grok": [".grok", "skills"],
+        "antigravity": [".agents", "skills"],
+    };
+    /** Copy general-knowledge steering + all role-eligible skills to General. */
     syncGeneralKnowledge(workDir, backend) {
         const knowledgeDir = join(dirname(fileURLToPath(import.meta.url)), "general-knowledge");
         if (!existsSync(knowledgeDir))
             return;
-        // Sync steering files → .kiro/steering/ (or workDir root for non-kiro)
-        const steeringDir = backend === "kiro-cli"
-            ? join(workDir, ".kiro", "steering")
-            : workDir;
-        mkdirSync(steeringDir, { recursive: true });
-        const srcSteering = join(knowledgeDir, "steering");
-        if (existsSync(srcSteering)) {
-            for (const file of readdirSync(srcSteering)) {
-                if (!file.endsWith(".md"))
-                    continue;
-                const src = join(srcSteering, file);
+        this.syncGeneralSteering(workDir, backend, join(knowledgeDir, "steering"));
+        this.syncRoleSkills(workDir, backend, "general", knowledgeDir);
+        this.logger.debug({ knowledgeDir, workDir, backend }, "Synced general knowledge files");
+    }
+    /** Publish only the bundled skills eligible for an instance role. */
+    syncRoleSkills(workDir, backend, role, knowledgeDir) {
+        const skillSegments = FleetManager.SKILLS_DIR_SEGMENTS[backend];
+        if (!skillSegments)
+            return;
+        const root = knowledgeDir ?? join(dirname(fileURLToPath(import.meta.url)), "general-knowledge");
+        if (!existsSync(root))
+            return;
+        // Before managed-skill manifests existed, only Kiro General received
+        // bundled skills. Allow that one legacy layout to be adopted so upgrades
+        // can keep those copies current; other backends never had unmanaged
+        // AgEnD-published skills and must retain the normal user-ownership guard.
+        const adoptLegacyUnmanaged = backend === "kiro-cli" && role === "general";
+        this.syncManagedSkills(join(workDir, ...skillSegments), join(root, "skills"), role, adoptLegacyUnmanaged);
+        this.logger.debug({ workDir, backend, role }, "Synced role-based bundled skills");
+    }
+    /**
+     * Steering (always-on rules like core-rules.md). Kiro loads a native
+     * steering directory; every other backend gets the content embedded into
+     * its instructions file (CLAUDE.md / AGENTS.md / …) inside a managed marker
+     * block — the previous behavior dropped bare .md files in the workspace
+     * root, which no CLI ever read. The block is replaced in place on every
+     * sync, so rule updates reach EXISTING workspaces; everything the user
+     * wrote outside the markers is preserved byte-for-byte.
+     */
+    syncGeneralSteering(workDir, backend, srcSteering) {
+        if (!existsSync(srcSteering))
+            return;
+        const files = readdirSync(srcSteering).filter(f => f.endsWith(".md")).sort();
+        if (files.length === 0)
+            return;
+        if (backend === "kiro-cli") {
+            const steeringDir = join(workDir, ".kiro", "steering");
+            mkdirSync(steeringDir, { recursive: true });
+            for (const file of files) {
                 const dest = join(steeringDir, file);
-                const newContent = readFileSync(src, "utf-8");
+                const newContent = readFileSync(join(srcSteering, file), "utf-8");
                 try {
                     if (existsSync(dest) && readFileSync(dest, "utf-8") === newContent)
                         continue;
                 }
-                catch { }
+                catch { /* rewrite */ }
                 writeFileSync(dest, newContent);
             }
+            return;
         }
-        // Sync skills → .kiro/skills/ (kiro-cli only)
-        if (backend === "kiro-cli") {
-            const srcSkills = join(knowledgeDir, "skills");
-            if (existsSync(srcSkills)) {
-                const destSkills = join(workDir, ".kiro", "skills");
-                mkdirSync(destSkills, { recursive: true });
-                for (const skillDir of readdirSync(srcSkills)) {
-                    const skillSrc = join(srcSkills, skillDir);
-                    if (!existsSync(join(skillSrc, "SKILL.md")))
-                        continue;
-                    const skillDest = join(destSkills, skillDir);
-                    mkdirSync(skillDest, { recursive: true });
-                    const src = join(skillSrc, "SKILL.md");
-                    const dest = join(skillDest, "SKILL.md");
-                    const newContent = readFileSync(src, "utf-8");
-                    try {
-                        if (existsSync(dest) && readFileSync(dest, "utf-8") === newContent)
-                            continue;
-                    }
-                    catch { }
-                    writeFileSync(dest, newContent);
-                }
+        const filename = FleetManager.INSTRUCTIONS_FILENAME[backend] ?? "CLAUDE.md";
+        const instructionsPath = join(workDir, filename);
+        const body = files.map(f => readFileSync(join(srcSteering, f), "utf-8").trim()).join("\n\n");
+        const block = `${FleetManager.STEERING_BLOCK_BEGIN}\n${body}\n${FleetManager.STEERING_BLOCK_END}`;
+        let existing = "";
+        try {
+            existing = existsSync(instructionsPath) ? readFileSync(instructionsPath, "utf-8") : "";
+        }
+        catch { /* treat as empty */ }
+        const beginAt = existing.indexOf(FleetManager.STEERING_BLOCK_BEGIN);
+        const endAt = existing.indexOf(FleetManager.STEERING_BLOCK_END);
+        let next;
+        if (beginAt !== -1 && endAt !== -1 && endAt > beginAt) {
+            next = existing.slice(0, beginAt) + block + existing.slice(endAt + FleetManager.STEERING_BLOCK_END.length);
+        }
+        else {
+            next = existing.trimEnd() + (existing.trim() ? "\n\n" : "") + block + "\n";
+        }
+        if (next !== existing) {
+            mkdirSync(dirname(instructionsPath), { recursive: true });
+            writeFileSync(instructionsPath, next);
+        }
+    }
+    static STEERING_BLOCK_BEGIN = "<!-- >>> agend:core-rules — managed by AgEnD; edits inside this block are overwritten -->";
+    static STEERING_BLOCK_END = "<!-- <<< agend:core-rules -->";
+    /**
+     * Publish AgEnD's bundled skills into a CLI's native skills directory,
+     * owning ONLY what we published. A manifest records which skill names AgEnD
+     * wrote; a bundled rename/removal deletes the stale managed copy, while a
+     * skill the user created by hand is never listed and therefore never
+     * touched — even if a future bundle happens to reuse its name (the sync
+     * then skips it and logs, rather than overwrite the user's work). The sole
+     * migration exception is the pre-manifest Kiro General layout explicitly
+     * selected by adoptLegacyUnmanaged.
+     */
+    syncManagedSkills(destSkills, srcSkills, role, adoptLegacyUnmanaged = false) {
+        if (!existsSync(srcSkills))
+            return;
+        mkdirSync(destSkills, { recursive: true });
+        const manifestPath = join(destSkills, ".agend-managed-skills.json");
+        const hadManifest = existsSync(manifestPath);
+        let previouslyManaged = [];
+        try {
+            const parsed = JSON.parse(readFileSync(manifestPath, "utf-8"));
+            if (Array.isArray(parsed))
+                previouslyManaged = parsed.filter(n => typeof n === "string");
+        }
+        catch { /* first sync, or corrupt manifest — treat as owning nothing */ }
+        const bundled = readdirSync(srcSkills)
+            .filter(name => existsSync(join(srcSkills, name, "SKILL.md")))
+            .sort();
+        // Pre-manifest Kiro General copied bundled skills directly into
+        // .kiro/skills. If every existing skill is still a bundled name, this is
+        // the unambiguous legacy layout: adopt it once, update it below, and write
+        // the ownership manifest. Any extra skill name keeps the directory fully
+        // on the user-owned/collision path.
+        if (!hadManifest && adoptLegacyUnmanaged) {
+            const existing = readdirSync(destSkills, { withFileTypes: true })
+                .filter(entry => entry.isDirectory() && existsSync(join(destSkills, entry.name, "SKILL.md")))
+                .map(entry => entry.name)
+                .sort();
+            if (existing.length > 0 && existing.every(name => bundled.includes(name))) {
+                previouslyManaged = existing;
+                this.logger.info({ skills: existing, destSkills }, "Adopted legacy AgEnD skills into managed ownership");
+            }
+        }
+        const eligible = bundled.filter(name => {
+            const roles = this.readManagedSkillRoles(join(srcSkills, name, "SKILL.md"));
+            // General is the coordinator and receives both coordinator and worker
+            // playbooks. Workers receive only skills explicitly marked for workers.
+            return role === "general" || roles.includes("worker");
+        });
+        const managed = [];
+        for (const name of eligible) {
+            const destDir = join(destSkills, name);
+            const dest = join(destDir, "SKILL.md");
+            const isOurs = previouslyManaged.includes(name) || !existsSync(destDir);
+            if (!isOurs) {
+                // Name collision with a user-authored skill: theirs wins, loudly.
+                this.logger.warn({ skill: name, destSkills }, "Skipping bundled skill — a skill of this name exists but was not published by AgEnD");
+                continue;
+            }
+            managed.push(name);
+            const newContent = readFileSync(join(srcSkills, name, "SKILL.md"), "utf-8");
+            try {
+                if (existsSync(dest) && readFileSync(dest, "utf-8") === newContent)
+                    continue;
+            }
+            catch { /* rewrite */ }
+            mkdirSync(destDir, { recursive: true });
+            writeFileSync(dest, newContent);
+        }
+        // Remove managed skills that are no longer bundled OR no longer eligible
+        // for this role. This makes a shared → general-only metadata change take
+        // effect on the next worker startup instead of leaving stale capability.
+        for (const stale of previouslyManaged) {
+            if (eligible.includes(stale))
+                continue;
+            try {
+                rmSync(join(destSkills, stale), { recursive: true, force: true });
+                this.logger.info({ skill: stale, destSkills }, "Removed retired AgEnD-managed skill");
+            }
+            catch (err) {
+                this.logger.debug({ err, skill: stale }, "Failed to remove retired managed skill");
             }
         }
-        this.logger.debug({ knowledgeDir, steeringDir }, "Synced general knowledge files");
+        try {
+            writeFileSync(manifestPath, JSON.stringify(managed, null, 2) + "\n");
+        }
+        catch (err) {
+            this.logger.debug({ err, manifestPath }, "Failed to write managed-skills manifest");
+        }
+    }
+    /** Read AgEnD's roles extension from SKILL.md YAML frontmatter. */
+    readManagedSkillRoles(skillPath) {
+        const fallback = ["general"];
+        try {
+            const content = readFileSync(skillPath, "utf-8");
+            const match = content.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+            if (!match)
+                return fallback;
+            const document = parseDocument(match[1]);
+            if (document.errors.length > 0)
+                throw document.errors[0];
+            const frontmatter = document.toJS();
+            if (!frontmatter || frontmatter.roles === undefined)
+                return fallback;
+            if (!Array.isArray(frontmatter.roles))
+                throw new Error("roles must be an array");
+            const roles = [...new Set(frontmatter.roles)]
+                .filter((value) => value === "general" || value === "worker");
+            if (roles.length !== frontmatter.roles.length || roles.length === 0) {
+                throw new Error("roles must contain only general and/or worker");
+            }
+            return roles;
+        }
+        catch (err) {
+            // Fail closed for workers: malformed or unknown metadata keeps the
+            // backwards-compatible General-only behavior instead of leaking an
+            // administrative skill into worker workspaces.
+            this.logger.warn({ err, skillPath }, "Invalid bundled skill roles — defaulting to General only");
+            return fallback;
+        }
     }
     /** Fetch forum topic icon stickers and pick emoji IDs for each state */
     async resolveTopicIcons() {