Worktrees and status

Find the current state of a task, interpret a status field, or look up the identity and environment values for its workspace.

Status requires a discerndiscern↗A tool that installs and runs an agent development practice in a project. project. Linked-worktree lifecycle fields require a Git repository with at least one commit. For a practical introduction, read Worktrees and the trunk.

discern status reports the task's current state and next action. It runs no gate jobGate job↗A named check or operation scheduled by the gate., test, standardStandard↗A held limit for a repeatable project measurement. measurement, or setup action. Use it at the start of a session or when you need to understand what remains.

--all and --local conflict. MCP callers use discern_status with the matching options and an absolute path when selecting a particular worktree.

Worktrees default to a local view. The main checkout shows its state, fleetFleet↗The project's collection of task worktrees. task rows, the Landing queue, Owner attention, Landing risks, and Next action. --verbose adds per-task evidence, configured checks, local environment, landing history, shared paths, and stored Proof pages.

The Landing queue lists every submissionSubmission↗An effort's recorded request to land one exact commit. with honored Proof that has not landed: tasks a grant pre-authorizes first, in grant order, then tasks awaiting the owner, in submission order. Each line carries the task's branch and, when it cannot land yet, one sentence saying why: its branch moved on after the submission, so its agent runs discern done then discern accept for the new work; or its retained composition awaits a checkpointCheckpoint↗A review question presented when a relevant kind of change occurs. decision, with the continuation named. A trunkTrunk↗The shared branch that accepted work joins, usually main. that merely moved after its Proof is not a waiting reason — acceptance composes and checks the combined code itself. The current worktree's own task is marked. A failed or abandoned run, or a run its agent never submitted, has no line. The deskDesk↗An interactive view of the project's tasks and the actions available for them. and the acceptance preview derive their lists from the same projection, so the surfaces show the same tasks in the same order.

The report uses stored task titles when available; --verbose reveals complete worktree and branch identities. Use the stable id or branch in commands, even when a friendlier title appears in the report.

Rows prioritize live, stale, or uncommitted work while still showing branch drift. Shared-file and Architecture Decision Record (ADR) number collisions remain separate landing risks.

The other fields explain that status:

• Git says clean or 6 files changed; DRIFT keeps ↑8, ↓3, or both. Color reinforces the complete arrow-and-count text.
• Proof is honored, report-only, missing, stale, dirty worktree, unavailable, or unreadable. Report-only means the commit is current but CI reported checkpoint review without enforcing it; ordinary discern done is still required before landing. A clean branch with an honored strict Proof can be ready.
• Activity shows the most recent observed activity and recorded action. A live gateGate↗The configured checks a change must satisfy for ordinary completion. reads Gate running · 2m; usually 4m is historical context.
• Landing is granted, needs approval, or scopeScope↗A named set of project paths used to select work or policy.-limited on ready rows; detail wraps below it.

Text and glyphs carry every state; --no-color changes no facts.

Owner attention holds lifecycle and landing decisions; Landing risks holds file, trunk, and ADR conflicts; Next action holds the executable continuation. --verbose adds evidence.

In the expanded view, Checks shows configured changed scopes, each changed scope's configured preview command, planned gate jobs, and a standards count. It labels preview commands as not run. Derived code and previewable markers stay machine-only. Port and resources sit under Local environment. Landing shows pass, branch, files changed, diff size, commit, and age. Proofs contains stored Proof Markdown.

discern status
discern status --all
discern status --local
discern status --verbose
discern status --markdown
discern status --json
discern status --verbose --json
discern status --no-color

During setup, this read-only result reports the recorded phase, dedicated branch, and bounded continuation. It performs no write probe; the later effectful command checks its own targets (Setup command boundaries).

CLI JSON, MCP structuredContent, and the status resource use the same structured fields. The default is a bounded view for orientation; request full collections when a decision depends on entries outside that sample.

Repeated orientation collections retain at most six members; landing history is omitted. discern status --verbose --json or MCP verbose: true selects mode: "full", restores complete collections and landing history, and removes the omission mapMap↗The project's account of how its software works and why.. Every default result includes this route to full detail.

Both structured modes omit rendered Proof pages. Terminal --verbose displays those pages. Full structured landed_proof.proof remains compact, and landed_proof.commit_at supplies the landing age when Git can read it.

MCP content and discern status --markdown provide an authored summary of the same state. Owner attention separates decisions for the owner from the reading agent's next action. An idle or clean task in the fleet remains a separate effortEffort↗One task carried through implementation and review: the work a worktree, its branch, and its submission all belong to.; its row grants no permission to take over its worktree.

Ahead and behind counts are non-negative integers when known, "unknown" after a failed or malformed count, and null on local status when the trunk is missing. Missing evidence cannot establish readiness or containment.

Proof inspection reports honored, report_only, missing, stale, dirty, unavailable, or read_failed. An honored marker includes compact facts: branch, trunk, validated commit, diff counts, and line. Report-only evidence cannot be used for landing. The validated commit is the worktree's own committed tip; Proof explains what it covers.

Dirty, behind, and missing-Proof states are observations and can still return ok: true. A status operation that cannot complete returns its own failure. Read the reported task state separately from whether the status command succeeded.

Each sampled fleet row carries its own available recovery facts: Git registration, branch reachability, filesystem presence, cleanliness, divergence, setup-ready marker, journal, and repair classification. A failed Git read retains the command and diagnostic. Unavailable facts stay absent or explicitly unavailable.

Readable rows also carry activity, one gate_proof, and authority. task holds the display title, title_source, optional brief, and creation ref and commit. title_source: "identity-fallback" identifies a worktree without stored task metadata. Structured fleet rows omit the earlier proof_honored, proof, and proof_line compatibility copies.

Authority includes the current decision, up to six authored-first path examples, uncovered totals, and scopes. This summary does not grant authority beyond the underlying recorded permission.

last_action records the newest completed action. running records a recent start with no matching completion. last_activity uses the later Git or logbookLogbook↗The local record of the project's use of discern. time. Disabling the logbook removes action fields while Git activity remains available.

fleet_collisions pairs branches with overlapping changed files and retains the shared-file count. adr_collisions identifies contested Architecture Decision Record numbers and claimant branches, including branches without worktrees. Structured results omit their path lists; terminal --verbose shows them. A later discern update names overlapping paths to re-read.

A reappeared-path row carries path, removed_at, kind, entries, a bounded contents sample, and cleanup_blocked_reason when prune must preserve it. Cleanup appears under Owner attention; status itself performs no cleanup. Recover an interrupted task gives the practical procedure for an interrupted landing.

After setup, detectors can add recent logbook observations to hints[]. They inspect at most 200 events and exclude CI, previews, human activity, and other branches. Findings change no Git fact, gate result, Proof, exit code, or ok; setup in progress and a disabled logbook suppress them. Run discern patterns for retained evidence.

• status never runs the gate. A valid Proof links the current clean commit to its complete evidence.
• Fleet worktrees belong to separate efforts. A clean sibling remains occupied until its owner lands or discards it; its maintenance state appears under Owner attention.
• A reappeared worktree path is no longer an active fleet member. Review its contents and close any program still writing there before confirmed prune.
• The dashboard and Markdown result are projections. Default JSON and MCP are also bounded for orientation; request verbose structured status only when exact full collections are needed.

In the desk, Desk commands includes Check for updates, including when no tasks exist. Selecting it opens release notes in your browser so you can see what's changed and check for updates. Its result keeps the URL readable if the launcher fails. Escape returns to the live desk.

A reminder may appear after 14 days. It invites you to check; it does not mean an update is available or that anything is wrong with your installation. The maintenance guide explains how to check and update.

A worktree has a stable identity used to derive its development port, resource names, and test-order seed. Moving the checkout preserves that identity.

Run discern identity in the main checkout or a linked worktree and select the value you need:

A linked worktree resolves its id from DISCERN_WORKTREE_ID, configured environment files, then Git metadata. Overrides accept letters, numbers, dots, dashes, and underscores. This read-only precedence never grants destructive ownership: cleanup uses the exact Git worktree entry plus discern's ready marker.

Main identity uses the configured trunk and preserves it in --branch. Its seed changes only with that setting. Worktree seeds stay stable by branch; branches rotate order. Neither uses the clock nor secure entropy.

discern start avoids trunk and live-sibling port collisions when possible. A crowded band or racing starts may collide; change DISCERN_WORKTREE_ID then.

A task's display title and optional brief are human metadata, kept separate from the stable identity above. New starts store them with the creation ref and resolved commit in the worktree's Git administrative directory (discern/task-metadata.json), and discern worktree rename <title> changes only the title. Status shows the stored title when one exists; a worktree from an older discern reports title_source: "identity-fallback" and keeps its id-derived label. Removing the worktree deletes its local record. A landing removes the worktree when its branch holds nothing beyond the landed submission. discern worktree park copies the wording into a branch-keyed record that a later discern start --from consumes.

[worktree].env_files lists env-style files in precedence order. The default is [".env", ".env.local"]. Reads use the last file that defines a key. Writes update that last definition or place a new key in the first existing listed file. When creation is requested and none exists, discern creates the first listed file.

Each entry may use any portable project-relative filename. It does not need an .env basename. discern removes leading ./ prefixes and refuses entries that name the same case-insensitive path.

Reads may follow a symbolic link when its target stays inside the project. A missing or stale checkout, an unreadable file, or a link that leaves the project behaves as an absent env file. Before writing, discern refuses every symbolic-link component instead of modifying its target; configure the target path directly or replace the link with a regular file.

[worktree].inherit_env names values copied from the main checkout into a new worktree. Inheritance creates the first env file when it is missing, so every declared value arrives. It copies only the named keys. The rest of the main checkout's local env stays there.

The configured env files can carry the values listed in the environment-variable reference. [worktree].export_port defaults to false; set it to true when project tooling reads the development-port value. Worktree setup then writes DISCERN_WORKTREE_PORT to the configured env files, the worktree hook warns when a sibling already uses the derived port, and status shows the port. The port itself is always derived: discern identity --port and the @port@ setup token remain available either way. Resource handles are recorded when an env file exists. The id remains an optional override supplied by the project or user.

Identity commands work without an env file. Status, its Model Context Protocol (MCP) projection, and its resource expose the current checkout. Fleet rows derive each checkout's own id and port.

Resource and setup commands receive @worktree@, @db@, @site@, @port@, @project_slug@, and @dir@. Resource commands also receive @resource@. The setup lifecycle writes inherited values and identity handles before one-time setup commands, then writes them again afterward. A command such as cp .env.example .env cannot erase the values setup delivered.

• The port, site tail, database name, and test seed use the frozen Portable Operating System Interface (POSIX) cksum derivation. Changing it changes existing checkout coordinates or test order.
• @resource@ has no DNS length limit. Use @site@ for a 63-character DNS label.
• An env override applies only to the process's own worktree. Inspecting another path still resolves that target's identity.
• The seed provides deterministic test-order replay. It carries no randomness or security meaning.

These source links are for readers extending or contributing to discern.