Recovery and troubleshooting

Closing or crashing the app while an agent is working

It is safe to close Castforge while an agent is in the middle of a task, and it is safe if the app or your machine crashes. Your work is not lost.

Castforge continuously saves the things that matter: your conversation transcript, your project and role configuration, and the agent's session identifiers. The only thing that cannot survive a close or crash is the live agent process itself, because that process stops when the app stops. Everything else is on disk and comes back when you reopen.

Resuming is manual, never automatic

When you reopen the app, Castforge does NOT restart any agents on its own. A run that was in flight comes back paused, and nothing runs until you say so. This is deliberate: an unattended agent should never wake up and start working while you were away.

When a saved pipeline snapshot is refused

Before Castforge restores a saved pipeline snapshot, it checks that the saved data is well-formed, uses a compatible schema, and still belongs to the current generation of the project. If any of those checks fail, Castforge refuses the restore without changing the live run. The original snapshot is preserved for diagnosis; it is not silently repaired, replaced, or discarded.

A successful restore is deliberately quiet, too. Castforge records a fresh generation for the restored state, but it does not launch an agent or resume work as part of that restore. Use the existing Resume action when you are ready to continue. That explicit resume is the only action that starts restored work, so the app never restarts a pipeline just because it opened successfully.

While Castforge is resolving a restore, commands that arrive for the same project wait behind it in FIFO order (first in, first out). They run only after the restore has reached its durable result, so a new command cannot race an older snapshot into an inconsistent state. This protection applies to the pipeline snapshot only; your queued messages remain their own independent queue and keep the behavior described below.

The Interrupted card on the board

If a card was mid-task when the app closed or crashed, it comes back marked Interrupted on the board instead of looking like it is still working. An Interrupted card has a coral marker, does not pulse (nothing is running), and shows a Resume control. This is your signal that the card was stranded by a restart and is waiting for you.

Click Resume on the Interrupted card to continue. Castforge rebuilds the run from the saved snapshot: the interrupted task plus the rest of the handoff chain that was queued behind it, and drives it through to completion. Resuming does not re-send your last chat message; it restarts the work that was in flight.

A resume picks up the work that is still outstanding, not the work that already finished. Some of what a run has queued up is a nudge asking the Lead to re-plan around a specific task. If that task is already finished on the board by the time you resume, re-sending the nudge would ask the Lead to re-plan work that is done, and because a resumed Lead starts a fresh session that has not seen your existing phases, it could answer by adding phases the board already has. So Castforge checks each queued step against the board first and skips the ones whose task is finished. Everything else is picked up exactly as before.

This check is deliberately cautious, and it is worth knowing which way it errs. Castforge only skips a step when it can see all of the following: the step was already sent once before the app stopped, it was a request for a plan, it names a specific task, and that task now reads as finished on the board. If any one of those is unclear, including anything that was queued but never actually sent, the step is picked back up. The worst case is that an agent asks you something it has already covered, which costs one turn. Losing queued work you were waiting on would cost far more, so Castforge re-asks rather than drops.

The Interrupted marker clears itself the moment work is genuinely running again. As soon as real output starts streaming for the project, the card stops reading Interrupted, the header stops counting it as interrupted work, and the Resume run button goes away. That holds whether you started the work yourself or Castforge picked it back up on its own (for example when a provider usage limit lifts). The point is that you are never offered Resume for a run that is already in flight, so you cannot accidentally start the same work twice. A project you simply reopened, with nothing actually running, still shows the Interrupted card and its Resume control: the marker only clears on real activity, never on the transcript merely looking busy.

This also covers a card that was waiting on a permission request or a question when the app closed. That prompt belonged to the agent process that has now stopped, so it cannot be answered in place. Rather than leaving the card in an urgent "Needs you" state that points at a prompt you cannot act on, Castforge brings it back as Interrupted or Paused with a Resume control. Resuming re-drives the card in a fresh, live turn, and the agent re-issues any permission request or question it still needs, this time as a live, clickable prompt.

A card that finished before the app closed is not marked Interrupted. The saved run state remembers which card was in flight, and that note is only cleared while Castforge is running, so a crash can leave it pointing at a card that had already reached Done, Review, or the queue. On reopen Castforge now checks that note against the board before it trusts it. If the card it names is genuinely still in progress, you get the Interrupted marker and Resume exactly as described above. If the card has since finished, moved on, or is no longer on the board, the stale note is dropped and rewritten, so it does not come back on the next open: nothing is marked Interrupted, and you are not offered a Resume for work that is already done. You are still told the app closed during a run, in a message that says the run state was cleared rather than inviting you to resume.

This also decides whether genuinely stuck cards are visible. A reopen that trusted a stale note reported a paused run, and a paused run parks all of its in-progress work by design, so no card in it reads Stalled. That hid any card that really was stranded, on the very reopen meant to surface it. Now that the note is checked first, a reopen with nothing genuinely in flight does not report a paused run, and stuck cards show up in the Health tab where you can Nudge them. A run that is genuinely paused with live work behind it is unchanged: none of its cards read Stalled, and Resume run is still how you continue it.

Stranded in-progress cards go back to Up next

A card only stays in progress across a restart if Castforge's saved snapshot still says a turn owned it, and that claim has to still match the card's own status on the board. That is the card you get the Interrupted marker and the Resume control for.

Any other card left sitting in progress is stranded: its turn ended when the app did, and no saved record claims it. On reopen, Castforge returns those cards to Up next so the board shows only the work that was genuinely in flight. This matters for more than tidiness. A card that looks in progress is treated as unfinished work that nothing is allowed to run past, so a stranded one holds back every task that depends on it and keeps its phase from completing. Returning it to Up next puts it back in the queue where the run can pick it up again.

You will see this as a card that read Doing before a crash reading Up next after you reopen. No work is lost: whatever the agent already wrote is still on disk, and the card is simply queued to be picked up rather than pretending someone is on it.

Castforge only does this when it has a saved record to compare against. If a project has no pipeline snapshot, for example because you pressed Stop, or because it has never run the team, nothing is reclassified: with no record of what was running, Castforge leaves your board exactly as you left it.

The fallback if a session cannot be restored

The live agent process is always gone after a close or crash, so the agent's tool usually reports its old session as stale. When that happens, Castforge does not fail or hang. It quietly starts a fresh turn from the saved context (your task, the board, and the run's progress) and records a short note in the project ledger that it resumed without the old session.

Your work and the run's progress are carried forward, so you keep going without retyping anything. This fallback is normal and non-destructive; the only thing lost is the agent's in-memory conversation from before the close, which it rebuilds as it continues.

When a resume has nothing left to pick up

A resume can end up with nothing to run. The check described above skips a queued step whose task is already finished, and a small run whose review round was right-sized away has no follow-up task waiting behind it either. Between the two, a resume can find that every step it was going to re-send has already been accounted for.

If that happens while your board still shows unfinished work, the run is neither working nor finished, and those two look identical from the outside. Castforge treats that as something you need to see rather than a quiet ending. Instead of resuming and going silent, it records a recovery entry for the project in the same list the Recover held verification menu shows, so there is something on screen saying the run stopped and why.

What to do. Right-click the card you want the work to continue on and open Recover held verification. The entry names the step the resume set aside. Selecting it binds that step to the card you picked and runs it, which is how you put the run back in motion. The list is not tied to any one card, so pick the card the work belongs on.

Castforge does not restart the work on its own, and that is on purpose. Resuming is already your explicit action, and this is the case where Castforge cannot tell what the right next step is. Guessing would mean starting a fresh planning session against a board it has not seen, which is exactly how a resume used to add phases your board already had. So it surfaces the decision and leaves the call to you.

If every card on the board is finished, nothing is held. A run with nothing left to do and nothing left unfinished has simply ended, and Castforge says so quietly.

Queued messages survive a restart

A message you sent while a run was in progress goes into the queued stack instead of interrupting the run, and it is written to disk the moment it lands there. So anything sitting in that stack when Castforge closed comes back when you reopen the project. The queued stack above the composer is repopulated, every restored row carries a Not yet run tag, and the caption reads "Restored from your last session. Confirm to let them run."

One thing this does not cover: text still sitting in the composer that you never sent is a draft, not a queued message, so it is not part of the restore.

Nothing from a restored queue runs on its own. A Keep these queued button sits under the rows, and pressing it is what releases them. Until you do, no restored message is sent, even if a run is going. This is the same stance as an Interrupted card: Castforge never wakes up and starts working from something you typed before a crash without you re-affirming it.

If you no longer want a restored message, remove it with its ✕ instead of confirming. Removing one row leaves the rest alone.

On the home screen, a project whose queue came back from your last session shows its Queued (n) chip in coral. That is your cue to open the project and confirm.

Stopping a run does not clear what you typed

Stop cancels the run. It does not cancel the messages you queued. After a Stop the queued rows are still there and the caption changes to "The run stopped, so the next one goes out with your next message.", so a Stop can never quietly eat something you typed. If you do want a queued message gone, remove it with its ✕.

A run you stopped is not an error

If you press Stop and the conversation ends with Run stopped. in neutral grey, nothing has gone wrong. That block is Castforge reporting what you asked for. It used to show a red execution error there instead, which made a deliberate stop look like a crash and sent people looking for a fault that was never there.

How to tell the two apart at a glance. A stop is neutral grey with a stop glyph and reads "You stopped this run, so the agent did not finish. Nothing was left running." A genuine failure keeps the red card with its red edge and its own error text. They are deliberately different to look at, and both can appear in the same conversation without being confused for each other.

When the second sentence is missing. If the block says only "You stopped this run, so the agent did not finish." and stops there, Castforge could not confirm that everything it tried to stop actually stopped. It drops the claim rather than making one it cannot back. The toast beside it tells you what did not stop cleanly. If you want to be sure, press Stop again: pressing it when nothing is running is harmless and reports that 0 role-turns ended.

There is one case worth knowing about. If a seat was genuinely running at the instant you pressed Stop and it failed on its own in that same instant, Castforge reports it as stopped rather than as a failure, because from the conversation's side the two are indistinguishable. If a stopped run left work in a state you did not expect, the project's history is the record to check.

An older message says it is no longer current

A message reading Done. or Stopped here as you asked. with a dashed border, dimmed text and a small No longer current chip on it has not been deleted, corrupted, or lost. It is an older message that the same seat has since overtaken by starting another turn, and the chip is Castforge saying so on the message itself.

This exists because the conversation is a record. Rather than remove a message that has stopped being true, Castforge keeps every word of it and marks it, so you can still read what was said and when without being misled into thinking it still holds. The reason is written next to the chip: the seat started another turn after this.

The marker is not an error state and needs nothing from you. It looks the same every time it appears, so a conversation with several of them is not telling you anything is escalating. The newest message from that seat is never marked, and another seat starting work never marks it, because that says nothing about whether this seat's own Done. still stands.

When a queued message is refused

These are the notices you may see when a message cannot be queued or cannot be started. In none of them does the message run:

A message sent just as a turn was finishing

A message you send while an agent is working waits in the queued stack and goes out when the current work settles. There is a narrow case where that settle point arrives while the turn is genuinely still in its last moment, and the message is passed over. Until now nothing came along afterwards to try again, so a message caught by that timing could sit in the queue indefinitely while the project looked idle.

Castforge now checks back on its own a short while later, and again a few times after that, so a message passed over this way is picked up without you doing anything. The check reads the queue itself rather than a note kept in memory, which is what makes it survive closing and reopening the app: a queued message you have already confirmed is still picked up in the new session.

If the message still cannot be started after those tries, Castforge stops trying and says so rather than going quiet. The project tile flips to Paused carrying:

A queued message could not be started. Send it again, or remove it from the queue.

What to do: either of those works, and both are in the queued stack above the composer. Sending the message again starts the count over, so the run genuinely tries afresh rather than showing you a button that does nothing. Removing the row with its ✕ clears the message and the notice with it.

Why some buttons look "stale" after a restart

After a restart, you might see an old permission prompt or an Apply button from a previous session that no longer responds when clicked. These are stale controls: they belong to an agent process that no longer exists, so there is nothing for the click to talk to.

This is expected. A permission prompt or Apply button is a live request from a running agent. Once that agent process has stopped (because you closed the app or it crashed), the request has no one to answer it, so the button can no longer act. Castforge renders these leftover prompts as inactive rather than pretending they still work.

What to do: ignore the stale control and continue in your current, live session. Send your next message, or use the Resume button if one is offered, and the agent will reissue any permission request it still needs. You will get a fresh, clickable prompt tied to the live session.

If you ever click a live permission button and nothing visible happens, that is a bug worth reporting rather than expected behavior. Castforge is designed to either act on your choice or show you a clear error, never to silently do nothing.

Undoing a change with /undo

If an agent edits a file and you want that edit reversed, use the /undo command in the message box.

1. In the composer, type /undo and run it.
2. Castforge takes the most recent file change the agent applied in this conversation and writes the file back to exactly how it was before that change.
3. The change is marked as reverted in the conversation, so you can see it was rolled back.

A few things to know:

• /undo reverses one change per use, starting with the most recent and working backwards.
• It applies to file edits (the diffs the agent applied), not to every possible action.
• Castforge keeps a limited history of recent edits per conversation for undo, so very old changes may no longer be reversible.

/undo restores the file from a saved copy of its previous contents, so it is a reliable way to step back from an edit you did not want.

Rolling back further: restore in place and cascade undo

/undo steps back one file edit at a time. For bigger rollbacks Castforge has two heavier, destructive options. Both are guarded: they ask you to confirm every single time, in every mode, including autonomous, because they change your working tree or your git history in ways that are not a one-click "redo".

Restore in place

Restore in place resets your project's working files back to a saved point in time (a keyframe the time machine captured). Before it touches anything, it stashes your current uncommitted work with git first, so nothing you had in progress is thrown away: your changes are set aside and are recoverable, and the branch you were on stays where it was. Then it resets the working tree to the chosen point. Because your prior work is stashed and your branch is untouched, the reset is reversible, but it does replace what is currently in your files, so Castforge always prompts before doing it.

Dependency-aware cascade undo

Cascade undo takes back a task's committed work and, because tasks can build on each other, also takes back the work of every task that depended on it, while leaving unrelated tasks alone. It walks the dependency graph from the card you chose, gathers that card plus everything downstream of it, and reverts their commits (it adds reverting commits rather than erasing history, so the record stays honest). Before it runs, it shows you a preview: exactly which cards, which commits, and which files it will touch, so there are no surprises. A card it cannot map cleanly to a commit is skipped and flagged in that preview rather than guessed at. If a revert hits a conflict it is stopped and surfaced to you, never force-resolved. Like restore in place, cascade undo prompts for confirmation every time.

Undoing a card takes back the commit that carried its work, and Castforge commits once per turn. So cards that finished in the same turn share one commit, and undoing one of them undoes the others' work with it. The app tells you at the moment you confirm, naming the other cards: "Undoing A also undoes work committed in the same turn: C. Castforge commits once per turn, so cards finished in the same turn share one commit and are undone together." Read that line before confirming; it is the one thing about cascade undo that the dependency preview alone would not have told you.

General troubleshooting

The app will not launch, or shows a blank white screen

A blank window on launch is almost always a stale or development build issue rather than a problem with your account or data.

1. Fully quit Castforge, including any background instance, and reopen it.
2. Make sure you are running the installed Castforge app, not a leftover development process.
3. If it persists after a clean relaunch, reinstall the latest version from castforge.ai. Your projects and sign-in are stored separately and survive a reinstall.

Sign-in problems

If the app shows you as signed out even though you signed in, or the sign-in does not seem to stick:

1. Sign in again with the magic link. The link opens in your browser; complete it there and return to the app.
2. If you closed the browser before the sign-in finished, it will not register; start the sign-in again and complete the browser step.
3. After a successful sign-in, Castforge stores your session in your operating system's keychain so it survives restarts. If it still does not stick after a clean relaunch, sign out fully and sign in once more.
4. If you are signed out roughly an hour after every sign-in, or you find yourself signed out within a second of launching the app, update to the latest version from castforge.ai. Older builds could not renew a session once the app had been restarted, so the session lapsed and the next launch signed you out. Current versions renew it in the background and keep you signed in across restarts.

If you see "session expired" or integrations stop syncing

Castforge keeps you signed in by quietly renewing your session in the background while the app is running, so you normally never think about it. If that renewal ever fails (for example, your session was revoked, or the app was offline for a long stretch and the session could no longer be renewed), Castforge signs you out rather than silently retrying forever. You will see a "Your Castforge session expired" message and the app will show you as signed out.

When this happens your connected integrations (like Vercel and Supabase) stop refreshing, because keeping those in sync needs a valid session. Nothing is lost: your projects, connections, and configuration are all still on disk.

To restore everything, just sign in again from the Account menu. A fresh sign-in renews your session, and Castforge resumes keeping your integrations in sync automatically. If the app was still able to renew your session on its own, it does so without asking you, so you only see the "session expired" message when a new sign-in is genuinely needed.

An agent is not responding

If you send a message and the agent does nothing:

1. Check that the agent is actually connected. Open the Connections page and use "Verify connection" on the agent's card.
2. Confirm the agent's command-line tool is installed and on your system path. If it is missing, Castforge shows install help on the card. After installing, restart Castforge so it picks up the new tool.
3. If a turn seems stuck from a previous session, look for a Resume button, or send a fresh message to start a new turn.
4. If you are mid-task and waiting on a permission prompt that will not respond, it may be a stale prompt from a previous session (see above). Continue in the live session and the agent will reissue the prompt.

A card keeps saying a role is working, but nothing is happening

A card in progress normally shows a live status while its role works. If a tool the role is using has been running for a while without producing any output, the card swaps that live status for a badge naming the tool and how long it has been running, for example Bash running 7m 30s.

Read the badge literally, because that is all it claims. It means exactly one thing: the named tool has been running for the stated time and has produced no output in that time. It is not a verdict that the run is broken, and Castforge does not treat it as one. Nothing is stopped, nothing is retried, and the turn carries on exactly as it would have without the badge.

The reason the wording is that careful is that Castforge cannot tell the two possible causes apart, and you often can:

• The tool is genuinely doing the work. A full build, a complete test run, a large install, or a scan across a big repository can all sit silent for minutes and then finish normally. This is the common case and it needs nothing from you.
• The tool is waiting on something outside Castforge that is never going to arrive. A dialog opened by another application, a prompt on a terminal Castforge cannot see, or a login window behind the main window. The tool will sit there for as long as you let it, because from its side nothing has gone wrong: it is still waiting for an answer.

Naming the tool is what lets you decide. You know whether the named tool plausibly takes that long on this project, and Castforge does not.

So there are two moves:

1. Wait. If the named tool is one that reasonably runs that long here, leave it alone. The badge clears by itself the moment the tool produces output again, and the card goes back to its normal live status.
2. Stop the turn yourself. Right-click the card and choose Stop this turn. That ends the agent's current turn, the same way the Stop control does. Use it when the named tool has no business taking this long, or when you recognise it as one that is waiting on something you would have had to answer.

Castforge never stops the turn on its own. There is no timer that cancels for you, no automatic retry, and no threshold past which the run is abandoned. The badge reports, and stopping is always your explicit choice, because a wrongly cancelled turn throws away real work while a badge you ignored costs you nothing.

If you do stop it, the card stays where it is and can be run again from the same menu with Retry / Re-run.

A run on GitHub Copilot answered in chat but the board stayed empty

If a project whose seats are on GitHub Copilot talked its way through a plan in the conversation and then produced no cards at all, that was a bug in Castforge and it is fixed. The turn really ran and its answer really reached the chat. What did not happen is the next part: nothing the run said reached the board, so no cards appeared, no work was handed to the next role, and the run had nowhere to go after the first reply. Your sign-in was never the problem, which is why reconnecting the agent or signing in again did not change anything.

The fix arrives with an app update, so if you are still seeing it, update Castforge and run the project again. There is nothing to change in your settings and no need to re-authenticate. Anything an earlier run said stayed in the chat only, so ask for the plan again on the updated version to get that work onto the board.

A check was refused, or a task stayed in progress

When a check is refused, its message names the checking role and says in plain language what went wrong, for example that the check was pointed at the wrong working copy, rather than printing an internal path at you. The full technical detail, including which trees were involved, is kept in the project's history. Re-run the writer turn after recreating or integrating the missing tree, so the checking role can read the work it was sent to review. Castforge refuses the check rather than letting it read the wrong files.

A refusal that stops nothing does not mark the role. If the run carries straight on after the refusal, the checking role keeps whatever status it already had, usually Done or Idle, instead of reading Blocked. The refusal is still visible: it appears as an outcome in the orchestration panel with its reason. So a Designer sitting on Blocked after an approval is not the expected picture of a declined check, and it is worth looking at rather than waiting out.

A design check on a phase whose design task is already finished is not refused. Castforge reopens that task and runs the check again, so you see the card move back to doing on the board while it runs and back to done when it finishes. If the Designer owns no card at all in the active phase, there is nothing to reopen, the run continues without the check, and the skip is written to the project's decision record naming the phase. Giving the Designer a card in that phase is the fix.

If a task reports done but stays in progress, either its own review blocked it or its finished work was not present in your project after integration. The work is intact either way: it is still on the task's own branch and nothing was thrown away. The next turn tries once more. If the work still is not in your project after that attempt, Castforge stops looking on every pass. It puts the reason it found right on the card, and routes that reason two ways: to the planning role for the causes a re-plan can settle, and to you directly for the rest, because those need a decision only you can make.

This park behaves differently from an ordinary blocked card, in two ways worth knowing. First, because the task itself genuinely finished, the card keeps reading Done and the reason is appended to it, so on the board it reads "Done: The turn for this card authored no commits, so there was nothing to bring into the project. Paused until the task is re-scoped." rather than showing as a plain Blocked card. Second, it does not come back on its own. It waits for you, because sending it round again with nothing changed is exactly the loop this behavior exists to stop. Running it from the card is the way back: the task reopens, moves to in progress, and starts again from there. If the same thing happens on that run, Castforge parks it again without asking you twice.

The reason on the card names what Castforge actually found, so you can tell an infrastructure problem apart from a task that needs re-scoping:

A card that finished with no record of where its work was written

A card can finish while Castforge holds no record of the working copy its work was written into, and no record of it having been merged. Nothing is broken about the card itself, but there is now nothing for a check to read, so the next verification has no way to confirm the work.

When that happens the card says so, in a line under the card title: "This card finished unverified." followed by the reason. It is information, not an alarm. The card is not marked failed and nothing is thrown away.

The run can fix this by itself, and on an Autonomous project it does. The fix is the one the refusal already names: start the card's writer again so there is a record to read. On an Autonomous project Castforge does that without asking, because an Autonomous project does not prompt. When it does, the card says so, in a second line: "The run repaired this card itself." followed by why. That line is deliberate. A run that quietly re-runs work looks exactly like a run that is looping, and you should never have to guess which one you are watching.

Once a run is going, it does not wait for you. Castforge looks for cards in this state on its own, every thirty seconds, so a card that finished unverified and then went quiet still gets picked up. It leaves a project alone while a role is working in it, while you are stopping it, while its provider has cut the run off for the day, and while the interface is unreachable, and it comes back to the card on a later pass instead.

It does wait for you to start, though, and that is new. Opening a project is no longer enough to set this going. Until you send a message, or press Run, Resume, Heal or Accept on that project, the thirty-second pass skips it entirely and spends nothing on it. From the first time you do any of those, it is live for the rest of the session and repairs without asking again. Closing and reopening Castforge starts you back at needing one press.

Before this, opening the app was the whole chain: a project gained a live entry the moment you opened it, and thirty seconds later a repair could run and use your allowance without you having done anything. If you ever wondered why work started on its own after you just wanted to look at a project, that was why, and it does not happen any more.

It does wait for the card's prerequisites. Re-running a writer only makes sense in a checkout that actually contains the work the card builds on. If a card this one depends on is not finished yet, or finished but its work has not landed on your main branch (for example, it is parked on a merge conflict), the repair is deferred: nothing is started, nothing is spent, and the card keeps its "finished unverified" line while Castforge re-checks every thirty seconds. The moment the prerequisite lands, the repair goes ahead on the next pass. On an Autonomous project a conflict-parked prerequisite is itself resolved by an agent (see the parallel-execution section of Board, course and milestones), so this wait resolves itself; on Careful and Balanced the conflict waits for you, and the repair waits with it.

It happens at most once per card, and only a repair that ran counts. If starting the writer again does not settle the card, Castforge does not try a second time; it falls back to the ordinary escalation, which brings the card to you with the reason it found. But a repair that never actually got to start, because its writer stayed stuck in the queue, does not use up the card's single repair. Castforge notices, takes the "repaired itself" line back off, returns the card to its finished-unverified state, and the repair is available again for a pass where the writer can really run.

On a Careful or Balanced project it offers instead of acting, because starting a writer again spends your agent allowance and those two levels do not spend it without you. The offer sits on the card's right-click menu as a named action, above Retry / Re-run:

The offer is durable. It stays on the card through a restart and while you are working in another project, and it goes away on its own once the card runs again for any reason. While it is waiting for you, Castforge leaves that card alone: an offer you have not answered is never taken off the card and replaced with something else.

You will often see both lines on the same card at once, and that is the truth rather than a contradiction: the first states the condition the card finished in, the second states what is being done about it. The "finished unverified" line clears once the card completes again with a record, or once its work reaches your project. The "repaired itself" line stays as long as the repair really ran, because then it is a note about something that did happen; the one time it comes off is the unwind above, when the repair never got to start.

My move was refused, why

Reordering the board is guarded. When a move would break something, Castforge refuses it instead of applying it and letting you find the damage later. Nothing is written, the item stays where it was, and the reason is stated: you read it in chat, and for a move you made yourself you also get a short warning on the board. This holds whether you moved the item or the team did.

There are five rules a move can break. The dependency rule is listed twice because it reads differently depending on which side of the dependency you moved, so it names the item you actually dragged either way:

There is one more line you may see when dragging your milestone backlog: Cannot apply that order. It does not match the milestones currently waiting, so the board has been left as it was. That means the order Castforge received no longer matches your backlog, usually because the backlog changed while you were dragging. Nothing was written. Reopen the board and drag again.

A refused move is the board enforcing something correct, not a fault, so it is shown as a plain notice rather than an error. See "The board: course, dispatcher, and milestones" for how moving phases and milestones works.

Nothing is merging into my project

Castforge will not merge finished work over uncommitted or untracked changes of your own sitting in the project folder. That is deliberate: merging on top of them could overwrite edits you have not saved to git.

Earlier builds simply waited in that state, pass after pass, without saying so, which looked exactly like a run that had died. Castforge now says it once and tells the planning role once, and it names how many entries of your own it found. The project's tile flips to Paused carrying a line like "Integration is paused: Git reports 4 uncommitted or untracked entries here. Commit or move them so finished work can merge."

Castforge will not commit, stash or delete those entries for you, and it will not ask an agent to do it either. They are your uncommitted work and only you may move them. The fix is yours: commit them, or move them somewhere else. After that, integration continues on its own on the next pass, with nothing to unblock by hand. You do not have to re-run the card, approve anything, or clear a marker.

How Castforge decides what to commit

That promise is about your entries. Castforge does commit as it works, so it is worth knowing how it tells the two apart.

Castforge compares what Git reports about your project at the start of a turn with what it reports at the end, and commits only the paths that were not already being reported. An entry you already had is left alone whatever happens to it during the turn. If an agent edits it or deletes it, Castforge simply does not commit that change and leaves it for you, which is why an entry of yours can come out of a turn modified and still uncommitted.

There is one case that comparison cannot cover, and it is better known than discovered. An entry you create while a turn is running looks exactly like one an agent created, so it may be included in that turn's commit. Castforge is reading a before and an after, not watching who typed what. If you want to be sure something stays yours, it helps to have it on disk before the run starts. If one does get swept in, nothing is lost: it is in that turn's commit, and git can take it back out.

Three things to know about the count:

• These are entries as Git reports them, not a count of files. A rename is one entry naming two paths, and an untracked folder is one entry however many files it holds. A project with a single untracked folder of ninety files reports one entry.
• Castforge's own .castforge entries are counted separately and never cause this. Only changes of your own hold up a merge.
• A submodule that reads as modified, uninitialized, or carrying untracked content counts as one of these entries, and is resolved inside the submodule rather than by committing in the project around it.

An entry you have staged blocks a merge even when the merge would not touch it. That is Git's own rule rather than a Castforge policy: a merge needs your index to match your last commit, so anything sitting staged holds landing up exactly like an unstaged change does. Commit it, or set it aside with git and put it back once the merge has landed. Castforge does neither for you, and a merge refused this way leaves your branch exactly where it was, with the staged change still staged and its contents untouched.

If a commit lands but your index does not catch up, the next turn tidies up after it. Castforge commits a turn's work and then brings your index up to match. Now and then that second half does not finish: git can refuse it for a moment, most often because another git process is holding the repository, and it does not have to be a crash for this to happen. Whatever the reason, the files that were just committed are left reading as changed when nothing about them has actually changed, and your own next commit would then have undone work that is already in your history.

At the start of the next turn Castforge puts those index entries back, and it says which paths it repaired in the log. It only ever touches a path where the file is still on disk and its contents are byte for byte what your last commit holds, so a change you staged on purpose is left exactly as you staged it, and no file of yours is rewritten either way. For a file that already existed before the turn, it goes one step further and only touches paths that Castforge's own last commit named, so a staged change of yours somewhere else is never in scope at all.

If a repair cannot be made, the run says so with git's own words for why rather than a bare failure, and the path stays in view for the next turn instead of quietly dropping out of everything Castforge commits from then on.

If Castforge cannot read your project's git status at all, that is a different message with a different fix: "Integration is paused: Castforge could not read this project's git status. Check that the folder is a readable git repository." That one is not a statement about your work. Nothing of yours is in the way, and there is nothing of yours to commit; Castforge simply could not run the check. Confirm the folder is still a git repository you can read, and the run picks up from there.

Finished work is not reaching my git history

Castforge commits each turn's work as cards finish (see "Working in a project" for what a run commits). When that stops happening, it says so on the project's tile rather than letting the board and your history drift apart in silence. The tile flips to Paused carrying one line that names the condition, how many cards are done, how many entries Git reports uncommitted, and the one thing to do about it. It is said once rather than on every pass, and none of these re-runs a finished card.

The two you are most likely to meet:

Finished work is not reaching Git history: 3 cards are done and Git reports 4 uncommitted entries in this folder. Commit or move them so the record matches the board.

The board says work finished and your history does not show it. Nothing is lost: that work is on disk in front of you. Commit those entries or move them, and the next pass carries on from there. Do not re-run the cards; their work already exists, and running them again would author it a second time on top of itself.

This one can also appear part way through a run that has already committed. Castforge does not only ask whether your history moved at all since the run began; it also watches whether it has moved recently. If several turns in a row change files and none of them produces a commit, that is a stall even though earlier commits are sitting right there in the log, and the tile says so. A single commit early in a long run is not evidence that the rest of it is reaching your history. If the run then commits again, the condition clears on its own and nothing further is said.

No Git identity is set here, so Castforge will not author commits under a made-up name. 3 cards done, 4 entries uncommitted. Set user.name and user.email in this folder.

This one is a refusal rather than a fault. Castforge could commit and deliberately does not, because every commit carries an author and it will not put a name nobody chose onto your history. Set user.name and user.email for that folder, or connect GitHub and let the project use your connected account (see "Connecting GitHub and other services"). The next turn commits normally.

The rest each name a specific reason Castforge refused its own commit. In every one of them nothing was written and your work is where you left it:

A card committed, but only part of its work went in

A commit is not proof that everything a turn wrote reached your history. A card can finish, Castforge can commit for it, and a few of the files that turn edited can still be sitting loose in the folder. This is the harder version of the problem above, because from the board and from the git log everything looks finished.

It happens when a file the turn edited was already showing as changed when the turn started. Castforge deliberately leaves files like that alone, because they are usually yours and committing them would sweep your half-finished work into the project's history. If a previous turn's commit was interrupted part way through, it can leave a file looking changed when nothing about it actually changed, and every later turn then treats that file as yours and steps around it.

Castforge now notices. When a turn commits and the files it edited did not all make it in, it records which ones were left, and the paths are kept with the run rather than being written into the commit message. Nothing is lost and nothing is undone: the work is on disk exactly where the role wrote it, and the fix is to commit those files. Use Save to history in the git footer (called Recover before 0.6.0-beta), or commit them yourself. Do not re-run the card. Its work already exists, and running it again would author it a second time on top of itself.

Two things worth knowing about when this appears:

• It is quiet when it cannot tell. Castforge only reports this when it actually has a record of which files a turn edited. Some agent CLIs report their edits in a form Castforge can follow and some do not, and projects worked on before this shipped have no record at all. When there is no record, Castforge says nothing rather than guessing, so silence here is not a guarantee that everything landed.
• Your own uncommitted files never trigger it. Having a messy working folder is normal and does not produce this report. It only looks at files a role actually edited during that turn.

Recovering work that never reached history

If a project has finished cards whose work is still sitting loose in the folder, there is a way out that does not make you sort it by hand.

In the git footer at the bottom of the workspace, beside the status pill, a Save to history button appears whenever something is outstanding. On a clean project there is nothing to save and the button is not there. Clicking it opens a dialog that splits what is outstanding into two groups and treats them differently on purpose.

This button was called Recover before 0.6.0-beta. It was renamed because "Recover" read as though it would recover a stopped run, which it never did: it is about work sitting uncommitted in your folder, and it does nothing to a paused run. If a run is paused or interrupted, the controls you want are Resume on the card or in the Health tab, not this button.

Recorded by Castforge and still verified. Entries Castforge recorded while it worked, whose contents still match what it recorded. Confirming this group commits it, and it is the only group Castforge will ever commit without asking. Something Castforge recorded that you have edited since is not in it: what is on disk now is not what Castforge saw, so it belongs to the other group.

Castforge cannot verify. Everything else, and your own work is always in this group. Its one action opens the quick commit box, where you write the message and click. Castforge does not commit this group itself. The dialog also tells the two reasons apart, because they mean different things: some entries changed after Castforge recorded them, and others were never recorded at all.

A brand-new folder is recorded file by file. When a role creates a whole folder that Git has never seen, Castforge records every file inside it separately, so each one can reach the verified group and be committed with a single confirm. Earlier versions recorded the new folder as one entry, which the dialog could not line up against the individual files inside it, so on a project built from scratch almost everything landed under "never recorded" and had to go through the quick commit box by hand. If you still see that on a project, the work was done by an older version, and the quick commit box is the way through.

A project Castforge worked on before this shipped has no usable record, so the verified group is empty and everything routes to the quick commit box. The dialog says exactly that: "Castforge has no usable record for this project, so it cannot verify any of this work and will not commit any of it on its own." That is the expected result rather than a failure. The record an older project carries predates the content check Castforge now keeps for every turn, and Castforge would rather commit nothing than commit on a path match alone.

Recovering a held verification

Sometimes queued review or test work cannot safely be connected to a Course card. Castforge refuses that work before the checking role starts and retains it as one held verification. It does not mark any card done or blocked.

To recover the held check, right-click the intended Course card, open Recover held verification, and select one listed entry. Castforge binds only the entry you choose and re-runs it through the tree that owns the card's work. The list is not tied to any one card, so you can right-click whichever card the held check belongs on.

Holds survive a restart, and since 0.4.2-beta they come back on their own: close Castforge, reopen the project, right-click a card, and the held check is listed again. You do not have to resume the run first, and you do not need the interrupted card to still be on the board. Before this, a hold parked before a restart was kept safely but did not reappear in the menu, so there was no way to select it. If a selection is stale, open the card menu again to refresh the list and try the available held verification. Choosing Stop intentionally discards held verifications.

This is different from a card-bound check that cannot find its writer tree. For that refusal, recreate or integrate the missing tree and re-run the writer turn. See "A check was refused, or a task stayed in progress" above.

Opening a project tells you what is wrong instead of starting

Opening a project never starts work. Castforge reads the project's health first, which costs nothing and calls no agent, and if there is something to say it shows one short panel at the top of the board with what it found and a single button.

What it looks at. Cards whose work cannot land because the branch conflicts, cards that finished with no record of where their work was written, cards marked in progress with nothing running, steps queued and waiting, and whether your provider has paused the run. All of that comes from the board and from Castforge's own notes, so reading it uses none of your allowance.

One button, not a menu. The panel offers exactly one action, chosen from what it found:

Pressing it is the point where you hand over. From that press the project runs the way it always has, including repairing itself when something fails, without coming back to ask again. The panel then stops appearing for that project until you restart Castforge.

If the check itself cannot run. You still get the panel, it says plainly that it could not read the project's health, and it still gives you a button. It does not pretend the project is fine, and it does not go quiet. That combination matters: a project that has not been started this session is skipped by the background repair pass, so if the panel vanished whenever its inputs were unreadable, the one control that starts the project would disappear exactly when you needed it. Pressing the button asks the project to continue and to repair anything blocking it first.

When you see no panel at all. Three situations, and they all mean the same thing here: work is already running, you have already pressed something this session, or there is genuinely nothing to do. In none of them is there a decision worth interrupting you for.

One exception, and it is the important one: a provider usage limit always shows the panel. Pressing a button earlier in the session normally hands the project to the background repair pass, and the panel stops appearing because that pass will handle whatever comes up. It does not handle a paused provider limit: it deliberately skips a project in that state, because no amount of repairing will produce an allowance you do not have. So a run stopped by your provider now gets the panel and a Resume whether or not you have pressed something already, and it says "A provider usage limit paused this run" instead of going quiet.

Before 0.6.1-beta this was the one case that fell between the two. The panel treated the project as already handed over, the repair pass declined it for being limit-paused, and the run sat there with nothing on screen explaining why. If you have been pressing Run over and over on a run that stops after a task or two and creeps a little further each time, that was this: you were hitting your provider's limit and Castforge was not telling you.

It never claims work is happening. The wording always says nothing is running, because nothing is. If you want the project to move, that is what the button is for.

A verification result is being held for you

This is a different hold from the one above, and the difference matters. The one above is a check that never ran. This one is a result that already came back.

When a phase finishes, a checking role verifies it and reports back. Once in a while that report arrives after the run has moved on, and it describes a phase that is not the one the run was checking at that moment. Castforge cannot prove which phase the report belongs to, so it will not apply it. It holds it instead.

Earlier versions threw that report away. That was worse than it sounds: the report being discarded was the one carrying the real findings, so the board could tell you a phase had paused with nothing listed against it, while the list of what actually failed had already been dropped. Nothing is discarded now.

Where you see it. At the top of the board, just under the header, in a panel headed Held verification results. It shows once per project no matter how many cards are on the board, and each entry names the seat that ran the check, the phase the result was stamped for, and how many items it reported as not met. When the check ended without a usable result, the entry also says which way: that it finished without stating a verdict, or without producing any output, or that it stated one that could not be read. Below that, each entry carries the first line of what the checking role wrote, so two entries that would otherwise read alike can be told apart at a glance. The full text is still behind See what it found.

If you used to see a row of these that all said the same thing, that was a bug and it is fixed. Any checking seat that ended a turn used to file a held result, even when it had said nothing about a phase at all, so an ordinary test run left an entry behind every time. Those entries were real records of nothing, they all read identically, and they buried the occasional genuine one. A result is now only held when something actually reported a verdict, or when a real phase check came back that Castforge could not match to a phase. You should see these rarely, which is what the panel was always meant to mean.

Sometimes the result does not name a phase at all. That is the case this panel exists for most of all: the report came back with nothing on it saying which phase it describes, so there is nothing to check it against. The entry says so in as many words, instead of leaving a gap where the phase name goes, and it still offers you all three actions.

The three things you can do with it:

Castforge will not attach the result to a phase you pick, and there is deliberately no option to. Choosing a phase from a list tells Castforge what you intend, but it does not establish that the check actually examined that phase. If Castforge applied it anyway, one phase could end up with correction tasks written from findings produced while checking a different phase, and the wrong work would look like it needed fixing while the real problem stayed hidden. Re-running the check is the honest way back: it costs one more turn and gives you a result that genuinely describes the phase it names.

See what it found and Dismiss always work, including on an entry that names no phase. Reading the findings needs no phase, and dismissing is how you clear an entry you have finished with, so an entry Castforge cannot re-run is never something you are stuck with.

Held results survive a restart, so closing the app and reopening the project brings the panel back. Resolving or dismissing one clears it for good.

A run that ends with a question no longer goes quiet

Sometimes an agent finishes a turn by asking you something ("Should I use Postgres or SQLite?") or telling you it is blocked, without there being a next task ready to run. Castforge now watches for this: when a turn ends on an unanswered question or a stated blocker and the board has nothing queued to continue, it raises a "Needs you" prompt on the card instead of letting the run settle silently. You will see the card flip to the coral "Needs you" state carrying the question, so you can answer and let the run continue rather than wondering why it went idle.

This is deliberately cautious. It only speaks up when the last thing the agent did was ask or report a blocker (not while it is still using tools), and it stays quiet on a normal, finished turn, so it will not nag you after work that actually completed. If it ever does surface a prompt on a turn that was really done, you can just dismiss it.

The project says every queued step is waiting on a card that is not ready

Every queued step is waiting on a card that is not ready. Open the board.

A run can reach a state where there is work queued, nothing running, and every queued step held back by a card that has not finished. There is no turn ending and no timer, so nothing is ever going to come along and pick that queue up. It is genuinely stopped, not slow.

This used to be completely silent. A run would go quiet mid-session and stay quiet for hours, with a full queue behind it and nothing on screen to say why. The project tile now flips to Paused carrying the line above, and the app also names the reason the first queued step was turned away, so you can tell "it is waiting on unfinished work" apart from "it was refused for another reason".

It is said once when the run reaches that state, not repeated on every pass, and it clears on its own as soon as the queue can move again.

What to do: open the board and look for the card the queued work is waiting on. Finishing it, running it, or removing the dependency all release the queue. If the card it is waiting on is itself stuck, the Health tab lists stalled cards with a Nudge to re-dispatch them.

A card whose check was held back, and how to release it

When a card's review step is turned away for a reason that cannot change on its own, Castforge holds that card back instead of trying it again on every pass. That is deliberate: re-running the identical check produced a burst of repeated errors in chat and got nowhere. The trade-off is that the card does not move, and anything depending on it waits too.

Ask Lead to re-plan is the way out. It clears every held card on the project and starts the board moving again. It works even when the board looks completely stuck, which was not true before: the re-plan used to do nothing at all unless the run happened to be waiting at a planning step, so pressing it on a stuck board appeared to be ignored. It now always clears the holds and looks for the next card to run.

If a re-plan finds nothing left to run, it says so rather than going quiet, so you can tell "there was nothing to release" apart from "the button did nothing".

A step that could not start goes back to Up next

When the run picks the next piece of work, it marks that card as in progress before handing the work out, so the board shows immediately what has been claimed. Occasionally the hand-off is then turned away, most often because the card it is bound to is waiting on something that has not finished. The card used to stay sitting in progress with nobody working on it, which reads as active work on the board and holds back everything queued behind it.

The card now goes back to Up next as soon as the hand-off is turned away, so the board matches what is really happening and the run can pick that card up again on a later pass. Nothing is lost and nothing is repeated: the work never started, so there is nothing to undo. You may occasionally see a card flip to in progress and straight back to Up next. That is this working rather than a glitch.

A queued step is also no longer able to double up on the same card. If a step for that card is already waiting, a second one is not added, so the queue cannot grow while the board is being tidied.

In the rare case where the card cannot be put back, Castforge does not leave you to notice it. The project tile flips to Paused carrying:

A board card is stuck in progress with nothing running. Open the board.

What to do: open the board and find the card sitting in progress with nothing working on it. Running that card, or moving it back to Up next yourself, releases whatever was waiting behind it.

An Autonomous run looks idle

Since 2026-08-05, an Autonomous run is not waiting on a permission approval, because it never raises one. If a project set to Autonomous looks stuck, a pending permission card is not the explanation. The Waiting on you panel will normally be empty on an Autonomous project, and its being empty is not a sign that something failed to display.

Work through these instead, in order:

1. A design question from the role that plans your work. Autonomous delegates execution, not design judgment, so a genuine planning question ("Postgres or SQLite?") still waits for you, in every mode. It appears in the conversation as a multiple-choice question, and on the board as a card in the coral "Needs you" state. This is the most common reason an Autonomous run is genuinely waiting.
2. A boundary you set by hand. If your request ended with something like "do not plan yet", the run stopped there on purpose and told you so in the chat. Send a new message to continue.
3. Another project is already running. Castforge asks what to do when two projects contend for the same resource. That question is a scheduling conflict rather than an authorization, so Autonomous does not answer it for you.
4. A rollback you started. Restore in place and cascade undo confirm every time, in every mode, including autonomous, when you press them yourself on the board.
5. A permission card from an older session. A card that was raised before the project was switched to Autonomous, or replayed from a saved conversation, can still be on screen. Answer it or send a new message.
6. Nothing is waiting and the run is genuinely stuck. See "An agent is not responding" above, and check the agent's connection.

If a card really is waiting, you do not have to hunt for it. The home screen shows a row across the top reading "N approvals are waiting on you" with a button per project, so an approval blocking a project you do not have open is visible from the home screen. Click the project button to jump straight there, where the Waiting on you (N) panel in the bottom right lists every outstanding approval with its buttons.

On Careful and Balanced, permission prompts work exactly as this section used to describe. A run held on one waits for a real answer, and opening the project does not answer it for you. That last part used to be a bug: opening a project could approve a waiting prompt, so a run appeared stuck on Mission Control and then "unstuck" itself when you navigated in. It is fixed below Autonomous. On Autonomous the card is now answered for you immediately, by design, which is the setting doing its job rather than that bug returning.

Where the record is. Because Autonomous no longer stops for anything, the log is the only account of what an unattended run did. Every check that would have prompted still runs and still writes a line naming the rule it matched and the folder the action actually resolved to. See "Working in a project" for what is on that list.

An Autonomous project is asking me for approvals

This is the opposite symptom, and since 2026-08-06 it has a deliberate cause.

Castforge answers prompts for you only once it has actually loaded that project's settings. In the moment right after you open a project, before its saved permission level has come back from disk, the app treats the project as Careful and shows the prompt. It does not assume your "Default permission level" applies, because at that instant it does not yet know whether this particular project uses it. So an Autonomous project can briefly ask you about something during the first moments after you open it, and then stop asking once its level loads.

That window is normally too short to notice. If a project keeps asking after that, its settings failed to load rather than loaded slowly, and the project stays on Careful until a load succeeds. Close the project and reopen it. If it persists, restart Castforge, and if it still persists, report it from inside the app (see "Reporting a bug from inside the app" below): the failure is written to the app's log with the project it happened to, so it can be diagnosed from your report.

This is intentionally the safe direction. The alternative, which is what earlier builds did, was to fall back to your account-wide default while the project's own settings were still loading. If that default was Autonomous, a project you had deliberately set to Balanced or Careful could approve things for you during that window, including production deploys, database migrations, publishing and spend. Being asked once too often is the cheaper mistake.

A run is blocked but I cannot see any prompt

This was possible in earlier builds and it is fixed. Approvals used to be shown only at the instant they arrived, so if a run raised one while you were on the home screen or in a different project, no screen ever showed it afterwards. The run sat blocked and looked broken, and the only way out was killing the agent.

Approvals are now read from the agent's own record of what it is blocked on, every time a screen opens. So both the home screen row and the workspace Waiting on you panel show approvals that arrived while you were somewhere else, and they show all of them with a count rather than just the most recent. If a run is blocked, an approval for it is visible from the home screen.

Approvals still only ever clear when you answer them. Castforge does not time them out, expire them, or approve them for you when you look at the list.

A card stayed open instead of completing after a restart

If an agent marks a card finished while that card is still waiting on another card, Castforge holds the completion rather than letting work land out of order, and applies it once the prerequisite finishes. That held completion is only valid for as long as the app session that made it. If you restart Castforge (or update to a new version) before the prerequisite lands, the held completion is discarded and the card stays open on the board.

This is deliberate, and it is the safe direction. A completion recorded in an earlier session cannot be re-checked later, and applying it anyway could mark a card finished whose work was never actually done. Nothing is lost: the card keeps its place, and the agent that owns it will pick it up and complete it again on its next turn. If you want to move it along yourself, use Resume or Nudge on the card from the Health tab.

Finding stuck or interrupted work in one place

If you are not sure what is stuck, open the project's Health tab (next to Chat, Course, Preview, and Memory). It gathers the cards paused because a provider usage limit was hit (each with a Resume, and the reset time when the provider reports one), the cards the board reads as stalled (each with a Nudge to re-dispatch), the cards left Interrupted by a restart (each with a Resume), and a recent history of stalls, wedges, surfaced idle prompts, and automatic resumes. It is read-only apart from those Resume and Nudge buttons, and it mirrors the board's own markers, so it never disagrees with the cards. If nothing needs you, it says "Nothing needs you".

The chat says plan file changes were reconciled onto the board

You may see a short banner in the conversation like this:

Plan file changes reconciled onto the board: 1 phase, 3 tasks added.

This is not an error and nothing is needed from you. Instead of writing a plan into chat, the Lead wrote the work into the project's plan file (.castforge/plan.md) on disk. Castforge noticed at the end of the turn, worked out what the board was missing, and added it. The counts tell you exactly how much landed, and those phases and tasks are on the board and ready to run.

The banner is a notice, not a status. It appears on the pass that found the difference and stays through the turn that follows it, then clears when the turn after that starts. That is deliberate: reconciling the plan file often lets the run continue straight away, so the very next turn frequently starts a second or two later, and a banner that cleared on it would be gone before you could read it. If the two are still apart, it appears again. For a view that stays put, use the Health tab, described below.

For how a plan file edit reaches the board, what gets matched against what, and what happens to anything else written into that file, see "The board: course, dispatcher, and milestones".

The chat says Castforge could not confirm the work was added

The plan file lists work the board does not have. Castforge could not confirm it was added to the board.

Castforge saw work in the plan file that the board does not carry, tried to add it, and could not verify that it landed. Read the line exactly as written. It is not telling you that nothing was added, and it is not telling you that something was. It is telling you Castforge cannot confirm it either way, so it is treating the board as unchanged rather than reporting a number it did not check. Your board is not damaged, and nothing was removed from it.

What to do: use Ask Lead to re-plan, the action in the board header. It converges the two sources before it composes anything: it reconciles the plan file with the board first, so the Lead is handed one board instead of two accounts that disagree. Pressing it on a project in this state can add phases or tasks to the board before the Lead answers, and can raise a plan file banner again at the same time. Both of those are expected.

Editing the plan file yourself is not the fix. Castforge rewrites that file from the board on the next board change, so a change you make there is replaced rather than kept.

Project health says the plan file and the board have drifted apart

The Health tab has a Plan file and board section. It appears only when the two disagree, and it names the direction and the size:

• The plan file lists work the board does not have, with a count of phases and tasks, and up to five of the phase names. This is work an agent wrote into the file that has not reached the board. Ask Lead to re-plan is the way to converge them, for the reasons in the entry above.
• The board has work the plan file does not list. This is the other direction and the milder one: the board is ahead and the file is behind. Castforge rewrites the plan file from the board on the next board change, so it normally resolves itself with nothing from you. That rewrite is best effort, so a file Castforge cannot write, a read-only file for example, stays behind until a later change succeeds.

Both can be true at the same time, and then both lines are shown.

This section is a live read: it is taken when you open the panel and taken again whenever the board changes while the panel is open, so a re-plan that lands work on the board updates it in place. It is not the same surface as the chat banner above. The banner is a per-turn notice that clears a turn later; this section reflects what is true right now. A banner that came and went while this section is still reporting a difference is the two surfaces behaving as designed, not a bug.

Project health says Castforge could not read the plan file or the board

Castforge could not read the plan file or the board for this project.

This is not a divergence claim, and it is not a clean bill of health either. Castforge could not read one of the two things it compares, so it is not telling you they agree; it is telling you it does not know. It reads as its own neutral line under Plan file and board rather than as a difference in either direction.

What to do: check that the project folder is still where Castforge expects it and that it is readable. A folder that moved, was renamed, or lost its permissions is the usual cause, and the project's folder setting is where to confirm it. Once the folder reads normally again, reopen the panel and the section reports a real answer.

When you hit a provider usage limit

AI providers cap how much you can run in a window (for example, GitHub Copilot Free gives a set number of premium requests per month, and the paid plans have their own limits). If a run hits that cap mid-task, Castforge does not lose your place. The active card is parked as Paused on a usage limit rather than looking like a generic stall, and the work done so far is saved.

Because a usage limit applies to your whole account, Castforge now pauses the entire run, not just the one active card. Once a limit is hit mid-run it stops dispatching further roles instead of marching the rest of the board into the same dead limit, so you never end up with a string of roles that each spawned, immediately failed on the same cap, and left phantom progress behind. The rest of the board simply waits for you.

You will find the paused card at the top of the project's Health tab. When the provider tells Castforge when the limit resets (Claude does today), the card names the provider and the reset time, for example "Claude usage limit was reached. It should reset around 3:00 PM, then you can resume." When the provider does not report a reset time, it simply tells you to resume once your limit refreshes.

Click Resume on the paused card in the Health tab once your limit is back, and the run continues from where it stopped. A typed message in the chat picks the run back up too, and a Stop clears it entirely. Any of those three is your explicit go-ahead to re-drive the run. Castforge never relaunches on its own; you decide when to pick it back up.

When in doubt, restart cleanly

Many transient issues clear with a clean restart: fully quit the app and reopen it. Your transcript, projects, and connections are all stored on disk, so a restart costs you nothing but reconnects the live pieces.

If the interface freezes during a very long session

On rare marathon sessions the interface itself can stop responding while the rest of the app is still healthy. Castforge watches for this: if the on-screen interface stops updating for an extended stretch while the window is visible, it records a diagnostic file (freeze-incidents.log, in the same logs folder as the rest of the app logs) capturing what the interface was doing at that moment, and then tries to bring it back. You do not need to do anything for this to happen.

Recovery happens in escalating steps, each given time to work before the next one is tried:

1. Castforge reloads the view from the outside. This works even when the interface is too stuck to act on a request of its own, which is the whole point: a stall this long means the interface cannot run anything you or Castforge asks it to.
2. If it is still stuck, Castforge reloads the app at its start screen, dropping whatever view was wedged.

Most freezes are resolved by step 1 or 2. A reload refreshes the interface and reattaches your saved state, so your projects, transcript, and board come right back. If a run happened to be mid-turn when the reload fired, it comes back the same way an interrupted run does after a restart: click Resume on the card (or send a message) to continue it.

All of this happens quickly. From the moment Castforge notices the freeze, the whole sequence takes about a minute, so you are not left watching a dead window while it works through its options.

If none of those steps bring the interface back, Castforge stops retrying and tells you, with a system dialog titled Castforge is not responding. It offers Restart Castforge and Keep waiting, and nothing happens until you choose. Restarting is safe: your projects, transcript, and board are on disk and come back with you. Any agent run still in progress stops, and you pick it back up with Resume on the card afterwards. Choosing to keep waiting leaves the window exactly as it is, and Castforge will not ask again for that same freeze.

If the freeze happens while an agent is waiting on your approval

This case is handled differently on purpose. When an approval or a question is sitting on screen waiting for you, Castforge will not reload the interface underneath you, because a reload would throw away whatever you were part way through deciding. So neither of the reload steps above runs at all.

That protection used to have no time limit, which meant a freeze during an open approval could leave you looking at a stuck window with nothing offered. It now has one. If the interface stays frozen past that point, Castforge stops staying quiet and shows you the same Castforge is not responding dialog, worded for this case so it is clear that recovery was held back rather than tried and failed. The reload steps stay switched off the whole time; only the dialog appears. Choosing Keep waiting changes nothing, so if your window does come back you can still answer the approval normally.

You reach that dialog just as quickly as you would for any other freeze. Holding back the reload steps costs you the automatic attempts, not extra waiting.

If you minimize the frozen window

Minimizing a window that has stopped responding is a natural thing to do, and it used to make Castforge go quiet. A minimized window normally slows its own timers right down, which looks the same from the outside as a window that has stopped responding, so Castforge deliberately stays out of the way rather than reloading something you are not looking at.

The difference now is that Castforge remembers whether it already saw the window stop responding while it was open. If it did, minimizing does not undo that. You still get the Castforge is not responding dialog on the same timing as any other freeze, so tidying a stuck window away no longer costs you the offer of help.

The reload steps stay switched off while the window is minimized, for the original reason: reloading a window you cannot see would throw away whatever was on it and you would not even watch it happen. Only the dialog appears. A window you minimized while it was working normally is left completely alone, as before.

After a recovery, the board catches up with what is really running

While the interface is wedged it cannot take in updates, so a role that started or finished during the freeze can leave the screen showing something that is no longer true. The usual shape of this is the conversation showing a role working while every seat indicator on the board reads idle, or the other way round.

Nothing used to correct that. The updates that would have fixed it were sent while the interface was unable to receive them, and they were not sent again, so the wrong picture simply stayed on screen until you reopened the project.

Now, as soon as the interface starts responding again, Castforge tells it to ask the app what is actually running and replaces what it was showing with that answer. Opening the board does the same check on its own, so you get a correct picture either way, and running both is harmless.

This is a fresh answer about the present moment, not a replay of what you missed. Anything that finished while the window was wedged reads finished rather than reappearing as busy, and your conversation, outcomes and pending requests are left exactly as they were.

Every recovery attempt is written to freeze-incidents.log, so the file shows what was tried and whether it worked, not just that a freeze happened. If you ever want to send us that file after a freeze, it is in your logs folder, reachable from the log-folder link in the app.

While the interface is unreachable, no new work starts

From the first recovery step onward, Castforge stops starting new work for your projects. This is deliberate. By that point it has proof the interface is not reachable, so anything it started would run somewhere you could not see it or stop it.

A step that was already running finishes and is saved. Castforge does not cut it off, because a half finished task is worse to come back to than a completed one.

Nothing new starts after that until you say so. Work that was lined up is held and waits for you rather than being thrown away.

When you come back, the chat tells you the run paused because the app window stopped responding, so you are not left guessing at a silent stall.

The pause is saved, so it is still there if you restart the app. Restarting is the fix the freeze dialog suggests, and it deliberately does not count as resuming.

You resume the same way you resume any paused run: click Resume in the chat, send a message, resume from the Health view, or retry a card. Stopping the run clears it too. Castforge never restarts the work on its own when the window comes back, because someone who has been unable to see their run should get to look before it starts again.

Storage stays healthy on its own

Castforge keeps its local database tidy for you. In the background it trims very old conversation messages (roughly two weeks and older) and caps how many messages any single conversation keeps, so the on-disk store cannot grow without bound and slow down launch. This runs automatically at startup and once an hour, and it never removes a conversation itself, only the oldest messages inside it. It also keeps just the few most recent daily backups rather than one for every day forever. You do not need to do anything, and it never interrupts an active run.

Message search is off by default on a fresh install so nothing is indexed until you want it, which keeps first-run storage small. If you turn search on later, Castforge builds the index on demand.

Reporting a bug from inside the app

Use Send feedback (in the app menu) and choose the Bug tab. Describe what happened, optionally what you expected and the steps to reproduce, then send.

Before you send, the "What we'll include" panel shows exactly what rides along: a few small diagnostics (app version, operating system, current screen, active agent), and for Bug reports a recent excerpt of your application log. The log excerpt is what lets the team see what the app was doing when things went wrong, without asking you to find log files on disk.

You can also attach a screenshot: click "Attach or paste an image", or just paste an image straight from your clipboard (for example, after a Win+Shift+S snip). A small preview appears that you can remove before sending. Screenshots are stored privately and are only visible to the Castforge team.

Everything attached is reviewable and removable: expand any item to read it, or remove it before sending. Secrets are scrubbed automatically, so API keys and tokens never leave your machine. The log excerpt is a bounded recent slice, not your whole log.

Common questions

Will I lose my work if Castforge crashes? No. Your transcript, projects, configuration, and the state of any in-flight run are saved continuously. Only the live agent process stops. When you reopen, an interrupted card comes back marked Interrupted and waits for you to click Resume; nothing restarts on its own.

I sent a few messages while the team was working and then the app crashed. Are they gone? No. A message sent during a run joins the queued stack and is written to disk the moment it lands there, so it comes back when you reopen the project, marked Not yet run. Nothing from a restored queue runs until you press Keep these queued, and you can remove any row you no longer want with its ✕ instead. Text you had typed but never sent is a draft, not a queued message, so it is not restored.

The app started a "fresh session," did I lose anything? Only the agent's in-memory context from before the close. Your conversation history is intact, and your last message is carried into the fresh session for you.

A permission button does not do anything. What is wrong? If it is left over from a previous session it is stale and inactive by design; continue in your live session. If it is a live prompt and clicking truly does nothing, that is a bug worth reporting.

How do I take back an edit the agent made? Run /undo in the composer to revert the most recent applied file change. Run it again to step back further. For larger rollbacks, restore in place resets your working files to a saved point (stashing your current work first), and cascade undo takes back a task plus everything that depended on it; both show up as confirm-every-time actions because they are destructive.

A run went quiet and I cannot tell what is stuck. Open the project's Health tab. It lists cards paused because a provider usage limit was hit (with the reset time and a Resume), stuck cards with a Nudge to re-dispatch, cards left Interrupted by a restart with a Resume, and a recent history of stalls, wedges, and automatic resumes. If nothing needs you, it says so.

Will Castforge's storage grow forever and slow things down? No. Castforge automatically trims old conversation messages and caps per-conversation history in the background, so its local database stays bounded. It also keeps only the few most recent daily backups. This happens on its own and never removes a whole conversation or interrupts an active run.

I see a white screen on launch. Fully quit and relaunch the installed app. If it persists, reinstall the latest build from castforge.ai; your data survives the reinstall.

The app says I am signed out after I signed in. Re-run the magic-link sign-in and complete it in your browser. After a clean relaunch the session is stored in your OS keychain and should persist.