Changelog

All notable public-preview changes for @lmctl-ai/lmctl are recorded here.

These docs currently describe @lmctl-ai/lmctl 0.1.248. Run lmctl --version before following command examples.

Docs Site Updates

• Added raw lmtext-skill.md for the lmtext speech-to-text service and wired it into the Docusaurus skills page, raw skills index, and deploy smoke checks.
• Added a raw opencode lmctl Lead skill for the opencode fork's background-job model: use opencode's shell({background:true}) / job surface, know that a background command keeps running after the Lead ends its turn, and keep resubmission explicit — opencode can deliver a notification turn reporting the finished job, but it does not drive the next Lead turn after the process exits.
• Rechecked delivery behavior against lmctl 0.1.248 after the 0.1.241 synchronous-by-default change. Public docs now teach busy receiver = immediate busy error by default, with mailbox queueing retained as opt-in via mailbox_queue_enabled=true or LMCTL_MAILBOX_QUEUE_ENABLED=true. Queue lifecycle pages are bannered as opt-in rather than deleted. The ClaudeMock mailbox drain fixture now exports LMCTL_MAILBOX_QUEUE_ENABLED=true.
• Added a raw Claude Code lmctl Lead skill for harness-specific operation: dispatch every lmctl chat through Claude Code background execution, never timeout-wrap it, wake up and decide the next task on background completion notifications, use Monitor for inbound-mail wakeups only in explicit queue-enabled configs, address cross-repo teams with absolute teamfile paths, and verify liveness evidence before calling a target stuck. Rechecked the referenced command surface against lmctl 0.1.237.
• Rechecked the ClaudeMock mailbox drain fixture against lmctl 0.1.228 after the mock session-store file-lock fix. Three sequential-fire runs and three concurrent-launch runs produced one queued row, no ClaudeMock session not found errors, and CREATE -> ENQUEUE -> MESSAGE_ACKNOWLEDGED after drain. Removed the temporary known-limitation caveat from the page.
• Added a no-cost ClaudeMock mailbox drain fixture verified against lmctl 0.1.227. The recipe uses a throwaway DB, provider=ClaudeMock, delayMs, lmctl mail pending, and relay-loop.pl --once --mode drain to prove CREATE -> ENQUEUE -> MESSAGE_ACKNOWLEDGED without touching the live fleet DB or any real provider API. Rechecked mail pending scope: in 0.1.227 it defaults to SELF in a member session and remains fleet-scoped from an operator shell.
• Rechecked lmctl chat --json against lmctl 0.1.223. Accepted synchronous sends now emit NDJSON: an early status: "accepted" line with message_id, then the final status: "ok" or stalled result with the same message_id. Busy and enqueued outcomes remain one-line JSON results.
• Rechecked public command guidance against lmctl 0.1.218. Top-level help includes status, diagnose, diagnose-prompt, serve, api, device, mail, team, chat, terminal, tail, session, health, recover, ls, lint, seed, hire, refresh, clone, plan, and db. mcp remains directly dispatchable but hidden from top-level help.
• Added manual pages for lmctl mail and for daemon/session inspection: serve start/status/stop and session --query-file.
• Retired the public bridge-install page into a tombstone; delegation docs now teach lmctl chat only.
• Split CLI reference API guidance into current surfaces and legacy compatibility notes. Retired workflow/project-engine API endpoints may still dispatch, but public docs should not teach them as normal current agent workflow.
• Converted same-origin /lmctl/docs/... links that Docusaurus can check into relative Markdown links, and extended scripts/deploy.sh to wait for the /lmctl/* CloudFront invalidation before smoke-checking the live sourceRevision, homepage, Skills docs page, install tutorial, and delegated work verification page. Root-prefix public links that stay outside the Docusaurus build, such as /lmprobe/, /skills/lmprobe-skill.md, and /examples/opencode.json, are now deploy-smoked against the live site.
• Added a Docusaurus /lmctl/docs/skills landing page for newly seeded agents, exposed it in the navbar/sidebar/footer, and linked it to the raw /skills/ files. The page leads with the current delegation contract: synchronous lmctl chat, lmctl chat --json/lmctl status for completion evidence, --prompt-file for safe prompt input, CLI fallback when seed text mentions lmctl_chat even though normal installs do not provide it, and durable-memory as portable working context.
• Added the Lead send-status procedure to the Skills docs and raw Lead skills: run lmctl status before important sends, and after queued sends use lmctl status --since 7d to read Waiting on: / mailbox outbound instead of inferring delivery from exit code 0.
• Expanded the homepage tutorial cards to include Baby steps and Operating teams, and changed the Install & first run handoff to point to Baby steps instead of jumping directly to the older workflow tutorial.

lmctl 0.1.158

• Verified the current help surface and hidden/compatibility caveats. Public agent-facing docs should prefer top-level chat, status, tail, health, lint, seed, hire, refresh, clone, workspace, plan, recover, and troubleshooting commands. chat --run ... --done remains current for answering paused managed runs; do not treat --run as blanket-removed.
• Refresh guidance now uses the current self-only guard observed in source and runtime behavior: a running session cannot refresh itself; refresh the target from a different session, another member, or an operator shell.

lmctl 0.1.157

• Rechecked public command guidance against lmctl --help, lmctl chat --help, and direct unknown-command probes. The public delegation surface remains lmctl chat; no separate agent-facing wake, poll, harvest, or detached delegation command is documented.
• Removed public references to private supervisor tooling. Public docs describe the agent-facing CLI only.

lmctl 0.1.154+

• Verified the current command surface against lmctl --help, lmctl chat --help, and lmctl status --help.
• Documented lmctl chat --prompt-file <path> and --prompt-file - as the safe input path for prompts that contain command examples, backticks, $(...), $VAR, or quotes. Positional prompts are assembled by the caller's shell before lmctl sees them. This guidance is also present in the raw Lead skills because seeded agents may read those directly.

lmctl 0.1.151+

• Added model-routing version-floor guidance. For routed model= teamfiles, use 0.1.151 or newer and verify the post-seed MODEL column with lmctl health <teamfile.lmctl>.
• Added 0.1.151+ status visibility notes for queued-mail troubleshooting. Waiting on: keeps old undelivered mail visible so old queued work does not disappear behind recency caps.

lmctl 0.1.129+

• Removed stale removed-flag and wake-loop guidance from the public manuals and skills. The current agent-facing delegation path is normal lmctl chat.

lmctl 0.1.125+

• Documented team/SELF scoped lmctl status: it resolves identity from LMCTL_SELF_SESSIONID in member sessions, reports team/member state and mailbox lanes, and does not take --project or --web.

lmctl 0.1.122+

• Added a known-issue note for current seed text that mentions MCP lmctl_chat. Public guidance remains the CLI: lmctl chat <teamfile> <alias> "task".
• Clarified that private supervisor tooling is outside the public agent-facing lmctl command surface.

lmctl 0.1.116+

• Documented the chat command as the live Lead delegation primitive: it is synchronous, blocks for one member turn, and returns the member reply when the receiver is idle.
• Documented that lmctl is agnostic to foreground/background execution; providers, runtimes, shells, harnesses, and supervisors own wake and concurrency.
• Retired the historical 0.1.103/0.1.113 wake-loop docs. Those commands are not in the 0.1.116 help surface, and no extra supervision command is documented as an LLM-called command.

lmctl 0.1.100+

• Clarified the then-current queued-member-mail delivery model: lmctl chat to a busy receiver enqueues when queueing is enabled, and the next lmctl chat from that same sender to that same receiver delivers that sender's queued lane plus the new message once the receiver is free. A live lmctl terminal lock is a valid busy state, so queued mail waits until the human exits the terminal. If the sender goes idle waiting for the queued reply, this is deadlock, not latency.
• Verified queued delegation guidance and documented the machine-readable lmctl chat --json queued contract: status: "enqueued" with path: "enqueued". Exit code 0 alone is not a delegated-work completion signal.
• Corrected busy queueing language from shell/member context to sender identity: calls with sender identity can queue for a busy receiver; calls without sender identity have no lane and return busy instead.
• Clarified that exit 1 from lmctl chat can be busy or a real error; use --json or the message text to tell retryable busy from non-busy failures.
• Added the concise queue lifecycle: queued -> in-flight -> delivered with receipt. Delivery is at-least-once, so a duplicate delivery can happen after a crash, but queued work should not be lost.
• Superseded the 0.1.89/0.1.90 receiver-pull queue flow with the sender-driven model.

lmctl 0.1.95+

• Documented the 0.1.95/0.1.96 identity cleanup. Old explicit identity flags are not current public command forms; member-run commands infer identity from LMCTL_SELF_SESSIONID, direct lmctl chat <teamfile> <alias> "<prompt>" works flaglessly from an operator shell, and manual self-identity invocation is explicitly experimental at /lmctl/docs/manual-invocation.
• Added /lmctl/docs/mcp-manual-install for the optional lmctl mcp bridge. lmctl no longer installs or relies on MCP by default, and stale cleanup is shape-gated to entries named lmctl/lmctl0 that actually invoke lmctl MCP.
• Noted that debug output is written to ~/.lmctl/debug-*.log, not terminal output.
• Historical note: 0.1.91 documented an interactive first-return primitive over the caller/team scope. This is not current guidance.
• Historical note: older Lead fan-out guidance used tracked background invocations and scoped wake primitives. This is not current guidance.
• Removed the top-level lmctl init command. Provider setup is documented in the Install & first run tutorial; lmctl reports a missing provider or credential at use time (seed/chat).
• Retired public guidance for the static _CONNECT_ cross-team statement and the lmctl connect command. Cross-team calls now work automatically at runtime, with automatic cycle protection. Legacy _CONNECT_ lines are ignored with a lmctl lint deprecation warning.
• Added provider=opencode model-effort selection with _MEMBER_ ... model=<id> effort=<variant>.
• Added managed opencode provider entries for GitHub Copilot, DeepSeek, and OpenRouter-backed Qwen models.
• Added examples/opencode.json as a copyable opencode provider/variant sample.
• lmctl lint now warns when effort= is used outside provider=opencode, opencode effort= is set without model=, or ~/.config/opencode/opencode.json is missing while still accepting lmctl-managed model ids.

Provider Effort Support

Provider	effort= support
opencode	Supported through opencode variants.
claude	Native CLI has --effort, but lmctl has not wired _MEMBER_ effort= to Claude yet.
codex	Codex exposes effort-like config through native settings; lmctl has not wired _MEMBER_ effort= to Codex yet.
agy	No verified effort flag in agy --help; only --model is currently supported by lmctl.