@lmctl-ai/lmctl 0.1.342 → 0.2.2

package/dist/templates/basedir.d.ts

@@ -0,0 +1,52 @@
+/** The ONE place the default basedir name lives — re-defaulting is 1 line. */
+export declare const DEFAULT_BASEDIR_DIRNAME = ".lmctl";
+/**
+ * The active basedir (tiers 1-3). Never touches the filesystem beyond the
+ * project-local probe; pure given env + cwd.
+ */
+export declare function resolveBasedir(cwd?: string): string;
+/** `<basedir>/templates/workflows`. */
+export declare function templatesWorkflowsDir(cwd?: string): string;
+/**
+ * The read-only shipped-sibling workflows dir. dev (tsx):
+ * src/templates/basedir.ts → ../../workflows = <repo>/workflows. built
+ * (unbundled) dist/templates/basedir.js → <repo>/workflows. packed bundle:
+ * every module collapses onto dist/cli/index.js → ../../workflows =
+ * <pkgroot>/workflows (exactly where pack-release.mjs ships the
+ * engine-owned built-in). One expression, correct in all three.
+ */
+export declare function shippedWorkflowsDir(): string;
+export interface MaterializeResult {
+    basedir: string;
+    copied: string[];
+    refreshed: string[];
+    preserved: string[];
+    shadowed: string[];
+}
+/**
+ * Copy shipped workflow templates into `<basedir>/templates/workflows/`,
+ * honouring the sha256 manifest for edit-preservation. Idempotent.
+ * Best-effort: a read-only/unwritable basedir does NOT throw fatally for
+ * callers that pass `{ swallow: true }` — the per-template resolver still
+ * falls back to the shipped sibling so the engine never hard-fails.
+ */
+export declare function materializeTemplates(opts?: {
+    cwd?: string;
+    swallow?: boolean;
+}): MaterializeResult;
+/**
+ * The ordered basedir search list (tiers 1-3, same order as
+ * `resolveBasedir` but ALL applicable tiers, not just the winner):
+ * `$LMCTL_HOME` → nearest `./.lmctl` → `~/.lmctl`. Single source of the
+ * tier order — reused by `resolveWorkflowTemplate` and the `lmctl://`
+ * resolver so they can never drift. (The read-only shipped-sibling
+ * fallback is workflow-only and is appended by `resolveWorkflowTemplate`.)
+ */
+export declare function basedirSearchList(cwd?: string): string[];
+/**
+ * Resolve a workflow template by name (no extension) to an on-disk path,
+ * basedir-first then the read-only shipped sibling. Pure lookup — no
+ * mutation. Returns null if it exists nowhere (caller decides: the worker
+ * built-in keeps its graceful `catch → null`).
+ */
+export declare function resolveWorkflowTemplate(name: string, cwd?: string): string | null;

package/dist/uri/lmctl_uri.d.ts

@@ -0,0 +1,38 @@
+/** The URI scheme prefix — single named constant. */
+export declare const LMCTL_URI_SCHEME = "lmctl://";
+/** F4 (DECIDED 2026-05-19, WIRED) — the live remote catalog base. Single
+ *  named constant; mirror the local path shape `<base><kind>/<name>`. */
+export declare const LMCTL_REMOTE_CATALOG_BASE = "https://lmctl.com/templates/";
+/** F5 — fetched bytes are cached under `<basedir>/<LMCTL_CACHE_DIRNAME>/`
+ *  ONLY (never the user-editable `templates/` tree). */
+export declare const LMCTL_CACHE_DIRNAME = ".cache";
+/** Bounded remote fetch — a hung/slow catalog can never wedge resolution. */
+export declare const LMCTL_REMOTE_FETCH_TIMEOUT_MS = 8000;
+export type LmctlUriKind = 'workflow' | 'mcp' | 'skill';
+export interface ParsedLmctlUri {
+    kind: LmctlUriKind;
+    name: string;
+    /** Optional `@<sha256>` integrity pin (F6 hash-pinning). */
+    ref?: string;
+}
+/** Distinct failure classes (the directive's classification map):
+ *  - `malformed`           — the URI itself is invalid (parse).
+ *  - `missing`             — not local AND remote unreachable/404/non-2xx.
+ *  - `validation-failure`  — remote 2xx but pin-mismatch or shape-invalid
+ *                            (artifact discarded, NOT cached; loud). */
+export type LmctlUriFailure = 'malformed' | 'missing' | 'validation-failure';
+export declare class LmctlUriError extends Error {
+    readonly reason: LmctlUriFailure;
+    constructor(message: string, reason?: LmctlUriFailure);
+}
+/** True iff `s` is a string using the `lmctl://` scheme. */
+export declare function isLmctlUri(s: unknown): s is string;
+/** Parse + validate an `lmctl://` URI. Throws `LmctlUriError`
+ *  (reason `malformed`) on any malformed input — never a raw crash. */
+export declare function parseLmctlUri(uri: string): ParsedLmctlUri;
+/**
+ * Resolve an `lmctl://` URI to a concrete EXISTING local path. Local-first;
+ * on miss, the wired remote tier (bounded, typed-classified). Async because
+ * the remote tier uses `fetch`.
+ */
+export declare function resolveLmctlUri(uri: string, cwd?: string): Promise<string>;

package/durable-memory/model_selection.md

@@ -4,8 +4,21 @@
 
 For `.lmctl` teamfile compatibility mode:
 
-- `lmctl lint <teamfile>` warns when a requested model is not in the
-  tested-model catalog for `claude`, `gemini`, or `qwen`.
+- `lmctl lint <teamfile>` resolves `model=` for `claude`, `gemini`, `qwen`,
+  and `hermes` against the lmprice model catalog (see
+  `## lmprice Model Catalog` below) and warns when the model is not found.
+  This REPLACED the static tested-model lists that used to live in this
+  document (2026-09-24) — hand-copied lists contradicted the catalog.
+
+**Best-effort contract (operator, 2026-09-25): lint is advisory and is NOT
+claimed to be 100% up to date.** Checks can lag provider reality in BOTH
+directions — a model lint warns about may have just been added upstream, and
+a model lint accepts may have just been retired. Every model check is a
+warning, never an error (`lint --strict` is the operator's explicit
+promotion, not the default). The runtime stance for anything unrecognized
+or out of date is always: "not recognized — could still be valid; no cost
+information," never a failure. Cost is equally best-effort (n/a with a
+reason, never a guessed price).
 - `codex` and `agy` model validation queries each provider's own live
   catalog command (`codex debug models`, `agy models`) instead of a
   hand-copied list — see their `## Codex` / `## Antigravity` sections
@@ -34,18 +47,42 @@ For `.lmctl` teamfile compatibility mode:
   prefix. Hermes only treats a leading `<x>:` as a provider delimiter when
   `x` is a known provider name (`hermes_cli/models.py:parse_model_input`);
   a bare id stays the model name and Hermes then has to infer the provider
-  by detection, which fails for models it cannot place. See the `## Hermes`
-  section below.
+  by detection, which fails for models it cannot place. After the shape
+  check, lint ALSO resolves the id against the lmprice catalog (the hermes
+  adapter splits the `provider:` prefix) and warns on a catalog miss —
+  warning-only, since Hermes may still resolve it from user config. See the
+  `## Hermes` section below.
 - `copilot` accepts `model=` syntactically, but model selection is not
   supported and lint warns that the value is ignored.
 - `lmctl seed <teamfile>` passes `model=` through to the provider seed
   call. It does not contact provider model catalogs.
 
-The runtime also carries a built-in fallback catalog so installed
-`lmctl` can lint without requiring this source-tree document to be
-present in `dist`. Keep this document and
-`src/providers/config/model-selection-lint.ts` synchronized when adding
-or retiring tested model ids.
+The `claude`/`gemini`/`qwen` tables in the sections below are HISTORICAL
+evidence records of the retired tested-model lists (pre-2026-09-24); lint no
+longer consults them — it resolves against the lmprice catalog.
+
+## lmprice Model Catalog
+
+Since 2026-09-24 (0.2.1), model validation and costing share one catalog
+layer fed by the public lmprice dataset
+(`https://lmctl.com/dataset/model_list.json` + `aliases.json`):
+
+- **Loading**: ETag-conditional refresh into `~/.lmctl/cache/lmprice/` with a
+  6h TTL (`LMCTL_PRICE_TTL=0` forces; `LMCTL_PRICE_DATA=<dir>` pins a
+  snapshot and disables network); bundled snapshot from build time is the
+  offline fallback; the loader never throws.
+- **Resolution order** (provider-aware): provider-qualified alias hit
+  (evidence `established`/`asserted` → standards chain → pinned row;
+  `unresolved` is terminal, never guessed) → provider adapter family match →
+  miss. States: priced / estimated / known-unpriced / unresolved / unknown /
+  no-catalog.
+- **Invariant (operator, 2026-09-25): if we can lint, then we can cost.**
+  lmprice build validation rejects half-bindings (asserted alias ending in a
+  null record pin); lmctl surfaces any legacy known-unpriced as the lint
+  warning "recognized but no price information."
+- **Freshness**: the catalog is only as current as the last lmprice publish
+  plus the client TTL — see the best-effort contract at the top of this
+  document. `cost --debug` shows the dataset's `generated_at`.
 
 ## Claude
 
@@ -69,7 +106,7 @@ week: it kept `gpt-5.4-mini` listed as valid after OpenAI withdrew it from
 the subscription (194 codex members with no `model=` pinned were silently
 falling through to it as the ambient default), and separately omitted
 `gpt-5.6-terra`/`gpt-5.6-luna` after an operator quota downshift moved 260
-members onto them — both real, working models (`lmctl chat` confirmed
+members onto them — both real, working models (`lmctl prompt` confirmed
 live), producing 45 fleet-wide false-positive warnings. `codex debug
 models` ("Render the raw model catalog as JSON") shipped since the first
 incident and gives codex the same live-catalog treatment `agy` already
@@ -102,20 +139,19 @@ withdrawn outright and is not expected back.
 
 ## Gemini
 
-| Configured `model=` | Evidence |
-| --- | --- |
-| `gemini-3.1-pro-preview` | Ported from lmctl0 tested-model catalog. |
-| `gemini-3-flash-preview` | Ported from lmctl0 tested-model catalog. |
-| `gemini-3.1-flash-lite-preview` | Ported from lmctl0 tested-model catalog. |
-| `gemini-2.5-flash` | Ported from lmctl0 tested-model catalog. |
-| `gemini-2.5-flash-lite` | Ported from lmctl0 tested-model catalog. |
+**2026-09-24: lint no longer reads a tested-model table here** — gemini
+models resolve against the lmprice catalog (chat rows only; embedding /
+image / tts / realtime rows are excluded by the adapter). Note the
+`gemini` provider requires an API/enterprise Google account; personal
+subscriptions should use `agy`.
 
 ## Qwen
 
-| Configured `model=` | Evidence |
-| --- | --- |
-| `qwen3.5-plus` | Ported from lmctl0 tested-model catalog. |
-| `qwen3.6-plus` | Ported from lmctl0 tested-model catalog. |
+**2026-09-24: lint no longer reads a tested-model table here** — qwen
+models resolve against the lmprice catalog (bare, `dashscope/*`, and
+`qwen/` rows). `qwen/qwen3.5-plus` is an established identity whose
+current catalog price is null (known-unpriced — not a warning);
+`qwen/qwen3.6-plus` is deliberately unresolved in the alias table.
 
 ## Antigravity
 
@@ -144,6 +180,54 @@ not maintained going forward.
 | `Claude Opus 4.6 (Thinking)` | Observed from `agy models` on 2026-07-20. |
 | `GPT-OSS 120B (Medium)` | Observed from `agy models` on 2026-07-20. |
 
+**Pricing (2026-09-29, operator decision, math.lmctl findings 002/003):** separate from the lint
+question above ("is this a real agy model," answered live) is "does this resolve in the lmprice
+catalog for cost purposes" — the fleet's largest unpriced population (86 members, 4 base models,
+11 effort-tier declared strings). Root cause: agy exposes Google's Gemini models under its own
+display-label strings with a reasoning-effort tier baked into the name (`"Gemini 3.8 Flash (High)"`),
+and no upstream catalog source (LiteLLM or OpenRouter) will ever carry that exact string —
+normalizing punctuation can't fix a naming SYSTEM difference, only an explicit, evidenced row can
+(see `backlog/`'s finding-002/003 threads for the full reasoning).
+
+**Two layers, discovered while fixing this, not designed up front:** lmprice's own `aliases.json`
+already independently covers 4 of the 11 strings (established evidence, sourced from
+antigravity.google/docs/models, added 2026-09-24 — predates this fix): `gemini 3.8 flash (high)`,
+`gemini 3.8 flash (medium)`, `gemini 3.1 pro (high)`. Those resolve via lmctl's existing alias-table
+step and never touch new code. `src/providers/model-catalog.ts`'s `agyAdapter`/
+`AGY_DISPLAY_TO_IDENTITY` (added here) covers the remaining 7 lmprice hasn't published yet — all of
+3.7-flash and 3.6-flash had zero coverage from either mechanism before this. Confirmed live via
+`resolveOfferForCost`'s `provenance` field: `"alias-pin"` for the 4 lmprice already has,
+`"route-preference"` (this new table) for the other 7 — no conflict, no double-resolution. Raw
+`agy models` output this table was built from (verified live, 2026-09-29, agy binary on this
+machine):
+
+```
+gemini-3.8-flash-high	Gemini 3.8 Flash (High)
+gemini-3.8-flash-medium	Gemini 3.8 Flash (Medium)
+gemini-3.8-flash-low	Gemini 3.8 Flash (Low)
+gemini-3.7-flash-high	Gemini 3.7 Flash (High)
+gemini-3.7-flash-medium	Gemini 3.7 Flash (Medium)
+gemini-3.7-flash-low	Gemini 3.7 Flash (Low)
+gemini-3.6-flash-high	Gemini 3.6 Flash (High)
+gemini-3.6-flash-medium	Gemini 3.6 Flash (Medium)
+gemini-3.6-flash-low	Gemini 3.6 Flash (Low)
+gemini-3.1-pro-high	Gemini 3.1 Pro (High)
+gemini-3.1-pro-low	Gemini 3.1 Pro (Low)
+claude-sonnet-4-6	Claude Sonnet 4.6 (Thinking)
+claude-opus-4-6-thinking	Claude Opus 4.6 (Thinking)
+gpt-oss-120b-medium	GPT-OSS 120B (Medium)
+```
+
+Every effort-tier variant of one base model maps to that base model's own catalog identity —
+reasoning effort/thinking budget changes how many tokens a turn generates, not the per-token rate,
+true of every major vendor's reasoning-effort parameter (OpenAI, Claude, Gemini alike). **Not yet
+mapped:** the 3 non-Gemini agy models (`Claude Sonnet 4.6 (Thinking)`, `Claude Opus 4.6 (Thinking)`,
+`GPT-OSS 120B (Medium)`) — smaller population, deferred, not the highest-value row. `claude opus 4.6
+(thinking)` already has an established display-label alias in lmprice's table (like the 4 Gemini
+ones above); `claude sonnet 4.6 (thinking)` and `gpt-oss 120b (medium)` don't — lmprice's alias table
+has a DASHED-slug entry for claude-sonnet-4-6 but under a spelling (`agy/claude-sonnet-4-6`) that
+doesn't match what agy actually declares (`Claude Sonnet 4.6 (Thinking)`), so it's a live gap too.
+
 ## OpenCode
 
 opencode model ids use `<provider>/<model>` shape. **lmctl does NOT manage opencode
@@ -182,7 +266,7 @@ does not edit your config.
 `effort=`/variants: an opencode member's `effort=` maps to opencode's `--variant`
 (reasoning effort). Declare the variants on the model in your `opencode.json` (see
 the sample's Claude/GPT entries with `variants: { high, xhigh, max }`); on the ACP
-chat path lmctl sends `session/set_config_option` with `configId: "model"` and
+prompt path lmctl sends `session/set_config_option` with `configId: "model"` and
 `configId: "effort"` before `session/prompt`.
 
 For each opencode member with `model=`, `lmctl lint` runs the same ACP
@@ -214,8 +298,7 @@ config-file-YOLO provider). lmctl forces it into full-auto via an ACP protocol
 call (`session/set_config_option`, `configId: "mode"`, `value: "auto"`) sent
 after `session/new`/`session/load` and before the first `session/prompt` —
 fail-closed: if that call is rejected, lmctl throws rather than proceeding, on
-both the one-shot transport (`src/providers/transports/acp.ts`) and the
-persistent `lmctl serve`/daemon path (`src/serve/persistent-adapters.ts`). See
+the one-shot transport (`src/providers/transports/acp.ts`). See
 `src/providers/yolo-contract.ts`'s `PROTOCOL_LEVEL_YOLO` set for the contract.
 
 Kimi 0.28.x exposes `thinking` through ACP only as an `on`/`off` toggle.
@@ -260,7 +343,7 @@ the value should carry a `provider:` prefix, because without one Hermes
 has to infer the provider by model-name detection and fails for models it
 cannot place.
 
-V1 supports ACP seeding and structured chat/dispatch against one effective
+V1 supports ACP seeding and structured prompt/dispatch against one effective
 `HERMES_HOME`. Existing session IDs default to strict resume. Yolo mode enables
 both the shell approval bypass and the per-process ACP edit mode; plan mode is
 rejected. Native deletion, interactive resume, fork, and persistent daemon

package/examples/README.md

@@ -4,6 +4,78 @@ This directory contains public examples that are safe to copy into a project and
 customize. Teamfiles are intentionally unseeded: run `lmctl lint` first, edit
 providers or models if needed, then run `lmctl seed` in the target project.
 
+## Anonymous cross-provider panel
+
+[`anonymous-panel.lms`](anonymous-panel.lms) sends the same question concurrently
+through `parallel([...])` to Codex (`gpt-6-astra`), Agy
+(`Gemini 3.8 Flash (High)`), and Claude (`claude-sonnet-5`), then prints the
+answers as three Markdown table columns. It exits with an error if any call
+fails. Each agent is an inline map; no teamfile or manual seed step is needed.
+The three CLIs must be installed and authenticated with access to these models.
+Provider-native session records are still written by the provider CLIs.
+
+Run this checkout from the repository root:
+
+```sh
+node bin/lmctl script examples/anonymous-panel.lms
+```
+
+If source changes have not been compiled, run `npm run build` first. With this
+build installed as `lmctl`, the equivalent command is
+`lmctl script examples/anonymous-panel.lms`.
+
+The opt-in live test sends a unique challenge to a real Codex agent in an empty
+temporary workspace and asserts the exact reply, a native session ID, and that
+**no workspace file was created**, including any teamfile. It does not claim
+that provider-native session storage outside the workspace is untouched.
+
+```sh
+RUN_AGENT_LIVE_E2E=1 npx vitest run tests/e2e/script-agent-live.test.ts
+```
+
+Optional `LMCTL_AGENT_LIVE_PROVIDER` and `LMCTL_AGENT_LIVE_MODEL` select a different
+provider/model pair. The test uses a 120-second provider idle timeout and no
+wall-clock dispatch cutoff. It is skipped in ordinary hermetic test runs.
+
+## Return an operator decision to a script
+
+After an agent turn, pass its map to `prompt_human`:
+
+```lms
+agent = { provider: "codex" };
+result = lm_agent(agent, "Review this repository and suggest the next step");
+decision = prompt_human(agent);
+if (decision.command == "retry") {
+  result = lm_agent(agent, join(decision.args, " "));
+}
+```
+
+The operator sees the script's conversation and can send more messages to that
+same native session. Enter `/exit retry check the tests` to return
+`{command: "retry", args: ["check", "the", "tests"]}` to the script. Arguments
+are separated by whitespace. `/exit` returns command `exit`; closed input
+returns `eof`. Provider errors return `error` and stalls return `stalled`, with
+details in `args`. The simple `prompt_human("Question? ")` form still returns a
+string, or null on closed input.
+
+## Batch turns from a member value
+
+The member-map form needs no teamfile or prompt-file name:
+
+```lms
+member = { provider: "codex" };
+handle = lm_batch_open(member, { permissionMode: "plan", idleTimeoutMs: 120000 });
+first = lm_batch_turn(handle, "Describe the problem", 1, 2);
+second = lm_batch_turn(handle, "Suggest a solution", 2, 2);
+lm_batch_close(handle);
+```
+
+It retains the native session between turns and stops after a failed turn.
+This form uses sequential agent calls. The existing
+`lm_batch_open(teamfile, alias, batchfile, options)` form retains managed-team
+logging, locking, and bundle optimization; its batchfile argument is a tracking
+label, while `lm_batch_turn` supplies each actual prompt.
+
 ## Teamfile Gallery
 
 - [`research-team.lmctl`](research-team.lmctl) - fan out a question to multiple
@@ -21,5 +93,36 @@ lmctl lint examples/book-team.lmctl
 lmctl lint examples/review-team.lmctl
 ```
 
+## CLI Connectors & Process-Boundary Integration
+
+Connectors in LMScript are CLIs executed across process boundaries rather than in-process plugins. Because LLM reasoning dominates execution latency, invoking CLIs via `system()` provides language-agnostic, stateless, crash-isolated integration with negligible overhead.
+
+### Best Practices for CLI Connectors
+1. **Use Argv Arrays**: Prefer `system(["tool", "arg1", "arg2"])` over shell command strings. The argv form executes directly with `shell: false`, eliminating shell quoting issues and accidental pipe (`|`) interpretation.
+2. **Inspect Process Records & Output**: `system()` returns a defined record `{ stdout, stderr, code, signal, timed_out, duration_ms, pid }`. Check `result.code` and inspect `result.stderr` or application payloads. `system()` is strictly a completion primitive (always awaited); `code: null` strictly indicates abnormal termination (via signal or timeout), never a running or detached process. Because utilities often exit with code 0 even when reporting errors (e.g. HTTP 404 or batch errors), caller predicates in user space (e.g. `fn curl_ok(r)`) should verify stderr and application status rather than assuming exit code 0 implies success.
+3. **Structured JSON Envelopes**: When integrating CLIs that output data, prefer returning typed JSON envelopes (with explicit `kind`, `schema`, and `status` fields) parsed with `json(out)`. Distinguishing summary records from match records prevents silent attribute mismatches.
+
 `opencode.json` is a sample OpenCode model catalog. Copy and adjust it only if
 your teamfile uses `provider=opencode`.
+
+
+## Test-only batch comparison
+
+The production `lmctl batch` command retains its procedural implementation.
+LMScript adds capability; it does not replace existing commands. The experimental
+comparison path is:
+
+```sh
+lmctl batch team.lmctl Lead prompts.txt --legacy
+lmctl script examples/batchscript.lms team.lmctl Lead prompts.txt --legacy
+```
+
+Both execute prompts, so use separate fixture sessions for a live comparison.
+The hermetic `tests/cli/batch.test.ts` and `batch-bundle.test.ts` suites run the
+same assertions against both paths. `batch_independence.test.ts` pins production
+independence and equality of this file with the embedded `BATCH_LMS` asset.
+
+## Security & Execution Model
+
+LMScript executes with full operator authority without sandboxing, equivalent to running an administrative shell or Python script. File operations (`read_file`, `write_file`) and shell invocations (`system()`) run with the credentials and local environment of the invoking operator. Do not execute scripts from untrusted origins.
+

package/examples/anonymous-panel.lms

@@ -0,0 +1,3 @@
+question = "What is one useful way to check an AI answer? Answer in one sentence under 70 characters. Do not use tools or create files.";
+answers = parallel([lm_agent({ provider: "codex", model: "gpt-6-astra" }, question, { idleTimeoutMs: 120000 }), lm_agent({ provider: "agy", model: "Gemini 3.8 Flash (High)" }, question, { idleTimeoutMs: 120000 }), lm_agent({ provider: "claude", model: "claude-sonnet-5" }, question, { idleTimeoutMs: 120000 })]);
+for (i = 0; i < len(answers); i = i + 1) { answer = answers[i]; if (answer.status != "ok") { lm_error(answer.status, answer.error); lm_exit(1); } } print(format("| Codex / gpt-6-astra | Agy / Gemini 3.8 Flash (High) | Claude / claude-sonnet-5 |\n| --- | --- | --- |\n| {} | {} | {} |", replace(replace(trim(answers[0].reply), "\n", " "), "|", "/"), replace(replace(trim(answers[1].reply), "\n", " "), "|", "/"), replace(replace(trim(answers[2].reply), "\n", " "), "|", "/")));

package/examples/batch-prompts.txt

@@ -0,0 +1,9 @@
+This is a conversation-only batch test. Do not use tools or modify any files during this conversation. Remember the token cedar-731 for later turns. Set a running total to 3. Reply exactly: cedar-731 3
+
+Add 100 to the running total. Reply with the remembered token, one space, and the new total only.
+
+Multiply the running total by 2. Reply with the remembered token, one space, and the new total only.
+
+Subtract 6 from the running total. Reply with the remembered token, one space, and the new total only.
+
+What was the token I asked you to remember in the first prompt? Reply with only that token.

package/examples/batchscript.lms

@@ -0,0 +1,67 @@
+# batchscript.lms - Test-only comparison with procedural lmctl batch
+# Arguments: [teamfile, alias, batchfile, flags...]
+
+if (includes(args, "--help") || includes(args, "-h")) {
+  println("usage: lmctl batch <teamfile> <alias> <batchfile> [--legacy] [--single]");
+  lm_exit(0);
+}
+
+if (len(args) < 3) {
+  lm_error("usage: lmctl batch <teamfile> <alias> <batchfile> [--legacy] [--single]");
+  lm_exit(1);
+}
+
+teamfile = args[0];
+alias = args[1];
+batchfile = args[2];
+legacy = false;
+single = false;
+for (flag_index = 3; flag_index < len(args); flag_index = flag_index + 1) {
+  if (args[flag_index] == "--legacy") {
+    legacy = true;
+  } else if (args[flag_index] == "--single") {
+    single = true;
+  } else {
+    lm_error("batch: unexpected argument: " + args[flag_index]);
+    lm_exit(1);
+  }
+}
+
+# 1. Read prompts
+prompts = lm_read_prompts(batchfile, single);
+
+if (len(prompts) == 0) {
+  lm_error("batch: " + batchfile + ": no prompts found");
+  lm_exit(1);
+}
+
+# 2. Open batch session
+handle = lm_batch_open(teamfile, alias, batchfile, {
+  promptCount: len(prompts),
+  legacy: legacy,
+  single: single
+});
+
+if (handle == null) {
+  lm_exit(1);
+}
+
+# 3. Sequential prompt execution
+for (i = 0; i < len(prompts); i = i + 1) {
+  promptText = prompts[i];
+  res = lm_batch_turn(handle, promptText, i + 1, len(prompts));
+
+  # Output reply or partial reply on stall
+  if (res.reply != null && len(res.reply) > 0) {
+    print(res.reply);
+    print(""); # Blank line separator
+  }
+
+  if (res.status != "ok") {
+    lm_batch_close(handle, "error", res.error);
+    lm_exit(1);
+  }
+}
+
+lm_batch_close(handle, "done");
+lm_exit(0);

package/examples/n8n/agent-lib.lms

@@ -0,0 +1,56 @@
+# agent-lib.lms -- shared user-space helpers for driving agents from LMScript.
+# User-defined, not engine: primitives stay small and stable while user functions carry the size.
+
+# The state line is the fleet's contract: every agent turn ends with one of four words.
+# A reply whose last non-blank line is prose is NOT a pass -- it is NO_STATE_LINE, and that is a
+# finding in itself. Never let a missing state line read as success.
+fn state_of(text) {
+  if (text == null) { return "NO_REPLY"; }
+  raw = text;
+  if (type(text) == "object" && has_key(text, "reply")) { raw = text.reply; }
+  if (raw == null) { return "NO_REPLY"; }
+  lines = split(trim(raw), "\n");
+  i = len(lines) - 1;
+  while (i >= 0) {
+    l = trim(lines[i]);
+    i = i - 1;
+    if (len(l) == 0) { continue; }
+    if (l == "DONE" || l == "NOTHING_TO_DO" || l == "BLOCKED" || l == "OTHER") { return l; }
+    return "NO_STATE_LINE";
+  }
+  return "NO_STATE_LINE";
+}
+
+fn needs_human(st) {
+  return st == "OTHER" || st == "BLOCKED" || st == "NO_STATE_LINE" || st == "NO_REPLY";
+}
+
+# ATTENDED automation's handoff. GAP: a script cannot raise a TUI or hand over control, so printing
+# and stopping is the honest fallback -- never continue past a handoff.
+fn handoff(context, st, reply) {
+  print("");
+  print("=== HUMAN NEEDED ================================================");
+  print("  " + context);
+  print("  state  " + st);
+  if (reply != null) {
+    raw = reply;
+    if (type(reply) == "object" && has_key(reply, "reply")) { raw = reply.reply; }
+    lines = split(trim(raw), "\n");
+    start = len(lines) - 20;
+    if (start < 0) { start = 0; }
+    j = start;
+    print("  tail of the reply:");
+    while (j < len(lines)) { print("    " + lines[j]); j = j + 1; }
+  }
+  print("=================================================================");
+}
+
+# Run one pipeline stage. Returns the state word; the caller decides what it means.
+fn run_stage(teamfile, alias, stage_name, prompt_text) {
+  print("  [" + stage_name + "] ...");
+  reply = lm_prompt(teamfile, alias, prompt_text, {});
+  st = state_of(reply);
+  print("  [" + stage_name + "] " + st);
+  if (needs_human(st)) { handoff(stage_name + " on " + teamfile + ":" + alias, st, reply); }
+  return [st, reply];
+}

package/examples/n8n/git-lib.lms

@@ -0,0 +1,93 @@
+# git-lib.lms -- user-defined wrappers around git, in LMScript.
+#
+# No engine module for git: these are ordinary user functions over system(), and any script can
+# import them. The engine owns lmctl's own internals as host functions; everything external is
+# user space -- the same pattern applies to gh, aws, or any other CLI a script wants to wrap.
+
+# NOTE: system() goes through a SHELL and there is no quoting helper, so any subcmd containing
+# | & ; < > $ ` must be quoted by the caller. The failure mode is an EMPTY result, not an error --
+# `--pretty=format:%h|%s` silently pipes into `%s` and returns "".
+# NOTE: system() returns [stdout, stderr] and NO exit status, so these wrappers cannot distinguish
+# "command failed" from "command succeeded with no output".
+fn git_run(repo, subcmd) {
+  out = system(format("git -C {0} {1} 2>/dev/null", repo, subcmd));
+  return trim(out.stdout);
+}
+
+fn is_git_repo(path) {
+  if (!file_exists(path)) { return false; }
+  return git_run(path, "rev-parse --is-inside-work-tree") == "true";
+}
+
+fn git_head(repo) {
+  return git_run(repo, "log -1 --format=%H");
+}
+
+fn git_head_short(repo) {
+  return git_run(repo, "log -1 --pretty=format:%h|%s");   # no space: git_run does not quote
+}
+
+fn git_head_epoch(repo) {
+  s = git_run(repo, "log -1 --format=%ct");
+  if (len(s) == 0) { return 0; }
+  return num(s);
+}
+
+# Changed = tracked-but-modified. Untracked = new and unignored. Kept separate on purpose:
+# conflating them is how "the tree is dirty" stops telling you WHICH kind of dirty.
+fn git_changed(repo) {
+  lines = split(git_run(repo, "status --porcelain"), "\n");
+  changed = [];
+  i = 0;
+  while (i < len(lines)) {
+    l = lines[i]; i = i + 1;
+    if (len(trim(l)) == 0) { continue; }
+    if (!starts_with(l, "??")) { push(changed, trim(substring(l, 2))); }
+  }
+  return changed;
+}
+
+fn git_untracked(repo) {
+  lines = split(git_run(repo, "status --porcelain"), "\n");
+  untracked = [];
+  i = 0;
+  while (i < len(lines)) {
+    l = lines[i]; i = i + 1;
+    if (starts_with(l, "??")) { push(untracked, trim(substring(l, 2))); }
+  }
+  return untracked;
+}
+
+fn git_unpushed(repo) {
+  # No upstream is NOT an error -- a worktree branch deliberately has none.
+  # NOTE: "@{u}" cannot go through format() -- "{u}" is read as a format placeholder.
+  up = system("git -C " + repo + " rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null");
+  if (len(trim(up.stdout)) == 0) { return -1; }   # -1 = no upstream, distinct from 0 = nothing to push
+  n = trim(system("git -C " + repo + " rev-list --count @{u}..HEAD 2>/dev/null").stdout);
+  if (len(n) == 0) { return -1; }
+  return num(n);
+}
+
+# "Are these changes AFTER some LLM process?" -- compare the working tree's newest mtime against a
+# marker time (e.g. when an agent turn started).
+fn touched_since(repo, epoch) {
+  out = system(format("git -C {0} status --porcelain", repo));
+  lines = split(trim(out.stdout), "\n");
+  recent = [];
+  i = 0;
+  while (i < len(lines)) {
+    l = trim(lines[i]); i = i + 1;
+    if (len(l) == 0) { continue; }
+    parts = split(l, " ");
+    f = parts[len(parts) - 1];
+    st = system(format("stat -c %Y {0}/{1} 2>/dev/null", repo, f));
+    m = trim(st.stdout);
+    if (len(m) > 0 && num(m) >= epoch) { push(recent, f); }
+  }
+  return recent;
+}
+
+# Did an agent actually do anything? The question behind every "it says DONE" report.
+fn agent_made_progress(repo, since_epoch) {
+  return len(touched_since(repo, since_epoch)) > 0 || git_head_epoch(repo) >= since_epoch;
+}