menu_bookRunner documentation

Everything the runner does, in detail

The feature list and the CLI reference come from the catalog the runner publishes with each release, the changelog from its releases on GitHub. Below them, the technical detail: quota, context overflow, concurrency, logs, bug reports, models, self-update and project maintenance.

arrow_backBack to the runner overview
buildKey features

What the runner handles on its own

Each feature as the runner itself describes it in the catalog it publishes with every release.

From an assigned task to a merged pull request

since v0.1.0

The runner takes the tasks assigned to you on mcptask.online one after another. Triage rates each task first and picks one of three model tiers for it; then the coding CLI works it through on its own branch — code, tests, push, pull request, CI. In auto-squash modes the runner merges the pull request itself once CI is green and checks that the merge really happened; in manual modes the pull request waits for a person. Effort and progress are logged back to the task as it goes.

One failing task does not stop the day

since v0.3.22

A task that fails, turns out to be out of scope, or was already started by somebody else is set aside and the loop moves on to the next one. After a while the set-aside task may come back for another attempt, a limited number of times a day, so a passing hiccup does not cost it the day and a genuinely broken task is not paid for over and over.

Surviving a full context window

since v0.1.0

When the coding CLI's context fills up, the session is lost but the work is not — it is a branch with commits on disk. The runner restarts the CLI in a fresh session with its last few actions, and if that runs out of room too, it leaves a short handoff note for the next run: the branch, the commits, the uncommitted files and the unfinished plan, with a reminder to spend context carefully. A task whose pull request is already open counts as delivered, not as an error, and a resumed task runs on the strongest model tier.

A daily budget it reads, never guesses

since v0.1.0

How much work is left for today comes live from your mcptask.online account, and the runner checks it before a task, between tasks and every few minutes during one. When the budget is spent the work stops; the pr_only and today_auto_squash modes end the day there, while daily sleeps until the next business day and starts again. An optional end of the working day stops new tasks at a set time, and an outage of the quota service is told apart from a spent budget and reported as a bug.

Watchdogs for a stuck or spinning run

since v0.1.0

A watchdog follows the coding CLI's output as it streams. It stops a run that has made no progress for too long or a command that hangs, and it recognises a run spinning in place — the same edit failing again and again, the same failing command, the same steps repeated — while leaving long CI and test waits alone. The task stays in progress and is picked up again later on the strongest model tier.

An unrelated urgent bug becomes its own task

since v0.1.0

When the coding CLI runs into an urgent bug that has nothing to do with its task, the work in progress is committed and pushed, the bug is filed as a new urgent task, and the runner fixes that bug first — even after a restart — before it returns to the original task. When uncommitted changes keep the runner from switching to main for it, the dashboard card names the bug, the branch and the directory, and the runner waits until a person has committed, stashed or discarded them; then it starts the bug by itself.

One test suite at a time on a shared machine

since v0.1.0

The test and CI helpers the runner installs share one machine-wide lock, so two agents — or two projects — never run their suites side by side and slow each other into timeouts. A second suite waits for the first, and a lock whose owner is gone is reclaimed on its own. On top of that, one checkout never has two runners working in it at once.

A crash files its own bug task

since v0.1.0

When a run ends in an error, a crash, or a broken guard of the runner's own, the runner files a bug task on mcptask.online with the run log, the tail of the CLI's output and its configuration files with tokens removed attached. Identical failures are recognised and filed once, and a spent quota or a task reassigned to someone else files nothing. The one failure it cannot report is a token it cannot use: a missing one shows in the exit code and the log, and a token whose reports mcptask.online refuses shows on the dashboard card too, with what to fix, while the runner keeps working. A situation the runner does not handle yet is one bug across all machines: it is recognised by where in the runner it happened rather than by its wording, a later occurrence anywhere is added to the open bug as a message (machine, runner version, how often), and one that comes back after the bug was closed files a new bug marked as a regression of it.

See what a run is doing, live and afterwards

since v0.1.0

Every run of the coding CLI gets a JSON run log that is opened the moment the CLI starts and refreshed while it works, so even a hung or crashed run leaves its state on disk; a process-wide log records everything else. While a run is in flight, a live card on mcptask.online shows its state, task, model and progress. Watching never stops a run: a dropped update costs freshness, not the result.

Updates you decide on, adopted without a restart

since v0.2.0

update --self installs the latest release after checking it against the published checksums, and puts the old binary back if the swap fails. The runner never upgrades itself — at the start of a run it only mentions that a newer release exists. Once you have installed a new binary, a long-running loop switches to it between two tasks, and daily switches on its way into the overnight pause, so an unattended machine does not keep running an old version.

Story branches — a whole Story in one merge

since v0.3.35

On unless a host opts out. The tasks of a Story each get their own branch and merge into a shared Story branch instead of the main one; the Story's last task merges the Story branch into main, so the main branch receives finished Stories rather than half of one. The runner names the branches itself and decides where each task starts, so the agent never has to guess. Manual modes never create or merge a Story branch.

A finished Story reaches main on its own

since v0.3.37

A Story whose every subtask is done gets merged into the main branch even when the task that finished it was worked in parallel, on another machine, or on one that does not use Story branches. Right after such a task, and between tasks in the auto-squash modes, the runner looks for finished Stories whose branch is still open and runs the Story's merge on its own — gate, pull request, host checks, merge. It then checks the repository itself, and a Story that still did not make it is reported as a bug, once.

Claude Code, Codex CLI or OpenCode

since v0.3.24

Each project chooses the coding CLI that drives it, once, with init --cli; the choice lives in a per-machine file, so two developers on the same repository can use different CLIs. The work loop, the watchdogs, the dashboard card, the effort log and the bug reports are the same whichever CLI runs. There is no default: a project that never chose is refused by name, and you can add a profile of your own.

Pull requests on GitHub, Bitbucket Cloud and GitLab

since v0.3.25

One command, mcptask_runner pr, opens, reads, checks and merges pull requests on whichever of the three hosts the repository is on, so the same instructions work everywhere. Before an auto-squash merge the runner asks the host for its CI verdict: a failure leaves the pull request open, a pipeline still running is waited for, and a repository with no host checks falls back to the project's own local gate.

Your own models, on a backend of your choice

since v0.1.0

The three model tiers resolve to whatever the harness profile names unless the project pins its own models. Together with a launcher command — local Ollama is the usual example — the coding CLI can run against a backend other than its vendor's. Pin all three tiers or none: a tier left unpinned asks that backend for a model it has never heard of.

A weekday job on macOS, Linux and Windows

since v0.1.0

init generates a scheduled job that starts the runner every weekday morning — a LaunchAgent on macOS, a systemd user timer on Linux, a Task Scheduler job on Windows — at 08:00 unless you pick another time, and on Monday to Friday unless you pick other days, weekends included. It does not switch the job on: starting something that spends a quota every morning stays your decision, and init prints the one command that does it.

A crash or a reboot does not cost the rest of the day

since v0.3.38

The scheduled job also starts when the system loads it — at login after a crash, a reboot, a logout or a power cut — and then works only if the day is under way: a scheduled day, past its start time and before the end of the workday. A login in the evening or at the weekend starts nothing. On macOS the job is loaded at login, so after a power cut the runner comes back when somebody logs in, or at boot with automatic login on.

A task cannot stop the runner that is working on it

since v0.3.39

A task written for a person — "restart the runner so it reads the new setting" — must not be carried out by the runner on itself. With Claude Code, the runner checks every shell command before it runs and refuses one that would stop, restart or remove the runner or its scheduled job; the agent is told why, the task is set aside for the day as out of scope, and a bug piece names the step a person has to do. With Codex and OpenCode the runner spots the command as it starts and recovers from the stop signal it sends, though not from a forced kill.

The dashboard card keeps up with the work

since v0.3.40

Every step the agent finishes is ticked off on its TODO list first and logged to the task second, so the card on the dashboard moves while the work does. With Claude Code the runner holds the agent to that order: a progress log with no step closed since the previous one is refused once, with the exact call to make, and a retry is accepted so the work record is never lost over the card. The closing log is never refused, and the run log notes any log that went out with the card behind it.

The runner works only pieces assigned to its own user

since v0.3.41

Before it starts work on a piece the queue offered, the runner checks whom the piece is assigned to. A piece given to somebody else, or to nobody, is not worked: no agent session starts, the run log names both users, the piece is left alone for the rest of the day, and a bug piece reports it. Pieces the runner has set aside are also left out of every later question to the queue, so they are not offered to it again.

A missing or expired CLI login pauses the runner instead of ending its day

since v0.3.43

When the coding CLI's login expires, or the CLI was never signed in at all (after a logout, on a fresh machine), the runner stops picking work and waits instead of ending the day. The dashboard card names the machine and says how to sign in; for Claude Code that is `claude` and then `/login` in a regular Terminal on that machine, for Codex `codex login`. The runner checks again after every short wait, and it clears the card and resumes by itself once the login is there. It also checks at startup, so the card shows the problem before any work is attempted.

Stop and start the coding CLI from the dashboard

since v0.3.44

The runner card has Stop and Start buttons. Stop now ends the running CLI at once and leaves the task in progress with its branch untouched; Stop after the task lets the current task finish and takes no next one. The runner itself keeps running and keeps the card fresh, and Start resumes work, picking the stopped task up again. The pause lasts until Start or until the runner restarts. While the runner waits for a problem on the machine to be fixed, the card shows Re-check now, which checks at once instead of at the end of the wait; the button leaves the card the moment it is pressed and comes back only if the problem is still there. On the task that installs the runner it also tries that task again.

Whatever stops the runner is on its card, and a CLI that cannot start is waited out

since v0.3.46

When the coding CLI cannot start on the machine — the binary is gone, it is half-way through an update, its usability check fails — the runner no longer ends its day. The dashboard card says what the CLI reported and what to do on which machine, the runner tries again after every short wait, and it clears the card and resumes by itself once the CLI starts. Whatever else ends, pauses or holds up a run — a failed task in a run for one named task, a budget nobody could read, a situation it does not handle yet, the work window closing — leaves its reason on the card too, and a configuration the runner refuses to start with is published to the card before it exits.

workflow — tasks, and the review comments on your pull requests

since v0.3.46

A scheduled mode between pr_only and today_auto_squash. The runner works the tasks assigned to you and waits for new ones like the other two; after every task, and whenever the queue is empty, it looks at your open pull requests. One where a person asked for changes or commented after the last push gets one run: the fix, a push, CI, and a reply under each comment — "Addressed in <commit>" or "Not addressed" with the reason. Bots are ignored, nothing runs when nobody wrote anything new, and nothing is ever merged: a person merges, even an approved pull request. Works on GitHub, GitLab and Bitbucket; on the last two a bot is recognised by the host's own marking or a bot-like account name, so a CI account with a plain name counts as a person.

A machine that refuses the work is waited out, not ended on

since v0.3.47

When a task cannot finish because the machine refuses something it needs — a database that is not running, an SSH agent with no key, a git host refusing the machine — the coding agent says whether it is the machine or only this task. A task-only problem sets that task aside and the runner moves on. A machine problem goes on the dashboard card with the agent's own words and what to do, and the runner waits: it re-runs only a small check the agent proposed, backing off between tries, and retries the task once the check passes — without a restart. A second task refused the same day counts as the machine either way.

Three scheduled modes — pr_only, workflow, today_auto_squash

since v0.3.47

All three work the tasks assigned to you, wait on an empty queue and end the day at end_of_workday_hour, when the day's hours are spent or when the dashboard stops the runner. pr_only opens a pull request per task and leaves it: no merge, no review handling (today is its old name). workflow does the same and also works in new human review comments on your open pull requests, still without merging. today_auto_squash merges each pull request itself once CI is green and does not read review comments.

A step only a person can take becomes that person's task

since v0.3.49

When a task cannot go on without a person — a sign-off, an approval, a step on a server, a decision — the coding agent creates a task for that person: assigned to the author of the waiting task (or the project's boss), naming the exact step, and blocking the waiting task until it is finished. The runner leaves the waiting task alone until then, across days and restarts, files only one such task per waiting task, and picks the waiting task up again once the person is done. If the task cannot be created, the agent leaves the step as a comment and the runner files a bug report about it.

An mcptask.online outage is waited out, not ended on

since v0.3.49

When mcptask.online does not answer — a deploy, a proxy answering 502, a dropped connection — the runner no longer reads the error a task or a triage ended on as a failed task. It asks the server itself, and while the server is down it says so on the dashboard card, starts no work, checks again every minute until the end of the work window, and carries on by itself once the server answers. Nothing is filed about the outage: it is the server's, not a defect of the runner or of the project. An error while the server answers ends the run as before.

A triage that cannot reach its tools is waited out

since v0.3.49

When the coding CLI cannot reach the mcptask-online MCP server while mcptask.online itself answers — a broken .mcp.json, a token the server rejects, tools the CLI does not allow — triage cannot pick a task. The runner no longer ends its day over it: the dashboard card names the problem and what to check on which machine, one report is filed for the incident, and the runner runs a fresh triage after every short wait until the end of the work window, clearing the card once a triage picks a task.

Git credentials origin refuses are waited out, not reported

since v0.3.49

When origin refuses the machine's git credentials — an SSH key no longer in the agent after a reboot, an expired HTTPS token — the runner no longer files a bug report for every git call that meets it. It says so on the dashboard card with git's own words and the fix (load the key with ssh-add, or refresh the stored credential), starts no work, checks origin again after every short wait, and carries on by itself once origin answers. A task whose push met the same refusal is run again afterwards instead of being set aside. Other git errors are reported as before.

A usage limit that outlasts the runner's waits is waited out, not ended on

since v0.3.49

When the coding CLI's usage limit is still spent after the runner's own waits of about three hours, the runner no longer counts it as a failed task and ends its day. The dashboard card shows the limit in the CLI's own words and, when the CLI says when it resets, that time. The runner waits until then — or checks again after every short wait — never past the end of the work window, and carries on by itself once the limit has reset. Nothing is filed about it. A hard cap with a date on it still ends the day.

An install you can read

since v0.3.49

init asks its questions, shows every warning and error, and ends with a few lines: what is true now, how to watch the runner, how to switch it off. Everything else it has to say goes to a log file of its own, kept for you alone, whose path is the last line on the screen. The password is never in it. --verbose prints the whole of it as well.

A situation the runner does not handle yet is reported and retried, not ended on

since v0.3.50

A runner that works the queue all day no longer ends its day over an error nobody planned for, a task that ended in error, or a crash in its own code. It files one bug about the situation — one across all machines — and shows it on the dashboard card in plain words: what happened, where the report went ("Reported as bug #N", "Already reported as #N at HH:MM", or why it could not be filed) and when it tries again. Then it waits a short while and tries again; once a round goes through, the card clears by itself. Re-check now on the card tries again at once, and Stop on the card pauses the runner. The retries are bounded: a task that fails twice in a day is set aside until tomorrow, the same failure after three paid runs holds further runs for it until tomorrow, a new runner version or Re-check now, a step that costs nothing backs off from five minutes to an hour, and a problem of the machine itself — a usage cap, a refused account, a computer that cannot start the coding tool — is one wait rather than a queue emptied task by task. A situation that keeps coming back for two hours or four tries adds one message to its bug, and the card says since when no work has been done. These counts survive a restart or an update within the day. After a crash the runner first stops the coding tool it was running and reads the project's checkout, which it leaves as it is; if it cannot confirm either, it ends and says why. The day still ends for the reasons it always did — the work window, the budget, a stop — and a run started for one named task or Story still ends on its error.

A machine that cannot start processes is one waited-out condition and one report

since v0.3.53

When something else on the machine fills its process table — a git hook that keeps calling itself, say — nothing can be started there, and the runner used to read that four different ways and file a bug report for each project. Now it is one condition on the dashboard card, naming the machine and how to find what holds the processes. No model run starts while it lasts; the runner checks by really starting a process after every short wait and carries on by itself once one starts. Every runner on the machine together files one report, with the machine's process limits in it and, once processes start again, the commands that had the most copies.

Start now ends the wait for the next look at the queue

since v0.3.53

While the runner waits before it asks the queue again — the queue was empty, or held only set-aside tasks — its card shows Start now. A click ends the wait, and the runner asks the queue within seconds and takes what you just assigned. If there is still nothing, the card says when it asked and when it looks next. The click changes nothing else: it lifts no pause and starts no model run the next look would not have started. Waits that a click cannot shorten show no button: the night, the end of the work window, a spent daily budget and a usage limit with a known reset time.

new_releasesChangelog

What's new in the runner

The release notes of every runner version, as published on GitHub. The newest three are open; the rest are one click away.

v0.3.53

Upgrading

Upgrading takes two commands. mcptask_runner update --self replaces the binary; then a bare mcptask_runner update in every project on the host, because the bundled .claude/ assets changed (skills/memory-search/SKILL.md). Run it while no runner is working that checkout. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.53 carries this binary; no wrapper changes.


Start now on a runner waiting for the queue (#15160)

While the runner waits for its next look at the queue (an empty queue, or one
holding only set-aside tasks), the snapshot now carries recheck together with
a new member, recheck_kind: "queue". The card (mcptask.online
#15159, already deployed) draws
"Start now" for it. A click ends the wait and the runner asks the queue at once.
If the queue still has nothing, the card says "Asked the queue at HH:MM on Start
now — nothing to take" with the time of the next look. The click lifts no pause,
resets no back-off and starts no model run that the next look would not have
started. A usage limit whose reset time the CLI stated no longer offers the
re-check button: a re-check before the reset only meets the limit again.
schema_version is unchanged. No action needed.

Optional models.last_resort level (#14990)

The tier table can now carry a fourth, optional level, last_resort. The claude
profile declares claude-fable-5-2; codex and opencode declare none. Nothing
uses it yet. A host models: section that does not name it has no such level.
No action needed.

init and update start git less often (#15157)

The install read HEAD and the current branch with their own git calls, after
git status had already said both. It now takes them from the status headers
(--porcelain=v2 --branch). On Windows, where every git start costs about
40 ms, a run of the package's tests starts about 430 fewer processes (3,224 to
2,796). Nothing to do; behaviour is the same.

memory-search skill: note IDs and ratings (#15148)

The bundled memory-search skill now searches through
mcp__llmmn-production__SearchNotesTool instead of curl, prints each note's
ID, rating and date, and rates the notes it used (+1 right, -1 with a reason
when wrong or outdated). It no longer needs LLMMN_TOKEN in the environment.
Hosts get it with mcptask_runner update.

A machine that cannot start processes is one condition and one report

On 2026-11-11 a git hook in another checkout called itself in a loop and filled
one Mac's process table for two hours. Every process the runner tried to start
was refused. The runner read that as four different problems: a CLI that would
not start, a project with no origin remote, a preflight it could carry on past,
and a story sweep that could not list origin. It filed eleven bug pieces, one per
project and per reading. Its re-check passed while nothing could fork, and let a
paid run start (#15150).

  • One condition on the card, host_cannot_fork. It names the machine and how to find what holds the processes. It is raised whichever step met the refusal: the CLI's launch, the auto-squash preflight, or a read of origin. The story sweep files no anomaly over it.
  • The re-check starts a real process, the runner's own binary, without a shell in front of it. No model run starts until a process does.
  • One report per machine. The incident is filed without the task or the project in its key. Its throttle state lives in ~/.mcptask, so every runner on the machine files one piece between them. The piece carries the process limits, read without starting a process. Once processes start again, a count of this user's processes by command is added to it.
  • Windows is recognised in its own words. CreateProcess's out-of-memory, system-resources, commit-limit and quota codes count, because a Windows machine never answers with EAGAIN.

Nothing to do on upgrade.

Claude Code 2.1.322's expired login waits on the card, and a refused triage keeps the CLI's words

From 2026-11-12 Claude Code 2.1.322 words an expired login as Failed to
authenticate: this login reached its time limit and cannot be renewed
. The
claude profile did not know that sentence. On one Mac every triage was then an
unnamed api_error: the card read "Triage completed but no task_id returned",
three bug pieces were filed and model launches were held, and nothing on the
card said to sign in (#15151).

  • The sentence is harness_login_required. The runner puts the login on the card, waits, re-checks with the login probe and resumes by itself, filing no bug piece and counting no retries.
  • The remedy names claude auth login, the command the CLI itself names, run in a regular Terminal on that machine; claude, then /login, is still given for an older CLI.
  • A refused triage keeps the CLI's own sentence. Any API refusal (a hard cap, a refused account, a retired model, or one nobody has named yet) leaves triage as the engine reported it. The runner no longer replaces it with "no task_id returned", and no second triage in the same round is launched against the same refusal.
  • The login probe's warning log shows the end of the CLI's output, where the refusal is, instead of the beginning, where settings warnings hid it.

On upgrade: run mcptask_runner update --self on every host with Claude Code
2.1.322 or later. A host that overrides the claude profile adds
login reached its time limit to its own failures.login_required list.

A permission refusal from mcptask.online for one piece is not the machine's

On 2026-11-12 AddAttachmentTool answered Access denied … authorization_error: true for one piece. The child
handed the step over correctly and also reported host_refused, so the runner filed a bug piece for a machine
that was fine. The prompt now says such a refusal is out of scope with the hand-off, never a host refusal; and
a host_refused whose message carries the literal marker authorization_error: true is set aside as the
task's — no host wait, no bug piece. Nothing else in the message is read. Nothing to do on upgrade.

A task that failed twice on genius gets one last_resort run (#14991)

A task that fails twice in a day in a situation the runner does not handle is
set aside for the rest of the day. When the second failure was on genius, and
the host's model table names models.last_resort, the task now gets one more
run on that model the next time triage picks it. After that run it is set aside,
whatever the run ended in.

  • Once per task per day. The grant is kept in the retry ledger, so a restart neither forgets it nor grants a second one.
  • Inside the existing caps. A failure that belongs to the machine is not counted toward it. The run counts as one of the three paid attempts after which model launches for the same failure are held.
  • No level, no run. On a host whose table does not name last_resort (codex, opencode, or a host models: section without it) the task is set aside as before, with one log line saying the level is not configured.
  • Triage still never recommends the level, and a pinned urgent bug is not escalated to it.

Nothing to do on upgrade.

The card says when a run is the last-resort one (#14992)

The snapshot gains an additive escalation member: {level, reason} while a
task runs on the last_resort level, null on every other run and on an older
binary. schema_version is unchanged; the card's model member already
carries the last-resort model id. No action needed on a host.

The card side is mcptask.online task 15221.

The last-resort run is tested end to end (#14993)

Story #14988 is closed by tests rather than by new behaviour:

  • A conformance scenario, 40_last_resort_run_after_two_failures_on_genius: a runner that starts with a granted last-resort run in its ledger — what a restart after the second failure on genius reads — launches the task on the profile's last-resort model, keeps the level out of the prompt, and sets the task aside after the run. On codex and opencode the same ledger meets "not configured" and the task runs on genius. Scenarios can now seed that ledger with a retry_ledger: section (Go only; the gem has no ledger).
  • A host-configuration matrix against the real bundled profiles: the claude profile with no host models: escalates to its own id; a host models: with three levels (the local-Ollama shape) never escalates and never launches a model it did not name; a host naming its own last_resort gets that id, including through ollama launch's --model; codex and opencode never escalate.
  • The prompt guard now refuses the level's name and every bundled last-resort model id in any prompt, and the stress day checks that the card shows the escalation exactly when there was one.

Nothing to do on upgrade.

A script run takes away the temp file a killed save of init's answers left (#15342)

init at a terminal saves the answers given so far in
tmp/mcptask_runner/init_state.<user>.json, so an interrupted install can be
continued. A machine that went down in the middle of the very first save left
no state file, only that save's temp file beside it — the same answers under
another name. A later run with nobody at a terminal sets saved answers aside
unread, but it looked only for the state file and so left the temp file where
it was, for good: the directory is ignored by git, so the install's own sweep
of abandoned writes never saw it.

Such a run now removes those temp files too and says so in the install log.
Found by the noon stress sweep (seed 217809009).

Nothing to do on upgrade.


Changelog

Other

  • b632d1373790e0cd71776dd59ed95ea0535e20e4 CI: the gem is checked out with a read-only deploy key
  • 7a2d0f96ab0f112bbe274b4a4d1c55b889989d3f [#14990] Optional fourth model level last_resort in the profile and host models tables (#28)
  • b3aa0b813d05ef837d36be0d315752946a773b3d [#14991] Second failure on genius gets one last_resort run before the task is set aside (#34)
  • 0d0d9da50a25abb1b5085a563d20599a7dac3d5c [#14992] Show a last_resort escalation on the runner card (#38)
  • c4b9562a31f162d37d1f4edf0db3a68d03baef5d [#14993] Test the last_resort escalation end to end (#39)
  • cbe3178c6b5a9e1fc3a88a5024ff7bca220451d0 [#15023] internal/install: one template host per binary, one for-each-ref for the base (#29)
  • 2e24a8ca0223d66f429c70bfecb1fb75045f66cc [#15148] memory-search skill returns note IDs and rates used notes (#35)
  • 6d10dc4b96301f68cbbfcc875d86cf822232e68b [#15150] A machine that cannot start processes is one host condition, re-checked by a real fork, reported once per machine (#31)
  • 89dec8e234271f43f82971e62587a71e51d69f1a [#15151] Claude Code 2.1.322's "login reached its time limit" is login_required; a refused triage keeps the CLI's own sentence (#32)
  • a4e4c0b9f751c13ac405d616be314d314d72878b [#15152] An authorization refusal from mcptask.online for one piece is not host_refused: prompt says so, no runner bug is filed (#33)
  • 312f2a372cf8ef7db4efe9346255ce931258b705 [#15157] internal/install: read HEAD and branch from the v2 status headers (#36)
  • 0beafc18ccf658f81bb578c9a157e7f990fd05c2 [#15160] Start now on the card ends the wait for the next look at the queue (#41)
  • 13bb4f9c41c66aa56d4a8ee9d29ebd8d512ff903 [#15161] CI cost: cheap Linux jobs per change, full matrix nightly and before a release (#30)
  • 039e4da3d9bb9b33790b78a990824a13008b7e85 [#15162] bin/ci runs the Linux tests with the race detector in Apple's container on a Mac (#42)
  • e08d9303fa3aab00d78082f25190129b1698a479 [#15176] internal/install: run the package's tests in parallel (#37)
  • a597afc4b6000c236268028d717d8f951a191794 [#15342] A script run removes the temp file a killed save of init's answers left
  • 9bff4a16fdf60901a17de13d56e25e25ea381247 [#15772] Install day: a key's foot comment is counted with the key after it
  • 5f37756427f6ebe35ba5ac95eab990beba1f169d docs(release): v0.3.52 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.52

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.52 carries this binary; no wrapper changes.


Waiting on a background command no longer freezes the card or kills the run

An agent that started a long command in the background, usually bin/ci, and
then waited for it to finish had nothing running as far as the runner could
tell. After three minutes the card said FROZEN ("No stream activity"). After
twenty minutes the runner killed the agent for inactivity, before a suite that
long could finish, and the task started over
(#15123).

  • A background command is now running until it ends. Claude Code announces such a command as backgrounded. The runner keeps it on the card and in the watchdog's view until the notification that it finished, so the wait is shown as the command running, with the same time limits as the same command run in the foreground.
  • A call that failed is still closed at once. An error result means nothing was left running.

Nothing to do on upgrade.


Changelog

Other

  • 1158a7ea3659806113f68f57721794d64372d004 [#15112] The whole gate before a merge: gem drift, install day and release notes on every PR (#27)
  • 53438bb68c6350136b3ae3d099b75372d197c5d8 [#15123] A background command runs until its notification, not its result
  • b74715d4815be348cb1f6b450e5e2804f6541eb8 docs(release): v0.3.51 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.51

Upgrading

Upgrading takes two commands. mcptask_runner update --self replaces the binary; then a bare mcptask_runner update in every project on the host, because the bundled .claude/ assets changed (baseline_permissions.json, skills/attach-pasted-image/SKILL.md, skills/mcptask-write/SKILL.md, skills/memory-search/SKILL.md, skills/pr/SKILL.md). Run it while no runner is working that checkout. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.51 carries this binary; no wrapper changes.


Every variable the MCP configuration names is asked for, and named on the card

A project's MCP file can authenticate a server of its own with a variable — jchsoft8's
.mcp.json sends Bearer ${LLMMN_TOKEN} to LLM Memory Notes. On a machine without that
variable the coding CLI sent an empty credential, the server refused it, and the run
ended host_refused after it had been paid for
(#14973).

  • The runner checks before it spends a run. Before every round, the first one included, it reads the variables the selected CLI's own MCP file names — ${NAME} in .mcp.json, bearer_token_env_var and env_http_headers in .codex/config.toml, {env:NAME} in opencode.json — and when one is not set in its own environment it starts nothing. The card says, for example, "LLMMN_TOKEN named in .mcp.json (server llmmn-production) is not set on this machine — run mcptask_runner update here to enter it", and the runner waits and re-checks like the other conditions a person fixes at the machine. No bug piece is filed, and no other variable's value is ever used in its place. The mcptask.online token keeps its own path: a missing one is still a refusal to start.
  • init and a bare mcptask_runner update ask for each one that is unset, on a terminal, naming the project, the file, the server and who issues the value, and read it without echo. macOS and Linux store it as one export file per variable in ~/.mcptask_env.d (the scheduled job's launcher sources it); Windows stores it as a user environment variable. An existing file is never overwritten. Without a terminal nothing is asked, and the missing names are the red line at the end.
  • A waiting runner picks the value up by itself. The re-check reads the variable's own export file (on Windows, the user environment) and goes on — no restart.

Upgrading

Run a bare mcptask_runner update once per project on each host, from a terminal, to
be asked for any variable that machine is missing. On Windows, if a scheduled run
started afterwards does not see a value entered there, sign out and back in once.

A project's own steps before and after every task

A project can now declare what its agents do before a task and after it — consult a
knowledge store, read a decisions log, record what they learned — and the runner puts
that text into every task's prompt as numbered steps, for claude, codex and opencode
alike (#14985).

  • Two optional keys in config/mcptask_runner.yml: work_steps.before (after the task is fetched, before any code is read) and work_steps.after (after the suite is green on the re-run, before the push). Both reach every mode that works a task, in the first prompt and in the continuation of an interrupted one.
  • The runner relays and does not interpret. The text goes in verbatim; the runner adds nothing, knows nothing about what it names, and never checks the step was done. A step the agent cannot carry out is said in the work log and does not cost the task. An absent slot leaves no trace: a project that declares nothing gets the same prompt as before.
  • init asks, at a terminal, with an example. No answer means no slot; update leaves an existing declaration alone.
  • The Claude Code prompt no longer says to skip /memory-search. A project whose CLAUDE.md said "search the notes first" got the opposite from the runner. What a project consults is now its own work_steps text.

An example, not a default

A jchsoft project that keeps LLM Memory Notes might write the following. The runner
ships nothing like it; it is only what a project MAY write. It names the REST search
the memory-search skill runs, because that call works from a headless run's main
session too:

work_steps:
  before: |
    Search LLM Memory Notes (memory_identifier from CLAUDE.md) for the area this task
    touches: curl -fsS -X POST https://llm-memory.com/api/v1/search
    -H "Authorization: Bearer $LLMMN_TOKEN" -H "Content-Type: application/json"
    -d '{"memory_identifier":"<id>","query":"<topic>","limit":3}'
    Read what is relevant before you change any code.
  after: |
    Store a note in LLM Memory Notes about what this task decided or discovered that
    the next task will need — not a summary of the diff.

Upgrading

Nothing to do. To add steps to an installed project, write the keys into
config/mcptask_runner.yml (a | block takes several lines); they apply from the
next task.

The scheduled run sees the tools your terminal sees

The scheduled job starts through a bash -l launcher, and a login bash reads neither
~/.zshrc nor (on Debian and Ubuntu) the interactive part of ~/.bashrc — exactly
where rbenv, asdf and mise activate install themselves. On a zsh host the coding CLI
therefore found the system Ruby, and agents spent dozens of commands working around it
(#14976).

  • The run measures your login shell's PATH. At its start it asks the login shell named in the user database (dscl on macOS, getent passwd on Linux — not $SHELL, which launchd and systemd often leave unset), interactive and in the project directory, and puts in front whatever the job's PATH lacks. One log line names what was added; a measurement that fails or takes over 15 seconds is said in the log and the run continues on the launcher's PATH. fish and nu are not measured, and the log says so. Windows is not measured: PATH there comes from the user environment.
  • The launcher sources ~/.mcptask_env.d itself. Variables stored there no longer depend on which rc file the login shell reads; before, only MCPTASK_TOKEN reached the job, because the job file carried it.
  • Harness note. The fix acts on the environment of the coding CLI's process. A CLI that runs each agent command through a login shell of its own lets macOS's path_helper put the system directories back in front of the shims; the shims are then on PATH but behind /usr/bin. Claude Code reuses the PATH it was started with.

Upgrading

Run mcptask_runner update in each scheduled project. It adds the sourcing block to the
launcher and sets its shebang back to #!/bin/bash -l, including a launcher hand-edited
to #!/bin/zsh -l as a workaround. No reload of the job is needed: the launcher is
read at every start. init and update print in red when this host's login shell
cannot be measured, with the reason.

An install refused at the push recovers once write access is granted

On 2026-11-09 a new developer's install of jchsoft8 met a GitHub account that could
read the repository and not push to it. The person fixed that within minutes, pressed
the card's re-check button, and the runner still did not recover: the install's task
had used both of its tries on the refusal, the pull request had to be opened and
merged by hand, and the queue waited the whole time
(#14918).

  • A refused push is re-checked by a push. The child names a probe that asks for the access that was refused: git push --dry-run origin HEAD for a refused push, which writes nothing. git ls-remote origin, the example it used to be given, passes on read access alone, before anything is fixed.
  • The machine's refusal does not use up the install's tries. A run that ended on a host condition, the git host or origin refusing this machine included, is waited out and does not count against the task. A task refused again after its probe passed is not waited on that probe a second time, because that probe cannot see the refusal. It waits for a person instead of paying for a run every wait.
  • The re-check button leaves the card when it is pressed. The card's line says "Re-checking now — Start was pressed on the dashboard", and the button comes back only if the re-check finds the problem still there. Before, it came straight back and the press looked like it had done nothing.
  • A press, or init run again, tries the install's task again. On a task the runner had stopped trying, and on a merge the git host refused, the press gives the task its tries back. The card now says what was tried and what the last try ended with, not "had 2 runs and no pull request came of them".
  • An open install pull request in a mode that merges gets merged. One that nobody has tried to merge, such as one a person opened by hand or one a run left behind, gets a run that merges it. It no longer waits for a person.
  • A base branch that requires a status gets it from bin/ci. jchsoft8's main, for example, requires signoff, which only a green bin/ci posts, and the install's task runs no tests otherwise. When the host refuses the merge for a required status and the project has a bin/ci, the task runs it once on its branch and merges again. It fixes nothing bin/ci reports: a red run leaves the pull request open, and the card quotes it with the host's words.

Nothing to do on upgrade. A runner that is waiting on an install today picks the new
behaviour up after a restart.

A pull request that fell behind its base is updated, checked again and merged

A base branch can require pull requests to be up to date before they merge
(GitHub's "Require branches to be up to date", which projectoid_ii switched on on
2026-11-09). When somebody else merged first, the host refused the runner's merge
and the task ended as a failed merge with the pull request left open
(#14889).

  • pr merge says so before asking the host. It refuses with a non-zero exit starting merge refused: pull request is behind its base.
  • New mcptask_runner pr update-branch <n>. It merges the base into the branch on the host with a merge commit, never a rebase, waits for the new head and fast-forwards the checkout to it. The agent then runs bin/ci again on the new head and merges.
  • It refuses rather than guesses. On another branch, with uncommitted changes, on a conflict with the base, and after 2 rounds on the same pull request (fell behind again during CI) nothing is changed and the pull request stays open for a person. GitHub only; on another host it says so.

A bare mcptask_runner update per project brings the pr skill that teaches the
agent the new refusal and the subcommand.

init and update no longer undo a project's own changes

On 2026-11-06 an init in projectoid_ii replaced two skills the project had
changed with the older bundled copies, appended a .gitignore line the project
already covered with a glob, and dropped the CI timing history from
.claude/test-commands.json (#14859).

  • A skill the project changed is kept. The install says which file it left alone and why.
  • .gitignore is appended to only when git does not ignore the file already (git check-ignore), not when the literal line is missing.
  • Keys the runner does not manage in .claude/test-commands.json are kept.

Nothing to do on upgrade.

init on a bash host no longer cuts ~/.profile off

On a host whose login shell is bash and which had ~/.profile but no
~/.bash_profile (the Debian and Ubuntu default), init created
~/.bash_profile. A login bash reads only the first of ~/.bash_profile,
~/.bash_login and ~/.profile, so from then on it skipped ~/.profile and lost
what that file set, ~/.local/bin on PATH included
(#15002).

init now uses ~/.bash_profile or ~/.bash_login when one exists, and a
~/.bash_profile it has to create starts by reading ~/.profile. A host where an
earlier init created ~/.bash_profile is not repaired by the upgrade: add this
as the file's first line by hand.

[ -f "$HOME/.profile" ] && . "$HOME/.profile"

A screenshot pasted into Claude Code can be attached to a task

New bundled skill attach-pasted-image (Claude Code only) and subcommand
mcptask_runner pasted-images (#14941).
The subcommand writes the images pasted into the current session to files and
prints one JSON line per file; the skill uploads them to an mcptask.online task
or posts them as a message. The mcptask-write skill's description of
AddAttachmentTool now matches the tool's real arguments
(#14945).

A bare mcptask_runner update per project installs the skill.

A task whose whole change stays on the machine can be finished

Some tasks ask for a change that by design never reaches git, such as an edit to a
gitignored file on the runner's own machine. Every finish the prompt offered ended
in git, so the agent declined such a task as out of scope and handed it to a
person (#14986).

  • New finish done_local. The agent makes the change, runs the task's verify commands, and logs 100 % naming the files and the verify output. The runner treats the task as closed for the run and looks for no pull request.
  • It cannot be used to skip a pull request. The task text has to say the change is local. The runner also checks the checkout: off the base branch, with tracked changes, or ahead of its upstream means the work was meant for git, and the task is failed and set aside for the day with what was found.

Nothing to do on upgrade.


Changelog

Other

  • cf1aa2882539effdd04138c511666e86d387f3f7 CLAUDE.md: switch memory_identifier to mcptask-go-runner
  • 722066be19e4beffcc44f85b3dd65e1119506237 Keep detached git maintenance out of install tests' repositories (#14919) (#15)
  • 13a0944d35e37bff25ba7dfe9ebba696b4ed82a9 [#14859] init keeps changed skills, checks git before .gitignore, keeps unmanaged test-commands keys (#19)
  • 700ec79977252173e3ead2c544739d7ccedf6b02 [#14889] pr merge: handle a PR branch that is behind its base (strict up-to-date protection) (#20)
  • 0370865702db259701bd8073e0d730bff7a49af6 [#14909] Stress harness: login shell skips dot-file temps like the glob does (#14)
  • 4327eb9183aa32d08a1a24288ab39089831af998 [#14910] Set up the mcptask runner in this project (#13)
  • c6ebd1347f0c20eb5d27f714a9d4c50767df7e1e [#14918] A press of the re-check button takes it off the card until the next wait
  • 75fbff9758d587afcb9cbdbf537fdb8ca4616f82 [#14918] A press of the re-check button, or init run again, tries a spent install task again
  • b8354770200690efcafd03b9baa8e6db3c0a0d70 [#14918] A refused push is re-checked by a push, and the machine's refusal spends no run
  • 99894def529ed383c074fe01e8373f4f3e9dff0e [#14918] An open install pull request nobody tried to merge gets a run that merges it
  • f3a4a18e80c966cac59be9f0bc67ecab038e73c9 [#14918] Preallocate the violation list in the refused-push check
  • e2399bcf8bc1336fcaa55775b48276926f5f5449 [#14918] The bad-day test replays the refused push, and the docs say how an install recovers
  • 2afa8eddba39a0dad767343610d7d303ce8ed2fa [#14918] The install's merge runs bin/ci once when the host requires a status
  • 54cf99b9b2806f1cb9f6922fdffefd2ff15fdcb4 [#14941] attach-pasted-image skill and pasted-images subcommand (#16)
  • 58dc91e4dab8e6fa9401108e382582583e75d168 [#14945] mcptask-write skill: real AddAttachmentTool arguments (#17)
  • d50e4754832d4566e05e8bb0c6e401becf948997 [#14952] Terminal harness: the tty's ^C echo is not a prompt (#18)
  • 3f87c1c127b75bb06071ed1fe1685e2c4658cccd [#14973] Every variable the MCP configuration names: init/update ask, the runner waits on the card (#25)
  • 1e6bba889ace83e559c7740325ba567f9adb6bcd [#14976] Scheduled run sees the login shell's PATH; launcher sources ~/.mcptask_env.d (#21)
  • 607b0d786005f7cb9c2ffb9229262482c5917d85 [#14985] Project-declared before/after work steps relayed into every CLI's prompt (#24)
  • fe520161377b291a544d833a0bc3cc80de214838 [#14986] done_local: a finish for a task whose whole change is local and never committed (#26)
  • 1155a90b1e9e13a85aaa9b48b3bf4b1e5729bc54 [#14987] Stress install day: a signal drawn past the end of a run is drawn again
  • 913c3df7a8c9d2aaad39bf9770e00e7ea65a4914 [#15002] init: bash writes the login file that exists; a new ~/.bash_profile reads ~/.profile first (#22)
  • 55b5f7e1abb2bd64970fc866dfdc5325c4a5abb8 [#15009] install tests: a third fewer git process starts; Windows timeout stopgap (#23)
  • 3ce8370141698b252effe81035bb926c1cba3963 docs(release): note for done_local (#14986) in v0.3.51
  • 1aa9747999b2acda4f56302bf5758d290885ca15 docs(release): notes for the pr update-branch, init and pasted-image changes in v0.3.51
  • 64029a0a36752e051509c1c7ad6741fee28fe1c4 docs(release): v0.3.50 shipped, the next-tag notes start empty
  • fb41ff5f3d0b8b7f3e6a613ed0712fd9e192468a install.sh says which download failed, not that the asset is missing

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

menu_bookOlder releases – the full changelogexpand_more

v0.3.50

Upgrading

Upgrading takes two commands. mcptask_runner update --self replaces the binary; then a bare mcptask_runner update in every project on the host, because the bundled .claude/ assets changed (skills/mcptask-read/SKILL.md). Run it while no runner is working that checkout. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.50 carries this binary; wrapper changes in its CHANGELOG.


Re-check now: the card checks a host problem at once

On 2026-11-05 a runner waited out a host_refused whose probe was
gh signoff --help, backing off 5, 10, 20, then 30 minutes between probes. The
person installed the missing extension three minutes after a probe; the next one
was due past the end of the work window, so the runner ended its day without
noticing the fix (#14804).

  • A runner_start on a runner that is not paused now means "re-check now" while the runner waits for a host condition: host_refused, login_required, a CLI that cannot start or is unusable, mcptask_unreachable, triage_tools_unreachable, git_remote_auth, a spent usage window, the install pin's waits, a missing remote, a dirty branch blocking an urgent bug, and the wait for the quota endpoint to answer. The wait ends within a minute and the condition's own re-check runs. Before, the runner logged "not paused — nothing to do" and waited on.
  • The card gets a Re-check now button for it. The dashboard drew Start only for a paused runner, so a card waiting on a host condition had no button at all (#14818). The snapshot now carries a recheck member — what the runner waits for, while a press would cut the wait short, null otherwise — and the card shows the button exactly then. Additive; schema_version stays 3.
  • A failed re-check does not reset the back-off. The wait after it is the one the condition was going to wait next, so a host_refused probe that fails after a press waits 20 or 30 minutes, not 5; pressing again is how to look sooner. Repeated presses coalesce into one re-check.
  • Start on a paused runner still lifts the pause, as before.
  • The card's remedy says so: every host condition's remedy now ends with "Pressing the re-check button on this card checks at once instead of at the end of the wait." A foreground init run, which does not wait, does not get the sentence.

Ship order: the button itself is mcptask.online's half,
#14819. Deploy it before this
tag, or the remedy names a button the card does not have yet. Nothing to
configure on the runner's side.

Each token variable gets its own export file

On 2026-11-06 install in a fresh clone of a project asked for credentials
"exported as MCPTASK_TODR_TOKEN", and nobody could tell why. The project
gitignores .mcp.json but commits a .codex/config.toml naming that
variable, and the runner takes the name from whichever of the project's MCP
files declares the server (#14822).

  • The prompt names the file when the variable is not MCPTASK_TOKEN: "That name is the one .codex/config.toml gives the token; change it there to use another."
  • The export file is named after its variable: ~/.mcptask_env.d/mcptask_kamr_token for MCPTASK_KAMR_TOKEN. Every variable used to be written to mcptask_token, so on a host with two projects naming different variables, the second install took the first project's variable away. MCPTASK_TOKEN stays in mcptask_token.
  • An older export of the same variable is removed when a token is written: a mcptask_token that exports MCPTASK_KAMR_TOKEN would otherwise be sourced after the new file and put its older token back. The install says which file it removed. A hand-written file in that directory that also exports the variable is left alone and named in a warning.

Nothing to configure. A host whose variable is not MCPTASK_TOKEN gets the new
file on its next install that writes a token.

A runner may now sit retrying instead of ending its day

Until now a runner that works the queue all day (pr_only, workflow,
today_auto_squash, daily, queue_manual, queue_auto_squash) ended its
day on the first error it had no name for, on any task that ended in error
("A task failed, stopping") and on a panic in its own code; daily paused half
an hour and tried again. Such a runner now ends only for a fixed list of
reasons — the work window, the daily budget, a stop, a refused account,
configuration it refuses to start with, a checkout it cannot vouch for, and a
few more. Everything else is reported once, shown on the card and retried, within
caps (Story 14788: tasks
#14802–#14808).
It does not mean the runner never stops: it means it stops for a reason it can
name, and says it on the card.

What the card shows

  • unhandled_situation: "Hit a situation the runner does not handle yet: <the error, sanitized and cut short>. Reported as bug #N. Re-trying at HH:MM." The full text, the stack and the last log lines are in the bug piece and the run log. Instead of Reported as bug #N. the card can say Already reported as #N at HH:MM., Already reported as #N, still open — this occurrence was added to it., Reported as bug #N — a regression of #M, which was closed. or Could not be reported: …. When the work window closes before the next try, the line says so instead of Re-trying at. After four tries, or two hours with no round going through, it adds once a day "No work has been done since HH:MM: it keeps coming back." — and one more message goes on the bug piece. The card clears once a round goes through. A more specific problem already on the card (a refused bug report, a spent usage window, …) keeps its place.
  • model_launches_held: the same failure came back three times today, each after a paid run of the coding CLI, so no more are launched for it — held until tomorrow, a new runner binary, or Re-check now on the card.
  • run_ended_real_damage (a tombstone, the run has ended non-zero): after a panic the runner could not confirm that the coding CLI it was running is gone, or could not read the checkout. Look at the checkout on that machine — the bug piece says what was found — and start the runner again.
  • Three new members inside attention, for the card to render on its own: retry_at (when the runner next re-checks or retries, RFC 3339 UTC — for the catch-all and for every other host-condition wait that has a next check; null when the work window closes first or nothing is waited), bug_piece_id (the bug piece the situation was reported as) and attempts (how often it failed today, across restarts). The last two are set for unhandled_situation and model_launches_held and null elsewhere. All three are additive and nullable; schema_version stays 3. Until mcptask.online renders them (a countdown in the viewer's time zone, a link to the bug), the message says the same in words, so nothing is lost on a card that ignores them.

What the runner does

  • One bug piece per situation, across machines. A situation is recognised by where it happened, not by its wording: a panic by the function and file, an error by its type and the step it failed in, a task that ended in error by its reason and the start of its message with numbers, paths and ids folded. No task and no project in the key, so the same bug met on ten tasks is one piece and two different crashes are two. The piece is named Runner unhandled: … with an [fp:xxxxxxxx] tag; before filing, the runner looks for the tag in the Errors epic — an open piece gets a message (machine, runner version, coding CLI, how often, when) instead of a second piece, a closed one gets a new piece marked as its regression. When the run's own report already filed the failure, nothing more is filed.
  • Then the short wait (short_wait_minutes), never past the end of the work window, and the round runs again — a task that ended in error is picked again, as a resume. An outage of mcptask.online is still its own condition (mcptask_unreachable), and a report it swallowed is filed at the next try.
  • A panic in the runner's own loop is retried on a clean slate. The coding CLI it was running is killed — its whole process group — and confirmed gone, and the checkout is read (branch, HEAD, uncommitted changes, into the bug piece) and never cleaned. If either cannot be confirmed, the run ends with run_ended_real_damage (above).

What the retries may cost

  • A task that fails twice in a day in a way the runner does not handle is set aside for the rest of the day (skip-list reason unhandled_failure, which no clock revives) and the runner goes straight on with other work. A pinned urgent bug has its pin suspended for the day as well, which is filed.
  • The same failure three times in a day, each after a paid run, holds model launches for it (model_launches_held, above).
  • A step that launches no model (git, a read of mcptask.online) waits 5, 15, 30 and then 60 minutes between tries, never past the end of the work window.
  • Failures that belong to the machine are one wait, never counted against a task: a host unable to start the CLI at all is launch_failed, a hard usage cap (You have reached your specified API usage limits) is rate_limited until the end of the work window, a provider refusing the account is harness_login_required, and a model the provider no longer serves holds model launches at once. A refused API key (not_authenticated) and a host that cannot start the CLI after every retry (the new termination spawn_exhausted) are one bug piece a day, not one per task.

How to stop it, or make it try now

  • Stop on the card pauses the runner in the middle of any of these waits (Start resumes it); stopping the scheduled job as usual (launchctl/systemctl/the Task Scheduler) ends it, also at once.
  • Re-check now on the card tries again now instead of at the end of the wait, and lifts a model_launches_held hold with three attempts back.
  • Installing a new runner binary lifts a hold too; it is taken up at the next task boundary.

What survives a restart

A crash, the overflow handoff or a binary handover used to start every count
over. Within the day they now carry on, in files beside the skip list in
tmp/mcptask_runner/, and start over the next day:

  • unhandled_retries.json: the attempts per situation, the tasks' failures, the suspended pins, the holds, the bug piece each situation went to, whether it was escalated, and — new — the clock of the long retry, so the two hours to escalation count from the first failure, whichever binary met it.
  • story_merges_tried.json (new): the Stories whose standalone story merge already ran today. A merge that failed is reported once; a handover or a crash used to run the half-done merge again at its first task boundary. The report of a failed story merge now also names the checkout — branch, HEAD and how many uncommitted changes — and the runner leaves the checkout exactly as it is: it never cleans it up.
  • log/runs/.error_report_state.json, the report throttle, now keeps the piece with each stamp. A file written by an older runner is still read; an older runner reading a new file starts its throttle over once.

What has not changed

  • A run started for one named piece of work (once*, review*, task_*, story_*) and the run init starts in front of you still end on their error, non-zero, as before. Their card code is run_ended_task_failed (it was day_ended_task_failed), and a panic there is still runner_crashed.
  • A panic on one of the runner's background goroutines (exit 2), and a panic while it is recovering from one, still end the run.
  • Exit codes: a runner that works the queue now usually exits on the window or the budget, where it used to exit 1 over a failed task.

Ship order: nothing to configure on the runner's side. The card's half —
rendering retry_at, bug_piece_id and attempts, and the new codes — is a
task for mcptask.online; the runner is complete without it, since every message
already says the same in words.

init says whose role is missing, and where

On 2026-11-06 a new developer's mcptask_runner init ended on
the task that gets this install's files into main could not be filed: HTTP 403
from https://mcptask.online/api/jchsoft/pieces
. His user had no role in the
project the target's CLAUDE.md names, and the message named neither
(#14823). It now reads:

trurl@jchsoft.cz has no role in project 7 (mcptask.online) of jchsoft on
mcptask.online, so the task that gets this install's files onto main could not
be filed. Add the user to the project — as a developer, for example — and run
`mcptask_runner init` again. (HTTP 403 from …)

The re-run that message asks for now works too. The refused install had left
its .gitignore lines written, and the re-run used to call that .gitignore
somebody else's change and keep the job off. A .gitignore whose every changed
line is one an install appends now counts as the install's own; one line of
anyone else's keeps it theirs.

The job still stays off on a 403, as before. init files this task in the
target's own project, while runner bug reports go to project 70, so a new
developer needs a role in both.

The mcptask-read skill downloads attachments with the signed link only

Since mcptask.online #14365 an attachment downloads only through the signed
download_url that GetAttachmentTool returns. The link lasts 15 minutes.
The bundled mcptask-read skill still told an agent it could build the URL
itself, which now ends in a 401 (#14551).

  • The skill now says never to build the URL, to call GetAttachmentTool again when the file is needed again, and that a 401 means the link expired.
  • download_url is a path (/api/…), and the suggested curl puts https://mcptask.online in front of it. The command the skill printed before had no host and could not work.

A project gets the new skill with mcptask_runner update.

init speaks in colour on a terminal

On 2026-11-06 a new developer's first init read as one grey page: the
questions, the explanations, the 403 and the refusal after it all looked alike
(Story 14828,
#14826). The palette was built for
the detail stream, which init writes to its log file, so it was off for
everything a person read. Every line on init's screen now has a kind, painted
for the screen itself:

  • questions are bold — the question, its options and the prompt;
  • explanations are dim — the sign-in text, why a time is asked, what a start now would do;
  • what worked is green under ✓ — Done., and an answer taken because there was only one (Coding CLI codex: the only one …);
  • an exception the install goes on past is orange under ! (yellow on a terminal that does not report 256 colours) — This directory is not a git repository. Create one?, a skipped sign-in, a job file rewritten while the old copy stays loaded;
  • an exception that stops is red under ✗, with the step to take in bold on the next line — The scheduled job stays off: … and When that is sorted, run …;
  • in the closing summary, Switch on:, Watch: and Full log: are dim and the command or path beside them keeps the terminal's colour, so it is easy to copy.

The closing Error: … line is red too, and the warnings init prints to
stderr are now painted as they were meant to be (they never were outside
--verbose).

The scheduled job stays off moved from stderr to stdout, next to the
question it answers. A script that read that refusal from stderr will find it on
stdout; the log keeps it word for word, and --start still ends on its error
with a non-zero exit. With --verbose it stays on stderr.

Nothing changes for anything that is not a terminal: a pipe, a redirect, the log
file and NO_COLOR get exactly the text they got before, without codes and
without the glyphs. MCPTASK_RUNNER_COLOR still forces colour on or off.

init runs in four sections, each with one green line

init at a terminal now walks through four sections, each opening with its
heading and closing with one green line that sums up what it wrote
(Story 14828,
#14829):

  • ▸ CLI — which coding CLI drives the project, then ✓ 12 skills, helpers and permissions for claude (with test commands and trust where the project and the CLI have them);
  • ▸ User — the sign-in, the shell file, the account and project, then ✓ token written to ~/.mcptask_env.d/mcptask_token as MCPTASK_TOKEN; .mcp.json and CLAUDE.md for project Alpha (#62) of acme;
  • ▸ Launcher — the mode, then ✓ today_auto_squash, with its waiting strategy in config/mcptask_runner.yml;
  • ▸ Time boundaries — the start and the end of the working day, then ✓ job written for weekdays from 08:00, with no end of day: ~/Library/LaunchAgents/…plist, and last Turn the job on now? [Y/n] with the closing under it.

Every line about a single file stays in the install log, as before. A project
that needs no job (--mode none) has no Time boundaries section, and
init --schedule shows only Launcher and Time boundaries.

A refused switch no longer ends in a green Done. When the job stays off
because of the tree — The scheduled job stays off: … in red, with the step
under it — that refusal is now the ending. The Done. The scheduled job is
written and off.
line and the Switch on: command that used to follow it are
gone: the first was the line people read, and the second switched on exactly
what had just been refused. Full log: still closes the screen.

One step moved, and nothing it writes changed: trust is now recorded right after
the permissions, inside the CLI section. The AGENTS.md pointer for a CLI that
reads its own instruction file stays where it ran, straight after the account
and project it is copied from, and so it is the User section's.

Nothing changes without a person at the terminal: a script's screen is still its
ending alone, --verbose prints the detail as it did, and the log marks where
each section begins with a [Installer] Section: … line.

update speaks the same line kinds as init

A clean mcptask_runner update is now a heading and one green line, where it was
a table of every skill and helper:

▸ Update
✓ 12 skills, helpers and permissions up to date for claude (3 updated)

A skill or helper the host has edited is an orange exception under it, naming the
file and the two things to do: mcptask_runner update --force (the edit is kept in
a .bak copy, to merge back by hand), or keep yours as it is. The green line counts
only what is up to date, so it never claims a file update left alone. Files
update changed that you did not ask about (the harness: key, the scheduled
job, the .mcp.json entry) are orange lines too, and the commands to reload a
rewritten job are on the screen under them.

The table, and everything else update has always printed, is in the install log
(~/logs/mcptask_runner/install/, the directory init writes to), and --verbose
prints all of it on the screen as before. A pipe gets the words without escape
codes or glyphs. Warnings that used to go to stderr are on the screen now, so a
script that read them from stderr should read the log or pass --verbose.

The install has a bad day of its own

The stress run that bin/ci runs now drives init too: many installs in a row,
each into a throwaway git project, each with a refusal, a leftover or an
interrupt drawn from a seed, and after each one two re-runs that have to end with
the job on (#14836). It is a test
and changes nothing an operator runs. bin/stress --install runs it by hand;
internal/stress/README.md says what it checks.

Known, and found by it on its first runs: an init refused at its task —
the 403 above, say — in a project whose CLAUDE.md it had to complete (no
project_relative_id there, so it came from --project-id or the question)
leaves those CLAUDE.md lines uncommitted, and every re-run then keeps the job
off with "the tree carries changes from before this run … CLAUDE.md". It is the
.gitignore case above, for CLAUDE.md, and task
#14832 fixes it. Until then, commit CLAUDE.md
(git commit CLAUDE.md -m "Declare the mcptask.online project") and run
mcptask_runner init again.

Found by it too, and fixed in the same release: every file init wrote was
truncated first and then written, so an init killed between the two could leave
that file empty — the day caught .gitignore emptied that way, the project's own
lines gone. See "A kill never empties a file" below
(#14840).

Every warning and refusal of init is a named exception, orange or red, with its step

init now has a fixed catalogue of the things that can go otherwise than the
clean path, the way the runner has its fixed list of endings
(Story 14828,
#14832). Each one is named, belongs
to one of the four sections, and is either orange — the install goes on past
it — or red — the install, or the switch at its end, stops and waits. Each
says who, where and what in one sentence, and names the step to take on the line
under it. Where init can put it right itself, it asks, [Y/n].

  • Warnings reach the screen as the line of their kind. The placeholder-token warning (WILL NOT START), a project with no recognisable test toolchain, a job that shows no log after its start, an account or project written unchecked for lack of a token, a helper changed by hand, a second export of the token: each is now an orange ! line with its step in bold under it, where it used to be grey text on stderr. The placeholder warning's three lines of "two ways to fix it" are one step now. With no screen — --verbose, update — they stay on stderr, in the same words.
  • A refusal init ends on is red, with its step under it, for a person at a terminal: ✗ trurl@jchsoft.cz has no role in project 7 (Projectoid) of jchsoft on mcptask.online and then Add the user to the project — as a developer, for example — and run mcptask_runner init again. instead of one Error: line. A script still gets the Error: line on stderr, and the exit code is unchanged.
  • The role in the project is checked right after sign-in, in the User section, with one read of the user's projects — not at the very end, where the 403 used to come after every question had been answered (#14823). No role in the project stops there. No role in project 70, where the runner files its own bugs, is orange: the install goes on, and the line says those reports will be refused until a boss of project 70 adds the user. A list mcptask.online does not give claims nothing either way, and says so.
  • Lines from an install that did not finish are offered back. An install whose task was refused leaves its .gitignore entries and the account and project it wrote into CLAUDE.md uncommitted, with no pin naming them. The re-run used to call CLAUDE.md somebody else's change and keep the job off (the install's bad day, #14836, found it; #14823 had fixed only .gitignore, silently). Now each file is asked about: CLAUDE.md carries lines from an install that did not finish, and none of anybody else's. Take them over? [Y/n]. One line of anybody else's keeps the file theirs. With nobody at a terminal the lines are taken over, as before, and that is said.
  • macOS: the hour the job is registered for is read back (#14793). Once the job is switched on, init reads the registration back from the system log (/usr/bin/log show, by its full path: in zsh log is a builtin) and compares the hour with the one asked for. On a freshly set-up Mac whose time zone changed after login, UserEventAgent (Aqua) keeps the old zone — Mon–Fri 08:00 was registered as 17:00 CET on Trurl's Mac mini, and nothing ran in the morning. That is now red: the scheduled job … is registered for 17:00 and not the 08:00 asked for, with the step Restart UserEventAgent (Aqua) with kill <pid> … then run mcptask_runner init --schedule to check again. When the log does not show the registration, init falls back to /etc/localtime changed after the agent started, and says which check it used. On Linux and Windows the log says the platform takes the hour as written.

An exception is one line. A reason quoted from somewhere else — a server's 502 page
quoted as the sign-in's failure, which the install's bad day caught breaking the
warning over eight lines — is said on one.

The install log names every exception as it happens,
[Installer] Exception <name> (<level>, <section>), so a log can be searched for
what went otherwise. Some messages were reworded to fit a sentence and a step:
--git-host x names no git host this runner knows and Name one of …, an
unparseable .mcp.json on one line with its step, the time and mode refusals
with theirs.

An interrupted init continues at its last unanswered question

init at a terminal now remembers where it was. Stop it — Ctrl+C included — and
the next init asks first
(Story 14828,
#14833):

Continue at Launcher › mode? [Y/n]:
  • Y (or Enter) carries the answers over and goes on at the question it was interrupted at; the line after it names what was kept, for example Kept from the interrupted install: sign-in me@example.com, shell file y, account acme, project 62, the token in /Users/you/.mcptask_env.d/mcptask_token. A sign-in interrupted at the password shows the email it continues with and asks for the password alone.
  • n deletes the saved answers and starts from the beginning. There is no --fresh flag: this question is how a person starts over.

Ctrl+C ends init with one grey line,
Interrupted at <section> — run init again to continue there., and exit code
130, as an interrupt does. A Ctrl+C at the password turns the terminal's echo
back on before it ends. Once the install's task is running, Ctrl+C is the task's,
as before: it stops the task and says how it ended.

Where it is kept: tmp/mcptask_runner/init_state.<user>.json in the project,
one file per person, readable by that person alone and replaced whole on every
save. The first save adds the runner's own lines to .gitignore (the ones the
switch used to add at the end), so the file never shows up as a change. It holds
the section and the question reached and the answers nothing else holds yet —
never the password and never the token. A token the interrupted install wrote is
read back from the file it was written to.

Nobody at a terminal — --start, a script, an AI agent — never reads the
saved answers: they were a person's, half-way through, and not the caller's. Such
a run deletes them and says An interrupted install was set aside — starting
over.
init --schedule leaves them where they are. A finished install deletes
them; one that ended over an error keeps them, so the run after the fix continues
where it stopped.

What the interrupted install left is the continued one's. The lines it wrote
into .gitignore and CLAUDE.md are taken over without the question
leftover_lines otherwise asks, because the yes to continuing already said whose
they are, and the orange line says so. An install interrupted after it wrote the
account and the project therefore ends with the job on when it is continued.

Its exceptions are the catalogue's, each with its step:

  • state_unreadable (orange): saved answers that are not JSON, another version's, or name a section, question or answer this runner does not know — set aside, and the install starts over;
  • state_not_saved (orange): an answer could not be kept; the install goes on, and an interrupt then would start it over;
  • state_not_set_aside (red): saved answers that have to go and cannot be deleted, with the file to delete;
  • resume_unanswered (red): the terminal closed at Continue at …?, which is neither a yes nor a no;
  • carried_token_missing (orange): the token the interrupted install wrote is gone, and the sign-in is asked again.

The question Continue at …? itself is not an exception: it is the path an
interrupted install was made to take.

The install's bad day gains eleven vectors — Ctrl+C in each of the four
sections and a yes to continue, a no, a script over saved answers, saved answers
that cannot be read, a kill during a save, a save that fails, saved answers a
script cannot delete, and a carried token that is gone — and four invariants: the
saved answers never hold the password or the token; none outlive a finished
install or any run with nobody at a terminal; a continued install starts at its
question, asks nothing it was answered and ends like an uninterrupted one; and a
run with nobody at a terminal never reads them.

init on an installed project sums it up and asks one question

Task #14834, Story
#14828. A re-run of init at a
terminal on a project that is installed already — a new version, a changed machine —
no longer walks every question again. It shows what each section was given, and asks
one question before the first heading:

This project is installed already. What each section was given:
  CLI              claude
  User             trurl@jchsoft.cz · project mcptask.online (#7) of jchsoft
  Launcher         today_auto_squash · job on
  Time boundaries  Mon–Fri 08:00–18:00
Change anything? [N/section]:
  • N (or Enter) re-applies every section's files, each section with its one green line, asks nothing more, and leaves every answer and the job as they are: the switch, Time boundaries' last question, is not put, and the service manager is not touched. The closing says The scheduled job is on, as it was. (or off).
  • A section — cli, user, launcher, time or Time boundaries, in any case — walks that section's questions alone, each with what is on disk as its default, which Enter keeps: Enter choice (1, 2, 3 or 4) [1]:, Enter time as HH:MM [08:00]:, … [18:00] (none = no end of day):, the CLI's question with the current CLI, and the sign-in over the token in place (a blank email keeps it). A job a walk rewrote — a new mode, or a token signed in again — keeps its state: reloaded where the platform holds it idle and its file changed, left as it was otherwise.
  • A piece that is gone is that section's exception, said in orange under its line, and that section's questions are asked whatever the answer: installed_token_missing (no file exports the token and nothing else gives it a value), installed_identity_missing (CLAUDE.md lost its account or project), installed_mode_unreadable (the launcher no longer says the mode), installed_job_incomplete (the job file, its start time, or the work_window it was written with is gone). An answer that names no section is change_answer_invalid (red).

What counts as installed is what is on disk: config/mcptask_runner.yml naming its
harness, then the token export, CLAUDE.md, the launcher, the job file and
work_window. An interrupted install's question (Continue at …?) comes first, and
then there is no summary. --schedule at a terminal is the shortcut to Launcher and
Time boundaries: no summary, both sections walked with the current values as
defaults, and the switch at the end. A run with nobody at a terminal keeps its
behaviour: no summary, no question, its answers from flags and defaults.

The install's bad day gains the vector a re-run on an installed project — N, a
section drawn from the seed, the token's export and the job file gone, the launcher
gone, CLAUDE.md without its project, and an answer that names no section — and three
invariants: N leaves every answer and the job as they were and tells the service
manager nothing; a section walked changes that section's answers only; and no
question is asked outside the sections walked. Every terminal re-run of the day now
meets the summary, and answers N when the job is on and Time boundaries otherwise.

A kill never empties a file

Every file init and update wrote used to be written in place: truncated, then
written. An init killed between the two — Ctrl+C, a closed terminal, a SIGKILL,
a machine that went down — left that file empty. The install's bad day caught it
on a person's .gitignore: their own lines gone, and both re-runs then kept the
job off over the file (#14840).

  • Every file init and update write is now replaced whole: the new content goes to a temporary file beside it, is synced, takes the old file's mode, and is renamed over it. Whoever reads the file sees the old one or the new one, never part of either. That is .gitignore, CLAUDE.md and the instructions pointer, .mcp.json, opencode.json and .codex/config.toml, the user's ~/.codex/config.toml trust entry, config/mcptask_runner.yml, the permission file, the skills, the helpers and their manifests, the token exports, the line in your shell's rc file, the scheduled job's plist, systemd units or task XML, the launcher, the runner binary the job runs, .claude/test-commands.json, the Bitbucket credentials, the install pin and outcome, and an interrupted init's saved answers.
  • A symlink is written through, not replaced. A ~/.zshenv that is a link into your dotfiles repository stays a link; the file it names gets the line.
  • A read-only file is still refused, as before, although a rename would not need its permission.
  • The directory now has to be writable, which a write in place did not need. A directory that refuses the temporary file is an error naming the file.
  • On Windows, a file another program holds open — an editor, the search indexer, a virus scan — cannot be replaced while it is held, where a write in place may have gone through. The rename is tried again for about two seconds; after that init stops with an error naming the file and saying to close what holds it. macOS and Linux replace a file whoever holds it.
  • A temporary file an init was killed with is named .<file>.mcptask_runner-<pid>-<random>.tmp, beside the file it was replacing — a dot-file, so that the shell sourcing ~/.mcptask_env.d/* never sources one. Nothing reads it, init does not count it as anybody's change (it never keeps the job off), and the next init removes it once the process that left it is gone, saying so in its log.
  • On macOS the sync is fsync(2), not F_FULLFSYNC. The full flush costs about 5 ms a file there, and an install writes some fifty files; a kill needs no flush at all, and fsync(2) keeps the content ahead of the rename through a crash of the system. Only a power cut can still lose the last write's flush.

The install's bad day gains a vector, "killed in the middle of a write",
that stops an install for good half-way through one of its writes, chosen from
the seed; invariant 5 now holds every file the install writes — the runner's own
state under tmp/ included — to its old content, its new one, or a whole
content one of the run's writes put in place, with nothing set aside. A source
test, TestEveryWriterGoesThroughTheAtomicHelper, refuses any new write that
opens a file in place.

init is tested through a real terminal

Nothing changes for a person running init; what changes is what is checked
before a release. Every other test of init's screen reads a buffer, which is no
terminal: no colour unless forced, no echo, Ctrl+C as a function call, stty on
nothing. A new suite in internal/stress builds the real mcptask_runner, starts it
on a pseudo-terminal the way a shell starts a command, types the answers a person
types and presses Ctrl+C as a key. It runs against the install's bad day's stub
mcptask.online, fake service manager and throwaway git project, and nothing of the
machine it runs on.

  • The clean first install is compared with a golden screen with its escape codes, and again with stdout piped, which has to carry the painted screen's words byte for byte and no code or glyph at all.
  • The re-run on an installed project, its summary answered N and with one section, and update, clean and over an edited skill, the same.
  • Ctrl+C at a question of each of the four sections exits 130, prints the grey line saying where the next run continues, and leaves the terminal's echo on — the password included; the next run's Continue at …? [Y/n] resumes at that question and ends with the job on. A SIGKILL at a question is followed by a re-run that ends with the job on too.
  • Every entry of the catalogue of install exceptions has a terminal vector or a reason in words, and an entry added without either fails the suite. A vector holds its entries to their colour, glyph, sentence and step, and a fix question to its answer doing what it offers.
  • No entry is pending as a known failure. The suite's first run found four said as plain warnings on stderr before the installer has a screen: the git host's three (GitLab's glab login, Bitbucket's missing and refused credential) and an install log that cannot be opened. They are said as their kind now (below).

A fast part runs in every go test ./..., about twenty seconds; the rest of the
catalogue under STRESS=1. Windows has no Unix pseudo-terminal, and each scenario
says so there. The test-only dependency is github.com/creack/pty v1.1.24.

What init says before it has a screen is painted too

The terminal suite found four exceptions that reached a person as plain grey lines
on stderr, because they are said before the installer exists, and the atomic-writes
task found that a shell with GLOB_DOTS would source a half-written token
(#14848).

  • GitLab's glab login, a missing Bitbucket credential and a refused one are said on the screen as what they are: orange, under !, with the step in bold under it, and the install log names each (Exception gitlab_login (continues, Launcher)) like every other exception. The git host step runs right after the CLI question, so they come out under the CLI heading. A script, and --verbose, get the same warnings on stderr as before.
  • An install log that cannot be opened is said the same way, on stdout, when a person is at the terminal. A script still gets the warning on stderr.
  • A resumed install no longer tells you to "Answer n…" to a question it did not ask. When you continue an interrupted install, the lines it left in .gitignore and CLAUDE.md are taken over without a question, as before. They are now said as an entry of their own, leftover_lines_continued, whose step says what happened: nothing to do, they are taken over as that install's own.
  • The loop your shell's startup file sources ~/.mcptask_env.d with skips every name that starts with a dot by itself, whatever the shell's glob options are. A write init was killed in the middle of leaves a dot-file beside the token export, holding half of it. Plain * never matched that file, but zsh's GLOB_DOTS and bash's dotglob do, and a new shell would then have sourced it.
  • Existing hosts get the new loop with their next init or update. Either one replaces the old loop where it is exactly the one init wrote. That covers the loop the Rails gem wrote into ~/.zshrc too. Each replacement is said in the log. A loop you have edited is left as it is: if you set GLOB_DOTS or dotglob, check it yourself. Until a host runs init or update, it keeps the old loop, which is safe unless one of those options is set.

The scheduled job runs on the days you choose, and --force repairs an old one

On 2026-11-07 a macOS host needed its runner on Saturdays. init could only write
Monday to Friday, so the Saturday entries were added to the plist by hand. On the
way, init --schedule --force turned out to do nothing to a LaunchAgent from before
the job carried its days, although that is the command run --if-due names when it
cannot read one (#14849).

  • --days chooses the days, and MCPTASK_RUN_DAYS does the same from a script or rake. It takes day names or ranges separated by commas, such as mon-fri, mon-sat, mon,wed,sat or fri-mon, or one of weekdays, all (daily) and weekend. A value that names no day stops the install as days_invalid, before anything is written.
  • At a terminal, init asks for the days before the hour: "On which days should the job run?", with Monday to Friday as the default, so Enter keeps it. The hour's question then names the days. Anything that answers init's questions by their words needs one more answer, an empty line for the default.
  • All three platforms write any set of days: one StartCalendarInterval entry per day in the LaunchAgent (Sunday is 0), OnCalendar= with day names in the systemd timer, and the DaysOfWeek elements in the Task Scheduler definition. run --if-due reads the same set back, and the install's line says it: "The job runs Mon–Sat at 08:00".
  • Writing a job again keeps what it had. init --schedule --force without --days or --at keeps the days and the hour of the job that is there. Before, it wrote every job for Monday to Friday at 08:00, so a Saturday added by hand was lost at the next re-run. At a terminal, the job's days and hour are the defaults of their questions.
  • init --schedule --force with nobody at a terminal now rewrites the job. Without --mode it used to find the job, print "The scheduled job was already written, and this install left it as it was", and change nothing. It now reads the mode from the job's launcher, says which, and writes the job again. A launcher that names no mode stops the install as job_mode_unreadable, whose step now includes --mode <mode>. A job whose start cannot be read, such as an old LaunchAgent with an Hour and a Minute and no Weekday, is written for Monday to Friday at 08:00. The install says so as job_start_reset, naming --days and --at.
  • What to do on a host that run --if-due refuses: run mcptask_runner init --schedule --force in the project, the command its log line now names along with the directory. Then reload the job with the command the install prints.
  • Weekend days still need the budget. The days decide when the job starts, not whether the day has work. With respect_working_hours ticked on your Company role on mcptask.online, a weekend has no daily budget, and a Saturday start ends without a task. When the chosen days include Saturday or Sunday, init says this.

The card carries the scheduled job's plan

On 2026-11-06 launchd registered a Mac mini's 08:00 job for 17:00 after the time
zone changed. Nothing ran in the morning, and nothing said so: a start that never
happens leaves no log, no card and no bug piece
(#14793). The runner cannot report
it. mcptask.online can, once it knows when the machine was due
(#14837).

  • Every snapshot carries a schedule member: the start time, the weekdays, the machine's IANA time zone and its current UTC offset, the end of the workday and the job's mode. It is read from the job file init wrote, the same way run --if-due reads it. It is null on a machine with no scheduled job for the project. Additive; schema_version stays 3.
  • It is sent whichever way the runner was started, including the install's own task run, which init starts just before switching the job on. The server therefore has the plan before the first scheduled start.
  • A job file that cannot be read costs only the member. The run log says why, as a [Schedule] warning, and the run goes on.

Ship order: none. The server ignores a member it does not know. The missed
start on the card is mcptask.online's half,
#14838, and it can deploy before
or after this tag.


Changelog

Other

  • 080e2196a852411f9844faba4d0aa98422e19a79 Give the stress day a 30-minute budget instead of 20
  • 5c6ed4815cb7ab643221ae878dd60262c81f6d29 Route a recovered loop panic through the catch-all's capped retry seam
  • f700184eacda80e00cb66d9c571179daf4fa9362 [#14551] mcptask-read: download attachments by the signed link only, with its host
  • bbb2670ddc7fdf793c90dac90debda19254adddd [#14802] The fixed list of endings, and a test that walks every exit against it
  • 8942ee2aa47bf51f07319544e4328faefa041dbd [#14803] The catch-all: an unhandled error or error verdict is waited out on the card
  • 2a52513eb3c9ed11b1197551e32c3ea0e9d714ee [#14804] Start on the card re-checks a host condition now instead of at the end of the wait
  • 583cdc4ad6b363bed639075d35fa5c80707880c1 [#14805] A recovered loop panic is retried on a clean slate, or ends as real_damage
  • c385d11720b400310fb2c8461ec579bf2a9c0a89 [#14806] The catch-all's retries are bounded in cost; host-wide failures are one wait
  • b473f0d27c61af8f174dd18254e6be5178844b0c [#14807] One unhandled bug is one piece across machines, linked from the card
  • 7ce6f6300440e4de257828f3b951fa0bff11e6bb [#14808] The card carries the next retry, the bug and the attempts; merges tried and the streak clock survive a restart
  • 81077b3c201303e2dc50ac15d25ca7aa2af8a26d [#14818] The snapshot says when Start would re-check a host wait, so the card can show the button
  • 1e6fca855b1503916bc7eac4107cd08a01c52b7e [#14822] Each token variable gets its own export file, and the prompt names where the name came from
  • df8b88fb2b74fddbbd417380c9a294d113d58123 [#14823] init's 403 says whose role is missing where, and a re-run takes back its own .gitignore
  • 318e1180b0a68c4900ef79afad3babf5ab65304b [#14826] init's screen speaks in six line kinds, painted for the screen itself
  • 96a3756cc60f86486e3dcd36ac2e9c787020d7e7 [#14829] init runs in four sections, each closing with one green line
  • a2063fcde0450a281d9478046d33ceac970a507a [#14830] update speaks the same line kinds and palette as init
  • c50d6cebd05164518bfc8dbee8a53f4be6d33794 [#14832] init's exceptions are a fixed catalogue: named, orange or red, each with its step
  • d948c795f3dcff7124b4bdd0a8a643adab2a4592 [#14833] An interrupted init continues at its last unanswered question
  • 5fbadd540a1ffed8260bcc1087b15f185c2c5eb3 [#14834] init on an installed project sums up its four sections and asks "Change anything? [N/section]"
  • c9434e40f87dd9d82c308b03d8c5d1dcf27ad054 [#14835] init's screen through a real terminal: the clean path, the catalogue, Ctrl+C and the re-run
  • 5af8ee7240a69d981df5211719765243fa7e1e42 [#14836] The install's bad day: refusals, leftovers and interrupts against invariants, in the stress run
  • 291d6d503c99f5b849d10eebdda65c399e9c7847 [#14837] The snapshot carries the scheduled job's plan, so the server can tell a missed morning start
  • c9b8465cddf8b6e82897bc3eaae568a24631d529 [#14840] A kill never empties a file: every file init and update write is replaced whole
  • 18124a96c616f82e1346203035c908c911966512 [#14848] The exceptions before init has a screen are painted; a taken-over leftover says what happened; dot-files are never sourced
  • 2b31b76ee538ecfe0d7b53be753d6478e8aaa445 [#14849] The scheduled job runs on the days you choose; init --schedule --force repairs a job --if-due refuses
  • e99553fe2a653e9c56adcfcd14e9eb25ca5984c9 docs(CLAUDE.md): a person at the terminal has to find their way
  • de7aa93cd5e97d9811c7cd23164d0e8962e776f5 docs(release): v0.3.49 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.49

Upgrading

Upgrading takes two commands. mcptask_runner update --self replaces the binary; then a bare mcptask_runner update in every project on the host, because the bundled .claude/ assets changed (helpers/check_test_lock, skills/test-runner/SKILL.md). Run it while no runner is working that checkout. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.49 carries this binary; no wrapper changes.


init asks which project this is

A project whose CLAUDE.md does not declare account_code and
project_relative_id used to install cleanly and then die in its first triage,
filed as stream_ended (#14521).

  • On a terminal, init now asks and appends a ## mcptask.online block to the file. The project is picked from what the server lists.
  • A scripted install on such a project is now refused until it passes --account and --project-id (env: MCPTASK_INSTALL_ACCOUNT, MCPTASK_INSTALL_PROJECT_ID). A project that already declares both notices nothing.
  • run refuses the same gap by name, on the card as project_identity_missing, before any child starts.
  • An attempt that cannot build its prompt is now filed as not_started.

init switches the job on

An install used to end with a job written and three commands printed, so the
runner did not run until somebody typed them, and the first evidence that a host
worked came the next morning.

  • On a terminal, init now ends with a question that says what would happen right now. A yes files a task that gets the files the install wrote onto the base branch, pins it, runs it right away in front of you, at any hour, and only then switches the job on. Nothing the install wrote is committed during the install.
  • How that task ended is on your screen the moment it ended, ahead of anything the job does, in one sentence that names the pull request or the branch and the task: at the end of the run, on the task as a message, and on your screen. "Complete at 100 %" is said only when mcptask.online says so. If the message could not be written on the task, the screen says that too. The screen gets one line while it works, and the whole of its output is in the install's log. --verbose and --ignore-quota on init reach that run.
  • That run does not answer to the daily budget or to respect_working_hours. It is a minute or two of your own install, not a working day, and the log says so in one line. A later background pickup of the same task keeps the normal gate.
  • That run never waits for a person. A CLI that is not signed in or cannot start, a machine refusing the work, a spent usage window, an overloaded API, an account the server refuses and a stop from the dashboard all end it at once with that reason. It runs one child. init exits non-zero when the task failed or a basic check refused it, on a terminal too, with the job on and the task still pinned for a re-run of init or the job's next start; a re-run files no second task.
  • While the task is pending, the checkout works from its branch, because that is where .mcp.json, the skills and the CLAUDE.md block are until the merge. The runner puts it there itself when the task's child ends, whatever the child did, and run and init do the same before their preflight. A branch a merge has deleted fast-forwards the base branch from origin instead, so that merging is what un-sticks it. A tree with somebody's uncommitted changes is not moved: run refuses, on the card as install_checkout_refused when it can reach one, and init keeps the job as it is, both naming the pull request or the branch and what to do. With no task pending, nothing here runs at all.
  • Ctrl-C stops the run through its process group. The task stays pinned, the job is not switched on, and mcptask_runner init --schedule carries on. A runner already working in the project holds the lock, so no run is started, and the screen says it takes the task at its next round and that the conclusion will appear on the task.
  • A background run that picks the task up later says and writes the same conclusion, and does not write one already there.
  • Inside the working day the job then goes straight to work, on the queue unless the queue is held, and the summary says which. Outside it the job is on and first starts at its next scheduled time: the end of the workday stays the one hard stop for the job.
  • The runner works that task first, with no triage, on the smart tier and with no tests and no CI. It starts nothing else until the files are on the base branch, because a task cut from it would run without .mcp.json and the skills.
  • What the task does depends on the mode and on whether the project has a remote:
    • A remote, today_auto_squash: branch, pull request, merge.
    • A remote, pr_only or workflow: branch, pull request. A person must merge it before the runner takes any other work, and the card says so as install_pr_unmerged.
    • No remote, today_auto_squash: branch, commit, merged into the base branch.
    • No remote, pr_only or workflow: branch, commit. A person must merge the branch, and the card says so as install_branch_unmerged, with the git merge command. A squash merge counts.
  • That merge does not ask the host's CI, and does not wait for it. This is a deliberate exception to "nothing merges without green CI", for the runner's own files only; every other task still answers to CI. It merges on three basic checks instead, made in Go: the branch changes only the files the install listed, none holds a literal credential, and every JSON file parses. A failed check merges nothing and leaves the pull request or the branch for a person, with the file and the reason on the card (status basic_check_failed). A host that refuses the merge, for a protected branch or a required review, ends the same way, in the host's words.
  • A project with no remote now takes no further task, in any mode that opens pull requests, and that includes a project with no remote that was installed long ago and used to pay for runs that failed at their last step. The card says no_git_remote with the remedy, git remote add origin <url>, and the runner goes on by itself when one appears. A workflow day on such a project used to refuse to start, and now waits the same way. A run pinned to one piece and an urgent bug are not held.
  • A directory that is not a git repository gets a question at the start of init, at a terminal. A repository with no commit gets one on a yes: empty if everything in it is the install's own, pushed if there is a remote. If it holds other files init asks before committing them, respecting .gitignore; a no, or no terminal, keeps the job off, and git's own refusal is the error in git's words. A repository init creates starts on main, and one with no commit and no remote that git called master is renamed to main before its first commit, because the regular prompts say git checkout main.
  • Two runs with nothing to show for them end in install_task_failed, and the task is then finished by hand. A host or server that cannot be asked is install_state_unknown.
  • A run on an account other than the built-in default now reaches its own account. With MCPTASK_ACCOUNT unset the runner used to ask the default account's paths for its profile, its budget and its pieces, whatever CLAUDE.md declared, so such a project ended on a 404 at its first question. CLAUDE.md is read now, after the environment.
  • The job stays off, with the reason, when a repository with commits has changes from before the install, when run itself would refuse, when the project has an origin this build has no git host for, or when an urgent bug is pinned. A server that refuses the task ends init non-zero, with the job off.
  • Scripts change nothing unless they add --start.
  • init now adds .claude/settings.local.json to .gitignore. It is one machine's approvals, and it should never have been a candidate for a commit. It adds tmp/mcptask_runner/ and the runner's logs under log/ too, unless the project already ignores them, so that the runner's own state never shows up as a change.
  • The printed "run it once now" hint was false outside the working day since v0.3.3x, because the launcher passes --if-due. It now says so.

The install's task logs its progress without a refusal

In all seven trial runs, the progress gate refused the install task's first progress
log (#14660). Each child had a TODO
list and had closed its item, but it sent the close and the log together in one batch
of calls. The gate reads the plan from the session's record, and that close was not
on the record yet. The retry a turn later went through, so the run worked, with one
refusal in its log every time.

  • Every progress step in the install's prompt now says the log goes out once the plan call has answered, never in the same batch as it. The progress rules say why.
  • The gate is unchanged, and so is the prompt of every other task.

init stops asking what it can find out

  • The Epic question is gone. init reads the project's Errors Epic from mcptask.online and writes the first one, saying which. A project with none, a server too old to say, no token or a failed read keep the project root, with a line saying why, and that never stops an install. --epic-id still overrides it, and a filled bug_destination section stays unless --force. An Epic is never created.
  • A script with a token now makes one read of the project list at the end of an install with no --epic-id. Its bug_destination may therefore come out filled where it used to stay empty.
  • The coding CLI comes from what is installed, at a terminal. The only CLI found is taken and said aloud, several are asked among, and none is refused by name with --cli as the way on. Previously the question always offered every profile. A launcher.command the install cannot read a CLI out of still gets that question. Scripts change nothing: they are refused with the list until they pass --cli.
  • The account comes from the token, at a terminal, once the server has GET /api/users/current: one account is taken and said aloud, several are picked from a list. Until that ships the call answers 404 and the question runs as it did, with no alarm. Any other failure of the call says why in one line and then asks.
  • bug_destination no longer claims to be where the runner files its own crash reports, in the section's comment, the settings summary and the docs. It never was: it places the bugs a run files over failing tests, and crash reports find their Epic on the server. Existing config files keep the old comment until the section is rewritten.

init keeps its details in a log

  • A successful init now shows the questions, the warnings and errors, and a closing summary. Everything it used to print goes to ~/logs/mcptask_runner/install/<slug>_<YYYYMMDD_HHMMSS>.log (under --home-dir when given), mode 0600, without colour. The summary names the file.
  • Scripts: stdout is now the opening line and the summary, with or without a terminal. Anything that reads init's stdout for a line it used to print has to read the log, or pass --verbose, which brings the whole output back and still writes the log. stderr and the exit code are as they were; a failed install's error gains a Full log: line after it.
  • A log that cannot be opened stops nothing: one warning, and the whole output comes to the screen.
  • The section tags ([Installer], [TokenProvisioner]) stay in the log and leave the questions on the screen.
  • update is unchanged.

A CLI that exits 127 is reported as not found

A scheduled job whose PATH did not hold the coding CLI ended with the CLI's
shell saying claude: No such file or directory and exit status 127, and the
runner's remedy blamed a refused command line and sent the reader to the CLI's
installed version (#14664, from the
report #14243).

  • Status 127 now says the program was not found on the job's PATH. With launcher.command set, it asks for an absolute path in launcher.command or the program's directory on the job's PATH; without it, for launcher.command set to the CLI's absolute path or its directory on the job's PATH.
  • Every other status keeps the old wording, word for word: the program ran and refused the command line, so the version is still the thing to check.
  • The text is the one in the run log and in the bug piece the failure files. Nothing else changes: the run still ends once, without a retry.

A bug report attaches only the current run's record

A harness_login_required report filed at 08:00 by a process that had run no task
carried a Triage record forty days old, so whoever opened it read another session's
data (#14121, fixed in
#14665).

  • A report attaches a run record or a runner log only if this process wrote it. Without the failing attempt's own record, the newest one is attached only when it was last modified no earlier than the process's start (less two seconds, for filesystems with coarse timestamps). Before, it was simply the newest on disk, of any age.
  • When there is none, nothing is attached and the report says so in one line of its body: No run record was written by this process, so none is attached. and the same for the runner log. A customer's report says it too, and its "Where the full record is" list reads runner log: none was written by this process under log/ where it used to say none found under log/.
  • Unchanged: the record of the attempt that failed is attached whatever its age. A crash or an anomaly before any task ran now carries no run record, where it used to carry whichever was newest.

The story sweep rides out a dropped connection

Four story_sweep_failed bug pieces in October were one laptop's VPN dropping for a
moment, under git ls-remote and under a Story read
(#14661).

  • The sweep now tries each of its two reads up to 3 times, 3 seconds apart, and files story_sweep_failed only when every attempt failed. The piece is the same as before, with the attempts added: (3 attempts, 3s apart).
  • Retried: a failure of the story-branch listing, and a Story read that got no answer (dial, reset, timeout, cut-off body) or a 5xx. A 4xx, a refused account, a body that does not parse and a missing token are filed at once, marked 1 attempt: a definite answer, not retried.
  • Not retried either: a listing git's two-minute deadline killed, which has hung for the whole of it already; it is filed after one attempt and says so. And once a listing outage is reported, later boundaries list once, as before, so an outage on record costs no pauses at every task boundary.
  • Every failure that is retried leaves a warning in the run log saying what failed and that it tries again. A stop during a pause is seen when the pause ends, a few seconds later at most, and the sweep then ends and files nothing.

pr merge carries a tree-identical head's statuses to the merge commit

A squash merge creates a new commit with no commit statuses, even when its tree is
the head's. A branch protection that requires a status then refused the next merge,
such as a story branch into main, over a verdict that had already been given
(#14335).

  • On GitHub, after a merge whose commit holds the identical tree of the pull request's head, the head's successful commit statuses are posted onto the merge commit with the same context and link. Each one has the description carried from <sha>: identical tree.
  • Only success is carried. A context the merge commit already reports itself is left alone. Check runs are not commit statuses and are not carried.
  • Different trees carry nothing, because the branch moved on and the check has to run on the merge commit for real. A merge commit that is the head itself needs nothing.
  • One [pr] line on stderr says which of these happened. stdout is unchanged.
  • A carry that fails is a warning, never a non-zero exit. The merge has already happened, and the warning names the merge commit, the contexts that were not carried and why. Nothing bypasses branch protection.
  • GitLab and Bitbucket carry nothing yet, and the line says so.
  • The statuses are posted as the gh user. Posting one needs write access to the repository, which the merge needed too.

init recognises an Xcode project

An iOS or macOS app with an .xcworkspace or .xcodeproj at its root and no
Package.swift got no test commands, so its runs stopped at /test-runner
(#14209,
#14662).

  • On a terminal, init now asks for the scheme and the destination. Each question shows a proposal and the reason for it: the scheme the project's files share, an iPhone simulator of the newest iOS runtime on the machine, or platform=macOS for a project that builds for macOS alone. Enter takes the proposal and anything typed replaces it. Enter with nothing proposed writes no file. The declaration is xcodebuild test -workspace|-project '…' -scheme '…' -destination '…' under unit and all, with every value in single quotes, and has no file or line.
  • A workspace at the root is used over a project, and the project.xcworkspace inside an .xcodeproj does not count. With several at the root, init asks which one and proposes none.
  • A scripted init and update write nothing for such a project. They name the missing values, print the command with <scheme> and <destination> to fill into .claude/test-commands.json, and add what is proposed for each.
  • A Package.swift at the root still wins, with swift test, exactly as before.
  • The lock guard (check_test_lock) now drops a quoted argument when it reads a declared command. Without that, a quoted xcodebuild test was never recognised as a test run. A declaration that is only a wrapper around quoted text, such as sh -c 'cd web && npm test', is not reduced to sh -c, which would have refused every sh -c during somebody's suite; the guard's note says the declaration names nothing it can recognise. A host gets the new guard with mcptask_runner update.

Two reports stop blaming the child for what happened outside it

Two anomaly reports described a mistake the child had not made
(#14676, from the reports
#14359 and
#14223).

  • story_pr_wrong_base says when the story branch was already gone. When a Story task's pull request merged outside its story branch and that branch is no longer on origin, the report says the Story was merged or its branch deleted while the task ran, and that there may be nothing to move. A live branch keeps the old advice, and a remote that cannot be read adds why it could not tell.
  • origin_rewritten no longer assumes a refused push. The runner sees the URL before and after, not who changed it, so the report now says the change may have come from outside the task: a person, an IDE or another session in the same checkout. It still names both URLs and the command that restores the old one.

An mcptask.online outage no longer ends the day

On 2026-11-04 mcptask.online answered 502 Bad Gateway for about five minutes. A
triage could not reach its MCP server and answered with an error twice, the runner
wrote A task failed, stopping, and the launchd job was off until somebody restarted
it by hand an hour later. Its bug reports met the same 502, so the run also ended
non-zero (#14726).

  • After a triage or a task ends in error, the runner asks mcptask.online itself (GET /api/<account>/users/current, with its own token). When that gets no answer or a 5xx, the error is the outage's. The card shows mcptask_unreachable, the runner starts no work and checks again every minute until the end of the work window, and once the server answers it clears the card and runs the round again. A task the outage interrupted is picked up again like any other task in progress.
  • The log says it once at Error level when the outage starts: what the check got, what the outage interrupted, and until when the runner waits. One line when it ends gives how long it lasted. A stop or the end of the work window ends the wait as stop_requested or end_of_workday, never as a failed task.
  • Nothing is filed about the outage, during it or after it. The run's own bug report is dropped, and the log says so. A 4xx is an answer, not an outage, and is handled as before.
  • An outage of the MCP endpoint alone, with the REST API answering, is not this. It is the next section.
  • An error while the server answers still stops the run and is reported exactly as before.

A triage that cannot reach its tools is waited out

A triage that reports its own failure on both attempts of a round while mcptask.online
answers the runner means the coding CLI cannot reach its mcptask-online MCP server: a
broken .mcp.json, a token in it the server rejects, or tools the CLI does not allow.
It used to end the day the same way
(#14726).

  • The card now shows triage_tools_unreachable with the triage's own words and what to check on which machine. When the runner's own token is refused too, the message says so.
  • One report is filed for the incident, with the remedy, in place of a report per triage.
  • The runner runs a fresh triage after every short wait until the end of the work window. That is short_wait_minutes, 5 as the installer writes it, because each check is a paid triage, and a check is one triage, not two. The card is cleared once a triage picks a task or answers in its own words.
  • A stop or the end of the work window ends the wait as before. Any other error with the server answering still stops the run and is reported.

A panic in a background goroutine is reported like a loop panic

A panic on the goroutine that applies the dashboard's Stop and Start, the one that
clears a piece from the skip list, or the one that stops a child whose piece was
reassigned used to end the process with exit 2 and nothing else: no bug piece, a
card frozen on a runner that was gone, the reason only in the host's stderr log
(#14736). So did a panic in the kill
that follows a command that operates on the runner's own job.

  • Each now files a loop_crash piece that names the goroutine and carries the stack, puts runner_crashed on the card, retires the card, and then ends the process with exit 2, the code a panic on the loop itself ends with. It is not swallowed: after a panic the runner does not know what state it is in.
  • The instance lock is left in place, so the next start clears it as stale and reaps a coding CLI that the dead runner left behind.

The daily loop keeps working when a bug report is refused

When mcptask.online refused a bug report with a 401 or 403, which usually means the
token's user is not a member of the project that holds the runner's Errors epic, a
daily runner ended at the end of that day and exited non-zero. A refused report is
not a precondition of the work, so it no longer stops anything
(#14735).

  • The card now shows bug_reports_refused while the runner works. It quotes the server's answer, says how many failure reports are only in the machine's log so far, and names the fix: add the user whose token the runner sends to the project, or point the token variable at a member's token, then restart the runner. The refusal still holds for the rest of the process, so the server is asked once and nothing is filed until the restart.
  • The log says it once at Error level, with the server's answer and the remedy, next to the reporter's existing REFUSED block. A report lost to the same refusal later is logged at most once an hour, with a count, instead of a line per report.
  • Exit codes do not change. A run that ends after it lost reports, refused or not, still exits non-zero. That covers daily on a stop and every other mode at its end, where the card's ending, bug_reports_unfiled, now carries the same remedy. A launchd job in today or today_auto_squash that did all its work but had a report refused therefore still records a failed run. That is #13090's deliberate choice, and the card is what says why.
  • A report lost to an outage or a timeout is handled as before: the loop goes on, and the run ends non-zero.

An urgent bug on a dirty branch waits for a person instead of ending the run

When a task files an urgent bug, the runner switches the checkout to main so the bug
runs next. If uncommitted changes on the task's branch made git checkout main
refuse, the run ended with exit code 0, three Error lines in the log, and nothing on
the card or the dashboard (#14733).

  • The card now shows urgent_bug_dirty_branch. It names the bug, the branch, the project directory and what git said. The remedy is to commit, stash or discard the changes on that branch. The runner never does any of the three itself.
  • The log says it once at Error level, and one report is filed per incident, because nobody may be watching the card.
  • The runner tries the same switch again after every short wait. Once it goes through, the card is cleared, the bug is pinned and runs next, and the mode carries on as it does after a clean switch. A story-locked loop still hands the bug back to its parent, and a single-task mode still ends with the bug pinned for the next start.
  • A stop or the end of the work window ends the wait as stop_requested or end_of_workday. A daily runner whose window closed on the wait tries again before the next morning's first triage. A runner that is started again from scratch does not remember the bug: it resumes the interrupted task, and the bug waits in the queue, as it did before.
  • While the install's task holds its pin, a dirty branch is not waited on. The bug cannot be pinned before the install's files are on the base branch anyway.

A usage limit that outlasts the runner's waits no longer ends the day

The runner waits out a spent usage window of the coding CLI by itself: eight waits,
about three hours. A window still spent after that ended the run in error, the error
counted as a failed task, and the day stopped on A task failed, stopping, hours
before the limit reset on its own
(#14734).

  • The card now shows rate_limited with the CLI's own words, what the limit interrupted and, when the CLI says when it resets, that time. The runner starts no work, waits until a minute after that reset or, with no reset stated, re-checks after every short wait (short_wait_minutes), and never waits past the end of the work window. Without a work window it waits as long as the limit lasts.
  • A re-check is the round itself, run again: a triage, and the task the limit interrupted is picked up again like any other task in progress. While the card shows the limit, a child that meets it still spent ends at once instead of starting another three hours of waits. A refused request costs no tokens. Once a child gets past the limit, the card is cleared and work goes on with the normal waits.
  • The log says it once at Warn level when the wait starts, with until when, and in one line when it ends, with how long it lasted. A stop or the end of the work window ends the wait as stop_requested or end_of_workday. Nothing is filed: a usage limit is the account working as designed.
  • Claude Code's reset time is read from its own rate_limit_event, never parsed out of a sentence. Codex and OpenCode state no reset time on their streams, so for them the runner re-checks after every short wait.
  • A hard cap with a date on it still ends the day, as before: Claude Code's "You have reached your specified API usage limits", which the profile names as a usage limit. Codex's and OpenCode's cap sentences (out of credits, a spend cap, a spent quota) have always been read as a usage window, so the runner now waits them out too, with their words on the card.
  • The mid-task quota guard, the day's budget on mcptask.online, is unchanged. ## A report no longer lists a settings file the project never had

Nearly every runner bug report carried Not attached: .claude/settings.json … no
such file
, and that line hid the gaps that matter
(#14785).

  • A missing file is listed only when init writes it. These are the MCP configuration, the permissions file and the trust file: .mcp.json and .claude/settings.local.json for Claude Code, both config.toml files for Codex, and opencode.json for OpenCode. Other files a profile attaches belong to the project or the operator, such as .claude/settings.json or OpenCode's user-level config. When one of those is absent, the report leaves it out.
  • A file that exists but cannot be read is still listed, whichever kind it is. ## One host refusal is one bug piece a day

The same refusal of the same task on one machine was filed three times in a
morning (#14784, from the reports
#14751,
#14762 and
#14773).

  • A host_refused report is keyed on the ending and the project only. The error message used to be part of the key, and each retry after the host wait described the refusal in new words, so the throttle saw a new failure every hour. The same goes for harness_login_required, the other ending that belongs to the machine.
  • Those endings are held for 24 hours instead of 6. A second report waits for the next day; every other failure keeps the 6-hour window.
  • A report the throttle turns away now says so in the log, with when the first one was filed. The card still shows the refusal as before.

Git credentials origin refuses are waited out, not filed

On 2026-11-04 three Macs came back from a reboot with no SSH key in the agent.
Every git call that reached origin was refused with Permission denied
(publickey)
, and each filed its own bug piece — the story sweep, the plan of a
task's branches, and every child whose push failed: eleven pieces for one
ssh-add (#14783).

  • The card now shows git_remote_auth with git's own words and the fix: load the key into the agent (ssh-add --apple-load-keychain on macOS, ssh-add elsewhere) or, over HTTPS, refresh the credential git's helper stores. The runner starts no work, re-runs git ls-remote origin HEAD after every short wait (short_wait_minutes), and carries on by itself once origin answers. A stop or the end of the work window ends the wait as before.
  • Nothing is filed about it. The plan of a task's branches no longer sets the task aside over it, the sweep no longer retries it as a dropped connection, and a child that answers host_refused quoting the same refusal has its report dropped and its task run again once origin answers, instead of its own probe being re-run.
  • Only git's words for a refused credential count: Permission denied (publickey), Authentication failed for '…', could not read Username or Password for '…'. A reset connection, a DNS failure or git's timeout is retried and reported exactly as before. ## A refused task waits for a person, and the child no longer looks for a way in

A task that needed admin rights where this machine has pull-only was reported
host_refused correctly, then run twice more the same day. On the third run the
child searched the machine for another credential, tried every SSH key and
created a repository it could not delete
(#14786, from
#14749).

  • The prompt forbids the workaround. Wherever it explains how to report a host refusal, it now says: when a service refuses this machine's identity or access, do not look for, try or switch to any other credential, token, key, account, login or password store, and do not create probe or test resources; report what was refused and stop. This applies to every executor and every harness.
  • A refusal nothing can re-check is not retried today. If the child gives a probe the runner can run, the runner still waits on it and resumes. If it gives none, or one the runner refuses to run, the task goes on today's skip list as host_refused and the loop moves on to other work. The same applies to a refusal the child scopes to the task. Retrying after every long wait is gone. The hourly revival that brings a failed task back does not apply to this entry, so the card lists the task as host_refused until tomorrow.

A step only a person can take becomes that person's task

A task finished except for the owner's sign-off was set aside on two mornings
running. Each time the child tried BlockTaskTool, was refused (only a task's
author or a manager may block it), and left a comment nobody's queue showed; the
set-aside let go at midnight and the next morning said it all again
(#14724, from
#14467).

  • The child hands the step over as a Task. On out_of_scope — now also the status for "what is left is a step only a person can take" — and on a host_refused the runner cannot re-check, the child creates a Task with CreatePieceTool at the project root, assigned to the waiting task's author (or the project's boss when the author is the runner's own user), naming the exact step, with blocks_relative_ids so the waiting task is blocked until it is finished. It reports the new Task as handoff_task_id. The BlockTaskTool step and the "needs blocking by hand" note are gone from every executor and harness.
  • One hand-off per waiting task. The child first looks for an open piece the runner's user already filed that blocks the task, and reuses it.
  • The set-aside holds until the hand-off is finished, across days and restarts: the skip list (tmp/mcptask_runner/set_aside.json) keeps the hand-off's id and asks mcptask.online once a day whether it is completed or approved. Then the task comes back and the next run continues it.
  • A refused hand-off is reported. The child posts the step as a comment, as before, and adds handoff_refused; the runner files it as a handoff_refused bug and holds the task for today only.
  • Needs the server side from projectoid_ii #14723 (blocks_relative_ids on CreatePieceTool). On a server without it the call is refused, and that refusal is what gets filed.

A Stop from the card during a Story's merge pauses the runner, not ends it

In the auto-squash modes, the task-boundary sweep runs a finished Story's merge
as a child of its own. A Stop pressed on the runner card while that merge was
running — or already in force when the sweep reached it — came back from the
merge as "stopped from the dashboard", nothing caught it there, and the run
ended as runner_crashed with a bug piece filed
(#14789).

  • The sweep holds on a Stop, as the triage after it always did: no merge starts while the card says paused, and the sweep runs once Start is pressed.
  • A merge stopped mid-run is no verdict. Nothing is filed, the Story is not counted as tried, and the next task-boundary sweep after Start merges it.
  • The same for the merge a task starts itself when it finishes its Story: a Stop then keeps the task's own verdict instead of discarding it and triaging the round again.

The banner says where the runner's own failures go; a refused card is said in the log

A runner on Trurl's Mac mini waited out a host_refused for hours with no
card on the dashboard, and its version said "Bug destination: Epic #6136"
while the runner's own failure report had gone to project 70
(#14790).

  • Two lines where there was one. bug_destination only ever told the coding CLI where to file the bug for tests already failing on main, and the Bug destination: line now says so. A new Runner failures: line right under it says where the runner files its own failures: jchsoft project 70, Epic #11480 on our account; the project the run worked, under the bug bucket the server names, on a customer's; or that they are NOT filed and why (the kill switch, no token, a CLAUDE.md with no project_relative_id).
  • A snapshot mcptask.online refuses is said in the log. The server answers a frame it drops (parked_seat for a parked AI-agent seat, unsupported_schema_version) and the runner used to ignore that answer, so a card the server was refusing looked, from the machine, like one on screen. The first refusal of each kind is now a [EventStream] mcptask.online REFUSED this runner's snapshot warning naming the error.
  • No change to what a waiting runner sends. During a host-condition wait the card gets a frame every minute (status: "waiting", attention set, ttl_seconds/closed_at null) on top of the two-minute heartbeat, as in v0.3.48. The missing card on Trurl's machine is for mcptask.online to explain.

Changelog

Other

  • c979caeacdfe7426f149a38adee1273f334eb9fc [#14457] bin/release refuses a tip that would stop the Release workflow
  • 34078b2a9ef8181f705f277af3c948f6d2a60164 [#14526] init asks which project this is, and run refuses without it
  • 4ca6a376391d5e8d9b8848d6e3112c330739b50c [#14527] init commits its own files and switches the job on
  • 3f36e10529345487a308332518dd7863236d401d [#14556] init finds the account, the errors Epic and the coding CLI itself
  • 1edf3f5d705c95fcf83eb8c907a9bc93a55e71fb [#14557] The install's files reach main through a pinned task
  • 9a3ca4b7a967cf5d2e97f85ba2add1e9d43eb3c6 [#14558] init keeps its details in a log; the screen shows questions, errors and a summary
  • a34a98883ff1f64f6811cc4c2ceb17dd76009030 [#14567] The install's task merges on basic checks without host CI, and works with no remote
  • b3be36c1f04190b4f8f592f595a0d9beecb4601a [#14568] init runs the install's task in front of the person, and the conclusion reaches them at once
  • 52a3c7ca0e08d64d6638d079cc9220dc8a8e5bbc [#14587] A pending install works from its branch, ignores the day's budget, and concludes before the job
  • 91136b44e976a11a97a4698d25211036bdda350a [#14587] A re-run leaves an unchanged manifest alone, for Windows' sake
  • c8c014188724bf0c34b76ec26143b4b2510f8a1f [#14587] CLI tests keep the run log out of their own directories
  • ff95723b36a6009502d13e863ea36e3ae4df5c29 [#14660] The install's progress logs wait for the plan call's answer
  • 94da526b6fdd47167fd95c99895a9b52742dcf3a [#14661] The story sweep tries a dropped connection again before it files story_sweep_failed
  • 97e8b7420b0c50d1026d6d7ba6d016faa0a6dc80 [#14661] [#14662] The sweep's retries stop at a hung or reported outage, and the lock guard keeps sh -c free
  • f07b04f29b2d9fcb6783f703c5f165296d309536 [#14662] init recognises an Xcode project and asks for its scheme and destination
  • 4039d2b135eeaed09fedc5c048900f5c682744b2 [#14663] A merge commit with the head's tree gets the head's passed statuses
  • 2ab476e7bc0292aa485e37ea72bacb5dfcb13f9b [#14664] A launch failure with exit status 127 says the program was not found
  • 0a7e1b6bfba221ddaa13e010101567cb8e4884e7 [#14665] A bug report attaches a run record or runner log only if this process wrote it
  • 383a02ca5ba186566eab2a119ca78ac4fe11d91d [#14676] Two anomaly reports stop blaming the child for what happened outside it
  • 10dd6c209a6c4923eea0c2c3440ea44f3aaea0ca [#14724] A step only a person can take becomes that person's hand-off Task
  • c74921a7739b8707dee0b218378535e74e0f62af [#14726] An mcptask.online outage and a triage without its tools are waited out, not ended on
  • 256b83090f7b4fa70ee19ee67869380e6f6576a9 [#14732] Review fixes: only a triage's own marker is the tools condition, and six smaller ones
  • 9769bc10dfa35257dadaf9dba7d16701f550f629 [#14733] An urgent bug on a dirty branch is waited out on the card, not a silent end
  • a62150dd6a3fc7efaa849216b66a183332ee9758 [#14733] The dirty-branch stress day's person tries the commit again after an index.lock
  • ff1dec25f0a47ff8141f5490d629a29dbcd6be74 [#14734] A usage limit that outlasts the engine's waits is waited out, not a day-ending error
  • 80b2c0f3024632efdea4cadb9084e69c75fbaed7 [#14735] The daily loop keeps working when mcptask.online refuses a bug report, and the card says so
  • 37242cd23c8dd4d9ba4c8560d8b1389be077d48c [#14736] A panic in the pause watcher, the skip-list watcher, AbandonReassigned or the self-operation kill is reported and ends the run like a loop panic
  • 4bd755e1db4de56482d9d321733f551e1833d7b7 [#14783] Git credentials origin refuses are waited out on the card, not filed per call
  • 061b16da86299cf4503dc89460b8ba5769cee4e3 [#14784] One host refusal is one bug piece a day
  • 853f1b7530cea81bd1b268f67fee39e2240278e5 [#14785] A bug report no longer lists an optional config file that is simply absent
  • fbd9800e019521d5663d8d68406c7bebd2d4a83f [#14786] A host refusal is never worked around, and one nothing re-checks waits for a person
  • a23717fd748500907ca5cc6ce6e8a965d27492cb [#14789] A Stop from the card during a Story's merge holds the runner instead of crashing it
  • 09cd1ded96eb6b8ccde3dc71b9cd67de15e39b5f [#14790] Banner says where runner failures go; a refused snapshot is logged
  • 1482ca7c8767c63188ef771895be17d637c3a175 docs(release): the next-tag notes carry a heading for the tag and CHANGELOG [skip ci]
  • 6934b439d684e8a1e3ac3de6524928ac542a3901 docs(release): v0.3.48 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.48

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.48 carries this binary; no wrapper changes.


init asks which coding CLI to use (#14405)

On a terminal, a project with no harness: key now gets a list of profiles to choose from, with nothing
preselected, instead of a refusal. That covers the bare
bundle exec rake mcptask_runner:install and npx @mcptask/cli init. Without a
terminal init still refuses, and the refusal now also names
bundle exec rake "mcptask_runner:install[--cli <name>]", because the bare
mcptask_runner is not on PATH until a first install has succeeded. Nothing to
do on an installed host.


Changelog

Other

  • fcfe0a0e13e275c51a707e19f4c7006d669f3a1b [#14145] A day that reaches its window has not left over the host
  • f8cbfa19072573abb26d6ca8673b5ab2d55c14b6 [#14405] init asks which coding CLI to use when it runs on a terminal
  • 3a6f5eab9159def88f13262648c31dc9513e0941 docs(release): v0.3.47 shipped, the next-tag notes start empty
  • ea0353c92c1a4d447568d4108eb8a20a3a41993c lint: satisfy errcheck in golangci-lint 2.15 on a bare channel receive

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.47

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.47 carries this binary; no wrapper changes.


workflow reads reviews on GitLab and Bitbucket too (#14053)

The workflow mode used to say "review handling is unavailable" on GitLab and
Bitbucket and work tasks only. It now works in human review notes on those hosts
as on GitHub. A note counts as a bot's when the host marks its author (GitLab
bot, Bitbucket type: app_user) or the account is named like one
(project_<id>_bot_<hash>, group_<id>_bot_<hash>, [bot], -bot, bot-).
A CI account with a plain name is not recognised and its notes count as a
person's. README and docs/catalog.yml now set pr_only, workflow and
today_auto_squash side by side. No action needed.

A machine that refuses the work is waited out, not ended on

A child that cannot finish because this machine refused something it needs — the
dev database not running, an empty SSH agent, a git host refusing this machine —
now says whose fault it is: "scope": "host" or "scope": "task" next to
"reason": "host_refused", and for the host a "probe", one cheap command
that exits 0 once the machine is fixed
(#14051).

  • task: the piece is set aside for the day like a failed task, and the run goes on. Until now any host_refused ended the day (A task failed, stopping), which is how three runners went quiet at 08:00 on 2026-10-21.
  • host: host_refused goes on the runner card with the child's words and the remedy, and the runner waits. It re-runs only the probe, backing off from short_wait_minutes to long_wait_minutes, clears the card once it passes, and retries the task. Without a usable probe the task is retried after every long wait. A second host_refused on another task the same day is the host's whatever the child said.

The probe runs without a shell, in the project directory, with a 30-second
timeout; one that needs shell syntax, acts on the runner, or names a command
that is not installed is refused and logged (… which the runner will not
run
). Nothing to configure. What to check on upgrade: a runner whose card shows
host_refused is waiting for a person at that machine — fix what the card
names and leave it running. The prompt changes (the failure option asks for the
scope and the probe), so prompt goldens moved; the codex and opencode vocabulary
goldens did not.

A read of the runner's own source is no longer refused (#14072)

The self-operation guard (Story 13557) refused a read-only grep for "kill" in
a directory under the runner's own name — on 2026-10-22 a task exploring the old
gem's source on Karel's Mac mini was stopped and set aside indefinitely
(#14072). A stop verb (kill,
pkill, killall, launchctl kickstart|kill|bootout|…, systemctl … restart,
shutdown, reboot) now counts only as the command a shell actually runs —
past sudo, env, nohup, timeout, xargs and leading VAR=value, and
inside bash -c, sh -c, eval and find -exec scripts — never inside a
quoted pattern, a commit message, an echo or a heredoc. Real restarts of the
runner (launchctl kickstart … online.mcptask.runner-…, pkill -f
mcptask_runner
, pgrep … | xargs kill, kill $PPID) are refused exactly as
before, by the detector and by the Claude Code pre-tool gate alike.

What to do on upgrade: a task set aside by this false positive (its card and the
task note say "refusing to let the task operate on the runner's own job" over a
grep/rg/sed) is picked again once its description changes, or after you
clear the runner's skip list for that project and restart it.


Changelog

Other

  • b67d6cadef071e49d337b51eb50950dcc5f6c669 [#14051] host_refused names its scope and a probe; a host cause is waited out on the card
  • 7d585515f05efa4531a51aedcbb5f87f7b2afdb2 [#14053] workflow reads reviews on GitLab and Bitbucket: bot detection, three modes documented
  • 973684023e7f118336c440dd2fc31473ac426386 [#14072] A stop verb counts only in command position: reading the runner's source for "kill" is not refused
  • f2d8761b01fe4a8457f69a647a84adfbad6f8ceb [#14072] Tokenize the command as written: xargs flags keep their case, the command word is compared lower-cased
  • 4e7fab8193dd05a835964d668277fedd49aaea87 docs(release): v0.3.46 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.46

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.46 carries this binary; no wrapper changes.


  • The API token no longer appears in the /cable URL. The EventStream connection now sends it as an Authorization: Bearer header, so it stays out of the server's access logs. Needs a mcptask.online that accepts the header (live since #13961); upgrade every runner, then the server drops ?token=.

today waits on an empty queue instead of exiting

today now does on an empty queue what today_auto_squash already did: it
waits — short_wait_minutes at first, long_wait_minutes once the queue has
stayed empty for a while — with WAITING on the runner card, and an assignment
to the runner's user on the dashboard ends the wait at once, so a task assigned
at 11:00 is started at 11:00 rather than at the next scheduled run
(#14033). The run still ends
where it did: at end_of_workday_hour (Past end of workday in the log), when
the day's hours are spent (Daily quota exceeded while waiting for work), on a
failed task, or when it is stopped. workflow waits the same way since

14032 — see below.

The line a waiting mode writes when it wakes past the hour now reads Past end
of workday (HH:MM) after the wait, stopping …
in every waiting mode, instead of
Now past end of workday …, so one phrase finds every end-of-day stop in a log.

What to check on upgrade: a host that runs today without
end_of_workday_hour
used to exit on the first empty queue, and now idles
until its daily hours run out — which, with nothing to work, may be never that
day. A today job that should stop at a fixed time needs work_window set
(mcptask_runner init --until HH:MM writes it), and anything that started
today and waited for it to exit, a script or a chained job, will now wait
until the end of the workday.

The today mode is now called pr_only; today still works

today said when, not what: the mode works the queue and ends the day as a set
of open pull requests, which is what separates it from workflow (PRs and their
reviews) and today_auto_squash (PRs merged once CI passes)
(#14054). The canonical name is
now pr_only: mcptask_runner run pr_only, init --mode pr_only, and the
prompt in init offers it under that name.

Nothing has to be changed on upgrade. today stays an accepted spelling —
on the command line, in init --mode, in the launchers and plists already
installed — and it is not an error. A run started as run today says once, on
stderr, that today is the old name. A day-state handover written by an older
binary under today is still resumed. update does not rewrite installed
launchers; re-run init --force to get pr_only in them. today_auto_squash
keeps its name. The runner's card and snapshot never carried the mode name, so
the dashboard needs no change; the name appears in the run log and the
invalid-mode error, which now lists pr_only in today's place.

Whatever stops the runner is on its card; a CLI that cannot start is waited out

A coding CLI that cannot start — it exits before writing a single stream line,
launch_failed — no longer ends the day's work as a failed task
(#14009). It is handled the way a
missing login is: the card carries attention with code launch_failed, the
CLI's own words and a remedy naming the machine, the runner re-checks after
every short wait and tries again, and it clears the card once a child has
started. No kickstart is needed after the binary is put back.

The startup preflight is split by who can fix the refusal:

  • Configuration — the harness key, a binary the profile cannot find, a launcher.command that contradicts the profile, a settings file the profile refuses — still refuses to start, but now publishes the refusal to the card first (harness_not_configured, harness_binary_missing, harness_settings_refused) whenever the token allows it.
  • A person at the machine — a profile's usability probe (binary.preflight, e.g. codex login status) that fails in words that are not a login — is no longer a refusal. The run starts, says so in the log, and the work loop waits it out with harness_unusable on the card.

Every other way a run ends now leaves its reason on the card too: the frame
before the tombstone carries the ending as its message (window closed, budget
spent, queue empty, stop requested), and the endings a person has to look at
carry attention as well — day_ended_task_failed,
day_ended_quota_unanswered, runner_crashed, account_refused,
bug_reports_unfiled. A card that retires with attention on it now lingers
12 hours instead of 60 seconds, so the reason is still there when somebody
looks. attention.code is an open set on the wire; a card that renders
message and remedy generically needs no change.

Nothing to do on upgrade.

workflow is a scheduled mode: tasks, and the review comments on your pull requests

workflow is now the third scheduled mode, between pr_only and
today_auto_squash, and init offers it as answer 3 (none moved to 4)
(#14032). It works the queue and
waits on an empty one exactly like pr_only, and ends the day the same way. In
between — after every task, and on every round that finds the queue empty — it
lists the open pull requests of the account the git host's credentials belong
to, and one carrying a human comment or change request newer than its head
commit
gets one child run: the reviews prompt pinned to that pull request,
which fixes, pushes, runs CI and then replies under each note it worked in
(Addressed in <sha> / Not addressed: <reason>). Bots are ignored; the pull
request's own author is NOT — the runner works under your account, so your
comment on "your" pull request is the review — and the runner's own replies are
told apart by the line _— mcptask_runner_ every pr comment note ends with.
Nothing is launched when nothing qualifies, and nothing
is ever merged. A round that fails is not retried that day until a new push.

What to check on upgrade:

  • Anything that ran workflow by hand gets a different mode. The old two-phase run — a paid child per open pull request until one said no_reviews, then the queue until it was empty — is gone. workflow now waits on an empty queue until the end of the workday, like pr_only, and its outcome is one list of verdicts rather than {"reviews": …, "tasks": …}.
  • GitHub only, for now. On GitLab and Bitbucket the runner cannot yet tell a bot's note from a person's (#14053): workflow works tasks there and says on the card and in the log that review handling is unavailable.
  • A project whose git host cannot be resolved refuses workflow (no git_host: and no recognisable origin) — naming why, instead of a day of tasks with every review silently unread.
  • New: mcptask_runner pr comment <n> [--reply-to <id>] --body … on all three hosts; the card's snapshot gains pr_number (null outside a review round, schema_version unchanged — the dashboard may render it whenever it likes); review rounds are remembered for the day in tmp/mcptask_runner/pr_rounds.json.
  • The review and reviews prompts gained the same reply step.
  • pr reviews on GitHub now includes the pull request's conversation comments (a third read, issues/<n>/comments), as plain notes with neither a state nor a path — what GitLab and Bitbucket already returned. A reviews run therefore also sees a review written only in the conversation.

Changelog

Other

  • 9c74f14b46d7c0eb93880d157758e0d31c6d6005 [#13964] Close the rejected dial's response body and group the websocket import
  • 7827c473d6fc5a0514c0fe0287a6018f1d42de25 [#13964] EventStream sends the API token in an Authorization header, not in the /cable URL
  • 75bd3ccdb016edbdcc614a147a746ce47c100e44 [#13984] The story-merge stress day ends on the merge, not on a three-second clock
  • 1b543daa2c4ba926ee595d40959077238c7d3f19 [#14009] Anything that stops the runner is on its card; a CLI that cannot start is waited out
  • ed7518224c4eb755e96e80a6b263fa2f0995f02e [#14032] Fix the two lint findings #14054 left on batch-1021
  • f7901d0189a3f3ef296a7b6317d56c51eb18bd69 [#14032] workflow is a scheduled mode: tasks, and new human review notes on your open PRs
  • 7a25dbba145ae356354657fb36b597f20f60d145 [#14032] workflow sees GitHub conversation comments, and the PR author's own
  • e875c88ff3c14aee08d0b32c81bd926043c5c114 [#14033] today waits on an empty queue like today_auto_squash
  • 8310dafcdba544bb6582ec9fbce4040b452558b6 [#14050] prhost lists the current user's open PRs with author and head commit time
  • 4ea7308930362768c6142a76cfcd319a6cd6cc7c [#14054] Check the legacy-name notice write and keep Consume's doc comment on Consume
  • aa3899cc2e10a31d3dd4aeee14a3f4ff84756992 [#14054] The today mode is now pr_only; today stays an alias
  • 2452e23459127827bb94b72dd48b7f0024f972ee docs(release): v0.3.45 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.45

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.45 carries this binary; no wrapper changes.


Stopping the runner reaches a piece request that hangs

When the runner is stopped from inside its own process, a request it has made
about one piece is now cancelled too: reading whom a picked task is assigned
to, reading a set-aside task's description, or posting a note on a task.
Before, such a request ran out its own thirty-second deadline first, the same
gap the quota requests had until
#13835
(#13845). An assignee read cut
this way is logged as the run was asked to stop before whom it is assigned to
was read
and files no assignee_unreadable bug piece, because nothing is wrong
with the piece or the server. That process-internal stop is the one the stress
harness uses; a signal stopped the process directly before this change and
still does, so production runs are unaffected. Nothing to do on upgrade.

Stopping the runner reaches a story-branch read that hangs

The same applies now to the piece reads behind story branches: planning which
branch a task goes onto, and reading a Story to see whether it is finished,
after a task or in the sweep between tasks
(#13891). A read cut this way is
logged as The run was asked to stop before … and files no
story_branch_plan_failed, story_left_unmerged or story_sweep_failed bug
piece. A task whose plan was cut is not set aside as a failure: the loop ends
with stop_requested, and the next run plans it again. A sweep cut this way
does not mark the Story as tried, and a set-aside task whose morning check was
cut is not marked as checked, so the next process that day asks again. As
above, only the process-internal stop is affected. Nothing to do on upgrade.


Changelog

Other

  • 6bcc91feeefe07b27f12b15127c95cca99d94c5d Give the stress day a 20-minute budget instead of 12
  • 46039c9268a15a7269dbd4cb79e4c5c6e3d08c1a [#13845] The loop's stop reaches a piece call that hangs
  • 6fe6d2e9d93cfa6c97d1a7af80460ff7a237cc08 [#13891] The loop's stop reaches a story-branch read that hangs
  • 058a46c612ef96a1b8a8db5a7ba408a7bf709fef docs(release): v0.3.44 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.44

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.44 carries this binary; no wrapper changes.


A CLI that was never signed in is waited out too (#13842)

v0.3.43 waited out an EXPIRED Claude Code login. A CLI with no credentials at
all (Not logged in · Please run /login, after a logout, on a fresh machine or
after a deleted keychain item) was still the terminal not_authenticated: the
runner ended its day and the card showed nothing. Now it is the same
harness_login_required, with the same attention card, remedy, wait,
re-check and resume. That covers the startup probe as well as a refused triage
or task.

Codex gets the same treatment for its recorded never-signed-in wording: the
startup codex login status that says Not logged in no longer refuses the
run, and the runner waits for codex login on that machine, re-checking with
the same free command. An expired Codex login and every OpenCode login have no
recorded wording yet and end the run as before.

not_authenticated stays, now only for a credential no login cures: an API key
the provider refuses (Codex, OpenCode). Its message says so: "credentials were
refused", fix the key.

What an operator has to do: when the card asks for a login, open a
regular Terminal on that machine and run claude then /login, or
codex login. The runner resumes by itself; no restart.

For the web team: nothing new on the wire. It is the same attention code
harness_login_required; only its message now reads "is not signed in (its
login is missing or has expired)".

A quota endpoint that does not answer no longer ends the working day

Before each task and between tasks, the runner asks mcptask.online how much of
today's budget is spent. If one of those requests timed out, the runner treated
the missing answer as a spent budget. It logged Daily quota exceeded (quota
endpoint did not answer, fail-closed)
and stopped work for the day, even when
the time-out happened in the middle of the morning. The noon stress sweep caught
this (#13836).

What the runner does now. A missing answer still blocks new work. The runner
does not guess the budget and does not start a task on one it cannot read. It
logs The quota endpoint did not answer — no new work starts on a budget nobody
can read
, waits the configured short wait (short_wait_minutes), and asks
again. On the card it shows as waiting for the quota endpoint to answer. Once
the endpoint answers, the runner logs Quota endpoint answering again after N
unanswered poll(s)
and carries on with the same day. If the outage lasts until
the end of the work window, the runner logs that the endpoint is still not
answering at the end of the window, and the day ends normally. Modes without a
work window keep waiting until the endpoint answers or the run is stopped. These
cases keep their old behaviour:

  • an expired trial still ends the run by name;
  • a runner with no token or base URL configured still does not wait;
  • the mid-task check still lets the running task finish.

A budget the server reports as spent still ends the day exactly as before.
Nothing to do on upgrade.

Stopping the runner reaches a quota request that hangs

When the runner is stopped from inside its own process, any quota request
waiting for an answer is now cancelled. Before, it ran out its own ten-second
deadline first. That process-internal stop is the one the stress harness uses.
In the harness, three such requests in a row kept the loop alive past the 30
seconds it is given to stop
(#13835). A signal stopped the
process directly before this change and still does, so production runs are
unaffected. Nothing to do on upgrade.

Stop and Start from the dashboard (#13840)

The runner now answers two commands on its dashboard socket, for the Stop /
Start buttons on its card. runner_stop with mode now kills the running CLI
at once. The piece stays in progress with its branch and working tree untouched
(the same recovery as Ctrl-C), and the test lock is handed back. Mode
after_task lets the running task finish. Either way the runner stays up and
launches nothing until runner_start, which resumes the same piece. The pause
is held in memory only, so a restart clears it. See "Stopping and starting from
the dashboard" in the README.

What an operator has to do: nothing. The buttons appear once the web half
(#13841) ships, and it shows them
only to runners at this version or later.

For the web team: the commands are
{"event":"runner_stop","session_id":"…","mode":"now"|"after_task"} and
{"event":"runner_start","session_id":"…"} on runner_sessions:<account_code>,
filtered by session_id. Every snapshot carries the new member pause: null,
"after_task" or "paused". It is additive, so schema_version stays 3 and the
Rails side needs no new accepted version. This tag is the minimum runner version
for the buttons.


Changelog

Other

  • 4ce3f964319639510bac3688cbc3c4e97d3d03ff [#13835][#13836] An unanswered quota poll is waited out, and the stop reaches it
  • a082468e0e1e0ed0e7aeb84923c47dcb9630448e [#13836] Build the focused day's violations with slices.Concat
  • 0dc76da36f59ba9aed9cb3a3b1904615ac9cd0fc [#13840] Stop and start the coding CLI from the dashboard
  • a5ec620808c2b09b1802e53d85d10dbb8a364491 [#13842] A CLI that was never signed in is waited out like an expired login
  • 4468137d1c5bda7a48c048ff44ee363474b58161 docs(release): v0.3.43 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.43

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.43 carries this binary; no wrapper changes.


Windows: the coding CLI runs in a Job Object (#13740)

On Windows the kill path used taskkill /T, which walks parent links from the
child's pid. A grandchild whose parent had already exited has no such link, so
it survived the kill, kept the child's stdout open and outlived the run — the
Windows half of #13730.

The child is now created suspended, put in a Job Object of its own
(JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE) and only then resumed, so nothing it
starts can be outside the job. The hard kill is TerminateJobObject, and the
kill is not done while the job still counts active processes; a job that cannot
be emptied is filed as the same process_group_survived_kill anomaly as on
macOS and Linux. Because the runner holds the job's only handle, a runner that
dies takes its child's whole tree with it.

Nothing to do on upgrade. A child that cannot be placed in a job is not run:
the attempt fails with placing process N in a process group of its own, which
names the Windows call that refused.

The stress day no longer demands a refusal of a command that was never sent (#13809)

The noon stress sweep failed with seed 1992539297 on three self-operation findings at
once: a launchctl kill that nothing refused, a triage refusal pinned on no piece, and
task #990042 never set aside. The runner was not at fault. The child was the last one
of the day, a triage that had been dealt kill_the_runner, and the 90 s wall ended the
day after its init line, before it fetched the piece or issued the call. The manifest
records the vector a child was dealt as soon as the child starts, and the harness read
that record as the vector having been played.

Each self-operation child now leaves a marker in the state directory just before its
shell call goes onto the wire. The harness judges only the children that left one. A
child whose call went out is still held to the refusal, the attribution and the
set-aside, so a detector that misses a command still turns the day red. The
production detector and the triage set-aside path are unchanged.

Operator action: none. This is a change to the test harness only.

An expired CLI login is waited out, not a lost day (#13827)

When Claude Code's login expires (Failed to authenticate: OAuth session expired
and could not be refreshed
), the runner used to read the refused triage as a
triage that gave up. It logged a retry it never made ("attempt 2/2"), defaulted
an empty model to genius, failed the round for a missing task_id and ended the
day, and the dashboard card showed nothing.

Now the refusal is named harness_login_required. The runner keeps running in
status waiting, and the card's new attention member names the machine and
the fix. After every short wait the runner re-checks with one tiny request on
the cheapest tier (about 0.001 USD), and it resumes by itself once the CLI
answers. It also probes once at startup. The work window and a stop end the
wait as they end any other.

What an operator has to do: when the card says the login has expired, open a
regular Terminal on that machine (not an embedded or sandboxed session), run
claude, then /login. A login done inside an embedded session can miss the
keychain item that the launchd job reads. See "An expired CLI login" in the
README.

For the web team: attention is additive and schema_version stays 3. It
is {"code","message","remedy","since"} while a condition stands and null
otherwise, as agreed in
#13828.

Also fixed: the triage retry line no longer promises a retry on its last attempt.


Changelog

Other

  • 2718f550e9f5466ecadf3b94ecc4c8bbf9310b2f [#13740] On Windows the child runs in a Job Object, so an orphaned grandchild is killed with it
  • ddaa109972b1f0691ced6fd0136f3c3d479019de [#13809] A self-operation child cut off before its call owes no refusal
  • 5f1983e264a8990d8fdc0e94de83d7e57b45a3b8 [#13827] An expired harness login is waited out with the remedy on the card
  • be85a77f0f413f4ba3ed2c3ad52a2540b40e87c2 [#13827] Document the attention member in the snapshot contract
  • cca602fd4f26c7e267a497a808c5fa0efa3ef384 docs(release): v0.3.42 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.42

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.42 carries this binary; no wrapper changes.


A piece assigned to somebody else stays skipped until it is reassigned (#13736)

0.3.41's assignee guard set such a piece aside for the rest of the day only, so
every morning the queue offered it again and the runner paid for a triage, an
assignee read and a not_assigned_to_me anomaly piece once more — the assignee
does not change overnight any more than it does in an hour. The set-aside now
outlives the day, the way a refused self-operation does: it is held against the
piece's assignee and description as the guard read them, compared with the
piece once a morning, and lifted the moment the piece is reassigned (or
rewritten). It survives a restart, and both the REST next-task check and the
child's @next keep excluding it. The "New day" log line now names each piece
it keeps and why.

Operator action: none. A piece refused under 0.3.41 is held from its next
refusal on; reassigning it to the runner's user brings it back the morning after.

A refused dashboard redial is retried within seconds, not a window later (#13776)

0.3.41 stopped dropping a socket that is lost again within 30 s of the last redial, by
arming a redial for when that window ends (#13639). But when the redial itself failed
(the dial was refused, or the socket was gone before the subscription), nothing was armed
at all. The failed attempt had restarted the 30 s window, so the snapshots that followed
could only arm a redial at the end of that new window. One refusal cost the card a second
window of silence: 57 s in the noon stress sweep (seed 269049714). In production this is a
deploy that is back up two seconds after it refused a redial, with every card staying dark
for thirty more.

A redial that ends without a connection now arms its own retry. The first comes after 1 s
and each further failure doubles the wait, up to the same 30 s. A confirmed subscription
starts the count over. A server that stays down still gets one dial every 30 s once the
doubling has caught up. The log says so in one line per retry: The redial did not bring
the socket back (N in a row); redialling in …
.

Operator action: none.


Changelog

Other

  • eb220d2875c3d848ce1cb9bc05655ab7474d1941 [#13736] A piece assigned to somebody else stays skipped until it is reassigned
  • 86cb870cea2b24ec4371c49b6365e2314ba4bd29 [#13776] A refused dashboard redial is retried within seconds, not a window later
  • 76287758d5801154ad5b84af07cf55c60142afb3 docs(release): v0.3.41 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.41

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.41 carries this binary; no wrapper changes.


A Story merges on a repository that allows squash merges only (#13718)

The Story merge asks for a merge commit (pr merge --squash=false), and a
GitHub repository that allows squash merges only refused it — "Merge commits
are not allowed on this repository" — on every task-boundary sweep, on every
host, filing a bug piece each time (13663, 13669, 13683, 13717, 13718 for one
Story of mcp4mail.online).

mcptask_runner pr merge now asks the repository which methods it allows
before it merges: gh repo view --json mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed
on GitHub, the pull request's destination.branch.merge_strategies on
Bitbucket. The requested method is used when allowed; otherwise the other of
squash and merge commit, then (GitHub only) rebase. The output's
pull_request.merged_with names the method used, and stderr says when it was
replaced. A repository that allows none of them is refused with an error
quoting the host's answer, before anything is merged. GitLab is unchanged — it
was never sent a merge method for a non-squash merge.

Operator action: none. On GitHub the merge needs one more gh call, which the
token gh already uses can make. A Story whose branch is still live from a
refused merge is picked up by the next task-boundary sweep after the upgrade.

A piece assigned to somebody else is never worked (task #13635)

Before paying for a session, the runner now reads the piece triage picked from
the queue and compares its assignee with the user behind the runner's own
token. A piece given to somebody else, or to nobody, starts no session: the run
log names both users in one line, the piece is set aside for the rest of the
day (no hourly comeback), and a bug piece is filed. No note goes on the piece.
The day's set-aside pieces now also reach the child's @next read as
exclude_relative_ids, so a set-aside piece stops being offered at all.

Nothing to do on upgrade. If the line Task #N is assigned to user X, not to
user Y whom this runner works as
appears, check which token the project's
.mcp.json names against the one the runner's scheduled job exports — on
2026-10-12 they belonged to two different users on one host. A piece whose
assignee cannot be read is not guessed at: that round works nothing and says
triage_assignee_unreadable.

An operator's stop is no longer swallowed after a refused self-operation (task #13636)

Since 0.3.39 a signal arriving while the runner was ending a child that tried
to stop the runner was absorbed as the child's own, with an afterglow of two
seconds after the child was gone. Two cases took the operator's stop instead,
and the runner then slept on (an hour, or until the next morning) with nobody
left to stop it:

  • Claude Code (gated launches): the pre-tool gate had already refused the command, so the child sent nothing — every signal in that window was the operator's. On a launch with the gate wired, nothing is absorbed any more; the log says which the pre-tool gate refused before the shell could run it … it is taken as the operator's.
  • Codex / OpenCode (no gate): once the child's own signal has arrived and the child is gone, the afterglow closes; a second signal is the operator's.

Nothing to do on upgrade. The stress harness also stops rolling an empty queue
on the first asks of a signalled day (seeds 861793654 and 2056327182 timed the
suite out, tasks #13638 and #13641).

A dashboard socket lost twice in 30 s is redialled (task #13639)

The card redials at most once every 30 s. A socket lost again inside that
window was dropped from the redial until some later frame happened to be
published after the window, so the card could go silent for longer (38 s in the
sweep, unbounded on a quiet day). The lost socket now gets one redial at the end
of the window, and the log says Connection lost again within 30s of the last
redial; redialling in ...
.

The STORY MERGE step accepts a squash on a squash-only repository (task #13725)

The step still asks for pr merge --squash=false, but it now tells the child
that a repository allowing squash merges only gets a squash, announced on
stderr, and that this is a merged Story rather than a failure. Without it, a
child reading "A merge commit, not a squash" literally could report the step
as failed after the squash from #13718 had landed. 13725 and 13727 were the
same refused merge commit as 13718, from v0.3.40 binaries.

The log names the method a merge used; the Story merge joins the bad-day test (#13731)

When a child's mcptask_runner pr merge answers with merged_with, the
runner's line about the pull request now carries it — PR #159 merged
(merged_with: squash) — <url>
— so a Story merge that asked for a merge commit
and was squashed by the repository says so in the run log and on the card, not
only in the child's tool output.

The stress harness gained a git host: the chaos binary answers as gh on PATH
next to the production mcptask_runner, with the repository's merge settings
drawn per day (merge allowed, squash only, rebase only, nothing allowed,
unreadable). A focused today_auto_squash day per draw runs the Story merge of

13718 end to end and holds it to its outcome: merged with the right method on

the first three, one named story_merge_failed piece and no merge sent on the
last two, and one merge attempt per process however many sweeps follow.

Operator action: none.

Killing a child waits until its whole process group is gone (task #13730)

On macOS a SIGTERM sent to the child's process group while a shell in it was
forking could miss the process being forked (about one kill in eight of a
forking shell). The leader died, the kill was declared done, and the survivor
kept the child's output pipe open: the runner waited on it for 30 s, and the
process went on running after the run — the "leftover child process group" of
task #13639.

The kill path now waits for the group to be empty, not for the leader to exit:
the group is signalled again while it still has members, SIGKILL follows after
the 5 s grace, and SIGKILL is repeated until nothing is left. A group that
SIGKILL cannot empty within 15 s is logged as an error naming what is still in
it and filed as a runner anomaly (process_group_survived_kill), instead of
being left running without a word.

Windows is unchanged and still uses taskkill /T, which can miss a process
started during the walk, and a grandchild whose parent has already exited. The
fix for Windows is a Job Object. It is not part of this release.

Nothing to do on upgrade. The stress day has a new vector,
grandchild_missed_term, and a new invariant, "a process the first SIGTERM
missed does not outlive its child's kill".


Changelog

Other

  • a50a15e84ba94943f169225cdbd6ee35e36b3594 [#13635] Assignee guard: a piece assigned to another user starts no session
  • 46eb368f7eb13a0bef0aa89ee66aad95ac2e7e05 [#13636] An operator's stop is no longer absorbed as a refused child's signal
  • 9a48f4161a0e9a6c1d964160cf633f5b437ce618 [#13718] pr merge asks the repository which merge methods it allows
  • 209368575f798d5f07977d06efbc397d19903d9a [#13725] STORY MERGE: a squash on a squash-only repository is a merged Story
  • 11c708817081d1dd079c4c209af03b133ce7b8f5 [#13730] Kill path waits for the child's whole process group to empty
  • 7bce439c59a3f6b30b87fa573e24c1c2a9ce89ec [#13731] Bad-day test: the Story merge runs against a drawn git host
  • 9cbe3612adece4af68a91b8b4560d22483f064bc [#13762] Lock-guard tests pay ruby's cold start once, outside the guard's budget
  • 37fb915a042c52f449f0d716736c0c030d65f4ac docs(release): v0.3.40 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.40

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.40 carries this binary; no wrapper changes.


The progress gate (task #13634)

With Claude Code, a progress log below 100 % is now refused once when no
TODO item has been closed since the previous log; the agent is told to close
the step's item first, and a retry is accepted either way. This is what keeps
Sonnet's card from sitting at 0/N for a whole run. Nothing to do on upgrade —
the gate file the runner writes per launch carries the new hook. A run log line
progress log at N% with the dashboard card behind it marks every log that
went out unpaired.


Changelog

Other

  • db0485dd4e4472d7be5c437b72b2c07d36b161a5 [#13634] Progress gate: a progress log with no TODO item closed is refused once
  • 21675986484c2f4a9a74ab00f7377dba3210e20d docs(release): v0.3.39 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.39

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.39 carries this binary; no wrapper changes.


A task can no longer stop the runner from the inside

On 2026-10-09 a runner was handed a task written for a person: set the
end-of-workday hour in the host's config, then
launchctl kill SIGTERM gui/$(id -u)/<runner-label> so the runner reads it. The
child session ran that command against its own parent. The runner took the
signal for an operator's stop, exited 143, and launchd left it off until the
next weekday; the task stayed "new", so a restart alone would have done it all
again (story #13557).

What the runner does now. Every shell command the child issues is read off
the stream before the shell runs it. One that stops, restarts or removes the
runner's own process or scheduler job — launchctl kill|kickstart|bootout,
systemctl stop|restart, kill/pkill/killall aimed at mcptask.runner,
mcptask_runner, mcptask-runner, the runner's own pid or $PPID — ends the
attempt: the child is terminated, the task comes back out_of_scope with reason
self_operation, the loop sets it aside for the day and goes on, and one bug
piece names the task and the command so the ticket's author learns it needs a
person on the host. The signals such a command produces are absorbed while
that child is being ended and for two seconds after, on the strength of the
command having been seen; the log says self-inflicted and the day continues.
This is a detector, not a gate. Of a kill -TERM; sleep; kill -KILL chain, or
of launchd's own escalation after a bootout, only the TERM half is absorbed;
the KILL half still ends the process, and a command hidden in a script never
passes through the detector at all. The KILL half is what the gate below
closes for the Claude Code harness; the script it does not. An operator's SIGTERM ends the run as before — with one
change: while a child is running, the handler waits up to 1.5 s for the stream
reader to catch up before it decides the signal is yours.

The gate in front of the shell (Claude Code). The detector reads a command
as the child starts it; the shell runs it regardless. So for the Claude Code
harness the runner now also launches the child with --settings <file>, a file
it writes per launch holding one PreToolUse hook on Bash that runs the runner's
own binary — mcptask_runner internal pretool-gate --runner-pid <pid> — with
the same rules the detector applies (one list, not a copy). A command aimed at
the runner is refused before the shell sees it: the hook exits 2 and Claude
Code shows the model a one-line reason telling it to finish as out_of_scope.
No signal is ever sent, so kill -9, launchctl kill SIGKILL, kickstart -k
and a bootout are covered too; the detector still ends the attempt and files
the piece, and its SIGTERM absorption becomes the second line rather than the
only one. The hook is added to the project's own hooks, not in place of them —
verified on Claude Code 2.1.293 with a project .claude/settings.json hook
firing beside it, and under bypassPermissions. Codex and OpenCode get no gate
yet, and their harness profiles say why in words (command.pre_tool_gate.
unavailable
, logged at every launch): Codex's hooks need trust or
--dangerously-bypass-hook-trust, OpenCode would need glob rules or a plugin,
and neither has been verified on a live run. What no gate catches, here or
anywhere: indirection — a script written to disk and run, eval, base64,
sudo -s — and a host whose managed settings disable hooks. A hand-written
harness profile must now say one or the other under command.pre_tool_gate;
one that says neither is refused at load, naming the key.

What the stress suite now proves about the gap. Three more chaos vectors
stand beside the replay of the incident (task #13566). kill_the_runner_hard
(launchctl kill SIGKILL) and bootout_the_runner (launchctl bootout, with
launchd's SIGTERM and, five seconds later, SIGKILL) each run in two
out-of-process focused days: on Codex, which has no gate, the day is asserted
to END of SIGKILL — the gap, pinned so the suite cannot report green while the
realistic form of the attack still ends the day on a harness without a gate —
and on Claude Code the day is asserted to survive because the gate refused the
call, with the operator's SIGTERM still ending the run with 143.
kill_the_harness (kill -TERM $PPID from the shell tool, which kills the
CLI rather than the runner) is decided: the detector already reads $PPID as
the runner's own process tree, so the task is refused, set aside as out of
scope and reported once — never retried into the same command. The bootout day
also found a hole and it is fixed: a SIGTERM that launchd delivered after the
refused attempt had already returned found no running engine to ask and ended
the day; the handler now asks the previous child's engine too, within its
two-second afterglow.

What to do. Nothing on the host. If you have tasks that ask the runner to
restart or reconfigure itself, rewrite them for a person: the runner will refuse
them and file a piece each time it is handed one. The prompt now tells the child
the same thing, so a well-behaved session answers out_of_scope with a note
rather than trying.

A refused ticket is refused once, not every morning (#13567). The
refusal now outlives the day: the skip list keeps a task refused for
self_operation across days and restarts, holding a SHA-256 of its description
and its assignee as they stood at the refusal, and lets it go only when one of
them changes — compared once a morning against GET /api/:account/pieces/:id;
a piece that cannot be read stays skipped and is asked about again the next
day. The same skip list now also travels as exclude_relative_ids on the REST
next-task check, so a queue holding nothing else answers empty instead of
paying for a triage. The bug piece is filed once per task per day, however many
times it is refused, links the task, and names the refused command, the host and
the scheduled job's label; the dashboard card says refused: self_operation by
task #N
instead of freezing on the killed tool call. So "each time it is handed
one" above now means once: rewrite the task, or reassign it, and it comes back.
The runner also posts one note on the refused task itself (same once-per-task-per-day
record as the bug piece): the refused command, the host, the job label, that a
person on the host has to do that step, and that the task is skipped until its
description changes or it is reassigned. A note that cannot be posted is logged
and named in the bug piece; it never stops the loop. This needs mcptask.online
with POST /api/:account/pieces/:id/messages, which is deployed together with
this release.

The triage child is held to the same rule. A triage session can run the
same command — it reads the ticket too — and it is refused and absorbed the
same way, but it is stopped before it names its pick, so its verdict carried no
task id. The loop read that as "Triage completed but no task_id returned": an
error, nothing set aside, no bug piece, and the ticket left at the head of the
queue for the next triage to obey. Now the refusal is charged to the piece the
triage was demonstrably reading — the one the loop handed it, or else the one
piece it fetched by id — and that piece is set aside and reported exactly as a
task child's would be (triage was stopped for operating on the runner's own
job while reading task #N
in the log). A triage that only asked the queue and
read no piece by id is not guessed at: the log says so, a
self_operation_refused_in_triage bug piece is filed, and the round answers
no_more_tasks, so the loop waits as on a queue it cannot use instead of
erroring. The absorption line no longer claims "the task is set aside" — at
that moment nothing has been decided; the loop's own line says what was.

A LaunchAgent rewritten by plutil is carried forward, and its start is read (#13593)

plutil, PlistBuddy and Xcode rewrite any plist they touch — keys sorted,
tabs, each StartCalendarInterval dict as Hour, Minute, Weekday. The v0.3.38
update matched the job by its text, so such a job was reported as "does not
read the way init writes it" and left off load. Worse, run --if-due read the
start time with the same text match: on a host whose launcher had been given
--if-due but whose plist was plutil-normalised, every scheduled start failed
because the start time "could not be read".

Both now read the plist as launchd does, by structure. update switches
RunAtLoad on in any layout of the job init writes — Label, ProgramArguments
(the launcher alone), StartCalendarInterval, EnvironmentVariables, RunAtLoad
and nothing else — by editing only that one value, so the file keeps its own
layout and token. A job with another program or any other key is still named
and left alone, and its launcher is now left alone with it.

What to do: mcptask_runner update --self on every Mac before its next start — that alone fixes the failing --if-due read. Then, on a Mac whose LaunchAgent was left alone by the v0.3.38
update, run mcptask_runner update again, then reload the job as it prints.
The systemd timer and the Windows task definition are still matched by text:
nothing normalises them in place.

An idle runner's card comes back after a server restart (#13589)

A runner now sends its latest snapshot again after two quiet minutes, instead of
only when its state changes. When mcptask.online restarted, it forgot every
stored card, and a runner waiting out an empty queue (up to 30 minutes) had
nothing to say, so its card stayed off the live page. Nothing to do on upgrade;
the heartbeat is a few hundred bytes per runner every two minutes, and a closed
session is never repeated.

The log line for a refused handshake no longer says "disabling stream". The
stream was never disabled: that attempt is abandoned and the next snapshot or
heartbeat redials.

A quota-endpoint outage during a task no longer ends the run

While a task runs, the heartbeat checks the daily budget on mcptask.online every
six minutes. If three checks in a row got no answer (about 18 minutes), it used
to kill the task, file a bug, and end the run non-zero, so daily mode exited
over a deploy or an outage. That is the day-ending deploy of
#11832, arriving through the
budget check. The stress day found it.

What the runner does now. It lets the task finish. At the third missed check
it logs Quota endpoint unreachable 3 polls running — letting the running task
finish
, and when the endpoint answers again it logs Quota endpoint answering
again after N unanswered polls
. If that answer shows the budget is spent, the
task is stopped exactly as before. The pre-run gate still refuses to start the
next task while the budget cannot be read. The most the budget can be overrun
during an outage is the rest of the one task already running. The termination
label quota_poll_outage is gone, and so is the bug piece it filed. That piece
was filed through the same unreachable server, and a deploy is not a defect.
Nothing to do on upgrade.


Changelog

Features

  • 4e2a68bb96af15070a1ece55dc05e8fb76c55ccf feat(chaos): kill_the_runner vector — the child kills its parent's job (task #13558)
  • e92e3b4b00da140ddc5a42d63e10e3602bbe43bc feat(prompt): never operate on the runner or the job that schedules it (task #13561)
  • 12effb0799a081d07d4618c96c55f2dc01c573ab feat(runner): a self-operation tool call is refused as out_of_scope and its SIGTERM absorbed once (task #13560) ### Fixes
  • 7cf822ffa76abdf0696ff31caafcad2e61cb2047 fix(review): systemctl verbs with flags before them are detected; the kill call has its own tool id (story #13557)
  • 0df48e85588fb40d4dfe1b82eaf9bcc63f0c74c0 fix(review): the self-inflicted window is the child's lifetime plus an afterglow, more verbs and targets, host endings; the detector's limits written down (story #13557)
  • 67233dad18a0f050a229eab3eae15cf31443d9d1 fix(runner): a quota-endpoint outage during a task no longer ends daily mode
  • 8346f77e1044a8f0921ec9cade36b5bae580dcb6 fix(runner): a triage refused for operating on the runner sets its piece aside
  • 59393f3c027815d3b42907fe227dad1f456ec3f9 fix(stress): the out-of-process self-kill day exercises what it claims (story #13557) ### Other
  • 9e86d70111f69f5a07ad0e7ad793d479965d2bf3 [#11778] The lunch sweep: random-seed stress days on a weekday schedule
  • 5615d49a670124e02979fc26c06c395b2279a7c8 [#13565] Pre-tool gate: the harness refuses a self-operation command before the shell runs it
  • 1f66995f306376a3cd0cdb56bdef4a18d8a95a3c [#13566] Stress vectors for the unabsorbable endings: SIGKILL, bootout escalation, the harness killed
  • d6e63feb88129a534c034f48f3620632c4bf6f1d [#13567] A refused self-operation is refused once, not every morning
  • d5b060e9a1811af0e5b1274ac8e92985de95d442 [#13567] Post the self-operation refusal as a note on the refused task
  • 7f05cb001625ba86cdece5136103c17e5f9d49b8 [#13589] Idle runners heartbeat their snapshot; a refused dial no longer claims to disable the stream
  • bcc38e073b149f9ecaf451a7eda4f1b2a7e45c58 [#13593] The LaunchAgent is judged by structure, not by text
  • 0ab8cc89b6d85778c82adbfb5ed7d487bdc16756 docs(readme): OpenCode's probe and failure classes, the host side that shipped, nine codex skills
  • 8de20f0514a69a1a0c6f9006e681deaec6dc98e2 docs(release): link 13593/13589, update --self fixes the failing --if-due read
  • ab90a4ba8814e5ac04f96ca53017b29b9425d458 docs(release): v0.3.38 shipped, the next-tag notes start empty
  • f9a587b7a2d10bd3993d0271141618ad152854f0 test(executor): the pre-tool gate tests name the CLI instead of finding it on PATH
  • 522c97bb4dc4d156fafdaf14bcae29451ddb39a7 test(golden): the five story-branch goldens carry the self-operation rule (story #13557)
  • 94e7ef38a7ddade29c20670af893cd4cc000cd31 test(stress): a child may not end the day (task #13559)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.38

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.38 carries this binary; no wrapper changes.


A crash, logout or reboot during the day no longer costs the rest of it

The scheduled job is now started whenever the platform loads it — at login after
a crash, a reboot, a logout or a power cut — and works only if the day is under
way: a scheduled day, past the job's start time, before work_window's end of
the workday (#13571). A load
outside that logs one line (loaded on Friday at 10:00, the day starts at 11:00
— waiting for the scheduled start
) and exits 0. The start time is read from the
job file itself, so there is nothing new to configure and nothing that can
disagree with the calendar.

Run mcptask_runner update on every scheduled host, after update --self.
It adds --if-due to the launcher and switches the job to start on load
(RunAtLoad true, Persistent=true + OnStartupSec, StartWhenAvailable),
and refuses to while the binary the launcher runs does not know the flag yet.
Then reload the job with the commands update prints — on macOS
launchctl bootout gui/$(id -u)/online.mcptask.runner-<slug> and
launchctl bootstrap gui/$(id -u) <plist>. The bootout stops a run that is in
progress (its task stays in_progress for the next one), and the bootstrap
starts the job again at once if the day is under way.

A macOS LaunchAgent loads only at login, so after a power cut the runner comes
back when somebody logs in — or at boot, if automatic login is on. That is a
host setting; the runner does not work around it.

The project's @next URI matches the server's template (#13568)

Triage and the work prompts read mcptask://pieces/<account>/@next?project_relative_id=N,
which mcptask.online answered with "Resource not found": the resource template is
…/@next?project_relative_id={…}&exclude_relative_ids={…} and a URI without the literal
&exclude_relative_ids= does not match it. The URI now carries it, empty. On a non-Claude
model that could not take the GetNextTaskTool fallback, triage errored and filed bug pieces
(#13552, #13553). The Claude Code fetch fallbacks also now say that a named-but-schemaless
fallback tool is deferred and is loaded with ToolSearch first. No action needed; goldens regenerated.


Changelog

Other

  • 0d961ab42a27d9f1072abf475efe6a1307e049e9 [#13568] The project @next URI carries exclude_relative_ids, as the server template requires
  • b5ea87ea518d338c4b416a5cac5748c1a3db8524 [#13571] The scheduled job starts on load and asks whether the day is due
  • 6a90cbd2ef93c4a0dd5acade2d5129978de0678f ci: golangci-lint v2.14.0, v2.13.0 cannot read Go 1.27.2 export data
  • 726a1af458e270b8a5434acf29998e799dcfd2c0 docs(release): v0.3.37 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.37

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.37 carries this binary; no wrapper changes.


Story branches are on by default

story_branches.enabled no longer has to be written: a host whose
config/mcptask_runner.yml lacks the key now works Stories on story branches
(#13501). A host that must stay
off says enabled: false. Nothing to do on a host that already had true.
Every host of one project should agree — a host that opts out merges its Story
tasks into main beside the others, unless the Story's branch is already live
(see below).

A live story branch binds every host

enabled: false now means "never start a story branch", not "ignore them"
(#13493). When a task's Story
already has a branch on origin, an opted-out host works the task on it like
any other host and logs this host opted out of story branches, but Story #N
has a live branch … — following it
. An opted-out host therefore reads the
task's piece and git ls-remote origin before an auto-squash or manual task,
and a failure there sets the task aside with a story_branch_plan_failed bug
piece, as on an enabled host. Nothing to configure.

A Story task whose verified pull request merged into a branch other than the
planned one now files a story_pr_wrong_base bug piece instead of passing
silently.

A finished Story is merged even when its last task did not know it was last

A Story whose subtasks were finished in parallel, on another host, or on a host
with story branches off used to sit on its live …/story branch until a person
opened the pull request into main
(#13492). The runner now runs a
story-merge run for such a Story: right after the task that finished it, and
at every task boundary of today_auto_squash, queue_auto_squash and
story_auto_squash, where it lists refs/heads/*/story on origin and merges
every Story whose subtasks are all completed or approved — on hosts that opted
out of story branches too. A pull request another host already opened is picked
up, not duplicated. Each Story is tried once per process; a branch still on
origin afterwards is filed as story_merge_failed, and a Story or listing that
cannot be read as story_sweep_failed. The run takes no slot of the daily task
budget and does not start after the end of the work window.

Nothing to configure. Expect, on the first day after upgrading, story-merge runs
for Stories that were finished and left unmerged before — look at origin for
*/story branches first if you would rather merge some of those by hand.


Changelog

Other

  • c693b3f5e78291253db5e242251017b272e149aa [#13492] A finished Story with a live branch is carried into main
  • 64995c943a486fe198ad335f112f8499a0623bb0 [#13493] A live story branch binds every host
  • f0f2876e3ec5a42edb251cd3589d80355a14900b [#13501] story_branches is on unless a host opts out
  • 639a6e78f7be7b78cd4308984877c1b7046c8faf docs(release): v0.3.36 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.36

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.36 carries this binary; no wrapper changes.


A feature catalog the website renders (Task #13451)

The public page at mcptask.online/runner was
written by hand and drifted from what the binary does. This repository now
carries catalog.yml: one entry per feature,
subcommand, flag, config key, harness, git host and exit code, each with the
release it first shipped in and a title and summary in English, Czech and
Slovak — the file the page will be rendered from.

internal/catalog loads and validates it strictly. A missing translation, an
unknown kind, a duplicate id, a flag without its subcommand or a since that is
not a release tag is an error that names the entry and the field, never a row
the page quietly drops.

What an operator has to do: nothing. The catalog is documentation shipped
with the source; the binary does not read it and no host behaves differently.

Every release carries catalog.yml as an asset (#13454)

From this release on, docs/catalog.yml — the runner's feature catalog — is attached to the GitHub release on jchsoft/mcptask-releases as catalog.yml. The latest one is at https://github.com/jchsoft/mcptask-releases/releases/latest/download/catalog.yml; mcptask.online reads it from there. bin/release now refuses to start without the file. Nothing for an operator to do.

The catalog and the code may not disagree (Task #13453)

A guard test, TestCatalogMatchesTheCode in internal/catalog/guard_test.go,
compares docs/catalog.yml with the code in both directions: every visible
subcommand and flag in the command tree, every config key the loader reads,
every bundled harness profile, every git host and every exit code has an
entry, and every entry names something that still exists. A readme_anchor
must land on a real README heading. bin/ci runs it, and a red run names the
id to add or remove. To list its exit codes from code rather than from a copy,
cli.Execute's codes are now named constants and the signal handler's list is
read through runner.SignalExitCodes; the codes themselves are unchanged.

What an operator has to do: nothing.


Changelog

Other

  • 547257ed8dec2ed0e229c1b406ce7022ad2e75e6 [#13451] Feature catalog: docs/catalog.yml and internal/catalog
  • bc62ec5003ff4f27129f4ca3c864805af8b25c3f [#13453] Guard test: the catalog and the code may not disagree
  • 8a8b40d54d6330144e28e8b01702eb1e29629080 [#13454] Publish docs/catalog.yml as a release asset on jchsoft/mcptask-releases
  • 3bcf928392c9b3e25c381b3d494103424b3704da docs(release): v0.3.35 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.35

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.35 carries this binary; no wrapper changes.


Story branches: a Story reaches main in one merge (opt-in) (Story #13009)

Until now every task merged into main on its own, Story subtasks included, so
main held half-finished Stories and a bug fix released from it shipped them
too. A project can now have the tasks of an unfinished Story merge into a
shared story branch instead, and main gets the whole Story in one merge when
its last task is done. Tasks outside a Story are unchanged.

It is off unless the project turns it on, in config/mcptask_runner.yml:

story_branches:
  enabled: true

A value that is not true or false is not read as off: a Story task then
refuses to start, the task is set aside and a bug piece names the key.

What the runner does with it on:

  • Names. A Story's branch is <story_id>-<slug>/story, its tasks' branches <story_id>-<slug>/<task_id>-<slug> — ASCII slugs of the titles, at most 40 characters. The runner decides both before the child starts and pastes them into the prompt; the child no longer makes up a feature/… name for a Story task.
  • Liveness is the remote. The story branch existing on origin (git ls-remote) is what keeps a Story open, whatever its state on mcptask.online. No branch and an approved Story → the task works against main, as before. No branch and an unapproved Story → this task creates the branch from main; two runners racing to create it end up on the same one. A branch is found by the Story's id, so renaming a Story does not cut a second branch.
  • Every Story task checks out the story branch, merges origin/main into it (so fixes from main reach the Story while it is open), cuts its task branch, opens its PR with --base <story branch> and squash-merges it there. The task link stays the LAST mcptask.online link in the PR body.
  • The last task — every other subtask completed or approved; a blocked one holds the Story — then opens a PR from the story branch to main whose body ends with the Story's link, merges it with a merge commit (mcptask_runner pr merge --squash=false) and deletes the Story's branches. The runner checks the remote afterwards: a story branch still on origin is filed as a story_merge_failed bug piece, and the task's own success stands. A finished Story whose last two tasks ran at once and so left the branch unmerged is filed as story_left_unmerged.
  • Manual modes never create a story branch. With one live, the PR targets it; without one, the task branch is still named under the Story's path and the PR targets main. A person merges.
  • mcptask_runner pr merge --squash=false now asks GitHub for a merge commit by name (gh pr merge --merge); it used to pass no method, which gh refuses without a terminal.

Host caveat. Only GitHub approves a piece when its PR merges (by the last
mcptask.online link in the body, whatever the base branch). On GitLab a merged
task is only set to 100 % ("Hotovo?"), and Bitbucket has no webhook at all —
either way a merged task counts as completed, which is enough for the last
task to be recognised, but nothing approves the Story there automatically. On
GitLab the story → main merge follows the project's merge method; a project set
to fast-forward only refuses the merge commit, and that is reported as
story_merge_failed.

Upgrading: nothing for projects that do not add the key. To turn it on,
add the two lines above to config/mcptask_runner.yml and commit them. Runner
hosts pick the feature up with the binary.


Changelog

Other

  • 1403b0679f1bfe14a19c5a231225e0efe9487d90 [#13010] mcptask client reads a piece with its parent Story and subtask states
  • c6576725026957eb7f002280c7f7ec4607148e64 [#13011] Story branch planner: naming, liveness by the remote, race-safe creation
  • abecf2e79ec5f82a982b3d31f564f903f9e5ebff [#13011] [#13015] Lint: story-branch planner and conformance sandbox
  • fbc3cdbbd5df90b43250a9467fcdddbb1ba68a25 [#13012] Auto-squash prompts take the planned branches: story branch in, main merged first
  • 3742459b7aaee8011d43e203d86bd0c4dea7c2f7 [#13013] The Story's last task is checked against the remote; GitHub merge commits by name
  • 83f4a1d7072706aefdb20c916309471d31c9ed2d [#13014] Manual mode names Story task branches under the story path
  • 3eb3a17b4c955ada3bb66623cc6585bb293d230e [#13015] Conformance scenarios, release notes and README for story branches
  • 4cd3f81e380a070f1c91d4a4fef5b48de75a5542 docs(readme): keep a Mac awake through launcher.command, not the plist
  • 8138647edb6cf2452abf73d22e882e573ea649e6 docs(release): v0.3.34 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.34

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.34 carries this binary; no wrapper changes.


A host with Claude Code's read block on refuses to start (#13168)

With permissions.blockReadsOutsideWorkingDirectories turned on, Claude Code
asks the person before any shell command it cannot analyse (a $var in a loop,
a heredoc, ruby -e, python3 -) and before any read outside the project. A
scheduled run has nobody to ask, so those actions are refused even under
bypassPermissions. On the MacBook this ended five runs in two days
(#13149 …
#13167), and the directory grant
from #13137 cannot cover commands.

The runner now reads Claude Code's settings files at startup (user, project,
project-local and managed, in that precedence) and refuses to start when the
effective value is true. The refusal names the file. The runner exits non-zero
and files no bug piece, the same as a missing token.

Upgrading: update --self is enough. On a host that has the setting on,
remove it from the named file, or set it to false, before the next scheduled
run. Until then that host runs nothing and reports the reason in the launcher
log.

A Sonnet card shows the whole plan, not 0/1 (#13424)

The plan block asked for "one item per step of the plan", and each model chose
its own plan. Opus made one item per numbered step, usually seven. Sonnet 5 and
5.5 made one item for the whole task ("Fix + tests + PR + CI + merge"), so every
Sonnet run showed TODO 0/1 on its card from start to finish, on every host.

The block now asks for one item per numbered step under WORKFLOW, and at least
one for every step that ends in a "LOG PROGRESS NOW" line. It also forbids a
single item for the whole task. Claude Code and OpenCode get the new wording.
Codex said "the workflow below", which was wrong in the auto-squash prompts,
where the block sits inside step 2; it now names the section too.

Upgrading: update --self is enough. A run already in progress keeps its
prompt; the next task picks up the new wording.


Changelog

Other

  • b4b962943caa4ab00c98cb8091f6d5d1e2d8ba2a [#13168] A host with Claude Code's read block on refuses to start
  • 688ee72caa82d93cf55622da0a5d82c9c12efb75 [#13424] The plan block asks for one item per WORKFLOW step
  • adfbfd79c7fb882aa6c5728e0ad21fe7ebe5fff3 [#13433] Stress signal tests no longer go red after 17:00
  • c03bed998d70217b24e1266d0ce5c977d8893e01 docs(release): v0.3.33 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.33

Upgrading

Upgrading takes two commands. mcptask_runner update --self replaces the binary; then a bare mcptask_runner update in every project on the host, because the bundled .claude/ assets changed (baseline_permissions.json). Run it while no runner is working that checkout. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.33 carries this binary; wrapper changes in its CHANGELOG.


A run the host refused is filed as a bug, not set aside quietly (#13139)

Sometimes the coding CLI refuses an action because of its own settings: a
permission rule denies it, or a read outside the project is blocked. The child
used to end such a run as failure. The loop then set the task aside for the
day and nothing was filed. On 2026-09-25 that happened to projectoid_ii
#13062 on the MacBook. The same
thing would have stopped every task on that host, and nobody would have been
told.

The runner now remembers each refusal it sees in the stream and logs the first
one as The host refused an action: …. If the run then ends as failure,
error, ci_failed, preexisting_test_errors, stalled_for_genius,
merge_failed or merge_unverified, it is filed as a bug under the termination
host_refused, quoting the first refusal. A run that got past the refusal files
nothing. The prompt also tells the child to end such a run as "status":
"error"
with "reason": "host_refused". That way the refusal gets filed on
Codex and OpenCode too, whose refusal wording nobody has recorded yet, so their
failures.host_refused lists are empty.

For this ending the throttle's fingerprint leaves out the task, so a host that
refuses every task files one piece, not one per task. A focused stress day
filed 76 pieces before this change. The stress day plays the new
host_refused vector and fails if no bug piece names it.

Upgrading: nothing to do. Hosts pick it up with the binary. If you override
a harness profile, add failures.host_refused to your copy (see the bundled
claude.yml).

Test and CI logs stay readable when reads outside the project are blocked (#13137)

The bundled /test-runner and /ci-runner write their logs under
~/.claude/logs/projects/<hash>/. That is outside the project, so a host with
Claude Code's permissions.blockReadsOutsideWorkingDirectories turned on
refused ci_wait's read, and every task stopped at its first test run. On
2026-09-25 this stopped projectoid_ii's
#13062 on the MacBook.

The permission baseline now adds "~/.claude/logs" to
permissions.additionalDirectories in each project's
.claude/settings.local.json. It is merged like allow and deny, so any
directories the project already lists are kept.

Upgrading: run mcptask_runner update in each runner-driven project. Nothing
else to change, and the read block can stay on.

The end of the workday stops the next task, not just an empty queue (#13076)

work_window.end_of_workday_hour (and end_of_workday_minute) now apply in
today_auto_squash, the mode every scheduled job runs. Before this fix it was
checked only when the queue was empty. A runner with work queued went from one
task to the next past the hour. On 2026-09-24 a runner set to stop at 18:00
started new tasks at 18:20 and 18:54. On 2026-09-23 a triage that waited out a
rate limit came back at 21:09, and the task it picked ran until 22:40.

The clock is now checked each time a task would start: once before triage and
again after it, because triage can take hours. This applies in today,
today_auto_squash and daily. A task that is already running still finishes.
The log says Past end of workday (HH:MM) before triage or … after triage,
and the day ends with the new verdict end_of_workday. The queue, story and
single-task modes still ignore the clock, as before.

Nothing to change in configuration. Hosts pick the fix up with the binary.

Auto-squash no longer merges a pull request that no CI has passed (#13089)

Until now an auto-squash run merged its pull request even when the project had
no bin/ci and the git host reported no checks at all (NONE). In that case
no CI had looked at the change. From this release the runner merges only on a
green signal: the host's checks are SUCCESS, or they are NONE and the
project has a bin/ci that the run executed and passed.

The rule is enforced by the runner, not only by the prompt. In every
auto-squash mode the runner sets MCPTASK_MERGE_GATE=auto_squash for the coding
CLI, and mcptask_runner pr merge then checks the host's CI before it merges.
It refuses when the checks are FAILED, still IN_PROGRESS, cannot be read, or
are NONE in a project without bin/ci. The refusal exits non-zero with
merge refused by the auto-squash gate: …, names the status to report, and
merges nothing. This works the same on GitHub, GitLab and Bitbucket.

On GitHub, mcptask_runner pr checks now answers NONE for a pull request
with no checks. Before, it failed with gh's no checks reported on the …
branch
message, so on GitHub a project without CI never reached the NONE
case at all. Running
mcptask_runner pr merge by hand, and every manual mode, is not gated.

A project with neither CI now ends the task with the new status
merge_skipped_no_ci. The pull request stays open, the agent leaves a message
on the piece saying why, and progress stops at 80 %. The loop sets the task
aside for the day and moves on, and the log reads Task #N has a pull request
left open because the project has no CI (no bin/ci, no host checks) and needs a
human to merge it
. The runner card lists the task under set aside with the
reason merge_skipped_no_ci. To get such projects auto-merging again, add a
bin/ci or CI on the git host.

Nothing to change in configuration. Hosts pick the fix up with the binary.

A crash on a customer's runner files a bug piece in the customer's own project (#13090)

Before this change the runner filed a bug piece about its own failure only when
it ran under the jchsoft account. Runners under any other account stopped and
logged locally. Now a hard failure on a customer's runner files a bug piece
in that customer's account, in the project the run was working
(project_relative_id from the host's CLAUDE.md). The piece goes under the
project's bug-bucket Epic (the lowest-numbered Epic marked for errors), or at
the project root when the project has none. It never goes into jchsoft.

A customer's piece carries no raw agent output. The raw runner log is not
attached. Neither is anything else that can quote source code: prompts, tool
inputs and results, the agent's messages and thinking, stderr dumps, or the
values in the CLI's configuration files. The piece carries:

  • the task link, runner version, OS/arch, CLI and its version, model, mode, machine, session, the CLI's exit status and the error message (code-like lines removed);
  • the last tool calls, by name and outcome only;
  • the agent's error lines, sanitized and cut at 200 characters;
  • runner_events.txt, the runner's own log lines with child output removed;
  • a filtered copy of the run record;
  • cli_config_keys.txt, the setting names from the CLI's config files, with no values.

The piece also lists what was left out and gives the local paths of the full
runner log and run record on that machine. Reports under jchsoft are
unchanged.

The run now ends non-zero when it owed a report and could not file one, under
any account, jchsoft included. The log says so at the end:
… runner failure report(s) owed by this run … — ending the run non-zero.
When the server refuses (401/403, no access to the project, an expired trial),
the runner does not try again for the rest of that run. In daily mode a
refusal also stops the loop at the end of the day. A plain outage does not stop
it.

The runner's debug log now writes Tool finished: <name> (error) for a tool
call that failed.

A customer whose token cannot create pieces in its own project gets
REFUSED — this runner may NOT file bug reports and a non-zero exit. The fix is
to give that user project membership. Nothing to change in configuration. Hosts
pick the change up with the binary, so no bare update is needed.

mcptask_runner on PATH for a coding CLI you start yourself (#13123)

A Claude Code session you open by hand in a gem-installed project used to fail
on mcptask_runner pr … with exit 127 — the binary is
~/.mcptask/bin/mcptask_runner and nothing put it on PATH — and then went
hunting for the path in the launchd plist. Runs the runner starts itself were
never affected.

init and update now write ~/.mcptask_env.d/runner_path, which puts the
runner's directory first on PATH (once, however many startup files source the
directory). For the copy bundled inside the Rails wrapper gem that is
~/.mcptask/bin, never the gem directory. A binary not named mcptask_runner
(a worktree build) writes nothing and says so; Windows prints the directory to
add by hand.

To pick it up: bundle exec rake mcptask_runner:update (or
mcptask_runner update), then open a new terminal / restart the session.

A scheduled job set up through npx no longer points into npm's cache (#13095)

npx @mcptask/cli init used to write the scheduled job (LaunchAgent, systemd
timer, Task Scheduler job) with the path of the binary inside npm's cache, for
example ~/.npm/_npx/<hash>/node_modules/@mcptask/cli/vendor/mcptask_runner.
Once npm cleaned that cache or fetched a newer version, the job failed at its
next start on a missing file. The same happened with a project-local or global
npm install.

Now, when the runner is the binary from the @mcptask/cli npm package, init
copies it to ~/.mcptask/bin/mcptask_runner (mcptask_runner.exe on Windows),
the same path the Rails channel uses, and the job runs that copy. The output
says Installed this runner as …, or Replaced … when a different binary was
there before, since other projects' jobs on the same host may run that file.
Keep it current with ~/.mcptask/bin/mcptask_runner update --self.

Jobs written before this change still point into npm's cache. Regenerate them
with npx @mcptask/cli init --schedule --force in each project. A bare
update does not do it.

Elapsed times count the hours the Mac slept (#13132)

On macOS the runner measured every duration with a clock that stops while the
machine sleeps, Maintenance Sleep included. A Mac mini left alone sleeps several
times an hour, so the times the runner reported came out short. One session ran
from 21:09 to 21:42 and was logged as Elapsed time: 0.19 hours.

These now use the wall clock and include sleep:

  • Elapsed time: … hours, Execution finished in …s, and every after N h in the log;
  • the task_worked hours in the result;
  • elapsed_s in the run record, the bug piece and the overflow handoff;
  • elapsed_s of a running tool on the dashboard card.

The 30- and 60-minute "ask the queue again" waits now end at the clock time
they announce. Before, a wait that crossed a sleep ran later than that time.

The watchdog still ignores sleep. Its inactivity and hung-tool deadlines, and
the waiting for: Bash since Ns part of the heartbeat line, measure only time
the machine was awake. A child cannot work while the machine sleeps, so a run
that was healthy before a sleep is not killed as stalled afterwards.

The same change affects Linux hosts after a suspend. Nothing to configure.
Hosts pick the change up with the binary, so no bare update is needed.

A piece name with braces no longer stops the day (#13121)

The runner lost a well-formed TASKRUNNER_RESULT when a string in it held
unbalanced braces. The usual case is a task_name copied from a piece name such
as a raw i18n hash, {one: "až %{count_max} uživatel…. It found the end of the
JSON by counting braces, strings included, so the object never closed. The
triage was logged as Missing TASKRUNNER_RESULT marker, retried, then failed
with no task_id, and the loop stopped with A task failed, stopping. The next
run picked the same piece and stopped again. On 2026-09-25 this stopped a
runner after four tasks. The only workaround was renaming the piece.

The marker is now decoded by the JSON decoder itself, which skips string
contents. A marker the runner finds in the raw stream is also unescaped
properly, so one spread over several lines is read too.

When a marker is present but its JSON cannot be used, the log now says so
instead of calling it missing:

  • result marker found but its JSON never closed: {"TASKRUNNER_RESULT": … (or did not parse (<decoder error>)), with the first 200 characters;
  • TASKRUNNER_RESULT marker present but unusable (…) - will retry with marker-only instruction;
  • after the retries: Unusable TASKRUNNER_RESULT after retries exhausted.

A marker that is really missing is still logged as Missing TASKRUNNER_RESULT
marker
. The retries are unchanged. Nothing to change in configuration. Hosts
pick the change up with the binary, so no bare update is needed.

Adopting the bundle's runner now updates the binary the scheduled job runs (#13133)

On a Rails host, a runner whose project Gemfile.lock names a newer
mcptask-rails-runner adopts that bundled binary, at the start of a run and
between tasks. Until this fix it installed the binary into the project's own
bin/mcptask_runner instead of ~/.mcptask/bin/mcptask_runner, and then ran
it from there. The day's run was on the new version, but the LaunchAgent
(systemd timer, Task Scheduler job) went on starting the old binary in
~/.mcptask/bin the next morning, so every scheduled run had to adopt again.

Now the adoption installs into ~/.mcptask/bin/mcptask_runner
(mcptask_runner.exe on Windows), the file the scheduled job runs. init,
the scheduler and the runner-on-PATH export compute that path with the same
function. A home directory the runner cannot find is an error that says so,
never a path relative to the working directory.

Copies the old code left behind are not deleted. At the start of run, in a
project that bundles the wrapper gem, the log says
[Adopt] <project>/bin/mcptask_runner looks like a runner binary adopted into
the project by mistake
. If that file is not the project's own, delete it. It
is about 10 MB. Check that it was never committed, because not every project
gitignores bin/mcptask_runner.

Nothing to change in configuration, and no bare update needed. Hosts pick
the fix up with the binary.


Changelog

Other

  • 21e8e9360eecd096c8b92827dc2b6776eeabe09d [#13076] No task starts after the end of the workday, and the stress day proves it
  • 6e96bc636e2938067a4fa825091ebf29e378f8a1 [#13088] The Bitbucket install tests no longer read the host's credentials
  • e7f96ff03899d44f7d8a9ef8f7bef2ed27452671 [#13089] Auto-squash merges only on a green CI signal, and the runner enforces it
  • 642d79ce7b4ee805e6359d46830ad4815c33c1f2 [#13089] GitHub checks with none reported answer NONE instead of failing
  • 4cb249304a5e7604346d9ad91f784ec175da0888 [#13090] A customer's runner files its crash into its own project, without raw agent output
  • ff34c2a772936bdebef01b25d8b6bcd505afcc47 [#13095] A job scheduled through npx runs a stable copy, not npm's cache
  • 5d754ec579a491ff7a2cfd3fc5e4b32bc9a43393 [#13121] A marker whose strings hold braces is decoded, not lost to a brace count
  • c55e20219b28d57cc57a67e88ac1e661e4133144 [#13123] init and update put mcptask_runner on PATH for sessions started by hand
  • 68be0fe333a3e29a48c21896c06cf8143b0f9267 [#13128] The updater resolves the mcptask token through an injected environment
  • 926062e754ed01351a51670424868f0a011175d9 [#13132] Reported durations count host sleep; the watchdog still does not
  • 44d445dfc19f779cd26a8a6a2217aec8d2f18ab7 [#13133] Adoption installs into ~/.mcptask/bin, the binary the scheduled job runs
  • fc43f98a756ab29a243bd1dce1d19d86af01f7a7 [#13133] [#13123] The Windows test run no longer assumes unix paths or an env directory
  • eae7ae45b239b386e86ca62f7bfe9c80400909d6 [#13137] The installer grants ~/.claude/logs so a read block cannot stop test and CI verification
  • 42cfa4cc388f4093557c46bf7afc7d1b890a32a5 [#13139] A run the host refused is filed as a bug, not set aside quietly
  • da351b1452fa33e03c2901533aaefe0e6a9143ef docs(release): v0.3.32 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.32

Upgrading

Upgrading starts with one command. mcptask_runner update --self replaces the binary. The bundled .claude/ assets did not change, so nothing on that account asks for a bare update in the projects — the sections below say whether anything else does. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.32 carries this binary; no wrapper changes.


A second bundle update in one day is taken up too (#12905)

Since 0.3.31 an iterating runner takes up a new runner from the project's bundle
at the next task boundary. It did so once per process lineage: the exec that
swapped it set MCPTASK_ADOPTED=1, every later process inherited it, and a
process carrying it never looked at the bundle again — so the second bundle
update
of the day waited for a manual restart. Now the marker names the version
that was installed (MCPTASK_ADOPTED=0.3.32, say), the new process takes it off
its own environment at startup, and it refuses only a re-adoption of that same
version. What an operator sees: each bundle update produces its own
"Updating from X to Y" on the card at the next boundary.

The marker no longer reaches the coding CLI's environment either.

One new line can appear in the log, and it means a broken release rather than a
broken host: [Adopt] This process was installed as the bundle's X but reports
itself as Y
— the gem's binary does not know its own version, and the runner
stays on it rather than reinstalling it in a loop.

No update is needed: nothing in a project's .claude/ changes. A runner still
on 0.3.31 sets the old flag form when it hands over; the new binary treats 1
as no version, so the handover onto this release is unaffected.

A refused push ends the task; it is no longer worked around (#12903)

In a smoke run a child's git push was refused because its SSH key had dropped
out of the agent. The child got past it by rewriting the project's origin to
another transport, finished the task, and left the clone changed — so the next
run failed on the rewritten URL, with an error that no longer pointed at the
missing key.

From this tag every PUSH step in every workflow (auto-squash, honest, manual,
story, review) tells the child that a refused push, fetch or pull —
authentication, permission, host key, protected branch — is not permission to
change the remote, switch transport, or touch credentials, SSH keys or git
config. It may re-run the same command once; after that it stops with status
failure and quotes git's refusal word for word, so the task note says what
the host said.

The runner also reads git remote get-url origin before and after every child.
If it changed, the run log gets an ERROR line naming the old and the new URL and
the git remote set-url origin <old> that restores it, and an anomaly piece
(origin_rewritten) is filed in the runner's Errors epic. The runner does NOT
restore the URL itself and does not change the task's result: whether the new
URL is wrong is for a person to decide. A project with no readable origin is
not checked (a DEBUG line says so).

No update is needed: the prompt and the check are both in the binary.

An expired trial stops the runner with one line instead of spinning (#12953, #12967)

mcptask.online now refuses an account whose trial has ended with no payment
method on file — HTTP 402 on the REST API, trial_expired: true on every MCP
tool (#12948). Until now the
runner read that as a passing hiccup: the queue check fell through to triage,
triage was refused too, a bug report was attempted and refused, and the wait
cycle started it all again.

Now the run ends at the first refusal it meets — the profile read at startup,
the queue check, or the quota poll — with one line on stdout and in the run log
naming the account, the server's own message and the payment link it contains,
and a non-zero exit:

❌ [WorkLoop] mcptask.online refuses account "kamr" — the trial has expired: "The trial has ended, please order a subscription: https://mcptask.online/kamr/standalone_payment" (payment page: https://mcptask.online/kamr/standalone_payment) — stopping the run: no triage, no retry, and no bug report, because the report would be refused the same way

No bug piece is filed for it, on purpose: the reporter uses the same token and
would be refused the same way. A scheduled host therefore shows a failed job in
its launcher log each weekday morning until the account is paid for; the next
start after payment runs normally. Nothing to do on upgrade — a bare update is
not needed.

A fan-out of subagents over one file is no longer killed as a loop (#12966)

The watchdog's stall detector counted every tool call on the stream into one
window, including the calls of subagents the session had forked. A skill that
sends six persona subagents over one shared file — each reading it once, by
design — produced six identical Reads, and the fourth ended the run:

Stall detected: reason=loop_signature signature=Read:/tmp/zuboklik-persona-target-wizard.md:: count=4

The run was filed as stalled_for_genius, the piece was re-run on genius,
stalled again and was set aside for the day. Zuboklik
#12842 spent four days that way.

From this tag the detector keeps its window, its failed-edit streak and its
Bash failure records per agent, reading who made each call off Claude Code's
parent_tool_use_id. One agent repeating itself four times is still a loop,
exactly as before; six agents each doing a thing once are not. A successful
edit still counts as progress for the session that forked the subagent, so a
root that delegates a fix and re-runs its failing tests is not killed either —
but never for a sibling subagent, whose loop is its own.

What you see in the run log. A verdict inside a subagent names it:
Stall detected: reason=loop_signature signature=Read:/x.md:: count=4
detail=agent=toolu_… — terminating for genius escalation
, and a Bash loop
reads detail=exit=1 agent=toolu_…. A verdict in the session you launched
reads exactly as it did.

The context-cost report had the same fault. After an overflow the fresh
session was told you read X in full 4 times about Reads its subagents had
made in their own context. It now counts only the session that ran out of
room, and the [context_cost] summary line says how much it left out when
there was anything: …, 0 failed edits; 6 subagent calls not counted (their
context is their own)
. A run that forked no subagent logs the line it always
did.

Codex and OpenCode are unchanged. Codex's exec --json items name no
thread and OpenCode prints no child session's calls at all, so on those two
every call the stream shows is counted as the root's, as before.

No update is needed: the change is in the binary.

ollama launch works again, and a CLI that cannot start says so (#12965)

Hosts whose launcher.command is [ollama, launch, claude] (or codex,
opencode) stopped working when Ollama 0.32 began taking a CLI's arguments only
after --: every launch died in a tenth of a second with Error: unknown
shorthand flag: 'p' in -p
, and the runner reported it as the model forgetting
its result marker — two --continue retries, then a bug piece titled
stream_ended.

  • The runner now composes ollama launch <cli> --model <model> -y -- <the CLI's arguments>. Nothing to change in the config: [ollama, launch, claude] is still the form to write. A launcher.command that itself carries --model, -- or another Ollama flag is refused before the run starts, with the reason.
  • Any CLI that exits non-zero before its first stream line now ends the run at once as launch_failed, with the exit status and the child's own stderr in the log, on the card and in the bug piece. No marker retry, no --continue.

Upgrading: no update is needed for this — nothing the installer writes
changed; the fix is the binary. Nor any config change: [ollama, launch, claude]
stays as it is. On an Ollama-launched host that has been failing since Ollama
0.32, install the new binary and restart the runner's LaunchAgent (an idle
runner keeps the binary it started with).


Changelog

Other

  • 877c4581f67ad907d299cdcaaf56224dbf04d356 [#12903] A refused push ends the task instead of being repaired by rewriting origin
  • f91a67c253643cf41d988cb575fc6b1eab856512 [#12905] The adoption marker names the version it installed, so a second bundle update in one day is taken up
  • 5623aaaaaa14668fc4ae8bea34abb89bc1ea0ae8 [#12953] An expired trial ends the run with one line, not a retried failure
  • b2e10d0883b56de3f5253ef1332b7b8c7131b5fd [#12965] A CLI that cannot start is a launch failure, and ollama launch gets the command line Ollama 0.32 accepts
  • 22435d77c05f3a8d5780d7c7d7362f2b13713a34 [#12966] The context-cost report counts only the session that ran out of room
  • c115499c802a2c2f5d924c29a56d8199541a4be4 [#12966] The stall detector judges each subagent on its own calls
  • 41f2b23b5b60b92ab0a40c4ae9d784dd86581b74 bin/release: the upgrading paragraph reports the asset diff, it no longer concludes a host has nothing else to do [skip ci]
  • b08156576375b0edbd75d758237b23d5d7cbf678 docs(release): v0.3.31 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.31

Upgrading

Upgrading is two commands this once. mcptask_runner update --self replaces the binary. Then a bare mcptask_runner update once in every project on the host (it also stamps the machine's helper home) — not because the bundled .claude/ assets changed (they did not), but because this tag starts recording which version installed them, and until that record exists every run start prints a WARN and leaves the files alone; see "The installed skills and helpers follow the binary by themselves" below. From then on installing a new binary is enough. A runner idling in a wait keeps the old binary until its next task or a restart (launchctl kill SIGTERM, wait for the job to stop, then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.31 carries this binary; no wrapper changes.


The installed skills and helpers follow the binary by themselves

Until now the skills in a project's .claude/skills, the helper scripts in
~/.claude/bin, the permission baseline and the test-commands file were
written by mcptask_runner init and refreshed by mcptask_runner update, and
by nothing else. A fix that lives in one of those files rather than in Go code
reached no host until somebody typed update there — task
#11669 corrected three helper
scripts on 2026-08-21 and every host kept the broken ones
(#11673).

From this tag every run starts by comparing the version that installed the
files with the version running, and refreshes them from the running binary
when the binary is the newer of the two. It is a string comparison against a
record on disk; nothing is fetched. The refresh is update without --force:
a skill or helper you edited by hand is left exactly as it is and named in the
log, never overwritten. The process that takes over between tasks after a
binary swap passes through the same start, so a binary installed at 10:00 has
its assets in place before its first task too.

What you see in the run log. One line per record, each naming the project:

  • [Reconcile] <project>: the skills in <project> were installed from 0.3.10 and this process is 0.3.11 — refreshed from it: 2 updated (ci-runner, test-runner), 1 left as edited by hand (discover), 9 already up to date — on stdout and in the file; the updater's per-file table is in the file at DEBUG, and a skill it left alone gets the usual conflict — … locally modified, skipped line at WARN. The helpers get the same line for ~/.claude/bin.
  • Nothing above DEBUG when the record already names the running version, which is every start after the first.
  • no skills manifest at … — this project was not set up by mcptask_runner init at INFO on a scratch clone run by hand; nothing is written there.
  • … were installed from 0.3.12, which is NEWER than the 0.3.10 this process is running — left exactly as they are at WARN. A host can legitimately be ahead of its binary — assets installed from a checkout, a hand-updated host where an older per-machine binary still runs — and the runner refuses to move them backwards. The binary is what is behind; install the newer one.
  • … records no runner version, so whether the skills … are older or newer than this 0.3.11 cannot be told — left as they are; run mcptask_runner update in this project once at WARN. This is every existing host at its first start on this tag: the record that makes the check possible did not exist before it, and an absent version is not read as "older than everything" — that guess is exactly what would put a corrected helper back to its broken version on a host whose binary is behind its files.
  • A refresh that could not be carried out (a directory that cannot be written) is an ERROR line, a bug piece under assets_reconcile_failed, and the run goes on with the files as they are.

What you have to do. Once per project, and once for the machine's helper
home: mcptask_runner update, from the binary you want the files to follow.
It records its version in .claude/skills/.mcptask_runner_manifest.json and
~/.claude/bin/.mcptask_runner_helpers.json, and from then on installing a
new binary is enough — update is no longer needed for an asset fix to land.
The order still matters for the typed command: release the binary, then
update. update from an older binary over newer files now says so before it
runs (… the files are going BACKWARDS), and runs anyway, because you asked.

Run logs and bug-report attachments no longer carry escape codes

The stream formatter used to wrap the task announcement in bold whenever the
emoji icons were on, whatever it was writing to — so the per-run log file got
\x1b[1m in it, and so did the copy bug-report attaches to a piece, which is
the one artefact meant to be read by somebody who was not there. Thirteen of
sixteen logs on the host that found this had escape bytes in them.

Colour is now decided per destination, by the same two variables as everywhere
else in the runner: MCPTASK_RUNNER_COLOR first (it wins both ways), then
NO_COLOR, then whether the writer is a terminal. The log file is never asked
and is never painted; stdout is painted only when it is a terminal that renders
it.

MCPTASK_RUNNER_ASCII is now about the icon set and nothing else. It used to
strip the bold as a side effect, which meant an operator who wanted clean log
files had to give up the emoji to get them — that is what the colour variables
are for now, and MCPTASK_RUNNER_ASCII=1 at a terminal keeps the emphasis it
used to lose.

Nothing to do on upgrade. Logs written before it still contain the escapes;
bug-report attachments from this version on do not.

The release is one script

bin/release X.Y.Z in this repository does the two-repository release —
gem CHANGELOG and version bump, both tags, the Go and gem Release workflows
watched, this file's contents put above what goreleaser wrote, this file
emptied, the six platform gems verified on rubygems — and refuses, by name,
before anything irreversible: a dirty or off-main checkout, a main that
differs from origin/main in either repository, a tag that already exists, a
version that does not go up, an empty notes file, a wrapper change with no
CHANGELOG line, or gh not signed in. bin/release X.Y.Z --dry-run runs
every check and prints every step it would take. Nothing changes for a host
that runs the binary; this is for whoever cuts the tags (task #12464).


A child that forks subagents in the foreground is no longer killed at five minutes

Zuboklik task #12842 asks for a persona review, which the project skill runs
as six subagents in one message with the parent silent until they answer. Four
runs on 2026-09-21/22 each read the inputs, logged 20 %, started the review
and died 5 minutes later with no commit and nothing on the piece; sibling
tasks went through fine, so to the owner it looked like the runners kept
skipping that one (bug #12900).

The profile knew the subagent tool as Task, the name Claude Code used to give
it, and gave that kind the long-running ceiling. Claude Code 2.1.x calls the
tool Agent, which no profile line named, so the watchdog filed it under
"other" and applied the quick ceiling: a kill at 300 s once the stream had
been quiet for 180 s, a failure verdict, the day's set-aside list, and a
resume that died the same way. Agent is now a subagent in the bundled claude
profile, beside Task, which stays for the CLIs that still use it.

One command on a host: mcptask_runner update --self. A host that overrides
the claude profile with a file of its own has to add the line itself —
Agent: {kind: subagent, name: Agent} under tools:.


A transient 500 from the API no longer ends the day

Bug #12896: on 2026-09-22 two
runners on the claude harness hit an HTTP 500 during triage. The CLI ended its
turn on the terminal event that a refusal arrives on, with a sentence that says
the condition is temporary; the runner filed it as a refusal it had no name for,
returned status error, and the quota Decider stopped the whole working day on
both machines over one 918ms request.

What an operator sees now:

  • API Error: 500, 502, 503 and 504 on Claude Code's terminal event are read as an overload and ride the same budget a 529 does — ten waits, doubling from 60 s to 600 s — instead of ending the run. The 500 was recorded from the incident; the other three are the same CLI template and were not.
  • The log says so in the CLI's own words. At the moment the line arrives: The API answered with a server-side error — the CLI said: "API Error: 500 …"; not a refusal: if this attempt ends without an answer it is retried on the overload budget (a WARN, not an ERROR). At the retry: API server-side error - retry 1/10, waiting 60s before next attempt... — the CLI said: "…", and the dashboard card says the same while it waits. A bare 529 keeps its old line, API overloaded (529) - retry 1/10 …, byte for byte.
  • On codex and opencode every overload already arrives as a sentence, so their retry lines now quote it too (… — the CLI said: "Selected model is at capacity…") rather than naming a 529 the CLI never sent.
  • If the ten waits run out, the run ends as before with status error, and the message carries the CLI's sentence rather than "API overloaded (529)".
  • A refusal the profile has no words for (a 403, for instance) still stops the run and the day, with no named remedy in the log: that is the cue to record the words in the profile, under overload if the CLI calls them temporary.

Nothing to do on upgrade. The profile change ships inside the binary. A host
that overrides the claude profile with its own copy — config/harnesses/claude.yml
in the project, or ~/.mcptask/harnesses/claude.yml — keeps running its copy
and has to add the four literals under failures.overload itself.

A running runner takes up a newly installed binary between tasks

Until now a binary installed while the runner was working was not picked up
until the process ended: in daily at the day's end, in today_auto_squash
at tomorrow's scheduled start. From this tag every mode that works more than
one task — today, today_auto_squash, daily, the queue and story modes —
checks at the boundary between two tasks whether the installed binary
changed, and if it did, swaps itself onto it there
(#11867). The check is two
stat calls and a read of Gemfile.lock; nothing is fetched from the
network, ever.

The channel does not matter: homebrew, mcptask_runner update --self,
curl | sh, another project's run rewriting ~/.mcptask/bin/mcptask_runner,
or bundle update mcptask-rails-runner — the bundle is adopted into
~/.mcptask/bin at the same boundary, which is what makes the process stale.

What you see. The runner's card on the dashboard blinks: it closes with
the message Updating from <old> to <new> and a new card opens under a fresh
session id a moment later. The run log says the same, with the number of
results carried over and where they were written. The new process continues
the same day — the tasks worked so far, the moment the day began — so the
quota check and the stop rules see the whole day, not a second one starting
at 11:00. The skip list and the urgent pin were already on disk and survive as
before. The day-end swap in daily stays as it was, in addition.

What you have to do. Nothing beyond installing the new version. Do not
restart the runner by hand; the running process swaps itself at the next task
boundary, never while a child is alive. Before handing over it runs
<new binary> version once; a binary that cannot say its version is refused
with a line in the log, and the runner stays on the one it has. A handover
whose exec fails is likewise logged and left for the day's end to try again.

State file. The day's state travels through
tmp/mcptask_runner/handover.json under the project, written a moment before
the exec and consumed once by the process that takes over. A file left there
by a run that did not continue is reported in the log and removed at the next
start, never resumed.

The story loop asks the server which subtask is next

Triage used to be handed a whole Story and a rule in prose — first subtask not
finished, not blocked, not on the skip list — and re-derived a database query
from a list that carried no priority, no task type and no blocker. On
jchsoft/Zuboklik on 2026-09-15 it walked that list in creation order, looped on
a medium task while an urgent bug in the same Story waited, and handed over a
blocked subtask that cost a whole session of the strongest model to discover
(task #12568).

The runner now asks mcptask.online's story-scoped queue — GET
/api/:account/pieces/:story/next
, task #12567 — before any triage session
runs, with today's skip list passed as exclude_relative_ids. The server
orders the Story the way it orders the queue (priority tier, bug or complaint
first, oldest first), never offers a blocked or finished subtask, and triage
receives one concrete subtask and chooses only the model. The subtask scan is
gone from every prompt that met a Story: the story-locked triage, the Story
branch of the discovery triage, and the dry run.

The three empty answers are three exits. Nothing left ends the story loop as a
finished Story. Every remaining subtask blocked ends it with no_more_tasks
naming the blocked subtasks — in the verdict, in the log and in the card's
message — rather than spinning on a Story it can take nothing from. Nothing
beyond the skip list ends it the way the skip list always has: the loop waits,
as on an empty queue.

Requires mcptask.online with the story-scoped @next (task #12567, deployed
2026-09-15).
Against an older server the REST call answers 404 and the loop
falls back to the same query through MCP: triage is handed the Story alone and
its prompt reads mcptask://pieces/{account}/{story}/@next?exclude_relative_ids=…
itself — on a server without that resource, a story loop cannot pick a subtask
at all and answers no_more_tasks with the server's refusal in its message.
Hosts with a .claude/ installed by an earlier release need no update: the
change is entirely in the binary and its prompts.

GetNextStorySubtaskTool now counts as fetch evidence in every bundled
harness profile, so a triage child that reached the Story's queue through the
tool rather than the resource is not discarded as an unverified pick.


Changelog

Other

  • bd3b65e6f6eef0f68903a903041510348672b0cf [#11673] The installed skills and helpers are reconciled with the running binary at every run's start, by version, never backwards
  • e56cf6ed50f6b870023a951d1cb9fb6f5abbc382 [#11780] the stream formatter paints a terminal and writes the log file plain
  • b0b6cc3fb415e10812d6dac48253707881a69a13 [#11867] The in-process stop cuts a session start and the closing-frame redial short
  • c57cd0a0b2ceaa592d335c4c0ec0d4ea40f20ed4 [#11867] The runner takes up a newly installed binary between tasks, not only at day end
  • ce2aceecdb4d290f9b1f096055fc536ec86698a0 [#12464] bin/release: the two-repository release as one script that refuses by name
  • 0d4c1f885553e4bf2004aa8d5449a468f2671ed2 [#12466] the conformance driver is built as mcptask_runner, and every scenario checks the child can find it
  • 9c20400e407555e830195ef674b42e5129041c13 [#12568] The story loop asks the server which subtask is next
  • 45953b16f287d6bd524b59786c53bc1b3880a300 [#12896] A transient 500 on the terminal event rides the overload budget instead of ending the day
  • 7d93df8475e9aff0dca905ba5ee10f1e13bf045f [#12896] Scenario 25 asserts the retry line in each dialect's own words
  • adf337334a4b44152054787ba20af6b203c81836 [#12900] the claude profile names Agent as the subagent tool, beside Task
  • eacefab166e2bd6f7300f133a406268a86c6ebda docs(release): v0.3.30 shipped, the next-tag notes start empty
  • 9e09a9be67ffe3fdfd83f920ab6dab75fd793a1c test(eventstream): the stop tests group their imports the way goimports wants

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.30

Upgrading takes two commands

mcptask_runner update --self replaces the binary. Then a bare
mcptask_runner update in every project on the host, because the bundled pr
skill changed — it now names the shape of the task link a pull request must
carry and tells the agent to copy the one the CREATE PULL REQUEST step prints,
which is the other half of the pr create check below. Run it while no runner
is working that checkout. A runner idling in a wait keeps the old binary until
its next task or a restart (launchctl kill SIGTERM, wait for the job to stop,
then kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.30 carries this binary; no wrapper
changes.


init can be told "no scheduled job"

The scheduled-job prompt at the end of init offered 1) today_auto_squash
and 2) today and nothing else. There was no way to say "I do not want the
runner started automatically": any other answer was invalid mode, and because
the schedule is the last step, that error failed an install whose every earlier
step had already succeeded (task #12790).

The prompt now has 3) none — no scheduled job, start the runner by hand. It
writes no LaunchAgent, systemd timer or Task Scheduler job, prints
Scheduling: skipped (none chosen …) and the install ends green. A
provisioning script says the same with --mode none. Nothing changes for a
host that already answered 1 or 2; pick it up with `mcptask_runner update

--self`.

The end of init can be read without reading every word

The tail of an install was forty [Installer] lines in one voice: paths
written, commands to run, and the sentences explaining both, all at the same
weight — and an operator who had just answered three prompts could not tell
which lines to do something about. On a terminal each line is now painted by
what it is. A path, a command and a value somebody set keep the terminal's own
colour; an explanation (why the hour matters, what the log retention is, what
stopping a run costs) is dimmed whole; and the one step to take now — "To
activate, run:" — is bold. The config summary follows the same rule: section
names bold, meanings and values still at their default dimmed, so what you
configured is the only thing on the page that is neither.

The words are unchanged, and so are the bytes a pipe, a log file or CI
receives: colour reaches a terminal and nowhere else, as before. NO_COLOR
and MCPTASK_RUNNER_COLOR still decide it outright.


A pull request without a task link is refused where no template would catch it

PR jchsoft/mcp4mail#48 went out with `Task: https://mcptask.online (jchsoft

12761)` in its description. mcptask.online reads a pull request back to its

task through that link, and its parser wants the whole path —
https://mcptask.online/<account>/tasks/<relative_id> — so it found no task,
answered the webhook with "Not body supported format!" and task #12761 was
never approved. The prompt said "mcptask.online task link" and left the shape
to the agent, and mcp4mail has no pull-request template, which is exactly where
the shape got invented (task #12865).

Two changes, one at each end. The CREATE PULL REQUEST step now prints the
task's link finished, in that shape, with nothing left to invent; when the run
picks its own task the account is filled in and the id is named as the one
from the fetch step. And on a project with no pull-request template,
mcptask_runner pr create refuses a description that carries no such link,
before the host is asked, naming the shape — the same way it has refused a
description that ignores the template since #12599. A project with a template
of its own is unchanged: the template says where the link goes.

Two commands on a host. mcptask_runner update --self puts the check in the
binary and the wording in the prompt; then a bare mcptask_runner update in
every project, because the bundled pr skill changed too — it now names the
link's shape and tells the agent to copy the one the CREATE PULL REQUEST step
prints. Run it while no runner is working that checkout. A project that was
opening pull requests without any task link will now see them refused — add
the link; that is the pull request mcptask.online could not follow anyway.


Changelog

Features

  • 94346af8cdc3284ec1f349489c76988645f5d8f2 feat(install): the end of init weighs each line by what it is ### Other
  • 589b7ce2b1f56c6f2698b299571f582b93347241 [#12790] Offer 3) none in the scheduled-job prompt, and --mode none on the CLI
  • daabf1e7e835b8e176e69a530da3c7c398bf42b8 [#12865] pr create refuses a description with no task link where no template would catch it
  • 9071ff135fa92d1cca4310a04b60b2a492ebf830 docs(release): the #12865 note names the bare update the changed pr skill needs
  • 8adb4fefdd6ddbf79e73e62100bf014de6d705cf docs(release): v0.3.29 shipped, the next-tag notes start empty
  • 1aa5fe3e30b0853f698b1f2c70fd469665034e62 test(install): the painted-fact check uses strings.Cut, not an Index slice

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.29

Upgrading takes two commands

mcptask_runner update --self replaces the binary. Then a bare
mcptask_runner update in every project on the host, because the bundled pr
skill changed — it now tells the agent to write the pull-request body under
the project template's own headings, which is the other half of the pr create
guard below. Run it while no runner is working that checkout. A runner idling
in a wait keeps the old binary until its next task or a restart
(launchctl kill SIGTERM + kickstart on macOS), so restart it.

The wrapper gem mcptask-rails-runner 0.3.29 carries this binary; no wrapper
changes.


A stalled task really does come back on the strongest model

A stall — the same call over and over, the same edit refused three times, the
same command failing the same way — kills the attempt and leaves the piece in
progress with the verdict stalled_for_genius. The name was a promise the daily
loop did not keep: triage in discovery is told never to call a pick a resume, so
@next handed the same piece back, triage graded it "smart" again, and one host
launched the same model on the same task several times in a row on 2026-09-16
(task #12613).

The loop now remembers what stalled today and on which tier, and decides the
escalation itself. A piece that stalled on a weaker tier runs on genius the next
time triage picks it, whatever triage recommends — the log says so in one line.
A piece that stalls on genius goes on the skip list for the rest of the day,
like a failed one, and gets its fresh look tomorrow. Nothing to configure; pick
it up with mcptask_runner update --self.


A blocked subtask no longer costs a session to discover

Triage walked a Story's subtask list excluding the two Czech labels for finished
work and nothing for blocked, so a subtask sitting at "Blokováno" passed it. The
loop then started the strongest model on the piece, which fetched it, read
is_blocked: true and stopped — a whole session to learn something the Story
payload triage had already read contained, while the work that was actually
available waited (task #12568, seen on jchsoft/Zuboklik on 2026-09-15).

Blocked subtasks are now excluded where the selection is made, in every prompt
that walks a Story: the triage prompts and the dry run. Where the server sends
the machine fields — is_blocked, task_state_code, priority_code,
task_type_code, blocked_by — the child is told to use them and to take the
list in the order the server gives it, which is what makes an urgent bug filed
after a blocked task reachable at all. A server that does not send them behaves
exactly as before: the state label and the progress are the whole test, and
nothing is inferred.

A Story whose remaining subtasks are all blocked now ends the story loop with
no_more_tasks and a message naming the pieces and their blockers, instead of
handing a blocked subtask over again. No new status, and nothing to configure —
pick it up with mcptask_runner update --self.


pr create refuses a description that ignores the project's template

About one pull request in four opened on projectoid_ii carried Claude Code's
own body — ## Summary, ## Test plan, the robot footer — instead of the
project's .github/pull_request_template.md: 9 of the last 40, on both
accounts and both models (task #12599, seen on
https://github.com/jchsoft/projectoid_ii/pull/2036). The CREATE PULL REQUEST
step names the template in one bullet, the agent never opens the file, and
mcptask_runner pr create forwarded whatever it was given.

The prompt has not grown a line. Instead pr create reads the template the
prompt names — GitHub's or GitLab's convention, or pr_template: path: —
and refuses a description missing any heading the template does not mark
(optional), before the host is asked. The refusal names the missing sections
and prints the template's skeleton, so the agent's next turn is the rewrite
with nothing else to look up. A project with no template on disk is checked
against nothing, and a declared path with no file behind it is said on stderr
rather than guessed around. Pick it up with mcptask_runner update --self.

Changelog

Other

  • 7989e4cc35ae390e09c18668e96d0543e90c3f8f [#12568] Skip a blocked subtask in triage, before it costs a session (#12)
  • d4e8fbc6d5427826ae23eb0fc080789a23fa7c57 [#12599] Refuse a pull-request description that ignores the project's template
  • 5d1baa4031bebbbf7809aa1e883c9b9603b8ac42 [#12613] Escalate a stalled task to genius runner-side, and set it aside when genius stalls
  • 7f952fb60a3a831633a0b9620d3b821ef7fcb300 docs(release): v0.3.28 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.28

Jobs with ignore_quota: true now wake up on an assignment

A runner started with ignore_quota never read its user profile, so it never
learned its own user id and ignored every assignment broadcast — the wait ran
its full length and the log said Assignment event ignored: this runner does
not know its own user id yet
on each one, while the card on mcptask.online
named the user the whole time (bug #12473). The profile is now read on every
start; ignore_quota only decides whether the working-hours flag is applied.

Nothing to configure. A running job picks the fix up at its next start: after
mcptask_runner update --self, restart an idle runner (launchctl kill SIGTERM
+ kickstart), or wait for the next scheduled run. The startup log of an
ignore_quota job now carries a [QuotaGuard] user id N read from the user
profile at startup
line; a job whose profile read fails three times goes ahead
without its id and says what that costs, instead of refusing to start over a
flag it would not have applied.

Changelog

Other

  • ee730bd334f95d1f5592e2f9abd98360d4b99382 [#12473] Read the user profile under ignore_quota too, so the stream knows whose assignments to act on
  • 6926a1de6b8ef860d4801211d0d0cb6acab146a7 docs(release): v0.3.27 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.27

Upgrading

Two commands: mcptask_runner update --self replaces the binary; then a bare
mcptask_runner update in any one project on the host, because the bundled
pr skill and the permission baseline both changed. Run it while no runner is
working that checkout. A GitLab project also needs glab installed and
glab auth login done on the host.

mcptask_runner is now on the child's PATH on every project

Binary only — no helper, skill or launcher file changes.

The prompt and the bundled pr skill both tell the coding CLI to run
mcptask_runner pr …, and nothing ever put that name where the child could
find it. Only Ruby projects got away with it: the mcptask-rails-runner gem
installs an executable called mcptask_runner into the bundle's bin directory,
which Bundler has already put on PATH. On a Go, Node, Python or plain
repository — and on any launchd run, whose generated launcher execs the binary
by absolute path and adds nothing to PATH — the first mcptask_runner pr
create
came back

Exit code 127: command not found: mcptask_runner

and the child, having no other way to open a merge request, typed glab mr
create
instead: the one thing the skill tells it never to reach for.

The runner now prepends the directory of its own running binary to the child's
PATH, so the mcptask_runner the prompt names is the binary driving the run
rather than an older copy installed somewhere else. Nothing changes on a Ruby
project: the bundle's shim and this binary are the same version, because the
gem's version is coupled to it.

If you run a binary you built yourself, name it mcptask_runner. The
directory goes on the child's PATH only when a file of that name is in it —
reaching for some other mcptask_runner elsewhere on the machine would be a
different build wearing this run's name — and a build named after the module
(mcptask_go_runner) gets one line in the run log saying exactly that:

[TaskAutoSquash] WARNING: mcptask_runner is NOT on the child's PATH. This runner is …

Releases and mcptask_runner init both install the binary under that name, so
this affects development builds only.

Adoption now works on an rbenv, asdf or mise host

Binary only — no helper, skill or launcher file changes.

Until now the runner looked for the gem its project bundles in GEM_HOME and
GEM_PATH, and nowhere else. rvm exports both; rbenv, asdf and mise export
neither — they put shims on PATH and initialise from ~/.zshrc, which the
bash -l launcher never reads. So on those hosts the search had no roots at
all, every task boundary printed

[Adopt] Gemfile.lock names 0.3.26 but its gem is not installed here — still running 0.3.24 (run `bundle install`)

and both halves of that were wrong: the gem was unpacked under
~/.rbenv/versions/<ruby>/lib/ruby/gems/<x.y.0>, and bundle install had
already run. The host stayed on its old binary indefinitely.

The search now keeps the environment roots first, then derives the project's
Ruby from .ruby-version (walking up) or the Gemfile's ruby line and probes
the documented layouts of rbenv, asdf, mise, rvm, chruby, frum and Homebrew,
~/.gem/ruby/<x.y.0> for user installs, and finally asks bundle show
mcptask-rails-runner
through that Ruby's bin — the only source that can name
a BUNDLE_PATH or vendor/bundle install. Nothing is taken on trust: a
candidate counts only once its interpreter reports the pinned RUBY_VERSION and
names its own Gem.dir, or — where no interpreter can be run — once the
directory is found to actually hold a gems/. Every adoption now logs which
source answered, and a failure lists the roots it searched. The two failures are
told apart as well: a root that exists without the version in it is a missing
bundle install and says so, while finding no gem directory at all names the
pinned Ruby and every candidate it turned down instead.

An affected host cannot adopt its way onto this fix, because the binary that
would do the adopting is the broken one. Once, in the project directory, in the
foreground:

bundle exec rake mcptask_runner:update     # or: mcptask_runner update --self

then a bare mcptask_runner update for the helpers. After that the host adopts
by itself again.


GitLab is a third git host

git_host: gitlab now drives merge requests, and mcptask_runner init writes
the key off a gitlab.com origin by itself. A self-managed instance is on the
customer's own hostname, so nothing in its remote says "gitlab" and nothing
guesses from one: such a project is installed with

mcptask_runner init --git-host gitlab

There is no credential to place. GitLab is driven through glab, which holds
its own login the way gh does, so init writes no token file and no
environment variable — it names the one command that makes the host work, and
glab auth login on that host is the whole of the setup. Nothing about Bitbucket
or GitHub changed: a project on either gets exactly the install it got before.

Two things follow that an operator sees. A GitLab project's
.claude/settings.local.json picks up Bash(glab:*) and
WebFetch(domain:gitlab.com) on the next mcptask_runner update — approvals no
other host is handed, the same way gh belongs to a github project alone. And
the pull-request template a GitLab project is told to follow is
.gitlab/merge_request_templates/Default.md, which is what GitLab's own web UI
puts into a new merge request; pr_template: path: still overrides it, and a
Bitbucket project still gets no template line at all, because Bitbucket Cloud has
no such convention to name.

A self-managed instance needs no address here. glab auth login --hostname
gitlab.example.com
once per machine, git_host: gitlab in the project, and that
is the setup: every question the runner asks is a glab run in the project's own
checkout, and glab resolves the host from that checkout's remote against the
credentials it stored. The runner keeps no URL of its own — a second place for the
address to be written is the first one to go stale. Hostname derivation stays
exact, so gitlab.com derives the key by itself and a customer's own domain does
not: a substring match on "gitlab" would point glab at somebody else's service.

mcptask_runner pr checks prints ONE row on GitLab, and that row is the whole
verdict rather than a summary of others. The host has no per-check object: a merge
request has one pipeline, and the pipeline's single status is what GitLab
publishes and gates merging on, so the report carries the head pipeline as one
check named after it. success is the only pass; failed, canceled and
canceling are red; everything else — skipped and manual included — is
IN_PROGRESS and is waited on, because a pipeline that never ran is not a green
one. A project with no .gitlab-ci.yml answers NONE, which is not a pass either.

Four conformance scenarios pin the behaviour (21–24: a manual merge request, a
green pipeline merged and verified, a red pipeline twice, and a merge the host
would not confirm). They drive a fake glab first on the PATH and assert its argv
word for word — including the --auto-merge=false that stops glab mr merge from
scheduling itself, exiting zero, and letting GitLab merge the branch ten minutes
later with nobody watching.

A failing gh or glab now says what it said

Binary only — no helper, skill or launcher file changes.

Until now, a refusal from either CLI reached the operator and the run log as its
exit status and nothing else:

Error: glab mr create --title x --description y --draft --yes: exit status 1

What glab actually said was a 409 — this branch already has a merge request —
and it was never lost on the wire: exec.Cmd.Output() captured the child's
stderr into ExitError.Stderr, and the wrap that named the command kept only
ExitError.Error(), which is the string "exit status 1". Every reason a merge
can be refused on those two hosts arrives that way: a protected branch, an
approval rule not satisfied, a merge train, an expired login. The runner reported
all of them identically.

It now repeats what the CLI said, in the form the Bitbucket adapter already used
for the host's own error envelope:

Error: glab mr create --title x --description y --draft --yes: exit status 1: ERROR Post https://gitlab.com/api/v4/projects/1/merge_requests: 409 {message: [Another open merge request already exists for this source branch: !1]}

One line: a two-line ERROR block is joined rather than allowed to wrap the run
log around it. stderr is quoted when there is any, and the first line of stdout
when there is not, because glab prints some refusals there. A failure with no
child behind it — a timeout, a glab that is not installed on this host — gets
nothing appended, since it has nothing to quote and its own text already names
what happened. Nothing about exit statuses or control flow changed: gh pr
checks
still exits non-zero on a red CI and that is still read as a verdict.


A machine's own pull-request skill no longer outranks the runner

Binary and skills — a host that installs this release should re-run
mcptask_runner update so the bundled pr skill and the permission baseline
land beside the new binary.

The first real GitLab run found the gap the mcptask_runner pr work of the
previous release had left open. The step said "CREATE PULL REQUEST", named the
command, and forbade "a host-specific CLI" — and the child used neither. It
reached for a skill installed machine-wide called pull-request-creator, whose
description offers to create a pull request "following WorkVector conventions",
which reads as the house style rather than as somebody else's host. That skill
drives GitHub's CLI, so on a GitLab project it produced

gh pr create …
→ none of the git remotes configured for this repository point to a known GitHub host

before improvising its way to glab mr create. The merge request was opened by
luck: on a project whose host has no CLI at all, the same route produces two
failures and nothing else.

Nothing was violated in the child's reading of the prompt, which is the point.
The step's own title is word for word what that skill advertises, and the step
never said the WORDS belonged to the command. It does now: "create a pull
request", "create a PR" and "open a merge request" are declared to mean
mcptask_runner pr create, and anything else offering to answer them — another
skill, another script, a command you know — is declared wrong, because each is
written for one git host and this project may not be on it. The bundled pr
skill leads with the same phrases and says outright that it outranks any other
pull-request skill on the machine. Neither names a host or a CLI; the neutrality
guards would refuse it, and the runner cannot know what is installed anyway.

One standing approval is gone from the permission baseline:
Skill(pull-request-creator). The installer was handing every project it
touched an approval for the very skill the prompts forbid. Removing it is all
this file can honestly do — the merge is a union, so a project that already has
the entry keeps it, and an implement run is launched in a permission mode that
skips these checks. What decides it is the prompt and the skill description.

A published pull request now reaches the run record even when the command was
not used.
The same run recorded {"status": "success"} with no pr_number,
while the runner had printed the merge request's number on the card and in the
log: only the mcptask_runner pr envelope ever stored one, and the child had
never run it. The CLI's own published-change event is a second source now,
below the envelope — which still wins, whichever arrives first — and strictly
read: an identifier that is not a positive integer is dropped rather than turned
into a number. Downstream of that are the merge verification, the effort line
and the card's closing message.

Changelog

Other

  • a10dab6b5fcf0b38a0b420c00b406b90f332a419 [#12418] Give the dry prompt the harness's fetch block
  • 9fba8128f0c481d15f67200de2e48d012827d85c [#12419] A close code is never destroyed, only misfiled, and the chaos test cannot prove it either way
  • 791cce8861066bb03f70ec4efc968f732130c99b [#12435] Drop a GEM_HOME that names no directory, and say so
  • 9aafbe1dd50684dc1e04f225f4b1aa67ccc28832 [#12435] Find the bundled gem on an rbenv, asdf or mise host
  • f95cc32f54aa4edc41a997118551525a00f54fc4 [#12435] Keep the gem search inside the roots the caller named, and off Windows's ruby.exe mismatch
  • fc4affd7ee63ec88e93d7bbdea32ca79b2b10e53 [#12437] Keep the host's test lock out of reach of tests and the stress day
  • 3cf39989ab8addfc1bbe3291c57d7b7412070819 [#12437] Put the conformance sandboxes outside every git repository
  • 54b60f2e96ea3710ccafb3f702f4571f62e8064b [#12449] A gitlab adapter that drives glab, and the places glab is not gh
  • 2abf0832e6337cf3ca95ef07ac71ea07f655241d [#12450] Everything that names a host by name learns the third one
  • d5999c68335e64dd9bf47ee21bb3ca49b2bbaf44 [#12451] GitLab proved: four scenarios against a fake glab, and two runs against the real one
  • 3e5c44a3adb7872fc6204d82d5ef81889e9053d3 [#12454] A refused gh or glab command repeats what the CLI said
  • 7095704f11f52dcda65147c623fead2d76004b3a [#12455] Claim the words "create a pull request", and read the number off the stream
  • 137eda5f6711e269680576f9dc03d7f6a956e536 [#12456] Put the runner's own binary on the child's PATH, under the name the prompt uses
  • c2a68e166540891078eedbb0323db2020b0c3a7f docs(release): v0.3.26 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.26

Upgrading

mcptask_runner update --self replaces the binary; then run a bare mcptask_runner update in any one project on the host, while no runner is working that checkout — the bundled pr skill gained the review commands and the binary does not rewrite installed skills on its own.

A close the server explains is logged with its explanation

When mcptask.online ends the dashboard socket with a close code — going away
during a deploy, a policy violation, an internal error — the runner's log now
says so, instead of sometimes reporting only use of closed network connection.

A dying socket is noticed twice: by the read loop, which has the close code, and
by whatever snapshot write was in flight, which has only the symptom. The
reconnect notice could be composed before the read loop was scheduled, and the
close code — the half that says who ended the connection — was then dropped on
the floor. It is now printed on a line of its own when it arrives that late:

[EventStream] WebSocket closed (the snapshot write failed: use of closed network connection), attempting reconnect...
[EventStream] the read loop's account of that close landed after the notice: server closed it, code 1001 going away

Nothing branches on the close code, so no behaviour changes: the runner redialled
before and redials now. What changes is that a run log attached to a bug report
says whether the server let the connection go on purpose — which decides whether
there is anything to go and look at on the server side at all.

What to do: mcptask_runner update --self. Binary only — no config change,
no reinstall of the .claude/ assets.


No prompt the runner composes names a git host any more

The review and reviews executors were the last two that did. Everything else
moved onto mcptask_runner pr in v0.3.24; these two could not follow, because
prhost.Host had no question for "what did the reviewers say on this pull
request" or "what is open on this repository", and a prompt cannot be pointed at
a command that cannot answer it. So they went on typing gh pr view, two
gh api repos/{owner}/{repo}/pulls/{n}/… reads and a gh pr list --state open —
four instructions that do nothing on a project hosted anywhere but GitHub.

The interface has both questions now, and two new subcommands expose them:

mcptask_runner pr list --open      # every open pull request, no search
mcptask_runner pr reviews 1234     # the verdicts, then the comments

reviews is one flat list across what each host splits differently — GitHub's
submitted reviews and inline comments, Bitbucket's participant verdicts and its
comments. A note carrying a state is a verdict (APPROVED,
CHANGES_REQUESTED, COMMENTED); one carrying a path and a line is inline
on the diff.

Two things it deliberately does not claim. bot: true is the host marking an
app, and Bitbucket Cloud marks none, so the field's absence is not a promise
that a person wrote the note — the pr skill says to read author there and to
say which you did. And there is no resolved flag on either host: whether a
review has been addressed is a judgement made by reading it, which is what these
prompts did when they called the REST endpoints directly, and a field only one
adapter could ever fill would be an invitation to trust a false the other host
never said.

The guard list in TestSpineNamesNoGitHost is now empty, which is the point of
keeping it: it was the record of what was left, and an empty one is a claim every
prompt is held to.

What to do: mcptask_runner update --self for the binary, then a bare
mcptask_runner update in each project — the bundled pr skill gained the two
commands, and a project still carrying the old copy will not know they exist.

Auto-squash asks the git host whether its checks passed, before merging

The auto-squash CI step used to have one verdict in it: the local bin/ci. A
green run merged, a red one left the pull request open, and the host — which is
the thing actually running the pipeline the project configured — was never
asked. A run on a project with no bin/ci merged on no verdict at all: it
skipped the local gate, merged immediately, and the host's pipeline reported
SUCCESS a few minutes later. It happened to be green. Nothing in the runner
would have noticed if it had not been.

The step now has two verdicts and the merge waits for both. Between the local
gate and the merge the child runs mcptask_runner pr checks <pr_number> and
reads .checks.state:

  • SUCCESS — merge.
  • FAILED — status ci_failed, nothing merged, the pull request stays open with the red check named.
  • IN_PROGRESS — wait two minutes and ask again, at most ten times. Still running after the last ask is ci_failed; an unfinished check is not a passed one.
  • NONE — merge. A check nobody reported is not a pass, but a project whose host runs no CI must still be able to auto-squash, and the local gate is what carries that case.

Which of the four decided the run is now a required field of the result marker,
status_detail, so a ci_failed in the effort trail says whether it was the
local suite, a red check on the host, or a build that never finished.

One text for every host, as the rest of the spine is: the command is
mcptask_runner pr checks on GitHub and on Bitbucket alike, and the adapter
behind it answers in the same four words.

What to do: mcptask_runner update --self. Binary only — no config change,
no reinstall of the .claude/ assets.

init --home-dir re-roots the Bitbucket credential, and a re-run says what it did with it

Two fixes to the step that places a Bitbucket credential during init
(#12424).

--home-dir re-roots everything an install writes outside the project: the
launcher script, the token directory, the shell rc file, the scheduled job. The
Bitbucket credential was the one file that escaped — it resolved the account's
own home and wrote there, so an install aimed at a scratch directory put a secret
into ~/.mcptask_env.d/bitbucket_credentials instead, where a second machine's
credential would then sit in a directory nothing sources. It now goes under the
same home the mcptask token does, out of one shared resolution rather than two.

The second half is what a re-run says. The credential step used to hang off the
path that newly wrote git_host:, so the two shapes of re-run that change
nothing — the key already in the file, or --git-host bitbucket repeating what
the file already says — printed git_host: bitbucket already set … and stopped.
That is exactly the run an operator types after making a token. It now runs
whenever the resolved host is bitbucket, and says which file it left alone:

[Installer] git_host: bitbucket already set in …/config/mcptask_runner.yml
[Installer] [Bitbucket] credentials already in ~/.mcptask_env.d/bitbucket_credentials — left alone. To replace them (a rotated token, or a different account), re-run init with BITBUCKET_ACCESS_TOKEN, or BITBUCKET_EMAIL and BITBUCKET_API_TOKEN, set.

The no-clobber rule is unchanged: an install handed nothing still writes nothing.
It just no longer does it silently.

What to do: mcptask_runner update --self. Binary only — no config change,
no reinstall of the .claude/ assets. A host installed with --home-dir that
has a Bitbucket credential is worth one look: the file may be in the account's
home rather than under that directory.

Run records say how the attempt ended

log/runs/run_*.json used to end like this on a run that had gone perfectly:

"status": "processing",
"termination": "result",
"final_status": "processing",
"result": { "status": "success", "pr_number": 3, … }

Two of those three lines were about a run that was still going. The record is
stamped on the way out of the streaming loop, one line before the session is
moved off processing, and it is never written again — so the field a reader
reaches for to tell how a run ended reported the state the run had been in while
it was working, and every clean run looked identical to a run that hung.

Both now answer the question they are named for. final_status carries the
child's own verdict where there is one — success, ci_failed,
merge_unverified, no_more_tasks — and the session's terminal status where the
child never answered, which is error on every kill path, exactly as it already
read there. status carries the terminal frame: finished on a clean ending,
error on a kill.

The record's shape is unchanged: same members, same order, no new field, nothing
for the dashboard to learn. Records written by older binaries keep their old
values; this only changes what is written from here on.

What to do: mcptask_runner update --self. Binary only — no config change,
no reinstall of the .claude/ assets.


Changelog

Fixes

  • 2e7ddea2857effacff589672145c8e02c6fdd236 fix(eventstream): a close code that arrives after the notice gets its own line (task #12421) ### Other
  • f3a9d1dbb050938efe31d3eb8f16dc47de2fad62 Ask mcptask_runner pr for reviews and for the open queue (task #12420)
  • 6ca5eb9ae3a8f8af8d35ae2baa90d637d7f53855 Ask the git host's checks before the auto-squash merge (task #12425)
  • b7595569ae0a929c8f48cb6fbd83d0d47980524d [#12424] Re-root the Bitbucket credential, and speak about it on a re-run
  • 47792ccc135245fb7b555b3a95b58d890543aeb1 [#12426] Make the run record say how the attempt ended
  • 6daeb941aeaa518cf1b819b35f918d7c2ab59ff7 docs(release): v0.3.25 shipped, the next-tag notes start empty

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.25

Upgrading

mcptask_runner update --self replaces the binary; then run a bare mcptask_runner update in any one project on the host, while no runner is working that checkout — this version changes the installed data pack (the new pr skill, per-host baseline permissions, ci_wait, the test-lock helpers), and the binary does not rewrite those on its own.

Bitbucket Cloud projects can be driven

git_host: bitbucket now selects a real adapter instead of an error. The runner
opens, finds, reads, merges and checks pull requests on Bitbucket Cloud through
its REST API 2.0 — there is no Bitbucket CLI to shell out to — and
mcptask_runner pr works there unchanged, because it goes through the same
interface gh does.

What to do on a Bitbucket host. Put a credential in the environment and
re-run mcptask_runner init, which writes it to
~/.mcptask_env.d/bitbucket_credentials (0600) beside the mcptask token, so it
reaches both your own shell and the scheduled job. One of:

  • BITBUCKET_ACCESS_TOKEN — a repository or workspace access token, sent as Bearer. The one to use for a machine.
  • BITBUCKET_EMAIL + BITBUCKET_API_TOKEN — the Atlassian account's email (not a Bitbucket username) and an API token, sent as Basic.

App passwords are not accepted. Atlassian stopped serving them on 9 June
2026; BITBUCKET_USERNAME / BITBUCKET_APP_PASSWORD are recognised only so that
init and the adapter can say so, rather than authenticating with something that
fails at merge time, after the work is done.

Setting both schemes at once is refused, naming both, and writes nothing — no
credential is ever picked on your behalf. A re-run of init with nothing set
leaves an existing credential file alone; setting the variables again is how a
rotated token is installed. Values are never printed, by init or by a 401.

What a GitHub host has to do. Nothing. gh still drives it, argv for argv.

One mapping worth knowing. Bitbucket's SUPERSEDED counts as DECLINED, not
MERGED: those commits may well be on the destination branch, but this pull
request was not merged, so an auto-squash run over one ends merge_unverified
and a person looks.

How far this is tested. The conformance suite now drives a Bitbucket project
in both modes against a scripted host, on all three coding CLIs: a manual run
that opens a pull request and puts it on the card, an auto-squash run whose merge
is confirmed by a GET on the pull request rather than by the agent's claim, a run
whose CI fails twice and leaves the pull request open, and the same recording as
that third one with the host answering OPEN — which comes out
merge_unverified. The last two are a pair on purpose: a runner that had stopped
verifying would pass the confirmed one and fail the other.

One environment variable comes with that, and is worth knowing about even though
almost nobody needs it. BITBUCKET_API_BASE_URL points the adapter at an API
root other than api.bitbucket.org — for a host behind a proxy that terminates
Atlassian's API on its own name, and for the conformance suite, which uses it to
reach a fake host on loopback. Unset means Atlassian's own root; a wrong value
fails at the first request, naming the URL it could not reach.

A once_dry run on a project with no assigned work no longer files a bug

once_dry used to have one ending in its prompt: success. So a dry run against
a project whose queue was empty had nothing to answer with — the child fetched
the next piece, was told "No available tasks or stories found", went looking for
one by hand, and then reported status: "error", which is a hard failure. The
runner filed a high-priority piece in its own Errors epic about a project that
was simply idle, and did so again every time that project was dry-run.

An empty queue is now the mode's own answer: the run ends no_more_tasks, the
log says No tasks available, the dry run had nothing to display, and nothing is
filed.

What to do. Nothing on the host — the change is in the prompt the runner
composes, so it takes effect with the new binary. Any pieces already filed under
Runner error: result — <project> for an idle project can be closed.

An API refusal is now named instead of retried

When the coding CLI ends its turn because the API refused it, the runner stops
and says which refusal it was. It no longer reads that as "the child forgot the
result marker", so the three --continue retries thirty seconds apart are gone —
none of them could ever have succeeded — and the ending is no longer filed as
stream_ended.

Four endings, and what each asks of you:

Termination What happened What to do model_unavailable the configured model is not being served — retired, removed, or spelled differently by this provider fix model: in config/mcptask_runner.yml; the message names the model and quotes the provider not_authenticated the CLI has no credentials sign the CLI in as the user the runner runs as on that host usage_limit the account is past a hard cap that clears on a date nothing, until that date — the message carries it verbatim api_error the API refused in words no harness profile recognises read the quoted text; if it is worth naming, add its phrase to the profile's usage_limit / model_unavailable / not_authenticated list

What changes for an operator. usage_limit files no bug piece — it is a
budget, like the day's quota and the usage window before it, and an account with a
monthly ceiling would otherwise file one piece a month. The day still ends,
because nothing can be spent until the cap clears. The other three do file a
piece, and it names the condition and the remedy rather than saying the stream
ended. The dashboard card and the run log's error_message now say the same
thing, where all three of the reports that prompted this carried null.

What does not change. A 429 still gets its eight patient waits and a 529 its
ten — a refusal the profile could name outranks them, an unnamed one does not — a
context overflow is still an overflow, and a turn that failed for a reason a
resume can fix still takes the marker retry it always had.

Recognition is Claude Code's wire shape for now, that being the only one these
conditions have been recorded on. A Codex or OpenCode host hitting the same wall
still spends the marker retries.

The lock guard no longer refuses commands that merely name a test run

check_test_lock — the PreToolUse hook that stops a second suite starting
beside somebody else's — decided what a test run was by looking for a recognised
invocation anywhere in the command text. A space counted as the start of a
command, and every word inside a quoted string has one in front of it, so a
command that only talked about a test run was refused while a suite was
running:

git commit -m 'fix: bin/ci now takes the lock'    BLOCKED, and it runs nothing
grep -q '=== bin/ci exit:' "$LOG"                 BLOCKED, and it is the line inside /ci-wait

The same anchor was wrong in the other direction, which is the half that
mattered: an invocation had to be preceded by whitespace or nothing at all, so
../other-worktree/bin/ci — how a story branch runs the gate — matched nothing
and a genuine second suite was waved straight through.

The command text is now read the way a shell reads it, into words, and only a
word in command position can be a test run: the first word of the line or of
a new command (after &&, ||, ;, |, &, a newline, (, `, $(),
optionally behind a wrapper that is not the command itself (sudo, env,
time, nohup, an option to one of those, a VAR=value assignment) or an
interpreter that introduces one (bash bin/ci, sh -c 'bin/ci', and
python -m pytest, which was not recognised before). Quotes and # comments
are tracked, and a path-bearing invocation counts. The
exemption for the lock's own helpers (test_lock, run_with_log) is decided
the same way, so a commit message naming one of them no longer exempts a real
test run sharing the line.

Blocking is unchanged for everything that actually runs a suite: bin/ci,
bin/ci --fast, cd worktree && bin/ci, and every command the project declares
in .claude/test-commands.json.

What to do. Run mcptask_runner update on each host — the hook is a helper
in ~/.claude/bin, not a file in any checkout, so a project that only pulls the
new binary keeps the old guard until the helpers are reinstalled. Nothing else
changes, and git commit -m with bin/ci in the message works again.

The machine-wide test lock: reinstall the helpers on every host

~/.claude/bin holds the copies of the helper scripts that actually run, so
none of the fixes below reaches a machine until its helpers are reinstalled —
mcptask_runner update on each host. A repository carrying the fix is not a
fixed machine, and the lock is the one piece of tooling where the difference is
invisible: a host still running the old test_lock keeps serialising its suites
exactly as badly as before, and says nothing about it.

Run the update while no suite is in progress on that host. The scripts are
replaced in place, and a run that is mid-flight through the old one keeps the
file it started with.

test_lock records COMMAND_PID and LOGFILE on Linux as well as macOS

set_command_pid and set_logfile edited the lockfile with sed -i and an
empty backup suffix as a separate argument, which is the BSD spelling: GNU sed
reads that empty string as the script, the real script as a filename, exits 4
and writes nothing. Both call sites discard the failure, so on Linux the lock
never gained either field and nothing said so.

Three consequences, all of them silent, all of them gone now: a lock whose
COMMAND_PID stayed empty was reapable while its suite was still running; ci_wait
could not tell a crashed run from a slow one, because the check for that reads
COMMAND_PID; and a LOCKED verdict could not name the other run's log, so
OTHER_LOG was always unknown on that platform.

Both fields are now written by filtering the key out of the file and renaming a
temporary copy over it — no in-place edit, nothing to spell two ways, and a
reader can no longer catch the file half-built. (task
https://mcptask.online/jchsoft/tasks/12402)

Every run through the helpers is ten seconds shorter

run_with_log started its stall watchdog with a command substitution, and a
backgrounded subshell inherits that substitution's stdout — so the line meant to
start a watchdog and move on blocked until the watchdog's next sleep returned.
Measured against a command that exits instantly: the command was gone at 0.03 s
and the Exit code: footer arrived at 10.8 s. Every run paid it, whatever the
command, because the wait, the tee teardown and the footer all queued behind
that line. The same measurement is now about a second.

/ci-wait and /test-wait answer sooner as a result, and so does anything
watching for the footer. ci_wait's 15-second footer grace is unchanged and now
pure headroom rather than a measured need — nothing pays it on a healthy run,
since it returns the moment the footer appears.

Two more corrections in the same file: the stall watchdog sized the log with
stat -f%z alone, which is BSD-only, so on Linux it read every log as zero
bytes and dumped thread traces into a run that was not stalled; and the watchdog
subshell's own stray output now lands in the log instead of on the launcher's
stderr.

run_with_log is also now maintained in this repository rather than vendored
from the retired Ruby gem, which is what made the fix possible here at all.
(tasks https://mcptask.online/jchsoft/tasks/12401,
https://mcptask.online/jchsoft/tasks/12402)

A lock is now held for as long as the run, and released only by that run

This is the behaviour change to read before updating a shared host. The lock did
not protect what it appeared to protect, in three independent ways, and all three
were silent while they happened.

A lock is stale when nothing it stands for is alive, and nothing else makes it
stale.
Age is no longer consulted at all. Before, age >= 900 was tested
first, ahead of any look at the command, so a suite that ran past fifteen
minutes lost its lock while it was working — and a full bin/ci runs to about
that mark. A lock whose command is alive now keeps it at any age; a lock whose
recorded command has died is over immediately.

An empty command pid is no longer a ten-second fuse. acquire used to leave
COMMAND_PID empty and fall through to a pidfile only run_with_log ever
writes, so a lock taken around anything else — a bare bin/ci, an operator
being a good citizen — was reapable from its tenth second, permanently, with no
warning to either side. acquire now records the process that asked for the
lock, and the sentinel's 900 s backs that up, so an unregistered lock lasts as
long as the shell that took it and then as long as the sentinel. The pidfile
branch is gone, and with it a path whose two sides derived the same filename from
different places.

A release now has to prove it is the run that acquired.
release_if_owner compared CALLER and PROJECT — a constant per skill and a
constant per worktree, both reused by a re-run after a rebase — so a run whose
own lock had already been reaped could reach its cleanup and release the NEXT
run's lock, two minutes into a suite that had done nothing wrong. acquire now
issues a token, prints it after ACQUIRED and records it; release_if_owner
<caller> [instance]
takes the token, or the command pid, or the holder pid, and
answers not-owner when the instance is not this lock's. run_with_log and
bin/ci pass theirs. A release with no instance still works, for callers that
predate the argument, and now says in as many words that it matched on the name
alone.

test_lock status says which case a lock is in. HELD_BY=command … (does
not age out), HELD_BY=holder … (no command pid recorded yet), HELD_BY=sentinel
…
with the time left, or STALE=yes. The first line still starts with LOCKED
or FREE, which is what /wait-unlock reads.

The PreToolUse guard, check_test_lock, was rewritten to the same rules in the
same commit. It had its own copy of the old ones, so on both counts above it
would have waved a test command straight into a running suite while test_lock
was still refusing to hand the lock over.

Two side effects worth knowing. run_with_log now records in the log whether the
lock learned its command pid — the line reads Lock: COMMAND_PID set to …, or
Lock: no lockfile — this run is NOT serialised against other suites on this
machine
, which is a legitimate state for a run nobody took a lock for and a
useful thing to be able to check afterwards. And the Windows flake in the
lock-guard tests around the ten-second cliff
(https://mcptask.online/jchsoft/tasks/11897) is gone with the cliff itself.
(task https://mcptask.online/jchsoft/tasks/11852)

Pull requests go through mcptask_runner pr, on whichever host the project is on

The prompts the runner composes used to say gh. Not always out loud, which was
the harder half: the auto-squash spine merged with gh pr merge --squash
--delete-branch
and gated its own success on gh pr view --json state, while
the CREATE PULL REQUEST step named no command at all — and a step that names no
command gets gh anyway, because that is what a model reaches for when nothing
says otherwise. Either way a project on Bitbucket Cloud was being told to run a
binary it has not got.

Every one of those is now mcptask_runner pr create|list|view|merge|checks,
which asks the adapter git_host: resolved for that project (task
https://mcptask.online/jchsoft/tasks/12362 put the adapters in). The command
prints one JSON object on stdout, and the workflow tells the child to read
.pull_request.number out of it rather than from its own recollection. A new
bundled skill, pr, carries the five commands and their output shapes.

The runner reads that JSON too. The pull request a run opened used to reach
the dashboard through an event only Claude Code emits, so a Codex or OpenCode run
opened one and the card said nothing; and its NUMBER reached the runner only when
the child put it in the result marker, which about three quarters of real markers
do not. Both now come out of the command's own output, which every harness hands
back the same way. A result with no pr_number takes the one the run was seen to
open — the child's own answer still wins when it gives one, and nothing is
invented when no pull request was opened at all.

Permissions are now per host. Bash(mcptask_runner pr:*) is in the baseline
every project gets. Bash(gh:*), Bash(gh pr checks:*), Bash(gh pr view:*)
and the three github.com WebFetch domains are installed only into a project
whose git host resolves to github; api.bitbucket.org and bitbucket.org only
into a Bitbucket one. A project whose host cannot be worked out gets the shared
list and nothing else — nothing falls back to another host's approvals. Existing
entries are never removed, so a project that already has Bash(gh:*) keeps it.

The pull-request template default is GitHub's alone.
.github/pull_request_template.md is GitHub's own convention, and telling a
Bitbucket project to follow it meant the agent looked, found nothing, and wrote
whatever description it liked, with nothing reporting that the instruction had
missed. A git_host: github project still gets that path and that line, byte for
byte. Any other project gets whatever it declares under pr_template: path: and,
declaring nothing, gets no template line in the prompt at all.

What to do. Run mcptask_runner update on each host: the pr skill is a new
file under the project's skills directory and the permission split is a merge
into .claude/settings.local.json, neither of which arrives with the binary
alone. Run it while no runner is working that checkout — the new files would
otherwise land inside somebody's task commit. Nothing else is required, and a
project already carrying git_host: needs no config change; one that does not
gets its host read off git remote get-url origin at run time, and
mcptask_runner init writes it down for good.

Still naming gh: the two review executors (review and reviews). They
read review threads and enumerate every open pull request on a project, and
internal/prhost models neither — its six questions are create, list-for-task,
view, by-branch, merge and checks. Rewording them to name no host would leave an
agent told what not to use and not told what to use instead, so they are excluded
by name, with the reason in words, in TestSpineNamesNoGitHost. Extending the
interface to cover them is its own piece.
(task https://mcptask.online/jchsoft/tasks/12364)

/ci-runner reads a green run that prints no summary block

A bin/ci that prints one line per step and no aggregation at all — no CI
SUMMARY
, no TOTAL RESULTS — matched neither shape ci_wait recognised, so
every green run on such a host ended in NO_SUMMARY_RECOGNISED plus twenty
lines of tail. That tail was not empty, which is what made it hard to spot: on
the run that filed this it happened to carry three of the nine step lines and
lost both of the ones a reader triages by, so the orchestrator reported a ragged
excerpt as if it were the run's summary and could give no step count or timings.

ci_wait now recognises a third shape, the per-step lines themselves:

✅ <step name> passed in 4.88s
❌ <step name> failed in 1m31.30s

They are emitted in order, ANSI-clean, in place of the fallback. A red run
carries both spellings — later steps keep running after one fails — and the
failure path already passed them through its tail filter untouched, so the same
shape now reads on both exits. NO_SUMMARY_RECOGNISED stays for a log that
matches none of the three, and now names all three in its message; it also no
longer spends its twenty lines on the log's own ==== rules, which the two
recognised branches had always dropped and it had not.

/ci-runner's skill body documents both shapes side by side instead of the
older one alone.

What to do. The fix is in ci_wait, which is installed onto the host rather
than compiled into the binary, so a new binary alone does not change it: run
mcptask_runner update in the project to refresh ~/.claude/bin/ci_wait and the
/ci-runner skill. (task https://mcptask.online/jchsoft/tasks/12413)


Changelog

Fixes

  • 1b6b96a7af616625a981712fcd6db8537a053382 fix(dry): an empty queue is an answer, not a bug piece (task #12407)
  • 1ac4ad2b9e8cadbecc497c93cf811781e469efd6 fix(eventstream): the throttle's clock is shared with the stream's own goroutines, so a test hands it over under a mutex (task #11688)
  • b463017bb9094c5304ae4315ff932e9a242a9034 fix(executor): the API refusing a run is named, not retried for a marker it will never give (tasks #12405, #12406, #11850)
  • a74dab9409d1133ef38a1a0a4fa2cbb388fd1e58 fix(helpers): a lock is held while its run lives, and given back only by that run (task #11852)
  • 584a71dd709ce416d09035aed18e4a88bf10d492 fix(helpers): the lock records its command pid and its logfile on either userland (task #12402)
  • 3b202a43d607cbc6957ba3faed2d39c1e3d61094 fix(helpers): the stall watchdog no longer holds the footer for a whole interval (task #12401)
  • 50b0446ede6def664d97428f61ce8ac379fa1d66 fix(stress): an orphan may end itself, and the sweep says which ones did (task #12403) ### Other
  • 4867ec85fccea0e4354333da18c647dd2b69ae3a Recognise an API refusal on every dialect, not just Claude Code's
  • 90353f488c2a233cbe78e862f466798b6e278ca3 Skip the 0600 check for the Bitbucket credential file on Windows
  • 0cb0ada0f2c2de1f328769c6bb44210d77f224b3 [#12362] Ask a PRHost, not gh: internal/prhost + mcptask_runner pr
  • e0a591aafc5e606230bddcebdde5d915b68456d3 [#12363] Drive Bitbucket Cloud: a prhost adapter over REST API 2.0
  • 6333beb769954a50eb88a6b3d22bab9c2d2fb6f8 [#12364] Say mcptask_runner pr, not gh: the prompt, a skill, and per-host approvals
  • 0d46b797c5cbf4e178324077b0c412c663eaf486 [#12365] Drive a Bitbucket project in conformance, and say so in the README
  • 1e4f48e9ef1deb729807cf4f4a679691ef1d3aa0 ci_wait: read a step record that comes with no summary block
  • e4418e46f7a757cd60f5264b387b74cecf8cce12 docs(release): v0.3.24 shipped, the next-tag notes start empty
  • 2425e84c9189223aafb21084742468d0f723f5f9 fix(check-test-lock): naming a test run is not running one (task #11674)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.24

Upgrading

Two commands this time: mcptask_runner update --self for the binary, then a bare mcptask_runner update in each host project — it writes the now-required harness: key and rewrites the helper scripts in ~/.claude/bin. Details below.

harness: is now required in config/mcptask_runner.yml

The runner drives a coding CLI named by a profile, and there is no default. A
project whose config does not name one refuses to start:

harness: is not set in config/mcptask_runner.yml, run `mcptask_runner init --cli <name>`; known profiles: claude, codex, opencode

What to do. Run mcptask_runner update on each host. A project this runner
already installed into — one with a .mcp.json and a
.claude/skills/.mcptask_runner_manifest.json — has harness: claude written
for it once, and the update says so in its output. That is the whole migration
and it changes nothing else about how the project runs.

A project update does not recognise (and any new project) needs
mcptask_runner init --cli <name> instead. init without --cli on a project
that has never named one is refused rather than assuming claude: assuming it is
how a host that installed a different CLI gets a Claude command line built for
it, fails at the first launch, and is told about a binary rather than about the
key nobody set.

A host that already sets launcher.command has said which CLI it starts, so
init and update now derive the key from it when exactly one profile claims
that name — printed, written into the file, never inferred at run time — and a
run whose launcher.command contradicts its harness: key is refused before it
starts, while a command whose program cannot be read (a shell, a wrapper script)
is logged and allowed; point launcher.command at a mock and you write
launcher.cli_check: false beside it, and a CLI that really runs under another
name goes in the profile's binary.aliases.

Where the harness shows up: the runner card on mcptask.online carries a harness
label beside the model (an additive snapshot member the server accepts since
2026-09-08; older runners keep working without it); mcptask_runner version and
the scheduled job's per-run log open with a Harness: <name> -> <binary> line
after the version line; a runner bug piece names the harness and attaches the
profile's own config files instead of the Claude Code settings only.

init --cli also adds config/mcptask_runner.yml to .gitignore if it is not
ignored already. The file is per-machine — harness, schedule times, model pins —
and two developers sharing one committed copy overwrite each other's answers.

Codex CLI support

mcptask_runner init --cli codex sets a project up for the Codex CLI instead of
Claude Code. The work loop, the watchdog, the dashboard card and the mcptask.online
protocol are unchanged; what differs is the command line, the words the prompt
uses for tools and skills, and what init writes:

  • .codex/config.toml in the project, with the mcptask.online MCP server marked required = true. The entry names the environment variable holding the bearer token (bearer_token_env_var) and never the token itself, so the file is safe to commit.
  • [projects."<path>"] trust_level = "trusted" in ~/.codex/config.toml (or under $CODEX_HOME), because Codex reads a project-level config only for a project it trusts.
  • Eight skills into .agents/skills, invoked as $test-runner, $ci-runner and so on. Helper scripts stay in ~/.claude/bin, shared with any claude project on the same machine.
  • AGENTS.md, pointing at the project's existing CLAUDE.md rather than copying it.

Both config writes append and never rewrite: an entry that already says what the
runner would have written is left alone, and one that says something else is
reported as a conflict and left as it is.

One thing to do by hand: codex login. The runner never logs a CLI in. It
checks, before a run starts, that this one is logged in already — codex login
status
has to exit 0 — and refuses with the probe's own output when it does not.
An unauthenticated headless Codex produces a failed turn with nothing done, for
as long as the loop runs.

Read the sandbox note before scheduling an unattended Codex run. The
implementing executors launch codex exec with
--dangerously-bypass-approvals-and-sandbox: full access, no approval prompts,
which is the parity with Claude Code's bypassPermissions this runner has always
used. Dry runs, triage and review get --sandbox read-only, plus one -c
override that approves the mcptask-online server's MCP tools and nothing else.
That second token is not optional: codex exec is non-interactive, which means
its approval policy is never, and never REFUSES an MCP tool call rather than
waving it through — without the override, every read-only-class run is cut off
from mcptask.online and cannot fetch the task it was started for. A write from a
read-only class is still refused by the sandbox. The checkout the runner is
pointed at is the only boundary there is.

How far Codex support has been proven. The conformance suite runs on
--dialect codex as its own CI job (twelve of fourteen scenarios; 06 and 07
describe a state Codex cannot reach and say so in the file), and the chaos stress
day runs on it too. Both drive a mock CLI.

Since 2026-09-09 the real codex binary has been driven as well, on codex-cli
0.153.4: a dry run, and a task worked end to end — branch, edit, go test,
bin/ci, pull request — with five progress logs left on the piece along the way.
Two faults that only a real CLI could show came out of that and are fixed here.
The approval-policy one is described above. The other is that continuations
were refused outright
: codex exec resume is a sub-subcommand with a smaller
option set than codex exec, taking neither -C nor --sandbox, so every retry
and every marker retry died with exit 2 and an argument-parser usage message. A
Codex host running an earlier build has never had a working retry. The flags now
precede resume, which is the order codex exec [OPTIONS] <COMMAND> documents.

Still unexercised: the rate-limit and context-overflow literals are source-derived
and no real run has reached either.

Claude Code hosts are unaffected by any of this beyond the harness: key.

Codex asks for its plan tool by name. codex-cli 0.153.4 does not offer
update_plan unless it is enabled, so every Codex command line now carries
-c tools.update_plan.enabled=true. Without it the child could log its progress
but never post a plan, and the runner card showed a run with no steps for its
whole duration. The prompt now also describes the tool the CLI actually has:
pending, in_progress and completed, exactly one step in progress at a
time, the whole list on every call.

Codex runs the test helpers directly, instead of a skill it cannot invoke.
A Codex run used to reach "UNIT TESTS", read $test-runner — codex exec does
load .agents/skills without being asked, so the skill really was there — and
stop. That skill is a state machine which drives itself through a sub-skill tool
Codex has not got, and its own rules forbid running the test command directly
because that would skip the machine-wide test lock, so the child was left with no
legal move. It refused, correctly, and every task_manual run on this harness
died at the same step. The prompt now names the lock-taking helper scripts the
installer already puts in ~/.claude/bin: test_start or ci_start to take the
lock and launch the run detached, then ci_wait polled for the exit code. Same
lock, one wrapper layer down — nothing about how runs are serialised on a shared
machine changes. Claude Code hosts keep invoking /test-runner and /ci-runner
and are unaffected.

A detached run now starts in a session of its own, and a fast one is no longer
called dead.
Two more defects, found by the first Codex run that actually
reached the helpers, both in the helpers themselves and both fixed for every
harness. test_start and ci_start used to detach with nohup and disown,
which survives the launching shell exiting but not its process group being
signalled — and a Codex child runs each command in a group of its own and
kills that group when the command returns, so the run died within seconds,
leaving no Exit code: footer and the lock held by a dead pid. Both scripts now
start the run in a new session: setsid where there is one, otherwise Ruby,
which this helper family already requires, and if neither is present they refuse
and say so rather than launching something that will be reaped. Separately,
ci_wait allowed two seconds between the command's process disappearing and the
footer arriving, where the real gap is about ten — the footer is written after
run_with_log has torn down its stall watchdog — so a sub-second command was
reported FAILED_EXTERNAL on a suite that then exited 0. That window is now 15
seconds, polled twice a second, and such a run is reported by its actual exit
code. The Codex vocabulary also spells the invocation as
test_start 600 cmd arg arg rather than test_start 600 <command>, and
test_start now refuses a whole command quoted into one argument by name
instead of guessing where to split it.

What to do. The same two-step upgrade the next section describes: these are
helper scripts in ~/.claude/bin rather than code in the binary, so
mcptask_runner update --self and then a bare mcptask_runner update in any one
project on the host.

bin/ci takes the test lock itself — reinstall the helpers

A bin/ci started by hand, or by a CLI child that found the script on disk,
used to run beside whoever was mid-suite; only the /ci-runner and
/test-runner skills took the machine-wide lock. The script now takes it
itself, and refuses out loud (exit 2, naming the holder) when somebody else has
it. The skills keep working through a marker: ci_start and test_start take
the lock first, as they always did, and export MCPTASK_TEST_LOCK_HELD so the
script knows the lock is its own.

What to do. The helpers live in ~/.claude/bin, not in the binary, so this
version needs the two-step upgrade: mcptask_runner update --self for the
binary, then a bare mcptask_runner update in any one project on the host,
which rewrites the helper scripts from the new binary. Until that second step
runs, a suite started through /ci-runner finds the lock held by the old
ci_start — which does not export the marker — and refuses itself as if
another agent held it. A hand-run bin/ci is fine either way.

Changelog

Features

  • c4eccf4f65a2cadec7e33fcff2896a27b63dec35 feat(bugreport): the bug piece names the harness and attaches the profile's config files (task #12300)
  • 9362d47e1beb2748c46af30e3c87d3f236d6dc86 feat(capture): capture mode records the child's raw stream for building new dialect fixtures (task #12287)
  • 037ee1d0bed0f907879ce6a9919586abeffaf28f feat(config): the version banner and the launcher log name the harness and its resolved binary (task #12301)
  • 48084db83a10dd77dfd9704861ab26d6f020940e feat(conformance): scenarios in normalized events, mock-cli --dialect with a renderer, chaos on the renderer (task #12286)
  • e804acbfb869f8c34e52a670166d04e7d640171a feat(conformance): the suite, mock-cli, chaos and the stress day run on the codex dialect (task #12291)
  • d23be25ec8018da875a9387ac27970667c2047d0 feat(harness): bundled codex.yml profile; command.order for subcommand CLIs; codex argv goldens (task #12288)
  • 044eea0e434dbc711436eeae289860aea6fb3e73 feat(harness): bundled opencode.yml profile; positional prompt with no token; readonly enforced via config (task #12295)
  • 81ad327cc9c069ee70d34aeb8b1f09f0e229147a feat(harness): codex failure literals from codex-rs 16ff14c, each cited by file and line (task #12293, part 1)
  • 20464a1d8ba009e00e04c6bc06b418bcd10d5197 feat(harness): codex prompt vocabulary: $test-runner/$ci-runner, MCP-tool piece fetch, update_plan block (task #12290)
  • 7fab6b61730ab89a47c14b363d3c7fba067df432 feat(harness): codex_jsonl decoder and renderer; resume by thread id from the captured session (task #12289)
  • ab5e95d01d01983505ecbcd435a7c22808483b89 feat(harness): every progress anchor in the spine spells the log tool through vocabulary.log_tool (task #12370)
  • 991f448a2e463139e69704d7e6d502a83c617c8d feat(harness): launcher.command is cross-checked against harness: at run time and derives the key at install time, never inferred at run time (task #12357)
  • 59bc636ee6aae849f258084538e03ffae4463b50 feat(harness): log lines name the harness display name; the engine delegates binary lookup to the profile (task #12285)
  • 7fcce96d85d09f100f68e1e1cc0b88af47b3047b feat(harness): opencode failure names from the OpenCode source, model tiers from the real CLI, real-run findings (task #12298)
  • 14a937f96d8b3b8dc1b9ad891ed0dd4ad4d98fdc feat(harness): opencode_jsonl decoder and renderer; result from marker and exit, never from step_finish (task #12296)
  • 438efa65eddc437eb5861090cbea78fc7a2689c8 feat(harness): profile schema, loader and the harness: config key with no default (task #12280)
  • 77962344c5bce58bdb178ae91d2958f45ae23a90 feat(harness): the claude_stream_json decoder emits normalized events; every consumer reads events and ToolKind (task #12282)
  • 8c883865a82d75827ac5ce69f437f10acf464419 feat(harness): the current-user fetch comes from vocabulary.current_user, not a literal resource line in the spine (task #12331)
  • 6af102c1f138dc30fc1cb5e44d01ace65c47262a feat(harness): the engine builds the child command from the claude profile (task #12281)
  • 6a989e2dd9db0c6b02d4808d53a76f8e50d56c5f feat(harness): the prompt spine reads its harness fragments from the profile vocabulary (task #12283)
  • 9c94208a607e941e7db261149cda8d11e2f7a19b feat(install): codex install section: .codex/config.toml MCP server, project trust, .agents/skills, AGENTS.md pointer, login preflight (task #12292)
  • 3182be07fffc1e83a7ddd102d4ab2900c7f3bd1b feat(install): opencode install section: opencode.json remote MCP writer, readonly overlay via OPENCODE_CONFIG_CONTENT, real vocabulary (task #12297)
  • 29452358747c03f1348feb98265499694706ce1a feat(install): the helper home is the profile's install.helpers_dir, rendered into skills and helpers at install time (task #12303)
  • 81ec85ca672e6e679e57e7b906ae27d7d30ddc9c feat(install): the installer reads its layout from the harness profile; init --cli, loud update migration, binary preflight (task #12284)
  • 35bb8f0110288dd68d07eee79c8bd36509086cb1 feat(snapshot): the additive harness member on the wire, in the run log and in the handoff note (task #12299) ### Fixes
  • 7d4bffd66f8eb1fe6b5d1efdaa9737e3a126dba7 fix(banner): the Models line names the profile whose ids it prints (task #12381)
  • 55df871aae8eff9c3bd5cdfbdfef45420125fd09 fix(ci): bin/ci takes the machine-wide test lock itself when not started through ci_start, and refuses when it is held (task #12369)
  • 298dc2022dcebf501c96f5a9d1b2fe003820eed1 fix(codex): ask for the plan tool, and describe the one this CLI has (task #12383)
  • b0f4dfa8113e57847d2f58d6fddccd4f0107a75c fix(codex): real runs on the ChatGPT plan — read-only class keeps its MCP server, continuations parse, refusals read from the wire (task #12293)
  • 7e42be2c3800bd4216fe7ac33d64d8912f9943b9 fix(codex): the prompt drives the lock's helper scripts, not a skill this CLI cannot invoke (task #12395)
  • 26a8adfc848505219155fcb529598dcdd78756dd fix(eventstream): a failed dial no longer prints the token it dialled with (task #12379)
  • 1b3a269360341a021ef2b557c95865e54bc96ce5 fix(executor): a run that answered with the marker is labelled result on every dialect, not stream_ended (task #12368)
  • 5815b2545a0afa62b046aef520afb23e56a48f56 fix(executor): the stderr label names the CLI that wrote the line (task #12380)
  • fc4178d720ed8b9483b063995268457491235523 fix(harness): codex exec takes --dangerously-bypass-approvals-and-sandbox or --sandbox read-only, never -a (task #12332)
  • f39750da54afbfb2935f773947d08a69c61a6780 fix(harness): opencode progress anchors name the callable log tool on every line (task #12367)
  • cb5a352cfb9f3ec3096e1baef06e1a90435b4071 fix(harness): the opencode readonly class keeps the shell and refuses writes by pattern (task #12353)
  • 77767eef92910fa8981498d2c5f13151ff21c496 fix(helpers): a detached run gets a session of its own, and a fast one is no longer called dead (tasks #12399, #12397)
  • 7c1d5abae8159d505e245705432c849dd68160ce fix(init): a scripted install is asked of the OS, not of the file mode (task #12382)
  • 5f4360b7d9c46d069093365af33c7be1895c558d fix(opencode): the plan comment stops claiming update_plan has no in_progress (task #12391)
  • 068f188f5dc5ff2adc3fa7bf0e5645dd9fd7390e fix(smoke): the banner checks ask a directory with no config (task #12384)
  • 381260a399407a1a859cf691eed5c8e0181d723b fix(tests): the init refusal test expects the host path, not the git spelling (story #12276) ### Other
  • d34e6c905f24482cf5c5f36c0e5184947023b4cc docs(ci): the codex conformance job comment counts its exclusions correctly (task #12294)
  • c3d811c3b2b7fe14b7c44f33dc9fa2aa5bcfbe45 docs(codex): the plan comment stops asking for a correction opencode.yml already carries (task #12391)
  • b679dd3947a85012cbc7064ab38528f6f62d9a74 docs(harness): README harness section, Codex host specifics, requirements, npm and CLI texts, release notes draft (task #12294)
  • c0583d6f795df1c4f39bc43b8815d490d86aa5ce docs(harness): the opencode skills comment reflects the self-locking local gate from task #12369 (story #12278)
  • 39ae784fb4cc661975f43cebceee59036c3f3c06 docs(release): the plan-tool flag, and the two-step upgrade the self-locking gate needs (story #12277)
  • 8ce7005b0b01d1df78928c5750d8cacf4d8c2e77 docs(release): where the harness shows up: card, version banner, launcher log, bug piece (story #12279)
  • 6dfba41f87808b2d5ec372b487b28cb74739676f merge: story #12276 — harness profile layer: Claude Code behind a data profile, no behaviour change
  • 0aa6545ba0faca27e80c14ccde4042d37f3b50fd merge: story #12277 follow-ups — token-free dial errors, per-harness stderr label, profile-true banner, scripted init, codex plan tool, smoke in a clean dir (tasks #12379-#12384)
  • b058a7d06faf042aaaed16c8d1d2d13ff52ef396 merge: story #12277 round 3 — plan-state comments agree, first real codex plan captured, release notes for the plan flag and the helper upgrade (tasks #12391, #12392)
  • bf250676dd324a0c6698be4bc00f10f0138a413b merge: story #12277 round 4 — codex drives the lock helpers, helpers survive their launcher, ci_wait waits for the footer (tasks #12395, #12399, #12397)
  • d5d8a86187669a6b0a2ab505b15be2173eae1c0b merge: story #12277 — Codex CLI harness (profile, decoder, vocabulary, install, conformance, docs; real-CLI runs pending login)
  • e2ee3141f3f18e6e9400388f27df42a934ee1c80 merge: story #12278 — OpenCode harness (profile, decoder, install, readonly by pattern, real runs verified; self-locking local gate)
  • 59e7ebd7a4066966e9425816201ff6add0225dae merge: story #12279 — harness visibility (snapshot member, bug piece, version banner, helpers_dir, launcher.command cross-check, log_tool vocabulary)
  • 650a002d65c1d9d3dbcc9fa223ef8ffd2bf01ad4 merge: task #12293 part 2 — codex driven for real (read-only MCP approval, resume argv, wire-shaped refusals)
  • 333b34da96f1ef8662e13bae51db95b91cfc0ced test(codex): the first real plan of a runner run, from the capture (task #12392)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.23

Upgrading

The usual one command replaces the binary:

mcptask_runner update --self

The bundled skills-and-helpers pack did not change in this release, so a
follow-up bare update is not required. Two behaviour changes worth knowing
before an unattended host picks this up:

  • --ignore-quota now means ignore, everywhere. The daily mode's day-level scheduler no longer queries mcptask.online about the budget when the flag is set, so a REST outage cannot park an unattended daily host until the next business day. The end-of-workday clock still applies — it is a time rule, not a quota rule (#11891).
  • The work window keeps its minutes. init --until 18:30 stores the new additive work_window.end_of_workday_minute key and the loop stops picking up new work at 18:30, not 18:00. Configs without the key mean :00, so existing hosts change nothing; a value that cannot be stored is refused loudly, never rounded (#11892, #11896).

And one to expect on your next bare update: locally modified helper
scripts
now get the same five-outcome manifest protection as skills — a
hand-edited helper reports conflict-skipped instead of being silently
overwritten, and FORCE=1 leaves a .bak beside anything it replaces
(#11894). Also in this release: the streamable-HTTP .mcp.json entry for
fresh installs (#11873, #11875), the token reaching interactive terminals
(#11874), and the ruby conformance baseline moving to nightly-only CI
(#11893).

Changelog

Features

  • 335d101837b7738278e105c3c46d93ca41802bcc feat(config): the work window keeps its minutes (task #11896)
  • 937d21249d4b1f6af9f16998672ddd731275d19a feat(update): carry a legacy SSE mcptask-online entry forward (task #11875) ### Fixes
  • e3ac5976b98e2c189534e3174803fea81935fc88 fix(install): --until refuses minutes it cannot store (task #11892)
  • 525daab5394e4d244bb5f52434a9195a24eec7fa fix(install): a fresh .mcp.json gets the streamable-HTTP entry (task #11873)
  • a8277924b6ea1dcdb274d9ec4cce211443650067 fix(install): helpers get the same five-outcome protection as skills (task #11894)
  • 22525d047a05382f6842127ab1d5953b6f99a958 fix(install): the token reaches a terminal, not only the scheduled job (task #11874)
  • 232399064826689e4dded85488bb5eed1b90ef80 fix(runner): --ignore-quota covers the daily scheduler too (task #11891)
  • 4c870dcc01c07fdf47f3eea5445e3ca817c434d7 fix(tests): the lock-guard test resets its clock before every subtest (task #11897)
  • 9e7abcc1af46b18293a54eb9fb5d2ebf3cbc2ce5 fix(tests): the shell-file table joins its paths instead of spelling them (task #11880) ### Other
  • aadfcf8d051948d4d9db6a04af39a1e4bcd96cb4 ci: the ruby baseline runs nightly only, and the docs stop contradicting it (task #11893)
  • be020fa81612407e1cfddbdfdb03054d7e1b94f0 docs(comments): the outage window is named by its constants, and childEnv stops teaching the pre-#11670 model story (task #11895)
  • 495223cb63bf2f8e1bee3ddbd3079163a51cc6bd merge: runner-audit fixes — tasks #11891-#11896

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.22

Upgrading takes two commands this time, not one

mcptask_runner update --self     # replaces the binary
mcptask_runner update            # in each host project

The first is the usual one and covers every loop change below. It is not
enough for the skills and helpers: those are a data pack the binary carries, and
only the second command writes them into a project.

Skipping it leaves the old /test-runner and /ci-runner in place — and on a
project that is not Rails those name commands it cannot run, which is the very
thing this version fixes. A host that has locally edited a skill keeps its edit;
FORCE=1 takes the new one and leaves a .bak beside it.

Worth knowing why this is easy to get wrong: the data pack lives inside the
binary, so an update run through the old binary reinstalls the old skills.
The order above is the whole trick.

One runner, every framework

The bundled CI and test skills stop naming a framework. /test-runner and
/ci-runner used to spell out bin/rails test, test:system and RuboCop, and
check_test_lock recognised a running suite by six regexes, five of which were
Ruby. On a Django, Node or Swift host the commands did not run, and the guard
against a second concurrent suite waved every real test command through — blind
on exactly the projects a universal runner exists for.

Both now read what the project declares in .claude/test-commands.json, which
mcptask_runner init writes and update backfills. With no such file the
toolchain is detected from go.mod, Gemfile, package.json, manage.py,
pyproject.toml or Package.swift — and when nothing is recognised the runner
says so rather than inventing a command that will fail later and elsewhere.
(#11853)

Two more places the prompt spoke Rails to everyone. The auto-squash workflow
told every project to run bin/rails assets:precompile RAILS_ENV=test between
its unit and system suites, and the manual screenshot step named a Rails class.
Neither is measured by what it breaks — the first costs a turn or invites a
plausible substitute, the second is silently ignored on a project that has no
such class — but both contradict the claim the product makes.
(#11858,
#11864)

A test now guards it: every executor prompt, both configs, is checked against
two lists — commands only one ecosystem can run, and identifiers that exist in
only one.

The working day

A failed task waits an hour, not the rest of the day. A task that fails is
set aside and the runner carries on with the next one.
(#11846)

The dashboard can take a piece off the skip list. A piece set aside earlier
can be released from the card, and the runner picks it up again without a
restart. (#11847)

The dashboard connection

A closed socket is described by whoever actually saw it close. Two paths
reported a dropped connection — the read loop, which knows the close code the
server sent, and a failed write, which knows only that the socket was gone.
Whichever finished first wrote the notice, so a deliberate close with a code
could be reported as a bare transport error.

The reader's account now wins. That is what makes "the server closed it, code
1001" worth trusting when you are deciding whether the server needs looking at,
and it is the difference between a server letting a connection go and a
connection dying underneath both ends.
(#11860)

Under the hood

The loop's test logger is safe to write from goroutines — a data race the race
detector caught on CI while forty local runs stayed green
(#11859) — and a stress day that
overruns its wall clock no longer leaves a child writing into a temporary
directory that has already been removed
(#11865). Neither changes runner
behaviour.


Verified before tagging: the full local bin/ci green on all ten steps with no
skips, including the stress day and both conformance suites, and GitHub CI green
across three operating systems and the Go floor from go.mod.

v0.3.21

The one that was costing whole days

A deploy of mcptask.online now costs one attempt instead of the working day (task #11832).

While the site is being deployed its MCP server is unreachable for minutes and then comes back on its own. The runner spent its entire recovery budget inside about forty seconds — a child dies in ten, five seconds between restarts, two restarts — so all three attempts lost the same race before the server could possibly be back, and the run ended with error. That status is what ends the day: one deploy could stop a day that had already finished eighteen tasks.

Restarting faster cannot fix a wait. The two situations that reach that path are now told apart where they are detected, rather than by reading the message afterwards:

  • A deferred tool that never loaded is the child's own miss. It keeps its two fast restarts and still ends in an error, because it is not going to fix itself.
  • An outage gets six restarts at twelve times the wait — about six minutes, which spans a deploy — and when that runs out it ends the way a stall does: a verdict the loop carries on from, the task left in_progress for the next triage, and no bug piece, because a deploy is not a defect anybody can fix. The wait keeps the heartbeat going, so a card watched through a deploy says the runner is waiting rather than falling silent.

This was the largest cluster in the Errors epic — five of twelve real failures, across three machines and two host projects.

The one you will see

Today's skip list is visible (task #11835). A task the runner has set aside — out of scope, failed, already taken by somebody else, a merge it cannot finish — is skipped by every later triage that day, and until now the only trace was one log line at the moment it was decided. It now shows on the startup banner, in every wait, and on the dashboard card. A quiet runner can be read rather than guessed at.

Also

main is unprotected on purpose, and the two habits that stand in for a branch rule are now written down (task #11831); a new push into a pull request stops the CI run it supersedes (task #11826).

Upgrading

Run mcptask_runner update --self on each host, or move a project's gem pin to 0.3.21 and run rake mcptask_runner:update. The binary is per machine and the newest one any project offers is the one that stays, so one project is enough.

Until a host actually runs this binary, a deploy of mcptask.online goes on costing it the day.

v0.3.20

Upgrading: run mcptask_runner update --self on each host, and do it for
this one rather than at leisure. The fix below can only reach a runner that is
running the new binary, and until it does, a task moved between two agents keeps
being worked by both. A daily process takes the new copy at its night swap — but
only once that copy is on disk, so the update still has to happen. Nothing to
migrate; no configuration changes.

What changed

A piece assigned to somebody else while this runner is working it now stops
the child.
The dashboard socket has always carried both halves of an
assignment — "given to you" cut an idle wait short, "given to somebody else"
reached nothing — so a task moved between two agents was picked up by its new
owner while its old one worked on to the end. Two agents on one piece, the same
branch name pushed twice, two sets of efforts logged. The runner now abandons
the piece, says so in the log, and goes back to the queue for one that is still
its own. It is not a reason to stop the day, and the piece is deliberately not
set aside: the queue has already stopped offering it, and it stays workable if
it is handed back. Neither quota ending loses its priority — a run killed by a
crossed budget and a reassignment in the same breath still stops the day, since
that is the claim about the whole day and this is a claim about one piece.

The run log is coloured as it is read, and the file itself stays plain. The
two lines that matter in a wall of uniform text — the ones Warn and Error
already mark with a glyph — are painted red and yellow, a child's stderr is
yellow, and the [Component] tags, cost lines and phase separators are dimmed
so the shape of a run is visible in a scroll. Only what the runner itself marked
gets coloured; guessing a severity from the wording would be wrong on the day it
mattered. Nothing is written to the file, which is what bug reports attach and
what people grep. runner-log --paint is the same filter over stdin, so
tail -f any.log | runner-log --paint works for a log read some other way.

The stress harness gained a day that proves the first of these end to end: two
otherwise identical days differ only in whether the broadcast names the piece in
flight, and they come out opposite — one abandons, the other leaves the child
alone. That second half is the one worth having, because killing healthy work
over a stranger's assignment would be worse than the bug this fixes.


Changelog

Features

  • 1fb910ebee499b6f89efc1935806a84ad4c7ce14 feat(stress): a day proves the runner lets go of a piece taken from it, and keeps working (task #11790) ### Fixes
  • 82c2ddddd93abee15fe8c3ed560f436c110128a3 fix(eventstream): a piece given to somebody else stops the runner that was working it (task #11788) ### Other
  • e3de44be2da659b116dcb8d824769cb78211a13a feat(runner-log): the run log is coloured as it is read, and the file stays plain (task #11786)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.19

The one you will notice

Every step that does work says so on the piece before it moves on (task #11784). A run on 2026-08-25 opened its pull request having called LogWorkProgressTool zero times — while its plan moved on the dashboard card the whole time. The card said "working", the piece said nothing, and the hours landed nowhere.

Task #11616 had already established the shape of the fix: the cadence has to be written into a numbered step, because a block sitting past the last step never gets read. It put three anchors on the auto-squash spine — and left the seven steps between CREATE BRANCH and the CI gate saying nothing about logging, while the three manual workflows got no anchor at all.

Now every substantive step carries its own LOG PROGRESS NOW line, and each one names the TaskUpdate that closes the same step's todo item:

4. IMPLEMENT TASK (incremental commits, clear messages)
   - LOG PROGRESS NOW — TaskUpdate this step's item "completed", then
     LogWorkProgressTool at ~45%: implementation written, tests not run yet

That pairing is the whole trick. The child was calling TaskUpdate reliably all along — that is why the card moved — so hanging the log on the call it already makes is what ties the effort trail to the plan. Auto-squash now walks 20 / 45 / 60 / 70 / 75 / 80 and reaches 100% only after gh pr view says MERGED; the manual workflows top out at 90%, because the PR is left for a human; a review run logs at 25 / 70 / 100.

It binds the model rather than forcing it — the runner posts no effort of its own, and has no way to speak to a child mid-run. What changed is that skipping the log is now skipping a step.

The one that was quietly stopping the 08:00 job

The child searches the project, not the whole disk (task #11782). A child that cannot place a file falls back to find / or find ~ — two days of one project's logs hold five such calls, one of them find /Users/<you> -maxdepth 3.

On macOS that walk enters ~/Documents and ~/Desktop, which are gated behind TCC, so the OS raises a permission dialog. The dialog names mcptask_runner — macOS asks on behalf of the responsible process, the launchd-spawned root of the tree, not the find underneath it — which is why the binary gets blamed for folders it never opens. And the job fires at 08:02 with nobody at the keyboard: the dialog blocks the call until it times out, and then denies it.

The prompt now bounds the search to the project directory, and — the part that makes a prohibition stick — names where to look instead: bundle show <gem> / gem which <file> for Ruby, go env GOMODCACHE for Go, then search under the path it prints.

Upgrading

Move your project's gem pin to 0.3.19 and run rake mcptask_runner:update. The binary is per machine and the newest one any project offers is the one that stays, so one project is enough to update the host.

Both changes are prompt text sent to the child, so they take effect on the next run the updated binary starts. Nothing to migrate, nothing to re-install beyond the binary.

v0.3.18

The one you will notice

The install and update output is coloured (task #11779). The update summary was a wall of grey in which the one row that needed attention read exactly like the thirty that did not. Now: green for up-to-date and added, yellow for updated and force-updated, red for conflict-skipped, dimmed section tags, warnings in red on stderr.

It is decided per stream and only when the stream is really a terminal — a pipe, a redirect and a launchd log all get exactly the bytes they got before. MCPTASK_RUNNER_COLOR (1/true/always/force, or 0/false/never) overrides, and NO_COLOR is honoured. Your run logs stay greppable.

The one that was quietly costing you processes

A child's process group is remembered, so what the child left behind is still reachable (task #11773).

A process group outlives its leader: while any member is alive the group id stays allocated and a signal to -group still reaches them. But the kernel can no longer name that group once the leader has been reaped — and killTree looked it up at kill time, got nothing, and fell through to signalling a bare pid that no longer resolved.

So anything a child started and then exited on went on running. Every claude session that launches a dev server, backgrounds a command, or leaves a watcher behind and then finishes its turn is exactly that shape. Nothing raises, so nothing ever reported it — the processes just accumulate on an unattended machine.

This had shipped in every version of the runner there has ever been. It is fixed by reading the group when the child starts, while it is certainly alive, instead of asking about it when it is already gone.

How it was found, which is the part worth repeating

Not by the test suite. bin/ci runs the chaos stress harness against one fixed seed, and the invariant that catches this — the orphan sweep — has existed since the harness was built. They never met, because the fixed seed draws a different misbehaviour at the moment the signal lands.

It took eight random seeds. Two failed on the current code, and a third failed all the way back at v0.3.16. Scheduling that sweep is now task #11778.

Also in here

The stress harness grew to cover the dashboard-card behaviour that landed after it was built (story #11765, seven tasks) — none of which ships in this binary, but it is what turned up both of the above.

Upgrading

Move your project's gem pin to 0.3.18 and run rake mcptask_runner:update. The binary is per machine and the newest one any project offers is the one that stays, so one project is enough to update the host.

v0.3.17

What this is

One story: the chaos stress harness grown to cover the behaviours that landed after it was built (story #11765, seven tasks).

For an operator, nothing changes. No new behaviour, no changed wording, no new configuration. The entire shipping delta against v0.3.16 is 29 lines, and the only one that touches a code path is a refactor that leaves production behaviour identical.

The one real fix

Stream.SetOnAssignment (new), wired unconditionally by the work loop.

The assignment wake-up added in v0.3.16 was wired inside the branch that builds a stream when the caller supplied none. Production always takes that branch, so the feature worked — but every caller that supplies its own Stream got one with no way to fill the wake channel, which meant no test could ever see it fire. The harness proved it: 299 assignments delivered to the runner's own user, not one wait cut short. The wiring now happens on whatever stream the loop ends up with.

If you are on v0.3.16 this changes nothing you can observe. It is here so the next change to that path cannot break it silently.

Everything else is the harness

internal/stress and internal/chaos do not ship in this binary. What grew there:

  • the stub's dashboard socket pushes as well as records, and can end a connection either with a close frame or with none at all
  • a stop names which of the three ended the day, and a reconnect names who closed the socket
  • the card's message must stand, a clean run must say how it went, and a retry must say what it is retrying for
  • an assignment wakes the short waits and must not touch the overnight sleep or the daily restart's anchor
  • a forked task keeps the name that buys it the watchdog's generous ceiling, while a tool that never closes is still killed
  • a plan reaches the card, and every child is proved to have been launched with the tools that make one

The suite now costs about four minutes rather than ninety seconds; bin/ci says so.

Upgrading

Nothing to do. The gem ships at the same version as always — move a project's pin to 0.3.17 and run rake mcptask_runner:update when convenient, or wait for the next release that actually changes something.

v0.3.16

Upgrading

Run mcptask_runner update --self on each host. Everything here is binary
behaviour — no new skills or helpers ship with this version — so plain
mcptask_runner update has nothing to do, and neither does bundle update:
the binary the 08:00 job runs lives in ~/.mcptask/bin and only --self
replaces it.

The wrapper gem mcptask-rails-runner is published at the same version, on all
six platforms.

What this release is about

The runner card on the dashboard is filled in rather than sparse. It names
the binary drawing it, says how a finished run went, counts out the retries the
CLI is riding out, links a pull request the run has just opened, and says what
an MCP tool call is acting on instead of showing a bare tool name. A task forked
inside a subagent reaches the card too, and the notification that ends it is no
longer thrown away. A card whose stream goes quiet keeps saying the last thing
it knew instead of emptying out, and the TODO list fills in on Opus and Sonnet
as well.

An idle wait ends the moment mcptask.online says this runner has been given a
piece
, rather than sitting out the rest of the poll interval.

A stop on the daily quota says which quota, and how many hours it means —
worked_today=8.2h of per_day=8h. Those hours are the user's day on
mcptask.online, not the run's: another session spends the same budget, so a
runner that idled all morning could end its day on hours it never worked, and
the old one-line message gave a reader no way to tell that from a bug. The same
line now separates a spent budget from an endpoint that never answered, and a
stop caused by a failed task no longer claims to be a quota stop.


Changelog

Features

  • e921a308b8fbcf2a25170d045efa21a28661bc59 feat(executor): a finished run tells the card how it went (task #11758)
  • ee0af55aaf5b9c2413245d5f9e5e13d8f53b6869 feat(executor): the card counts out the retries the CLI is riding out (task #11754)
  • 7ab052bb17845a0b24b2f353a6b96f19119f72f4 feat(executor): the pull request a run just opened shows up on its card (task #11753)
  • cfa61d63b0f4d26311cbf1253a5ad4d5bb4dc8e1 feat(runner): an idle wait ends when mcptask.online says this runner was given a piece (task #11741)
  • 55872bda6abec508541898b59a2ccafbb6f152b9 feat(snapshot): the runner card names the binary that is drawing it (task #11747) ### Fixes
  • 82ebb34127201c463e683996d27d755e999b331f fix(eventstream): the reconnect notice names what closed the socket
  • 94c3df906f741e11924f1f9a81238964d1d763e9 fix(executor): a task forked inside a subagent reaches the card, and the notification that ends it is not thrown away (task #11751)
  • 29978c739ec623b14188fc6708e5447ba3120881 fix(executor): an MCP tool call says what it is acting on, instead of arriving as a bare name (task #11752)
  • 1f8c1cf4cd755524d7ff565cda919344dd37bc5b fix(executor): the dashboard TODO card fills in on Opus and Sonnet too (task #11755)
  • cae366f659a7abd6287c0337c1aa387f566a8762 fix(runner): a daily-quota stop names the quota and the hours behind it (#5)
  • 87cbd6820e787192ab590e5d04f44648dafbca42 fix(snapshot): the card keeps saying the last thing it knew (task #11757) ### Other
  • 3a73198713dd540b1fefaf46dec7ec1f3c9b7eb8 docs(ci): a piped bin/ci reports tail's exit code, not the suite's
  • a2555366c751739e2513be0580c793e79c930d30 docs(snapshot): the two session views, and why neither is a superset (task #11759)
  • 3a1056cee599be8b20ba258926e78a8814618f03 test(executor): the branches the two card stories left uncovered (tasks #11750, #11756)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.15

What this release is for

Two things an unattended host feels directly, and one the dashboard does.

A 429 rate limit is recognised. The CLI retries a spent usage window ten
times internally and then stops mid-answer with no result marker. The runner had
no branch for that, so it called the ending a missing marker, spent its three
thirty-second retries against a window that had not reset, failed the task, filed
a bug piece about the marker — and, because the quota Decider stops the loop on
any error, ended the day's remaining work. The window that prompted this came
back about a minute after the last retry. A 429 now has its own flag, its own
budget of eight, and a back-off measured in minutes (5 → 10 → 20 → 30, capped),
classified ahead of the missing-marker path because a 429 always also looks like
one. A spent usage window is no longer filed as a bug: nobody can fix one.

A daily runner adopts a new binary by itself. Everything that notices a new
version — the bundle adopt, the update hint — runs once, at startup, and a
daily process never ends. It kept whichever binary it started with, however
many releases went by, on exactly the host nobody is watching. On its way into
the overnight sleep it now compares its own executable with what is installed and,
if they differ, retires the card, releases the instance lock and replaces itself
— at the configured end of the workday, or at midnight on a host with no window.

A failed task now shows as failed on the card. A run is marked finished the
moment its stream ends, before the ending is classified, and finished → error
was not a legal transition — so a failed task filed a bug piece while the
dashboard went from finished straight back to triage. Anyone watching saw a
healthy runner through every failure of the day.

Upgrading

Nothing to do beyond the usual install. One exception, and it is the reason to
bother: a daily host will not pick this up by itself. The self-restart
above only exists from this version on, so the process now running has to be
stopped once by hand — after that it keeps itself current.

launchctl bootout gui/$(id -u)/online.mcptask.runner-<slug>
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/online.mcptask.runner-<slug>.plist

today hosts need nothing: the next morning's job starts the current binary.
Check which one a machine is running with ~/.mcptask/bin/mcptask_runner version.

Changelog

Features

  • be9e6ef541de78e0cb923fbc32f4c4de13791f37 feat(chaos): a CLI stand-in that starts well, decays through five phases, and records what it did to the runner (task #11715)
  • 9b8b4cc4a50ceca2cf32614e40e554b8a7f11383 feat(chaos): a stub mcptask.online that freezes, lies, drops the dashboard socket, and keeps an honest ledger (task #11716)
  • 184cc296585c53afc787ed3bdb89769a1843ca5f feat(executor): a 429 rate limit is waited out on its own budget instead of misread as a missing marker (task #11731)
  • c5e50fa889774937a76d2fe8a70a2f9253cf977a feat(runner): a daily runner replaces itself with the installed binary at the day's end (task #11729)
  • dcef1a9ef3d1421d5221b85111a76fc927b9af60 feat(stress): a real signal to a real binary, and everything it has to take with it (task #11719)
  • e0eb4f012390d344327db1f970d12b0722212ea4 feat(stress): an in-process driver that compresses a workday into ninety seconds and states how the loop may end (task #11717)
  • e38e3638755ce63536aa8bdcbd3fc5c00a2e57be feat(stress): one fixed-seed day in bin/ci, bin/stress for the rest, and the harness written down (task #11720)
  • 36a22107e88c62e2bf5f3613025a18c08a374550 feat(stress): the card has to keep telling the truth while everything burns (task #11718) ### Fixes
  • f799bfe05a5d6490c2cdf691fc58ff499044df93 fix(eventstream): a first subscription confirmation has nothing to resend, so a fresh session stops duplicating its opening frame (task #11725)
  • ea6fc1839a472f7bbaeb4b7e3507d92c9652215a fix(executor): a marker whose JSON does not parse is not the child's answer — keep looking, and take the retry (task #11724)
  • 74dc7ad64df2f477e6d8306632d25327bbf98add fix(executor): a server that has not finished connecting is recognised as the MCP route failing, not left to become an empty bug report (task #11712)
  • 693d609f24dff2143e40924c879ed26907bf2e11 fix(executor): the card says what it is retrying for, because the runner already knew (task #11732)
  • c8a70925de6f362b0fb156740529ba395cb5faf9 fix(loop): a day that ended on the clock sleeps until the next one instead of spinning until midnight (task #11726)
  • c9644cf59a609d39643aac69134fb839b88a874a fix(runner): a failed task shows as failed on the card, and the check that says so cannot be fooled (task #11734)
  • 8678677b6c093f7e312956b35d762983bb8c95d9 fix(snapshot): the dashboard TODO card follows TaskCreate/TaskUpdate, the plan tools that replaced TodoWrite (task #11710) ### Other
  • 2658215af771f52833587916fc08b23defc13792 docs(config): every wording of work_window says which mode exits and which sleeps (task #11728)
  • bfc76427946075e8fffac21a29db48c7fe01dbd1 merge main into story-11714 before the story merge

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.14

Upgrading

Run mcptask_runner update --self on each host. This release changes loop
behaviour inside the binary, and nothing replaces the binary for you: the copy
the scheduled job runs lives in ~/.mcptask/bin, and neither bundle update
nor a gem bump touches it. mcptask_runner version says what a host actually
has.

No new skills or helpers ship here, so plain mcptask_runner update has
nothing to do in this one.

What changed

An empty queue is asked about every half hour, not every five minutes.
The REST next-task check added in v0.3.13 made an idle round cheap, and cheap
rounds ran twelve times an hour: two GETs each, and two rows in the dashboard's
activity feed each, all saying nothing had happened.

waiting_strategy.short_wait_minutes still governs the first rounds — it is
the right answer in the minutes just after a task finishes, when work is
expected any moment. What is new is that a run of empty rounds counts as
evidence: once those short waits have added up to one long_wait_minutes, the
long wait takes over and keeps it until there is work again. Nothing waits
longer than long_wait_minutes, the ceiling daily mode always had, and the
switch is announced in the log in both directions.

On the installer's 5 and 30 that is 21 idle rounds across an eight-hour
afternoon instead of 96. A configuration whose long wait is no longer than its
short one has nothing to back off to, and is left alone.

Two smaller log fixes in the same path. The quota check made after an empty
round used to end the day on a bare break with no line at any level; it now
says why the runner stopped. And daily mode no longer claims "will wait 1 hour
before retry" while waiting long_wait_minutes.

Changelog

Features

  • adad985d17350cb40bd716dbe08d02fd92b13816 feat(loop): a queue that has been empty for half an hour is asked about every half hour, not every five minutes (task #11699) ### Fixes
  • a65a5fda79fdaf748efb8a6204ef7393f553fb21 fix(loop): the backoff line names its waits the way the waiting strategy does (task #11699)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.13

Upgrading: mcptask_runner update --self (or bundle update mcptask-rails-runner to 0.3.13) upgrades the binary; then run mcptask_runner update in each project — this release ships a new helper (runner-log) and rewritten config sections, and nothing installs those for you. The scheduled job runs the per-machine binary in ~/.mcptask/bin, so check mcptask_runner version there afterwards.

What changes in behaviour:

  • Before paying for a triage session the loop asks GET /api/:account/pieces/next; an empty queue answers no_more_tasks with no model involved. Until mcptask.online ships that endpoint (task #11691) it answers 404 and the log shows next-task REST check failed (HTTP 404 …); falling through to triage every cycle — expected, triage behaves exactly as before.
  • The configured end of workday is the one hard stop, checked after a task finishes. There is no default any more: a config whose work_window.end_of_workday_hour is unset or null has no end of day (the 18:00 default is gone; the quota and the day gate still apply), and a running task is never interrupted by it.
  • The skip list is persisted, so a restart does not re-pick what today already declined; failure, task_already_started, merge_failed, merge_unverified and out_of_scope set a task aside for the day instead of stopping the run.
  • respect_working_hours is read from the user profile once at startup — a change to the checkbox is heard at the next start.

Changelog

Features

  • a1798c3cb6bc2f707d31e01c4d5d5e5f4d89aef0 feat(bugreport): a guard of the runner's own that did not hold files a piece instead of a log line (task #11684)
  • a14790c3995e036d6368c7b5742768246f617fcc feat(install): ship runner-log, the helper an operator types to tail the current run
  • 3fb7637cc491069964281b2f729ecf3c2f949491 feat(install): the install ends with a summary of every config section the runner reads, and the sections it writes carry a comment (task #11690)
  • 8f78435eb604330ea5267a1cd1085c521da4ff08 feat(loop): ask the REST next-task endpoint before triage — an empty queue is no_more_tasks without a model (task #11692) ### Fixes
  • dde40a14bf9a2fefe495970f3accf73a5e5dc9ba fix(loop): a task declined as out of scope goes on today's skip list, and the loop never stops over it
  • dd3a529977087feb39b27a0626c0e6dc63c35596 fix(loop): failure, task_already_started, merge_failed and merge_unverified set the task aside for the day instead of stopping (task #11680)
  • f727a15afec1b66ff369fc56daaa397f763d9040 fix(loop): the configured end of workday is the one hard stop, checked after a task finishes — and there is no default any more (task #11689)
  • 0b18385f30d5a1f429a68be46714ce8763350b6d fix(loop): the skip list outlives the process, so a restart does not re-pick what today already declined (task #11683)
  • 32c00200b5849084d91bb1e0beaa2249fe4293bd fix(quota): read respect_working_hours from the user profile once at startup, not from time_status (task #11686)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.12

This release is mostly about a guard that had stopped guarding, and a setting that could not be right for everyone reading it.

The lock that let tests through. check_test_lock refuses a direct bin/ci while another agent's suite is running. It looked for pidfiles in a flat directory nothing has written in a long time, so every lock older than ten seconds read as stale and the command went through — the guard worked for the first ten seconds of a lock's life and never again. The path is now rebuilt from the lock's own project. Two smaller failures in the same lock went with it: the directory that serialises the moment of acquiring could not go stale, so an acquire killed midway wedged every later run behind a lock reported as unknown; and a lockfile missing its PID= line killed acquire outright before the staleness check could reap it, leaving nothing but a blank error to act on. (#11669, #11671, #11672)

Bundled skills no longer declare a model:, and the install-time rewrite that resolved it is gone.

A model name written into .claude/skills/ can only be right for one backend, and that directory is read by two: the runner's child process and whoever opens the same project in a session of their own. Whichever way the name was written, it was wrong for one of them — and wrong silently, because the CLI returns its model error as the skill's own result and the agent above reads that as the answer. Each fork now runs on its session's own model. context: fork is untouched, and that is what actually keeps a fork's output out of the parent's context. (#11670)

Upgrading

Run mcptask_runner update in each project after upgrading the binary. Nothing does it for you — upgrading the binary does not refresh the skills and helpers already on disk, so without this step every fix above stays installed nowhere. Helpers are replaced in ~/.claude/bin; skills are refreshed per project. Do it in every project you use, not just one. (Making the upgrade reconcile them by itself is tracked as #11673.)

No --force is needed. Hosts whose skills carry a rewritten model name are replaced normally by mcptask_runner update, because the installer recorded the manifest hash from the same content it wrote — so the rewritten form is the baseline, and the updater reads those files as untouched. Verified against three hosts carrying rewritten copies (gemma4:31b-cloud, minimax-m3:cloud and haiku): all eight bundled skills hash equal to their manifest entry on each. A skill somebody edited by hand is still reported as a conflict and skipped, exactly as before.

One known rough edge, not fixed here: now that the lock guard blocks correctly, it also blocks commands that merely mention bin/ci — grepping a CI log, for instance — because the pattern matches the substring rather than the command position. If a refusal looks wrong, check ~/.claude/bin/test_lock status to see whether a run is genuinely in progress. Tracked as #11674.

Changelog

Fixes

  • cccbcab0c3ec7d60f581c594405a91121f9945b6 fix(shutdown): a SIGTERM is not a failed attempt, so it announces no retry (task #11655)
  • 481f3a986071f48906736ef6dc791eb0d4a8329f fix(skills): a pinned model can only be right for one of the two backends reading the same directory (task #11670) ### Other
  • f6d5a9815968c7fa3f2c7443e150928740e698ed fix(ci-lock): the acquiring guard could not go stale, and a nameless lock killed acquire outright (tasks #11671, #11672)
  • bb0b389ebab93a7153d7f439e3d8600367a4a13a fix(ci-lock): the guard against a direct test run looked for pidfiles nobody writes (task #11669)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.11

Changelog

Fixes

  • 230496500ec4a402e8d4bdd4bcff1918147f74df fix(quota): a role that ignores working hours is not stopped by its hour goal (task #11643)
  • 886a3355e74423c1d01e1a367a3d39a613a4731c fix(triage): a disabled fetch tool is a detour, not the end of the day (task #11642)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.10

Changelog

Fixes

  • 5fef8b8808e0f121d83d093370ddc01964e07cb1 fix(helpers): resolve Ruby the same way on rbenv as on rvm (task #11641)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.9

Changelog

Fixes

  • bc156c306eb0ce4f115e07d004fdcd6802851175 fix(ci): bump pinned golangci-lint to v2.13.0 for Go 1.27 support
  • 642002843a54df7469862fd332bae3adb55e1c74 fix(install): print which account a scheduled job will authenticate as (task #11494)
  • b782fbecb65c01aa7072cf72b78b5ea5db07b958 fix(launcher): one log file per run instead of one that grows forever (task #11617)
  • a40f46624f890ca770b34e0181d5d204d35ab7ce fix(loop): a declined task skips, it does not end the day (task #11622)
  • e38b8d6025f8662f11a9a6c2cdb8b69652dfda15 fix(triage): discard a pick that belongs to a different project (task #11619) ### Other
  • 55f52d52fb2f96a49b26aa4c7c2d1361246eabb9 docs(skills): follow the MCP parameter renames ahead of the server change (task #11609)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.8

Changelog

Features

  • bb18d74c555e82f11ac1324d9b3b92ac9b3e4d22 feat(config): make end-of-workday hour configurable at install time (task #11495) ### Fixes
  • 7264ca3901696ef4c861fada80b586d35793394a fix(prompt): anchor the progress-logging milestones inside the auto-squash steps (task #11616)

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

v0.3.7

Changelog

Features

  • b66ced087bcd9d6afae57c80e57cf5ea1ce4283a feat(bugreport): remove the manual bug-report CLI command (task #11481) ### Fixes
  • 66bab4931cd4555bab6cfc0655994d9ae61bd275 fix(bugreport): retarget automatic error reports to this project's own Epic (task #11482) ### Other
  • 0ae13df7ff594e7e7db44aa841892ed4a0ee6df4 chore(claude): each story gets its own worktree to protect against concurrent session conflicts
  • c1af57c30c09d8a8f16ecd8618aaf109d0443325 chore(claude): ignore /.claude/settings.local.json repo-wide
  • 30d47d8edc50821df2fb312e2f9eeccfff6b5075 chore(claude): install discover/mcptask-read/mcptask-write/memory-search skills

curl -fsSL https://github.com/jchsoft/mcptask-releases/releases/latest/download/install.sh | sh

Or brew install jchsoft/tap/mcptask_runner, scoop install mcptask_runner,
or npx @mcptask/cli. Verify any manual download against checksums.txt.

list_altCLI reference

Five public subcommands, two persistent flags, three exit codes

The runner is a single binary on a cobra root: run, init, update, version, pr. A sixth subcommand, internal, is hidden from --help because generated launcher scripts call it, not operators: internal launcher-log-name is how the Windows launcher names its own log. Hidden is not provisional — the launcher depends on it at run time. Two persistent flags --verbose and --ignore-quota are read case-insensitively from the matching env var (verbose=true, ignore_quota=true). Per-subcommand flags are listed below each command. Exit code is 0 on success, 3 for an unimplemented mode, 1 for anything else, and 128+N on a signal. 3 is a designed sentinel rather than an ending you can reach today: every mode is implemented, so nothing returns ErrModeNotImplemented.

menu_bookEvery subcommand, flag and exit code – referenceexpand_more

Subcommands

run — the work loopsince v0.1.0

Starts the work loop in one of fifteen modes: a single task, everything assigned for today, a whole queue, the subtasks of one Story, one named task, pending code reviews, or an unattended loop that runs every business day. Auto-squash modes take a task all the way to a merged pull request; manual modes leave the pull request open for a person to review.

  • --story-idsince v0.1.0

    The Story whose subtasks story_manual and story_auto_squash work through.

  • --task-idsince v0.1.0

    The one task that task_manual and task_auto_squash work on.

  • --if-duesince v0.3.38

    Start only if the scheduled job's working day is under way, reading the start time from the job itself. The scheduled job passes it, so that a login at 20:00 or on a Saturday starts nothing.

init — set up a projectsince v0.1.0

Prepares a project for the runner in one command: it records which coding CLI drives the project and which git host its pull requests live on, installs the bundled skills and helper scripts, writes the MCP configuration and the approvals the CLI needs, stores the access token, and generates a weekday scheduled job that you switch on yourself.

  • --clisince v0.3.24

    Names the coding CLI that drives the project — claude, codex or opencode. A script has to give it the first time. At a terminal, init takes the only one installed, or asks among several. There is no default, and later runs reuse the answer.

  • --git-hostsince v0.3.25

    Names the git host — github, bitbucket or gitlab — when the origin remote does not say it, for example behind an SSH alias, on a mirror or on a self-managed GitLab.

  • --epic-idsince v0.1.0

    The Epic on mcptask.online for the bug tasks a run files over failing tests; 0 keeps them at the project root. Left off, init reads the project's Errors Epic from the server. The runner's own crash reports do not use this.

  • --epic-namesince v0.1.0

    A display name recorded next to --epic-id.

  • --modesince v0.1.0

    The work-loop mode the scheduled job runs, such as today_auto_squash, or none for no scheduled job at all.

  • --atsince v0.3.3

    The time of day the scheduled job starts, as HH:MM. Without it, a job written again keeps its own time, and a new one starts at 08:00. A value that is not a time of day is refused, never rounded.

  • --untilsince v0.3.8

    The time of day after which the runner starts no further task, as HH:MM. A task already running still finishes. Left out, the working day has no end and only the daily quota stops the runner.

  • --schedulesince v0.1.0

    Regenerates the scheduled job and touches nothing else.

  • --forcesince v0.1.0

    Overwrites skills, helpers, config sections and the scheduled job that already exist. Also set by FORCE=1.

  • --helper-bin-dirsince v0.1.0

    Where the CI and test helper scripts are installed, and what the skills are written to call. Defaults to the directory the harness profile names.

  • --home-dirsince v0.1.0

    Puts the token directory, the shell start-up file and the scheduled job under another home directory than the current user's.

  • --accountsince v0.3.49

    The mcptask.online account this project is in, written into CLAUDE.md when the file declares none and checked against the server. On a terminal, init reads it from the token when the server can say, and asks otherwise. Required without a terminal.

  • --project-idsince v0.3.49

    The project's number on mcptask.online, written into CLAUDE.md when the file declares none and checked against the server. On a terminal the project is picked from a list instead, and without one this is required.

  • --startsince v0.3.49

    Files a task that gets the files the install wrote onto the base branch, runs it right away while you watch, at any hour and whatever the day's budget says, shows how it ended, writes that on the task, and then switches the scheduled job on; nothing the install wrote is committed during the install. A mode that merges merges it after basic checks without asking the git host for CI, a manual mode leaves the pull request for a person, and a project with no remote works through a local branch and takes no further task until it has one. The run never waits for a person: what would make a background runner wait ends it with that reason, and a failure exits non-zero with the task still pinned for a re-run. The job keeps its working day: inside it the job goes straight to work, outside it the job first starts at its next scheduled time. Asked on a terminal, and without one nothing runs unless this says otherwise.

  • --dayssince v0.3.50

    The days the scheduled job runs on — mon-fri, mon-sat, mon,wed,sat, or weekdays, all or weekend. At a terminal init asks, with Monday to Friday as the default. Without it, a job written again keeps its own days. A value that names no day is refused, never guessed.

update — refresh skills, or the runner itselfsince v0.1.0

Brings an installed project up to date with the runner it now runs on. Every bundled skill and helper is compared with what was installed and reported as added, up to date, updated, skipped because you edited it, or overwritten on request with a backup. With --self it replaces the runner binary from the latest release instead.

  • --selfsince v0.2.0

    Replaces the runner binary with the latest release, verified against the release's checksums; a failed or mismatched download leaves the installed binary untouched.

  • --checksince v0.2.0

    Reports whether a newer runner release exists, and changes nothing.

  • --forcesince v0.1.0

    Overwrites skills and helpers you edited locally, keeping a .bak copy of each one next to it. Also set by FORCE=1.

  • --helper-bin-dirsince v0.1.0

    Where the CI and test helper scripts are refreshed, and what the skills are written to call. Defaults to the directory the harness profile names.

  • --home-dirsince v0.1.0

    Re-roots whatever update writes outside the project under another home directory.

version — what is running, with which settingssince v0.1.0

Prints the runner version together with the configuration it resolved for this project: the coding CLI, the models for each tier, the launcher command, the git host and the other settings, each with where its value came from.

pr — pull requests on any supported git hostsince v0.3.25

Creates, lists, reads, merges and checks pull requests on whichever git host the project is on — GitHub, Bitbucket Cloud or GitLab — and prints one JSON object per call. The bundled skills and the runner's prompts use only this command, so the same instructions work on every host.

  • pr createsince v0.3.25

    Opens a pull request for the current branch — a merge request on GitLab — using the project's pull-request template when it has one.

    • --titlesince v0.3.25

      The pull request title. Required.

    • --bodysince v0.3.25

      The pull request description, given inline.

    • --body-filesince v0.3.25

      Reads the pull request description from a file instead.

    • --basesince v0.3.25

      The branch to merge into; the host's default branch when not given.

    • --headsince v0.3.25

      The branch the work is on; the current branch when not given.

    • --draftsince v0.3.25

      Opens the pull request as a draft.

  • pr listsince v0.3.25

    Finds pull requests: the ones that mention an mcptask.online task, the one opened from a given branch, or every open pull request of the repository.

    • --tasksince v0.3.25

      Searches for pull requests that mention an mcptask.online task. The results are candidates — a search for one number also finds longer ones that contain it.

    • --branchsince v0.3.25

      Finds the pull request opened from this branch, in any state.

    • --statesince v0.3.25

      Narrows a --task search to open, merged, declined or all pull requests.

    • --opensince v0.3.26

      Lists every open pull request of the repository — the whole review queue.

  • pr viewsince v0.3.25

    Reads one pull request — its state, branches and link — as JSON.

  • pr reviewssince v0.3.26

    Reads everything reviewers left on a pull request in one list: the verdicts first, then the comments, inline ones with their file and line, bots included and marked as such.

  • pr mergesince v0.3.25

    Merges a pull request and reads it back, so the output says what really happened rather than what was asked for. Inside an auto-squash run the merge is refused unless the host's CI said yes, or the host runs no checks and the project has its own local gate. On GitHub, a merge commit with exactly the same files as the pull request's last commit gets that commit's passed statuses, so a squash does not lose a check the next merge requires.

    • --squashsince v0.3.25

      Squashes the branch into one commit. On by default.

    • --delete-branchsince v0.3.25

      Deletes the head branch after the merge. On by default.

  • pr checkssince v0.3.25

    Reports the git host's CI verdict on a pull request: success, failed, still in progress, or none — and none is never read as success, because a repository whose CI never ran has not passed anything.

  • --git-hostsince v0.3.25

    Overrides the git host for one pr command, whatever the configuration file or the origin remote say.

  • pr commentsince v0.3.46

    Leaves a note on a pull request, or replies in the thread of one inline review comment — the way the workflow mode answers each comment it worked in.

    • --bodysince v0.3.46

      What the note says.

    • --body-filesince v0.3.46

      Reads the note from a file instead.

    • --reply-tosince v0.3.46

      Replies in the thread of this inline review comment instead of on the pull request as a whole; a comment the host does not know is an error and nothing is posted.

  • pr update-branchsince v0.3.51

    Brings a pull request up to date with its base when the base requires it before merging. The base is merged into the branch on GitHub — a merge commit, never a rebase — and the checkout follows it, so the next local CI run checks the work together with everything merged before it. `pr merge` refuses a pull request that is behind such a base and names this command. It stops after two rounds, on a conflict, and on a checkout with uncommitted changes.

pasted-images — files from images pasted into Claude Codesince v0.3.51

Writes the images the user pasted into the current Claude Code session to files and prints one JSON line per file, with the size, checksum and content type mcptask.online's upload needs. The bundled attach-pasted-image skill uses it to put a pasted screenshot on a task.

  • --lastsince v0.3.51

    How many of the most recent pasted images to write; default 1. Output is oldest first.

  • --transcriptsince v0.3.51

    Reads this transcript file instead of the one named by CLAUDE_CODE_SESSION_ID.

  • --outsince v0.3.51

    Directory to write the files into; default $TMPDIR/claude-pasted-images/<session-id>.

Global flags

--verbosesince v0.1.0

Prints every line the coding CLI streams, not just the summary. On init it prints everything the install writes to its log, not just the questions, the errors and the ending. Also set by the environment variable verbose=true.

--ignore-quotasince v0.1.0

Skips the daily quota checks: the runner neither asks mcptask.online for the remaining budget nor refuses a task over it, and the operator takes responsibility for the spend. Also set by ignore_quota=true.

Configuration keys

harnesssince v0.3.24

Which coding CLI drives the project, by profile name: claude, codex, opencode, or a profile of your own. The one required key — there is no default, and a project that names none is refused rather than assumed to be anything. init --cli writes it.

git_hostsince v0.3.25

Which git host the project's pull requests live on: github, bitbucket or gitlab. Optional — left out, the runner reads it off the origin remote, and a remote it cannot recognise is refused by name rather than guessed at.

models.geniussince v0.1.0

The model behind the strongest tier, used for heavy coding and for a task that has to be finished after an earlier attempt fell short. Without it the harness profile's own model is used.

models.smartsince v0.1.0

The model behind the middle tier, used for triage and reviews. Without it the harness profile's own model is used.

models.primitivesince v0.1.0

The model behind the fastest tier, used for simple, read-mostly work. Without it the harness profile's own model is used. On a backend that is not the CLI's own, pin all three tiers or none.

launcher.commandsince v0.1.0

A command that starts the coding CLI in place of its plain binary — for example through ollama launch, or wrapped in caffeinate so a Mac does not fall asleep mid-task. It is checked against harness, so it cannot quietly start a different CLI than the one the project declared.

launcher.flagssince v0.1.0

Overrides individual command-line flags the harness profile passes to the coding CLI; a flag set to null is left out entirely.

launcher.cli_checksince v0.3.24

On by default. Set to false only when launcher.command points at a test double instead of a real coding CLI; it switches off the check that the command starts the CLI the project declared.

waiting_strategy.short_wait_minutessince v0.1.0

How long today and today_auto_squash wait before asking again when no task is ready; an assignment on the dashboard ends the wait at once. 30 minutes by default.

waiting_strategy.long_wait_minutessince v0.1.0

How long daily waits before asking again when no task is ready. 60 minutes by default.

skip_list.revive_after_minutessince v0.3.22

How long a task the loop had to set aside — one that failed, or that somebody else had already started — stays out of triage before it may be picked again. 60 minutes by default; 0 keeps it out for the rest of the day.

skip_list.max_revivalssince v0.3.22

How many times in one day a set-aside task may come back for another attempt. 2 by default; 0 means never.

bug_destination.epic_relative_idsince v0.1.0

The Epic on mcptask.online that receives the bug tasks a run files over failing tests. Without it they land at the project root. The runner's own crash reports find their Epic on the server instead.

bug_destination.epic_namesince v0.1.0

A label for that Epic, shown in the start-up summary only.

pr_template.pathsince v0.1.0

The pull-request template the agent is told to follow, relative to the project root. GitHub and GitLab projects get their host's usual path without it; on Bitbucket this key is the only way to name one.

work_window.end_of_workday_hoursince v0.3.8

The hour after which pr_only, today_auto_squash and daily start no further task; a running task still finishes. Left out, the working day has no end. init --until writes it.

work_window.end_of_workday_minutesince v0.3.23

The minute within that hour, so a day can end at 18:30. Optional and 0 when absent; an unreadable value leaves the whole window unset and says so at start-up.

story_branches.enabledsince v0.3.35

Story branches for this host: the tasks of a Story merge into a shared Story branch, and the Story's last task brings the whole Story into the main branch in one merge. On unless set to false, and even a host set to false follows a Story branch that already exists; a value that is not true or false is refused rather than guessed.

debug.capturesince v0.3.24

Records the coding CLI's raw output into the project's log directory, with secrets redacted, for diagnosing a run. It changes nothing about how the run behaves, and an environment variable overrides it either way.

work_steps.beforesince v0.3.51

The project's own step before the work, in its own words: the runner puts the text into every task's prompt as a numbered step, after the task is fetched and before any code is read, for every coding CLI. It adds nothing to the text and checks nothing; a step the agent cannot carry out is noted in the work log and does not cost the task.

work_steps.aftersince v0.3.51

The project's own step after the work, in its own words: a numbered step in every task's prompt once the tests are green and before the push — for example, recording what the next task will need. Relayed verbatim to every coding CLI; an empty slot leaves no trace.

models.last_resortsince v0.3.52

An optional fourth model level above genius. Triage never picks it; it is used only after the same task failed twice on genius, once per task per day. A models section that does not name it has no such level.

Coding CLIs

Claude Codesince v0.1.0

Anthropic's coding CLI. It gets the full skill set, including the three skills that hand a lookup to a separate sub-session so its raw output never fills the main context, and it can run against any Anthropic-compatible backend through launcher.command and pinned models.

Codex CLIsince v0.3.24

OpenAI's coding CLI. The runner checks that it is logged in before a run starts and refuses the run otherwise, rather than spending the day's quota on a CLI that would fail at its first call.

OpenCodesince v0.3.24

The open-source coding CLI that takes models from many providers. It has no read-only switch, so the runner supplies a permission map that gives the same guarantee by another route.

Git hosts

GitHubsince v0.3.25

Driven through the gh CLI and its own login. The pull-request template is read from the place GitHub expects it. A GitHub Enterprise instance is a different host and is refused by name rather than treated as github.com.

Bitbucket Cloudsince v0.3.25

Driven through Bitbucket Cloud's REST API, with either an access token for a machine or an e-mail and API token for a person — never both, and never an app password. init stores the credential in a file only you can read and never prints it.

GitLabsince v0.3.27

Driven through the glab CLI, which keeps its own login, on gitlab.com and on self-managed instances alike; a self-managed project names gitlab in its configuration because its address does not say so. What the runner opens there is a merge request.

Exit codes

0 — the run completedsince v0.1.0

The command ran to its end. For run this means the loop finished its work, not that every task succeeded — a task that failed is reported on mcptask.online and in the log, and is not a reason for the process to fail.

1 — the command could not do its jobsince v0.1.0

Something the command needs was missing or refused — no harness named, no token, a coding CLI whose preflight fails, an unknown mode, a failed download — and the error printed on stderr names it. The runner refuses to start rather than spend an hour exiting with success over nothing.

3 — mode not implementedsince v0.1.0

Reserved for a work-loop mode the binary recognises but does not carry out. Every mode is implemented today, so a current runner does not return it; a scheduled job may still treat it as "upgrade the runner".

130 — stopped with Ctrl-Csince v0.3.0

The runner was interrupted (SIGINT). It stops the coding CLI it started, marks the session as ended on the dashboard, and exits with the shell's usual 128 plus the signal number. The task stays in progress and the next run picks it up again.

143 — stopped by the systemsince v0.3.0

The runner was asked to terminate (SIGTERM), typically by the scheduler or at shutdown. It stops cleanly the same way as after Ctrl-C, so a stopped run is never recorded as a successful one.

2 — the pre-tool gate refused a commandsince v0.3.39

Returned only by the check the coding CLI runs before each shell command, never by a run: the command would have stopped or restarted the runner itself. The CLI blocks the command and shows the agent the one-line reason the check printed.

monetization_onQuota gates

One number, three places to check it

The runner never trusts its own guess. Every quota decision reads a live number from mcptask.online over REST, then enforces it before, between, and during tasks.

sourceWhere the number comes from

The daily budget is fetched live from mcptask.online over REST (GET /api/{account}/users/current/time_status). The runner never asks the agent to estimate its own budget and never reads a cached value — the account is the single source of truth.

gpp_goodThree gates, in this order

WhenWhat gets checked
PRE-RUN (after triage)Re-polls the live REST endpoint after triage. Triage itself takes minutes; a fresh pull catches anything the user spent while the runner was classifying the task.
BETWEEN-TASK (decider)Stops the loop on a mid-task quota kill, a spent daily budget, or a task that ended with status error. A failed, out-of-scope, already-started or merge-failed task goes on the skip list instead, and the loop moves on to the next one.
MID-TASK (every 360 s)Polls every DefaultQuotaPollInterval. A crossing kills the child and ends the loop with quota_exceeded_mid_task — no retry. Only the daily mode comes back on its own, the next day, starting again from triage. The kill streak (DefaultQuotaFailureKillStreak = 3) absorbs about an 18-minute REST outage before the runner gives up.

tuneA deliberate fail-closed / fail-open split

The two questions are not answered the same way on purpose. "Is the quota exceeded?" fails CLOSED; "Can I work today?" fails OPEN. One error blocks a run; the other lets it start.

blockFail closed

When the question is "have we already spent today's budget?" and the REST call cannot answer it, the answer is YES — the budget is treated as spent and no new work starts. Better to skip a task than to overspend.

check_circleFail open

When the question is "is there budget left for me to work today?" and the REST call cannot answer it, the answer is YES. Better to start a run than to waste a working day on a transient outage.

reportOutage vs spent budget

A REST outage that killed healthy work is a different bug from an exhausted daily budget. The runner tells them apart on purpose (ErrQuotaPollOutage); a spent budget is nobody's fault, while a REST outage is an 18-minute incident worth a bug task.

ScenarioWhat the runner does
Daily budget spentBetween-task decider stops the loop. No bug filed.
REST poll outage (under kill streak)Retry on the next interval. Loop continues.
REST poll outage (over kill streak, ~18 min)Ends the loop fail-closed with status error and its own termination quota_poll_outage — not quota_exceeded_mid_task. That termination is not on the soft list, so a bug task is filed unconditionally and the 18-minute incident gets tracked.

--ignore-quota skips all three gates. The runner never asks for the time status and never refuses a task — the one REST call left is the startup check that identifies the user (/users/current); the operator takes responsibility for the spend.

memoryContext overflow

What survives when the context overflows

The session is unrecoverable. The work is not — because the work is a branch and commits on disk. Two independent mechanisms carry the rest forward, and a third verdict tells the harness to stop filing noise.

menu_bookHow the runner survives a context overflow – technical detailsexpand_more
check_circle

Survives

What the runner hands to the next attempt

  • account_tree

    The git branch and its commits

    The work itself is a branch with commits on disk. Even if every byte of the session context is gone, the diff is still reviewable, the PR is still openable, and the changes are still recoverable.

  • history

    Last 3 actions (in-process restart)

    When the budget is fresh and the process restarts in place, the restart preamble carries the last three actions (RecentActionsCap = 3) plus the measured context-cost findings, so the new attempt resumes with momentum instead of cold.

  • rule

    ContextBudget rulebook

    Every restart inherits the shared handoff.ContextBudget() rules — what counts toward the limit, what does not, and how the runner decides the next attempt is safe to start.

block

Lost

What no mechanism can save

  • chat_bubble_outline

    The full conversation context

    --continue would reload the same oversized context, so the SESSION is unrecoverable. Only the last three actions ride along in the restart preamble; everything before that is gone.

layersTwo independent mechanisms

MechanismScopeWhat carries forward
In-process fresh restartInside the same runner process (retry.go, handleContextOverflow)Budget = 1 restart per process (maxOverflowRestarts = 1, deliberate — kept at 1 after a review). The new attempt reads the last 3 actions, the cost findings, and the budget rulebook.
Cross-process TaskHandoffinternal/handoff/ — one note per task (engine.go, recordTaskHandoff)Writes log/handoffs/task_<id>.json on BOTH the restart and the terminal branch (terminal ends THIS process, not the task). The next NEW process reads it as the prompt preamble for the first attempt — never on a --continue retry. overflow_count accumulates ACROSS runner processes. Notes retire the moment a run ends any other way, and are pruned after 30 days.

gavelThe third verdict: overflow_pr_open

If the restart budget is spent AND an open PR for the task exists, the status is overflow_pr_open, NOT an error. The PR is the deliverable; an open PR with green checks means the work shipped. Filing an error here costs the whole day's loop on a task that is already done. A real task lost a finished commit, an open PR and the rest of the day over exactly this misclassification, which on top of that auto-filed a bug task it had not earned.

overflow_pr_open (not an error)error (what it used to be)
restart budget spent + PR open → overflow_pr_openrestart budget spent + no PR → error
memoryFor developers

Why this isn't magic

Four concerns run in parallel: a child in its own process group, a stream reader, a watchdog, and the event stream. The state machine underneath has ten named states and an explicit allow-list - a rejected transition is a warning, never a reason to stop.

menu_bookWhat runs at the same time – process group, watchdog and state machineexpand_more
lan

Child in its own process group

The runner spawns the coding CLI in a new process group (syscall.SysProcAttr{Setpgid: true}, internal/executor/process_unix.go, configureProcessGroup), so SIGTERM and SIGKILL from the runner hit the whole tree and never leak to the parent. Reader joins are bounded at 30 s (engine.go, stderrJoinTimeout + defaultStdoutJoinTimeout) so a wedged child cannot block shutdown.

stream

Stream reader

Reads the CLI's stream-json line by line as it is produced, in whichever dialect the harness profile declares. Parses events, hunts for the TASKRUNNER_RESULT completion contract, and feeds the StallDetector. No waiting for the process to end — it reacts incrementally to every line that lands.

timer

Watchdog

Independent guard thread on a 30-second heartbeat. Idle kill at 20 minutes, frozen soft-warn at 3 minutes, per-tool hang ceilings (quick / long), an absolute backstop, and a live REST quota poll every 6 minutes. The only outside supervisor over the child.

wifi

Event stream

Persistent WebSocket to mcptask.online over ActionCable (RunnerSessionChannel). Snapshots throttled to ~0.5 s; FSM state changes force-flush. Async reconnect with a 30-second throttle on drop, and a 0.5-second grace window on the final 'closed' frame so the live card never freezes on a stale state. MCPTASK_RUNNER_DISABLE is not a stream-only opt-out — it is the global kill switch for all mcptask.online traffic: the event stream, the quota polls and the bug reports alike (internal/mcptask/endpoint.go, DisableEnv).

hubThe state machine underneath

schema version 3

Ten named states. Every transition is on the allow-list; anything else logs a warning and keeps working. Frozen, pending, stalled and closed are always-allowed transition targets from any state; they are forced by the watchdog (frozen, pending), the stall detector (stalled) and the loop's session close (closed).

States

startingtriageprocessingwaitingfinishedstalledfrozenpendingerrorclosed

Allow-list (a sample)

A few of the transitions the loop uses every minute — and the forced ones the watchdogs fire on their own.

fromtobynote
startingtriageloopAfter spawn, before the first task is picked
triageprocessingloopTask chosen, context delivered to the CLI
processingwaitingloopBacking off between attempts of the same task
processingstalledstall detectorRepeated Edit failures, repeated identical Bash failures, or the same tool signature within the sliding window
anyfrozenwatchdogIdle past FROZEN_WARN_THRESHOLD, no active tools
anypendingwatchdogSingle tool past its warn ceiling
anyclosedloopend_session — the final frame
visibilityObservability

What you can see while a run is in flight

Three independent surfaces — the on-disk run log, the process-wide operational log, and the live ActionCable card — plus the explicit opt-out variables. They are best-effort by construction: watching a run — snapshots and logs — never aborts it.

menu_bookWhat the runner writes to its logs and what the live card shows – technical detailsexpand_more
data_object

Run log — one JSON file per child execution

The most useful surface when the question is "why has the runner been stuck for 90 minutes". The file is opened IMMEDIATELY when the child is spawned, so even an instant crash leaves something to read.

folderWhere
log/runs/run_*.json (one file per child execution)
  • lock_open

    Opened

    At spawn — before the first line of stream-json is even read

  • favorite

    Heartbeat

    Refreshes stream_events, inactive_s and stream_quiet_s every tick, so a hung run leaves its in-flight state on disk

  • task_alt

    Finalize

    Stamps why the attempt ended

Turn "why has the runner been stuck for 90 minutes" from a grep over a 268 000-line stream log into a single file read.

description

Process-wide operational log — broader than the run log

Not a human-formatted mirror of the JSON run log. It is a chronological text log of the whole process: every subsystem writes its Debug/Info/Warn/Error calls into it, so it holds things no run log ever shows — and it does not carry the run log's fields such as session_id or stream_events.

folderWhere
log/mcptask_runner_YYYYMMDD_HHMMSS.log
short_textLine shape
[timestamp] SEVERITY - message (internal/observe/logger.go)
wifi

Live card — one ActionCable WebSocket

One persistent WebSocket carries whole snapshots, never individual events. A dropped frame costs freshness, not correctness, and a reconnect needs no replay.

ChannelPayloadThrottleTimeouts
RunnerSessionChannel (internal/eventstream/eventstream.go, channelIdentifier)Whole snapshots only — no event replay500 ms snapshot, 30 s reconnect throttle, 500 ms final-frame grace10 s subscribe + dial

Finished card: Lingers 60 s after the loop ends (snapshotCloseTTL)

No token: A runner started without a token says so once, loudly, at startup — never silently misses the first event

shield

The boundary — and the opt-outs

Every one of these is best-effort by construction. Outbound observation never aborts a run; a nil *Log is a working no-op. Two environment variables turn the stores off cleanly.

Run logTask handoff
MCPTASK_RUN_LOG=0 – Turns the JSON run log offMCPTASK_TASK_HANDOFF=0 – Turns the cross-process task-handoff note off

The one exception — reassignment: RunnerSessionChannel is duplex: alongside the outbound snapshots it receives the inbound control events piece_assigned and set_aside_cleared (internal/eventstream/eventstream.go). A reassignment is wired through abandonReassigned (internal/runner/loop.go) into the engine's AbandonReassigned — it kills the in-flight child and reclassifies its death as a reassignment. That is the channel's one deliberate control role.

What this does NOT mean: None of the observability surfaces — the run log, the operational log, the outbound snapshots — can stop a run, restart a run, or classify a run. The best-effort property is the precise boundary of the project's no-fallbacks premise: the one place it does degrade, and says so out loud.

Runner fleet: Every runner instance of the account is also listed on its Runner fleet page (user menu): one row per machine and project with the CLI, model, state, last reported task, today's hours against the daily limit and the runner version, updated live. Account managers and company owners see every runner; project members see the runners of their own projects.

bug_reportBug reporting

When a hard failure happens, a bug task files itself

There is no manual command to run. When a hard failure happens, the runner opens a bug task for it automatically. A real crash becomes a task somebody can pick up — not a silent gap nobody knows to go looking for.

menu_bookWhen the runner files a bug task by itself, what it attaches and how it avoids duplicatesexpand_more
rule

When a bug task gets filed

Only status error, status crash or status anomaly counts as a hard failure. Those are the three values in hardStatuses (internal/bugreport/runner_error.go). Every other outcome — success, stalled_for_genius, urgent_bug_pending, or a graceful quota bail — is the runner working as designed and files nothing.

check_circle

Filed

status error, status crash, status anomaly

What an anomaly is

a guard of the runner's own that did not hold in a run which then carried on — nothing failed, the day's work continued, and from the outside there is nothing to see. An error announces itself by ending a run and a crash by killing a process; an anomaly announces itself to nobody, which is exactly why it gets a piece.

horizontal_rule

NOT filed

success, stalled_for_genius, urgent_bug_pending, graceful quota bail — these are working-as-designed verdicts

priority_high

Soft exception

a mid-task quota kill, a spent rate-limit window, a spent CLI usage limit, or a piece taken away from the runner all arrive wearing status error and are never filed (softTerminations = {"quota", "rate_limited", "usage_limit", "reassigned"}, internal/bugreport/runner_error.go)

attach_file

What the bug task carries with it

Three artefacts are attached to the filed piece (internal/bugreport/runner_error.go, attachArtifacts), so the next person can read the failure without re-running it.

description

Failing attempt's run log

the JSON the on-disk run log finalized with

terminal

Stream log tail

the newest stream log, capped at 512 KB (internal/bugreport/runner_error.go, streamTailBytes)

visibility_off

Redacted config snapshots

depend on the harness — .mcp.json, .claude/settings.json and .claude/settings.local.json on Claude Code, .codex/config.toml on Codex CLI, opencode.json on OpenCode — tokens stripped (mcptask/piece.go, ConfigFiles + Redact)

fingerprint

One incident is one piece

Identical failures are fingerprinted, throttled, and reported exactly once. Without that, a tight loop would file the same bug 200 times before somebody noticed.

FingerprintNormalizationThrottle windowStamp claim before file
sha256 over termination + normalized message + task id + project, truncated to 16 hex chars (internal/bugreport/runner_error.go, fingerprint)strips paths, hex strings, and decimal numbers — what looks like the same crash with a different timestamp counts as the same crashsix hours (internal/bugreport/runner_error.go, throttleWindow + claim) — the second identical fingerprint within the window is droppedthe fingerprint stamp is claimed BEFORE the piece is created and RELEASED if the piece never gets created. The failure most likely to break CreatePiece is the one a retry would otherwise silently suppress
warning

Panics — re-raised, with a stack trace

A panic is a hard failure with a forensic trail. The piece gets the trace; the loop keeps the panic (loop.go, reportPanic). Otherwise the trace would be eaten by the panic recovery and lost to whoever picks up the task next.

shield

Fail-safe throughout

Every reporting path swallows its own errors, including its own panic (internal/bugreport/runner_error.go, MaybeReport defer/recover). A reporting failure can never end a run. The whole premise is that the worst-case reporter is the one that costs the least — a swallowed log line, not a missed crash.

visibility_off

The blind spot, stated openly

The reporter authenticates with the same token as everything else, so it CANNOT file the bug that says the token is missing. A missing or unconfigured token skips the reporter silently — OutcomeSkippedDisabled writes no error line, so only the runner's own exit code and log carry it. A token the server refuses is the loud path instead: OutcomeRefused logs an error naming the token (internal/bugreport/runner_error.go). The alternative was to hide the gap; the choice here is to name it.

swap_horizFor developers

Model-agnostic by configuration

Three tiers map to any provider and to any of the three coding CLIs. Claude Code points at any Anthropic-API-compatible endpoint (local Ollama is the documented example) by changing the launcher and the models section. OpenCode takes provider/model IDs from any provider, Codex CLI ships its own defaults, and `ollama launch <cli>` works for all three.

menu_bookModel configuration YAML examples – technical detailsexpand_more

The models: section is optional. Without it each harness uses its own generic aliases, resolved by that CLI at runtime: opus / sonnet / haiku on Claude Code, gpt-6-astra / gpt-5.6-terra / gpt-5.6-luna on Codex CLI, and provider/model ids on OpenCode. Pin versioned IDs only when you want deterministic retries, or when routing through a non-Anthropic backend — and once you do, set all three of genius / smart / primitive. The runner does not refuse a partial models: map, but the background work the CLI does on its own then fails with "model may not exist".

terminalPer-harness defaults
# models: is optional. Without it each harness falls back to the generic
# aliases its own CLI resolves at run time.

# Claude Code
models:
  genius:    opus
  smart:     sonnet
  primitive: haiku

# Codex CLI
models:
  genius:    gpt-6-astra
  smart:     gpt-5.6-terra
  primitive: gpt-5.6-luna

# OpenCode — every id is provider/model
models:
  genius:    <provider>/<strongest>
  smart:     <provider>/<middle>
  primitive: <provider>/<fastest>
terminalExample: non-Anthropic backend
models:
  genius:    minimax-m3:cloud
  smart:     kimi-k2.7-code:cloud
  primitive: deepseek-v4-flash:cloud

launcher:
  # Local ollama
  command: [env, "ANTHROPIC_BASE_URL=http://localhost:11434", "ANTHROPIC_AUTH_TOKEN=ollama", "claude"]

The IDs below are one example, not a recommendation — they age fastest of anything on this page. The shape is what matters.

launcher.command flags (launcher.go, Flag* constants): a null flag is OMITTED from the spawned argv, a value flag with no token is passed POSITIONALLY.

auto_fix_highThe loader never fails

A missing, empty, or malformed config/mcptask_runner.yml is treated as "no config" (config.go, LoadFile) and the built-in defaults apply — the loader itself never fails. The run preflight is a separate check, and it does refuse to start: when harness: is unset, when the token is missing, or when the project has no CLAUDE.md.

check_circleNo pin

No shipped skill declares `model:` — ForkModelEnv therefore reaches every forked subagent, including ones running on a non-Anthropic launcher.

info

The configuration lives in config/mcptask_runner.yml, resolved relative to the working directory of the launcher (config.go, FileName; README.md) — the same file the Ruby gem reads, with the same semantics. You can also set additional options there, such as the destination Epic for auto-found bugs or the waiting strategy between runs.

GEM — exact file path, exact semantics

system_update_altSelf-update

update --self, and the deliberate non-feature

The runner is a static binary installed by download, not a gem that bumps on every bundle. Two commands move it: update --self fetches a newer release and swaps it in, update --check reports whether one exists and does nothing else. The third decision — whether the runner should ever move itself before a scheduled run — is the one we deliberately do not automate.

menu_bookHow the runner swaps itself for a new version – technical detailsexpand_more
swap_horiz

How update --self swaps the binary

The new binary lands in the same directory as the old one and a rename dance moves it into place (selfupdate.go). That sequence matters more than it looks: a rename is only atomic within ONE filesystem, and /tmp usually is not the same one, so the new file is staged alongside, not copied over from somewhere else. A failed or mismatched download never reaches the swap — the binary on disk is untouched and the command exits non-zero.

file_download

1. Fetch from the public releases mirror

the binary for this GOOS/GOARCH is downloaded from jchsoft/mcptask-releases (selfupdate.go, DefaultRepo). The source repo is private, so the public mirror is the only host the download can come from without a token

verified

2. Verify against the release's checksums.txt

the asset's sha256 is compared to the one the release published (selfupdate.go, verify). A mismatch aborts before any write touches the install directory

file_copy

3. Stage alongside, rename the running binary aside

the new binary is written next to the running one, then the running one is renamed to a sibling name. That is also what makes Windows work — overwriting a file that is mapped for execution fails on Windows, and the rename-aside step sidesteps that

published_with_changes

4. Rename the staged binary in, atomically

a final os.Rename on the same filesystem moves the staged binary into the install path. Atomic within that filesystem. The command exits 0 only after the swap

visibility

update --check — a tag lookup, no download

update --check resolves the latest release tag, compares it to the running version, reports the answer and exits. It downloads no asset and verifies no checksum — none of the four steps above run. The binary on disk is not touched. It is the right command to wire into a nightly job that wants to alert without installing.

shield

The deliberate non-feature

The runner does NOT update itself before a scheduled run. It prints a one-line hint when a newer release exists and does nothing else, because one bad release must not reach every unattended host at 08:05 simultaneously. Upgrading stays the operator's decision, even when the binary runs unattended.

notifications

What the hint does

selfupdate.Hint prints one line when a newer release exists (hint.go, hintTimeout + hintInterval). Capped at 2 s, cached for 24 h, ignoring every error — a network blip or a rate-limit never reaches the run

block

How to turn it off

set MCPTASK_NO_UPDATE_CHECK=1 in the host environment. That is what an air-gapped or metered host wants, and the check is silenced before the cache file is even read

inventory_2

One of three paths that restart the runner — bundle adoption

BUNDLE ADOPTION: on run, if the project's own Gemfile.lock names a newer wrapper-gem version than the running binary, the run re-execs on that binary. It FETCHES NOTHING — the operator already made that decision by merging the lockfile. The 08:05 host reads the lock it pulled from main and runs what the lock says to run. The third path sits between tasks: an iterating mode takes up a newly installed binary before it starts the next task — including one update --self put into ~/.mcptask/bin — and checks the lockfile for adoption at that same boundary.

repeat

MCPTASK_ADOPTED

set in the environment of the re-exec'd child, this stops adoption from becoming an exec loop (adopt.go, EnvMarker). A binary that reports older than the lock would otherwise adopt, exec, find itself outdated again, and spin

push_pin

MCPTASK_NO_ADOPT

set to 1 to pin the installed binary no matter what projects carry. A host that wants one runner version across every project it runs sets this once

bedtime

Another path — daily hands over to a newer binary before its overnight pause

On the way into its overnight sleep, a daily run checks whether the binary on disk is still the one it started from. If not, it releases the instance lock and execs the installed binary — restartOnCurrentBinary (restart.go). That handover DOWNLOADS NOTHING either — it only adopts what update --self or an operator already put on disk. The ordering is load-bearing: the day's work is finished, so no child is alive and no working tree is half-written, and the process that wakes up tomorrow is the one that started this evening.

help_outline

Why it exists

everything that notices a new version happens once, at startup. A daily process starts once and never ends, so an unattended host would otherwise keep whichever binary it happened to start with however many releases go by — exactly the host nobody is watching. Making daily exit instead was considered and rejected: a runner that goes away is one a missing or unloaded scheduled job never brings back

lock_open

ErrLockLost — the third ending

restart.go declares ErrLockLost, a handover that let go of the instance lock and then could not take it back. That ending DOES stop the loop, deliberately and loudly — carrying on unlocked would let the next scheduled start put a second runner in the same checkout

autorenewMaintenance

Skill Updates Without Losing Your Edits

An installed project drifts as the runner gains skills. One command re-syncs it: mcptask_runner update. It compares every skill and helper against the install manifest, reports what it did to each one, and refuses to overwrite anything you edited yourself. It is also how an installed project stops calling `gh`: the bundled skills migrated to `mcptask_runner pr`, and `update` is what brings that migration to a project installed before it.

The command

mcptask_runner update
menu_bookWhat update does to your project – the five outcomes and --forceexpand_more
fact_check

Five outcomes, one per file

The updater holds a content hash for every file it installed. Each skill and helper is classified against that manifest and the result is printed — five outcomes, not a silent copy. A project installed before the PR work reads its skills as `updated` — they are the shipped version, untouched by you — so the `gh` calls inside them are replaced without asking.

add_circle_outlineadded

The file is not on disk. The updater writes it. New runner capabilities land this way without you asking for them by name.

check_circle_outlineup-to-date

The file on disk hashes to the manifest entry. Nothing is written. A gem-installed host reads as up-to-date to this binary — checked directly against the file, not assumed from the install channel.

syncupdated

The file matches an older manifest entry, so it is the shipped version and you never touched it. Safe to replace, and it is replaced.

blockconflict-skipped

The file hashes to neither the current nor a known shipped version — you edited it. The updater leaves it exactly as it is and says so. This is the default, and it is why the command is safe to run on a project you have customised.

restore_pageforce-updated

The same conflict, resolved the other way because you asked. Only reachable with --force or FORCE=1.

restore_page

Overwriting a conflict, with a way back

mcptask_runner update --force

--force (or FORCE=1) overwrites locally modified files instead of skipping them — and keeps a .bak next to each one it overwrites. Your edits are not deleted; they are moved aside where you can diff them.

shield

What plain update deliberately leaves alone

update touches skills and helpers — and one outdated .mcp.json entry, described below. Everything else the installer once wrote stays exactly where it is. That restraint is the selling point, not an omission: re-syncing skills must not silently re-activate a schedule or rewrite a config file you tuned by hand. `git_host:` and `harness:` are config, so `update` never touches them either — moving a project to another PR host or another coding CLI stays an `init` decision.

schedule

The scheduled job

The LaunchAgent, systemd user timer or Task Scheduler job is not regenerated and not re-enabled. Use init --schedule when you actually mean to regenerate it.

data_object

.mcp.json

Your MCP client configuration is not regenerated. The token variable you declared survives the update untouched; the one change update makes is moving a legacy SSE mcptask-online entry to HTTP, the transport the server speaks today.

tune

The config sections

config/mcptask_runner.yml keeps the values you set — the work window, the launcher command, the end-of-workday hour. update has no opinion about them.

system_update_alt

Updating the binary is a separate decision

update re-syncs the project. It does not move the binary that did the syncing. Two other commands do that, and neither of them ever runs on its own: mcptask_runner update --self swaps in a newer release, and mcptask_runner update --check reports whether one exists and changes nothing.

person

The runner never updates itself before a run

At the start of a run the runner may print one line saying a newer release exists. That is the whole feature — capped at 2 s, cached for 24 h, every error ignored, and silenced entirely by MCPTASK_NO_UPDATE_CHECK=1. Upgrading stays the operator's decision, because a runner that moved itself before a scheduled run would be changing the thing doing the work without being asked. That matters if you are leaving a binary running unattended.

verified

A bad download never reaches the swap

update --self downloads from the public mirror jchsoft/mcptask-releases and verifies the asset against the release's checksums.txt. A failed or mismatched download aborts before any write touches the install directory: the binary on disk is untouched and the command exits non-zero.

verifiedProof

Conformance scenarios and the CI matrix

The evidence behind every reliability claim on this page: recovery, watchdog, stall detection and quota each have a recorded scenario of their own.

playlist_play

Fourteen conformance scenarios

Each scenario is a recorded conversation with the claude CLI plus the behaviour a runner is required to show while replaying it. The scenarios are implementation-neutral: plain YAML plus the contract in conformance/README.md, with no Go or Ruby in them. Driven with `go run ./cmd/conformance {list,run --impl go}`.

Every failure mode the runner claims to survive has its own recorded scenario in conformance/scenarios/. The two implementations run the same files; the old mcptask_runner Ruby gem (not the mcptask-rails-runner gem, which ships the Go binary) is the retired reference implementation the suite can be compared against, and the gate is the Go suite being green.

menu_bookAll 14 conformance scenarios the runner has to passexpand_more
Scenarios 
01 — successthe happy path: a clean run ends with a green verdict, no retries, and a branch ready to push
02 — missing_marker_retrythe run log never finalises a marker; the runner retries until the budget runs out and then bails with a verdict instead of a hang
03 — context_overflow_fresh_restartcontext overflow while the engine is still running — the in-process restart is what carries the work forward and keeps the run alive
04 — context_overflow_terminalcontext overflow after the engine has stopped — the carry-forward machinery hands the file to a new process and that is the only way the run gets out alive
05 — api_overload_529the upstream returns 529 — the runner backs off, the run stays on the right task, and the marker does not advance on a transient
06 — tool_not_enabled_fresh_restarta tool the run needs is missing on the first attempt; `--continue` re-runs it as a fresh restart and the run recovers
07 — tool_not_enabled_terminalthe same tool is still missing after a fresh restart — the run bails with a verdict, not a hang
08 — stall_edit_failuresthe engine edits a file the harness watches; the edits diverge and the watchdog catches it before the marker advances on a lie
09 — inactivity_kill_then_recoverthe child process stops talking — the watchdog kills it, the debug dump is left on disk, and the next attempt picks up the same task
10 — recoverable_retries_exhaustedevery recoverable retry has been spent and the run is still not done — that is a verdict, and the verdict is the only safe outcome
11 — quota_mid_taskthe budget runs out while the engine is mid-edit — the runner kills the child, the attempt ends as quota_exceeded_mid_task with no retry and the loop ends; only the daily mode starts again from triage the next day
12 — stream_closedthe upstream closes the stream mid-turn — the runner detects the close, treats the run as incomplete, and the next attempt re-derives state from disk rather than the gone stream
13 — hung_tool_killa tool the engine called has stopped answering — the watchdog kills the child with the kill-on-hang signal and the run is left re-runnable
14 — triage_unverified_pickthe next-task picker returns a task that has not been verified — the runner refuses to start it, files nothing, and waits for a verified candidate rather than picking something blindly
science

The binary carries no test hook of its own

The runner is pointed at a mock CLI through the ordinary `launcher.command` override (README.md) — the same per-host configuration a developer uses to drive a real one. The suites run in all three harness dialects (Claude Code, Codex CLI, OpenCode), and a conformance project on Bitbucket Cloud and one on gitlab.com cover the other two PR hosts, so a green result holds for every dialect and every host. There is no test-only code path in the binary for the conformance suite to lean on, so a green run here is the same code a user installs.

grid_view

The CI matrix

Every commit runs a 3-OS x 2-Go-version matrix (ubuntu / macos / windows x 1.25.x / stable), go vet, race-detector tests on Unix + stable, bin/smoke on the BUILT binary, gofmt, golangci-lint, a goreleaser config check plus a six-target cross-compile, and the whole conformance suite (.github/workflows/ci.yml). The matrix exists because the runner is installed on developer machines — every desktop platform has to build and pass.

fact_check

What a local run does not cover

A green LOCAL run prints what it did NOT cover — "This machine only: <goos>/<goarch>" — because one OS, one architecture and one Go version is not what CI runs (bin/ci). Green locally is necessary, not sufficient. The Ruby comparison run is a reference check, not a gate: it is skipped, not failed, when the retired gem is not checked out — a machine that cannot reach the reference should still be able to check its own work.

visibility_off

The boundary, named

The conformance harness runs one runner process per scenario, so it cannot express the cross-process half of overflow survival; that is covered by tests running two engines in sequence sharing only the file (README.md). The Ruby comparison run is skipped, not failed, when the retired gem is not checked out, and it holds up no merge either way.

rocket_launch

Turn the machine on in the morning

One static binary, one install line, and the runner starts taking tasks from your queue.

verified_userFree 30-day trial. No credit card. Cancel any time.