Tvijo wiki
Catalog

Topics

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

📚 You will learn
  • 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 /root are 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
100%
→ Linked articles← Linked from⋯ Same topic
Article links · keyboard / text view

💬 Comments

Comments are public and moderated. Do not post personal data.
  • No comments yet. Be the first!

Next steps