@kisev/skills-opencode 1.1.1 → 1.2.0

package/README.md

@@ -91,10 +91,14 @@ npm exec -- skills-opencode agent model-set worker --scope global \
 npm exec -- skills-opencode agent reconcile --scope global --dry-run
 ```
 
-`agent configure` предлагает terminal selection в порядке provider, model,
-variant по cached output `opencode models`; refresh не выполняется. Если catalog
-недоступен, передайте exact `--provider <provider> --model <model>` или
-`--model <provider/model>`.
+`agent configure` предлагает настоящий terminal wizard: стрелками выбираются
+agent из inventory, затем provider, только его models и, если metadata выбранной
+модели публикует variants, variant. Текущие model/variant и target показываются
+перед выбором; доступны `keep`, `change`, `clear variant`, `back` и `cancel`.
+Wizard не вызывает LLM, OpenCode Question или refresh catalog. Если catalog
+недоступен, он завершается без записи и печатает инструкцию для exact
+`--model <provider/model>` с optional `--variant`. Для модели без variants
+дополнительный selector не показывается.
 
 Additional critic имеет имя `critic-<safe-suffix>`. Стандартный `critic` и fixed
 roles нельзя удалить или переименовать:

package/dist/agent-profiles.js

@@ -719,10 +719,12 @@ export async function availableModelVariants(model) {
                 document += `${lines[index]}\n`;
                 try {
                     const metadata = JSON.parse(document);
+                    if (metadata.variants === undefined)
+                        return [];
                     if (!metadata.variants ||
                         typeof metadata.variants !== "object" ||
                         Array.isArray(metadata.variants))
-                        throw new Error("variants missing");
+                        throw new Error("invalid variants metadata");
                     const variants = Object.keys(metadata.variants);
                     if (!variants.every((variant) => VARIANT_PATTERN.test(variant)))
                         throw new Error("unsafe variant");

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { createInterface } from "node:readline/promises";
 import { AgentProfileError, applyAgentProfileChange, availableModels, availableModelVariants, FIXED_AGENT_ROLES, listAgentProfiles, previewAgentProfileChange, validateAgentName, validateModel, validateVariant, } from "./agent-profiles.js";
 import { renderInventory, renderPlan, shellCommand, terminalSafe } from "./cli-output.js";
 import { apply, InstallerError, preview } from "./installer.js";
 import { LifecycleError } from "./lifecycle.js";
+import { promptText, selectOption } from "./terminal-wizard.js";
 function parseOptions(values) {
     const options = { dryRun: false, json: false };
     for (let index = 0; index < values.length; index += 1) {
@@ -83,56 +83,123 @@ function exactModel(options) {
         throw new InstallerError("invalid_input", "--provider is required when --model is not provider/model");
     return validateModel(`${options.provider}/${options.model}`);
 }
-async function choose(label, values, input) {
-    process.stderr.write(`${label}:\n${values.map((value, index) => `  ${index + 1}. ${value}`).join("\n")}\n`);
-    const answer = await input.question("> ");
-    const index = Number(answer) - 1;
-    if (!Number.isSafeInteger(index) || !values[index])
-        throw new InstallerError("invalid_input", `Invalid ${label.toLowerCase()} selection`);
-    return values[index];
-}
-async function interactiveSelection(options) {
-    if (!process.stdin.isTTY || !process.stderr.isTTY)
+async function interactiveSelection(options, action = "model-set") {
+    if (!process.stdin.isTTY || !process.stderr.isTTY) {
         throw new InstallerError("terminal_required", "agent configure requires a terminal or explicit --provider and --model");
-    const input = createInterface({ input: process.stdin, output: process.stderr });
-    try {
-        const inventory = await listAgentProfiles(options.scope);
-        const configurable = inventory.profiles.filter((item) => item.ownership !== "user-owned").map((item) => item.name);
-        const name = options.name ? validateAgentName(options.name) : await choose("Agent", configurable.length ? configurable : FIXED_AGENT_ROLES, input);
-        if (options.provider && options.model)
-            return { name, model: exactModel(options), ...(validateVariant(options.variant) ? { variant: validateVariant(options.variant) } : {}) };
-        let models;
-        try {
-            models = await availableModels();
+    }
+    const inventory = await listAgentProfiles(options.scope);
+    const configurable = inventory.profiles.filter((item) => item.ownership !== "user-owned");
+    let name;
+    if (options.name) {
+        name = action === "critic-add" && !options.name.startsWith("critic-")
+            ? validateAgentName(`critic-${options.name}`)
+            : validateAgentName(options.name);
+    }
+    else if (action === "critic-add") {
+        const raw = await promptText("Critic name (critic-<suffix>):");
+        if (raw === null)
+            throw new InstallerError("cancelled", "Wizard cancelled");
+        name = raw.startsWith("critic-") ? raw : `critic-${raw}`;
+        validateAgentName(name);
+    }
+    else {
+        const agentNames = configurable.map((item) => item.name);
+        if (agentNames.length === 0)
+            agentNames.push(...FIXED_AGENT_ROLES);
+        const index = await selectOption("Select agent:", agentNames);
+        if (index === null)
+            throw new InstallerError("cancelled", "Wizard cancelled");
+        name = agentNames[index];
+    }
+    const currentProfile = configurable.find((item) => item.name === name);
+    const currentModel = currentProfile?.model;
+    const currentVariant = currentProfile?.variant;
+    const showTarget = (model, variant) => {
+        process.stderr.write(`Target: ${model}${variant ? ` / ${variant}` : ""}\n`);
+    };
+    if (options.provider && options.model) {
+        const model = exactModel(options);
+        const variant = validateVariant(options.variant);
+        return { name, model, ...(variant ? { variant } : {}) };
+    }
+    while (true) {
+        const actions = [];
+        if (currentModel) {
+            actions.push(`Keep current (${currentModel}${currentVariant ? ` / ${currentVariant}` : ""})`);
         }
-        catch (error) {
-            if (!(error instanceof AgentProfileError) || error.code !== "catalog_unavailable")
+        actions.push("Change model");
+        if (currentVariant)
+            actions.push("Clear variant");
+        if (!options.name && action === "model-set")
+            actions.push("Back");
+        actions.push("Cancel");
+        const currentLabel = `Agent: ${name}${currentModel ? ` (current: ${currentModel}${currentVariant ? ` / ${currentVariant}` : ""})` : ""}`;
+        const actionIndex = await selectOption(currentLabel, actions);
+        if (actionIndex === null)
+            throw new InstallerError("cancelled", "Wizard cancelled");
+        const chosen = actions[actionIndex];
+        if (chosen.startsWith("Keep current")) {
+            if (!currentModel)
+                throw new InstallerError("invalid_state", "No current model to keep");
+            showTarget(currentModel, currentVariant);
+            return { name, model: currentModel, ...(currentVariant ? { variant: currentVariant } : {}) };
+        }
+        if (chosen === "Change model") {
+            let models;
+            try {
+                models = await availableModels();
+            }
+            catch (error) {
+                if (error instanceof AgentProfileError && error.code === "catalog_unavailable") {
+                    process.stderr.write("\nModel catalog is unavailable.\nUse direct CLI with exact --model provider/model and optional --variant.\n\n");
+                    throw new InstallerError("catalog_unavailable", "Use direct CLI with exact --model provider/model");
+                }
+                throw error;
+            }
+            const providers = [...new Set(models.map((m) => m.split("/", 1)[0]))].sort();
+            const providerIndex = await selectOption("Select provider:", providers);
+            if (providerIndex === null)
+                continue;
+            const provider = providers[providerIndex];
+            const filteredModels = models.filter((m) => m.startsWith(`${provider}/`));
+            const modelIndex = await selectOption("Select model:", filteredModels);
+            if (modelIndex === null)
+                continue;
+            const selectedModel = filteredModels[modelIndex];
+            let selectedVariant;
+            try {
+                const variants = await availableModelVariants(selectedModel);
+                if (variants.length) {
+                    const variantOptions = ["(none)", ...variants];
+                    const variantIndex = await selectOption("Select variant:", variantOptions);
+                    if (variantIndex === null)
+                        continue;
+                    if (variantIndex > 0)
+                        selectedVariant = variantOptions[variantIndex];
+                }
+            }
+            catch (error) {
+                if (error instanceof AgentProfileError && error.code === "catalog_unavailable") {
+                    process.stderr.write("\nModel variant metadata is unavailable.\nUse direct CLI with exact --model provider/model and optional --variant.\n\n");
+                    throw new InstallerError("catalog_unavailable", "Use direct CLI with exact --model provider/model");
+                }
                 throw error;
-            const provider = options.provider ?? (await input.question("Provider: ")).trim();
-            const model = options.model ?? (await input.question("Model: ")).trim();
-            const variant = options.variant === undefined ? (await input.question("Variant (optional): ")).trim() : options.variant;
-            return { name, model: validateModel(model.includes("/") ? model : `${provider}/${model}`), ...(validateVariant(variant) ? { variant: validateVariant(variant) } : {}) };
+            }
+            showTarget(selectedModel, selectedVariant);
+            return { name, model: selectedModel, ...(selectedVariant ? { variant: selectedVariant } : {}) };
         }
-        const providers = [...new Set(models.map((model) => model.split("/", 1)[0]))].sort();
-        const provider = options.provider ?? (await choose("Provider", providers, input));
-        const selectedModel = options.model
-            ? exactModel({ ...options, provider })
-            : await choose("Model", models.filter((model) => model.startsWith(`${provider}/`)), input);
-        let variants = [];
-        try {
-            variants = await availableModelVariants(selectedModel);
+        if (chosen === "Clear variant") {
+            if (!currentModel)
+                throw new InstallerError("invalid_state", "No model to clear variant for");
+            showTarget(currentModel);
+            return { name, model: currentModel };
         }
-        catch (error) {
-            if (!(error instanceof AgentProfileError) || error.code !== "catalog_unavailable")
-                throw error;
+        if (chosen === "Back") {
+            return interactiveSelection({ ...options, name: undefined }, action);
+        }
+        if (chosen === "Cancel") {
+            throw new InstallerError("cancelled", "Wizard cancelled");
         }
-        const variant = options.variant === null
-            ? undefined
-            : options.variant ?? (variants.length ? await choose("Variant", ["none", ...variants.filter((value) => value !== "none")], input) : (await input.question("Variant (optional): ")).trim());
-        return { name, model: selectedModel, ...(variant && variant !== "none" ? { variant: validateVariant(variant) } : {}) };
-    }
-    finally {
-        input.close();
     }
 }
 async function runProfile(request, options) {
@@ -210,7 +277,7 @@ async function run(arguments_) {
         requireConfirmationMode(options);
         const selected = options.provider && options.model && options.name
             ? { name: validateAgentName(options.name), model: exactModel(options), ...(validateVariant(options.variant) ? { variant: validateVariant(options.variant) } : {}) }
-            : await interactiveSelection(options);
+            : await interactiveSelection(options, "model-set");
         await runProfile({ action: "model-set", ...selected, variant: selected.variant ?? null }, options);
         return;
     }
@@ -237,9 +304,13 @@ async function run(arguments_) {
             : `critic-${options.name ?? ""}`;
         if (operation === "add") {
             const model = exactModel(options);
-            if (!model)
-                throw new InstallerError("invalid_input", "critic add requires --provider and --model, or exact --model provider/model");
-            await runProfile({ action: "critic-add", name, model, variant: options.variant ?? null }, options);
+            if (!model) {
+                const selected = await interactiveSelection(options, "critic-add");
+                await runProfile({ action: "critic-add", name: selected.name, model: selected.model, variant: selected.variant ?? null }, options);
+            }
+            else {
+                await runProfile({ action: "critic-add", name, model, variant: options.variant ?? null }, options);
+            }
         }
         else {
             if (options.provider || options.model || options.variant !== undefined)

package/dist/index.d.ts

@@ -7,7 +7,8 @@ import rtk, { type RtkOptions } from "./plugins/rtk.js";
 import zedBell, { type ZedBellOptions } from "./plugins/zed-bell.js";
 import zedClickablePaths, { type ZedClickablePathsOptions } from "./plugins/zed-clickable-paths.js";
 export { COMMAND_REGISTRY, renderCommand } from "./registry.js";
-export { CATEGORIES, resolveRouting, RoutingGate } from "./routing.js";
+export { CATEGORIES, resolveRouting, RoutingGate, ExecutionCardLifecycle, validateExecutionCard } from "./routing.js";
+export type { ExecutionCard, ExecutionCardStatus } from "./routing.js";
 export { AgentProfileError, FIXED_AGENT_ROLES, applyAgentProfileChange, availableModels, availableModelVariants, listAgentProfiles, previewAgentProfileChange, renderAgentProfile, validateAgentName, validateModel, validateVariant, } from "./agent-profiles.js";
 export type { AgentInventory, AgentModelSelection, AgentOwnership, AgentProfileAction, AgentProfileConfig, AgentProfileOperation, AgentProfilePlan, AgentProfileRecord, AgentProfileRequest, AgentProfileResult, AgentProfileScope, AgentState, DeploymentManifest, DeploymentRecord, FixedAgentRole, } from "./agent-profiles.js";
 export { backgroundAttempts, goalLoop, scheduler, autonomyPolicy, rulesInjector, rtk, zedBell, zedClickablePaths };
@@ -48,6 +49,7 @@ declare const plugin: (input: {
                     capabilities: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
                     tools: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
                 }, import("zod/v4/core").$strip>>;
+                execution_card: import("zod").ZodOptional<import("zod").ZodAny>;
                 override: import("zod").ZodOptional<import("zod").ZodString>;
                 budget: import("zod").ZodOptional<import("zod").ZodObject<{
                     cost_class: import("zod").ZodOptional<import("zod").ZodString>;
@@ -66,6 +68,7 @@ declare const plugin: (input: {
                     capabilities?: string[] | undefined;
                     tools?: string[] | undefined;
                 }[];
+                execution_card?: any;
                 override?: string | undefined;
                 budget?: {
                     cost_class?: string | undefined;
@@ -151,6 +154,7 @@ export declare const server: (input: {
                     capabilities: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
                     tools: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
                 }, import("zod/v4/core").$strip>>;
+                execution_card: import("zod").ZodOptional<import("zod").ZodAny>;
                 override: import("zod").ZodOptional<import("zod").ZodString>;
                 budget: import("zod").ZodOptional<import("zod").ZodObject<{
                     cost_class: import("zod").ZodOptional<import("zod").ZodString>;
@@ -169,6 +173,7 @@ export declare const server: (input: {
                     capabilities?: string[] | undefined;
                     tools?: string[] | undefined;
                 }[];
+                execution_card?: any;
                 override?: string | undefined;
                 budget?: {
                     cost_class?: string | undefined;

package/dist/index.js

@@ -10,7 +10,7 @@ import zedBell from "./plugins/zed-bell.js";
 import zedClickablePaths from "./plugins/zed-clickable-paths.js";
 import { applyAgentProfileChange, listAgentProfiles, previewAgentProfileChange, } from "./agent-profiles.js";
 export { COMMAND_REGISTRY, renderCommand } from "./registry.js";
-export { CATEGORIES, resolveRouting, RoutingGate } from "./routing.js";
+export { CATEGORIES, resolveRouting, RoutingGate, ExecutionCardLifecycle, validateExecutionCard } from "./routing.js";
 export { AgentProfileError, FIXED_AGENT_ROLES, applyAgentProfileChange, availableModels, availableModelVariants, listAgentProfiles, previewAgentProfileChange, renderAgentProfile, validateAgentName, validateModel, validateVariant, } from "./agent-profiles.js";
 export { backgroundAttempts, goalLoop, scheduler, autonomyPolicy, rulesInjector, rtk, zedBell, zedClickablePaths };
 const CATALOG = {
@@ -29,16 +29,17 @@ const plugin = (async (input) => {
             task: tool.schema.string(),
             requirements: tool.schema.array(tool.schema.string()).default([]),
             agents: tool.schema.array(tool.schema.object({ agent: tool.schema.string(), available: tool.schema.boolean().optional(), capabilities: tool.schema.array(tool.schema.string()).optional(), tools: tool.schema.array(tool.schema.string()).optional() })),
+            execution_card: tool.schema.any().optional(),
             override: tool.schema.string().optional(),
             budget: tool.schema.object({ cost_class: tool.schema.string().optional(), latency_class: tool.schema.string().optional() }).optional(),
             decision: tool.schema.any().optional()
         },
         async execute(args, context) {
-            const input = { category: args.category, requirements: args.requirements, agents: args.agents, override: args.override, budget: args.budget };
+            const input = { category: args.category, task: args.task, requirements: args.requirements, agents: args.agents, execution_card: args.execution_card, override: args.override, budget: args.budget };
             if (args.action === "preview")
                 return JSON.stringify(gate.preview(input));
             const decision = gate.dispatch(input, args.decision);
-            gate.grant(context.sessionID, decision);
+            gate.grant(context.sessionID, decision, { task: args.task, requirements: args.requirements, card: args.execution_card });
             return JSON.stringify({ decision, status: "routed" });
         }
     });
@@ -92,7 +93,14 @@ const plugin = (async (input) => {
             const agent = typeof args.agent === "string" ? args.agent : typeof args.subagent_type === "string" ? args.subagent_type : undefined;
             if (!agent)
                 throw new Error("Native Task requires an explicit agent and an active routing receipt");
-            gate.consume(input.sessionID, agent);
+            const hasBinding = "task" in args || "requirements" in args || "execution_card" in args;
+            if (!hasBinding)
+                gate.consume(input.sessionID, agent);
+            else {
+                const task = typeof args.task === "string" ? args.task : "";
+                const requirements = Array.isArray(args.requirements) ? args.requirements : [];
+                gate.consume(input.sessionID, agent, { task, requirements, card: args.execution_card });
+            }
         }
     };
 });

package/dist/plugins/background-attempts.js

@@ -22,12 +22,23 @@ export async function backgroundAttempts({ client, directory, cwd }, options = {
         await appendState(join(root, "receipts.jsonl"), root, { attempt_id: item.attempt_id, event, status: item.status, revision: item.revision, at: new Date().toISOString() });
     };
     const transition = async (item, status, event) => {
-        if (!TERMINAL.has(item.status)) {
-            item.status = status;
-            item.revision += 1;
-        }
+        const allowed = {
+            queued: ["running", "failed", "cancelled"],
+            running: ["waiting", "completed", "failed", "cancelled", "orphaned"],
+            waiting: ["running", "completed", "failed", "cancelled", "orphaned"],
+            completed: [], failed: [], cancelled: [], orphaned: [],
+        };
+        if (!allowed[item.status].includes(status))
+            throw new Error(`Invalid background-attempt transition: ${item.status} -> ${status}`);
+        item.status = status;
+        item.revision += 1;
         await save(item, event);
     };
+    for (const item of await all()) {
+        if (item.project === project && (item.status === "running" || item.status === "waiting")) {
+            await transition(item, "orphaned", "recovery.orphaned");
+        }
+    }
     const pump = async () => {
         const records = await all();
         const running = records.filter((item) => item.status === "running" || item.status === "waiting");

package/dist/plugins/goal-loop.d.ts

@@ -1,3 +1,9 @@
+type WorkItem = {
+    contract_version: "work-item/v1";
+    acceptance_criteria: Array<{
+        id: string;
+    }>;
+};
 type Goal = {
     schema_version: 1;
     goal_id: string;
@@ -14,6 +20,11 @@ type Goal = {
     };
     receipts: Array<Record<string, unknown>>;
     updated_at: string;
+    work_item?: WorkItem;
+    completion_evidence?: Array<{
+        criterion_id: string;
+        evidence: string;
+    }>;
 };
 type Client = {
     session: {

package/dist/plugins/goal-loop.js

@@ -12,6 +12,14 @@ function tokens(messages) {
     const value = last?.info?.tokens?.total ?? last?.info?.tokens?.output;
     return typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0;
 }
+function validWorkItem(goal) {
+    return goal.work_item?.contract_version === "work-item/v1" && Array.isArray(goal.work_item.acceptance_criteria) && goal.work_item.acceptance_criteria.length > 0;
+}
+function hasCompletionEvidence(goal) {
+    const criteria = goal.work_item?.acceptance_criteria ?? [];
+    const evidence = goal.completion_evidence ?? [];
+    return criteria.every((criterion) => evidence.some((item) => item.criterion_id === criterion.id && item.evidence.trim().length > 0));
+}
 export async function goalLoop({ client }, options = {}) {
     if (!options.enabled)
         return {};
@@ -29,6 +37,8 @@ export async function goalLoop({ client }, options = {}) {
         const item = await lookup(session);
         if (!item || item.state.status !== "running")
             return;
+        if (!validWorkItem(item.state))
+            return settle(session, "blocked", "invalid work item");
         item.state.status = status;
         item.state.revision += 1;
         item.state.updated_at = new Date().toISOString();
@@ -53,6 +63,8 @@ export async function goalLoop({ client }, options = {}) {
             if (item.state.limits.token_budget > 0 && item.state.usage.tokens >= item.state.limits.token_budget)
                 return settle(session, "blocked", "token budget reached");
             const verdict = await (options.audit?.(item.state) ?? Promise.resolve("continue"));
+            if (verdict === "complete" && !hasCompletionEvidence(item.state))
+                return settle(session, "blocked", "completion evidence is incomplete");
             if (verdict === "complete" || verdict === "blocked")
                 return settle(session, verdict, "audit verdict");
             await client.session.prompt({ path: { id: session }, body: { parts: [{ type: "text", text: "Continue the current goal within its declared constraints and boundaries." }] } });

package/dist/routing.d.ts

@@ -8,8 +8,10 @@ export type AvailableAgent = {
 };
 export type RoutingInput = {
     category: Category;
+    task?: string;
     requirements: string[];
     agents: AvailableAgent[];
+    execution_card?: unknown;
     override?: string;
     budget?: {
         cost_class?: string;
@@ -27,13 +29,68 @@ export type RoutingDecision = {
         excluded_reasons: string[];
     }[];
     matrix_revision: string;
+    task_digest: string;
+    requirements_digest: string;
+    execution_card_digest?: string;
+    execution_card_revision?: number;
     decision_digest: string;
 };
+export type ControlMarker = {
+    path: string;
+    expected?: string;
+    expected_absent?: boolean;
+};
+export type ExecutionCard = {
+    status: "READY";
+    card_id: string;
+    revision: number;
+    objective: string;
+    changed_behavior: string[];
+    risks: string[];
+    write_set: string[];
+    control_markers: ControlMarker[];
+    decisions: string[];
+    steps: Array<{
+        path: string;
+        operation: string;
+    }>;
+    acceptance_criteria: string[];
+    checks: string[];
+    boundaries: {
+        forbidden_paths: string[];
+    };
+};
+export type ExecutionCardStatus = ExecutionCard["status"] | "RUNNING" | "COMPLETED" | "BLOCKED" | "FAILED" | "REJECTED_PLAN" | "APPROVED" | "CHANGES_REQUIRED" | "CANCELLED";
 export declare function resolveRouting(input: RoutingInput): RoutingDecision;
+export declare function validateExecutionCard(card: unknown): {
+    valid: true;
+    card: ExecutionCard;
+} | {
+    valid: false;
+    failedField: string;
+};
+type ReceiptContext = {
+    task?: string;
+    requirements?: string[];
+    card?: unknown;
+};
+export declare class ExecutionCardLifecycle {
+    #private;
+    constructor(card: unknown);
+    get status(): ExecutionCardStatus;
+    get card_id(): string;
+    get revision(): number;
+    transition(status: ExecutionCardStatus, identity: {
+        card_id: string;
+        revision: number;
+    }): ExecutionCardStatus;
+}
 export declare class RoutingGate {
     #private;
     preview(input: RoutingInput): RoutingDecision;
     dispatch(input: RoutingInput, provided: unknown): RoutingDecision;
-    grant(sessionID: string, decision: RoutingDecision): void;
-    consume(sessionID: string, agent: string): void;
+    grant(sessionID: string, decision: RoutingDecision, context?: ReceiptContext): void;
+    cancel(sessionID: string): void;
+    consume(sessionID: string, agent: string, context?: ReceiptContext): void;
 }
+export {};

package/dist/routing.js

@@ -58,33 +58,173 @@ export function resolveRouting(input) {
             eligible.push(agent);
     }
     const selected = input.override ? eligible.find((agent) => agent.agent === input.override) : eligible[0];
+    const card = input.execution_card === undefined ? undefined : validateExecutionCard(input.execution_card);
+    if (card && !card.valid)
+        throw new Error(`Invalid execution card: ${card.failedField}`);
     const base = selected
-        ? { schema_version: 1, status: "selected", category: input.category, agent: selected.agent, reason_codes: [input.override ? "explicit_override" : selected.agent === category.profiles[0] ? "primary_available" : "fallback_selected", "capabilities_match"], alternatives, matrix_revision: revision }
-        : { schema_version: 1, status: "escalate", category: input.category, reason_codes: [input.override ? "override_unavailable" : "no_eligible_profile"], alternatives, matrix_revision: revision };
+        ? { schema_version: 1, status: "selected", category: input.category, agent: selected.agent, reason_codes: [input.override ? "explicit_override" : selected.agent === category.profiles[0] ? "primary_available" : "fallback_selected", "capabilities_match"], alternatives, matrix_revision: revision, task_digest: digest(input.task ?? ""), requirements_digest: digest(input.requirements), ...(card?.valid ? { execution_card_digest: digest(card.card), execution_card_revision: card.card.revision } : {}) }
+        : { schema_version: 1, status: "escalate", category: input.category, reason_codes: [input.override ? "override_unavailable" : "no_eligible_profile"], alternatives, matrix_revision: revision, task_digest: digest(input.task ?? ""), requirements_digest: digest(input.requirements), ...(card?.valid ? { execution_card_digest: digest(card.card), execution_card_revision: card.card.revision } : {}) };
     return { ...base, decision_digest: digest(base) };
 }
+function isNonEmptyStringArray(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string" && item.length > 0);
+}
+export function validateExecutionCard(card) {
+    if (!card || typeof card !== "object" || Array.isArray(card)) {
+        return { valid: false, failedField: "root" };
+    }
+    const c = card;
+    const expectedFields = [
+        "status", "card_id", "revision", "objective", "changed_behavior", "risks",
+        "write_set", "control_markers", "decisions", "steps", "acceptance_criteria",
+        "checks", "boundaries",
+    ];
+    if (Object.keys(c).sort().join(",") !== expectedFields.slice().sort().join(","))
+        return { valid: false, failedField: "schema" };
+    if (c.status !== "READY")
+        return { valid: false, failedField: "status" };
+    if (typeof c.card_id !== "string" || !c.card_id)
+        return { valid: false, failedField: "card_id" };
+    if (typeof c.revision !== "number" || !Number.isInteger(c.revision) || c.revision < 1)
+        return { valid: false, failedField: "revision" };
+    if (typeof c.objective !== "string" || !c.objective)
+        return { valid: false, failedField: "objective" };
+    if (!isNonEmptyStringArray(c.changed_behavior))
+        return { valid: false, failedField: "changed_behavior" };
+    if (!isNonEmptyStringArray(c.risks))
+        return { valid: false, failedField: "risks" };
+    if (!isNonEmptyStringArray(c.write_set))
+        return { valid: false, failedField: "write_set" };
+    if (new Set(c.write_set).size !== c.write_set.length)
+        return { valid: false, failedField: "write_set" };
+    if (!Array.isArray(c.control_markers) || c.control_markers.length === 0)
+        return { valid: false, failedField: "control_markers" };
+    for (const marker of c.control_markers) {
+        if (!marker || typeof marker !== "object" || Array.isArray(marker))
+            return { valid: false, failedField: "control_markers" };
+        const m = marker;
+        if (typeof m.path !== "string" || !m.path)
+            return { valid: false, failedField: "control_markers" };
+        const hasExpected = typeof m.expected === "string" && m.expected.length > 0;
+        const hasExpectedAbsent = m.expected_absent === true;
+        if (hasExpected === hasExpectedAbsent)
+            return { valid: false, failedField: "control_markers" };
+        if (Object.keys(m).some((k) => k !== "path" && k !== "expected" && k !== "expected_absent"))
+            return { valid: false, failedField: "control_markers" };
+    }
+    if (!isNonEmptyStringArray(c.decisions))
+        return { valid: false, failedField: "decisions" };
+    if (!Array.isArray(c.steps) || c.steps.length === 0)
+        return { valid: false, failedField: "steps" };
+    for (const step of c.steps) {
+        if (!step || typeof step !== "object" || Array.isArray(step))
+            return { valid: false, failedField: "steps" };
+        const s = step;
+        if (typeof s.path !== "string" || !s.path)
+            return { valid: false, failedField: "steps" };
+        if (typeof s.operation !== "string" || !s.operation)
+            return { valid: false, failedField: "steps" };
+        if (Object.keys(s).some((k) => k !== "path" && k !== "operation"))
+            return { valid: false, failedField: "steps" };
+    }
+    if (!isNonEmptyStringArray(c.acceptance_criteria))
+        return { valid: false, failedField: "acceptance_criteria" };
+    if (!isNonEmptyStringArray(c.checks))
+        return { valid: false, failedField: "checks" };
+    if (!c.boundaries || typeof c.boundaries !== "object" || Array.isArray(c.boundaries))
+        return { valid: false, failedField: "boundaries" };
+    const b = c.boundaries;
+    if (!isNonEmptyStringArray(b.forbidden_paths))
+        return { valid: false, failedField: "boundaries" };
+    if (Object.keys(b).some((k) => k !== "forbidden_paths"))
+        return { valid: false, failedField: "boundaries" };
+    const writeSet = c.write_set;
+    const forbiddenPaths = b.forbidden_paths;
+    const stepPaths = c.steps.map((s) => s.path);
+    const markerPaths = c.control_markers.map((m) => m.path);
+    const referenced = new Set([...stepPaths, ...markerPaths]);
+    if (![...referenced].every((p) => writeSet.includes(p)))
+        return { valid: false, failedField: "steps" };
+    if (writeSet.some((p) => forbiddenPaths.includes(p)))
+        return { valid: false, failedField: "boundaries" };
+    return { valid: true, card: c };
+}
+export class ExecutionCardLifecycle {
+    #status = "READY";
+    #cardID;
+    #revision;
+    constructor(card) {
+        const result = validateExecutionCard(card);
+        if (!result.valid)
+            throw new Error(`Invalid execution card: ${result.failedField}`);
+        this.#cardID = result.card.card_id;
+        this.#revision = result.card.revision;
+    }
+    get status() { return this.#status; }
+    get card_id() { return this.#cardID; }
+    get revision() { return this.#revision; }
+    transition(status, identity) {
+        if (identity.card_id !== this.#cardID || identity.revision !== this.#revision)
+            throw new Error("Execution card identity is stale");
+        const allowed = {
+            READY: ["RUNNING", "CANCELLED"],
+            RUNNING: ["COMPLETED", "BLOCKED", "FAILED", "REJECTED_PLAN", "CANCELLED"],
+            COMPLETED: ["APPROVED", "CHANGES_REQUIRED"],
+            BLOCKED: [], FAILED: [], REJECTED_PLAN: [], APPROVED: [], CHANGES_REQUIRED: [], CANCELLED: [],
+        };
+        if (!allowed[this.#status].includes(status))
+            throw new Error(`Invalid execution-card transition: ${this.#status} -> ${status}`);
+        this.#status = status;
+        return this.#status;
+    }
+}
 export class RoutingGate {
     #receipts = new Map();
+    #ttlMs = 10 * 60 * 1000;
     preview(input) {
         return resolveRouting(input);
     }
     dispatch(input, provided) {
         const decision = resolveRouting(input);
-        if (!provided || typeof provided !== "object" || provided.decision_digest !== decision.decision_digest || provided.matrix_revision !== decision.matrix_revision)
+        if (!provided || typeof provided !== "object" || stable(provided) !== stable(decision))
             throw new Error("Routing decision is stale; request a new preview");
         if (decision.status !== "selected" || !decision.agent)
             throw new Error("Routing escalated; no agent was dispatched");
         return decision;
     }
-    grant(sessionID, decision) {
-        this.#receipts.set(sessionID, decision);
+    grant(sessionID, decision, context) {
+        const now = Date.now();
+        const taskDigest = context?.task === undefined ? decision.task_digest : digest(context.task);
+        const requirementsDigest = context?.requirements === undefined ? decision.requirements_digest : digest(context.requirements);
+        const cardDigest = context?.card === undefined ? decision.execution_card_digest : digest(context.card);
+        this.#receipts.set(sessionID, {
+            decision,
+            taskDigest,
+            requirementsDigest,
+            cardDigest,
+            expiresAt: now + this.#ttlMs,
+        });
     }
-    consume(sessionID, agent) {
+    cancel(sessionID) { this.#receipts.delete(sessionID); }
+    consume(sessionID, agent, context) {
         const receipt = this.#receipts.get(sessionID);
         if (!receipt)
             throw new Error("Native Task requires an active routing receipt; use the route tool");
-        if (receipt.agent !== agent)
+        if (receipt.decision.agent !== agent)
             throw new Error("Native Task agent does not match the active routing receipt");
+        if (Date.now() > receipt.expiresAt)
+            throw new Error("Routing receipt has expired; request a new preview");
+        if (context) {
+            const taskDigest = digest(context.task ?? "");
+            if (taskDigest !== receipt.taskDigest)
+                throw new Error("Routing receipt task does not match the active routing receipt");
+            const requirementsDigest = digest(context.requirements ?? []);
+            if (requirementsDigest !== receipt.requirementsDigest)
+                throw new Error("Routing receipt requirements do not match the active routing receipt");
+            const cardDigest = context.card !== undefined ? digest(context.card) : undefined;
+            if (cardDigest !== receipt.cardDigest)
+                throw new Error("Routing receipt execution card does not match the active routing receipt");
+        }
         this.#receipts.delete(sessionID);
     }
 }

package/dist/runtime/state.d.ts

@@ -4,4 +4,5 @@ export declare function readState<T>(path: string, boundary: string): Promise<T
 export declare function listState(boundary: string, suffix?: string): Promise<string[]>;
 export declare function writeState(path: string, boundary: string, value: unknown): Promise<void>;
 export declare function appendState(path: string, boundary: string, value: unknown): Promise<void>;
+export declare function withStateLock<T>(boundary: string, callback: () => Promise<T>): Promise<T>;
 export declare function digest(value: unknown): string;

package/dist/runtime/state.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { lstat, mkdir, readFile, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { appendPrivate, writeAtomic } from "../lifecycle.js";
+import { appendPrivate, withLifecycleLock, writeAtomic } from "../lifecycle.js";
 function home(value = process.env.HOME ?? homedir()) {
     if (!isAbsolute(value) || value.split(sep).includes(".."))
         throw new Error("HOME must be an absolute safe path");
@@ -94,14 +94,21 @@ export async function listState(boundary, suffix = ".json") {
 export async function writeState(path, boundary, value) {
     if (!inside(boundary, path))
         throw new Error("state path escapes its boundary");
-    await safeDirectory(dirname(path), boundary, true);
-    await writeAtomic(path, Buffer.from(`${JSON.stringify(value)}\n`), 0o600);
+    await withLifecycleLock(boundary, async () => {
+        await safeDirectory(dirname(path), boundary, true);
+        await writeAtomic(path, Buffer.from(`${JSON.stringify(value)}\n`), 0o600);
+    });
 }
 export async function appendState(path, boundary, value) {
     if (!inside(boundary, path))
         throw new Error("state path escapes its boundary");
-    await safeDirectory(dirname(path), boundary, true);
-    await appendPrivate(path, value);
+    await withLifecycleLock(boundary, async () => {
+        await safeDirectory(dirname(path), boundary, true);
+        await appendPrivate(path, value);
+    });
+}
+export async function withStateLock(boundary, callback) {
+    return withLifecycleLock(boundary, callback);
 }
 export function digest(value) {
     return createHash("sha256").update(JSON.stringify(value), "utf8").digest("hex");

package/dist/terminal-wizard.d.ts

@@ -0,0 +1,2 @@
+export declare function selectOption(label: string, options: readonly string[], stdin?: NodeJS.ReadStream, stderr?: NodeJS.WriteStream, initial?: number): Promise<number | null>;
+export declare function promptText(label: string, stdin?: NodeJS.ReadStream, stderr?: NodeJS.WriteStream): Promise<string | null>;

package/dist/terminal-wizard.js

@@ -0,0 +1,125 @@
+import { InstallerError } from "./installer.js";
+function parseKey(buffer) {
+    const seq = buffer.toString();
+    if (seq === "\r" || seq === "\n")
+        return { name: "return", sequence: seq };
+    if (seq === "\x03")
+        return { name: "ctrl+c", sequence: seq };
+    if (seq === "\x04")
+        return { name: "ctrl+d", sequence: seq };
+    if (seq === "\x1b" || seq === "\x1b\x1b" || seq === "\x1b\x1b\x1b")
+        return { name: "escape", sequence: seq };
+    if (seq === "\x1b[A" || seq === "\x1b[OA")
+        return { name: "up", sequence: seq };
+    if (seq === "\x1b[B" || seq === "\x1b[OB")
+        return { name: "down", sequence: seq };
+    if (seq === "\x1b[C" || seq === "\x1b[OC")
+        return { name: "right", sequence: seq };
+    if (seq === "\x1b[D" || seq === "\x1b[OD")
+        return { name: "left", sequence: seq };
+    return { name: "unknown", sequence: seq };
+}
+function clearLines(stderr, count) {
+    for (let i = 0; i < count; i++) {
+        stderr.write("\x1b[A\x1b[K");
+    }
+}
+export async function selectOption(label, options, stdin = process.stdin, stderr = process.stderr, initial = 0) {
+    if (!stdin.isTTY || !stderr.isTTY) {
+        throw new InstallerError("terminal_required", "This operation requires an interactive terminal");
+    }
+    let selected = Math.max(0, Math.min(initial, options.length - 1));
+    const lineCount = options.length + 1; // label + options
+    function render() {
+        stderr.write(`${label}\n`);
+        for (let i = 0; i < options.length; i++) {
+            const cursor = i === selected ? "> " : "  ";
+            stderr.write(`${cursor}${options[i]}\n`);
+        }
+    }
+    render();
+    return new Promise((resolve) => {
+        stdin.setRawMode(true);
+        stdin.resume();
+        function cleanup() {
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdin.removeListener("data", onData);
+        }
+        function onData(data) {
+            let remaining = data.toString();
+            while (remaining) {
+                const sequence = remaining.startsWith("\x1b[") ? remaining.slice(0, 3) : remaining[0];
+                remaining = remaining.slice(sequence.length);
+                const key = parseKey(Buffer.from(sequence));
+                if (key.name === "ctrl+c" || key.name === "ctrl+d" || key.name === "escape") {
+                    cleanup();
+                    clearLines(stderr, lineCount);
+                    resolve(null);
+                    return;
+                }
+                if (key.name === "return") {
+                    cleanup();
+                    clearLines(stderr, lineCount);
+                    resolve(selected);
+                    return;
+                }
+                if (key.name === "up") {
+                    clearLines(stderr, lineCount);
+                    selected = (selected - 1 + options.length) % options.length;
+                    render();
+                }
+                else if (key.name === "down") {
+                    clearLines(stderr, lineCount);
+                    selected = (selected + 1) % options.length;
+                    render();
+                }
+            }
+        }
+        stdin.on("data", onData);
+    });
+}
+export async function promptText(label, stdin = process.stdin, stderr = process.stderr) {
+    if (!stdin.isTTY || !stderr.isTTY) {
+        throw new InstallerError("terminal_required", "This operation requires an interactive terminal");
+    }
+    stderr.write(`${label} `);
+    return new Promise((resolve) => {
+        let buffer = "";
+        stdin.setRawMode(true);
+        stdin.resume();
+        function cleanup() {
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdin.removeListener("data", onData);
+        }
+        function onData(data) {
+            for (const seq of data.toString()) {
+                if (seq === "\r" || seq === "\n") {
+                    cleanup();
+                    stderr.write("\n");
+                    resolve(buffer.trim() || null);
+                    return;
+                }
+                if (seq === "\x03" || seq === "\x04" || seq === "\x1b") {
+                    cleanup();
+                    stderr.write("\n");
+                    resolve(null);
+                    return;
+                }
+                if (seq === "\x7f" || seq === "\b") {
+                    if (buffer.length > 0) {
+                        buffer = buffer.slice(0, -1);
+                        stderr.write("\x1b[D \x1b[D");
+                    }
+                    continue;
+                }
+                if (seq >= " ") {
+                    buffer += seq;
+                    stderr.write(seq);
+                }
+            }
+        }
+        stdin.on("data", onData);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kisev/skills-opencode",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "OpenCode integration and opt-in installer for portable Agent Skills.",
   "license": "MIT",
   "repository": {