DSHREM owner practice: cwd, worktrees, WIP, and root boundaries
Learn to record the current directory and Git state, protect existing work, and give an agent an isolated clean worktree. This lesson separates Linux identity, tool policy, and repository ownership, then treats the advertised root alias as a candidate until its implementation is verified.
🎯 For Project owners and operators preparing a repository for agent work
- Capture cwd and a complete Git status before starting work
- Create an isolated branch and worktree without disturbing shared WIP
- Diagnose protected workspace refusals without bypassing them
Practice
Lesson 1 — establish cwd and the WIP baseline
Goal: prove which repository and directory a task will use, then record pre-existing work. A terminal prompt or VS Code title alone is not enough.
Exact commands from a repository:
pwd
git rev-parse --show-toplevel
git status --short --untracked-files=all
git branch --show-current
Expected result: pwd identifies the current directory, Git prints the repository root and branch, and status lists every changed or untracked path. Save this output in the task receipt. Treat every listed path as owned by someone unless a user identifies it as in-scope. A clean-looking status is a point-in-time observation, not a lock against concurrent edits.
Common mistake: using git status --short without untracked files, then overwriting a directory that contains untracked work. Include --untracked-files=all; do not infer ownership from filenames, timestamps, or the fact that a path resembles the requested feature.
Lesson 2 — isolate the task in a worktree
Goal: create a new branch and working directory from a known base while leaving the original checkout intact. Select a task branch name that does not already exist and a new destination path.
Exact commands from the original repository:
git fetch origin
git worktree list
git worktree add -b codex/mobile-course /tmp/codex-mobile-course origin/main
cd /tmp/codex-mobile-course
git status --short --untracked-files=all
git rev-parse --show-toplevel
Replace the illustrative branch and path with unique values. If the task must start from a pinned review commit, use that reviewed commit as the base instead of origin/main. Do not use git worktree prune as cleanup in a shared checkout.
Expected result: git worktree list shows both directories; the new checkout names the new branch and reports a clean status. Original user WIP remains in its original worktree. Before any commit, stage only the task's exact paths and check the resulting diff.
Common mistake: work in the shared checkout because its branch name looks right. Another is to create a new worktree from the wrong base or reuse an existing branch. Check both the path and commit before edits. Do not remove the other tree if setup fails; preserve it and inspect its state.
Lesson 3 — distinguish identity, policy, and ownership
Goal: understand why Linux UID 0, a tool mode called root, and authority to edit a path are separate facts. Check identity and policy independently:
id
pwd
git status --short --untracked-files=all
Expected result: id prints operating-system identity; pwd prints cwd; Git status reports repository content. A process can run as UID 0 while an application blocks a path. The --root flag selects explicit local owner mode. It does not widen tool grants, elevate Linux UID or bypass budgets, audit or WIP protection.
Common mistake: interpreting “root” as permission to overwrite protected work. The DSHREM CLI source explicitly checks dirty paths and refuses unapproved writes. The bash_requires_unprotected_workspace refusal is defined in deploy/dshrem/guards.mjs when baseline WIP is protected from arbitrary shell code. ROOT keeps this protection; use path-checked file tools or a separate clean worktree.
Check yourself
Before a real task, can you identify the repository root, current branch, exact WIP paths, target worktree, and task allowlist? Can you explain why UID 0 does not cancel a protected-path refusal? Continue to economy swarm practice; the preceding phone terminal practice covers remote session recovery. For the general context model, see agent memory and context engineering.
When this does not work
If git rev-parse fails, you are not in a Git worktree or are inside an unusual path; stop and locate the intended repository before any write. If git worktree add says the branch exists, choose a fresh branch name after listing branches. If the destination exists, do not overwrite it. If status changes after your baseline, another writer may be active; pause edits to overlapping files and compare the new state. If a guard names a protected path, narrow the task or move to an isolated tree. Do not add a bypass flag to silence the guard.
Evidence
On 8 November 2026 UTC, read-only inspection of scripts/dshrem_cli.py showed a protected(cwd, touched) routine that reads porcelain Git status including untracked paths and supports an explicit dirty-path allowance; its run path records cwd and checks a bounded set of paths. The current source also maps / or /root session cwd back to its configured repository root in one path. The updated client and adapter implement dshrem --root and -root, with tests for project ownership and no UID escalation. The release receipt separately records installation. Linux UID, tool policy and repository contents remain distinct checks.
Next
Pair this lesson with phone terminal practice for a safe SSH and tmux entry point. Continue to economy swarm practice before submitting worker tasks. For evidence review, use AI judging and cost per accepted task.
Sources
scripts/dshrem_cli.py— cwd handling, dirty-path inspection, and session setup.scripts/dshrem_subscription.py— cwd must be a scoped directory;/and/rootare refused.AGENTS.md— shared worktree ownership, baseline capture, and non-destructive rules.- Evidence and source verification — handling dated claims and incomplete observations.
Verified owner launch and refusal diagnosis
Goal: open one owner session without confusing the mode with system privilege elevation.
id -u
pwd
dshrem --root doctor
dshrem --root
The alias is dshrem -root. Expected result: a visible ROOT notice with the current Linux UID, then one input area and one short status. Doctor checks the runtime without a model request; entering an agent task starts a separately budgeted request. Ordinary dshrem keeps ordinary restrictions. A nonowner receives a local-owner refusal and can continue in a worktree they own.
Typical error: bash_requires_unprotected_workspace is emitted by deploy/dshrem/guards.mjs when baseline WIP is protected. ROOT does not bypass it. Use path-checked read/edit tools, or the clean worktree from Lesson 2. Only for your own specifically named WIP may you pass dshrem run --allow path/to/your-file; this is an explicit path grant, never permission for foreign WIP. Never use chmod 777, clean/reset or a global guard switch.
🔗 Article connections
Open the full knowledge graph ↗Published article links. Select a node to open its article at the heading.
Show the connection graph
Article links · keyboard / text view
Same topic
- Tvijo agent system: PRIZMA, RUNLEDGER and acceptance
- Read agent communication receipts without mistaking delivery for a human read
- Audit an AI technology radar against primary sources before promoting a story
- Run an AI coding harness evaluation offline before any live pilot
- DSHREM on a phone: SSH, tmux, and safe task handoff
- DSHREM economy swarm: checkpoints, routes, and real cost evidence
Next steps
Related reading
Tvijo agent system: PRIZMA, RUNLEDGER and acceptance
Tvijo is developing a controlled workflow from a repository task to an accepted result, with permissions, resource limits and attributable evidence. PRIZMA describes the intended resource profile; RUNLEDGER connects the work to its checks a…
AI and process foundationRead agent communication receipts without mistaking delivery for a human read
Find the current stage of a swarm message without confusing durable storage, delivery, runtime receipt and viewing. This guide connects local checks, the private observation screen and distinct receipts, so a delivery acknowledgement does not become an unsupported claim that an action completed.
AI and process foundationAudit an AI technology radar against primary sources before promoting a story
Check a technology news item against its primary source, version and event date before deciding to adopt it. This guide follows a fixed ten-item sample, separates facts from interpretation and forecasts, and preserves limitations and the condition for checking the claim again.
💬 Comments