@llblab/pi-telegram 0.11.0 → 0.11.2

package/docs/command-templates.md

@@ -4,12 +4,14 @@ Command templates are the portable integration format for deterministic local au
 
 **Meta-contract:** transportable (bit-for-bit identical across projects), high-density (zero fluff), constant (evolve by crystallizing, not speculating), optimal minimum (add only when it hurts).
 
-**Scope:** portable synchronous command execution format — shell-free exec, composition/pipes, timeout (30s default), delay-before-start, retry, critical-step branching, output artifact selection, and handler-level fallback. Single JSON standard; no platform lock-in.
+**Scope:** portable synchronous command execution format — shell-free exec, composition/pipes, optional timeout, delay-before-start, bounded retry, failure propagation, recover cleanup, output artifact selection, and handler-level fallback. Single JSON standard; no platform lock-in.
 
 ---
 
 Extensions may choose their own config files, selectors, placeholder sources, and examples, but should preserve this core contract.
 
+Layer boundary: command templates own only the synchronous execution graph. Recipe imports, import-reference expressions, recipe lookup, `async: true`, run ids, state dirs, FIFO controls, and outbox events are host/recipe/async-run configuration layers, not portable command-template syntax.
+
 ## Shape
 
 A command template is either a command-line string or an ordered array of command-template leaves:
@@ -32,13 +34,15 @@ Common object fields:
 
 - `label`: Optional human label for diagnostics and parallel branch reports.
 - `mode`: Optional execution mode for array templates. Default is `"sequence"`; `"parallel"` runs children concurrently.
-- `args`: Optional placeholder-name declarations only. Never stores defaults.
+- `args`: Optional placeholder declarations. Untyped names remain valid; compact typed forms such as `file:path`, `timeout:int`, `speed:number`, `dry_run:bool`, `prompts:array`, and `mode:enum(check,fix)` are valid when the host supports typed tool schemas. Defaults belong in `defaults` or inline placeholder defaults; hosts may normalize interactive shorthand such as `timeout:int=60000` before persistence.
 - `defaults`: Placeholder default values by name.
-- `timeout`: Optional execution timeout in milliseconds. Default is `30000`. Long-running agent calls should set this explicitly.
+- `timeout`: Optional execution timeout in milliseconds. Omit it, or set `0`, to leave the command unbounded. Set an explicit positive timeout when a tool must fail closed instead of waiting indefinitely.
 - `delay`: Optional wait in milliseconds before starting this node. Default is no delay.
 - `output`: Optional result selector. Default is `"stdout"`; runtime values such as `"ogg"` are valid.
 - `retry`: Optional max attempts including the first. Default is `1`.
-- `critical`: Optional boolean. When `true`, failure aborts the root composition.
+- `critical`: Optional boolean. Backward-compatible alias for `failure: "root"`.
+- `failure`: Optional failure propagation scope: `continue`, `branch`, or `root`. Default is `continue`.
+- `recover`: Optional command template run between failed retry attempts. Recovery output is ignored; recovery failure stops retries.
 - `template`: Required command string or ordered composition array.
 
 For object form, write `template` last. Read the node flags first, then the executable content. Storage paths, labels, selectors, descriptions, and registry-specific metadata belong to each extension's local schema.
@@ -63,8 +67,9 @@ Supported forms:
 | ---------------- | ------------------------------------------------ |
 | `{name}`         | Required value from runtime values or `defaults` |
 | `{name=default}` | Inline default when no value is provided         |
+| `{items[index]}` | Array item selected by literal or repeat index   |
 
-Resolution order is runtime values → `defaults` → inline default → error.
+Resolution order is runtime values → `defaults` → inline default → error. Default values that are themselves a single placeholder, such as `{prompt}` resolving to `{prompts[index]}`, are resolved recursively with a small depth guard. A repeat node may set `repeat` to `{items.length}` when an array arg should determine fanout width.
 
 ```json
 {
@@ -80,6 +85,8 @@ With runtime values `{ "text": "hello" }`, argv is:
 
 Use `defaults` for visible configuration data; use inline defaults for compact local literals. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
 
+Typed declarations annotate the public tool interface, not the shell command. They may live in `args` or inline placeholders such as `{timeout:int=60000}` and `{mode:enum(check,fix)=check}`. Use metadata-first authoring (`args` plus `defaults`) when long templates should stay visually short; use inline-first authoring when one self-contained `template` property is clearer. They do not sandbox or reinterpret the executable; they only let the host generate narrower input schemas and normalize runtime values before placeholder substitution. Untyped `args` and untyped placeholders continue to work unchanged.
+
 ## Quoting
 
 Placeholder values are not shell-escaped because no shell is used. A value containing spaces remains one argv item when it replaces one split word:
@@ -122,12 +129,12 @@ Composition rules:
 
 - Execute leaves in order when `mode` is omitted or set to `"sequence"`
 - Execute child templates concurrently when `mode` is set to `"parallel"`
-- Parallel composition uses soft-quorum semantics by default: failed non-critical children are reported but do not abort siblings or the next sequence step
-- Non-critical failures are recorded and execution continues, while `critical: true` failures abort the root composition
+- Parallel composition uses soft-quorum semantics by default: failed children are reported as degraded branches unless failure propagation escalates
+- Non-critical failures are recorded and execution continues, while `failure: "branch"` stops the current branch and `failure: "root"` aborts the root composition
 - Treat the whole composition as one handler for selector matching and fallback
 - Top-level `args` and `defaults` apply to every leaf unless the leaf defines private values
 - Leaf `args` replace inherited `args`; leaf `defaults` merge over inherited defaults; `timeout` and `output` are not inherited into leaves
-- Default `30000` (30s) timeout applies automatically; configure `timeout` only for exceptional long-running commands
+- Timeout is disabled by default; configure a positive `timeout` for bounded commands that should fail closed
 - Each sequence leaf receives the previous leaf's stdout on stdin by default, while the final leaf stdout remains the default composition result
 - Each parallel child receives the same stdin, and child stdout values are joined in stable array order before flowing to the next sequence leaf
 - Parallel branch joins include branch label and status, and tool details include branch metadata plus coverage summary
@@ -231,38 +238,76 @@ Legacy local schemas may accept `pipe` as an alias, but the portable standard is
 
 By default, composition continues on failure: the failed step is logged and the next step executes. This is analogous to `make -k` — the user sees all failures at once and decides what to fix.
 
-## Critical Steps
+## Failure Propagation
+
+By default, failed steps use `failure: "continue"`: record the failure, clear stdout for that step, and continue the current sequence. This preserves the fail-open profile.
+
+Use `failure` when a node should stop more aggressively:
 
-Set `critical: true` on any leaf to abort the entire root composition on failure. One `critical` leaf can halt the whole pipeline.
+- `"continue"`: record the failure and continue the current sequence.
+- `"branch"`: stop the current sequence/subtree and return a failed branch to the nearest parent. In a parallel node, sibling branches keep running and the join becomes degraded. At the root, branch failure is still a tool failure.
+- `"root"`: abort the outermost composition.
 
 ```json
 {
+  "mode": "parallel",
   "template": [
-    { "template": "cargo build" },
-    { "template": "cargo fmt --check" },
-    { "critical": true, "template": "cargo test" }
+    {
+      "label": "agent-a",
+      "failure": "branch",
+      "template": [
+        "agent-a-work {scope}",
+        "agent-a-validate {scope}",
+        "agent-a-push {scope}"
+      ]
+    },
+    {
+      "label": "agent-b",
+      "failure": "branch",
+      "template": [
+        "agent-b-work {scope}",
+        "agent-b-validate {scope}",
+        "agent-b-push {scope}"
+      ]
+    }
   ]
 }
 ```
 
-`build` / `fmt` failures are logged, execution continues. `test` failure aborts the root composition immediately.
+If `agent-a-validate` fails, `agent-a-push` is skipped, `agent-b` can still finish, and the parallel join reports degraded branch coverage.
 
-A `critical` leaf in a nested composition still aborts the outermost root `template: [...]`. There is no per-branch scoping in the current standard.
+`critical: true` remains a backward-compatible alias for `failure: "root"`. Prefer `failure` for new templates because it names the propagation scope directly.
 
 ## Retry
 
-Set `retry: N` on a leaf to attempt execution up to `N` times (including the first). Retries happen immediately on non-zero exit. The first successful attempt stops the retry loop.
+Set `retry: N` to attempt execution up to `N` times including the first. The first successful attempt stops the retry loop.
+
+On leaf commands, retry repeats that command. On sequence or parallel nodes, retry repeats the whole node. A retried group only retries when the group returns a failure, so validator checkpoints normally pair group retry with `failure: "branch"` or `failure: "root"`.
 
 ```json
 {
-  "template": [
-    { "retry": 3, "template": "npm install" },
-    { "retry": 2, "critical": true, "template": "npm test" }
-  ]
+  "failure": "branch",
+  "retry": 3,
+  "template": ["implement {scope}", "npm test", "git diff --check"]
+}
+```
+
+Here the whole group runs again when a validator fails. Without `failure: "branch"`, the failed validator would be logged and the group would continue by default.
+
+## Recover
+
+Set `recover` on a retried node to run cleanup after a failed attempt and before the next attempt. `recover` is another command template: it can be a string command, sequence, or mode tree. Its output is ignored and the next retry receives the original stdin.
+
+```json
+{
+  "failure": "branch",
+  "retry": 3,
+  "recover": "git -C {work_dir} reset --hard HEAD",
+  "template": ["pi -p --tools read,edit,bash {scope_file}", "npm test"]
 }
 ```
 
-`npm install` is retried up to 3 times. `npm test` is retried up to 2 times; if all attempts fail, the critical step aborts the pipeline.
+`recover` is not a fallback success path. It is cleanup between attempts. Practical uses include resetting a worktree, removing temp files, clearing generated output, releasing a local lock, or stopping a helper process before trying the node again. If recovery fails, retries stop and the recovery failure is returned. Recovery uses fail-closed semantics by default; set an explicit `failure` inside a recover template only when a softer cleanup failure is intentional.
 
 ## Delay
 
@@ -290,12 +335,24 @@ string           → leaf command
 string[]         → sequential composition
 { template }     → leaf command object
 { mode, template } → sequence or parallel subtree
-{ mode, args, defaults, delay, retry, critical, output, template } → full node
+{ mode, args, defaults, delay, retry, failure, recover, output, template } → full node
 ```
 
-Start with a string. Add composition when needed. Add `mode: "parallel"` when independent work can run concurrently. Add delay when launch pacing matters. Add retry when flaky. Add critical when safety matters. Same contract, growing capability, no dead weight.
+Start with a string. Add composition when needed. Add `mode: "parallel"` when independent work can run concurrently. Add delay when launch pacing matters. Add retry when flaky. Add `failure` when propagation scope matters. Add `recover` when a retried node needs cleanup before another attempt. Same contract, growing capability, no dead weight.
+
+`mode: "parallel"` is the synchronous fanout shape. Saved JSON recipes and detached lifecycle concerns such as logs, cancellation, and durable state belong to host-specific recipe/async-run standards, not to command templates.
+
+## Trust Boundary
+
+Command templates avoid shell interpolation by splitting the template into argv first and substituting placeholders per arg. A placeholder value containing spaces remains one argv value, not a shell fragment.
+
+This is not a sandbox. The executable still runs with the same user permissions as the host agent. Shells, interpreter eval modes, destructive filesystem commands, and local scripts remain trusted code. Examples that deserve extra operator attention:
+
+- `bash`, `sh`, `zsh`, or `fish`, especially with `-c`.
+- `node -e`, `python -c`, `ruby -e`, `perl -e`, or similar eval modes.
+- `rm`, `mv`, `cp`, or `rsync` over broad paths or placeholder-derived paths.
 
-`mode: "parallel"` is the synchronous fanout shape. Detached lifecycle, logs, cancellation, and durable state belong to host-specific async job or runtime-envelope standards, not to command templates.
+Hosts may surface lightweight warnings for these obvious high-risk shapes. Warnings should inform review without blocking existing tools, because many trusted local wrappers intentionally use shells or filesystem mutation.
 
 ## Tool Boundary
 

package/index.ts

@@ -11,7 +11,6 @@ import * as Config from "./lib/config.ts";
 import {
   createTelegramExtensionSectionRegistry,
   setGlobalTelegramSectionRegistry,
-  registerTelegramSection,
   type TelegramSectionRegistry,
 } from "./lib/extension-sections.ts";
 import { createTelegramExternalHandleUpdate } from "./lib/external-handlers.ts";
@@ -38,6 +37,7 @@ import * as Runtime from "./lib/runtime.ts";
 import * as Setup from "./lib/setup.ts";
 import * as Status from "./lib/status.ts";
 import * as TextGroups from "./lib/text-groups.ts";
+import * as TimeInjection from "./lib/time-injection.ts";
 import * as Voice from "./lib/voice.ts";
 
 const VOICE_EVENT_RECORDER_KEY = "__piTelegramVoiceEventRecorder__";
@@ -45,42 +45,6 @@ const VOICE_EVENT_RECORDER_KEY = "__piTelegramVoiceEventRecorder__";
 type ActivePiModel = NonNullable<Pi.ExtensionContext["model"]>;
 type RuntimeTelegramQueueItem = Queue.TelegramQueueItem<Pi.ExtensionContext>;
 
-export {
-  registerTelegramOutboundHandler,
-  hasTelegramOutboundHandler,
-  getTelegramOutboundProgrammaticHandlers,
-  recordTelegramRuntimeEvent,
-} from "./lib/outbound-handlers.ts";
-
-// --- Voice Integration Exports ---
-// Prefer domain imports from ./lib/voice.ts; root exports stay for compatibility.
-export {
-  registerTelegramVoiceSynthesisProvider,
-  getTelegramVoiceSynthesisProviders,
-  hasTelegramVoiceSynthesisProvider,
-  clearTelegramVoiceSynthesisProviders,
-  planTelegramVoiceReply,
-  getTelegramVoiceReplyMode,
-  computeVoiceTurnFlags,
-  isVoiceTurn,
-  shouldSuppressPreviewForVoice,
-  computeVoicePromptContribution,
-  type TelegramVoiceSynthesisProvider,
-  type TelegramVoiceTurnView,
-  type TelegramVoiceSynthesisProviderResult,
-  type TelegramVoiceReplyMode,
-} from "./lib/voice.ts";
-
-// --- Extension Section Exports ---
-export {
-  registerTelegramSection,
-  type TelegramSectionRegistration,
-  type TelegramSectionContext,
-  type TelegramSectionCallbackContext,
-  type TelegramSectionView,
-  type TelegramSectionSettingsRegistration,
-} from "./lib/extension-sections.ts";
-
 // --- Extension Runtime ---
 
 export default function (pi: Pi.ExtensionAPI) {
@@ -98,7 +62,10 @@ export default function (pi: Pi.ExtensionAPI) {
   Config.setGlobalTelegramConfigRuntime({
     updateVoiceConfig(voice) {
       const current = configStore.get();
-      const next = { ...current, voice: { ...(current.voice ?? {}), ...voice } };
+      const next = {
+        ...current,
+        voice: { ...(current.voice ?? {}), ...voice },
+      };
       configStore.set(next);
       void configStore.persist(next);
     },
@@ -113,6 +80,10 @@ export default function (pi: Pi.ExtensionAPI) {
     Config.createTelegramVoiceReplyModeConfiguredChecker(configStore);
   const setVoiceReplyMode =
     Config.createTelegramVoiceReplyModeSetter(configStore);
+  const getTimeInjectionMode =
+    Config.createTelegramTimeInjectionModeGetter(configStore);
+  const setTimeInjectionMode =
+    Config.createTelegramTimeInjectionModeSetter(configStore);
   const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
   const lockOwnershipGuard =
     Locks.createTelegramLockOwnershipGuard(lockRuntime);
@@ -132,14 +103,16 @@ export default function (pi: Pi.ExtensionAPI) {
     createTelegramExtensionSectionRegistry();
   setGlobalTelegramSectionRegistry(sectionRegistry);
 
-
   const runtimeEvents = Status.createTelegramRuntimeEventRecorder({
     getBotToken: configStore.getBotToken,
   });
   const recordRuntimeEvent = runtimeEvents.record;
-  (globalThis as Record<string, unknown>)[
-    VOICE_EVENT_RECORDER_KEY
-  ] = recordRuntimeEvent;
+  const timeInjectionRuntime = TimeInjection.createTimeInjectionRuntime({
+    getConfig: Config.createTelegramTimeConfigGetter(configStore),
+    recordRuntimeEvent,
+  });
+  (globalThis as Record<string, unknown>)[VOICE_EVENT_RECORDER_KEY] =
+    recordRuntimeEvent;
   const getContextModel = Pi.getExtensionContextModel;
   const isIdle = Pi.isExtensionContextIdle;
   const hasPendingMessages = Pi.hasExtensionContextPendingMessages;
@@ -156,6 +129,7 @@ export default function (pi: Pi.ExtensionAPI) {
     Queue.createTelegramQueueStore<Pi.ExtensionContext>();
   const deferredQueueDispatchRuntime =
     Queue.createTelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>({
+      delayMs: 50,
       recordRuntimeEvent,
     });
   const pollingControllerState = Polling.createTelegramPollingControllerState();
@@ -386,8 +360,10 @@ export default function (pi: Pi.ExtensionAPI) {
       isProactivePushEnabled,
       getVoiceReplyMode,
       isVoiceReplyModeConfigured,
+      getTimeInjectionMode,
       setProactivePushEnabled,
       setVoiceReplyMode,
+      setTimeInjectionMode,
     },
     sectionRegistry,
   );
@@ -435,6 +411,7 @@ export default function (pi: Pi.ExtensionAPI) {
     setMyCommands,
     getCommands,
     downloadFile: downloadTelegramBridgeFile,
+    resolveTimeLine: timeInjectionRuntime.resolveLine,
     getThinkingLevel,
     setThinkingLevel,
     persistScopedModelPatterns: Pi.createScopedModelPatternPersister({
@@ -611,9 +588,23 @@ export default function (pi: Pi.ExtensionAPI) {
   const agentStartWithDedupReset = Lifecycle.createAgentStartDedupHook(
     agentLifecycleHooks.onAgentStart,
   );
+  const compactionObserver = Lifecycle.createTelegramCompactionObserverRuntime({
+    setCompactionInProgress: lifecycle.setCompactionInProgress,
+    updateStatus,
+    requestDeferredDispatchNextQueuedTelegramTurn:
+      deferredQueueDispatchRuntime.request,
+    dispatchNextQueuedTelegramTurn,
+    recordRuntimeEvent,
+  });
   Lifecycle.registerTelegramLifecycleHooks(pi, {
     ...sessionLifecycleRuntime,
     ...agentLifecycleHooks,
+    async onSessionShutdown(event, ctx) {
+      compactionObserver.onSessionShutdown();
+      await sessionLifecycleRuntime.onSessionShutdown(event, ctx);
+    },
+    onSessionBeforeCompact: compactionObserver.onSessionBeforeCompact,
+    onSessionCompact: compactionObserver.onSessionCompact,
     onAgentStart: agentStartWithDedupReset,
     onBeforeAgentStart: Prompts.createTelegramProactiveBeforeAgentStartHook({
       isProactivePushEnabled,

package/lib/command-templates.ts

@@ -8,9 +8,8 @@ import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
 
-export const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
-
 export type CommandTemplateMode = "sequence" | "parallel";
+export type CommandTemplateFailureScope = "continue" | "branch" | "root";
 
 export interface CommandTemplateObjectConfig {
   label?: string;
@@ -23,7 +22,9 @@ export interface CommandTemplateObjectConfig {
   output?: string;
   retry?: number;
   critical?: boolean;
-  repeat?: number;
+  failure?: CommandTemplateFailureScope;
+  recover?: CommandTemplateValue;
+  repeat?: number | string;
 }
 
 export type CommandTemplateValue = string | CommandTemplateConfig[] | CommandTemplateObjectConfig;
@@ -72,23 +73,92 @@ export function normalizeCommandTemplateConfig(
   return typeof config === "string" ? { template: config } : config;
 }
 
+function normalizeRecoverConfig(
+  config: CommandTemplateValue | undefined,
+): CommandTemplateConfig | undefined {
+  if (config === undefined) return undefined;
+  return Array.isArray(config) ? { template: config } : config;
+}
+
 function normalizeCommandTemplateDefaults(
   defaults: Record<string, unknown> | undefined,
 ): Record<string, unknown> | undefined {
   if (!defaults) return undefined;
   const normalized: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(defaults)) {
-    normalized[key] =
-      value === undefined || value === null ? "" : String(value);
+    normalized[key] = Array.isArray(value)
+      ? value
+      : value === undefined || value === null ? "" : String(value);
   }
   return normalized;
 }
 
-function normalizeRepeat(value: number | undefined): number | undefined {
+export function resolveCommandTemplateRepeat(
+  value: number | string | undefined,
+  values: Record<string, unknown> = {},
+): number | undefined {
   if (value === undefined) return undefined;
-  if (!Number.isInteger(value) || value < 1)
-    throw new Error("Command template repeat must be a positive integer.");
-  return value;
+  if (typeof value === "number") {
+    if (!Number.isInteger(value) || value < 1)
+      throw new Error("Command template repeat must be a positive integer.");
+    return value;
+  }
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) return Number(trimmed);
+  const lengthMatch = trimmed.match(/^\{?([A-Za-z_][A-Za-z0-9_-]*)\.length\}?$/);
+  if (lengthMatch) {
+    const source = values[lengthMatch[1]];
+    if (Array.isArray(source)) return source.length;
+    if (source === undefined) return undefined;
+  }
+  throw new Error("Command template repeat must be a positive integer or {array.length}.");
+}
+
+function getExecutableName(command: string | undefined): string {
+  if (!command) return "";
+  return command.split(/[\\/]/).pop()?.toLowerCase() ?? "";
+}
+
+function hasAnyFlag(args: string[], flags: string[]): boolean {
+  return args.some((arg) => flags.includes(arg));
+}
+
+function hasRiskyPathArg(args: string[]): boolean {
+  return args.some((arg) =>
+    arg === "/" ||
+    arg === "~" ||
+    arg === "./" ||
+    arg === "../" ||
+    arg.includes("{") ||
+    arg.startsWith("~/") ||
+    arg.startsWith("/"),
+  );
+}
+
+function getLeafCommandTemplateWarnings(
+  config: CommandTemplateLeafConfig,
+): string[] {
+  const parts = splitCommandTemplate(config.template);
+  const command = getExecutableName(parts[0]);
+  const args = parts.slice(1);
+  const warnings: string[] = [];
+  if (["bash", "sh", "zsh", "fish"].includes(command)) {
+    const mode = hasAnyFlag(args, ["-c"]) ? "shell command strings" : "shell scripts";
+    warnings.push(`${config.label ?? command}: invokes ${command}; ${mode} are trusted executable content and are not sandboxed by command-template argv splitting.`);
+  }
+  if (["node", "deno", "bun"].includes(command) && hasAnyFlag(args, ["-e", "--eval"])) {
+    warnings.push(`${config.label ?? command}: invokes ${command} eval mode; code strings are trusted executable content and are not sandboxed.`);
+  }
+  if (["python", "python3", "perl", "ruby"].includes(command) && hasAnyFlag(args, ["-c", "-e"])) {
+    warnings.push(`${config.label ?? command}: invokes ${command} code-eval mode; code strings are trusted executable content and are not sandboxed.`);
+  }
+  if (command === "rm" && (args.some((arg) => /^-[^-]*r/.test(arg) || /^-[^-]*f/.test(arg)) || hasRiskyPathArg(args))) {
+    warnings.push(`${config.label ?? command}: removes filesystem paths; verify placeholders and paths before running trusted destructive commands.`);
+  }
+  if (["mv", "cp", "rsync"].includes(command) && hasRiskyPathArg(args)) {
+    warnings.push(`${config.label ?? command}: mutates broad filesystem paths; verify placeholders and paths before running trusted commands.`);
+  }
+  return warnings;
 }
 
 function pad(value: number, width: number): string {
@@ -124,7 +194,7 @@ function expandRepeatConfig(
   config: CommandTemplateObjectConfig,
   context: Pick<CommandTemplateObjectConfig, "args" | "defaults">,
 ): CommandTemplateObjectConfig[] | undefined {
-  const repeat = normalizeRepeat(config.repeat);
+  const repeat = resolveCommandTemplateRepeat(config.repeat, context.defaults ?? {});
   if (repeat === undefined) return undefined;
   return Array.from({ length: repeat }, (_unused, index0) => {
     const { repeat: _repeat, ...rest } = config;
@@ -164,12 +234,19 @@ export function expandCommandTemplateConfigs(
   if (repeated) {
     return repeated.flatMap((step) => expandCommandTemplateConfigs(step, context));
   }
+  const recoverConfig = normalizeRecoverConfig(normalizedConfig.recover);
+  const recoverSteps = recoverConfig
+    ? expandCommandTemplateConfigs(recoverConfig, context)
+    : [];
   if (Array.isArray(normalizedConfig.template)) {
-    return normalizedConfig.template.flatMap((step) =>
-      expandCommandTemplateConfigs(step, context),
-    );
+    return [
+      ...normalizedConfig.template.flatMap((step) =>
+        expandCommandTemplateConfigs(step, context),
+      ),
+      ...recoverSteps,
+    ];
   }
-  if (typeof normalizedConfig.template !== "string") return [];
+  if (typeof normalizedConfig.template !== "string") return recoverSteps;
   return [
     {
       ...normalizedConfig,
@@ -178,9 +255,37 @@ export function expandCommandTemplateConfigs(
       retry: normalizedConfig.retry,
       critical: normalizedConfig.critical,
     },
+    ...recoverSteps,
   ];
 }
 
+export function getCommandTemplateWarnings(
+  config: CommandTemplateConfig,
+): string[] {
+  return [
+    ...new Set(
+      expandCommandTemplateConfigs(config)
+        .flatMap((leaf) => getLeafCommandTemplateWarnings(leaf)),
+    ),
+  ];
+}
+
+function parseCommandTemplateArgToken(value: string): { name: string; defaultValue?: string } {
+  const separatorIndex = value.indexOf("=");
+  const rawName = separatorIndex === -1 ? value : value.slice(0, separatorIndex);
+  const colonIndex = rawName.indexOf(":");
+  return {
+    name: (colonIndex === -1 ? rawName : rawName.slice(0, colonIndex)).trim(),
+    ...(separatorIndex === -1 ? {} : { defaultValue: value.slice(separatorIndex + 1).trim() }),
+  };
+}
+
+function parseCommandTemplatePlaceholderContent(content: string): { name: string; inlineDefault?: string } | undefined {
+  const match = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)(?::(?:string|path|int|number|bool|array|enum\([^)]*\)))?(?:=([^}]*))?$/);
+  if (!match) return undefined;
+  return { name: match[1], ...(match[2] !== undefined ? { inlineDefault: match[2] } : {}) };
+}
+
 export function getCommandTemplateDefaults(
   config: CommandTemplateConfig | undefined,
 ): Record<string, string> {
@@ -190,9 +295,9 @@ export function getCommandTemplateDefaults(
   const defaults: Record<string, string> = {};
   for (const item of normalizeCommandTemplateArgs(normalizedConfig?.args)) {
     if (!item) continue;
-    const [name, ...defaultParts] = item.split("=");
-    if (!name || defaultParts.length === 0) continue;
-    defaults[name.trim()] = defaultParts.join("=").trim();
+    const parsed = parseCommandTemplateArgToken(item);
+    if (!parsed.name || parsed.defaultValue === undefined) continue;
+    defaults[parsed.name] = parsed.defaultValue;
   }
   for (const [key, value] of Object.entries(normalizedConfig?.defaults ?? {})) {
     defaults[key] = value === undefined || value === null ? "" : String(value);
@@ -256,7 +361,7 @@ export function expandCommandTemplateExecutable(
 
 function evaluateCommandTemplateExpression(
   expression: string,
-  values: Record<string, string>,
+  values: Record<string, unknown>,
 ): number {
   let index = 0;
   const source = expression.replace(/\s+/g, "");
@@ -283,7 +388,7 @@ function evaluateCommandTemplateExpression(
     if (nameMatch) {
       index += nameMatch[0].length;
       const value = values[nameMatch[0]];
-      if (value === undefined || !/^-?\d+$/.test(value))
+      if (value === undefined || !/^-?\d+$/.test(String(value)))
         throw new Error(`Invalid command template expression variable: ${nameMatch[0]}`);
       return Number(value);
     }
@@ -313,7 +418,7 @@ function evaluateCommandTemplateExpression(
 
 function substituteCommandTemplateExpression(
   content: string,
-  values: Record<string, string>,
+  values: Record<string, unknown>,
 ): string | undefined {
   const padded = content.match(/^(_{1,6})\((.+)\)$/);
   if (padded) {
@@ -323,22 +428,50 @@ function substituteCommandTemplateExpression(
   return String(evaluateCommandTemplateExpression(content, values));
 }
 
+function resolveCommandTemplateValue(
+  content: string,
+  values: Record<string, unknown>,
+  missingLabel: string,
+  depth = 0,
+): string | undefined {
+  if (depth > 5) throw new Error(`Command template value recursion exceeded: ${content}`);
+  const indexed = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)\[([A-Za-z_][A-Za-z0-9_-]*|\d+)\]$/);
+  if (indexed) {
+    const source = values[indexed[1]];
+    const indexValue = /^\d+$/.test(indexed[2]) ? indexed[2] : values[indexed[2]];
+    const index = Number(indexValue);
+    if (!Array.isArray(source) || !Number.isInteger(index) || index < 0 || index >= source.length) {
+      throw new Error(`Missing ${missingLabel} value: ${content}`);
+    }
+    return String(source[index] ?? "");
+  }
+  const simple = parseCommandTemplatePlaceholderContent(content);
+  if (simple) {
+    if (Object.hasOwn(values, simple.name)) {
+      const raw = values[simple.name] ?? "";
+      if (typeof raw === "string" && /^\{[^{}]+\}$/.test(raw)) {
+        return substituteCommandTemplateToken(raw, values, missingLabel, depth + 1);
+      }
+      return Array.isArray(raw) ? JSON.stringify(raw) : String(raw);
+    }
+    if (simple.inlineDefault !== undefined) return simple.inlineDefault;
+  }
+  const expression = substituteCommandTemplateExpression(content, values);
+  if (expression !== undefined) return expression;
+  return undefined;
+}
+
 export function substituteCommandTemplateToken(
   token: string,
-  values: Record<string, string>,
+  values: Record<string, unknown>,
   missingLabel = "command template",
+  depth = 0,
 ): string {
   return token.replace(
     /\{([^{}]+)\}/g,
     (_match, content: string) => {
-      const simple = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)(?:=([^}]*))?$/);
-      if (simple) {
-        const [, name, inlineDefault] = simple;
-        if (Object.hasOwn(values, name)) return values[name] ?? "";
-        if (inlineDefault !== undefined) return inlineDefault;
-      }
-      const expression = substituteCommandTemplateExpression(content, values);
-      if (expression !== undefined) return expression;
+      const resolved = resolveCommandTemplateValue(content, values, missingLabel, depth);
+      if (resolved !== undefined) return resolved;
       throw new Error(`Missing ${missingLabel} value: ${content}`);
     },
   );
@@ -405,8 +538,6 @@ function execCommandTemplateOnce(
     }
     if (options.timeout !== undefined && options.timeout > 0)
       timeoutId = setTimeout(killProcess, options.timeout);
-    else if (options.timeout === undefined)
-      timeoutId = setTimeout(killProcess, DEFAULT_COMMAND_TIMEOUT_MS);
     proc.stdout?.on("data", (data) => {
       stdout += data.toString();
     });
@@ -427,7 +558,7 @@ function execCommandTemplateOnce(
 
 export function buildCommandTemplateInvocation(
   config: CommandTemplateConfig,
-  values: Record<string, string>,
+  values: Record<string, unknown>,
   cwd: string,
   options: { emptyMessage?: string; missingLabel?: string } = {},
 ): CommandTemplateInvocation {