Working in this repository

This is the product. Clawdline is a Go daemon plus a React console, built for macOS, Linux and Windows. The daemon owns port 7727 on this machine. README.md says what it is for; docs/ says how each part was decided. This page holds the rules; docs/working-rules.md holds the incidents and procedures behind them — read its section when you reach the thing it covers.

The retired Swift app

The Swift app stopped on 2026-09-19 and was archived on 2026-09-22; keep its archive read-only and its file-and-line citations intact (see docs/working-rules.md), and let TestNothingSaysTheRetiredAppIsStillRunning guard against claims that it still runs.

Where work happens

The branch is main (it was master until 2026-09-22). Work lands through a disposable worktree, never in the shared checkout:

git worktree add -f <scratch>/<name> HEAD

• A root integrates by merging the child's branch, not by applying its patch, and records the landing as soon as it lands. A branch cut before 2026-09-22 can only be cherry-picked (docs/working-rules.md).
• After recording a landing, run tools/check-worktrees.sh (a dry run: 0 nothing owed, 1 landed residue, 2 could not check, 3 unknown). Inspect it, then run --apply for every proved landed_clean checkout. Remove a root-owned task worktree after its commit is on main, its checkout is clean, and no owner is using it. Never use age or ancestry alone to delete an unknown, active, dirty, or unlanded checkout. In every delivery, tell the person how many worktrees were removed and which candidates were kept, with their reasons. For a read-only throwaway checkout use tools/check-worktrees.sh --ephemeral -- <command>. docs/worktrees.md.
• A dispatched child's worktree path comes from the task record (GET /v1/orchestrator/tasks/<id> → .task.worktree.path), never composed. cd "$W" || exit 1 — a failed cd runs everything else somewhere else.

Choose performance work by user impact

Prioritize current user failures or blocked interactions, then frequently used operations with measurable real-world waiting time. Rank candidates using observed usage frequency, absolute time that can actually be removed from the user's critical path, and the severity of the current impact. Summed request durations can overlap or belong to background work; they are not automatically time a person can save.

A large percentage on an already imperceptibly fast operation is not a reason to optimize it. Microbenchmarks locate costs; they do not establish product priority or user benefit. Before retaining a change, record the affected action, observed frequency, absolute end-to-end baseline and expected saving, supporting evidence, correctness risk and maintenance cost. Compare repeated measurements under the same conditions. If the benefit is only a microbenchmark, inside noise, or unproved on the affected action, defer or revert it rather than sell a percentage. Resource savings can justify work when they demonstrably relieve current contention, cost or a capacity limit; state that effect instead of implying a latency improvement.

See the local API review for the baseline, rejected attempts and the next observability priorities.

Before anything is committed

The workflow targets ten seconds during development and one minute for an ordinary local commit. Run the smallest relevant package/test while editing with tools/check.sh --quick ./package --run=TestName. This is never an integration receipt.

tools/check.sh is the local commit gate. It runs directly edited or paired Go test modules (whole-package fallback), affected console tests, incremental whole-project type checking, changed-file privacy and repository guards. --plan explains the direct scope, module selectors, guard triggers and transitive callers; --callers also compiles those callers' tests. Caller runtime suites, cross-platform builds/vet, complete suites and bundles run in background CI after integration. They do not block a local commit, landing on main or a dev installation. A public Release requires complete verification of its exact tree and release acceptance. Dev installation builds the selected commit, then checks the running version, console and existing Sessions; a failed startup rolls back. Report pending or failed CI explicitly and fix failures. Unknown/tooling/policy inputs and unreliable scope discovery conservatively select full checks when requesting a local check, but are not a dev-install prerequisite. Platform inputs remain named in the plan; foreign-platform validation belongs to CI and the Release gate.

Every selected check must be green; unknown is not a pass. tools/check.sh --full runs every check below, once inside tools/heavy.sh, and prints individual outcomes and elapsed times. --full --profile retains uncached Go timing evidence. Keep new checks in that script too. See docs/checks.md for coverage, timing, fallback and cache ownership semantics.

gofmt -l internal cmd          # silent
tools/heavy.sh go vet ./...
tools/heavy.sh go build ./...
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 tools/heavy.sh go build -o /dev/null ./cmd/clawdline
GOOS=windows GOARCH=amd64 CGO_ENABLED=0 tools/heavy.sh go build -o /dev/null ./cmd/clawdline
GOOS=windows tools/heavy.sh go vet ./...      # the Windows-only files, and every test, as Windows compiles them
tools/heavy.sh go test ./...
tools/heavy.sh go test -count=1 ./internal/config # uncached repository copy guards
go run ./tools/contract-gen -check      # Go and TypeScript are generated together
tools/check-legacy-css.sh               # the pinned CSS copies still match; legacy JS is owned code
node web/console/tools/check-rounded-side-borders.mjs # no rounded surfaces with accent side borders
tools/check-machine-words.sh            # no shown sentence calls the machine a Mac
tools/heavy.sh bash tools/test-machine-words-changes.sh # delta scanning includes new files and preserves failures
tools/heavy.sh bash tools/test-heavy-handoff.sh # capability discovery accepts help exit statuses
tools/check-shell-expansions.sh         # no $name runs into a non-ASCII character
tools/check-private.sh                  # nothing of the person's is in a public repo
node tools/check-console-tests.mjs      # every console test file is run by npm test or npm run check
node tools/check-mirror-tests.mjs       # no console test asserts on the shape of the code
tools/heavy.sh node --test tools/check-plan.test.mjs tools/check-profile.test.mjs tools/check-scope.test.mjs
tools/heavy.sh bash tools/test-check-modes.sh # entrypoint scope, fallback and failure propagation
tools/heavy.sh bash tools/release/supply-chain.test.sh # release evidence fails on what it exists to catch
tools/heavy.sh sh tools/test-shell-pairing-permission.sh # macOS only: a pairing's code waits for its saved permission
tools/heavy.sh bash tools/test-linux-dev-build.sh # Linux only: dev skips full checks; ordinary builds preserve failures
tools/heavy.sh bash tools/test-heavy-linux-cache.sh # Linux only: cache ownership, retention and pressure cleanup
( cd web && npm run check && ../tools/heavy.sh npm run build && ../tools/heavy.sh npm test )   # when anything under web/ changed

• Only application builds and native compilation queue through tools/heavy.sh (clawdline heavy). Go/Swift tests, Python, frontend bundles, type checks and ordinary checks run directly; CPU usage alone never requires a queue. For opaque native build scripts use tools/heavy.sh --compile <command>. Do not wrap a whole check/test script as compilation. Wait for queued native builds with one long wait. If it exits 75 before acquiring the slot, run it later. A queued tools/check.sh hands itself to a callback and exits 76: a root ends its turn and waits for the notice; a child waits in place. See docs/working-rules.md for the incident and procedure.
• After compilation, remove the cache you created for that build once its commands have exited and no other process uses it. Confirm the exact path belongs to this task before removing it. The persistent Linux heavy-wrapper cache follows its registered budget; per-worktree TypeScript build information is reclaimed with the checkout. Neither follows per-command Session cleanup. Do not clear the default shared Go cache, another Session's cache, or a broker-managed gate cache as routine post-build cleanup. See docs/disk-lifecycle.md for ownership and shared-cache rules.
• A test that needs a Unix facility asks for it through a per-platform file (gone_unix_test.go beside gone_other_test.go), not through syscall inline.
• A new bound — a limit, a cache size, a number of rows — must be registered in internal/domain/capacity; TestEveryBoundIsRegistered fails otherwise. Drive the guard red before you make it green, and keep the output that proves it went red.
• When slow sends, long loading, pending messages that never clear or lost events recur, do not only add a timeout or a spinner: trace the whole capacity and protocol path — queue and concurrency limits, backpressure, synchronous external dependencies, retry amplification, idempotency and receipts, SSE resume, stale snapshots, failure isolation — and tell apart accepted, executed, delivered, observed and acknowledged. The fix carries typed errors and failure-injection tests.

This repository is public

Nothing of the person's may appear in it: no names of their businesses, no tokens, no paths into their accounts, no content from their conversations. tools/check-private.sh without its word list answers 3, undetermined, not 0. Automatic checks read the working tree only; historical scans are manual audits for an initial publication or an intentional history rewrite. A history finding names the commit, file and line, never the matched text. docs/privacy-guard.md is the whole of it.

Commit messages, comments and documentation are in English; the conversation with the person is in Traditional Chinese.

Keep filesystem searches inside the task's scope

On macOS, a command started through Clawdline can make a privacy prompt name Clawdline even when the command itself is the reader. Search the named repository or task directory, not the whole home directory. Do not recursively enumerate ~, ~/Library, ~/Documents, ~/Downloads, ~/Music, or the Photos library to discover files for a repository task. Open a protected location only when the task actually requires it and its exact path is known. The observed attribution and the permission prompts it caused are in docs/working-rules.md.

Maintaining product translations

When changing product-generated, person-facing copy, update English and Taiwan Traditional Chinese in the same change. Other shipped languages may be translated in batches; do not require their files to change with every code edit. A missing newer translation falls back to English and is counted in the localization coverage report. Keep placeholders, plural forms, and markup valid in every existing translation. An outdated translated guide section falls back to its current English section so it cannot show obsolete commands. The first multilingual release requires a complete baseline in every shipped language; later routine changes use the two-language gate. The resolver, fallback and release checks are in docs/localization.md.

How a commit reads here

The subject is a sentence about what changed for a person, not a category: A tmux that escapes the separator is a listing, not an empty machine. The body says what was measured, what the machine said that contradicted the first guess, and what was deliberately left undone. Numbers come from a run, not from memory.

How every delivery report ends

When a root Session has finished and verified a turn, including any required commit, run clawdline session report --summary "One concrete sentence about what was delivered." as the last action before the final answer. Confirm that the command succeeded; the final answer and the status lines below do not create the Session delivery receipt. If the command is refused, say that the Session status was not updated and give the refusal reason. Do not report a turn that is unfinished, only diagnostic, blocked, or waiting for the person, and never report a child's turn. Read clawdline guide for the current command and receipt semantics before using it.

The final response for every task ends with exactly five unbulleted status paragraphs in this order: GitHub, app.clawdline.com, this machine's dev install, public Release, and clawdline.com. Put each item on its own line with a blank line between items so Markdown renders five separate rows, never one wrapped paragraph. Start each with its emoji. Add no text, heading, code fence, or other content after the five items. Choose each status independently for this delivery; a newer commit in one place does not establish the state of another place. Use these meanings:

• ✅ — the required action is complete and its destination has been verified.
• ➖ — this delivery requires no action at that destination. Say why briefly; do not use this merely because the action has not been attempted.
• 🕰️ — an action is required or underway, or its required verification is still pending.
• ❔ — the evidence needed to decide is unavailable. Name what could not be checked.

Use these line labels and concise, specific details, including a commit or version when relevant:

✅ GitHub：<本次 commit 已在 origin/main；或寫明待推送／無需變更／無法確認>

✅ app.clawdline.com：<已上線並驗證；或寫明待部署／不需更新／無法確認>

✅ 這台 Mac 的 dev：<正在運行哪個 dev commit；或寫明待安裝／不需更新／無法確認>

✅ Release：<已發布哪個公開版本及其 commit；或寫明待發版／暫不需發版／無法確認>

✅ clawdline.com：<官網已更新並驗證；或寫明待更新／不需更新／無法確認>

Replace each example ✅ with the emoji warranted by that line's evidence. For GitHub, ✅ requires this delivery's commit to be reachable from current origin/main; a local commit, an unpushed merge, or a pending/rejected push is 🕰️. For app.clawdline.com, ✅ requires the production BUILD.json to name the delivered commit or a descendant and the served main bundle to pass the CloudGate check in docs/hosted-console.md. A queued build, preview deployment, stale stamp, or skipped online check is 🕰️ when a deployment is required. An unrelated change that does not need a hosted-console deployment is ➖.

For this Mac's dev install, compare the intended dev commit with the version actually running on this machine, not just a built or installed artifact; see docs/updates.md. Use ➖ when this delivery does not call for a dev install, including after a deliberate return to the stable release. For Release, compare the intended public version and commit with the published signed release, not with the hosted console's stamp; see docs/releasing.md. A dev build ahead of the public release does not by itself mean a release is due. Before release acceptance, mark a dependent website download update as 🕰️ if it is already known to be required, and say it follows the release. For clawdline.com, use the website's own deployed version or visible page and its acceptance evidence; neither this repository's commit nor the hosted console stamp proves that website was updated. Use ❔ rather than guessing when that evidence is unavailable.

If a delivery changes Cloud API or relay, report their deployment separately before these final five lines; the hosted console's status does not cover them. Any required review-residue statement, including Fixed but not yet released (awaiting review), also goes before the final five lines.

What a child does not do

• git add -A in a shared tree, or stage a file it was not assigned.
• Leave its delivery uncommitted: it commits to its own task branch and never pushes — the commit is what lets the landing be proved.
• Start a daemon on port 7727 or write to the person's running one. Use an empty CLAWDLINE_NEXT_DIR of its own, never a copy of ~/.config/clawdline-next.
• Read ~/.config/clawdline except where the code already does, or write it.
• Stop a daemon by pattern: stop your own by the PID your serve printed.
• Remove a private tmux socket directory while its tmux server still runs: kill that server first, or its assistants keep running where nothing can reach them.
• Confirm a restart with /v1/health alone: the console is back when GET / answers 200.

The incident behind each of these is in docs/working-rules.md.

Questions that need the person to choose

For a concrete choice the person must make, read clawdline guide note, create one answer Note with complete suggested replies, then ask briefly in chat and wait for the person's sent message. For Codex's non-blocking request_user_input_async, also create one answer Note with the same question and complete replies so the person can return to it later. A blocking question screen (Claude Code's AskUserQuestion, or a blocking Codex prompt) needs no duplicate Note. Suggested or preselected options are not answers; wait for the person's sent message.

The single pages

The capacity register implements the policy in docs/limits.md §4; the rest of that file is a dated retired-app record.

Where instruction files conflict, the nearest one wins, and a task brief wins over all of them.