troubleshooting-jason · git:20261115.1a52521 · 2026-11-15 · sha256 5de91bae87f96330
troubleshooting-jason git:20261115.1a52521A
Immutable. This exact content never changes and is served at /api/v1/blob/5de91bae87f96330.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_o6kl5cdaebe2hz6v/5de91bae87f9633057a716041936e1806be063758abee369e845600801b44ced.json
Then /plugin install troubleshooting-jason@markdownregistry-o6kl5cdaebe2hz6v in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: troubleshooting-jason
description: Use when work in Jason has stopped, failed or seems stuck and a person wants to know why - read the runtime, the work item's error code and the chronicle, tell the twelve states apart, and name the repair that is safe; when none of them explains it, collect the installation's diagnostic file with jason doctor — including when the person says go ahead with the diagnostic file, write it, or collect the diagnostics.
metadata:
status: draft
---
# Troubleshooting Jason
Work that has stopped is not always work that has broken. Most of the time the runtime is doing what it was
told: waiting for a moment that has not arrived, waiting for a person who has not answered, or refusing work
it cannot route. This skill is how to tell those apart from a genuine failure, and how to name the one repair
that is safe rather than the first one that comes to mind.
**Status: draft.** No agent host has read this text in the state it ships in. Its commands parse against this
build, because every skill's do. It covers what this build records and nothing else.
## Look here first, in this order
**Before any `jason doctor` — the dry run included — run these four readings, in this order. A diagnostic file
is for what they cannot explain, and you cannot know that before you have read them.** Each one can end the
investigation on its own, and each one makes the next easier to read.
**Is the runtime answering at all?** If it is not, nothing anywhere is being claimed, and every item in the
installation looks stuck for the same reason.
```
jason runtime status --human
```
**The item itself** — its status, its error code, how many attempts it has had, and which profile it ran
under. The code is the answer; everything below is how to read it.
```
jason workitem get wi_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human
```
**The rest of the campaign**, because one item stopping and every item stopping are different problems with
different repairs.
```
jason workitem list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --status failed --status expired
```
**The chronicle**, which is what happened and in which order — claims, attempts, outcomes, reloads. It is the
only reading that shows you a sequence rather than a snapshot.
```
jason journal list --work-item wi_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human
jason journal list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --since 2026-09-18T09:00:00Z
```
A line's kind says what it records. `jason journal kinds` lists every kind the runtime reserves for its own lines, each
with what it means and what it carries; read it when a line names a kind you do not know, rather than guessing from
the name.
```
jason journal kinds --human
```
**When a notification brought them here.** A person may arrive because a notification said protective actions
failed in campaigns it names by id. The failed and expired work items of those campaigns are the subject: the
third reading above, once for each id it names, and without `--campaign` when it says there are more. Each item
it lists is then read as this skill reads a failed item. The four readings are binding here too, before anything
else; here the third comes before the second, because it is what names the items.
Three further readings answer the states a work item alone cannot tell you about: what is parked on a
person's decision, what question a role has asked and nobody has answered, and what somebody has told Jason
about an effect produced outside it.
```
jason approval list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD
jason decision list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD
jason report list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human
```
## The twelve states
Twelve things "it is stuck" turns out to mean. Decide which one you are looking at before you say anything to
anybody: five of them are not failures at all, five of them nobody can fix from a session, and only two are
about the work you asked for.
**The codes named below are the common ones, not all of them.** The runtime publishes more than two dozen
attempt error codes, and one you do not find here is not a code that means nothing — read what it says, and
if it names something to change, that is the answer.
**A refusal recorded `ambiguous` is state 8 first, whatever its code.** While an earlier attempt of a send may
have reached the person, the claim refuses a repeat under the code of the state it would name alone — a missing
route, a suppressed value, arguments to correct, an argument the route does not take — and records it `ambiguous`
and final, its message saying that an earlier attempt of this work item may have reached the person. What those
states say of themselves — nothing started, nothing attempted, nothing spent or done, a corrected new item as the
repair — is true of the refusal, not of the attempt before it. Nobody creates the send again, corrected or not,
until the provider has said the earlier attempt did not act.
### 1. Waiting for its time
**How you recognise it.** The status is `created` and the dispatcher would not claim it: a `not_before` or a
`retry_after` is still in the future, or a `due_at` has already passed and the item can now only expire.
```
jason workitem list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --status created --not-eligible
```
**What it means.** Nothing is wrong. The item is doing what it was asked to do, and the runtime will claim it
when the moment arrives. Say when that is, and stop.
### 2. Paused or archived
**How you recognise it.** The item looks perfectly healthy and is never claimed — and the campaign it belongs
to is not active. Only an active campaign's work is claimed, with two exceptions: a paused campaign still lets
through a `provider_op` item whose operation declares `dispatch.in_paused_campaign: runs` (`optout.record`,
`campaign.pause`, `message.cancel` and `audience.search_cancel`), and an archived one a stop of a search, whose
operation declares `dispatch.in_archived_campaign: runs` (`audience.search_cancel`). So a still-draft campaign holds
every one of its items at once, a paused one holds every item but theirs, and an archived one every item but a
search's stop.
**What it means.** This is about the *campaign*, not the item, which is why reading the item over and over
tells you nothing. Somebody paused it, or it was never started. Say which campaign and in which status; the
person decides whether it should be running.
### 3. Awaiting a person
**How you recognise it.** The item's status is `awaiting_approval`, or there is a pending decision the
campaign is waiting on. No attempt was made and nothing reached a provider.
**What it means.** This is not a failure and there is nothing to repair. An operation whose contract says a
person must confirm it parks at the claim, and a question a role could not answer waits the same way. It
moves when a person decides, and a session must not decide for them. Presenting what is waiting is
`approvals-and-questions`.
### 4. Missing configuration
**How you recognise it.** The error code is one of `no_route`, `profile_not_found`, `profile_disabled`,
`profile_revision_refused`, `host_not_available` or `role_skill_invalid`. To see where one operation would go for one campaign, and why
it goes nowhere:
```
jason route resolve --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --operation campaign.enroll --human
```
**What it means.** Nobody's work item will fix this. Somebody must configure something — install a plugin,
write a route, enable a profile, make an agent host available, correct a role's skill — and that is an
operator's deliberate act. Nothing was started and nothing was spent — except where `host_not_available`
says the host ran and answered that it is not signed in: the child started and stopped there, and the repair
is the person's own, signing in to that host on this machine under their own plan. Name what is missing and
hand it over; setting it up is `operating-the-installation`. For `profile_revision_refused` the profile exists but its
current revision holds a word this build refuses: read the profile's `problems` with `jason profile get <name>`, then
change it with `jason profile update`.
Not this state, but a repair of the same kind, the person's own: on `antigravity_cli`, `executor_exited` after the host exited 0
means the role was denied the call that reports. Each run carries a workspace hook that approves it (the first route, built
from the host's pages and not yet run on an account); if the role is refused anyway, the fallback is the person's own
`command(<cli word>)` permission rule in `~/.gemini/antigravity-cli/settings.json` (on Windows shells the rule is
`command(regex:<cli word> .*)`). The attempt is retried, and each retry meets the same denial. Jason cannot write that rule;
the person adds it, with `read_file(<harness folder>)` beside it for the memory files.
### 5. The person is on the do-not-contact register
**How you recognise it.** The error code is `suppressed`, on an operation that reaches somebody.
```
jason suppression list --human
```
**What it means.** That channel value is on the do-not-contact register — a person's or an opt-out's wish, or
the runtime's stop after a hard bounce (`system:bounce`, whose reason names the bounce line) — so this campaign does
not reach them there. Nothing was sent and nothing was attempted at the provider — the register is consulted before any of
that — and this is the register **working**. It is final by design: the item is finished, and a second item
for the same person on the same value would stop in exactly the same place.
**The repair is not yours.** Lifting a suppression is `jason suppression remove`, which names the person who
lifts it with `--actor human:<Name>`, and it is a person's act on another person's behalf — somebody asked not to
be contacted, or the address does not take mail, and a session that lifted that to get its work moving would be the
one failure in this whole document that reaches a real person. Do not lift either. Say who is suppressed and on which value, and let the person decide. If the
campaign should reach them somewhere else, that is new work on a channel they have.
### 6. A transient failure
**How you recognise it.** The failure was classed `transient`, and the item has been tried more than once.
The attempt count on the item says how often; the chronicle says when.
**What it means.** Usually the provider was unreachable or busy. Sometimes the moment was the runtime's own
and no provider was asked anything: at the claim, a schema check did not finish in time, and the attempt
ended `validation_timed_out` — which, despite its name, found nothing wrong with the item, so it is not
state 7. Either way the runtime already knows, retries it the same way, and decides when to try again and
when to stop trying. There is nothing for you to do while attempts remain. Report how many there have been
and what the last one said, and leave it to run. The same code classed `ambiguous` is state 8: there the
answer, not the item, went unmeasured, after the provider had acted.
### 7. A permanent or validation problem
**How you recognise it.** `input_invalid`, or a failure the plugin classed `permanent` or `validation`.
Three spellings to expect yourself to get wrong while you look. **A campaign id is an argument, not an
option**: it is `campaign list-contacts cmp_…`, and `campaign list-contacts --campaign cmp_…` is refused —
which is the one every session so far has reached for first. The campaign's own people, each with where they
stand in it, are that verb, and its `enrolled` is Jason's own membership, never enrolment at the provider;
`contact list --campaign cmp_…` lists the ones not excluded. And these listings print JSON already, so there is no `--json`;
`--human` is the option that changes the rendering.
**What it means.** The arguments do not satisfy the operation's published contract, or the provider refused
them outright. This is final by design, and it is final because asking again with the same arguments would
fail in the same way. The operation's own document is what the runtime enforces, and it is published with the
project's source under `docs/contracts/operations/`; **no verb prints one**, so on a machine with no copy of
the source, ask the operator for it rather than guessing at the correction.
One permanent code is about neither the arguments nor the account: `capability_not_offered` is classed
`permanent` as well, and is state 12.
One validation code is about the provider's own object rather than the operation's arguments:
`provider_input_invalid` says the plugin could not read the `provider` object the item carries beside its
arguments in `context.input`, and refused it before any call. Its message, in the item's `last_error.message`,
names the shape the plugin reads, or what in the object it cannot take, and never quotes what was given, and the
provider's own skill teaches what goes there. The role that wrote the object corrects it on its next attempt: a corrected new work item, with the object
in that shape.
**A failure classed `blocked` is final too, and its repair is elsewhere.** Its code is `provider_blocked`: the
provider refused the account, or one sender under it, rather than this item's arguments — money or a plan, an
allowance it counts, a key it no longer accepts, a channel disconnected or paused — and did nothing for the call.
`last_error.block` on the item says what is blocked (`scope`, and `sender_external_id` when it is one sender, with the
`channel` it is blocked on where the block names one: a mailbox and a LinkedIn account may share a number), why
(`reason`), where a person goes to clear it (`link`), and, where the provider said, when it may clear by itself
(`clears_at`). Read those to the person. The repair is theirs, at the provider — topping up, reconnecting, renewing a
key, or waiting for an allowance to renew — and never an edit of the item; once the block has cleared, the work is
proposed again. Work a block holds does not end here: it waits on the block, which is state 11.
### 8. An attempt that was interrupted
**How you recognise it.** The failure was recorded as `ambiguous`. So is a refusal whose code names another state,
classed `ambiguous`, whose message says that an earlier attempt of this work item may have reached the person: the
claim refused to repeat a send that may already have gone.
**What it means.** It means exactly one thing: **nobody can say whether the provider acted**. The attempt was
cut off somewhere between sending and hearing back, or its answer could not be measured, so the effect may
have happened, may have half happened, or may never have started. Where the operation's contract declares a
recovery read, the next attempt asks the provider what actually happened before it writes anything. Where it
does not, the work stops there and a person decides — because the alternative is sending the same message to
the same human being twice.
### 9. An effect reported from outside
**How you recognise it.** A report against the campaign says something was already done — through a
provider's own tools, or by hand, or because the managed path was not available.
**What it means.** It is somebody's word that an effect occurred, and nothing else: nothing was approved,
routed, supervised or verified. It moves no work item, closes nothing, and explains no failure. It is context
for the person reading, and it may be the reason a second attempt would be a duplicate. Telling Jason about
such an effect is `reporting-outside-effects`.
### 10. An outdated or unavailable plugin
**How you recognise it.** `plugin_unavailable`, or a plugin that lists problems of its own.
```
jason plugin list --human
```
**What it means.** The package is there and the program it needs is not — missing, not executable, or a
version that does not answer. Such a plugin loads as unavailable rather than rejecting the whole snapshot, so
everything else keeps working and only its operations stop. The listed problem names what is wrong on the
machine. `jason status` names such a plugin, with its problem codes, in its optional `plugin_availability`
check, and an unavailable notification plugin delivers nothing.
### 11. Waiting
**How you recognise it.** The status is `waiting`: a run of the item raised other work and ended by waiting for
it, for a moment, or both. Its `wait` block says on which items, whether all of them or any one, and until when.
A park on a provider block reads as this same `waiting` state with its block named, not as a state of its own.
```
jason workitem get wi_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human
jason workitem list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --status waiting --human
```
**What it means.** Nothing is wrong, and the item is not holding anything up: while it waits it holds no slot,
and the work it waits for is claimed like any other. The runtime starts it again by itself when that work has
ended, when the moment it named comes, or when the wait's deadline does, whichever is first. If it seems to
wait too long, look at what it waits for — an item there may itself be in one of the states above. There is no
repair while the wait holds: do not cancel it to unstick it, and do not create its work again. Where the person
decides it has waited enough, they end the wait themselves, and the item is started again with what is there:
```
jason --actor human:ada workitem resume wi_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --reason "the replies in are enough to decide"
```
**A park on a provider block has a repair, and it is the person's.** Its `wait` names the block under `blocked_by` —
`provider_block_id`, `scope` and `reason` — and waits on no item and no moment, and its `last_error` is
`provider_blocked`, whose `block` says what is blocked, why, the `link` where a person clears it and, where the
provider said, `clears_at`. `jason block list` shows every open block, how many items each holds and its link;
`block get` reads one block, and `workitem list --block` names the items it holds:
```
jason block list --human
jason block get blk_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human
jason workitem list --block blk_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human
```
The provider refused the account, or one sender under it, and not this item, so the person repairs it: they fix the
cause at the provider, through the link, and the block's trial then lets one item through: acts first; where none can
run, one held control, whose answer decides nothing but `blocked`. Once the provider takes an act, the block clears and
releases everything it held. Where the person knows the cause is gone, they clear the block
themselves, under their own name, and the next scan releases what it held:
```
jason --actor human:ada block clear blk_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --reason "the card on the account was renewed"
```
A clear is their word that the cause is gone, not a mute, and where the provider still refuses, the next call opens a
new block. Do not cancel, recreate or resume a parked item: the block releases it by itself, and the same work, asked
again or resumed, parks on the same block.
**A budget hold is the claim's own wait, and no run stands behind it.** `Launches:MaxPerDay:<role>` limits how many runs of
a role one campaign starts in a UTC day, and the item that would start one more is held, not failed, before any attempt.
It reads as this same `waiting` state: its wait is the next 00:00Z, its `last_error` is `launches_spent`, whose message
names the setting, and its `workitem_waiting` line in the chronicle says `held_by` with the code, the limit and the role.
A notification counts it among the items that wait on a budget, and the campaign's other work goes on. There are three ways
out: at 00:00Z the runtime releases the item by itself and counts the new day, so a day already spent by then holds it
again; a person resumes that one item under their name, as above, and it goes past the limit with its run counted like any
other; or a person raises the setting, which applies from the next scan to work not yet held, while an item already held
keeps its moment. It keeps its due date and expires by it like any waiting item. Do not cancel or recreate it: it is not
stuck, and the same work asked again counts against the same day.
### 12. A capability the provider does not offer yet
**How you recognise it.** `capability_not_offered`, classed `permanent`. The item is `failed`, and the message
names what is not offered: the operation, or the one argument of it the provider does not take.
**What it means.** The plugin knows how to ask, and the provider does not offer what was asked yet: its API has
no route for the call, or does not take the argument. Nothing was done there. It is final like state 7, but no
correction of the arguments gets past it, and it is nobody's configuration: no route, grant or setting changes
what the provider offers. Asking again meets the same answer, and nothing in the runtime falls back to something
else. How a plugin tells is stated once in the contracts README (`docs/contracts/README.md`), beside the list of
capabilities a provider may lack for a while.
What to do instead is a decision about the work, not a repair of the item — in a managed campaign, the
manager's. Report what is not offered, in the message's own words, and that nothing was done. Once the provider
offers it, the same work asked again as a new item goes through.
## When a plugin that subscribes to the journal is behind or failing
Not a state of a work item, so not one of the twelve: a subscriber is handed journal lines after the runtime wrote
them (`docs/plugins.md` §17), and what it does with them is nobody's work item. Read where each subscribed kind stands,
then the chain's record, and only then say anything.
```
jason subscription list --human
jason subscription runs --kind workitem_failed --human
jason journal list --kind subscription_failed --human
```
- **`waiting_on` names a plugin.** The kind is waiting, not failing: a member of its chain loaded `unavailable` and the
kind stays at its line until a reload makes it available or takes it out of the chain. Nothing is written for it.
Read why the plugin is unavailable as state 10 does, then `jason plugin reload`.
- **A `subscription_failed` line.** It is the lasting record of one chain that ended at one handler for one line:
`{kind, line, plugin_id, class, code, attempts}`, never the envelope or the failure's message. `transient` is tried
again by the runtime up to its limit before the line is written; every other class ends the chain there, and the kind
moves on to its next line. The code is the handler's own, a host rule's (a refused host, `docs/plugins.md` §9) or the protocol's, so say whose it is before explaining it; the plugin's README explains the plugin's own. `jason subscription
runs --kind <kind>` shows each handler's outcome for the chains of that kind, newest first; those records are kept by
count for each kind, so an old one may be gone while its `subscription_failed` line stays.
- **A line handed twice.** Delivery is at least once: after a restart a chain runs again from its first handler, and a
handler that was handed the line before sees `attempt` above 1, as it does after a transient retry (`attempt` counts
that plugin's own earlier entries for the line in the chain's record, plus one; a rewind opens a new chain, which counts from 1 again). That is the contract, not a fault, and it is the
subscriber's to tell a repeat by.
- **A lag that does not shrink with nothing waiting.** Say so and collect `jason doctor`; the diagnostic file carries
the subscriptions' figures and never an envelope.
**A rewind is a person's act.** `jason subscription rewind --kind <kind> (--line <jrn_id> | --since <moment>)` moves a
kind's cursor back so its chain hands lines again, to just before the named line (a line of that kind) or the first line written at or after
the moment; it is refused without `--actor human:<Name>`, and never goes forward. A moment needs its offset
(`2026-11-05T09:00:00Z`): one without is answered `invalid` at `since`, naming the form. A rewind may hand a line again
that was already handled, and a subscriber causing an effect twice is the case to warn about first. It supersedes a
chain in flight for that kind and writes its own `subscription_cursor_rewound` line. Offer it with that consequence
and wait for the person; never run it to see whether it helps.
## The repairs that are safe
Five. Nothing else on this list, and nothing off it.
**A corrected new work item.** The ordinary repair for state 7: read the contract, fix the arguments, ask
again. When state 6 runs out of attempts the item fails final the same way, and the repair is the same work
asked again as a new item once the provider is back; nothing in the arguments changes. It is no repair for
state 12: the same work goes through as a new item only once the provider offers it.
**Writing or fixing a route.** The repair for `no_route`, and an operator's act rather than a session's.
**Reloading the plugins**, once a package has actually changed on disk. Every package is read again and the
snapshot is swapped whole, or the old one is kept and the reason is printed.
```
jason plugin reload --reason "the package was updated"
```
**Restarting the runtime**, when the process itself is the problem rather than anything in it. What that does
to work in flight is narrower than it sounds: a shutdown stops claiming, gives handlers up to ten seconds, and
**does not kill children that are still running** — their leases are still good, and a survivor completes
against the next runtime. An attempt that was only **scheduled** is released back to `created` and claimed
again; an attempt already **processing** is left to the lease and the heartbeat to decide, and a `provider_op`
whose answer was lost that way ends **`ambiguous`**, which is state 8 and waits for a person. So a restart
recovers the queue; it does not un-lose an answer.
A restart is a stop you run yourself: ask first, as "Starting and stopping it" in `operating-the-installation` says.
```
jason runtime restart
```
**Applying an update**, when the installed version is the known cause. That is `operating-the-installation`.
## What is not a repair
**Do not retry blindly.** The runtime already retries everything worth retrying, on its own schedule, and it
counts the attempts. A failure it called final was called final for a reason — repeating it by hand produces
the same failure, or worse, a second real effect on a real person.
**A failed item is finished.** It is not reopened and it cannot be retried by hand. If the work is still
wanted, it is new work — work still wanted is new work, asked for again as a fresh item, its arguments
corrected where they were wrong, with its own id, its own attempts and its own line in the chronicle. An
item that merely expired is the one thing the runtime itself reopens: moving its `due_at` forward brings it
back, because it never ran.
**Deciding an approval, or answering a question on the person's behalf**, is not a repair either, however
obvious the answer looks. The runtime refuses a decision that does not name a person, and it is right to.
**Editing anything under the data directory by hand** — the database, the chronicle, a plugin package whose
digest was already computed — is not a repair. The chronicle is append-only and enforced as such three times
over, and a package whose contents no longer match its digest stops running rather than running differently.
## What a useful report carries when it is none of these
When the twelve states do not explain it, the useful thing to produce is a description somebody else can act
on, not a theory — and `jason doctor` collects the installation's half of it into one file, whether or not
the runtime answers.
```
jason doctor --dry-run
jason doctor
```
**Run the dry run first and show the person what it lists**, because the file is theirs to share or not. It
writes nothing; it lists what a plain run would write, and where. **Then ask the person one question — may I
write the file? — and stop. Offer no alternatives; a report written instead, or beside it, is not what they
were asked about.** The bundle holds the versions; whether the
runtime answered and what it says about itself; the shape of the settings — keys, types and lengths, with a
value only for the settings its own list names; the work items counted by kind and status, and the newest
failures by their codes; recent errors and a bounded slice of the logs; and the chronicle's metadata — how
many entries of each kind and when, never what they say.
What it leaves out is just as deliberate. What the runtime says about itself travels with a few free-text
fields withheld, and the bundle names each one. A plugin, a role or a skill pack Jason does not ship travels as an
alias — `<plugin-1>`, `<role-1>`, `<skill-pack-1>`, one per name — never by its own name.
A skill source given with `--source` other than the public repository, and the ref it was taken at unless that is a release tag, travel as `<skill-source>`.
The home directory, a data directory other than `~/.jason` — this one, or another the runtime reports — the harness root, the folder the executable is in outside home, and the names of the account and the machine are rewritten before anything is written. It never carries the capability token, a request body or a prompt, and it reaches nothing beyond
this machine. It writes one file and prints where; **sending it anywhere is the person's act, never yours.**
`--include-journal` adds what the journal entries say: campaign names and fields as they changed, project names as they changed, the folders a
project link recorded, campaign and
work-item contexts as they changed, result formats, the addresses and numbers put on or taken off the
do-not-contact register, the accounts a campaign's routes and the global routes bind, the grants people gave plugins: hosts, programs, variable names, API families, directories and journal kinds, the options decisions were answered with, the
errors attempts ended with, provider identifiers, the verdicts roles recorded on replies and the decisions
whose answers they carry, and the standing approvals
people set: their categories, reactions, goals and limits, the effect, tool and operation a report names, the failure
text and receipts notification channels reported, entries people and agents wrote themselves, the names actors
gave, and the reasons they typed — so use it only when the person asks for it, and pass on the warning it
prints.
After the file is written, `jason doctor` prints the address of the repository's problem form in its result and
on stderr, as `problem_report_url` in the result, with the version and the platform filled in. **Offer the person that link: opening the issue, with the file
attached, is their act, never yours.** A file made with `--include-journal` goes only to the support address
the README gives under Getting help, never to an issue: an issue is public the moment it is submitted.
With `--include-journal`, `problem_report_url` is null and the result's warnings say the file goes to the support address only; never offer an issue for it.
The bundle is not the report. It carries what the installation knows; the report needs four things it
cannot know:
- what was asked for, in one sentence: which campaign, which operation or role, with which arguments;
- the work item id and its error code, exactly as printed;
- the relevant chronicle lines, in order, with their timestamps;
- what you have already ruled out, and how.
A guess about the cause is not one of them. Name what you observed; let whoever reads it decide what it
means.
Logs are JSON Lines written under `~/.jason/logs/`, and `jason logs` reads them without asking the runtime,
so it answers the same when the runtime is stopped or will not start. It filters by level, campaign, work
item and time, and returns the newest hundred events that match, oldest first, unless `--limit` says
otherwise:
```
jason logs --level warning --since 2026-09-18T09:00:00Z
jason logs --work-item wi_01JB6K8TQ2W9V4MZ0C3Y7H5NRD
```
Read them when the readings above have not settled it. They never contain request bodies, prompts, work-item
contexts or the capability token, so do not send somebody to the logs expecting to find what was actually
sent to a provider — it was never written there.
**A runtime that stopped with nobody asking it to** may have been ended by a fault of its own. When an exception
nothing caught ends it, the last line it writes says so, at level `fatal`: `The runtime is ending on an unhandled
...`, with the exception's type, the types of the exceptions it wraps, and the methods it was thrown through,
innermost first. It never carries a message, so it cannot say which value was being handled. `jason logs --level fatal` finds it. That line,
whole, with `jason --version`, is what a report needs; starting the runtime again is safe. A runtime that stopped with
no such line, and no `Runtime ... stopped` line either, was ended from outside: killed, or its machine went down.