Owlshift Owlshift

Troubleshooting

Find what you see below, run the command it names, apply the fix. The quoted lines are the ones Owlshift prints or posts; <…> stands for a value that differs on your machine.

owlshift doctor ends with ✗ Not ready

What you see. Each line of the report is marked ✓ (fine), ! (a warning, which never blocks owlshift do) or ✗ (a problem); · is information. A report with a ✗ ends with:

✗ Not ready: 1 problem to fix before `owlshift do`

and then, for each ✗ line, a block with the reason (Why) and the steps (Fix). The command that says why: owlshift doctor; run it again after each fix until it ends with ✓ Ready: nothing blocks `owlshift do`. The ✗ lines you meet first:

The sandbox line, on Linux. Every agent run is confined with bwrap, and Owlshift starts none without it.

On macOS the line is agent runs are confined with sandbox-exec; sandbox-exec cannot confine a trial run: <reason> is fixed by looking for what keeps it from running, such as a security tool or a device management profile; /usr/bin/sandbox-exec is missing is fixed by updating or reinstalling macOS.

The secrets line, on Linux and WSL2. Owlshift keeps its secrets in a Secret Service such as GNOME Keyring, as macOS keeps them in the Keychain. A server or WSL2 without a desktop session runs none. The line reads not checked: could not read the system keychain: <reason>, and the block ends with:

Fix   1) Make the system keychain available: unlock it on macOS; on Linux,
         start a Secret Service such as GNOME Keyring
      2) owlshift doctor    (to check)

The claude agent login line then fails too, with could not tell whether a token for agent runs is stored in the system keychain (service `owlshift`, account `claude-agent`): <error>: owlshift init cannot store the token without a Secret Service. Start one in your session, and unlock it, then run owlshift doctor again.

The git line. It reads <version> (<path>), older than 2.39.0. Install git 2.39.0 or later (https://git-scm.com/downloads), then check git --version: an older git may come first on the PATH.

The claude agent login line. It reads no token for agent runs in the system keychain (service `owlshift`, account `claude-agent`). Agent runs are confined and cannot reach the Keychain where your own Claude Code login lives, so they log in with a token of your subscription that Owlshift keeps. The fix block gives the two steps:

claude setup-token
owlshift init

claude setup-token prints a token; owlshift init asks for it and stores it. Your own claude login being out (your own login: not logged in) is information only: agent runs do not use it.

A claude line reading not found on the PATH means Claude Code is not installed: the fix block gives the install step.

The gate passes on your laptop and fails under owlshift gate

What you see. owlshift gate ends with a line such as:

Gate red: `<command>`: <reason>.
Gate log: <path>

while the same commands pass in your terminal. The command that says why: the Gate log line names the file that holds the whole output of the run; read it from the failing command up. owlshift gate runs the gate the way it runs on an agent's work: in a fresh worktree of your default branch, confined, with your home folder closed and nothing of your environment but what the project declares and your personal file allows. Four causes cover almost every case.

A tool is missing. The log says the command is not found. The gate sees the PATH of the shell that ran owlshift gate, and, for the background service, the PATH that owlshift start --at-login ran with. A folder of your home that the PATH names is opened to the run, read-only, unless it holds or lies in a folder the sandbox keeps closed (credentials, the temporary folders, a folder as wide as ~/.config). A version manager whose shims read other folders of your home needs those named too: declare the variable that names them in stack.gate_env, and allow it with allow_gate_env. A PATH that changed after start --at-login is taken by running it again.

A test reads your home folder. The sandbox closes your home folder to every setup, gate and agent run. A tool that reads or writes there fails with its own message: npm's EPERM and "run sudo chown", Operation not permitted, Read-only file system, or on Linux No such file or directory. When the failing command's output names a folder of your home, owlshift gate says so after the gate's result and gives the two lines that open it read-only:

The sandbox closes your home to every run and gate. The failing command was refused:
  ~/.cache/demo
A folder of your home opens to runs, read-only, once the project declares it and this machine allows it:
  in ~/src/web/owlshift.toml, under [stack]:
    caches = [".cache/demo"]
  in ~/Library/Application Support/owlshift/config.toml:
    [repositories."github.com/acme/web"]
    allow_caches = [".cache/demo"]

At a terminal it asks whether to add them; answer y and it writes both files, your personal file first, then commit owlshift.toml. Off a terminal it only prints them. Every run of the project can then read that folder: allow caches, never secrets. A folder that holds credentials (~/.ssh, ~/.config/gh and the like) is never opened, whatever the configuration. Read-only, a folder still refuses writes, so keep the tool from writing there (npm's --prefer-offline), fill it outside the sandbox, or point the tool's writable folder into $TMPDIR, the run's own folder. On Linux a write to a new path under the home does not fail: it lands in a throwaway home that the run loses. A Build whose setup fails the same way names the folders at the end of its reason, and owlshift init offers the line for each cache the project file declares that your machine does not allow yet.

npm fails with EPERM. npm says your cache folder "contains root-owned files" and suggests sudo chown. Under Owlshift that message means the sandbox, or a package missing from the cache: sudo changes nothing.

Dependencies were never installed. The gate runs in a fresh worktree, which holds no node_modules or virtual environment. List the install commands under stack.setup in owlshift.toml, from a frozen lock file, and the folders they read under stack.caches. A variable of your environment that the gate needs, such as a feature flag, goes in stack.gate_env, and your personal file allows it with allow_gate_env: credential variables are refused. owlshift gate reads the project file at origin's default branch: push your change to a branch and check it with owlshift gate --at origin/<branch> before merging it.

If a Build's gate fails the same way on the default branch, owlshift why says so (base <commit>: fails its <step> command ...) and, once it is fixed, owlshift gate --at <commit> checks it again.

A ticket does not start

What you see. You put the agent label on a ticket, or ran owlshift start, and nothing runs. The commands that say why:

owlshift status
owlshift why
owlshift why ENG-12

owlshift status says what the service does; owlshift why says, for each admitted ticket, what it waits for, and owlshift why ENG-12 gives that ticket's reasons over time, ending with now: <reason>. Both only read, and work while the service runs. The reasons, as printed:

A ticket is parked

What you see. The ticket moves to Parked (or Needs Input), and Owlshift comments on it with a title [owlshift] PARKED: Parked: <reason>., what explains it (The last failure, The run said or The forge said) and how to restart it. The reasons it can give:

The command that says why: the comment itself, then owlshift why ENG-12 and owlshift logs ENG-12. The fix: fix what the comment names, answer the questions it lists if any, then restart the ticket in either of two ways, as the comment says: reply continue on the ticket, in a comment of its own, as its decider, or run:

owlshift continue ENG-12

A parked ticket restarts at the stage it parked at; an answer alone does not restart it. When the comment says **To restart it:** run `owlshift do ENG-12` to run it again., nothing was kept and the ticket runs again from the start. A ticket parked at its budget counts its runs afresh after the restart; raise policy.ticket_budget_usd in owlshift.toml to raise every ticket's. For a park by isolation breach, see A project is quarantined or paused. Where the service serves the project, owlshift continue ENG-12 --to-watch restarts a parked ticket and returns without running it: the service drives it from its next pass.

A usage limit stopped a run

What you see. At a terminal, owlshift do ends with one of:

Stopped: the harness reached its usage limit, which resets at <time>; run again then.
Stopped: the harness reached its usage limit; run again once it resets.

Under the service, a desktop notification says <ticket>: Claude Code is at its usage limit until <time>: its runs wait until then (or ... and gave no reset time: its runs wait, and one tries it again at <time>), and daemon.log says Claude Code is at its usage limit until <time>: no step that runs it starts before then. The command that says why: owlshift why prints Claude Code: at its usage limit until <time> for each limited harness, or no harness is limited; owlshift status shows each harness's usage and reset.

The fix. A usage limit is not a failure and parks nothing: the ticket keeps its stage, nothing counts against it, and the limit holds only the runs of its own harness, on the whole machine. Under the service it resumes by itself after the reset. After a foreground run, run owlshift continue ENG-12 once the limit resets. Where the provider gave no reset time, one run tries the harness again at the deadline status names. To keep a margin of your subscription for yourself, usage_cap_percent under a harness in your personal file counts that harness as at its limit while a usage window it reports is at or above that share.

A project is quarantined or paused

What you see. owlshift status shows, under the project, one or both of:

Paused: every project of this machine, by owlshift pause at <time>: <reason>. Nothing is dispatched and no step starts; `owlshift resume` lifts it.
  paused by owlshift pause at <time>: <reason>; `owlshift resume <owner/repo>` lifts it
  quarantined: <text>; `owlshift unquarantine`, in its checkout, shows it whole and clears it

and owlshift why prints quarantine: a marker stands; every command refuses the project.

Paused. A pause is something you or the service asked for: while it stands, no ticket is dispatched and no step starts, nor a merge on green; the steps under way finish, and answers, pull requests and stages are still read. Lift it with:

owlshift resume
owlshift resume acme/web

owlshift resume lifts the machine's pause, the one owlshift pause with no project sets; owlshift resume acme/web lifts that project's own. Each lifts only its own: run the one that status names. The service pauses a project itself when its watch cannot start (; the daemon tries it again at each of its passes), and owlshift status then says why.

Quarantined. A run whose isolation check did not pass leaves a marker, and every command refuses the project until a person has looked at what the run changed. A desktop notification says <project> is quarantined: run <run> of <ticket> broke isolation (<what>). No ticket of the project runs until a person clears it with owlshift unquarantine, or <project> is quarantined: a run's isolation check did not pass or did not finish. ...; without a desktop session, owlshift status and owlshift doctor show it. Each held ticket gets a comment (Your answer counts, but Owlshift continues no ticket of this project for now, This ticket is ready, but Owlshift builds no ticket of this project for now, or This ticket's work has started, but Owlshift runs no ticket of this project for now) that says it goes on by itself once the quarantine is cleared. In the project's repository, on the machine that ran it:

owlshift unquarantine

It shows what the marker says, and clears it only once you type the project's name (owner/repo) at a terminal: it refuses to run in a script. It answers Cleared: the quarantine is gone, and the next command or watch pass works the project again., or Kept: the quarantine stands, and Owlshift still refuses the project. when the name was not typed. A ticket parked by the breach restarts as A ticket is parked says. Check what the run changed first: that is the point of the marker, and SECURITY.md says what the confinement protects.

Where the logs are