cc-session-tools 2.8.2__tar.gz → 2.9.0__tar.gz

{cc_session_tools-2.8.2/src/cc_session_tools.egg-info → cc_session_tools-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 2.8.2
+Version: 2.9.0
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)
 Author: raffishquartan
 License: MIT License

{cc_session_tools-2.8.2 → cc_session_tools-2.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "2.8.2"
+version = "2.9.0"
 description = "Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)"
 readme = "README.md"
 license = { file = "LICENSE" }

{cc_session_tools-2.8.2 → cc_session_tools-2.9.0}/src/cc_session_tools/cli/ccsched.py

@@ -11,6 +11,7 @@ from cc_session_tools import __version__
 from cc_session_tools.lib.scheduler import (
     cursor,
     ledger,
+    notify,
     reconcile,
     registry,
     state,
@@ -240,7 +241,9 @@ def _cmd_remove(job_id: str) -> int:
     return 0
 
 
-def _cmd_run(args: argparse.Namespace) -> int:
+def _cmd_run(
+    args: argparse.Namespace, *, notify_push: worker.NotifyPush = notify.push_outcome,
+) -> int:
     specs = {s.job_id: s for s in registry.load_registry()}
     spec: JobSpec | None = specs.get(args.id)
     if spec is None:
@@ -249,25 +252,22 @@ def _cmd_run(args: argparse.Namespace) -> int:
     now = datetime.now(timezone.utc)
     attempt_ts = state.format_ts(now)
     state.ensure_registered_db(spec.job_id, now)
-    crashed = outcome.timed_out or outcome.exit_code not in spec.success_exit_codes
-    if crashed:
+    # Manual runs always use record_manual_failure/record_success, not
+    # worker.py's suspend-threshold-aware record_failure - `ccsched run` never
+    # auto-suspends a job, unlike the scheduled `_run-job` path.
+    capture = worker.classify_outcome(spec, outcome, notify_push=notify_push)
+    if capture.crashed:
         new_consecutive = state.record_manual_failure(spec.job_id, attempt_ts=attempt_ts)
     else:
         state.record_success(spec.job_id, new_success=attempt_ts, attempt_ts=attempt_ts)
         new_consecutive = 0
-    findings = None
-    if not crashed and outcome.exit_code != 0:
-        findings = outcome.stdout.strip()[:1000] or None
     ledger.record(ledger.LedgerEntry(
-        job_id=spec.job_id,
-        event=ledger.LedgerEvent.FAIL if crashed else ledger.LedgerEvent.RUN,
-        owed=1, ran=0 if crashed else 1, exit_code=outcome.exit_code,
-        duration_ms=outcome.duration_ms,
-        error=(outcome.stderr.strip()[:200] or None) if crashed else findings,
-        consecutive_failures=new_consecutive if crashed else 0,
+        job_id=spec.job_id, event=capture.event, owed=1, ran=0 if capture.crashed else 1,
+        exit_code=outcome.exit_code, duration_ms=outcome.duration_ms, error=capture.detail,
+        consecutive_failures=new_consecutive if capture.crashed else 0,
     ))
-    print(f"{'failed' if crashed else 'ran'} {spec.job_id} (exit={outcome.exit_code})")
-    return 1 if crashed else 0
+    print(f"{'failed' if capture.crashed else 'ran'} {spec.job_id} (exit={outcome.exit_code})")
+    return 1 if capture.crashed else 0
 
 
 def _cmd_status(args: argparse.Namespace) -> int:

{cc_session_tools-2.8.2 → cc_session_tools-2.9.0}/src/cc_session_tools/cli/ccst.py

@@ -1217,6 +1217,64 @@ def _cmd_pdata_reorganize(args: argparse.Namespace) -> int:
         return 0
 
 
+def _cmd_pdata_rename_group(args: argparse.Namespace) -> int:
+    from cc_session_tools.lib.pdata import init_paths, naming, rename_group
+
+    try:
+        project_root = init_paths.resolve_project_root(args.project, rehearse=None)
+    except ValueError as exc:
+        print(f"ccst pdata: {exc}", file=sys.stderr)
+        return 2
+
+    if not args.write:
+        try:
+            plan = rename_group.dry_run(
+                project=args.project, project_root=project_root, old=args.from_, new=args.to,
+            )
+        except ValueError as exc:
+            print(f"ccst pdata: {exc}", file=sys.stderr)
+            return 2
+        print(f"record_group: {plan.old} -> {plan.new}")
+        print(f"  {plan.row_count} row(s) in records to update")
+        if plan.has_extension_table:
+            print(f"  ext table: {naming.extension_table_name(plan.old)} -> "
+                  f"{naming.extension_table_name(plan.new)}")
+        else:
+            print("  no extension table")
+        if plan.manifest_entry_paths:
+            n = len(plan.manifest_entry_paths)
+            print(f"  {n} manifest entr{'y' if n == 1 else 'ies'} to update:")
+            for path in plan.manifest_entry_paths:
+                print(f"    {path}")
+        else:
+            print("  no matching manifest entries")
+        return 0
+
+    try:
+        result = rename_group.write(
+            project=args.project, project_root=project_root, old=args.from_, new=args.to,
+        )
+    except ValueError as exc:
+        print(f"ccst pdata: {exc}", file=sys.stderr)
+        return 2
+
+    if result.failure is not None:
+        print("ccst pdata rename-group: failed:", file=sys.stderr)
+        for reason in result.failure.reasons:
+            print(f"  - {reason}", file=sys.stderr)
+        return 1
+
+    plan = result.plan
+    print(f"Renamed record_group {plan.old!r} -> {plan.new!r}: {plan.row_count} row(s)")
+    print(f"Backup: {result.backup_path}")
+    n = len(plan.manifest_entry_paths)
+    if n:
+        print(f"{n} manifest entr{'y' if n == 1 else 'ies'} updated - remember to update any "
+              f"skills/docs that still reference the old group name.")
+    print("SUCCESS")
+    return 0
+
+
 def _cmd_pdata_reconcile_session_output(args: argparse.Namespace) -> int:
     from cc_session_tools.lib import roots
     from cc_session_tools.lib.pdata import session_output
@@ -2247,6 +2305,18 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Perform the move and update matching pdata records (default: dry-run only)",
     )
 
+    pdata_rename_group_parser = pdata_sub.add_parser(
+        "rename-group", help="Rename a record_group in place (records, record_group_fields, "
+                              "its ext table, and any matching manifest entries)"
+    )
+    pdata_rename_group_parser.add_argument("--project", required=True, metavar="NAME")
+    pdata_rename_group_parser.add_argument("--from", dest="from_", required=True, metavar="OLD")
+    pdata_rename_group_parser.add_argument("--to", required=True, metavar="NEW")
+    pdata_rename_group_parser.add_argument(
+        "--write", action="store_true",
+        help="Perform the rename and update .ccst-pdata-proposal.json (default: dry-run only)",
+    )
+
     pdata_reconcile_parser = pdata_sub.add_parser(
         "reconcile-session-output",
         help="Backfill the session-output index from cc-sessions/*/out/ on disk (idempotent)",
@@ -2553,6 +2623,8 @@ def main() -> None:
             sys.exit(_cmd_pdata_init(args))
         if args.verb == "reorganize":
             sys.exit(_cmd_pdata_reorganize(args))
+        if args.verb == "rename-group":
+            sys.exit(_cmd_pdata_rename_group(args))
         if args.verb == "reconcile-session-output":
             sys.exit(_cmd_pdata_reconcile_session_output(args))
         if args.verb == "verify":

{cc_session_tools-2.8.2 → cc_session_tools-2.9.0}/src/cc_session_tools/lib/pdata/init_service.py

@@ -5,10 +5,12 @@ A's service.py — this module owns no SQL of its own.
 from __future__ import annotations
 
 import csv
+import sqlite3
 from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
 
+from cc_session_tools.lib import db
 from cc_session_tools.lib.pdata import (
     backup,
     cutover,
@@ -16,6 +18,7 @@ from cc_session_tools.lib.pdata import (
     manifest,
     repository,
     service,
+    store,
 )
 from cc_session_tools.lib.pdata.importers import ImportRow, count_source_rows, import_entry
 from cc_session_tools.lib.pdata.manifest import Manifest, ManifestEntry
@@ -137,6 +140,58 @@ def _rollback(*, project: str, created_ids: list[int]) -> list[str]:
     return rollback_failures
 
 
+def _check_db_not_locked(project: str) -> None:
+    """Pre-flight concurrency guard (inter-session message 20260819T114156Z-3ec7,
+    gap #2): refuse to start --write if another connection already holds a write
+    lock on the project's .db right now — e.g. a concurrent --write, or
+    pdata-verify-all's scheduled cadence firing against the same project — rather
+    than letting the first schema_add_field/add_record call inside the with-block
+    below block on db.py's passive 5s busy_timeout and eventually fail with
+    rows already mid-migration. Called as the very first thing inside write()'s
+    project_db_dir_override/backup_dir_override with-block so store.db_path()
+    resolves the rehearsal-sandboxed path when rehearsing, exactly like every
+    other db access in this function.
+
+    No-op if the project has no .db yet (a brand-new project's first --write) —
+    nothing to guard, and connecting would create one just to probe it.
+
+    The probe is a throwaway BEGIN IMMEDIATE / ROLLBACK on its own short-lived
+    connection, not a lock held across the rest of write() — this does not
+    protect against a second --write starting a few seconds *after* this check
+    passes (a TOCTOU race that is out of scope; the existing passive
+    busy_timeout is still the backstop for that narrower case). Its job is only
+    to catch the common case of something *already* actively using the .db,
+    immediately and with a clear message, instead of a raw sqlite3 error
+    surfacing minutes into the migration.
+
+    busy_timeout is overridden to 0 on this connection only — db.connect()'s
+    shared 5000ms default is exactly the passive wait this probe exists to
+    avoid; a probe that waits out the same timeout the mutation path already
+    relies on would defeat the point of checking up front. isolation_level is
+    set to None for the same reason repository.connect() sets it: so this
+    caller-issued BEGIN IMMEDIATE isn't wrapped in a second, implicit
+    transaction by sqlite3's own legacy transaction handling."""
+    db_path = store.db_path(project)
+    if not db_path.exists():
+        return
+    conn = db.connect(db_path)
+    conn.isolation_level = None
+    try:
+        conn.execute("PRAGMA busy_timeout=0")
+        try:
+            conn.execute("BEGIN IMMEDIATE")
+        except sqlite3.OperationalError as exc:
+            raise ValueError(
+                f"cannot start 'ccst pdata init --write' for project {project!r}: "
+                f"another process appears to be using {db_path} right now ({exc}) "
+                f"— wait for it to finish, or confirm it isn't stuck, then re-run --write"
+            ) from exc
+        else:
+            conn.execute("ROLLBACK")
+    finally:
+        conn.close()
+
+
 def write(
     *, project: str, rehearse: Path | None = None,
     on_progress: Callable[[str], None] | None = None,
@@ -171,6 +226,8 @@ def write(
         init_paths.project_db_dir_override(rehearse),
         init_paths.backup_dir_override(rehearse),
     ):
+        _check_db_not_locked(project)
+
         db_owned = [e for e in m.entries if e.classification == "db-owned"]
         _emit(on_progress, f"Importing {len(db_owned)} file(s)...")
         for entry in m.entries:

cc_session_tools-2.9.0/src/cc_session_tools/lib/pdata/rename_group.py

@@ -0,0 +1,161 @@
+"""Record-group rename for `ccst pdata rename-group` (feature request from the `home` project's
+migration-test session, message 20260822T114514Z-91ed).
+
+A record_group rename touches three places that must move together in one transaction -
+`records.record_group`, `record_group_fields.record_group`, and the `ext_<group>` table's own
+name - plus a fourth, non-transactional place that is just as easy to forget: any matching entry
+in `.ccst-pdata-proposal.json` (the classification manifest, spec §7.1). Skip that and
+verify.check_row_count_parity cross-checks live row counts against the manifest's archived-file
+entries by record_group; every renamed group then fails `ccst pdata verify` forever with a
+"possible data loss" row-count-parity issue that isn't actually data loss - it's just comparing
+the new name's row count against the old name's manifest entry.
+"""
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+
+from cc_session_tools.lib.pdata import backup, init_paths, manifest, naming, repository
+
+
+@dataclass(frozen=True, slots=True)
+class RenameGroupPlan:
+    project: str
+    project_root: Path
+    old: str
+    new: str
+    row_count: int
+    has_extension_table: bool
+    manifest_entry_paths: list[str]
+
+
+@dataclass(frozen=True, slots=True)
+class RenameGroupFailure:
+    reasons: list[str]
+
+
+@dataclass(frozen=True, slots=True)
+class RenameGroupResult:
+    plan: RenameGroupPlan
+    backup_path: Path | None
+    failure: RenameGroupFailure | None
+
+
+def _plan(*, project: str, project_root: Path, old: str, new: str) -> RenameGroupPlan:
+    naming.validate_record_group(old)
+    naming.validate_record_group(new)
+    if old == new:
+        raise ValueError(f"--from and --to are the same record_group: {old!r}")
+
+    conn = repository.connect(project)
+    try:
+        old_row_count = conn.execute(
+            "SELECT COUNT(*) FROM records WHERE record_group=?", (old,)
+        ).fetchone()[0]
+        old_has_ext = repository.extension_table_exists(conn, old)
+        if old_row_count == 0 and not old_has_ext:
+            raise ValueError(f"no such record_group {old!r} in project {project!r}")
+
+        # "has rows" is checked including soft-deleted rows, and an ext table with zero rows
+        # (a schema-only group) also counts - both would otherwise collide silently with the
+        # ALTER TABLE RENAME TO / UPDATE below instead of raising a clear refusal up front.
+        new_row_count = conn.execute(
+            "SELECT COUNT(*) FROM records WHERE record_group=?", (new,)
+        ).fetchone()[0]
+        new_has_ext = repository.extension_table_exists(conn, new)
+        if new_row_count > 0 or new_has_ext:
+            raise ValueError(
+                f"record_group {new!r} already exists in project {project!r} - "
+                f"rename-group refuses to merge into an existing group"
+            )
+    finally:
+        conn.close()
+
+    proposal_path = project_root / init_paths.PROPOSAL_FILENAME
+    manifest_entry_paths: list[str] = []
+    if proposal_path.exists():
+        m = manifest.load(proposal_path)
+        manifest_entry_paths = [e.path for e in m.entries if e.record_group == old]
+
+    return RenameGroupPlan(
+        project=project, project_root=project_root, old=old, new=new,
+        row_count=old_row_count, has_extension_table=old_has_ext,
+        manifest_entry_paths=manifest_entry_paths,
+    )
+
+
+def dry_run(*, project: str, project_root: Path, old: str, new: str) -> RenameGroupPlan:
+    return _plan(project=project, project_root=project_root, old=old, new=new)
+
+
+def _rename_in_db(project: str, *, old: str, new: str) -> None:
+    conn = repository.connect(project)
+    try:
+        with repository._immediate(conn):
+            if repository.extension_table_exists(conn, old):
+                old_table = naming.extension_table_name(old)
+                new_table = naming.extension_table_name(new)
+                conn.execute(f'ALTER TABLE "{old_table}" RENAME TO "{new_table}"')
+            conn.execute("UPDATE records SET record_group=? WHERE record_group=?", (new, old))
+            conn.execute(
+                "UPDATE record_group_fields SET record_group=? WHERE record_group=?", (new, old)
+            )
+    finally:
+        conn.close()
+
+
+def _rename_in_manifest(project_root: Path, *, old: str, new: str) -> int:
+    """Returns the number of entries updated. No-op (returns 0) if the project was never
+    migrated - nothing to update against."""
+    proposal_path = project_root / init_paths.PROPOSAL_FILENAME
+    if not proposal_path.exists():
+        return 0
+    m = manifest.load(proposal_path)
+    updated = 0
+    for entry in m.entries:
+        if entry.record_group == old:
+            entry.record_group = new
+            updated += 1
+    if updated:
+        manifest.save(m, proposal_path)
+    return updated
+
+
+def write(*, project: str, project_root: Path, old: str, new: str) -> RenameGroupResult:
+    plan = _plan(project=project, project_root=project_root, old=old, new=new)
+
+    # Safety net before any write, matching reorganize.write() / init_service.write()'s own
+    # use of the same helper.
+    try:
+        backup_path = backup.create_backup(project=project, project_root=project_root)
+    except backup.BackupError as exc:
+        return RenameGroupResult(
+            plan=plan, backup_path=None, failure=RenameGroupFailure(reasons=[str(exc)]),
+        )
+
+    try:
+        _rename_in_db(project, old=old, new=new)
+    except sqlite3.Error as exc:
+        return RenameGroupResult(
+            plan=plan, backup_path=backup_path, failure=RenameGroupFailure(reasons=[str(exc)]),
+        )
+
+    # The DB rename already committed by this point - a manifest-write failure here (a
+    # permissions error, a malformed manifest another process wrote concurrently) must be
+    # reported clearly rather than silently leaving the manifest pointing at the old name,
+    # since that's exactly the "possible data loss" verify failure this command exists to
+    # prevent.
+    try:
+        _rename_in_manifest(project_root, old=old, new=new)
+    except (OSError, ValueError) as exc:
+        return RenameGroupResult(
+            plan=plan, backup_path=backup_path,
+            failure=RenameGroupFailure(reasons=[
+                f"records/record_group_fields/ext table renamed successfully, but updating "
+                f"{init_paths.PROPOSAL_FILENAME} failed: {exc} - fix it by hand for these "
+                f"paths: {plan.manifest_entry_paths}"
+            ]),
+        )
+
+    return RenameGroupResult(plan=plan, backup_path=backup_path, failure=None)

{cc_session_tools-2.8.2 → cc_session_tools-2.9.0}/src/cc_session_tools/lib/scheduler/digest.py

@@ -31,9 +31,15 @@ class JobReport:
     # SUMMARY only: number of routine entries folded into this one line.
     count: int = 0
     # RAN only: a successful-but-nonzero-exit run's captured stdout (e.g. a
-    # drift monitor's report). Always surfaced, never folded into SUMMARY -
-    # see surface.py.
+    # drift monitor's "found something" report). Always surfaced with a
+    # warning wording, never folded into SUMMARY - see surface.py.
     findings: str | None = None
+    # RAN only: a successful, zero-exit run's captured stdout (e.g. a verify
+    # command's "all OK" confirmation). Always surfaced with neutral wording,
+    # distinct from `findings`' warning wording - see surface.py. Mutually
+    # exclusive with `findings`: a given run is either a clean 0-exit or a
+    # findings-bearing nonzero exit, never both.
+    output: str | None = None
 
 
 def _ordinal(n: int) -> str:
@@ -64,24 +70,36 @@ def _line(report: JobReport) -> str | None:
             f"({_ordinal(report.consecutive_failures)} consecutive{age_suffix}) — see "
             f"`ccsched status {report.job_id}`"
         )
-    if report.outcome is Outcome.RAN and report.findings:
-        # Bypasses the surface gate deliberately, same as FAILED/SUSPENDED
-        # above: findings are signal, not routine noise a job can silence.
+    if report.outcome is Outcome.RAN:
+        # A completed run is always shown, regardless of `surface` - unlike
+        # LAUNCHED below, "it ran" is never something a job can silence.
         overdue = f" ({report.overdue} overdue)" if report.overdue else ""
-        header = f"⚠ {report.job_id} ran with findings{overdue}:"
-        body = "\n".join(f"  {line}" for line in report.findings.splitlines())
-        return f"{header}\n{body}"
+        if report.findings:
+            # Bypasses the surface gate deliberately, same as FAILED/SUSPENDED
+            # above: findings are signal, not routine noise a job can silence.
+            header = f"⚠ {report.job_id} ran with findings{overdue}:"
+            body = "\n".join(f"  {line}" for line in report.findings.splitlines())
+            return f"{header}\n{body}"
+        if report.output:
+            # A clean (0-exit) run's captured stdout - neutral wording, kept
+            # distinct from the findings/warning case above so a passing check
+            # is never mistaken for one that found something. One line-group:
+            # never falls through to the bare "✓ ran" case below.
+            header = f"✓ ran {report.job_id}{overdue}:"
+            body = "\n".join(f"  {line}" for line in report.output.splitlines())
+            return f"{header}\n{body}"
+        base = f"✓ ran {report.job_id}{overdue}"
+        if report.deferred:
+            base += f"\n⏳ {report.job_id}: {report.deferred} backfills deferred"
+        if report.expired:
+            base += f"\n   ({report.expired} missed run(s) dropped as expired)"
+        return base
+    # Only Outcome.LAUNCHED can reach here - SUMMARY/SUSPENDED/FAILED/RAN are
+    # all fully handled above and always return. A "started" notice is not
+    # "it ran", so it is the one outcome that still respects `surface`.
     if not report.surface:
         return None
-    if report.outcome is Outcome.LAUNCHED:
-        return f"▶ launched {report.job_id} (running in background)"
-    overdue = f" ({report.overdue} overdue)" if report.overdue else ""
-    base = f"✓ ran {report.job_id}{overdue}"
-    if report.deferred:
-        base += f"\n⏳ {report.job_id}: {report.deferred} backfills deferred"
-    if report.expired:
-        base += f"\n   ({report.expired} missed run(s) dropped as expired)"
-    return base
+    return f"▶ launched {report.job_id} (running in background)"
 
 
 def format_digest(reports: list[JobReport], *, parse_error: str | None = None) -> str:

{cc_session_tools-2.8.2 → cc_session_tools-2.9.0}/src/cc_session_tools/lib/scheduler/ledger.py

@@ -112,6 +112,24 @@ def read_since(offset: int) -> tuple[list[dict[str, object]], int]:
         conn.close()
 
 
+def offset_before_ts(cutoff_ts: str) -> int:
+    """The highest catchup_events id whose ts is strictly earlier than
+    cutoff_ts (0 if none) - the offset such that read_since(this) yields
+    every row with ts >= cutoff_ts. Used by the SessionStart digest's 24h
+    rolling lookback (§9.3 widen fix) to compute a starting offset without
+    loading the whole ledger table into memory; idx_catchup_events_ts makes
+    this a single index range scan rather than a full-table filter."""
+    conn = telemetry_store.connect()
+    try:
+        row = conn.execute(
+            "SELECT COALESCE(MAX(id), 0) AS m FROM catchup_events WHERE ts < ?",
+            (cutoff_ts,),
+        ).fetchone()
+        return int(row["m"])
+    finally:
+        conn.close()
+
+
 def current_offset() -> int:
     """The current max catchup_events id (0 if empty). Used to seed a
     brand-new session's cursor (§9.3) so its first digest reflects only

{cc_session_tools-2.8.2 → cc_session_tools-2.9.0}/src/cc_session_tools/lib/scheduler/notify.py

@@ -9,7 +9,12 @@ if already exported, else are parsed directly from ``~/.creds`` (override via
 ``CCCS_CREDS_PATH``) since a detached subprocess's inherited environment is not
 guaranteed to have sourced a shell profile. Every failure mode degrades to a
 logged warning and a ``False`` return — a notification that can't be sent must
-never take down the worker it's reporting on."""
+never take down the worker it's reporting on.
+
+`suspended()` is the one-time push for the auto-suspend event; `push_outcome()`
+(§ visibility fix) is the general-purpose push for every ordinary FAILED/RAN
+worker completion, wired in from worker.py's `_run_body` at the same points it
+already records the ledger event."""
 from __future__ import annotations
 
 import json
@@ -19,6 +24,8 @@ import urllib.request
 from collections.abc import Callable
 from pathlib import Path
 
+from cc_session_tools.lib.scheduler.digest import Outcome
+
 logger = logging.getLogger(__name__)
 
 _CREDS_PATH_ENV = "CCCS_CREDS_PATH"
@@ -95,3 +102,30 @@ def suspended(job_id: str, consecutive_failures: int, *, post: Poster = _default
         f"`ccsched enable {job_id}` after fixing"
     )
     return send_telegram(message, post=post)
+
+
+def _push_message(job_id: str, outcome: Outcome, detail: str | None) -> str:
+    """The single place that decides what a push message for outcome X looks
+    like. Deliberately simpler than digest.py's in-session line (no
+    overdue/deferred/expired context, no warning-vs-clean wording split) — a
+    detached worker has neither that context nor a need to match the digest
+    byte-for-byte, just to say what happened."""
+    if outcome is Outcome.FAILED:
+        suffix = f": {detail}" if detail else ""
+        return f"[cc-scheduler] {job_id} failed{suffix}"
+    suffix = f":\n{detail}" if detail else ""
+    return f"[cc-scheduler] {job_id} ran{suffix}"
+
+
+def push_outcome(
+    job_id: str, outcome: Outcome, detail: str | None = None, *, post: Poster = _default_post,
+) -> bool:
+    """Best-effort push for one worker-completion outcome (§ visibility fix).
+    Fires unconditionally for every FAILED and RAN outcome the worker
+    records — `JobSpec.surface` no longer gates run-completion visibility
+    here, matching digest.py's in-session line. Never called for
+    LAUNCHED/SUSPENDED/SUMMARY: LAUNCHED is not informative enough to push,
+    SUSPENDED already pushes via `suspended()` above, and SUMMARY is a
+    digest-only backlog-fold concept that never arises at the worker level.
+    """
+    return send_telegram(_push_message(job_id, outcome, detail), post=post)