twinlane 0.4.1__tar.gz

twinlane-0.4.1/CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: "If you use twinlane, please cite this release."
+title: "twinlane"
+version: 0.4.1
+date-released: 2026-10-27
+authors:
+  - name: twinlane contributors
+repository-code: https://github.com/mmelqadi/twinlane
+license: MIT

twinlane-0.4.1/DESIGN.md

@@ -0,0 +1,152 @@
+# Design
+
+## Observation cost and read-only status
+
+Each command/poll shares one invocation-local job index from a single directory scan.
+Specs and writer identities are resolved once per distinct job/path and released at the
+end of the invocation. Lane activity is indexed by baton and writer once, with lifecycle
+mtimes checked before opening old specs. No age filter weakens live-worker custody.
+Bound transcript lookup/context estimates and session provenance are shared within a poll.
+Status dispatches before directory initialization and uses only cached meter evidence;
+effective job state is reported separately from the persisted receipt status.
+
+## Waiting, owners and wake delivery
+
+Batons store `waiting_on` (`lead`, `user`, `job:<id>`, `lane:<slug>`, `none`) and
+`waiting_since`, an ISO timestamp changed only when the dependency changes. Legacy
+batons default to `none`. Job ids and lane slugs use the existing validators. A user wait
+reuses the yes/no `--ask` and inbox path; answers are evidence, never execution authority.
+Board reads rank lead/user waits oldest first and count observed idle lanes without writes.
+
+`run --owner SLUG` validates an existing baton before allocation, merges the new job into
+its job index and sets its dependency. Every terminal receipt persistence path notifies the
+owner. Under the baton lock, completion records `job_done` with id, state, exit code and
+receipt path. It changes a matching job dependency (or `none`) to its bound lane, otherwise
+lead. Other dependencies are preserved. A per-job notification marker and history check
+make repeated finalization idempotent; notification failures log without changing the job.
+Before publishing a terminal receipt, the runner writes `owner-pending.json` with the
+owner slug. Completion writes `owner-notified.json` and removes the pending intent.
+Runner re-entry, wait, result and the writable inbox CLI repair pending completions;
+metadata-preserving re-entry still refuses terminal-job mutation. Status, board and watch
+never repair. Collection discovers per-job notices independently of the capped job index.
+WIP admission is acquired before baton locks. Collection notices compare the dependency
+and its timestamp with the completion marker and the existing result-collected marker.
+
+`watch` reads finalized receipts, baton/history snapshots, cached meter windows and bounded
+tails of identifiable bound sessions. There are no per-poll subprocesses, network requests,
+model calls or refreshes. It watches Claude 5h/7d and Codex weekly 80%/85% crossings and
+estimated bound context crossing 70%; missing estimates are skipped. Meter thresholds use
+a high-water value per reset window, so decreases do not trigger or re-arm a wake.
+Each poll sees only the latest meter/context observation. A threshold excursion that
+rises and falls between observations is not detected or reconstructed. Context crossing
+keys include the baton slug and session id, so shared sessions wake each bound lane.
+
+Each validated watcher name owns `state/watch-<name>.json`. On startup it delivers retained
+events absent from that cursor, including events predating the first invocation. Names
+are independent. Output is printed and flushed before the atomic cursor write: a crash
+can replay output, so delivery is at least once. No-event polls persist observation
+baselines but acknowledge no events. Only the cursor file is written. Retention is bounded
+by available receipts and baton history; this is a local wake mechanism, not an event broker.
+Coordinating sessions run watch in the background and re-arm after each wake; worker guards
+refuse it before cursor access. Defaults are a 5-second interval and a 3300-second timeout.
+
+`capacity.py` provides pure weekly-pace advice: percent used divided by elapsed fraction
+of a seven-day window. Only a measured lower Codex pace advises Codex first; ties and
+unknown readings advise Claude first with the reason, naming missing meters. This line
+is advisory and never replaces policy admission.
+
+## Lanes, human questions and checkpoints
+
+`wip.py` merges jobs, batons and recent interactive sessions by `common.writer_key`, the checkout toplevel.
+Count and creation are serialized under the WIP lock. Writer rows without a known identity retain their lane.
+The versioned `state/wip-queue.json` contains retry argv, never prompt bodies or approvals. A next operation
+prints the retry command; it never dispatches and leaves the queue intact while full unless forced.
+
+Jobs count as admission classifies them (`write`, or any profile but `intel`). A job releases its lane
+only when its receipt is terminal and `jobs._writer_job_busy(id)` is false, the writer-directory
+admission rule: a provably dead engine frees it even when the runner's identity is unreadable and its
+status file is unfinished. A just-admitted job (no pid, no receipt) and a row without an id retain their lane.
+
+Setting `wip.claims_command` to a non-empty argv list selects claims mode: writer jobs and claimed
+worktrees count; batons and activity-window sessions do not. Because a baton holds no lane there, baton
+commands (`baton new|set|snap`, `handoff`) skip writer admission and never run the provider. A null or empty
+command keeps the default activity mode. Claims merge by `common.writer_key` and respect `wip.count_main_checkout`.
+
+The provider prints `{"version": 1, "claims": [{"worktree": "<absolute path>", "id": "<opaque string>",
+"age_s": null}]}`. Ages may also be finite numbers in seconds. Collection runs the argv
+without a shell, stdin or pipes: stdout goes to a temporary file read up to 1 MiB (`output too large`
+beyond), stderr is discarded, and on timeout the provider's process tree is killed with a bounded wait, so
+a descendant holding inherited handles cannot stall admission under the WIP lock. Claims are fetched once
+per command observation.
+
+`wip.claims_timeout_s` defaults to 10. Spawn errors, timeouts, nonzero exits and invalid JSON, versions,
+claim shapes or paths fail closed with `writer custody unknown: claims provider failed: <reason>`,
+which names the config file to remove `wip.claims_command` from. Only writer admission fails: `board`
+and `status` show the writer count as `?` with a signal, and read-only (intel) runs never enter admission.
+Reasons are short fixed labels; provider output and arguments are never included in the error.
+
+`lanes.py` derives stale from progress, local git activity, job activity and bound sessions. Mechanical
+snapshots preserve the progress clock. Parked batons release their slot until explicitly resumed; after the
+park timeout the board asks whether to close or resume. Only an explicit human/lead close writes closed.
+Landing records landed, the count and verified status outside the integrator lock, including unverified landings.
+
+The inbox ranks blocking questions, waiting questions and legacy approvals, collapsing duplicate legacy text.
+Its header reports every hidden item. Answers take only the baton lock and append to `holds.answers`, never
+`approvals_granted`; an inbox yes is never a live-write approval. ATTENTION contains inbox and stale work.
+SIGNALS retains the P0 usage and process warnings. Board collection takes no locks and writes no state.
+
+Supervisor discovery is memoized and bounded; failure falls back to transcript observations. Notification,
+Stop and Codex notify write atomic local lane-state files, never contact a service and never store Codex
+message bodies. Supervisor observations take precedence over hook state. Provenance never confers authority.
+
+`wt prune --merged-only` and its thin `wt gc` alias retain shallow/deep blockers, interactive usage,
+locks and immediate rechecks. Unique patches plus unique merge commits keep a branch; landed ledger tips
+can identify squash landings. The merged minimum age defaults to one hour; `wt.behind_max` defaults to 50.
+Removal unlinks dependencies first, restores links if a folder remains, and uses `git branch -d` only.
+Worktree creation is gated by WIP. Configured dependencies must be ready and links resolve within allowed roots.
+The optional post-land archive applies these same checks to one just-landed path, outside the integrator lock.
+
+`context.py` uses the latest per-request usage, never cumulative billing totals. Window precedence is exact
+model policy, engine policy, then the Codex rollout window. Every display carries `~` and `estimate: true`;
+missing denominators remain unknown. PreCompact binds by session id, checkpoints up to three batons with
+bounded lock time, preserves `progress_at`, and never guesses by cwd. Worker callbacks return first.
+Install previews a redacted unified settings diff, preserves unrelated keys/events and requires `--yes`.
+Codex notify configuration is printed for manual installation, never edited.
+
+twinlane keeps its state under a configurable data directory. `state/` stores cached usage and locks, `jobs/` stores per-attempt inputs and receipts, `batons/` stores task context, and `bin/` is reserved for local helpers. The packaged policy is merged with a user JSON override at read time.
+
+`meter.py` normalizes Claude OAuth usage and Codex app-server limits. Each reading carries source and age; missing evidence remains unknown. `route.py` is a pure decision function over a task kind, meter snapshot, and policy. `jobs.py` launches workers, records JSON events and final text, and tries the other engine only after a usage-limit result. `codex_runner.py` calls `codex exec --json` directly and writes the adapter evidence contract.
+
+`baton.py` records goals, worktree state, decisions, holds, and next actions. `board.py` reads cached records without starting workers. `sessions.py` discovers vendor session files for forwarding. `hook.py` warns at the limit boundary; `guard.py` checks tool calls inside Claude workers. The advisory hook fails open, so a hook failure leaves the user's prompt usable. The guard fails closed inside a job: if it cannot load it exits 2 (a blocking PreToolUse result), and a scan that cannot finish denies. It is a heuristic over command text, not a sandbox, and an obfuscated command can still pass, so the worker's permission profile and the Codex sandbox remain necessary.
+
+Liveness is three-valued: `common.pid_state` returns alive, dead or unknown, and a process whose creation time cannot be read is unknown, never lost. On Windows a process this token cannot open (for example a SYSTEM service that now holds a recycled pid) has its creation time read from a `NtQuerySystemInformation` process snapshot, trusted only when the same snapshot gives the current process the creation time `GetProcessTimes` gives it; a different time is dead, and without a trusted snapshot it stays unknown. A job keeps a `child-starting.json` marker from just before its engine starts until the engine is reaped, and a `survivor.json` when an engine outlives its kill, so a crash between those writes and the receipt still reads `orphaned` or `unknown`. On Windows, `--bg` runners start through WMI with the caller's environment handed over in an owner-only file, and `--bg` is refused when that start is impossible; POSIX runners use a new session. Windows tree kills verify creation times and terminate through the same pinned handles; snapshot parsing bounds the full fixed header and declared thread payload within each entry, and query growth is bounded.
+
+Windows descendant membership uses each child's handle to read its recorded parent PID and monotonic process sequence number (`NtQueryInformationProcess`, classes 0 and 92), requiring the sequence to exceed its verified parent's while retaining all ancestor handles until termination. An orphan predating a reused parent PID fails this rule regardless of wall-clock rollback or recovery; creation FILETIMEs remain identity checks, never ancestry ordering evidence. An unavailable sequence query, mismatched parent, or inaccessible intermediate refuses that branch and returns `False` after attempting only the verified root and independently proven branches.
+
+A job's `result.json` has one writer: the holder of the runner role (`runner.lock`, taken with O_EXCL; a lock naming a dead process is stale). `twinlane stop` writes `stop.requested` and kills the recorded tree, but writes `stopped` only after it takes the runner role itself, which a live runner never yields; it re-reads the receipt inside the role and keeps any terminal receipt. While a runner may still be alive, stop exits 4 (`stop_requested`) and that runner records the outcome itself: `stopped`, or `done` when the work had already finished. A background refusal takes the same role, and a runner that starts later finds the receipt and exits.
+
+`jobs.codex_credit_refusal` runs before every Codex attempt and refuses paid credits for every model unless `codex.allow_credits` is true; a write job also reserves its worktree so two writers cannot share one.
+
+A stale writer claim with a terminal receipt can be released when the runner and recorded child are provably DEAD, without attempt exit evidence. For an existing process whose creation identity is unreadable, the PID-reuse exception instead requires a DEAD runner and a `done` or `failed` receipt with a nonempty attempts list: the terminal final attempt has a matching integer exit code, a nonempty post-wait events path, no survivor, and an integer `n` equal to the recorded `status.json` `attempt`. Engines must match when both are present. Missing attempt numbers, unknown existence, a matching live child, survivors and launch markers block this exception. The exit evidence covers only the recorded child; descendants are covered by the survivor marker. Admission holds `writers.lock`, rechecks a pending status repair under `status.lock`, and refuses if that recheck is rejected. Repair returns `repaired`, `already-final` or `rejected`; unsuccessful repair never grants writer clearance.
+
+## Project commands and the trust boundary
+
+`projects.py` resolves a repository to its main checkout (the first `git worktree list` entry, confirmed by asking that checkout which worktrees it owns, because a linked worktree's `.git` file is writable by whoever works in it). Settings for `land`, `ship`, `wt` and `test` come only from the `projects` map of the user config, keyed by that path, and never from repository content. A worker in a checkout therefore cannot rewrite the gate, land command or ship command that judges its own work. Commands are argv lists with named placeholders replaced in one pass; there is no shell, unknown keys and placeholders are errors, and values with line breaks are refused. A `.bat` or `.cmd` target receives only plain values, because `cmd.exe` re-parses its arguments. State for each project lives under `state/<feature>/<repo_key>/`.
+
+## Land queue and lock
+
+`land.py` keeps `queue.json`, `holder.json` and an append-only `ledger.jsonl` per project, and serialises every read-modify-write behind one OS file lock. The integrator lock is a lease held by the running `land run` process (a token plus a heartbeat). Staleness alone never takes it: a live holder is respected, a provably dead one is broken only by an explicit `--break --reason`, and an unjudgeable one (another host, an unreadable process identity) is never broken. Landing is fast-forward only; the gate runs on the tree that will land, and a gate that changes `HEAD` or the tree is refused. The ledger records each landing's exact range, which is what `ship plan` later reads. A file that exists but cannot be parsed is an error, never an empty queue, so a write cannot silently drop entries.
+
+## Ship manifests and receipts
+
+`ship plan` hashes the bytes a checkout of the source commit would produce (git attributes are read from that commit) and records files, deletions, commits, excluded commits and flags for foreign and superseded changes. The manifest is accepted by `ship run` only in the exact canonical bytes `plan` writes, and `run` works on a private copy keyed by its sha256. `ship run` is a dry run that writes a receipt; `--execute` crosses a different boundary than the plan: it needs a fresh, unused receipt for the same manifest hash and command, a confirm code (the first 8 hex digits of the hash), a manifest that still matches the repository, and a re-hash just before the command starts. twinlane runs only the configured command; it has no deploy logic of its own.
+
+## Prune safety
+
+`wt prune` is a dry run first. It keeps a worktree if anything uses it, if it is dirty, if its branch is not merged, if it holds submodules or links it cannot classify, or if it is itself a link. Junctions and symlinks inside a worktree are unlinked first, after recording their targets and without following them, because some Windows Git builds descend into a junction and delete what it points at; a link that will not go, or a vanished target outside the worktree, stops the prune. Branches are deleted with `git branch -d`, never `-D`, so git itself refuses an unmerged branch. Each action is appended to `prune.jsonl`.
+
+## Resume
+
+`resume.py` re-runs a lost job's request as a continuation. It never runs on its own, selects only jobs whose status is exactly `lost`, and stops at the first refusal. `host.py` compares the job's start with the machine's boot time to name a restart as the likely cause; a missing boot time gives `unknown`, never a guess. A `resumed.json` marker prevents a second resume.
+
+Exit codes: 0 success, 2 command usage, 3 refused, 4 still running, 5 failed, 6 usage limit, 127 missing executable.

twinlane-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammed Elqadi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

twinlane-0.4.1/LIMITS.md

@@ -0,0 +1,141 @@
+# Limits
+
+- Job admission lock contention waits up to `jobs.lock_wait_s` (default 1800 seconds / 30 minutes),
+  with jitter and `waiting for slot lock` / `waiting for writer lock` in status and the board.
+  Expiry reports how long the lock stayed busy and the last observed holder PID and age, if available.
+  One bound covers a whole streak of lock waits and restarted scans (restarts do not reset it); after three restarted scans in a row the next attempt probes inside the lock so the oldest job always decides. The lead command `release_stale_writers` (`wt doctor --fix`, patrol) still fails after 30 s.
+  Holder sidecars are best-effort diagnostics, never grounds to remove a lock. OS locks still release
+  when the holder dies. Slot admission probes processes outside the lock and rereads admission files
+  inside it; new identities cause a retry. Ordinary non-admission lock timeouts remain unchanged.
+
+- Codex meter timeouts or closed output/no reply get one additional app-server exchange with a 30 s timeout (`APP_SERVER_RETRY_TIMEOUT_S`), before the rollout fallback; the default exchange budget is 15 + 30 s, plus bounded process cleanup. Missing binaries, protocol errors and unsupported requests are not retried. Only dispatch admission (`route`, `run`, best-of and start/failover checks) can use the last genuine `app-server` or `rollout` Codex section after an unavailable live read. Its original `reading_at` must be younger than `meter.stale_ok_max_age_s` (default 1800 s / 30 minutes), capped by `codex.stale_reading_max_age_s`. Every counted window needs a known percentage and a future reset; the section must be `ok` or `caution` under current thresholds and never on credits. Missing, unreadable, malformed, expired, reset, handoff/stop/out/unknown or previously carried sections are refused as before. A carried section is labelled `meter stale-ok (age Nm)` with `stale_ok` and `stale_ok_age_s`; it never refreshes its original stamp or replaces `state/meter.json`. Actual failed observations are stored separately in `state/meter-codex-failure.json`, so explicit meter commands and the board show the failure with only a labelled fallback-availability note. The 120 s cache TTL and `--fresh` semantics are unchanged. Claude's OAuth meter has no stale-ok fallback; its failures have a different cause. Post-job usage observations also never substitute stale-ok evidence.
+
+- The writer cap coordinates one twinlane home on one machine. It counts distinct worktrees, not model calls or processes. Interactive activity comes from recent transcript markers and is an estimate; unreadable live job metadata occupies its own lane. Starting a CLI outside twinlane is not mechanically prevented. Queue entries contain metadata, never executable prompts, and `wip next` grants no slot or authority. `wip pump` claims a request (`pumping_at`) before it starts and the request leaves the queue only when the job of the run it started exists on disk; a claim older than five minutes is left for a human (`wip next`), never relaunched blind. A run started inside a job object that ends its children can therefore die with its parent; its request stays claimed rather than being lost. If a stall kill does not report that the whole tree is gone, the job is not retried and its worktree claim is held by `tree-unresolved.json` until a person confirms with `twinlane stop JOB --tree-gone`; twinlane cannot tell which processes survived and kills none of them from that marker. On Windows each runner attempt starts its engine suspended, assigns a kill-on-close Job Object and then resumes it; zero ActiveProcesses after TerminateJobObject is the only confirmation. Descendants stay contained even after an intermediate parent exits. Escaping descendants remain a limit for callers without that job handle (cross-process stop, or assignment failure such as forbidden nesting): snapshot cleanup is best effort and reports tree exit unconfirmed. An unconfirmed runner kill retains custody. The attempt handle closes after the result is read; first the job is terminated and must report zero active processes, otherwise (or if an interrupt cuts the drain short) the job keeps its worktree claim (`tree-unresolved.json`, or the pid-less launch marker when that cannot be written) like an unconfirmed stall kill. If the job object cannot be assigned (for example a host that forbids nesting), the attempt still runs but nothing can prove its descendants gone, so unresolved-tree custody is written BEFORE the engine is resumed (a killed runner or a `stop` cannot lose it) and every such attempt ends with the claim held until a person confirms; if that marker cannot be written the engine is not started; an unresolved tree also stops a usage-limit failover from starting a second engine. On macOS and Linux no stall kill is ever reported confirmed (the packaged Codex runner starts `codex exec` in its own session, and a Claude worker may start a helper in its own session): the process group is still killed, but the job is not retried and the claim is held until a person runs `twinlane stop JOB --tree-gone`, so the automatic stall requeue only works on Windows. It re-runs a queued `run` command exactly as typed (it holds the path of the brief, not its text) through full admission again, only for a request younger than a day whose brief file still exists.
+- Host load is advisory. CPU is averaged over `hostload.cpu_window_s` (default 20 s), so a spike shorter than that cannot hold the queue, and a real overload shorter than that is noticed late. It is read from CPU, free-RAM and process counters; desktop-heap exhaustion has no cheap counter, so it shows up only as a stalled worker, which the watchdog handles. The watchdog judges progress by file changes, so a worker that is busy but silent for longer than `watchdog.stall_s` is killed and requeued once.
+- Stale is an inactivity projection, not proof of completion. Batons are never auto-closed; landing marks landed and explicit closure remains a human/lead action. Inbox answers are retained as context on that baton and never transfer live-write authority across sessions or engines. A lane resumes only through fresh admission.
+- Context is an estimate from the latest request record in a bounded transcript tail. Claude input and cache tokens are summed; Codex uses `last_token_usage`, never cumulative totals. Missing usage or a missing model-window configuration stays unknown. The packaged context-window map is intentionally empty; verified Codex event windows can supply the denominator. The 70/85 flags are advisory and do not stop a model.
+- `startedBy` is explicit recorded provenance; missing provenance stays unknown. `UNMANAGED` is a recent session outside direct job receipts, explicit baton bindings and the configured lead family. It does not imply that the session is malicious or still running. Child sessions are visible and are not automatically trusted because their parent is tracked.
+- `wt gc` is a dry run by default and uses prune's existing ownership, age, lock, link and recheck protections. A zero-unique-patch result permits cleanup of a cherry-picked equivalent branch; its branch ref is kept if `git branch -d` refuses deletion. Post-land archive defaults to a suggestion; apply is an explicit user-config choice and retains prune safety. Configured dependency checks cannot prove that an application runs correctly.
+- PreCompact snaps up to three batons explicitly bound by session id. A matching cwd alone grants no binding. It never calls a model, refreshes usage, creates a Git checkpoint or installs itself. The advisory hook remains fail-open if snapshotting fails.
+
+- Claude's OAuth usage endpoint is undocumented and may change. The meter sends the locally stored token only to `api.anthropic.com` and refuses redirects. Unknown or stale readings block dispatch for that engine.
+- Codex usage comes from its app-server interface and local session evidence. These formats may change; unknown readings stay unknown.
+- Served-model reporting differs by vendor. A Codex receipt can only show the requested model when the CLI does not report the served one.
+- Windows has the most complete detach behaviour. POSIX uses a new process session and process-group termination; Windows job-object details are unavailable there.
+- On Windows, `--bg` runners start through WMI. Surviving a desktop app quit was shown with real quit-and-reopen tests on one tested Windows machine and build; that is not a general guarantee. Sign-out, shutdown, sleep and reboot are untested, and survival says nothing about whether the task succeeds.
+- A job whose runner cannot be identified (for example from inside a restricted-token sandbox) reads `unknown`; twinlane will not stop it, so check it from the host.
+- The Codex app-server meter currently finds only the Windows Codex desktop app. It copies the app-server build into `<home>/bin`, keeping at most 3 copies of about 434 MB each (about 1.3 GB total). On Linux/macOS, set `TWINLANE_CODEX_BIN` or rely on rollout files; otherwise the Codex meter reads **unknown**, and parallel/sweep routes fail safe to Claude or refuse.
+- When the Codex app-server exchange fails, the meter falls back to the newest local rollout reading. `--no-rollout` or `meter.codex_rollout_fallback: false` turns that off; Codex then reads **unknown**.
+- `twinlane install` registers an advisory hook for interactive sessions. The blocking guard only acts inside twinlane-dispatched workers; interactive sessions are NOT guarded. The guard is a heuristic over shell text, not a sandbox: it does not read script files, and an obfuscated command can still pass. Code workers must still run in worktrees with the vendor's own permissions and sandbox.
+- Built and tested against the `codex exec --json` interface (flags `--json --model --config model_reasoning_effort=... --sandbox --cd --output-last-message`); older Codex CLI releases may not accept current model names; run `codex --version` and set your models in config.
+- Model ids are defaults as of 2026-10; set your own in config.
+- Credits and extra usage are checked only when a job starts. A long Codex job can still reach paid credits if your account allows it; twinlane passes no option that enables credits. Nothing in twinlane stops a running Codex job that crosses into credits partway. Check the receipt and meter before continuing.
+- Removing secret-named environment variables from code workers does not remove secrets a script reads from files such as a repository `.env`. It also removes `CLAUDE_CODE_OAUTH_TOKEN`, so a Claude code worker on a setup that logs in only through that variable fails to authenticate; intel workers keep it.
+- Outside-path checks fail closed: a `..` or home path named by any command that is not on the guard's short read-only list is denied, even when it is only read (`python ../tools/x.py`, `sort ../x > out.txt`); read or run it from a read-only command or from inside the worktree. A command is read-only per call: one with a write or run option is read-only only without it (`git` read subcommands without `--output` or `grep -O`, `find` without actions, `fd` without `-x`/`-X`, `rg` without `--pre`, `xxd` with one file operand, `tree` without `-o`/`-R`, `file` without `-C`), and `less`, `ack` and `ag` are not read-only at all. A path the shell computes when it runs (`$(...)`, backticks, `${X:-..}`, `${PWD%/*}`) in a command that is not read-only is denied, and so is a brace expansion over 256 words; bash `$'...'` quoting is decoded first. Code jobs allow only known tools: MCP tools, a write or shell call without a known job worktree, and a call without a string path or command are denied. What still passes: an ABSOLUTE path given to a command the guard does not know as a writer, outside an output option (`chmod 777 /abs/x`); a target taken from a config file or an environment variable; a plain `$VAR` given to a command the guard does not know as a writer; and anything a script file does. Codex workers also run under Codex's own `workspace-write` sandbox; Claude workers rely on the guard plus Claude Code's own permissions.
+- Archive extractors are allowlisted: tar and bsdtar run only with options known to keep member names inside the destination (unknown options, `-P`, `--absolute-names`, `--transform`, `-s` and command hooks are denied in any getopt abbreviation), unzip only with plain letter options (no `-:`/`-^`), 7z without `-spf`/`-snl`/`-snh`; extraction by `cpio`, `jar`, `pax -r` and `python -m tarfile -e` is denied. A tar `-T`/`--files-from` list is denied unless `--verbatim-files-from` comes first, because GNU tar reads its lines as options. Setting `TAR_OPTIONS`, `TAR_READER_OPTIONS`, `TAR_WRITER_OPTIONS`, `TAPE`, `UNZIP`, `UNZIPOPT`, `ZIPOPT` or `ZIP` is denied in any syntax the guard reads, including names joined from quotes, escapes or `+`; an uppercase `UNZIP`, `ZIP` or `TAPE` anywhere in a command is refused too (`grep UNZIP` needs `grep -i unzip`); and `export`, `declare`, `env`, `setx`, `Set-Item env:` or `SetEnvironmentVariable` with a variable NAME built at run time (`export "$n=x"`, `$'..'`, `[char]`) is denied, because the name cannot be read. `git fetch`, `git clone` and `git ls-remote` may contact any host, so the URL itself can carry data out.
+- After a timeout or interrupt kill, twinlane checks the process it started. On macOS and Linux the packaged Codex runner starts `codex exec` in its own session, so a Codex engine that outlives its runner is not detected; on Windows the attempt Job Object contains the tree; if assignment fails, verified snapshot members are killed best effort and tree exit stays unconfirmed.
+- The guard hook runs with the Python interpreter recorded at install time. If that interpreter is removed (for example a rebuilt virtual environment), the hook cannot start and Claude Code does not block the call; rerun `twinlane install`.
+- The guard is a deny-list and defense in depth, not a sandbox, and a deny-list cannot be complete: a new tool, an unmodelled spelling or a script file can pass. Real confinement comes from elsewhere: workers that hold no push or deploy credentials, a worker that runs only in its own worktree, and a lead who reviews every diff and reruns the gates. Treat a guard denial as a guardrail, and a guard pass as no evidence of safety. `guard.deny_commands` and `guard.deny_text` add your own rules; they do not make the guard complete.
+- The guard acts only inside twinlane-dispatched workers. A `guard` policy section that is not an object, or cannot be read, denies every call of the job (fail closed); a typo in `deny_text` therefore stops the job instead of weakening it.
+- `twinlane land` serialises landings through one lock per repository and lands fast-forward only. It trusts the project's gate to be a real check; with no `land.gate` it lands ungated and says so. A holder whose liveness cannot be judged (another host, an unreadable process identity) is never broken, so such a lock needs a person to look at it. The queue and ledger are local files: they coordinate sessions on one machine's state directory, not machines.
+- `twinlane ship` never deploys by itself. It writes a manifest and runs only the command you configured in your user config, after a fresh dry-run receipt and a confirm code. It cannot tell whether that command is safe, and the manifest lists files and commits, not whether the release is correct. Manifest hashes are computed on the machine that plans, so line-ending or filter settings can make them differ across machines.
+- `twinlane wt prune` never deletes an unmerged branch (`git branch -d`, never `-D`) and keeps any worktree that is dirty, in use, linked or unclassifiable; the cost is that some stale worktrees stay until you remove them yourself. Link handling covers Windows junctions and symlinks; an unusual reparse point is kept, not removed.
+- `twinlane resume` continues only jobs whose status is exactly `lost`, only on request, once each. A continuation is a new attempt with the original brief and any recorded context; it does not restore a running conversation or undo partial changes. The restart cause is advisory: it compares times and can be `unknown`.
+- `run --best-of` spends one run of usage per contestant and never fails over between engines. `compare` shows evidence; it does not choose a winner or merge anything.
+- Per-project commands run with your user's rights and no shell. twinlane refuses a string command, an unknown placeholder, a value with a line break and, for `.bat`/`.cmd` targets, any value `cmd.exe` would interpret, but it does not sandbox the command itself.
+
+- WIP sees only jobs, batons and local supervisor/transcript activity in this home. Sessions with no observable activity are invisible. Transcript activity uses file times; `wip.count_main_checkout` controls main-checkout lanes.
+- An inbox yes is never a live-write approval. Answers are recorded separately from grants. Context numbers labelled `~` are estimates from the newest bounded usage record.
+- Merged-only pruning keeps a one-hour minimum age except the optional archive of a just-landed worktree. It never deletes an unmerged branch.
+- A landed-unverified range is never shippable. Re-gating is possible only when the lane worktree still sits on the landed commit. twinlane never deploys by itself.
+
+- `twinlane patrol` is a file-only, one-pass report by default (exit 0 even with findings).
+  It reads cached engine meters and host-load samples without refreshing them, and writes only
+  `state/patrol.json` and `state/patrol.jsonl`. The cache-only host reader never measures or spawns.
+  Missing, older-than-five-minute or unusable host counters mean host status `unknown`: the overload
+  count is retained and an existing overload finding stays stale until usable evidence returns.
+  Liveness observations never spawn `ps`: POSIX uses `/proc` or signal zero, keeping unreadable
+  identities `unknown` and conservatively counted as running. This also applies to the file-only board.
+  Custody snapshots take no lock and create no file; only a missing folder is complete and empty.
+  Unreadable folders or claim files are incomplete evidence: `patrol_error` retains prior custody
+  findings as stale, without authorizing release. Actual release still locks and revalidates claims.
+  No model is called.
+  `--fix` permits only `wip.pump_quietly()` and `jobs.release_stale_writers()`; pumping can launch stored
+  requests through full admission. Engine workers may read patrol, but cannot run `patrol --fix`.
+  All other findings are report only: unresolved trees require a person to verify they are gone before
+  `twinlane stop JOB --tree-gone`; lost jobs point at `twinlane resume` and are never auto-resumed.
+  `queue_ready` reports engine and host eligibility only; file-only readers cannot verify writer capacity.
+  Only a confirmed `--fix` pump launch produces `queue_stalled`; a refusal is `queue_waiting` with the
+  pump's own reason, retained on subsequent reports until evidence changes. `queue_claimed` is never
+  replayed by patrol; a claim older than ten minutes (or with an unreadable timestamp) needs a person.
+  A claim missing its timestamp defers the whole pump, since its replay guard cannot recognize it.
+  Slot-leak checking is skipped: slots are derived from job liveness, with no separate cheap lease reader.
+  `worktrees.doctor` is skipped because repository and dependency probes exceed the file-only pass budget.
+  Each collector has a bounded wait within a roughly ten-second pass; slow or failed collectors become
+  `patrol_error`, and unknown evidence does not resolve earlier findings. An overdue read is not duplicated
+  on the next pass. Remedies check the pass deadline before making changes; an interrupted pump can leave
+  a claimed request for manual inspection. The existing remedies retain their own admission and custody rules.
+  `--loop SECONDS` requires at least 30 seconds; `--max-runs N` bounds the number of passes.
+  `--quiet` suppresses unchanged output; opened, resolved and hourly reminder findings are printed.
+  JSON always includes every current finding and its `new` flag. Ages and changing host measurements
+  (`detail`) are separate from stable condition identity, preserving quiet output and hourly reminders.
+  History retains the last 2000 opened/resolved/fixed events. Unreadable patrol state freezes
+  state/history writes and fixes until it can be read or repaired; prior evidence is not overwritten.
+  Configure `patrol.queue_stall_s` (600) and `patrol.person_wait_s` (1800); overload needs three consecutive
+  measured passes above the configured host-load threshold; unknown evidence does not reset the count.
+  A quiet job with the watchdog disabled asks for inspection and offers `twinlane stop JOB`.
+  Patrol is advisory and never kills or stops a job.
+
+
+### Patrol reader completeness
+
+Incomplete evidence never resolves a finding. Each failed source emits `patrol_error`; earlier findings
+that depend on it stay open with `stale=True`, `safe_fix=False`, including a finding emitted again with
+the same key. Policy failures invalidate all dependent checks; details invalidate board checks, and
+board/slots/host failures invalidate queue checks. Runtime waits also depend on the board's live-job
+classification and queue evidence, despite their stored source being details. No error authorizes a fix.
+A genuinely missing optional file/directory can be complete and empty; a denied parent is an error,
+never absence.
+
+The table covers every reader consumed by `patrol.collect()`. "Strict" means only FileNotFoundError
+is accepted as absence; other access/I/O failures and invalid JSON/object types raise. The underlying
+readers remain tolerant for other callers unless stated otherwise.
+
+| Reader / evidence | Unreadable directory | Unreadable file | Malformed file | Patrol handling |
+| --- | --- | --- | --- | --- |
+| Policy + optional config (`load_policy`); host/watchdog/patrol settings | Strict open raises (config is checked without isfile) | Strict open raises; loader SystemExit is captured | Strict JSON/object raises; loader failure captured | policy error; all prior sources stale. Settings functions only transform this policy; invalid optional scalar settings keep documented defaults. |
+| Board meters cache | Strict open raises | Raw reader returns None; patrol strict open raises | Strict parse requires engine objects and parseable read_at plus each engine's reading_at, including missing timestamps | board error; board, host, queue and runtime-wait findings stale; no pumping. Missing cache means engines unknown. |
+| Board job directory scan (`observations.job_ids`) | scandir raises; missing directory is empty | Entry is_dir/stat errors propagate | Non-job directory names ignored | board/details/slots errors; their dependents stale. |
+| Board job rows (`job/status/result.json`), runner.pid, survivor/child/tree markers | Strict patrol inputs raise | Raw JSON/text can return None/empty; strict patrol inputs raise | Strict JSON/object/status or runner identity validation raises; board problems also become errors | board error; prior job findings stale; details/slots independently validate these inputs. |
+| Board batons (`collect_batons`, file_only) | Explicit listdir raises; missing directory is empty | Row reports problems | Row reports problems; invalid wait/inbox timestamps flag incomplete | board error; prior human waits stale. Non-patrol enumeration retains tolerant glob behavior. |
+| Board inbox/attention + durable owner notices | Job scan raises | Raw notice read returns None; patrol strict input raises | Raw notice ignored; patrol strict JSON/object raises; malformed baton holds become row problems | board error; prior human waits stale. Inbox ranking and attention projection perform no extra evidence reads. Collected-marker stat is strict. |
+| WIP queue (`wip.queue` equivalent) | Strict open raises | Raw read can default to empty; patrol strict open raises | Strict JSON, object, version, rows, identity and timestamp checks raise | queue error; prior queue and runtime-wait findings stale. Queue absence is complete and empty. |
+| Queue launchability (`wip.launchable`) | Strict cwd/brief stat raises, including absolute legacy briefs without cwd | Permission/I/O stat failure raises; no brief contents read | Malformed argv/paths cause reader error or explicit unlaunchable reason | queue error + stale on read failure; genuinely gone brief/cwd is an explicit wait. |
+| Host cache (`hostload.cached`) | Strict open raises | Raw reader returns None; patrol strict open raises | Invalid JSON raises; invalid timestamp/counters return None/unusable; any missing counter is partial | hostload error; prior overload and queue findings stale. Missing/stale cache is unknown; no sampling. Disabled host checks need no measurement. |
+| Slots (`jobs.running_count`) | Strict job scan/inputs raise | Strict job inputs raise rather than accepting tolerant None | Strict inputs raise; non-integer/negative returned counts raise | slots error; prior queue findings stale. Native liveness stays non-spawning and conservative. |
+| Read-only custody snapshot: writers directory, claims, receipt/status, runner identity, marker stats | listdir/stat/open raise; missing writers directory is empty | Strict open raises | Strict JSON/object/receipt status/runner identity raises | custody error; prior custody findings stale, no release. Missing receipt without a live status is incomplete; unknown identity needs existing finalized/grace proof. Release still locks and revalidates independently. |
+| Job details: job/status + containment markers, output mtimes | Strict inputs/stat raise | Raw helpers use None/False; patrol uses strict inputs/stat | Strict JSON/object/status raises; log contents are not parsed | details error; prior unresolved/quiet-job/queue findings stale. Missing logs use job start time; watchdog settings come only from policy. |
+
+The dependency audit below includes indirect invalidation. Failure of any named collector keeps
+both re-emitted and prior matching findings stale, disables their fixes, and emits no resolved event.
+The single parametrized reader-failure matrix exercises every source/dependency pair, including
+runtime waits through board AND queue and legacy requests through their absolute brief path.
+
+| Finding source / kinds | Required collect readers |
+| --- | --- |
+| board: job_orphaned, job_unknown, job_lost, job_long, waiting_on_person | policy, board, details |
+| hostload: host_overload | policy, hostload, board, details |
+| queue: queue_ready, queue_waiting, queue_claimed, queue_stalled, engine_blocked | policy, queue, board, slots, hostload, details |
+| custody: custody_stale | policy, custody |
+| details: custody_unresolved | policy, details |
+| details: runtime queue_waiting | policy, details, board, queue (also slots and hostload through queue invalidation) |
+
+Patrol errors identify the failed reader in the current pass; they never authorize fixes.
+A failed whole-pass collector retains every prior finding as stale.
+
+Patrol's own previous-state reader runs before collect: unreadable or malformed state emits a state
+error and freezes state/history writes and fixes. It cannot reconstruct unreadable findings, so it retains
+the stored observation for recovery instead of replacing it with an empty one. History is bookkeeping,
+not evidence for finding resolution; its existing read/write errors emit a history error. Verdict text,
+board signals and display-only activity stats do not decide patrol findings. Worktree/session/provider
+readers are excluded from the file-only board.

twinlane-0.4.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE README.md LIMITS.md DESIGN.md METHODOLOGY.md CITATION.cff
+recursive-include skills *.md
+recursive-include twinlane *.json
+recursive-include tests *.py *.json *.jsonl *.txt
+recursive-include examples *

twinlane-0.4.1/METHODOLOGY.md

@@ -0,0 +1,23 @@
+# Operating method
+
+Keep one lead for a task. The lead writes a small goal and owns the worktree, chooses a task kind, and checks the board before dispatch. Workers on either engine return evidence and changes; the lead reviews the diff and runs the final checks.
+
+Use a read-only worker for investigation and a code worker only where edits are intended. Cross-vendor review is useful for risky changes and disagreements. Stop when the evidence converges on the stated goal; do not repeat a completed review just to alternate vendors.
+
+At 75% usage, narrow new work; between 75% and 85%, `twinlane route` sends new work to the other engine when it is below 75% and usable. At 80%, update the baton and prepare a handoff brief. At 85%, stop new nonurgent work on that engine and move it to the other engine if its reading is usable. Never treat unknown usage as free allowance, turn on paid extra usage, or spend Codex credits. A handoff transfers context, not an approval for live actions.
+
+## Lead and integrator lanes
+
+Workers do not land or ship. Each worker finishes in its own worktree on its own branch and reports evidence; the lead reviews the diff and reruns the project's gate itself rather than trusting a worker's "done".
+
+One session is the integrator for a repository. It enqueues finished branches with `twinlane land enqueue SLUG`, checks `twinlane land status`, and lands them one at a time with `twinlane land run`, after a `--dry-run` if anything looks off. Because the gate runs on the tree that will land and a landing is fast-forward only, a branch that falls behind goes back to its worker or is rebased with `--rebase` when its range is linear. Two integrators never run at once: the lock refuses the second, and a stale lock is broken only when its holder is provably dead, with a reason on record.
+
+Release is a separate, targeted step. After landing, `twinlane ship plan SLUG` writes a manifest of exactly that landing's files; read its foreign and superseded flags before passing `--allow-foreign` or `--allow-superseded`. Run `twinlane ship run --manifest PATH` as a dry run, review it, and only then `--execute --confirm CODE`. Ship the landing you reviewed, not everything on the branch. Nothing in this lane needs a worker to hold deploy credentials.
+
+Keep the tree tidy at task boundaries: `twinlane wt doctor`, then `twinlane wt prune` as a dry run before `--yes`. After a reboot or an app quit, `twinlane resume` lists lost jobs; continue one only if its work is still wanted. Use `run --best-of` and `compare` for a decision that deserves two independent attempts, and accept that it costs the usage of both.
+
+The lead loop is `twinlane board` ? `twinlane inbox` ? `twinlane wip` ?
+`twinlane wt prune --merged-only` (preview). Ask one yes/no question instead of marking work blocked.
+Bind the active session to its baton with `--bind-session SESSION_ID`; an inbox yes is never a live-write
+approval. Park waiting work explicitly and close stale or landed batons yourself after checking the evidence.
+Use `twinlane land card --baton SLUG` before enqueueing. Review source, tests, integration and release separately.