feat(statehub): add offline write buffer relay

custodian_cli.py

@@ -465,6 +465,55 @@ def cmd_status(_args: argparse.Namespace) -> None:
             print(f"  [{deadline}] {d['title']}")
 
 
+
+def _outbox_store(args):
+    from api.edge.outbox import OutboxStore, default_outbox_path
+
+    return OutboxStore(args.outbox_path or default_outbox_path())
+
+
+def cmd_outbox_status(args: argparse.Namespace) -> None:
+    store = _outbox_store(args)
+    print(json.dumps(store.summary(), indent=2))
+
+
+def cmd_outbox_list(args: argparse.Namespace) -> None:
+    store = _outbox_store(args)
+    rows = store.export(status=args.status, limit=args.limit)
+    print(json.dumps(rows, indent=2))
+
+
+def cmd_outbox_export(args: argparse.Namespace) -> None:
+    store = _outbox_store(args)
+    payload = store.export(status=args.status, limit=args.limit)
+    if args.output:
+        Path(args.output).write_text(json.dumps(payload, indent=2) + "\n")
+        print(f"Exported {len(payload)} envelope(s) to {args.output}")
+    else:
+        print(json.dumps(payload, indent=2))
+
+
+def cmd_outbox_replay(args: argparse.Namespace) -> None:
+    import asyncio
+    from api.edge.relay import replay_pending
+
+    store = _outbox_store(args)
+    upstream = args.upstream_url or os.environ.get("STATEHUB_UPSTREAM_URL") or API_BASE
+    result = asyncio.run(replay_pending(store, upstream_url=upstream, limit=args.limit))
+    print(json.dumps(result, indent=2))
+
+
+def cmd_outbox_retry(args: argparse.Namespace) -> None:
+    store = _outbox_store(args)
+    store.retry(args.envelope_id)
+    print(f"Queued {args.envelope_id} for retry")
+
+
+def cmd_outbox_cancel(args: argparse.Namespace) -> None:
+    store = _outbox_store(args)
+    store.cancel(args.envelope_id)
+    print(f"Cancelled {args.envelope_id}")
+
 # ── Entry point ────────────────────────────────────────────────────────────────
 
 def main() -> None:
@@ -549,12 +598,47 @@ def main() -> None:
     ctask.add_argument("--assignee", default=None)
     ctask.add_argument("--description", default=None)
 
+
+    # outbox
+    outbox = sub.add_parser("outbox", help="Inspect and replay the local State Hub edge outbox")
+    outbox.add_argument("--outbox-path", default=None, help="SQLite outbox path (defaults to ~/.statehub/edge-outbox.sqlite3)")
+    out_sub = outbox.add_subparsers(dest="outbox_command", required=True)
+
+    out_status = out_sub.add_parser("status", help="Show pending, conflict, and ack counts")
+    out_status.set_defaults(func=cmd_outbox_status)
+
+    out_list = out_sub.add_parser("list", help="List outbox envelopes as JSON")
+    out_list.add_argument("--status", default=None, help="Filter by status")
+    out_list.add_argument("--limit", type=int, default=100)
+    out_list.set_defaults(func=cmd_outbox_list)
+
+    out_export = out_sub.add_parser("export", help="Export non-secret envelopes")
+    out_export.add_argument("--status", default=None, help="Filter by status")
+    out_export.add_argument("--limit", type=int, default=1000)
+    out_export.add_argument("--output", default=None, help="Write JSON to a file instead of stdout")
+    out_export.set_defaults(func=cmd_outbox_export)
+
+    out_replay = out_sub.add_parser("replay", help="Replay due queued envelopes")
+    out_replay.add_argument("--upstream-url", default=None, help="Central State Hub API base URL")
+    out_replay.add_argument("--limit", type=int, default=50)
+    out_replay.set_defaults(func=cmd_outbox_replay)
+
+    out_retry = out_sub.add_parser("retry", help="Force one envelope back to queued")
+    out_retry.add_argument("envelope_id")
+    out_retry.set_defaults(func=cmd_outbox_retry)
+
+    out_cancel = out_sub.add_parser("cancel", help="Cancel one envelope")
+    out_cancel.add_argument("envelope_id")
+    out_cancel.set_defaults(func=cmd_outbox_cancel)
+
     # status
     sub.add_parser("status", help="Show State Hub health and summary totals")
 
     args = parser.parse_args()
 
-    if args.command == "register":
+    if hasattr(args, "func"):
+        args.func(args)
+    elif args.command == "register":
         run_statehub_register(args)
     elif args.command == "register-project":
         cmd_register(args)