Project folder missing (recreate or relink)
What happens when a session's project folder is gone from disk: Omniscio fails the spawn at once and shows a red banner naming the exact path, with Locate moved folder… to re-point the project and a confirm-gated Create empty folder…, instead of looping on a cryptic spawn error. Covers the ways to clear it and how automatic recovery waits it out.
On this page
What it is
When a session tries to start and its project's folder doesn't exist on disk, Omniscio now fails the spawn immediately with a clear, actionable banner instead of silently looping with the misleading error "spawn cmd.exe ENOENT". This happens when the folder was moved, renamed, deleted, or lives on a drive that isn't currently mounted (removed USB stick, unmounted network share, unplugged external drive).
You'll see the session flip to red Error status and a red banner slides in above the message composer with:
- The heading "Project folder is missing"
- The exact path Omniscio expected (e.g.
D:/Projects/MyThing) - A short note that the folder may have been moved, renamed, or is on an unmounted drive
- A "Locate moved folder…" button on the right — it opens a folder picker and re-points the project (and its sessions) at where the repo actually is now, then restarts the session
- Below it, a quieter "Create empty folder…" button — see Option 1 below; it always asks you to confirm first
The chat itself also has a one-line system message naming the missing path and pointing at the banner.
Where to find it
The banner appears inside the session panel, directly above the message composer — you don't have to go looking for it. The session's row in the sidebar simultaneously flips to a red Error status. The same event also drops a one-line system message into the conversation itself, naming the missing path and pointing up at the banner.
How it behaves
It only ever names your PROJECT folder — never one session's own scratch folder
The banner is about a project: it appears on every session of that project at once, and both of its buttons act on the project — Locate moved folder… re-points the project itself, and Create empty folder… creates the project's folder. So it is only ever raised when the project's own folder is genuinely missing.
A session can have its own working folder that is separate from the project — a worktree, a code reviewer's read-only copy of a branch, a scratch checkout. If only that one is gone, the session still stops with its own error and its own one-line system message naming the path, and automatic recovery still waits for it to come back. What does not happen is the project-wide banner: your whole hub of sessions is never told a folder is missing because one session's private folder went away. Before this was fixed, a reviewer session whose scratch folder had been cleaned up painted "Hub folder is missing" across every session in the hub while the hub folder was sitting right there — and its buttons offered to re-point the hub itself at the wrong place.
A removed worktree falls back — it does not alarm
Worktree-isolated sessions run inside a temporary worktree checkout, not the project folder itself. If that worktree is later removed (e.g. a background cleanup reaps a finished one), the session's saved working directory points at nothing — but the project folder is still fine. Omniscio does NOT raise the "folder is missing" banner in that case: the pre-spawn check re-resolves the working directory and falls back to the project folder (the same fallback resolveSessionWorkDir already uses everywhere else), so the session simply spawns there. The banner is reserved for when the project folder itself is genuinely gone. This is why a reaped worktree no longer mislabels your project/Hub folder as missing, and no longer loops the session in a retry storm.
When the banner DOES fire, it names the project folder that is actually gone — the very path the banner's two buttons act on — so what you read and what the buttons do can never disagree.
What counts as a missing folder at startup
The startup check reports a folder only when the filesystem says it is definitively not there — ENOENT or ENOTDIR. Anything else is treated as "could not confirm" and raises nothing: a stat that blows its two-second deadline, an unreadable share (EACCES), or any other error. Every unconfirmed path is probed a second time, so a genuinely deleted folder is still reported once the machine is answering again.
That distinction matters because the check runs on the boot path, alongside work that can hold the main thread for tens of seconds. A wall-clock deadline that fires while the loop is busy says nothing about the folder, and treating it as "missing" once reported all 95 projects — including the folder Omniscio was running from — inside one 17 ms burst, painting the red banner over every session until the user clicked through it. A filled deadline is now logged as a fired deadline rather than silently read as an answer. The same rule applies to the spawn-side check, which asks the filesystem directly and never guesses.
What to do about it
Option 1 — The folder was deleted and you want it back at the same path. Click Create empty folder…. It first asks you to confirm with a warning that says exactly what it does: it makes a brand-new EMPTY folder at the path the project stores, and it will NOT restore your existing files or code. Confirm, and Omniscio creates the folder and automatically restarts the session. The banner disappears and the session returns to normal. Use this when the folder was accidentally deleted or when you're happy to start it fresh at the original path — not when the folder merely moved, because the new folder starts out empty.
A folder saved on another computer's user folder is created in yours. A project can carry a path from your other computer — C:\Users\Kaylin\Desktop\Software Projects\Beehive on a computer whose own user folder is C:\Users\kayli — when its record came from that computer or reached it through a folder shortcut that has since gone. Windows never lets an ordinary program create a new folder directly under C:\Users, so creating it at the saved path can only fail with "permission denied". When the saved path sits inside a user folder that does not exist on this computer, Create empty folder… creates the same place inside YOUR user folder instead (C:\Users\kayli\Desktop\Software Projects\Beehive) and points the project there, so the session can start. If a folder already exists at that place in your user folder, nothing is created or re-pointed: the banner says so, and Locate moved folder… is the way to choose that folder, because pointing a project at a folder that already holds files is a choice only you make. A path inside your own user folder, on another drive, or inside a user folder that does exist here is created exactly where it was saved.
Option 2 — The drive is unmounted. Plug the external drive back in / reconnect the network share. If the folder is there again at the same path, click Create empty folder… and confirm: Omniscio finds the folder already exists, creates nothing, and just restarts — you get your existing files back untouched. If the drive came back at a different path, use Locate moved folder… instead.
Option 3 — The folder moved and you want to keep the content. Click Locate moved folder… on the banner. It opens a folder picker; point it at where the repo is now and Omniscio re-points the project (and its sessions) at that folder, then restarts the session. The same control lives in the Edit Project dialog as Move to a new folder… (Edit → More options). The stored folder path is the one project property you cannot retype in place — there is no editable path field.
While the create is in flight the Create empty folder… button shows a spinner and is disabled. If the create fails — permission denied, invalid drive letter, read-only volume — the banner shows the specific error inline in a red pill so you can react.
Automatic recovery waits for the folder
Omniscio's self-healing features cooperate with this state instead of fighting it. When crash recovery, aborted-response recovery, or the background safety net that re-drives failed sessions reaches a session whose folder is missing, it checks the folder first and simply waits — nothing is charged against any retry limit (no daily-cap attempts, no quarantine strikes, no backoff climb), because no retry can succeed until the folder is back. The first blocked attempt raises the same red banner plus a one-line note in the chat, so you know why the session is holding. The moment the folder exists again — drive plugged back in, folder restored or recreated — recovery resumes on its own. No manual retry needed.
Why it fails fast now (vs. the old silent loop)
Node's child_process.spawn() reports a missing working-directory (cwd) as "spawn cmd.exe ENOENT" — which looks identical to "couldn't find the cmd.exe binary" and doesn't mention that the cwd is the actual problem. Before this change the spawn would just fail with that cryptic message, Omniscio would retry, and the session would stay stuck without the user understanding why. The real cause was the libuv UV_ENOENT / -4058 error bubbling up from the kernel on a non-existent directory.
The fix: Omniscio pre-checks existsSync(workingDir) immediately before spawn. If the directory is missing, Omniscio writes a system message naming the path, emits a push event that the UI reacts to with the red banner, and marks the session status as error — all without ever calling spawn(). SSH sessions are exempt from this check because the working directory lives on the remote host, not the local filesystem.
Related
A session that is holding rather than failing usually has one of the other "waiting on you" causes, and session-stuck-in-needs-you.md walks through all seven. The recovery machinery that deliberately stands down while the folder is gone is described in crash-recovery.md and aborted-response-recovery.md, and it is worth reading if you want to understand why nothing is retrying. When you need to dig into what Omniscio did at spawn time, logs-and-debugging.md says where those errors land. If you would rather move the project to the folder than the folder to the project, edit-a-project.md covers changing a project's stored path.
Last verified 2026-11-20