opencode-swarm 7.164.12 → 7.164.13

package/dist/commands/registry.d.ts

@@ -30,10 +30,31 @@ export type CommandContext = {
     activeAgentName?: string;
     reviewAgentModelRegistry?: ReviewAgentModelRegistry;
 };
-export type CommandResult = Promise<string>;
+/**
+ * Issue #2493 (#1646 item 3): opt-in structured failure channel. A handler
+ * may return a plain string (ok — CLI exits 0, chat prints it verbatim) or
+ * this shape to signal failure; the CLI maps `ok: false` to `exitCode ?? 1`
+ * while the chat path displays `text` unchanged (chat has no exit codes).
+ */
+export type CommandFailure = {
+    /** User-facing failure text (also what the chat path displays). */
+    text: string;
+    ok: false;
+    /** CLI exit code; defaults to 1 when omitted. */
+    exitCode?: number;
+};
+export type CommandResult = Promise<string | CommandFailure>;
+/** Type guard for the CommandFailure half of the CommandResult union. */
+export declare function isCommandFailure(value: string | CommandFailure): value is CommandFailure;
 export type CommandCategory = 'core' | 'agent' | 'config' | 'diagnostics' | 'utility';
 export type CommandEntry = {
-    handler: (ctx: CommandContext) => CommandResult;
+    /**
+     * Command handler. OPTIONAL on pure alias entries (#1646 via #2493): an
+     * entry without a handler MUST carry a valid `aliasOf` (enforced by
+     * validateAliases) and `resolveCommand` dereferences to the canonical
+     * entry — new aliases never redeclare the canonical handler.
+     */
+    handler?: (ctx: CommandContext) => CommandResult;
     /** Human-readable description shown in /swarm help and CLI --help */
     description: string;
     /** If true, this command is only accessible as a sub-key of a parent command */
@@ -131,56 +152,48 @@ export declare const COMMAND_REGISTRY: {
         readonly toolPolicy: "none";
     };
     readonly 'blueprint-validate': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "TUI shortcut alias for blueprint validate";
         readonly category: "utility";
         readonly aliasOf: "blueprint validate";
         readonly deprecated: true;
     };
     readonly 'blueprint-current': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "TUI shortcut alias for blueprint current";
         readonly category: "utility";
         readonly aliasOf: "blueprint current";
         readonly deprecated: true;
     };
     readonly 'blueprint-history': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "TUI shortcut alias for blueprint history";
         readonly category: "utility";
         readonly aliasOf: "blueprint history";
         readonly deprecated: true;
     };
     readonly 'blueprint-diff': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "TUI shortcut alias for blueprint diff";
         readonly category: "utility";
         readonly aliasOf: "blueprint diff";
         readonly deprecated: true;
     };
     readonly 'blueprint-export': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "TUI shortcut alias for blueprint export";
         readonly category: "utility";
         readonly aliasOf: "blueprint export";
         readonly deprecated: true;
     };
     readonly 'harness-candidate-validate': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "TUI shortcut alias for harness candidate validate";
         readonly category: "utility";
         readonly aliasOf: "harness candidate validate";
         readonly deprecated: true;
     };
     readonly 'harness-candidate-show': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "TUI shortcut alias for harness candidate show";
         readonly category: "utility";
         readonly aliasOf: "harness candidate show";
         readonly deprecated: true;
     };
     readonly 'harness-candidate-diff': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "TUI shortcut alias for harness candidate diff";
         readonly category: "utility";
         readonly aliasOf: "harness candidate diff";
@@ -216,7 +229,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolNoArgs: true;
     };
     readonly 'context-map-stats': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Show aggregated context-capsule telemetry stats";
         readonly category: "diagnostics";
         readonly aliasOf: "context-map stats";
@@ -230,7 +242,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolPolicy: "agent";
     };
     readonly plan: {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Show current plan (deprecated alias for /swarm show-plan)";
         readonly category: "core";
         readonly clashesWithNativeCcCommand: "/plan";
@@ -278,7 +289,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolNoArgs: true;
     };
     readonly 'config-doctor': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Run config doctor checks";
         readonly subcommandOf: "config";
         readonly category: "diagnostics";
@@ -293,7 +303,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolNoArgs: true;
     };
     readonly 'doctor-tools': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Run tool registration coherence check";
         readonly category: "diagnostics";
         readonly aliasOf: "doctor tools";
@@ -307,7 +316,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolNoArgs: true;
     };
     readonly diagnosis: {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Run health check on swarm state";
         readonly category: "diagnostics";
         readonly aliasOf: "diagnose";
@@ -327,14 +335,12 @@ export declare const COMMAND_REGISTRY: {
         readonly toolPolicy: "agent";
     };
     readonly 'guardrail-explain': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Dry-run: show what the guardrails would do to a command or write target (executes nothing)";
         readonly category: "diagnostics";
         readonly aliasOf: "guardrail explain";
         readonly deprecated: true;
     };
     readonly 'guardrail-reset': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Reset one exact active invocation/action circuit after repair";
         readonly category: "diagnostics";
         readonly aliasOf: "guardrail reset";
@@ -370,9 +376,14 @@ export declare const COMMAND_REGISTRY: {
         readonly toolNoArgs: true;
     };
     readonly benchmark: {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly handler: (ctx: CommandContext) => Promise<string | {
+            text: string;
+            ok: false;
+            exitCode: number;
+        }>;
         readonly description: "Show performance metrics [--cumulative] [--ci-gate] [--max-cost-usd <n>] [--gate-audit-run <id>]";
         readonly args: "--cumulative, --ci-gate, --max-cost-usd <n>, --gate-audit-run <id>";
+        readonly details: "Exit codes (#2493 review F-14): with --ci-gate, the process exits 0 only when every quality check passes and 1 on any failure, budget breach, or missing evidence — CI-safe by construction. Without --ci-gate the command is informational and always exits 0.";
         readonly category: "diagnostics";
         readonly toolPolicy: "agent";
     };
@@ -515,7 +526,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolNoArgs: true;
     };
     readonly 'evidence-summary': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Generate evidence summary with completion ratio and blockers";
         readonly subcommandOf: "evidence";
         readonly args: "";
@@ -525,7 +535,6 @@ export declare const COMMAND_REGISTRY: {
         readonly deprecated: true;
     };
     readonly doctor: {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Run config doctor checks";
         readonly category: "diagnostics";
         readonly aliasOf: "config doctor";
@@ -533,35 +542,30 @@ export declare const COMMAND_REGISTRY: {
         readonly clashesWithNativeCcCommand: "/doctor";
     };
     readonly info: {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Show current swarm state (plus background-work health when hooks.background_subagents is enabled)";
         readonly category: "core";
         readonly aliasOf: "status";
         readonly deprecated: true;
     };
     readonly 'list-agents': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "List registered agents";
         readonly category: "core";
         readonly aliasOf: "agents";
         readonly deprecated: true;
     };
     readonly health: {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Run health check on swarm state";
         readonly category: "diagnostics";
         readonly aliasOf: "diagnose";
         readonly deprecated: true;
     };
     readonly check: {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Run preflight automation checks";
         readonly category: "diagnostics";
         readonly aliasOf: "preflight";
         readonly deprecated: true;
     };
     readonly clear: {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Clear session state while preserving plan, evidence, and knowledge";
         readonly category: "utility";
         readonly aliasOf: "reset-session";
@@ -616,13 +620,12 @@ export declare const COMMAND_REGISTRY: {
     readonly finalize: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Use /swarm finalize to finalize the swarm project and archive evidence";
-        readonly details: "Idempotent 4-stage terminal finalization: (1) finalize writes retrospectives for in-progress phases, (2) archive creates timestamped bundle of swarm artifacts and evidence, (3) clean removes active-state files for a clean slate, (4) align performs aggressive git reset --hard to the default remote branch, discarding uncommitted changes and gitignored build artifacts (user-created untracked files are preserved); falls back to a cautious reset that preserves uncommitted changes when the aggressive path cannot proceed. WARNING: alignment discards local changes and gitignored files. Resets agent sessions, delegation chains, and active-agent mappings. Reads .swarm/close-lessons.md for explicit lessons and runs curation. Use --skill-review to run the quota-bounded skill_improver in proposal mode. Use --dry-run to preview what finalize would archive, clean, and align without taking the lock or changing anything.";
+        readonly details: "Idempotent 4-stage terminal finalization: (1) finalize writes retrospectives for in-progress phases, (2) archive creates timestamped bundle of swarm artifacts and evidence, (3) clean removes active-state files for a clean slate, (4) align performs aggressive git reset --hard to the default remote branch, discarding uncommitted changes and gitignored build artifacts (user-created untracked files are preserved); falls back to a cautious reset that preserves uncommitted changes when the aggressive path cannot proceed. WARNING: alignment discards local changes and gitignored files. Resets agent sessions, delegation chains, and active-agent mappings. Reads .swarm/close-lessons.md for explicit lessons and runs curation. Cleanup: knowledge.jsonl is preserved; plan.json, plan.md, events.jsonl, handoff.*, run-memory.jsonl, and summaries/ are removed. Use --skill-review to run the quota-bounded skill_improver in proposal mode. Use --dry-run to preview what finalize would archive, clean, and align without taking the lock or changing anything.";
         readonly args: "--prune-branches, --skill-review, --dry-run";
         readonly category: "core";
         readonly toolPolicy: "none";
     };
     readonly close: {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Use /swarm close (deprecated alias) to finalize and archive swarm state";
         readonly details: "Deprecated alias for /swarm finalize. Preserved for backward compatibility. Supports the same flags, including --dry-run.";
         readonly args: "--prune-branches, --skill-review, --dry-run";
@@ -686,19 +689,16 @@ export declare const COMMAND_REGISTRY: {
         readonly toolPolicy: "agent";
     };
     readonly 'sdd-status': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Show OpenSpec-compatible SDD status and effective spec source";
         readonly aliasOf: "sdd status";
         readonly deprecated: true;
     };
     readonly 'sdd-validate': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Validate OpenSpec-compatible artifacts and effective spec projection";
         readonly aliasOf: "sdd validate";
         readonly deprecated: true;
     };
     readonly 'sdd-project': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Materialize the OpenSpec-compatible effective spec into .swarm/spec.md";
         readonly aliasOf: "sdd project";
         readonly deprecated: true;
@@ -797,7 +797,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolPolicy: "agent";
     };
     readonly 'pr-subscribe': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Subscribe the current session to PR state-change notifications";
         readonly aliasOf: "pr subscribe";
         readonly deprecated: true;
@@ -811,7 +810,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolPolicy: "agent";
     };
     readonly 'pr-unsubscribe': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Unsubscribe the current session from PR state-change notifications";
         readonly aliasOf: "pr unsubscribe";
         readonly deprecated: true;
@@ -826,7 +824,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolNoArgs: true;
     };
     readonly 'pr-status': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Show PR monitor subscription status for the current session";
         readonly aliasOf: "pr status";
         readonly deprecated: true;
@@ -848,7 +845,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolPolicy: "none";
     };
     readonly 'deep dive': {
-        readonly handler: (ctx: CommandContext) => CommandResult;
         readonly description: "Alias for /swarm deep-dive — launch deep codebase audit";
         readonly args: "<scope> [--profile standard|security|ux|architecture|full] [--max-explorers 1..8] [--json] [--skip-update] [--allow-dirty]";
         readonly category: "agent";
@@ -863,7 +859,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolPolicy: "none";
     };
     readonly 'deep research': {
-        readonly handler: (ctx: CommandContext) => CommandResult;
         readonly description: "Alias for /swarm deep-research — launch a cited deep research pass";
         readonly args: "<question> [--depth standard|exhaustive] [--max-researchers 1..6] [--rounds 1..4] [--brief]";
         readonly category: "agent";
@@ -878,7 +873,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolPolicy: "none";
     };
     readonly 'codebase review': {
-        readonly handler: (ctx: CommandContext) => CommandResult;
         readonly description: "Alias for /swarm codebase-review - launch codebase-review-swarm";
         readonly args: "[scope] [--mode phase0|complete|defect|security|correctness|testing|ui|performance|ai-slop|enhancements|custom] [--tracks <list>] [--continue <run-id>] [--json] [--skip-update] [--allow-dirty]";
         readonly category: "agent";
@@ -893,7 +887,6 @@ export declare const COMMAND_REGISTRY: {
         readonly toolPolicy: "none";
     };
     readonly 'design docs': {
-        readonly handler: (ctx: CommandContext) => CommandResult;
         readonly description: "Alias for /swarm design-docs — generate or sync design docs";
         readonly args: "<description> [--out <dir>] [--lang <name>] [--update]";
         readonly category: "agent";
@@ -949,7 +942,7 @@ export declare const COMMAND_REGISTRY: {
     readonly reset: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Clear swarm state files [--confirm]";
-        readonly details: "DELETES plan.md, context.md, and summaries/ directory from .swarm/. Stops background automation and clears in-memory queues. SAFETY: requires --confirm flag — without it, displays a warning and tips to export first. Before deleting, auto-backs up the state it removes to .swarm/reset-backups/<timestamp>/ (newest 5 kept) so it can be restored by copying the files back.";
+        readonly details: "DELETES plan.md, plan.json, context.md, events.jsonl, run-memory.jsonl, and summaries/ from .swarm/. Stops background automation and clears in-memory queues. SAFETY: requires --confirm flag — without it, displays a warning and tips to export first. Before deleting, auto-backs up the state it removes to .swarm/reset-backups/<timestamp>/ (newest 5 kept) so it can be restored by copying the files back.";
         readonly args: "--confirm (required)";
         readonly category: "utility";
         readonly clashesWithNativeCcCommand: "/reset";
@@ -1212,25 +1205,21 @@ export declare const COMMAND_REGISTRY: {
         readonly toolPolicy: "agent";
     };
     readonly 'memory-status': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Show Swarm memory provider, JSONL, and migration status";
         readonly aliasOf: "memory status";
         readonly deprecated: true;
     };
     readonly 'memory-export': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Export current Swarm memory to JSONL files";
         readonly aliasOf: "memory export";
         readonly deprecated: true;
     };
     readonly 'memory-import': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Import legacy JSONL memory into SQLite";
         readonly aliasOf: "memory import";
         readonly deprecated: true;
     };
     readonly 'memory-migrate': {
-        readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Run the one-time legacy JSONL to SQLite migration";
         readonly aliasOf: "memory migrate";
         readonly deprecated: true;
@@ -1293,7 +1282,9 @@ export declare const _internals: {
  * Returns a warning if the resolved command is a deprecated alias.
  */
 export declare function resolveCommand(tokens: string[]): {
-    entry: CommandEntry;
+    entry: CommandEntry & {
+        handler: (ctx: CommandContext) => CommandResult;
+    };
     remainingArgs: string[];
     key: string;
     warning?: string;

package/dist/commands/turbo.d.ts

@@ -14,7 +14,7 @@ export declare const _internals: {
  * Supports standard turbo toggle, lean turbo mode, and status reporting.
  *
  * @param directory - Project directory (used to persist Lean Turbo run state)
- * @param args - Optional arguments: "lean" | "standard" | "on" | "off" | "status" | undefined
+ * @param args - Arguments: (none) | "on" | "off" | "status" | "lean" ["on"|"off"] | "standard" ["on"|"off"] | "epic" ["on"|"off"]. Unknown arguments are rejected without changing state.
  * @param sessionID - Session ID for accessing active session state
  * @returns Feedback message about Turbo Mode state
  */

package/dist/config/bundled-skills.d.ts

@@ -1,14 +1,15 @@
-export declare const BUNDLED_PROJECT_SKILLS: readonly ["brainstorm", "specify", "clarify-spec", "swarm-resume", "clarify", "discover", "consult", "pre-phase-briefing", "council", "deep-dive", "deep-research", "codebase-review-swarm", "swarm-implement", "design-docs", "swarm-pr-review", "swarm", "swarm-pr-feedback", "swarm-pr-subscribe", "swarm-ci-monitor", "issue-ingest", "plan", "critic-gate", "execute", "phase-wrap", "loop", "writing-tests", "running-tests", "engineering-conventions", "commit-pr", "ci-failure-batching", "gate-attribution", "merge-queue-readiness", "skill-edit-validation", "worktree-retry-cleanup", "test-file-split", "fork-pr-operations", "parallel-work-check", "ci-fix-monitor", "issue-tracer", "orchestrating-subagents", "durable-session-state"];
+export declare const BUNDLED_PROJECT_SKILLS: readonly ["brainstorm", "specify", "clarify-spec", "swarm-resume", "clarify", "discover", "consult", "pre-phase-briefing", "council", "deep-dive", "deep-research", "codebase-review-swarm", "swarm-implement", "design-docs", "swarm-pr-review", "swarm", "swarm-pr-feedback", "swarm-pr-subscribe", "swarm-ci-monitor", "issue-ingest", "swarm-plan", "critic-gate", "execute", "phase-wrap", "loop", "writing-tests", "running-tests", "engineering-conventions", "commit-pr", "ci-failure-batching", "gate-attribution", "merge-queue-readiness", "skill-edit-validation", "worktree-retry-cleanup", "test-file-split", "fork-pr-operations", "parallel-work-check", "ci-fix-monitor", "issue-tracer", "orchestrating-subagents", "durable-session-state"];
 export type BundledProjectSkill = (typeof BUNDLED_PROJECT_SKILLS)[number];
 /**
  * Bundled skill slugs that were retired (renamed away) in shipped releases.
  * The sync removes their materialized directories from
  * `.swarm/bundled-skills/` in existing user projects so a rename never leaves
- * a stale protocol copy behind (issue #2379: `resume` → `swarm-resume`).
+ * a stale protocol copy behind (issue #2379: `resume` → `swarm-resume`;
+ * issue #2388 via #2493: `plan` → `swarm-plan`).
  * A slug must never appear both here and in BUNDLED_PROJECT_SKILLS (asserted
  * by tests/unit/skills/claude-slug-collision-guard.test.ts).
  */
-export declare const RETIRED_BUNDLED_PROJECT_SKILLS: readonly ["resume"];
+export declare const RETIRED_BUNDLED_PROJECT_SKILLS: readonly ["resume", "plan"];
 /**
  * Project-private runtime location for plugin-owned skills. Repository-native
  * skill roots (`.opencode/skills`, `.claude/skills`, and `.agents/skills`) are

package/dist/config/constants.d.ts

@@ -5,6 +5,19 @@ export type { AgentName, PipelineAgentName, QAAgentName } from './agent-names';
 export { ALL_AGENT_NAMES, ALL_SUBAGENT_NAMES, ORCHESTRATOR_NAME, PIPELINE_AGENTS, QA_AGENTS, } from './agent-names';
 export declare const OPENCODE_NATIVE_AGENTS: Set<"plan" | "summary" | "compaction" | "title" | "build" | "general" | "explore">;
 export declare const CLAUDE_CODE_NATIVE_COMMANDS: ReadonlySet<string>;
+/**
+ * OpenCode built-in slash commands (without leading slash). Used by
+ * tests/unit/skills/claude-slug-collision-guard.test.ts to assert that no
+ * repo-shipped native skill slug in `.opencode/skills/` or `.claude/skills/`
+ * shadows one of OpenCode's own `/<slug>` commands (the host exposes every
+ * native skill directory as a slash command, so e.g. a `plan` skill dir would
+ * shadow OpenCode's built-in `/plan` plan mode — issue #2388/#2493).
+ *
+ * Hand-curated mirror of OpenCode's built-in slash commands — must be
+ * reviewed when bumping @opencode-ai/* dependencies (no programmatic oracle
+ * exists; issue #2493).
+ */
+export declare const OPENCODE_NATIVE_COMMANDS: ReadonlySet<string>;
 export declare const MEMORY_TOOL_NAMES: readonly ["swarm_memory_recall", "swarm_memory_propose", "swarm_memory_outcome"];
 export declare const MEMORY_AGENT_TOOL_MAP: Partial<Record<AgentName, ToolName[]>>;
 export declare const EXTERNAL_SKILL_TOOL_NAMES: readonly ["external_skill_discover", "external_skill_list", "external_skill_inspect", "external_skill_promote", "external_skill_reject", "external_skill_delete", "external_skill_revoke"];

package/dist/hooks/extractors.d.ts

@@ -15,6 +15,15 @@ export declare function extractCurrentPhase(planContent: string): string | null;
 export declare function extractCurrentTask(planContent: string): string | null;
 /**
  * Extracts decisions section from context content.
+ *
+ * #2493 W9a: derives from the shared section extractor
+ * (`src/utils/context-decisions.ts`) instead of a private line-scan.
+ * Mapping preserves this consumer's historical output exactly:
+ * - Only NON-indented `- ` lines are kept (the old scan matched raw
+ *   `line.startsWith('- ')`; the shared extractor is indent-tolerant, so
+ *   indented sub-bullets are filtered out here).
+ * - Lines are reproduced verbatim from `raw` — bullet prefix, markers
+ *   (✅ / [timestamps]) and all — then joined, trimmed and truncated.
  */
 export declare function extractDecisions(contextContent: string, maxChars?: number): string | null;
 /**

package/dist/hooks/non-architect-advisory.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Issue #2493 (K3 UX-3): one-time first-run advisory when a session runs on a
+ * non-architect agent. The OpenCode plugin v1 shape has no session-start hook,
+ * so "session starts on a non-architect agent" is operationalized as the first
+ * user message observed on a non-architect agent (the chat.message hook calls
+ * this on every message; the one-shot flag makes it fire once per sessionID).
+ *
+ * Invariant 8: the guard lives on AgentSessionState (session-keyed, bounded by
+ * the existing session-state eviction) — no new module-level session map.
+ */
+export declare const NON_ARCHITECT_ADVISORY_KEY = "[non-architect-advisory]";
+/**
+ * Emit the one-time non-architect advisory for `sessionID` when `agentName`
+ * identifies a user-facing, non-architect agent. Returns true when the
+ * advisory was enqueued this call. Fail-open by contract: callers wrap in
+ * try/catch so an advisory failure can never block message processing.
+ */
+export declare function maybeEmitNonArchitectAdvisory(sessionID: string, agentName: string): boolean;

package/dist/hooks/repo-graph-injection.d.ts

@@ -25,9 +25,23 @@
  * touches SQLite. Whole-graph consumers (`buildLaneOrientationBlock`,
  * `semantic-diff-injection`) always get the full JSON graph.
  */
+import * as fs from 'node:fs';
 import { loadPluginConfigWithMetaAsync } from '../config/loader';
 import { type FreshnessOptions, probeFreshness, type RepoGraph } from '../tools/repo-graph';
 import { loadSubgraphForFiles } from '../tools/repo-graph/indexed-storage';
+interface CachedGraph {
+    graph: RepoGraph;
+    mtimeMs: number;
+    size: number;
+    /**
+     * File identity from `st.ino`. The indexed freshness stamp relies on it
+     * because same-size/same-mtime-tick rewrites are common, and these caches
+     * shadow that stamp (a hit short-circuits before the index is consulted).
+     * On filesystems reporting no usable id it is 0 on both sides, so the
+     * comparator degrades to mtime+size exactly as before.
+     */
+    ino: number;
+}
 export interface RepoGraphInjectionOptions extends FreshnessOptions {
     enabled?: boolean;
     refreshCap?: number;
@@ -49,7 +63,9 @@ export declare const _internals: {
     loadPluginConfigWithMetaAsync: typeof loadPluginConfigWithMetaAsync;
     loadSubgraphForFiles: typeof loadSubgraphForFiles;
     subgraphCacheKey: typeof subgraphCacheKey;
+    fullGraphCacheMatches: typeof fullGraphCacheMatches;
 };
+declare function fullGraphCacheMatches(cached: Pick<CachedGraph, 'mtimeMs' | 'size' | 'ino'>, stat: Pick<fs.Stats, 'mtimeMs' | 'size' | 'ino'>): boolean;
 /**
  * Cache key for a subgraph request. The graph artifact's `{mtimeMs, size, ino}`
  * is part of the key, so a graph change invalidates every cached subgraph for