devlyn-cli 4.2.3 → 4.2.5

package/bin/devlyn.js

@@ -880,6 +880,7 @@ function install(targets, global, optionalNames = []) {
     else installClaudeCore();
   }
   log(`\n✅ devlyn ${PKG.version} installed`, 'green');
+  if (global) log('The principles block installs per project: run npx devlyn-cli in the project without --global.');
   noticeGlobalDrift(roots);
   return roots;
 }

package/bin/skill-history.json

@@ -1,9 +1,11 @@
 {
-  "source": "devlyn-cli@4.1.0 (npm tarball sha1 398ff07d3d689b56cc22e18ac50260bc6e4e9e85); devlyn-cli@4.2.0 (npm tarball sha1 c93c2fb1cf5630b18d2eba0085182c14fddbe2d5); whole-tree fingerprints from bin/skill-ownership.js; deprecated commands: commands/ and optional-commands/*/ files of devlyn-cli 0.0.1-0.5.8 (every published version that shipped them), LF-normalized SHA-256",
+  "source": "devlyn-cli@4.1.0 (npm tarball sha1 398ff07d3d689b56cc22e18ac50260bc6e4e9e85); devlyn-cli@4.2.0 (npm tarball sha1 c93c2fb1cf5630b18d2eba0085182c14fddbe2d5); devlyn-cli@4.2.4 and 4.2.5 (_shared and devlyn-ideate, fingerprinted from an install of each packed tarball); whole-tree fingerprints from bin/skill-ownership.js; deprecated commands: commands/ and optional-commands/*/ files of devlyn-cli 0.0.1-0.5.8 (every published version that shipped them), LF-normalized SHA-256",
   "skills": {
     "_shared": [
       "eb3327d5e6940bd5e0459fa28c9ab323d9c58ccfdeb9426c19cd027cc4e5c4ed",
-      "8c80926ab03b2477e52264495b35c2116f65fc51b02e8c56e441b5705872392a"
+      "8c80926ab03b2477e52264495b35c2116f65fc51b02e8c56e441b5705872392a",
+      "3c81c575cc43d70488865b440204cb399091405d9b7f81dbf047a32d3d5ac045",
+      "6546d6b833701f2641a004802cfc17ec62442e5d0003f396cb0231b676ba9a4a"
     ],
     "devlyn-design-ui": [
       "91080266232fb62b6f1d45932184f065589e12eb66f02fb6442527c6dfcd81b6"
@@ -14,7 +16,9 @@
     ],
     "devlyn-ideate": [
       "8ff5148cc65b4608c35b29afd6fef20d42d8da93a094144d98cfc63e74089b6e",
-      "5824f07e455fe1c3942bf595a12e935258d4c0a851ca1bf741db915603d1c4e0"
+      "5824f07e455fe1c3942bf595a12e935258d4c0a851ca1bf741db915603d1c4e0",
+      "7f451e48e391643b34f6249244bc47d93d6303875e7b092771e3af0718343bc1",
+      "d6433bf0f96dd9dd485c3623885255738654674b3e23cfcc1a2cfd24f3cda96e"
     ],
     "devlyn-queue": [
       "4c7d988dcd154c7bf658d2d24cd7868955df9d854ed87eb784742d6d4bb229e0"

package/config/skills/_shared/role-config.py

@@ -102,7 +102,8 @@ def resolve(work, default_engine, *, available=None, shared=SHARED):
     """The project's executor pin, else the invoking CLI; status only, never a dispatch decision."""
     config, source = read_config(Path(work) / ".devlyn/engines.json", optional=True, shared=shared)
     engine = config.get("executor", default_engine)
-    adapter(engine, shared=shared)
+    # read_config validates pins; the invoking host needs no adapter to report its own default.
+    name(engine, "engine")
     available = available or (lambda candidate: shutil.which(candidate) is not None)
     return {"executor": {"engine": engine, "source": "engines.json" if "executor" in config else "default",
                          "availability": "CLI-present/auth-unchecked" if available(engine) else "CLI-unavailable"},
@@ -113,6 +114,7 @@ def select(work, default_engine, *, available=None, shared=SHARED):
     """The executor for dispatch. A pin is a promise: an unavailable pinned engine is never substituted."""
     result = resolve(work, default_engine, available=available, shared=shared)
     executor = result["executor"]
+    adapter(executor["engine"], shared=shared)
     if executor["source"] == "engines.json" and executor["availability"] == "CLI-unavailable":
         fail(f"pinned executor {executor['engine']} is unavailable; install and authenticate its CLI, "
              f"verify `{executor['engine']} --version`, and retry, or pin an available engine with `devlyn-engines executor <name>`",

package/config/skills/_shared/task-complete.py

@@ -22,6 +22,7 @@ import subprocess
 import sys
 import tempfile
 import unittest
+import uuid
 
 
 class CompletionError(Exception):
@@ -122,21 +123,22 @@ def verify_files(root, files):
 
 
 def custody(work, destination, files):
-    destination.mkdir(exist_ok=True)
-    for relative, expected in files.items():
-        source = safe_path(work, relative)
-        target = safe_path(destination, relative)
-        target.parent.mkdir(parents=True, exist_ok=True)
-        if not target.exists():
-            # Interrupted partial copies are diagnosed, never silently overwritten.
+    # Publish only a complete copy. A hard crash's private staging directory is never reused.
+    with tempfile.TemporaryDirectory(prefix=".custody-", dir=destination.parent) as temporary:
+        root = Path(temporary)
+        for relative, expected in files.items():
+            source = safe_path(work, relative)
+            target = safe_path(root, relative)
+            target.parent.mkdir(parents=True, exist_ok=True)
             with source.open("rb") as incoming, target.open("xb") as outgoing:
                 shutil.copyfileobj(incoming, outgoing)
                 outgoing.flush()
                 os.fsync(outgoing.fileno())
             target.chmod(expected["mode"])
-        require(file_record(target) == expected, f"custody copy mismatch; retain original: {relative}")
-    verify_files(work, files)
-    verify_files(destination, files)
+            require(file_record(target) == expected, f"custody copy mismatch; retain original: {relative}")
+        verify_files(work, files)
+        verify_files(root, files)
+        root.rename(destination)
     atomic_json(destination.parent / "manifest.json", files)
 
 
@@ -309,7 +311,12 @@ def bind_acceptance(receipt, path, supplied):
     else:
         raise CompletionError("acceptance kind must be direct|loop")
     files = snapshot_files(work, paths)
-    custody(work, path.parent / "custody", files)
+    destination = safe_path(path.parent, "custody")
+    if destination.exists():
+        # An unbound copy is never authoritative; retain it like an orphan staging directory.
+        require(destination.is_dir(), "custody is not a directory; retain and inspect")
+        destination.rename(path.parent / (".custody-" + uuid.uuid4().hex))
+    custody(work, destination, files)
     recovery = ref_sha(receipt, receipt["recovery_ref"])
     require(recovery in {None, sha}, "recovery ref changed")
     if recovery is None:
@@ -368,9 +375,14 @@ def gh(receipt, *args):
     return command(["gh", *args, "--repo", "github.com/"+receipt["repository"]])
 
 
+def repository_info(repository):
+    info = json.loads(command(["gh", "repo", "view", "github.com/"+repository, "--json", "nameWithOwner,url,defaultBranchRef,mergeCommitAllowed"]))
+    require(info["nameWithOwner"].lower() == repository.lower() and info["url"].lower() == "https://github.com/"+repository.lower(), "GitHub repository identity changed")
+    return info
+
+
 def repo_policy(receipt):
-    info = json.loads(command(["gh", "repo", "view", "github.com/"+receipt["repository"], "--json", "nameWithOwner,url,defaultBranchRef,mergeCommitAllowed"]))
-    require(info["nameWithOwner"].lower() == receipt["repository"].lower() and info["url"].lower() == "https://github.com/"+receipt["repository"].lower(), "GitHub repository identity changed")
+    info = repository_info(receipt["repository"])
     require(info["defaultBranchRef"]["name"] == receipt["base"] and receipt["branch"] != info["defaultBranchRef"]["name"], "base/default branch changed; retain resources")
     return info
 
@@ -792,7 +804,7 @@ def main():
     attachment = actions.add_parser("attach")
     attachment.add_argument("--receipt", required=True)
     attachment.add_argument("--commit", required=True)
-    attachment.add_argument("--file", default="docs/specs/queue.md")
+    attachment.add_argument("--file", required=True)
     completion = actions.add_parser("complete")
     completion.add_argument("--receipt", required=True)
     completion.add_argument("--acceptance")
@@ -1793,21 +1805,37 @@ class CompletionTests(unittest.TestCase):
 
     def test_custody_failure_and_evidence_tamper(self):
         self.allocate(); self.accept()
+        self.cli("accept", "--receipt", self.receipt, "--acceptance", self.acceptance)
         bad = self.receipt.parent / "custody/.devlyn/checks.txt"
-        bad.parent.mkdir(parents=True)
-        bad.write_text("partial interrupted copy", encoding="utf-8")
+        bad.write_text("corrupted bound copy", encoding="utf-8")
         _, r = self.complete("--writers-stopped", success=False)
         self.assertNotEqual(r.returncode, 0)
         self.assertTrue(self.task.exists())
         self.assertEqual((self.task / ".devlyn/checks.txt").read_text(encoding="utf-8"), "actual fixture check: accepted bytes\n")
         self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture"), "")
-        bad.unlink()  # Owner repairs only the identified corrupt fixture copy.
+        shutil.copy2(self.task / ".devlyn/checks.txt", bad)  # Repair only the identified corrupt fixture copy.
         self.complete("--mode", "pr")
         (self.task / ".devlyn/checks.txt").write_text("altered after acceptance", encoding="utf-8")
         _, r = self.complete("--mode", "auto", success=False)
         self.assertNotEqual(r.returncode, 0)
         self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("merges",0), 0)
 
+    def test_unbound_partial_custody_is_retained_through_cleanup(self):
+        self.allocate(); self.accept()
+        partial = self.receipt.parent / "custody/.devlyn/checks.txt"
+        partial.parent.mkdir(parents=True)
+        partial.write_text("partial interrupted copy", encoding="utf-8")
+        original = file_record(partial)
+        result, _ = self.complete("--writers-stopped", "--mode", "auto")
+        self.assertEqual(result["status"], "COMPLETE")
+        self.assertEqual(result["scratch_cleanup"]["status"], "CLEAN")
+        self.assertFalse(self.task.exists())
+        retained = list(self.receipt.parent.glob(".custody-*"))
+        self.assertEqual(len(retained), 1)
+        self.assertEqual(file_record(retained[0] / ".devlyn/checks.txt"), original)
+        self.assertEqual(self.complete(acceptance=False)[0]["status"], "COMPLETE")
+        self.assertEqual(file_record(retained[0] / ".devlyn/checks.txt"), original)
+
     def test_actual_foreign_writer_and_registration(self):
         # H4. Prediction: a process still using the merged task's tree settles the delivery COMPLETE with the workspace
         # retained (CLEANUP_PENDING) and the process named, as unobservable writers do. Before: complete ended BLOCKED
@@ -2118,6 +2146,12 @@ class CompletionTests(unittest.TestCase):
                 result, _ = self.cli("accept", "--receipt", self.receipt, "--acceptance", acceptance, success=False)
                 self.assertEqual(result["status"], "FAILED" if verdict == "FAILED" else "BLOCKED", result)
 
+    def test_attach_requires_an_explicit_queue_file(self):
+        result = self.run_cmd([sys.executable, str(Path(__file__).resolve()), 'attach',
+                               '--receipt', str(self.root / 'absent.json'), '--commit', 'HEAD'], success=False)
+        self.assertEqual(result.returncode, 2, result.stdout + result.stderr)
+        self.assertIn('the following arguments are required: --file', result.stderr)
+
     def test_attach_requires_the_terminal_checkout_only_for_a_publishable_result(self):
         for verdict in ("ACCEPTED", "FAILED"):
             with self.subTest(verdict=verdict):

package/config/skills/devlyn-ideate/SKILL.md

@@ -100,6 +100,8 @@ Run `python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" status --repo .` and report it
 
 ## drain
 
+`status`, `add` and `drain` write the repository's Git directory, and auto/pr delivery needs network access, so a sandboxed host runs them with escalation or full access.
+
 Follow [loop.md](references/loop.md). The executor is the configured route, the `.devlyn/engines.json` `executor` pin or else this CLI, checked per `_shared/engine-preflight.md`. Pass its argv after `--`. `<git dir>` is the output of `git rev-parse --path-format=absolute --git-common-dir`, where the executor commits and writes its submission; the drain fills `{worktree_git_dir}` with the task worktree's own Git directory, which Codex's sandbox keeps read-only unless that exact directory is listed:
 
 | Executor | argv |

package/config/skills/devlyn-ideate/references/loop.md

@@ -11,7 +11,7 @@ python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" drain --repo . [--local-only] [--wo
 
 Both print one JSON object; exit 1 is `BLOCKED` with a `reason`.
 
-- `status` writes nothing beyond finishing `add`'s cleanup (step 1): reconciled counts (`pending`, `active`, `accepted`, `failed`, `blocked`, `legacy_pending`), the `next` task, `blockers`, deliveries still pending with their resume (drain again until the terminal commit is attached, then `task-complete.py complete --receipt <receipt>`), and under `cleanup` the package copies `add` kept or could not remove.
+- `status` takes `queue.lock` in the repository's Git directory and finishes `add`'s cleanup (step 1); it reports reconciled counts (`pending`, `active`, `accepted`, `failed`, `blocked`, `legacy_pending`), the `next` task, `blockers`, deliveries still pending with their resume (drain again until the terminal commit is attached, then `task-complete.py complete --receipt <receipt>`), and under `cleanup` the package copies `add` kept or could not remove.
 - `drain` ends `DRAINED` (no runnable task remains; open deliveries show per task), `WAITING` (a task waits with its reason, or legacy rows need planning) or `BLOCKED` (conflict, invalid input or a recovery blocker). Progress lines `devlyn-loop: <task>: <event>` go to stderr.
 - `--local-only` (alias `--no-push`) keeps the loop local. A manifest `delivery: local-only` and any earlier local receipt of the loop keep that restriction for later drains. A local loop needs no remote; nothing is fetched or pushed. An `auto`/`pr` loop none of whose tasks has a pushed PR runs as a local loop from its capture and the branch it was added on. Once one has, that PR is never rewritten to local and the loop is never run locally: its tasks wait, naming the PR, while other work continues.
 - Worktrees default to `<repo parent>/<repo name>.devlyn/<loop-id>/<task-id>`.
@@ -41,6 +41,7 @@ The host supplies the executor and maps its configured engine to the argv; the l
     | Inputs commit | A branch head equal to the expected inputs tree is adopted; anything else blocks. |
     | During execution | Each attempt's start is recorded before its spawn and its exit after it. A start without an exit waits until task-complete observes no process using the worktree, then adopts the submission that executor wrote or runs the executor again; where writers cannot be observed (native Windows) the task becomes `[F] interrupted-unobservable` with its workspace retained, its dependents become prerequisite-blocked and independent work continues. Exactly-once execution is not promised. |
     | During checks | Acceptance reruns; incomplete evidence stays unreferenced. |
+    | During custody binding | Acceptance reruns while the receipt is unbound. Any unbound custody copy, complete or partial, is set aside in a unique hidden sibling before fresh custody is published; it and orphan staging copies stay retained and unreferenced. A bound receipt resumes its original result with strict evidence validation. |
     | Accepted, before terminal commit | Only the missing transition is created. |
     | Terminal committed, before attachment | The commit is validated and attached, also when attachment already moved the recovery ref; nothing reruns. |
     | Terminal committed, before delivery | Only the missing delivery effects run. |

package/config/skills/devlyn-ideate/scripts/queue.py

@@ -843,9 +843,9 @@ def evidence_ignored(anchor, common, start):
 
 
 def allocate(v, row, opts):
-    """Allocate the task's owned worktree, or return why it waits: origin names no GitHub repository, or its refreshed
-    remote base holds another version of the loop's package or lacks the checkout's instructions (waiting() checks a local
-    start before selection)."""
+    """Allocate the task's owned worktree, or return why it waits: origin names no GitHub repository, its base is not the
+    default, or its refreshed remote base holds another version of the loop's package or lacks the checkout's instructions
+    (waiting() checks a local start before selection)."""
     identity, loop, task = row["identity"], row["loop"], row["task"]
     package = v["packages"][loop]
     manifest = package["manifest"]
@@ -868,6 +868,13 @@ def allocate(v, row, opts):
         except helper["CompletionError"]:
             return (f"{manifest['delivery']} delivery needs an origin remote of the form https://github.com/<owner>/<repo>, "
                     "git@github.com:<owner>/<repo> or ssh://git@github.com/<owner>/<repo>; set one, or drain with --local-only")
+        try:
+            default = helper["repository_info"](values["repository"])["defaultBranchRef"]["name"]
+        except (helper["CompletionError"], OSError, KeyError, TypeError, ValueError) as exc:
+            return f"cannot check delivery repository: {exc}"
+        if manifest["base_ref"] != default:
+            return (f"{manifest['delivery']} delivery base {manifest['base_ref']} is not the repository's default branch {default}; "
+                    f"plan the loop on {default}, or drain with --local-only")
         try:
             start = helper["remote_base"]({"common_gitdir": str(common), "remote": "origin", "base": manifest["base_ref"]})
         except helper["CompletionError"] as exc:
@@ -1069,6 +1076,8 @@ def advance(v, row, opts):
         except LoopError as exc:
             return f"delivery blocked: {exc}"
         progress(identity, f"delivery {result['status']}")
+        if result.get("merge_refused"):
+            return f"merge refused: {result['merge_refused']}; a person merges the PR"
     return None
 
 
@@ -1093,9 +1102,11 @@ def summary(v, row):
                     questions=[r.removeprefix("needs-review: ") for r in acceptance_record.get("reasons", []) if r.startswith("needs-review: ")],
                     worktree=receipt["worktree"] if receipt.get("worktree") and Path(receipt["worktree"]).exists() else None,
                     cleanup=f"{c['status']} — {c['reason']}; resume: {c['resume']}" if (c := receipt.get("workspace_cleanup")) else None,
-                    branch=receipt.get("branch"), recovery_ref=receipt.get("recovery_ref"),
+                    branch=receipt.get("branch") if receipt.get("branch") and ref_value(v["anchor"], "refs/heads/" + receipt["branch"]) else None,
+                    recovery_ref=receipt.get("recovery_ref"),
                     custody=str(Path(state["path"]).parent / "custody") if receipt.get("files") else None,
-                    scratch=(receipt.get("scratch_cleanup") or {}).get("status", "NOT_CLEANED"))
+                    scratch=(f"{c['status']} — {c['reason']}; resume: {c['resume']}" if (c := receipt.get("scratch_cleanup") or {}).get("reason")
+                             else c.get("status", "NOT_CLEANED")))
     return item
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "4.2.3",
+  "version": "4.2.5",
   "description": "Loop & harness engineering for AI coding agents (Claude Code, Codex, and any AGENTS.md-driven agent) — core engineering principles for CLAUDE.md/AGENTS.md and a loop designer that splits one intent into tasks agents drain hands-free",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {