NEEDLE: Instructions file for Codex

NEEDLE Codex Guide

This file is the primary operating guide for Codex in this repository, both in interactive sessions and when Codex runs headlessly as a NEEDLE worker. Inspect the current repository state and the relevant source before relying on older examples or planning documents.

Project Overview

NEEDLE (Navigates Every Enqueued Deliverable, Logs Effort) is a Rust worker binary. It selects and claims work through the repository's configured bead backend, dispatches a coding agent, records telemetry, and routes every outcome through an explicit state machine.

The primary backend is bead-rs (bead); bead-forge (bf) remains supported for explicitly bound legacy workspaces. Check .needle.yaml and the .beads/ layout before running either CLI. Do not infer the backend from which binaries happen to be installed, and never use one backend's repair or import command on the other backend's database. br is retired and must not be introduced in source, prompts, scripts, tests, or documentation.

Working Safely

• Inspect git status --short before editing. Preserve unrelated user and worker changes in a dirty worktree.
• Multiple NEEDLE workers may share the same repository. Re-check files before modifying them and avoid broad rewrites that can overwrite concurrent work.
• Do not create per-worker git worktrees to isolate concurrent workers — a shared checkout is the intended model, not a bug to route around. Worktrees add disk and build-cache duplication without addressing the actual failure mode, which happens at the bead level: the same bead getting claimed and worked twice (confirmed 2026-08-09, commitgraph cg-l0v0kc — two byte-identical commits at the same second from two concurrent workers). The supported backends provide atomic claim operations, so avoid this by decomposing and dependency-ordering beads so the same unit of work is never independently claimable twice — see the target repo's own AGENTS.md for repo-specific guidance.
• A disposable clone under ~/scratch is the same thing as a worktree for this purpose, and the rule above covers it. git clone into a mktemp -d is the usual way this rule gets routed around: it satisfies the letter (no git worktree) while costing the identical disk. On 2026-08-21 there were 241 of them on ex44 — ~/scratch at 95G, each a full clone plus a Rust target/ — and the root filesystem reached 100%, which fails writes with ENOSPC for every agent on the box, not just the one that filled it. Work in the shared checkout. If a disposable checkout is genuinely warranted, the thing that creates it owns removing it: mktemp -d with a trap that cleans on success and deliberately leaves the tree on failure for diagnosis. Do not file cleanup as its own bead — fleet workers share no filesystem, so a cleanup bead can be claimed by a worker that cannot see the directory. A startup sweep is the backstop (needle-f40a5de7).
• Do not use destructive Git operations (reset --hard, forced checkout, forced push) to resolve unrelated changes.
• Never advance a branch ref without its tree. In a shared checkout, do not move main (or any branch) with git update-ref, git reset --soft, or git branch -f. Each moves the ref and leaves the index and working tree where they were, so every file the skipped commits changed now reads as a staged revert of them, and the next pathspec commit of such a file silently undoes another worker's commit. Workers did exactly this to ~/NEEDLE (git update-ref refs/heads/main <origin/main>, about twenty times from 2026-10-07) and left the checkout 85 files and 9,959 lines behind HEAD by 2026-10-16 (needle-8879251b). To pick up origin/main, run git merge --ff-only origin/main, which moves the ref, index and worktree together; if local commits have diverged, reconcile with a merge commit, never a rebase or a force-push. If a dirty tree or staged files block the merge, stop and report the blocking paths on the bead — do not move the ref by hand, and do not stash, reset or check out other workers' files to clear the way. needle audit reports a checkout whose tracked files hold older committed content than HEAD as F7_STALE_TREE_DRIFT.
• Forgejo (git.ardenone.com) is the authoritative remote. GitHub is a mirror. Push only to the configured origin, and never use --force or --force-with-lease.
• Keep commands suitable for unattended execution: avoid prompts, pagers, and commands that require an interactive terminal.
• Treat docs/plan/plan.md as architecture and design history. Verify current behavior in source and against the installed CLI before depending on old command examples.