dctracker 1.2.0__tar.gz → 1.3.0__tar.gz

{dctracker-1.2.0/dctracker.egg-info → dctracker-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dctracker
-Version: 1.2.0
+Version: 1.3.0
 Summary: Deterministic Context Tracker (dct) — cross-project tracking, changelog, and release tooling for Claude Code.
 Author-email: fotodeveloper <dev@fotodeveloper.com>
 License-Expression: MIT
@@ -25,7 +25,7 @@ Requires-Dist: platformdirs>=4.9.6; sys_platform == "win32"
 Provides-Extra: pg
 Requires-Dist: psycopg[binary]; extra == "pg"
 Provides-Extra: mcp
-Requires-Dist: mcp[cli]; extra == "mcp"
+Requires-Dist: mcp[cli]<2,>=1.2; extra == "mcp"
 Provides-Extra: web
 Requires-Dist: flask>=3.0; extra == "web"
 Requires-Dist: markdown>=3.5; extra == "web"
@@ -34,7 +34,7 @@ Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Provides-Extra: all
 Requires-Dist: psycopg[binary]; extra == "all"
-Requires-Dist: mcp[cli]; extra == "all"
+Requires-Dist: mcp[cli]<2,>=1.2; extra == "all"
 Requires-Dist: flask>=3.0; extra == "all"
 Requires-Dist: markdown>=3.5; extra == "all"
 Requires-Dist: pytest; extra == "all"
@@ -48,7 +48,7 @@ Dynamic: license-file
 [![CI](https://github.com/fotodeveloper/dct/actions/workflows/ci.yml/badge.svg)](https://github.com/fotodeveloper/dct/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Persistent, queryable memory for AI coding assistants — your assistant reads facts from a database instead of guessing. One user-scoped database tracks issues, todos, changelog entries, plans, sprints, and decisions across all your projects. Built for [Claude Code](https://claude.com/claude-code) (skills, hooks, 49 MCP tools); the MCP server and CLI work with any MCP-capable assistant.
+Persistent, queryable memory for AI coding assistants — your assistant reads facts from a database instead of guessing. One user-scoped database tracks issues, todos, changelog entries, plans, sprints, and decisions across all your projects. Built for [Claude Code](https://claude.com/claude-code) (skills, hooks, 52 MCP tools); the MCP server and CLI work with any MCP-capable assistant.
 
 Part of the **dc tools** family ([dctools.dev](https://dctools.dev)) — *deterministic context* for AI-assisted development.
 
@@ -122,7 +122,7 @@ markdown, and makes the release commit.
 - **Decision records** — ADRs, sprint amendments, inline plan decisions with multi-anchor linkage
 - **LLM-assisted classification** — uncertain plan sections auto-resolved via `claude --print` (haiku by default)
 - **Passive autoscan hook** — PostToolUse hook re-scans plan-like files in background on every edit
-- **MCP server** — native Claude Code integration via FastMCP, 49 tools
+- **MCP server** — native Claude Code integration via FastMCP
 - **CLI** — fast `dct` command for hooks and scripts
 - **Skills** — Claude Code slash commands (`/track`, `/clog`, `/dct-import`, `/plan-status`, …)
 - **Soft deletes** — ledger pattern, nothing is ever lost
@@ -257,7 +257,12 @@ dct sprint create "Payments hardening" --code pay-1 --goal "Close the P1 backlog
 dct sprint show 3                     # Details + linked items
 dct sprint activate 3                 # Shortcuts: activate / complete / defer
 
-# Handoffs (amend an unconsumed handoff in place; creation is /handoff or MCP)
+# Session edges (same composed ops the /pickup and /handoff skills use)
+dct pickup                            # Snapshot: sprint, handoffs, gates, decisions
+                                      # (read-only — --consume defaults to never)
+dct handoff create --prompt-file - --add-items 22,6   # Sprint change + handoff, one transaction
+                                      # --remove-items cuts scope, --items replaces;
+                                      # omit all three to leave the sprint untouched
 dct handoff update 12 --prompt "Wire the toggle into settings next"
 
 # Config
@@ -267,7 +272,7 @@ dct config path                       # Show resolved config/data locations
 
 ## MCP Tools
 
-dct ships **49 MCP tools**, registered at user scope so they're callable from any Claude Code session as `mcp__dct__<name>`. Zero-arg calls auto-detect the project from the session's working directory; pass `project=<slug>` to override. Write ops return a minimal ack (id + a few post-state scalars); fetch full context with `get_item(id)` / `get_handoff(id)`. Ten mid-session daily drivers are always resident (`alwaysLoad`); the rest of the catalogue loads on demand via ToolSearch:
+dct ships **52 MCP tools**, registered at user scope so they're callable from any Claude Code session as `mcp__dct__<name>`. Zero-arg calls auto-detect the project from the session's working directory; pass `project=<slug>` to override. Write ops return a minimal ack (id + a few post-state scalars); fetch full context with `get_item(id)` / `get_handoff(id)`. Thirteen tools are always resident (`alwaysLoad`) — ten mid-session daily drivers plus the three composed workflow ops (`pickup_work`, `handoff_work`, `get_context_snapshot`); the rest of the catalogue loads on demand via ToolSearch:
 
 | Tool | Purpose |
 |---|---|
@@ -282,7 +287,7 @@ dct ships **49 MCP tools**, registered at user scope so they're callable from an
 | `reject_checkpoint` | Mark a checkpoint rejected (scope change) — ledger-preserving |
 | `add_changelog` | Add an unreleased changelog entry |
 
-Session-edge tools stay deferred: `get_handoff` (full handoff dict — untruncated prompt + context_summary), `create_handoff`, `set_sprint`, `release_changelog`, and more. Full categorized catalogue of all 49 tools: **[docs/mcp-tools.md](docs/mcp-tools.md)**.
+Session-edge tools stay deferred: `get_handoff` (full handoff dict — untruncated prompt + context_summary), `create_handoff`, `set_sprint`, `release_changelog`, and more. Full categorized catalogue: **[docs/mcp-tools.md](docs/mcp-tools.md)**.
 
 ## Plans, Roadmaps & Decisions
 
@@ -360,7 +365,7 @@ The `DCT_DATABASE_URL` environment variable overrides `[database].url`. For the
 ## Testing
 
 ```bash
-.venv/bin/pytest -q                    # All tests (938)
+.venv/bin/pytest -q                    # All tests
 .venv/bin/pytest tests/test_plan_parser.py -v          # Parser only
 .venv/bin/pytest tests/test_plan_ingest.py -v          # Ingest + sticky-resolved semantics
 

{dctracker-1.2.0 → dctracker-1.3.0}/README.md

@@ -5,7 +5,7 @@
 [![CI](https://github.com/fotodeveloper/dct/actions/workflows/ci.yml/badge.svg)](https://github.com/fotodeveloper/dct/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Persistent, queryable memory for AI coding assistants — your assistant reads facts from a database instead of guessing. One user-scoped database tracks issues, todos, changelog entries, plans, sprints, and decisions across all your projects. Built for [Claude Code](https://claude.com/claude-code) (skills, hooks, 49 MCP tools); the MCP server and CLI work with any MCP-capable assistant.
+Persistent, queryable memory for AI coding assistants — your assistant reads facts from a database instead of guessing. One user-scoped database tracks issues, todos, changelog entries, plans, sprints, and decisions across all your projects. Built for [Claude Code](https://claude.com/claude-code) (skills, hooks, 52 MCP tools); the MCP server and CLI work with any MCP-capable assistant.
 
 Part of the **dc tools** family ([dctools.dev](https://dctools.dev)) — *deterministic context* for AI-assisted development.
 
@@ -79,7 +79,7 @@ markdown, and makes the release commit.
 - **Decision records** — ADRs, sprint amendments, inline plan decisions with multi-anchor linkage
 - **LLM-assisted classification** — uncertain plan sections auto-resolved via `claude --print` (haiku by default)
 - **Passive autoscan hook** — PostToolUse hook re-scans plan-like files in background on every edit
-- **MCP server** — native Claude Code integration via FastMCP, 49 tools
+- **MCP server** — native Claude Code integration via FastMCP
 - **CLI** — fast `dct` command for hooks and scripts
 - **Skills** — Claude Code slash commands (`/track`, `/clog`, `/dct-import`, `/plan-status`, …)
 - **Soft deletes** — ledger pattern, nothing is ever lost
@@ -214,7 +214,12 @@ dct sprint create "Payments hardening" --code pay-1 --goal "Close the P1 backlog
 dct sprint show 3                     # Details + linked items
 dct sprint activate 3                 # Shortcuts: activate / complete / defer
 
-# Handoffs (amend an unconsumed handoff in place; creation is /handoff or MCP)
+# Session edges (same composed ops the /pickup and /handoff skills use)
+dct pickup                            # Snapshot: sprint, handoffs, gates, decisions
+                                      # (read-only — --consume defaults to never)
+dct handoff create --prompt-file - --add-items 22,6   # Sprint change + handoff, one transaction
+                                      # --remove-items cuts scope, --items replaces;
+                                      # omit all three to leave the sprint untouched
 dct handoff update 12 --prompt "Wire the toggle into settings next"
 
 # Config
@@ -224,7 +229,7 @@ dct config path                       # Show resolved config/data locations
 
 ## MCP Tools
 
-dct ships **49 MCP tools**, registered at user scope so they're callable from any Claude Code session as `mcp__dct__<name>`. Zero-arg calls auto-detect the project from the session's working directory; pass `project=<slug>` to override. Write ops return a minimal ack (id + a few post-state scalars); fetch full context with `get_item(id)` / `get_handoff(id)`. Ten mid-session daily drivers are always resident (`alwaysLoad`); the rest of the catalogue loads on demand via ToolSearch:
+dct ships **52 MCP tools**, registered at user scope so they're callable from any Claude Code session as `mcp__dct__<name>`. Zero-arg calls auto-detect the project from the session's working directory; pass `project=<slug>` to override. Write ops return a minimal ack (id + a few post-state scalars); fetch full context with `get_item(id)` / `get_handoff(id)`. Thirteen tools are always resident (`alwaysLoad`) — ten mid-session daily drivers plus the three composed workflow ops (`pickup_work`, `handoff_work`, `get_context_snapshot`); the rest of the catalogue loads on demand via ToolSearch:
 
 | Tool | Purpose |
 |---|---|
@@ -239,7 +244,7 @@ dct ships **49 MCP tools**, registered at user scope so they're callable from an
 | `reject_checkpoint` | Mark a checkpoint rejected (scope change) — ledger-preserving |
 | `add_changelog` | Add an unreleased changelog entry |
 
-Session-edge tools stay deferred: `get_handoff` (full handoff dict — untruncated prompt + context_summary), `create_handoff`, `set_sprint`, `release_changelog`, and more. Full categorized catalogue of all 49 tools: **[docs/mcp-tools.md](docs/mcp-tools.md)**.
+Session-edge tools stay deferred: `get_handoff` (full handoff dict — untruncated prompt + context_summary), `create_handoff`, `set_sprint`, `release_changelog`, and more. Full categorized catalogue: **[docs/mcp-tools.md](docs/mcp-tools.md)**.
 
 ## Plans, Roadmaps & Decisions
 
@@ -317,7 +322,7 @@ The `DCT_DATABASE_URL` environment variable overrides `[database].url`. For the
 ## Testing
 
 ```bash
-.venv/bin/pytest -q                    # All tests (938)
+.venv/bin/pytest -q                    # All tests
 .venv/bin/pytest tests/test_plan_parser.py -v          # Parser only
 .venv/bin/pytest tests/test_plan_ingest.py -v          # Ingest + sticky-resolved semantics
 

dctracker-1.3.0/dct/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("dctracker")
+except PackageNotFoundError:
+    __version__ = "1.3.0"

{dctracker-1.2.0 → dctracker-1.3.0}/dct/cli.py

@@ -2,17 +2,20 @@
 
 import argparse
 import atexit
+import contextlib
 import os
 import signal
 import socket
 import subprocess
 import sys
+from datetime import UTC
 from pathlib import Path
 
 from dct import __version__, migrate, paths
-from dct.config import load_config, save_config, Config
-from dct.db import get_engine, create_tables
+from dct.config import Config, load_config, save_config
 from dct.core.engine import bootstrap_engine
+from dct.core.items import TERMINAL_STATUSES
+from dct.db import create_tables, get_engine
 
 # Windows-policy seam (tests flip it): dispatches the daemonization,
 # liveness-probe and signal paths that differ on win32 (W8-W10, ADR #52).
@@ -35,6 +38,7 @@ def _get_engine():
 def _detect_project(engine) -> str:
     """Auto-detect project slug from CWD. Exits if not found."""
     import os
+
     from dct.core.projects import get_project_by_path
 
     cwd = os.getcwd()
@@ -72,6 +76,59 @@ def _prompt_version(default: str = "0.1.0") -> str | None:
     return shortcut.get(choice, choice)
 
 
+def _read_text_arg(text: str | None, path: str | None) -> str | None:
+    """Resolve a `--foo` / `--foo-file` flag pair to text ('-' = stdin).
+
+    The file wins when both are given. Returns None when neither is supplied,
+    so callers can tell "not passed" from an empty string. Raises (OSError) on
+    an unreadable path — call it INSIDE the command's try/except so the user
+    gets `✗ Error: ...` instead of a traceback.
+
+    Encoding is pinned to UTF-8 on BOTH paths: handoff prompts routinely carry
+    '✓', '—' and non-ASCII prose, and the platform default (cp1252 on Windows,
+    or a C-locale ASCII stdin) would mangle or reject them.
+    """
+    if path:
+        if path != "-":
+            return Path(path).read_text(encoding="utf-8")
+        # Decode the raw byte stream ourselves so a C-locale stdin still takes
+        # UTF-8. `buffer` is absent when stdin is a StringIO (tests, embedders)
+        # — then the text stream is already decoded.
+        buffer = getattr(sys.stdin, "buffer", None)
+        if buffer is None:
+            return sys.stdin.read()
+        return buffer.read().decode("utf-8")
+    return text
+
+
+def _json_default(obj):
+    """json.dumps fallback for core payloads — datetime → ISO 8601, rest → str.
+
+    Core dicts carry real datetime objects (created_at, consumed_at, ...);
+    without this every `--json` surface would raise TypeError.
+    """
+    from datetime import date, datetime
+
+    if isinstance(obj, (datetime, date)):
+        return obj.isoformat()
+    return str(obj)
+
+
+def _default_identity() -> str:
+    """Actor identity used when pickup/handoff callers omit theirs.
+
+    Shape: `<client> @ <UTC minute>` — the provenance client when the host
+    self-identifies (Claude Code, a G2 adapter), else "cli". Commands ECHO the
+    resolved value so attribution is never silent.
+    """
+    from datetime import datetime
+
+    from dct.core.provenance import get_provenance
+
+    client = get_provenance().actor_client or "cli"
+    return f"{client} @ {datetime.now(UTC).strftime('%Y-%m-%dT%H:%MZ')}"
+
+
 def _print_table(headers: list[str], rows: list[list[str]], max_widths: dict[int, int] | None = None) -> None:
     """Print a simple aligned table."""
     if not rows:
@@ -239,6 +296,7 @@ def cmd_hooks_wire(args):
 
 def cmd_project_add(args):
     import os
+
     from dct.core.projects import create_project, set_version
 
     # #227: realpath (not abspath) so a symlinked path is stored canonically and
@@ -360,7 +418,11 @@ def cmd_project_changelog_path(args):
     With a relpath → set it (validated to stay within the project root). Without
     → print the current relpath and its resolved absolute path.
     """
-    from dct.core.projects import get_project, resolve_changelog_path, set_changelog_path
+    from dct.core.projects import (
+        get_project,
+        resolve_changelog_path,
+        set_changelog_path,
+    )
 
     engine = _get_engine()
 
@@ -400,6 +462,7 @@ def cmd_plan_rescan(args):
     injection + [x] state reading (§9.2).
     """
     import os
+
     from dct.core.plans.ingest import ingest_file
     from dct.core.projects import get_project_by_path
 
@@ -614,19 +677,69 @@ def cmd_delete(args):
 
 # ── Handoff commands ──────────────────────────────────────────────────────────
 
-def cmd_handoff_update(args):
-    from dct.core.handoff import update_handoff
+def cmd_handoff_create(args):
+    """`dct handoff create` — session-end op: set sprint membership + leave the
+    handoff prompt in ONE transaction (workflows.session.handoff_work)."""
+    import json
+
+    from dct.workflows.session import handoff_work
 
     engine = _get_engine()
+    try:
+        project = args.project or _detect_project(engine)
+        prompt = _read_text_arg(args.prompt, args.prompt_file)
+        identity = args.created_by or _default_identity()
+
+        def _ids(raw: str | None, flag: str) -> list[int] | None:
+            # None → flag unused; empty/garbage → error (a blank shell var
+            # must never read as "no items" or wipe anything — K-27).
+            if raw is None:
+                return None
+            try:
+                ids = [int(x.strip()) for x in raw.split(",") if x.strip()]
+            except ValueError:
+                raise ValueError(
+                    f"{flag} expects comma-separated item ids, got: {raw!r}"
+                ) from None
+            if not ids:
+                raise ValueError(f"{flag} got no ids ({raw!r}) — omit the flag instead")
+            return ids
+
+        result = handoff_work(
+            engine, project,
+            prompt=prompt or "",
+            created_by=identity,
+            item_ids=_ids(args.items, "--items"),
+            add_item_ids=_ids(args.add_items, "--add-items"),
+            remove_item_ids=_ids(args.remove_items, "--remove-items"),
+            sprint=args.sprint,
+            scope=args.scope,
+            context_summary=args.context_summary,
+        )
+    except Exception as e:
+        print(f"✗ Error: {e}", file=sys.stderr)
+        sys.exit(1)
 
-    def _read(text, path):
-        if path:
-            return sys.stdin.read() if path == "-" else Path(path).read_text()
-        return text
+    if args.json:
+        print(json.dumps(result, indent=2, default=_json_default))
+        return
+
+    h = result["handoff"]
+    print(f"✓ Handoff #{h['id']} created (scope: {h.get('scope') or 'none'}, by {identity})")
+    sprint = result.get("sprint")
+    if sprint:
+        print(f"  sprint #{sprint['sprint_id']}: {sprint['open_size']} open items")
+    else:
+        print("  sprint untouched")
 
-    prompt = _read(args.prompt, args.prompt_file)
+
+def cmd_handoff_update(args):
+    from dct.core.handoff import update_handoff
+
+    engine = _get_engine()
 
     try:
+        prompt = _read_text_arg(args.prompt, args.prompt_file)
         result = update_handoff(
             engine, args.id,
             prompt=prompt or None,
@@ -642,6 +755,129 @@ def cmd_handoff_update(args):
         sys.exit(1)
 
 
+# ── Session pickup (#413) ─────────────────────────────────────────────────────
+
+def _cols_rows_dicts(table: dict | None) -> list[dict]:
+    """{cols, rows} → list of dicts — the compact wire shape read by name."""
+    if not table:
+        return []
+    return [dict(zip(table["cols"], row)) for row in table["rows"]]
+
+
+_CONTROL_CHARS = {c: None for c in range(0x20) if c not in (0x09, 0x0A)} | {0x7F: None}
+
+
+def _strip_controls(text: str | None) -> str:
+    """Drop C0 control characters from DB text before printing it.
+
+    Handoff prompts and item titles are free text written by another session;
+    an ESC sequence in there would repaint or clear the reader's terminal. Tabs
+    and newlines are legitimate formatting and survive — everything else below
+    0x20, plus DEL, is removed. None → "".
+    """
+    if not text:
+        return ""
+    return text.translate(_CONTROL_CHARS)
+
+
+def _render_pickup(snap: dict, identity: str | None) -> None:
+    """Human view of `dct pickup`: what was consumed, then the state that
+    matters at session start. Sections dropped via --include are simply
+    absent from the snapshot, so every lookup is guarded. ALL free text coming
+    from the DB is passed through _strip_controls — a stored escape sequence
+    must not drive the reader's terminal."""
+    picked = snap.get("picked_up")
+    summary = snap.get("summary", {})
+
+    if picked:
+        print(f"✓ Picked up handoff #{picked['id']} (consumed as {identity})")
+        print()
+        for line in _strip_controls(picked.get("prompt")).splitlines():
+            print(f"  {line}")
+    else:
+        print(f"— no handoff consumed ({summary.get('handoffs_pending', 0)} pending)")
+
+    sprint = snap.get("sprint")
+    if sprint:
+        items = _cols_rows_dicts(sprint.get("items"))
+        pending_cp = sum(
+            1 for c in _cols_rows_dicts(sprint.get("checkpoints")) if c.get("status") == "pending"
+        )
+        print(f"\nSprint items ({pending_cp} pending checkpoints):")
+        _print_table(
+            ["#", "sprint", "prio", "status", "cp", "title"],
+            [
+                [
+                    str(i["id"]), str(i.get("sprint_id") or ""), i.get("priority") or "",
+                    i.get("status") or "", "{}/{}".format(*(i.get("cp") or [0, 0])),
+                    _strip_controls(i.get("title")),
+                ]
+                for i in items
+            ],
+            max_widths={5: 60},
+        )
+
+    gates = _cols_rows_dicts(snap.get("gates"))
+    if gates:
+        print("\nPending gates:")
+        _print_table(
+            ["#", "cp", "kind", "prio", "title", "text"],
+            [
+                [
+                    str(g["item_id"]), str(g["checkpoint_id"]), g.get("kind") or "",
+                    g.get("priority") or "", _strip_controls(g.get("item_title")),
+                    _strip_controls(g.get("text")),
+                ]
+                for g in gates
+            ],
+            max_widths={4: 30, 5: 50},
+        )
+
+    if summary:
+        print(
+            f"\nSprint: size {summary.get('sprint_size', 0)}, "
+            f"done {summary.get('sprint_completion', '0/0')} · "
+            f"open in project: {summary.get('total_open_in_project', 0)} · "
+            f"handoffs pending: {summary.get('handoffs_pending', 0)} · "
+            f"gates: {summary.get('gates_pending', 0)}"
+        )
+
+
+def cmd_pickup(args):
+    """`dct pickup` — session-start op: one snapshot read + (possibly) consume
+    ONE handoff (workflows.session.pickup_work)."""
+    import json
+
+    from dct.workflows.session import parse_sections, pickup_work
+
+    engine = _get_engine()
+    consume = {"auto": None, "always": True, "never": False}[args.consume]
+    # consumed_by is REQUIRED by pickup_work whenever consumption is possible;
+    # default it (and echo it) rather than let the op fail on a missing identity.
+    identity = args.consumed_by or (None if consume is False else _default_identity())
+
+    try:
+        project = args.project or _detect_project(engine)
+        include = parse_sections(args.include)
+        snap = pickup_work(
+            engine, project,
+            consume=consume,
+            handoff_id=args.handoff_id,
+            scope=args.scope,
+            consumed_by=identity,
+            since=args.since,
+            include=include,
+        )
+    except Exception as e:
+        print(f"✗ Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.json:
+        print(json.dumps(snap, indent=2, default=_json_default))
+        return
+    _render_pickup(snap, identity)
+
+
 # ── Changelog commands ────────────────────────────────────────────────────────
 
 def cmd_clog_add(args):
@@ -695,7 +931,8 @@ def cmd_clog_count(args):
 
 def cmd_clog_release(args):
     import subprocess
-    from dct.core.changelog import release_entries, count_unreleased
+
+    from dct.core.changelog import count_unreleased, release_entries
     from dct.core.projects import get_project
     from dct.core.version import bump
 
@@ -777,6 +1014,7 @@ def cmd_internal_task_mirror(args):
         project: dct project slug. Empty → autodetect from CWD.
     """
     import json
+
     from dct.config import load_config
 
     try:
@@ -812,8 +1050,8 @@ def cmd_internal_task_mirror(args):
     if not todos:
         return
 
-    from dct.core.items import list_items, create_item
     from dct.core.checkpoints import add_checkpoint
+    from dct.core.items import create_item, list_items
     from dct.core.projects import get_project_by_path
 
     engine = _get_engine()
@@ -941,7 +1179,7 @@ def cmd_checkpoint_add(args):
 
 
 def cmd_checkpoint_list(args):
-    from dct.core.checkpoints import list_checkpoints, get_progress
+    from dct.core.checkpoints import get_progress, list_checkpoints
 
     engine = _get_engine()
     cps = list_checkpoints(engine, args.item_id)
@@ -1125,7 +1363,8 @@ def cmd_upgrade(args):
     matrix so the user knows what takes effect when.
     """
     import subprocess
-    from dct.update import detect_install_method, upgrade_command, dist_pkg
+
+    from dct.update import detect_install_method, dist_pkg, upgrade_command
 
     method = detect_install_method()
 
@@ -1138,14 +1377,18 @@ def cmd_upgrade(args):
         cmd = upgrade_command(method)
         print(f"Detected install method: {method}")
         print(f"Upgrading {dist_pkg()} …  ({' '.join(cmd)})")
-        result = subprocess.run(cmd)
+        result = subprocess.run(cmd, check=False)
         if result.returncode != 0:
             print(f"✗ Upgrade command failed (exit {result.returncode})", file=sys.stderr)
             sys.exit(result.returncode)
 
     # Refresh Claude Code integration: re-link current skills/hooks (idempotent),
     # then remove links to skills/hooks that the new package no longer ships.
-    from dct.integrations.claude import install_hook, install_skills, prune_dangling_symlinks
+    from dct.integrations.claude import (
+        install_hook,
+        install_skills,
+        prune_dangling_symlinks,
+    )
 
     linked_ok = True
     removed: list[str] = []
@@ -1190,6 +1433,7 @@ def _maybe_print_legacy_nudge() -> None:
 
 def cmd_project_detect(args):
     import os
+
     from dct.core.projects import get_project_by_path
 
     engine = _get_engine()
@@ -1608,7 +1852,9 @@ def build_parser() -> argparse.ArgumentParser:
     # resolve
     p_resolve = sub.add_parser("resolve", help="Resolve/close an item")
     p_resolve.add_argument("id", type=int)
-    p_resolve.add_argument("--status", "-s", default="resolved", choices=["resolved", "wont_fix"])
+    p_resolve.add_argument(
+        "--status", "-s", default="resolved", choices=list(TERMINAL_STATUSES)
+    )
     p_resolve.add_argument("--resolution", "-r")
 
     # note
@@ -1741,10 +1987,62 @@ def build_parser() -> argparse.ArgumentParser:
         p_verb.add_argument("id", type=int)
         p_verb.set_defaults(_forced_status=_st)
 
-    # web (read-only browser dashboard daemon — v0.4.1)
+    # pickup (session-start op — snapshot + handoff consume, #413)
+    p_pickup = sub.add_parser(
+        "pickup",
+        help="Session-start op: project snapshot + consume the pending handoff",
+    )
+    p_pickup.add_argument("--project", help="Project slug (default: auto-detect from CWD)")
+    p_pickup.add_argument("--since", default="last_release",
+                          help="Activity window anchor for recent_changes: "
+                               "last_release (default) | all | <N>h (e.g. 24h) "
+                               "| ISO date")
+    p_pickup.add_argument("--include", default=None,
+                          help="Comma-separated snapshot sections (sprint,handoff,gates,"
+                               "decisions,recent_changes). 'none' = summary only.")
+    p_pickup.add_argument("--consume", choices=["auto", "always", "never"], default="never",
+                          help="never (default): pure read — pickup does not write; "
+                               "auto: consume an unambiguous single candidate; "
+                               "always: consume or fail (autonomous flows)")
+    p_pickup.add_argument("--handoff-id", type=int, default=None,
+                          help="Consume this specific handoff (wins over --scope)")
+    p_pickup.add_argument("--scope", default=None,
+                          help="Only consider handoffs carrying this scope tag")
+    p_pickup.add_argument("--consumed-by", default=None,
+                          help="Session identity stamped on consume "
+                               "(default: '<client> @ <UTC minute>', echoed)")
+    p_pickup.add_argument("--json", action="store_true", help="Print the raw snapshot as JSON")
+
+    # handoff (session-end ledger)
     p_handoff = sub.add_parser("handoff", help="Manage session handoffs")
     p_ho_sub = p_handoff.add_subparsers(dest="handoff_command")
 
+    p_ho_create = p_ho_sub.add_parser(
+        "create",
+        help="Session-end op: set sprint membership + leave a handoff prompt (one transaction)",
+    )
+    p_ho_create.add_argument("--prompt", default=None, help="Handoff prompt text")
+    p_ho_create.add_argument("--prompt-file", default=None,
+                             help="Read the prompt from a file ('-' = stdin)")
+    p_ho_create.add_argument("--created-by", default=None,
+                             help="Session identity (default: '<client> @ <UTC minute>', echoed)")
+    p_ho_create.add_argument("--items", default=None,
+                             help="REPLACE the sprint's OPEN membership with these ids "
+                                  "(e.g. 22,21,6) — a conscious replan; resolved members "
+                                  "stay as history. Mutually exclusive with --add-items/"
+                                  "--remove-items. Omit all item flags to keep the sprint.")
+    p_ho_create.add_argument("--add-items", default=None,
+                             help="ADD these item ids to the target sprint (additive edge)")
+    p_ho_create.add_argument("--remove-items", default=None,
+                             help="CUT these OPEN items from the sprint's scope "
+                                  "(terminal members refuse — they are history)")
+    p_ho_create.add_argument("--sprint", default=None,
+                             help="Target sprint id or code (required when several are active)")
+    p_ho_create.add_argument("--scope", default=None, help="Scope tag")
+    p_ho_create.add_argument("--context-summary", default=None, help="Context summary snapshot")
+    p_ho_create.add_argument("--project", help="Project slug (default: auto-detect from CWD)")
+    p_ho_create.add_argument("--json", action="store_true", help="Print the raw result as JSON")
+
     p_ho_update = p_ho_sub.add_parser("update", help="Amend an unconsumed handoff in place")
     p_ho_update.add_argument("id", type=int, help="Handoff id")
     p_ho_update.add_argument("--prompt", default=None, help="New prompt text")
@@ -1752,6 +2050,7 @@ def build_parser() -> argparse.ArgumentParser:
     p_ho_update.add_argument("--scope", default=None, help="New scope tag")
     p_ho_update.add_argument("--context-summary", default=None, help="New context summary snapshot")
 
+    # web (read-only browser dashboard daemon — v0.4.1)
     p_web = sub.add_parser("web", help="Read-only browser dashboard daemon")
     p_web_sub = p_web.add_subparsers(dest="web_command")
 
@@ -1799,6 +2098,7 @@ COMMAND_MAP = {
     "resolve": cmd_resolve,
     "note": cmd_note,
     "delete": cmd_delete,
+    "pickup": cmd_pickup,
     "_task-mirror": cmd_internal_task_mirror,
     "_web-serve": cmd_internal_web_serve,
 }
@@ -1852,6 +2152,7 @@ CHECKPOINT_COMMAND_MAP = {
 }
 
 HANDOFF_COMMAND_MAP = {
+    "create": cmd_handoff_create,
     "update": cmd_handoff_update,
 }
 
@@ -1928,7 +2229,8 @@ def _maybe_nudge(args) -> None:
     suppressed, or opted-out command) is silent and never affects the command's
     own output or exit code.
     """
-    try:
+    # A passive nicety must never break a command.
+    with contextlib.suppress(Exception):
         if not sys.stderr.isatty() or _nudge_suppressed(args):
             return
         from dct.config import load_config
@@ -1940,8 +2242,6 @@ def _maybe_nudge(args) -> None:
         notice = get_cached_notice(config=cfg)
         if notice:
             print(notice, file=sys.stderr)
-    except Exception:
-        pass  # a passive nicety must never break a command
 
 
 def main():