GitHub and cloud sessions

A ticket can be built somewhere else. canon sends it to your GitHub repo as an issue, a Claude cloud session builds it there on your Claude subscription (no API key), and you bring the result back and merge it on your own machine.

The cloud session does the whole sprint: it plans and waits for your approval, builds, runs the reviewer and the evaluator, closes the ticket and opens a pull request. Your machine imports the result, checks it and merges it. It grades again only in four cases: a change to the board, a Go change that needs a release (the daemon, the Go board or the headless helper), a high-risk ticket, or a pull request head that no longer equals the head the evaluator graded. The import says which apply, or that none does.

This page follows one real ticket on a small ToDo app, "Export to CSV", on canon 0.47.2: from a project with no GitHub repo, through setup and a first cloud run, to a merged pull request. The recovery section and a few troubleshooting pictures are from earlier runs on canon 0.22 to 0.31, and each caption says which.

One-time setup

Setup has three parts: make the project ready on your machine, connect GitHub to your Claude account, and create a Claude cloud environment that has canon in it.

Make the project ready

Open Factory in the sidebar, then the GitHub tab. Its Checks box lists what must be true before a ticket can be sent, with a fix command and a Copy button beside each check that fails. Here ToDo-Demo has no GitHub repository yet, and no test command.

The Factory page, GitHub tab, for the project ToDo-Demo, scrolled to the Checks box. Its title reads Checks · 1 of 3 required ready · 1 optional. Signed in to GitHub is green. No repository on GitHub yet (2.1) is red, with the fix command gh repo create "ToDo-Demo" --private and a Copy button. origin is not a GitHub repository (2.2) is red, with git remote set-url origin and the repository's address, and a Copy button. No test command (optional) (3) is amber. The account name is covered.
Factory › GitHub before setup.

The checks are:

The title counts the required checks. In our run it read 1 of 3, then 2 of 3 once the repository existed, 3 of 4 while First push was waiting, and 3 of 3 when it was done.

Run each fix command from a terminal in the project folder, then press Check again. The board's Terminal can do it: it opens a restricted prompt, and su gives you a full shell for ten minutes (check here for su setup). Copy the command from the check first, then type su, accept the operating system's prompt, and paste. On Windows 11 the Terminal needs sudo switched on in Settings and starts Git Bash in the project folder. If a pasted command shows ^[[200~ in front of it, paste again with Paste as plain text, Ctrl+Shift+V.

Create the repository first:

The board's Terminal after su, in the ToDo-Demo folder. The su banner, then gh repo create "ToDo-Demo" --private, which prints Created repository, the owner and ToDo-Demo on github.com, and the repository's address. The account name is covered.
Creating the private repository.

Press Check again. The repository check turns green and the title moves to 2 of 3. Check 2.2 stays red until origin points at the new repository.

The Checks box after the repository was created. Signed in to GitHub is green and Repository found on GitHub (2.1) is green. origin is not a GitHub repository (2.2) is still red, with its git remote set-url command. The title reads Checks · 2 of 3 required ready · 1 optional. The account name is covered.
The repository exists; origin does not point at it yet.

Run the command from 2.2 the same way (copy it, su, paste; check here for su setup), then press Check again. With origin set, the repository is still empty, so the check for the first push appears:

The Checks box after origin was set. Signed in to GitHub, Repository found, and private (2.1) and origin points at it (2.2) are green. First push (2.3) is red: The repository is empty: send your current branch so the cloud session has code to work on (it clones what origin holds). It has the command git push -u origin HEAD and a Copy button. The title reads Checks · 3 of 4 required ready · 1 optional. The account name is covered.
origin points at the repository, which is still empty.

Run the push the same way. HEAD is the branch you are on, so it sends that branch whatever it is called: in this project it is master.

The Terminal after the two commands. git remote set-url origin with the repository's address, then git push -u origin HEAD, which writes 36 objects and ends with [new branch] HEAD -> master and branch 'master' set up to track 'origin/master'. The account name is covered.
Setting origin, then the first push.

Press Check again once more.

The Checks box with every required check green: Signed in to GitHub, Repository found, and private and origin points at it. The title reads Checks · 3 of 3 required ready · 1 optional. No test command (optional) is amber, and First push is gone. Below it is the Intake box, Intake · issues become tickets. The account name is covered.
Factory › GitHub after setup.
Prefer a terminal window of your own?

Any terminal in the project folder runs the same commands, and tkt github-doctor runs the same checks.

tkt github-doctor

Push the project's agent files too, such as CLAUDE.md, AGENTS.md and PROMOTED.md: the cloud session starts from a fresh clone of the repository.

Connect GitHub to Claude

A cloud session works on your repo through Claude, not through your gh. In Claude's settings, open Connectors, then GitHub, and do both steps: connect your GitHub account, and install the Claude GitHub App on it. Claude's screen marks the app as for cloud sessions only. In our run, a session with no repository connected started, but could not read the issue.

Claude settings, Connectors, Connect GitHub to Claude: step 1 Connect your GitHub account with a Connect button, step 2 Install the Claude GitHub App, marked Cloud sessions only, with an Install on GitHub button.
Claude's GitHub connection, as it looked on 2026-10-27.

These screens belong to Claude, not to canon, and may change.

Create the cloud environment

A cloud session starts from a clean machine. An environment tells it which sites it may reach and what to install first. canon needs both: the allowed sites, and a setup script that installs canon and gives the session its reviewer and evaluator.

In Claude's session list, open the environment menu and create or edit a cloud environment. Name it canon. Open Network access. Full reaches every site and needs no list. If your organisation needs Limited, add these domains under Allowed domains, one per line, and keep Allow package managers ticked:

getcanon.dev github.com raw.githubusercontent.com objects.githubusercontent.com
The Network access page set to Limited, with the Allowed domains box holding getcanon.dev, github.com, raw.githubusercontent.com and objects.githubusercontent.com, one per line, and a ticked Allow package managers box.
Network access set to Limited, with canon's four domains.

Then open Setup script and use this script:

#!/bin/bash set -e curl -fsSL https://getcanon.dev/install.sh | bash for t in canon sprint tkt sprint-check skills.sh evidence.sh gate-snapshot.sh subagent-log.sh mutant-sweep; do printf '#!/bin/bash\nexec "$HOME/.canon/tools/%s" "$@"\n' "$t" > "/usr/local/bin/$t" chmod +x "/usr/local/bin/$t" done mkdir -p "$HOME/.claude/agents" cp "$HOME/.canon/current/agents/canon-reviewer.md" "$HOME/.canon/current/agents/canon-evaluator.md" "$HOME/.claude/agents/" \ || echo "setup: could not copy canon gate agents from $HOME/.canon/current/agents" >&2 git config --global user.name >/dev/null || git config --global user.name "canon cloud session" git config --global user.email >/dev/null || git config --global user.email "noreply@getcanon.dev"
  1. Copy the script above. Either paste it into the Setup script form, or save it as a file and use Choose file (files up to 64 KB).
  2. Add your own install lines after the first line if your project needs them, such as npm install. Leave the rest as it is.
  3. Save changes, and make this environment your default. A session started from your terminal uses the default.
The Edit cloud environment dialog for an environment named ToDo, with rows for Network access, Network secrets, Setup script (Not set), and Environment variables, and Cancel and Save changes buttons.
The environment dialog.
The Setup script form in Bash with Choose file and a copy button, showing the default two lines, a shebang and npm install; below it Files up to 64 KB and a note that the script runs when a new session is started, before Claude Code launches.
The Setup script form, before the script is pasted.

The script runs before Claude starts. A session picks up an environment only when it starts, so changes to an environment reach new sessions, not one that is already running: archive the old session and start another. If the setup script is missing, the session has no sprint or tkt.

A Go project needs a longer script and four more domains. The Cloud environment box on Factory › GitHub has the exact recipe for the project you are in, with Copy domains and Copy setup script buttons.

Prefer the terminal?

tkt cloud-env prints canon's own recipe: the domains first, under a # Network access comment, then the script under # Setup script. Paste only the lines below # Setup script into the form. It is the recipe for the canon you have installed, so if it differs from the script above, use the one it prints.

tkt cloud-env

Ticket to issue

Create the ticket as usual with + New. This one, "Export to CSV", has only a problem and an outcome. It has no acceptance criteria and no plan, and that is allowed: the cloud session then drafts both and stops for your approval, as the Send panel's warning says.

The New Ticket form over the ToDo-Demo board. The title reads Export to CSV. Type Feature and priority P2 are selected; CI, Eval-only and Lite are not. The description holds a Problem, No way to export Todos to CSV file, and an Outcome, A CSV file is created with the list of Todos.
The new ticket: a problem and an outcome.
The ToDo-Demo board with the new ticket t-zm4p, Export to CSV, in the Open lane. The card is a feature, P2, marked needs acc, with a Start button. The Done lane holds Create a Todo app.
The card: needs acc, because there are no acceptance criteria yet.

Press ▶ Start. The session opens with a Worktree box, and one of its choices is GitHub · new issue.

The t-zm4p session before it starts: a Run sprint button above a terminal that says to press Run sprint to launch an interactive agent session, and a Worktree box with three choices. Main checkout (current) is selected, GitHub · new issue is described as A Cloud Agent works it, and + New offers the branch name sprint/t-zm4p.
The Worktree box: GitHub · new issue.

Choose GitHub · new issue. The Send panel shows the issue exactly as it will be created and sends nothing until you press Create issue. At the top it warns about what the cloud will not see: uncommitted files, and here the missing acceptance criteria and plan.

The cloud works from GitHub, not from your machine, so it sees only what is on origin. The panel splits the send in two. Create issue stays greyed out while a tracked file has uncommitted changes, until you either commit and push them in step 1 or tick Send without these changes (the cloud will not see them).

The Send t-zm4p to GitHub panel. An amber warning has three lines: the first, with the project folder's path, says 2 file(s) have uncommitted or untracked changes and that the cloud session will not see them; t-zm4p has no acceptance criteria: the session will draft them and wait for your approval; and t-zm4p has no plan (plan.md ## Approach is empty): the session will draft it and wait for your approval. Step 1 is Commit and push, with a Commit and push button. Below is the issue as it will be created: the repository, with the owner covered, ToDo-Demo (PRIVATE), the title t-zm4p: Export to CSV, the label canon and the body. The checkbox Send without these changes is unticked and the Create issue button in step 2 is greyed out.
The Send panel: Create issue waits for step 1.

Commit and push… lists the files that changed. Changed tracked files start ticked, except a file written in the last five minutes, which starts unticked and is marked with its age, and every file while an agent session is working in the project, since those may be its work in progress. New files that git does not track yet start unticked, and nothing new is added unless you tick it. You can edit the commit message.

The Commit and push form open in the Send panel. The branch line reads master -> origin/master (0 commit(s) to push). AGENTS.md and HANDOFF.md are ticked and marked changed. A note says this ticket's own files go in the issue below (Description, Acceptance, Plan, Research), and the cloud session rebuilds .tickets/t-zm4p/ from it, so they are not committed here unless your project tracks them in git. The commit message is chore: t-zm4p work for the cloud session.
Tracked changes ticked.

A confirmation says what it will do: commit the ticked files on master, then push master to origin, never forced.

The confirmation dialog Commit and push t-zm4p?. It says it commits 2 file(s) on master, then pushes master to origin, never forced, lists AGENTS.md and HANDOFF.md and the commit message, and has Commit and push and Cancel buttons.
The confirmation.

After the push the amber warning keeps only the lines about the missing acceptance criteria and plan, and the two steps give way to the issue and the Create issue button, now enabled.

The Send panel after the push. The warning now has two lines, no acceptance criteria and no plan. The issue is shown with the repository, title, label and body, where Acceptance reads (none yet) and the Plan section begins. The Create issue button below it is enabled.
After the push.

If you tick the checkbox instead, Create issue is enabled at once and the cloud works from origin as it is.

Prefer the terminal?

tkt send-issue <id> --dry-run prints the same text and creates nothing. Without --dry-run it creates the issue, adds the canon label and records the issue in the github: line of ticket.md. Commits that are on no branch of origin are refused; push first, or add --allow-unpushed in a terminal.

tkt send-issue t-0igh --dry-run tkt send-issue t-0igh

A ticket with no acceptance criteria or plan shows (none yet) for them. The picture is from an earlier run, on canon 0.31.0, with ticket t-0igh.

A Cockpit terminal after tkt send-issue --dry-run on a ticket with no plan yet: the Description, then Acceptance, Plan and Research each reading (none yet), the Working on this steps, and the last line, dry run: nothing was created.
A dry run for a ticket with no plan (canon 0.31.0).

canon refuses to send a ticket to a public repository unless you add --public (tkt send-issue <id> --public), because anyone could read the issue.

Press Create issue. The panel then says the ticket was sent as issue #1 and gives you the prompt to start the cloud session with. It says the card moved to In progress and explains three buttons: To Claude Cloud, Copy command, which copies the same prompt as a claude --cloud command for a terminal you open yourself, and Copy prompt, which copies the text for claude.ai/code.

The panel after sending: Sent t-zm4p as issue #1. It says to start a Claude cloud session on the canon environment and type the prompt, shows the prompt, says the card moved to In progress and shows the next step, and explains the buttons To Claude Cloud, Copy command and Copy prompt.
Sent: the prompt, and the ways to start the session.

The prompt is one line. It points the session at the issue rather than repeating the ticket:

Work on Issue#1 for ticket t-zm4p. Read its section "Working on this" thoroughly before starting and follow it step by step. Work on a new branch, never main.

On GitHub the issue carries the canon label, the ticket's description, and (none yet) where the acceptance criteria, the plan and the research would be.

The issue page on GitHub: t-zm4p: Export to CSV, number 1, open. The body shows t-zm4p · feature · P2 · Export to CSV, then the Description with the Problem and the Outcome, then Acceptance, Plan and Research each reading (none yet), and the start of Working on this. The label canon is in the sidebar. The author's name and avatar are covered.
The issue on GitHub.

Further down is a section called Working on this, which tells the session what to do, in order: import the issue, draft and get approval for the plan, work on a new branch, build and test, run sprint complete, run tkt export, and stop. If a step cannot be done it says to say so in the pull request.

The issue's Working on this section: seven numbered steps. Run sprint import-issue first. Plan with canon's own approval, not plan mode, and wait for the user's approval of the plan before editing anything else. Work on a new branch, never main, push it and open a PR with Fixes #<this issue number>. Build it and run the tests. Run sprint complete, which dispatches a fresh reviewer and a fresh evaluator. Run tkt export t-zm4p, commit .tickets/t-zm4p/ on the PR branch and push it, and say in the PR which step failed and why if sprint complete could not pass. Then stop, not merging, and reply with tkt import-results t-zm4p --pr and tkt merge-pr t-zm4p, with the PR number filled in. A last line says to say so in the PR description if a step cannot be done.
The steps the cloud session follows.

To Claude Cloud starts the session from tkt send-issue <id> --launch. On macOS and Linux it opens the board's Terminal with that command already typed; press Enter and answer y when it asks whether to start a cloud session. On Windows the button copies the line instead, and the panel says what to do with it.

The Sent panel after To Claude Cloud was pressed on Windows. Below the buttons it says: Copied. Windows: open PowerShell or Git Bash in C:\Users\agentops\Documents\ToDo-Demo (the project's root folder, the one with .tickets/), paste, and press Enter. The board's Terminal cannot start a cloud session on Windows yet. Close this panel once you have run the command. The sidebar shows a Cloud group with t-zm4p.
On Windows the button copies the command.

That note about the board's Terminal was out of date in our run: after su and the operating system's prompt, the same command ran in the board's Terminal, and canon's release notes list that under t-353a. Paste it with Ctrl+Shift+V, press Enter, and answer y when it asks whether to start a cloud session. It prints the prompt, the claude --cloud command, the session's name and a link to open it.

The board's Terminal after su: tkt send-issue t-zm4p --launch said t-zm4p was already sent as the account's ToDo-Demo#1, asked Start a Claude cloud session on it? Nothing new is created. [y/N], took y, then printed the prompt and the claude --cloud command, then Created cloud session: Issue #1 t-zm4p, a View link and Resume with claude --teleport. The account name and the session identifiers are covered.
Starting the cloud session.

The claude --teleport line comes from Claude's command line, not from canon. Do not use it for this flow: the point is that the cloud builds and grades and your machine only imports, checks and merges.

While the session works, the card shows a GitHub #1 · cloud session wo… badge, the sidebar has a Cloud group, and pointing at its row says what it is doing. The card's Issue ↗ button opens the issue on GitHub.

The ToDo-Demo board while the cloud session works. The t-zm4p card in the In progress lane has a badge reading GitHub #1 · cloud session wo…, a take back link, needs acc and an Issue ↗ button. The sidebar has a Cloud group with t-zm4p at 4m, and a tooltip reading Export to CSV · GitHub issue #1 · working on GitHub.
The card while the cloud works.

In the cloud

The session opens on claude.ai/code with the prompt as its first message. It reads the issue and runs sprint import-issue 1, which rebuilds the ticket in the clone from the issue's sections. Because there were no criteria or plan, it drafts both in acceptance.md and plan.md and stops for your approval. It works on its own branch and has not touched your code. In our run a hook then re-prompted the session, which committed the imported ticket files and pushed them to its branch before you approved; it reported that the commit held only the drafted acceptance and plan, and that index.html was unchanged.

A Claude cloud session on Issue #1 t-zm4p. It lists what it did: sprint import-issue 1 rebuilt .tickets/t-zm4p/ and started the sprint, it drafted acceptance.md and plan.md, and it is on the branch claude/issue-1-t-zm4p-c9xweo, with nothing committed or pushed yet. The plan adds an Export CSV button to index.html that builds todos.csv with the columns text,completed, with proper quoting and CRLF line endings, prefixes values starting with =, +, - or @ with a ', and gives a header-only file for an empty list. It rates the risk as tier normal and notes there is no scripts/test.sh. It asks the user to reply approved or send changes. After a line reading Hook re-prompted Claude, ran a command, it says it committed the imported ticket files and pushed them to the branch, that no PR is open yet, and that it is still waiting for approval.
The cloud session stops at its plan.

Read the plan, answer its questions and approve it by replying in the session. Do not switch the session to Claude Code's plan mode: a session that planned in plan mode has passed its plan to the reviewer and evaluator, which then cannot run.

The cloud session after the reply approved, go ahead with the implementation. It ran 2 commands, said Now implement., ran python3, and said Test: unit-check the CSV builder in node, then a real download in Playwright.
The reply, and the build starting.

The session builds the change, tests it, runs sprint complete and closes the ticket. It opens a pull request with Fixes #1, runs tkt export t-zm4p and stops. It does not merge, and it does not watch the pull request: the merge happens on your machine. It ends with the two commands to run, with the pull request number filled in.

The end of the cloud session. It says it built the CSV export and opened PR #2 (Fixes #1), that the sprint closed with a reviewer YES and an evaluator pass, and that it did not merge the PR or act on CI or review comments. The Export CSV button in index.html downloads todos.csv with text,completed columns, cells starting with =, +, - or @ get a ' prefix, and an empty list gives a header-only file. Bullets cover Testing (no scripts/test.sh, so the commit-time test gate never ran), Skipped gates (mutation-test, doc-audit and skill-eval, with reasons recorded in .tickets/t-zm4p/acceptance.md), the UTF-8 BOM, and a Reviewer note about a headless Chrome process. It ends with Run these on your machine: tkt import-results t-zm4p --pr 2 and tkt merge-pr t-zm4p.
The session's report.

The pull request description says the same. It lists the canon steps that ran, and it names any step that was skipped or ran as a fallback: an earlier run reported that canon's reviewer and evaluator agents were not loaded in the cloud session, so both gates ran as fallbacks, and said so there. Check the description for the same note on your own runs.

The pull request on GitHub, still open: number 2, t-zm4p: Export to CSV, wants to merge 6 commits into master from claude/issue-1-t-zm4p-c9xweo. The description starts with Fixes #1, says it adds an "Export CSV" button to index.html that downloads todos.csv (text,completed, RFC 4180 quoting, CRLF, UTF-8 BOM), and under Canon steps lists import-issue, plan approved (sprint approve), implement, reviewer (YES), evaluator (pass), sprint complete (closed) and tkt export t-zm4p, with All ran; none skipped. The tabs show Commits 6, Checks 0 and Files changed 9, with +202 -4. The account name and avatar are covered.
The pull request, before the merge.

Back home

When the session has pushed, the sidebar's cloud row shows a Results badge and the ticket's card shows a "GitHub #1 · results ready" badge and an Import results button.

The board when the results are ready. The t-zm4p card shows a GitHub #1 · results ready badge, take back, needs acc and an Import results button, with the tooltip Bring the cloud session's results back into this ticket. The sidebar's cloud row shows a Results badge.
The card when the results are ready.

Import results brings the ticket back: every file as the cloud wrote it, any local file that differed kept in .tickets/<id>/.before-import/ (which git ignores), and a report of the ticket's status, the evaluator's verdict and the head it graded. A project that commits .tickets/ gets the results with the pull request; otherwise they travel on a branch called canon-results/<id>. An import whose pull request head is not the graded head is refused, and the trail says so.

The import's result dialog over the board: Results are back in .tickets/t-zm4p/, and Next: Check & merge on the card. The log says evaluator: pass with its graded head, that PR #2's head is graded-head plus late docs only and names acceptance.md, eval-report.md, evidence/cloud/machine.log, summary.md, ticket.md and HANDOFF.md, that no re-grade is needed (tkt merge-pr, no rebase), that it was read from PR #2's head because a tracked .tickets/t-zm4p/ rides in the PR, and to add its LEARNINGS.md row locally if it wrote learnings.md.
The import: no re-grade needed.

The card then reads "GitHub #1 · results in" and shows Check & merge.

The board after the import: the t-zm4p card in the Done lane with a GitHub #1 · results in badge, a take back link, ready, and a Check & merge button. The sidebar's cloud row shows a Merge badge.
Results in: Check & merge is next.

The ticket now records where it ran. Open it on the board and choose Machines in its tree: the table lists the machines that wrote to the ticket, taken from its events (each names the host that wrote it) and from its test-evidence logs (they name the OS, never the host). After a cloud run it has two rows, yours and cloud.

The closed ticket t-zm4p open on the board, on its Machines entry. A table with three columns, headed Machine, "OS, ARCHITECTURE, CORES, RAM" and Activity, has two rows. SJ-VM-WIN11, local, runs Windows 11 10.0.26200 with 4 cores and 6 GB, 4 events, last Nov 6, 2026, 2:34 PM. cloud, cloud session, runs Ubuntu 24.04.5 LTS, Linux 6.18.44-fc-v242, 4 cores and 16 GB, 1 evidence log, last Nov 6, 2026, 2:45 PM. A note says the table comes from the ticket's events and its test-evidence logs.
The Machines entry: where the ticket's work ran.

Check & merge first runs the checks that run none of the pull request's code. It tells you whether the pull request's head is the head the evaluator graded, or that head plus files that are safe to arrive late: the ticket's own folder, LEARNINGS rows, HANDOFF.md when canon's own Recent activity block is all that changed in it, and lines added to the audit log .claude/subagent-runs.jsonl (the log may only grow). It shows what the pull request changes, and says what it will do. Nothing from the pull request runs until you press the button, which reads Merge (no tests) when the project has no test command.

The Check & merge PR #2 dialog over the board. Running the tests runs the PR's code on this machine, and nothing from the PR runs before you press the button. The log says the PR head is graded-head plus late docs only and lists the files, then PR #2 with the owner covered: 9 files changed, 202 insertions(+), 4 deletions(-), then merge-pr: ready: no test command (pass --test); would merge PR #2 on the gates alone (closes #1). The buttons are Merge (no tests) and Cancel.
Check & merge, before anything runs.

A cloud pull request can open as a draft, and GitHub will not merge a draft. When it is one, Check & merge stops within seconds and offers Mark ready (tkt pr-ready <id>); press it and run Check & merge again. Here the pull request was not a draft.

While it runs, the dialog shows the log and a Stop button.

The dialog while Check & merge runs: Checking & merging t-zm4p and Running… 0m16s. The log repeats the check, then says No test command (pass --test). Merge PR #2 into master on the gates alone? yes (--yes), and Merged PR #2 into master, with the merge commit. The owner in the repository line is covered. The only button is Stop.
Merging.

When it has merged, the dialog says so. GitHub closes issue #1 through the pull request's Fixes #1 line, and canon tries to move your local master forward to the merge commit.

The Merged dialog: The PR is merged and the issue closed by its Fixes line. Local master: 1 file(s) here differ from the merged copy; left at 16f76873: HANDOFF.md, then Commit or move them, then run: git pull (in the Cockpit Terminal, type su first). The log repeats the check, then Merged PR #2 into master with the merge commit, a warning that LF will be replaced by CRLF in HANDOFF.md, the same Local master line, and issue #1 was already closed. The owner in the repository line is covered.
Merged. Local master was left where it was.

canon moves local master forward itself. The usual thing that stops it is a file it would overwrite that differs from the merged copy (a staged file, a branch checked out in another worktree and a git refusal stop it too). These do not stop it: a file identical to the merged copy, the ticket's own ticket.md where it differs only in canon's local fields, local lines in the audit log, and a HANDOFF.md whose only local change is canon's own Recent activity block. In our run HANDOFF.md also held three lines under ## Scratch that canon had written after our Terminal sessions, so canon stopped, named the file and left master at the commit it was on. The merge on GitHub had already happened.

Compare the file before you move anything. In the Terminal, after su, git fetch and then git diff origin/master -- HANDOFF.md show what differs. Here every differing line was one canon had written itself: its Recent activity block and the Scratch lines. See Troubleshooting for what comes next.

The board after the merge: the t-zm4p card in the Done lane with no GitHub badge, marked ready, next to Create a Todo app. The sidebar's Agents list reads No agents running.
The card after the merge.

In canon 0.31.0 the ticket's GitHub tab kept the trail: each send, launch, import and merge appended a dated entry to .tickets/<id>/github.md. In that run the file was not committed, so after the folder was lost the trail started at the import.

The ticket's GitHub tab, read-only, with two entries: imported, which reports 7 files, ticket status closed, evaluator pass, the graded head and that the PR head is graded-head plus late docs only, and merged, which gives PR 4, the merge commit and base main.
The ticket's GitHub tab (canon 0.31.0).
Prefer the terminal?

The same steps as commands. tkt merge-pr needs su first in the board's Terminal.

tkt github-status t-zm4p tkt import-results t-zm4p --pr 2 tkt merge-pr t-zm4p

On GitHub, issue #1 is closed with the canon label, and its pull request is linked.

The closed issue on GitHub: t-zm4p: Export to CSV, number 1, with a purple Closed badge and a link to pull request #2, and the label canon in the sidebar. The body shows the Description with the Problem and the Outcome. The author's name and avatar are covered.
The issue, closed by the merge.

Once your local master has the merge, the app has the feature. An "Export CSV" button under the list downloads todos.csv, with the columns text and completed.

The ToDo app after the merge, with two todos: Testing sprint workflow, ticked, and Testing GitHub pipeline. An Export CSV button sits under the list. Below it, an editor shows the downloaded todos.csv in the Downloads folder: the header text,completed and the rows Testing sprint workflow,true and Testing GitHub pipeline,false.
The merged feature, and the file it exports.

If your project folder is gone

The cloud works from GitHub, so losing your copy does not lose the work. In an earlier run (canon 0.31.0, ticket t-0igh, issue #3, pull request #4) the project folder was lost while the cloud session was waiting for approval. The issue still held the ticket's text, and GitHub still knew the pull request, so the way back was:

  1. Clone the repository to a new folder, for example gh repo clone <owner>/<repo> <folder>, and add that folder with + Add Project.
  2. In the new project's Terminal, run tkt import-issue 3. It rebuilds the ticket from the issue and links it to the issue.
  3. Run tkt github-status t-0igh. It reports where the ticket stands, here that the results were ready on pull request 4, and gives the tkt import-results command to run.
  4. Run tkt import-results t-0igh --pr 4, then merge.
The ToDo-App board of the new clone, with the two tickets that had been committed in the Done lane and none of the lost ticket.
The recovered project: the lost ticket is not there yet.
A Cockpit terminal after tkt import-issue 3, which says it rebuilt .tickets/t-0igh from issue 3, and tkt github-status t-0igh, which reports the issue, the stage results-ready, PR 4 open with its head commit, and that PR 4 carries the closed ticket, with the tkt import-results command to run.
Rebuilt from the issue, and found on GitHub.

A ticket rebuilt this way is not marked as out on GitHub, so the card shows an ordinary ticket, even after the import, and offers no Check & merge. This is how canon 0.31.0 behaved in our run, and newer releases may differ. The way to the merge is the terminal: tkt merge-pr <id>.

The board after the import of the recovered ticket: Add time to ToDos is in the Done lane, marked ready, with no GitHub badge and no Check & merge button.
A recovered ticket: no badge, no Check & merge.

Issues to tickets

The header button GitHub Sync turns open issues labelled canon into tickets (tkt sync-issues). It stays greyed out until the checks on Factory › GitHub pass. It opens a preview table with an index, the issue, a reason and a checkbox for each issue. Issues it would create start ticked; the others are disabled, with the reason. Create tickets creates only the ticked ones. Factory › GitHub's Intake box shows the issues waiting and when the project last synced.

When a cloud sprint cannot close

If the gates cannot run in the cloud (plan mode, or a QA item that needs your machine), the session opens the pull request, exports without closing and stops. Import brings the ticket back open, with cloud_status: in_progress recording what the cloud left.

Close it from the pull request's head: tkt land <id>, or Continue here on the card, makes a worktree at the head and starts the ticket there. Run a fresh evaluator and sprint complete in it, then Finish (tkt land <id> --finish) removes the worktree. When Check & merge fails because the suite fails on your machine, Fix here (tkt land <id> --fix) makes the worktree even though the cloud's verdict passed.

A fix pushed to the pull request after grading needs the evaluator again: merge-pr merges only the graded head. When the pull request holds a change the evaluator never graded, the import says so and asks for the same thing.

An import dialog titled Imported, but the cloud sprint did not close. It says there is no passing evaluator verdict on the PR's head, so there is nothing to merge yet, and to finish the close on this machine with tkt land. The output shows status closed, evaluator pass and its graded head, says the PR head does not match it because the evaluator graded other code, and that a re-grade is needed on this Mac.
An import that needs a re-grade, from canon 0.26.0.

Troubleshooting

A Claude cloud session that cannot start: it says it cannot read the Working on this section of issue 1 because GitHub access to that repo is not enabled for this session, that gh issue view and gh api both returned 403 saying to use add_repo, and offers three ways to proceed. The panel on the right shows the environment as Default, Not connected, and Add repository. The repository name is covered.
A session with no repository connected (canon 0.22, the first run).
The board's Terminal after tkt github-status t-yx0o, which prints the ticket, its issue, the stage pr-open, and PR 2 open with its head commit.
Where a ticket stands on GitHub (canon 0.23.0, the first run).
The board's Terminal after tkt land t-yx0o: land: t-yx0o is closed, not open; import its results first (tkt import-results t-yx0o).
tkt land on a ticket whose results are not in (canon 0.26.0).