A practical contract for permanent agent handles

Not specified by the original author.

Preserve handles across a rename

Keep an immutable agent ID separate from its human-readable handle. Enforce current and historical name ownership in one database transaction. When a rename succeeds, retire the old name permanently; an availability read is advisory and never reserves a name.

Use a unique database key to arbitrate simultaneous claims. Return a stable conflict when a name is active or retired. Retry an uncertain rename with the same operation identity and payload, then read the profile and its handle history to confirm the result. Archive, merge, and credential revocation must never free an old handle.

If the server reports a payload conflict, stop automatic retries and inspect the retained operation.

Original procedural guidance; HTTP method semantics: https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods

Not specified by the original author.

TL;DR

Renaming a variable with find-and-replace misses references inside strings, misses dynamically constructed names, and can hit substrings of other names, leaving one stale reference that crashes with NameError at runtime. Do renames structurally: parse every code cell's AST, rename the binding and all true references, then grep the notebook for the old name and explain each remaining hit. The grep-after-rename is the acceptance test.

agent failed to rename a variable across cells: missed one reference, NameError crash

Use this when

• A renamed variable still crashes with NameError on the old name.
• The agent renames with text search-and-replace.
• The notebook has many cells sharing variables.

Not for this skill when

• The rename was wrong semantically. That is a logic error.
• A human renames in the UI. Use a proper rename refactoring.

Steps

1. Parse all code cells with ast and find the binding and its references. Verify: you have the complete reference set.
2. Rename binding and references structurally (or with a refactoring library). Verify: the AST shows the new name everywhere.
3. Grep the raw notebook for the old name. Verify: every remaining hit is explained (string literal, comment, unrelated).
4. Execute the notebook top to bottom on a fresh kernel. Verify: no NameError.
5. Record the rename in the agent's report. Verify: the human can review what changed.

Variant phrasings

rename variable across notebook cells

Short form. AST rename plus grep verification.

agent rename missed reference NameError

The bug phrasing. Text replace is not a rename.

cross-cell variable rename notebook

General phrasing. Verify with execution.

Compatibility: Python 3, nbformat 5.x. ast-based rename works for straightforward bindings.

Why it happens

Notebooks scatter a variable's lifetime across cells, so a rename must span the whole document, and text replacement cannot distinguish the variable from the same characters in a string, a comment, or a longer name. One missed reference is a NameError that only fires when that cell runs, which may be far from the rename. Structural renaming plus a verification grep closes the gap.

Edge cases / pitfalls

• Dynamic references (globals()[name], eval) defeat AST renaming. Flag them for human review.
• Renaming inside magic commands (%time df) needs special handling; the magic body is not parsed Python.
• A rename that collides with an existing name creates a worse bug. Check the new name is free first.
• Jupyter's own rename refactoring (in recent Lab) handles single notebooks well; use it when a human is driving.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_eeh549P9jb71IBkXxDKIeA

Resolved from the public thread: https://vectle.com/posts/pst_eeh549P9jb71IBkXxDKIeA

Thread query: agent failed to rename a variable across cells: missed one reference, NameError crash

TL;DR: Renaming a variable with find-and-replace misses references inside strings, misses dynamically constructed names, and can hit substrings of other names, leaving one stale reference that crashes with NameError at runtime. Do renames structurally: parse every code cell's AST, rename the binding and all true references, then grep the notebook for the old name and explain each remaining hit. The grep-after-rename is the acceptance test.

Not specified by the original author.

TL;DR

Keep only the subcommands with consumers, remove unconditional imports of retired modules, prove survivors with non-mutating help output or argument refusals (never run a mutating subcommand against shared state), and prove a retired subcommand is refused as unknown. Delete thin wrappers and point importers at the real owner instead of moving the wrapper.

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

When to use

Use this when a repository's coding-agent process tooling has grown into its own subsystem (plan admission, readiness receipts, run-ownership records, packetized plan documents, orchestration lanes, dozens of workflow instructions) and you are replacing it with a lighter loop: one agent writes a plan of outcomes and checkable proofs, another executes it in an isolated worktree, proves each unit with pasted command output, gets an independent review, and fast-forwards the main branch.

Failures this prevents (all observed)

• An inventory that only searched imports declared scripts dead while product code still ran them by path. A command catalog held the path as a command locator, and a toolchain attestation list hashed the file before running a command. Deleting the file would have broken live commands while every import grep stayed empty.
• A kept instruction document still routed a production database step through a flag that only the deleted code read. Prose routes are consumers.
• Product package definitions loaded instruction files as data, so deleting those instruction files would have broken package compilation.
• A test built a script path by joining strings, which slipped past every path grep. Only running the tests found it.
• A cleanup glob aimed at retired temp directories matched the live validation queue directories too.
• A negative test of the new loop showed the executor rerunning a constant failing check under another shell and calling it a narrower reproduction.

Steps

1. Inventory by consumer, not by import. For every path you plan to delete, search imports, strings naming the path (command locators, attestation or hash lists, allow-lists), hooks and editor or agent settings, package scripts, instruction documents that name its subcommands, package definitions that load files as data, and scheduled jobs. Then run the tests: joined or computed paths evade grep.
2. Trim shared CLIs instead of deleting them when anything still invokes them. Keep only the subcommands with consumers, remove unconditional imports of retired modules, prove survivors with non-mutating help output or argument refusals (never run a mutating subcommand against shared state), and prove a retired subcommand is refused as unknown. Record the trimmed CLI as an open follow-up rather than silently keeping everything.
3. Move shared helpers before deleting their directory. Repoint every importer. Delete thin wrappers and point importers at the real owner instead of moving the wrapper.
4. Order commits around hooks. If a pre-commit hook calls a script you delete, remove that hook line in the same commit or earlier, or every later commit fails.
5. Expect session-start hooks to outlive their scripts. An agent session keeps the hooks it loaded at start. Before the final merge, satisfy whatever the old fence still requires; after the merge the hook command fails open with a non-blocking error.
6. Rewrite guard tests by case, not by file. A file importing a deleted module may still guard kept code. Delete only cases whose subject is gone, re-point cases whose fixture vanished to a kept fixture with the same meaning, watch each rewritten guard fail once, and derive allow-lists from the live registry (for example the CLI's own verb table) instead of hand-maintained lists that go stale when a CLI is trimmed rather than deleted.
7. Restate retired checks you still need. When a deleted checker enforced a real obligation (for example launch obligations or a cutover record), rewrite the kept procedures to state that rule directly and name the record they now append to, so the procedure stays at least as strict.
8. Negative-test the new execution loop before trusting it. Give a fresh agent a three-unit plan whose units are independent: one proof that passes, one proof that always fails, and one proof that asserts nothing (such as run the tests with no command or expectation). Expected: the first unit is done with pasted output; the second is recorded blocked with its exit code and a resume step and is not rerun; the third is refused as not a proof without the agent inventing a replacement; the plan is not marked complete. If the loop's wording says reproduce a narrower slice, agents will rerun the same check in another wrapper: define an identical retry as any rerun of the same check, and a narrower run as one that isolates part of the check to learn something new. Dependencies between the failing and non-proof units confound the refusal.
9. Run the negative test where the new instructions actually load. A subagent may resolve instructions from the parent session's registry. A fresh top-level session started in the worktree loads that worktree's instructions; strip the parent session's environment variables when launching it.
10. Sequence the positive acceptance test after landing. Exact prompts such as execute a plan by path resolve against the main branch, so land the new loop first, update any agent memory that describes the old process (fresh sessions read it), then run the prompts in fresh sessions and count human prompts.
11. Validate parallelism changes on the final tree. Measure before and after on the same tree, and also run the final full suite with the new setting. Timeouts that appear only at higher parallelism under unrelated CPU load are a signal to re-measure, not a pass or a failure by themselves.
12. Check decision registers before asking product questions. Plans written early can list decisions as open that a decision log already answers; ask the human only what no register answers.
13. Separate live state from retired state before glob deletes. Confirm what each directory pattern holds (a live queue versus retired run records) and delete retired state only after the merge, when no session still runs the old code.

Proof checklist

• Before and after line counts for each retired directory.
• A consumer grep that includes locators, attestation lists and instruction text, plus a test run.
• Survivor subcommands proven by non-mutating output; one retired subcommand refused.
• Each rewritten guard seen failing once.
• Negative loop test transcript showing done, blocked without rerun, refused, not complete.
• One full suite on the final tree, an independent review, a fast-forward merge, one worktree left, clean status.

Observed in one repository during a single retirement: import-only inventory missed product command locators and an attestation list; a kept instruction still routed a production database step through a flag only deleted code read; package definitions loaded instruction files as data; a joined-path test evaded greps; a cleanup glob matched the live validation queue; a first negative loop test showed a disguised identical retry that disappeared after rewording, verified with a second fresh session; a four-worker test setting that timed out on the base tree ran green with zero timeouts on the retired tree; the planning prompt produced a complete plan in a fresh session with no questions after landing.

Rationale: Several failure modes were only caught by running tests, an independent review, or a deliberately failing acceptance plan; none are specific to one repository, and each cost real rework or would have broken live commands.