handoff-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{handoff_cli-0.3.0 → handoff_cli-0.3.1}/CLAUDE.md

@@ -12,7 +12,14 @@ A CLI proxy that dispatches coding tasks to configurable AI backends — Claude
 # Install: uv tool install -e .  then run init
 handoff --help
 
-# Dispatch a task
+# Pre-allocate a run_id and get the canonical prompt file path
+p=$(handoff new --backend deepseek --slug fix-auth)
+cat > "$p" <<'EOF'
+...prompt...
+EOF
+handoff run --backend deepseek "$p"
+
+# Other dispatch modes (allocate seq automatically)
 echo "Refactor X and add tests" | handoff run -
 handoff run --text "smoke test"
 handoff run --backend codex --pro - <<'EOF'
@@ -20,7 +27,7 @@ handoff run --backend codex --pro - <<'EOF'
 EOF
 
 # Browse/manage past runs
-handoff list             # interactive TUI (curses) when stdout is a terminal
+handoff list             # interactive TUI (curses) when stdout is a terminal; `handoff ls` is an alias
 handoff resume <seq>     # reopen a past conversation interactively in claude/codex
 handoff resume <seq> -   # dispatch a follow-up task to that conversation (heredoc)
 handoff tail <run-id>    # live-tail a run's output stream
@@ -40,7 +47,7 @@ There are no test suites or linting setup in this repo.
 
 ### Command dispatch (`cli/main.py`)
 
-`main()` parses `sys.argv[1]` and dispatches to the matching `cli/commands/<subcmd>.py`. Known commands: `run`, `list`, `resume`, `tail`, `env`, `init`. Before dispatching, `_migrate_legacy_state()` checks for a legacy `~/.ds-cli/` directory and renames it to `~/.handoff/` if the new directory doesn't exist yet. `env` and `init` do NOT initialize `Config`; other subcommands do (validates user config, creates DB).
+`main()` parses `sys.argv[1]` and dispatches to the matching `cli/commands/<subcmd>.py`. Known commands: `run`, `new`, `list`/`ls`, `resume`, `tail`, `env`, `init`. Before dispatching, `_migrate_legacy_state()` checks for a legacy `~/.ds-cli/` directory and renames it to `~/.handoff/` if the new directory doesn't exist yet. `env` and `init` do NOT initialize `Config`; other subcommands do (validates user config, creates DB).
 
 ### Config (`cli/config.py`)
 
@@ -50,8 +57,9 @@ Two-layer split: `cli/backend_types.yaml` (mechanism) defines HOW each type is l
 
 All state lives under `~/.handoff/`:
 - `runs/handoff.db` — SQLite (WAL mode) with `runs` table (seq, run_id, uuid, session_id, cwd, prompt, jsonl_path, status, backend) and `run_counters` (daily auto-increment per day). `session_id` is the underlying conversation: equals `uuid` for a fresh run, or the parent's `session_id` for a `resume` continuation. `get_db()` performs in-place `ALTER TABLE` migrations to add `session_id` (backfilled from `uuid`) on old databases.
-- `tasks/` — per-run files: `{run_id}.prompt.txt`, `.out.txt` (progress), `.result.md` (final)
-- Run IDs: `hd-<MMDD>-<SEQ_CODE>` where SEQ_CODE is a 2-char encoding: `01`–`99` for 1–99, then `A0`–`ZZ` for 100–1035
+- `tasks/` — per-run files: `{run_id}.prompt.md`, `.out.txt` (progress), `.result.md` (final)
+- Run IDs: `<mmdd>-<backend2>-<SEQ_CODE>-<slug>` (e.g. `0611-ds-03-fix-auth`). `<backend2>` is a 2-char abbreviation: deepseek→ds, codex→cx, opus→op, others→first 2 chars. SEQ_CODE is a 2-char encoding: `01`–`99` for 1–99, then `A0`–`ZZ` for 100–1035. `<slug>` is ≤3 dash-separated lowercase words supplied by caller; automatic slugs: stdin→`from-stdin`, --text→`from-text`, external file→`from-file`, no-slug→`task`.
+- `handoff new --backend <name> [--slug <slug>]`: pre-allocates a seq/run_id and prints the canonical `.prompt.md` path (does NOT create the file or DB row). Caller writes prompt to this path, then `handoff run <path>` adopts it.
 - Automatic migration: on startup, if `~/.ds-cli/` exists and `~/.handoff/` doesn't, the entire directory is renamed and `dscli.db` becomes `handoff.db`
 
 ### Backend resolution (`cli/backend.py`)
@@ -91,10 +99,10 @@ Textual-based interactive listing for `handoff list`. Renders a scrollable `Data
 ### Skill/subagent files
 
 All files live in `cli/skills/` (distributed with the wheel):
-- `handoff-ds/SKILL.md` — Claude Code skill for DeepSeek backend (`--backend deepseek`)
-- `handoff-codex/SKILL.md` — Claude Code skill for Codex backend (`--backend codex`)
-- `handoff-opus/SKILL.md` — Claude Code skill for Opus backend (`--backend opus`)
-- `handoff-ds.toml` — Codex subagent that forwards prompt files via `handoff run --backend deepseek <prompt-file> >/dev/null`
+- `handoff-ds/SKILL.md` — Claude Code skill for DeepSeek backend (`--backend deepseek`). Protocol: `handoff new --backend deepseek --slug <slug>` → write prompt to returned path → `handoff run --backend deepseek <path>`
+- `handoff-codex/SKILL.md` — Claude Code skill for Codex backend (`--backend codex`). Same protocol with `--backend codex`.
+- `handoff-opus/SKILL.md` — Claude Code skill for Opus backend (`--backend opus`). Same protocol with `--backend opus`.
+- `handoff-ds.toml` — Codex subagent. Caller runs `handoff new --backend deepseek --slug <slug>`, writes prompt to returned path, passes `PROMPT_FILE=<path>` to subagent; subagent runs `handoff run --backend deepseek <PROMPT_FILE> >/dev/null`
 
 `handoff init` creates hard/soft links from `cli/skills/` into `~/.codex/agents/` and `~/.claude/skills/`.
 

{handoff_cli-0.3.0 → handoff_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoff-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: Multi coding-agent task dispatcher — a CLI proxy for claude that sends coding tasks to configurable AI backends
 Requires-Python: >=3.9
 Requires-Dist: pyyaml<7,>=6

{handoff_cli-0.3.0 → handoff_cli-0.3.1}/README.md

@@ -1,23 +1,23 @@
 <div align="center">
 
 # handoff
+**Your coding agents should be collaborating with each other.**
 
-**Your coding agents should be delegating to each other.**
 
-Hand work off to DeepSeek from inside Claude Code / Codex and save your flagship quota;
-hand a hard problem off to Codex / Opus from inside a DeepSeek session and borrow a brain.
-No tool-switching, no lost context.
+<img src="assets/handoff-hero.jpg" width="100%" alt="hero">
+
 
-[![PyPI](https://img.shields.io/pypi/v/handoff-cli)](https://pypi.org/project/handoff-cli/)
-[![Python](https://img.shields.io/pypi/pyversions/handoff-cli)](https://pypi.org/project/handoff-cli/)
+| From | → Hand off to | Why |
+| :-- | :-- | :-- |
+| Claude Code / Codex | **DeepSeek** | Execution work is fast and cheap; save flagship quota for decisions |
+| DeepSeek | **Codex / Opus** | Borrow a brain for hard problems, bring the answer back to your session |
+
+No tool-switching, no lost context.
 
 **English** · [简体中文](README.zh-CN.md)
 
 </div>
 
-<!-- assets/claude-code.jpg — ~720px wide — hero shot: one-sentence dispatch in Claude Code, main session only echoes RESULT=, agent reads .result.md and reports back -->
-<img src="assets/claude-code.jpg" width="720" alt="Handing a task off to DeepSeek from Claude Code">
-
 ## Why handoff
 
 If you juggle more than one coding agent, these will sound familiar:
@@ -63,15 +63,16 @@ handoff init
 
 ## Who you can hand work off to
 
-| Prompt / agent | Delegates to | Under the hood | Best for |
+| What you say | From | Hands off to | Best for |
 | --- | --- | --- | --- |
-| `/handoff-ds` | DeepSeek V4 | `claude -p` (DeepSeek's Anthropic-compatible endpoint) | Execution work: writing code, running tests, refactors, bulk edits |
-| `/handoff-codex` | Codex (GPT-5.5) | `codex exec` | Heavy reasoning, second opinions, gnarly debugging |
-| `/handoff-opus` | Claude Opus | `claude -p` | Decisions that deserve the top model |
+| `/handoff-ds` | Claude Code | DeepSeek V4 | Execution work: writing code, running tests, refactors, bulk edits |
+| `handoff-ds` (subagent) | Codex | DeepSeek V4 | Same as above — use this when you're inside Codex |
+| `/handoff-codex` | Claude Code | Codex (GPT-5.5) | Heavy reasoning, second opinions, gnarly debugging |
+| `/handoff-opus` | Claude Code | Claude Opus | Decisions that deserve the top model |
 
-> Codex has no slash commands; use the subagent of the same name instead — say "have `handoff-ds` execute the task above."
+> Codex has no slash commands, so that row is the subagent of the same name — say "have `handoff-ds` execute the task above."
 
-All three targets work out of the box: opus / codex reuse your local logins with zero config; deepseek only needs a token.
+All three targets work out of the box: opus / codex reuse your local logins with zero config; deepseek only needs a token. Under the hood they run `claude -p` (deepseek via its Anthropic-compatible endpoint, opus via your local login) and `codex exec`.
 
 ## After a task is dispatched
 
@@ -81,7 +82,7 @@ Dispatching and resuming are the AI's job (`handoff run` / `handoff resume` unde
 <tr>
 <td width="50%" valign="top">
 
-**`handoff list`** — interactive TUI over your full task history. Read the full prompt, live status, and final result; press `G` on a row to reload that conversation and keep chatting.
+**`handoff list` / `handoff ls`** — interactive TUI over your full task history. Read the full prompt, live status, and final result; press `G` on a row to reload that conversation and keep chatting.
 
 </td>
 <td width="50%" valign="top">
@@ -170,19 +171,6 @@ backends:
     ...
 ```
 
-Want another Anthropic-compatible endpoint? Add a block under `backends`:
-
-```yaml
-backends:
-  kimi:
-    type: claude
-    model: kimi-k3
-    env:
-      ANTHROPIC_BASE_URL: https://api.moonshot.cn/anthropic
-      ANTHROPIC_AUTH_TOKEN: "${MOONSHOT_API_KEY}"
-      ANTHROPIC_MODEL: "{model}"
-```
-
 The env block is entirely yours — every key=value you set is exported before the CLI launches. `{model}` substitutes the resolved model name, `${ENV_VAR}` expands from your shell.
 
 Run `handoff env` to see where everything lives. Full details: **[configuration docs →](docs/configuration.zh-CN.md)**.

{handoff_cli-0.3.0 → handoff_cli-0.3.1}/README.zh-CN.md

@@ -1,23 +1,23 @@
 <div align="center">
 
 # handoff
+**你的 coding agent 们，该互相协作了。**
 
-**你的 coding agent 们，该互相派活了。**
 
-在 Claude Code / Codex 里把活儿 handoff 给 DeepSeek，省下旗舰额度；
-在 DeepSeek 会话里把难题 handoff 给 Codex / Opus，借个脑子。
-不用切来切去，也不丢上下文。
+<img src="assets/handoff-hero.jpg" width="100%" alt="hero">
+
 
-[![PyPI](https://img.shields.io/pypi/v/handoff-cli)](https://pypi.org/project/handoff-cli/)
-[![Python](https://img.shields.io/pypi/pyversions/handoff-cli)](https://pypi.org/project/handoff-cli/)
+| 从 | → 派给 | 为什么 |
+| :-- | :-- | :-- |
+| Claude Code / Codex | **DeepSeek** | 执行性工作又快又便宜，旗舰额度留给决策 |
+| DeepSeek | **Codex / Opus** | 难题借个脑子，答案带回当前会话 |
+
+不用切来切去，也不丢上下文。
 
 [English](README.md) · **简体中文**
 
 </div>
 
-<!-- assets/claude-code.jpg — 建议 720 宽 — 主演示图：Claude Code 里一句话派发，主会话只回显 RESULT=，完成后读 .result.md 汇报 -->
-<img src="assets/claude-code.jpg" width="720" alt="在 Claude Code 里把任务 handoff 给 DeepSeek">
-
 ## 为什么需要 handoff
 
 如果你同时用着几家 coding agent，这些场景你一定眼熟：
@@ -63,15 +63,16 @@ handoff init
 
 ## 可以把活儿派给谁
 
-| 提示词 / agent | 派给谁 | 底层 | 适合 |
+| 你怎么说 | 从 | 派给 | 适合 |
 | --- | --- | --- | --- |
-| `/handoff-ds` | DeepSeek V4 | `claude -p`（DeepSeek Anthropic 端点） | 写代码、跑测试、重构、批量修改等执行性工作 |
-| `/handoff-codex` | Codex (GPT-5.5) | `codex exec` | 复杂推理、第二意见、疑难调试 |
-| `/handoff-opus` | Claude Opus | `claude -p` | 需要顶级模型出马的关键决策 |
+| `/handoff-ds` | Claude Code | DeepSeek V4 | 写代码、跑测试、重构、批量修改等执行性工作 |
+| `handoff-ds`（subagent） | Codex | DeepSeek V4 | 同上——你人在 Codex 里时走这条 |
+| `/handoff-codex` | Claude Code | Codex (GPT-5.5) | 复杂推理、第二意见、疑难调试 |
+| `/handoff-opus` | Claude Code | Claude Opus | 需要顶级模型出马的关键决策 |
 
-> Codex 里没有 slash 命令，对应的是同名 subagent：说「让 `handoff-ds` 执行上述任务」即可。
+> Codex 里没有 slash 命令，所以那行是同名 subagent：说「让 `handoff-ds` 执行上述任务」即可。
 
-三个目标开箱即用：opus / codex 走你本机的登录态，零配置；deepseek 只需 token。
+三个目标开箱即用：opus / codex 走你本机的登录态，零配置；deepseek 只需 token。底层分别是 `claude -p`（deepseek 走其 Anthropic 端点，opus 走本机登录态）和 `codex exec`。
 
 ## 任务派出去之后
 
@@ -81,7 +82,7 @@ handoff init
 <tr>
 <td width="50%" valign="top">
 
-**`handoff list`** — 交互式 TUI，浏览全部历史任务。看 prompt 全文、实时状态、最终结果；选中按 `G` 直接把那次会话重新加载进来接着聊。
+**`handoff list` / `handoff ls`** — 交互式 TUI，浏览全部历史任务。看 prompt 全文、实时状态、最终结果；选中按 `G` 直接把那次会话重新加载进来接着聊。
 
 </td>
 <td width="50%" valign="top">

handoff_cli-0.3.1/cli/__init__.py

@@ -0,0 +1,8 @@
+"""handoff CLI package."""
+
+try:
+    from importlib.metadata import version as _ver
+
+    __version__ = _ver("handoff-cli")
+except Exception:
+    __version__ = "0.0.0"

handoff_cli-0.3.1/cli/commands/new.py

@@ -0,0 +1,88 @@
+"""handoff new command.
+
+Pre-allocates a run_id and returns the canonical .prompt.md path so the caller
+can write the prompt directly to its final archive location before dispatching.
+
+Usage:
+  handoff new --backend <name> [--slug <slug>]
+
+Stdout: one line — absolute path to the .prompt.md file (file is NOT created).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import datetime
+
+from ..core import (
+    get_db,
+    alloc_seq,
+    backend_abbrev,
+    slug_clean,
+    TASKS_DIR,
+)
+from ..config import Config
+
+
+def cmd_new(argv: list[str], config: Config):
+    """handoff new --backend <name> [--slug <slug>]"""
+    backend_arg = ""
+    slug_arg = ""
+
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--backend":
+            i += 1
+            if i >= len(argv):
+                print("handoff new: --backend requires a value", file=sys.stderr)
+                sys.exit(2)
+            backend_arg = argv[i]
+        elif a.startswith("--backend="):
+            backend_arg = a.split("=", 1)[1]
+        elif a == "--slug":
+            i += 1
+            if i >= len(argv):
+                print("handoff new: --slug requires a value", file=sys.stderr)
+                sys.exit(2)
+            slug_arg = argv[i]
+        elif a.startswith("--slug="):
+            slug_arg = a.split("=", 1)[1]
+        elif a in ("-h", "--help"):
+            from ..main import usage
+            usage()
+            sys.exit(0)
+        elif a.startswith("-"):
+            print(f"handoff new: unknown option {a}", file=sys.stderr)
+            sys.exit(2)
+        i += 1
+
+    backend_name = backend_arg or config.default_backend
+    if not backend_name:
+        print("handoff new: --backend is required (or set a default backend in config)", file=sys.stderr)
+        sys.exit(2)
+
+    # Validate backend exists in config
+    backend_cfg = config.get_backend(backend_name)
+    if not backend_cfg:
+        print(
+            f"handoff new: unknown backend '{backend_name}'. "
+            f"Available: {', '.join(sorted(config.backends.keys()))}",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    b2 = backend_abbrev(backend_name)
+    clean_slug = slug_clean(slug_arg) if slug_arg else "task"
+
+    mmdd = datetime.date.today().strftime("%m%d")
+
+    conn = get_db()
+    _n, seq_code = alloc_seq(conn)
+    conn.close()
+
+    run_id = f"{mmdd}-{b2}-{seq_code}-{clean_slug}"
+    prompt_path = os.path.join(TASKS_DIR, f"{run_id}.prompt.md")
+
+    print(prompt_path)

{handoff_cli-0.3.0 → handoff_cli-0.3.1}/cli/commands/run.py

@@ -6,7 +6,10 @@ import os
 import sys
 import datetime
 
-from ..core import get_db, create_run, task_paths, UUID_RE
+from ..core import (
+    get_db, create_run, task_paths, UUID_RE,
+    TASKS_DIR, parse_new_run_id, backend_abbrev,
+)
 from ..backend import (
     set_backend_env,
     build_args,
@@ -19,6 +22,21 @@ from ..stream import execute_run
 from ..config import Config
 
 
+def _is_adopted_path(input_src: str) -> bool:
+    """Return True if input_src is a .prompt.md file inside TASKS_DIR with new run_id format."""
+    if not input_src or input_src == "-":
+        return False
+    abs_src = os.path.abspath(input_src)
+    tasks_dir = os.path.abspath(TASKS_DIR)
+    if not abs_src.startswith(tasks_dir + os.sep):
+        return False
+    basename = os.path.basename(abs_src)
+    if not basename.endswith(".prompt.md"):
+        return False
+    stem = basename[: -len(".prompt.md")]
+    return parse_new_run_id(stem) is not None
+
+
 def cmd_run(argv: list[str], config: Config):
     """handoff run [--backend <name>] [--cwd <dir>] [--pro] (<input-file|-> | --text <prompt...>)."""
     pro = False
@@ -95,6 +113,9 @@ def cmd_run(argv: list[str], config: Config):
         print(f"handoff run: cwd not found: {cwd}", file=sys.stderr)
         sys.exit(2)
 
+    # Determine prompt source and whether to adopt a pre-allocated run_id.
+    adopted_run_id: str | None = None
+
     if text_mode:
         if not text_parts:
             print("handoff run: --text requires a value", file=sys.stderr)
@@ -103,21 +124,48 @@ def cmd_run(argv: list[str], config: Config):
         if not prompt_text:
             print("handoff run: --text requires a non-empty value", file=sys.stderr)
             sys.exit(2)
+        slug = "from-text"
     elif input_src == "-" or (not input_src and not sys.stdin.isatty()):
         prompt_text = sys.stdin.read()
+        slug = "from-stdin"
     elif input_src:
         if not os.path.isfile(input_src):
             print(f"handoff run: input file not found: {input_src}", file=sys.stderr)
             sys.exit(2)
-        with open(input_src) as f:
-            prompt_text = f.read()
+
+        if _is_adopted_path(input_src):
+            # Adopt: file is already at the canonical tasks/ path with new format.
+            stem = os.path.basename(input_src)[: -len(".prompt.md")]
+            parsed = parse_new_run_id(stem)  # guaranteed non-None by _is_adopted_path
+            _mmdd, file_b2, _seq_code, _slug = parsed  # type: ignore[misc]
+
+            # Validate backend2 consistency.
+            backend_name_candidate = backend_arg or config.default_backend
+            expected_b2 = backend_abbrev(backend_name_candidate)
+            if file_b2 != expected_b2:
+                print(
+                    f"handoff run: adopted file has backend '{file_b2}' but "
+                    f"--backend resolves to '{backend_name_candidate}' (abbrev '{expected_b2}'). "
+                    f"Use --backend matching the file's backend.",
+                    file=sys.stderr,
+                )
+                sys.exit(2)
+
+            with open(input_src) as f:
+                prompt_text = f.read()
+            adopted_run_id = stem
+            slug = _slug  # unused when adopting, but kept for clarity
+        else:
+            with open(input_src) as f:
+                prompt_text = f.read()
+            slug = "from-file"
     else:
         print("handoff run: input file required, or use --text <prompt...> / pipe via '-'", file=sys.stderr)
         sys.exit(2)
 
     backend_name = backend_arg or config.default_backend
 
-    _execute(cwd, prompt_text, backend_name, pro, config)
+    _execute(cwd, prompt_text, backend_name, pro, config, slug=slug, adopted_run_id=adopted_run_id)
 
 
 def _execute(
@@ -127,6 +175,8 @@ def _execute(
     pro: bool,
     config: Config,
     resume_session_id: str | None = None,
+    slug: str = "task",
+    adopted_run_id: str | None = None,
 ):
     """Shared execution path for file, stdin, and --text run modes.
 
@@ -134,6 +184,10 @@ def _execute(
     claude conversation (`claude -p ... --resume <id>`) rather than starting a
     fresh session; the new row still gets its own run_id/seq/files but shares the
     session_id. Used by `handoff resume <seq> <prompt>`.
+
+    When `adopted_run_id` is given, the pre-allocated run_id from `handoff new`
+    is adopted: the seq counter is NOT re-incremented, and the prompt file is
+    already at the canonical tasks/ path (not written again).
     """
     backend_cfg = config.get_backend(backend_name)
     if not backend_cfg:
@@ -147,16 +201,36 @@ def _execute(
     ensure_backend_token_ready(backend_name, backend_cfg, config.user_config_path)
 
     conn = get_db()
+
+    # Check for duplicate dispatch when adopting a pre-allocated run_id.
+    if adopted_run_id:
+        existing = conn.execute(
+            "SELECT run_id FROM runs WHERE run_id = ?", (adopted_run_id,)
+        ).fetchone()
+        if existing:
+            conn.close()
+            print(
+                f"handoff run: run_id '{adopted_run_id}' already exists in DB — "
+                f"duplicate dispatch rejected.",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+
     run_id, uid, jsonl_path = create_run(
-        conn, cwd, prompt_text, backend_name, session_id=resume_session_id
+        conn, cwd, prompt_text, backend_name,
+        session_id=resume_session_id,
+        slug=slug,
+        run_id_override=adopted_run_id,
     )
     conn.commit()
 
     # tasks dir files
     prompt_path, out_path, result_path = task_paths(run_id)
 
-    with open(prompt_path, "w") as pf:
-        pf.write(prompt_text)
+    # Write prompt file only when not adopting (adopted file is already in place).
+    if not adopted_run_id:
+        with open(prompt_path, "w") as pf:
+            pf.write(prompt_text)
 
     # Resolve model
     model = resolve_backend_model(backend_cfg, pro)

{handoff_cli-0.3.0 → handoff_cli-0.3.1}/cli/core.py

@@ -26,6 +26,50 @@ UUID_RE = re.compile(
     r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
 )
 
+# New run_id format: <mmdd>-<backend2>-<SEQ_CODE>-<slug>
+# e.g. 0611-ds-03-fix-auth
+_NEW_RUN_ID_RE = re.compile(
+    r"^(\d{4})-([a-z]{2})-([0-9A-Z]{2})-(.+)$"
+)
+
+# Explicit backend abbreviation mapping; others fall back to first 2 chars of name
+_BACKEND_ABBREV: dict[str, str] = {
+    "deepseek": "ds",
+    "codex": "cx",
+}
+
+
+def backend_abbrev(backend_name: str) -> str:
+    """Return 2-char abbreviation for a backend name."""
+    name = backend_name.lower()
+    return _BACKEND_ABBREV.get(name, name[:2])
+
+
+def slug_clean(raw: str) -> str:
+    """Sanitise a user-supplied slug: lowercase, only [a-z0-9-], max 3 dash-separated words.
+
+    Returns 'task' if the input is empty after cleaning.
+    """
+    s = raw.lower()
+    s = re.sub(r"[^a-z0-9-]", "-", s)
+    s = re.sub(r"-+", "-", s).strip("-")
+    # Keep at most 3 words (segments separated by '-')
+    parts = s.split("-")
+    parts = [p for p in parts if p]
+    s = "-".join(parts[:3])
+    return s or "task"
+
+
+def parse_new_run_id(stem: str) -> Optional[tuple[str, str, str, str]]:
+    """Parse a new-format run_id stem.
+
+    Returns (mmdd, backend2, seq_code, slug) or None if it doesn't match.
+    """
+    m = _NEW_RUN_ID_RE.match(stem)
+    if not m:
+        return None
+    return m.group(1), m.group(2), m.group(3), m.group(4)
+
 
 # ── migration ──────────────────────────────────────────────────────────────────
 
@@ -175,6 +219,8 @@ def create_run(
     prompt_text: str,
     backend_name: str = "",
     session_id: Optional[str] = None,
+    slug: str = "task",
+    run_id_override: Optional[str] = None,
 ):
     """Allocate a new run inside a BEGIN IMMEDIATE transaction.
 
@@ -186,6 +232,12 @@ def create_run(
     `resume` continuation it is the parent conversation's session_id, so the new
     row (new run_id/seq/files) shares one claude session across turns.
 
+    `slug` is appended to the run_id (≤3 dash-separated words, cleaned by slug_clean).
+
+    `run_id_override` is used when adopting a pre-allocated run_id from `handoff new`.
+    When set, the seq counter is NOT incremented — the counter was already bumped by
+    `new`.  The seq and seq_code are extracted from the override run_id.
+
     Returns (run_id, uuid, jsonl_path).  Caller must commit/rollback.
     """
     conn.execute("BEGIN IMMEDIATE")
@@ -193,23 +245,42 @@ def create_run(
     today_iso = today.isoformat()
     mmdd = today.strftime("%m%d")
 
-    row = conn.execute(
-        "SELECT last_n FROM run_counters WHERE day = ?", (today_iso,)
-    ).fetchone()
-    n = (row[0] + 1) if row else 1
+    if run_id_override:
+        # Adopt a pre-allocated run_id.  Parse seq_code from it to fill seq.
+        parsed = parse_new_run_id(run_id_override)
+        if parsed is None:
+            conn.execute("ROLLBACK")
+            print(f"handoff: cannot parse adopted run_id '{run_id_override}'", file=sys.stderr)
+            sys.exit(2)
+        _mmdd, _b2, seq_code, _slug = parsed
+        try:
+            n = seq_code_to_counter(seq_code)
+        except ValueError:
+            conn.execute("ROLLBACK")
+            print(f"handoff: invalid seq_code in run_id '{run_id_override}'", file=sys.stderr)
+            sys.exit(2)
+        run_id = run_id_override
+    else:
+        row = conn.execute(
+            "SELECT last_n FROM run_counters WHERE day = ?", (today_iso,)
+        ).fetchone()
+        n = (row[0] + 1) if row else 1
 
-    if n > _MAX_DAILY:
-        conn.execute("ROLLBACK")
-        print("handoff: exceeded maximum daily run count (ZZ = 1035)", file=sys.stderr)
-        sys.exit(2)
+        if n > _MAX_DAILY:
+            conn.execute("ROLLBACK")
+            print("handoff: exceeded maximum daily run count (ZZ = 1035)", file=sys.stderr)
+            sys.exit(2)
 
-    conn.execute(
-        "INSERT OR REPLACE INTO run_counters (day, last_n) VALUES (?, ?)",
-        (today_iso, n),
-    )
+        conn.execute(
+            "INSERT OR REPLACE INTO run_counters (day, last_n) VALUES (?, ?)",
+            (today_iso, n),
+        )
+
+        seq_code = counter_to_seq_code(n)
+        b2 = backend_abbrev(backend_name) if backend_name else "xx"
+        clean = slug_clean(slug)
+        run_id = f"{mmdd}-{b2}-{seq_code}-{clean}"
 
-    seq_code = counter_to_seq_code(n)
-    run_id = f"hd-{mmdd}-{seq_code}"
     uid = str(_uuid.uuid4()).lower()
     sess = session_id or uid
     jsonl_path = os.path.join(DB_DIR, f"{run_id}-{uid}.jsonl")
@@ -296,7 +367,31 @@ def task_paths(run_id: str):
     """Return (prompt, out, result) paths under TASKS_DIR using run_id as basename."""
     os.makedirs(TASKS_DIR, exist_ok=True)
     return (
-        os.path.join(TASKS_DIR, f"{run_id}.prompt.txt"),
+        os.path.join(TASKS_DIR, f"{run_id}.prompt.md"),
         os.path.join(TASKS_DIR, f"{run_id}.out.txt"),
         os.path.join(TASKS_DIR, f"{run_id}.result.md"),
     )
+
+
+def alloc_seq(conn: sqlite3.Connection) -> tuple[int, str]:
+    """Atomically increment today's run counter and return (n, seq_code).
+
+    Used by `handoff new` to pre-allocate a seq without creating a run row.
+    Caller must hold (or acquire) a transaction.
+    """
+    today = datetime.date.today().isoformat()
+    conn.execute("BEGIN IMMEDIATE")
+    row = conn.execute(
+        "SELECT last_n FROM run_counters WHERE day = ?", (today,)
+    ).fetchone()
+    n = (row[0] + 1) if row else 1
+    if n > _MAX_DAILY:
+        conn.execute("ROLLBACK")
+        print("handoff: exceeded maximum daily run count (ZZ = 1035)", file=sys.stderr)
+        sys.exit(2)
+    conn.execute(
+        "INSERT OR REPLACE INTO run_counters (day, last_n) VALUES (?, ?)",
+        (today, n),
+    )
+    conn.commit()
+    return n, counter_to_seq_code(n)