@hasna/economy 0.5.4 → 0.5.6

package/dist/server/service-worker.js

@@ -4288,8 +4288,8 @@ function sourceTimeMillis(value) {
 init_database();
 init_pricing();
 import { readdirSync as readdirSync2, readFileSync as readFileSync2, existsSync as existsSync5, statSync as statSync2 } from "fs";
-import { homedir as homedir3 } from "os";
-import { join as join4, basename } from "path";
+import { homedir as homedir4 } from "os";
+import { join as join5, basename } from "path";
 
 // src/lib/accounts-store.ts
 import { existsSync as existsSync4, readFileSync } from "fs";
@@ -4912,12 +4912,41 @@ function withAccount(record, account) {
   };
 }
 
+// src/lib/paths.ts
+import { homedir as homedir3 } from "os";
+import { join as join4 } from "path";
+function getHomeDir2() {
+  return process.env["USERPROFILE"] ?? process.env["HOME"] ?? homedir3();
+}
+function agentPaths() {
+  const home = getHomeDir2();
+  const claudeHome = process.env["CLAUDE_CONFIG_DIR"] || join4(home, ".claude");
+  const codexHome = process.env["CODEX_HOME"] || join4(home, ".codex");
+  return {
+    claudeProjects: join4(claudeHome, "projects"),
+    claudeCredentials: join4(claudeHome, ".credentials.json"),
+    takumiProjects: join4(home, ".takumi", "projects"),
+    codexDir: codexHome,
+    codexDb: join4(codexHome, "state_5.sqlite"),
+    codexAuth: join4(codexHome, "auth.json"),
+    codexConfig: join4(codexHome, "config.toml"),
+    geminiTmp: join4(home, ".gemini", "tmp"),
+    geminiHistory: join4(home, ".gemini", "history"),
+    opencodeMessages: join4(home, ".local", "share", "opencode", "storage", "message"),
+    piSessions: join4(home, ".pi", "agent", "sessions"),
+    hermesDir: join4(home, ".hermes"),
+    hermesDb: join4(home, ".hermes", "state.db")
+  };
+}
+
 // src/ingest/claude.ts
 function autoDetectProject(cwd, projects) {
   return projects.find((p) => cwd === p.path || cwd.startsWith(p.path + "/"));
 }
-var CLAUDE_PROJECTS_DIR = process.env["HASNA_ECONOMY_CLAUDE_PROJECTS_DIR"] ?? join4(homedir3(), ".claude", "projects");
-var TAKUMI_PROJECTS_DIR = process.env["HASNA_ECONOMY_TAKUMI_PROJECTS_DIR"] ?? join4(homedir3(), ".takumi", "projects");
+var TAKUMI_PROJECTS_DIR = process.env["HASNA_ECONOMY_TAKUMI_PROJECTS_DIR"] ?? join5(homedir4(), ".takumi", "projects");
+function claudeProjectsDir() {
+  return process.env["HASNA_ECONOMY_CLAUDE_PROJECTS_DIR"] ?? agentPaths().claudeProjects;
+}
 function dirNameToPath(dirName) {
   return dirName.replace(/^-/, "/").replace(/-/g, "/").replace(/\/\//g, "/-");
 }
@@ -4927,9 +4956,9 @@ function collectJsonlFiles(projectDir) {
     try {
       for (const entry of readdirSync2(dir, { withFileTypes: true })) {
         if (entry.isDirectory())
-          walk(join4(dir, entry.name));
+          walk(join5(dir, entry.name));
         else if (entry.name.endsWith(".jsonl"))
-          files.push(join4(dir, entry.name));
+          files.push(join5(dir, entry.name));
       }
     } catch {
       collectionProblem("failed", "source_unreadable");
@@ -4938,7 +4967,7 @@ function collectJsonlFiles(projectDir) {
   walk(projectDir);
   return files;
 }
-async function ingestClaude(db, verbose = false, projectsDir = CLAUDE_PROJECTS_DIR) {
+async function ingestClaude(db, verbose = false, projectsDir = claudeProjectsDir()) {
   return ingestJsonlProjects(db, projectsDir, "claude", verbose);
 }
 async function ingestTakumi(db, verbose = false, projectsDir = TAKUMI_PROJECTS_DIR) {
@@ -4960,7 +4989,7 @@ async function ingestJsonlProjects(db, projectsDir, agentName, verbose = false)
   const ingestState = loadIngestState(db, agentName);
   const projectDirs = readdirSync2(projectsDir, { withFileTypes: true }).filter((d) => d.isDirectory());
   for (const projectDirEntry of projectDirs) {
-    const projectDirPath = join4(projectsDir, projectDirEntry.name);
+    const projectDirPath = join5(projectsDir, projectDirEntry.name);
     const projectPath = dirNameToPath(projectDirEntry.name);
     const jsonlFiles = collectJsonlFiles(projectDirPath);
     for (const filePath of jsonlFiles) {
@@ -5111,24 +5140,19 @@ init_database();
 init_pricing();
 import { existsSync as existsSync6, readFileSync as readFileSync3, statSync as statSync3 } from "fs";
 import { createHash as createHash4 } from "crypto";
-import { homedir as homedir4 } from "os";
-import { join as join5, basename as basename2 } from "path";
-var DEFAULT_CODEX_DB_PATH = join5(homedir4(), ".codex", "state_5.sqlite");
-var DEFAULT_CODEX_CONFIG_PATH = join5(homedir4(), ".codex", "config.toml");
-var DEFAULT_CODEWITH_DB_PATH = join5(homedir4(), ".codewith", "state_5.sqlite");
-var DEFAULT_CODEWITH_CONFIG_PATH = join5(homedir4(), ".codewith", "config.toml");
+import { join as join6, basename as basename2 } from "path";
 var CODEX_INGEST_VERSION = "rollout-events-v4";
 function codexDbPath() {
-  return process.env["HASNA_ECONOMY_CODEX_DB_PATH"] ?? DEFAULT_CODEX_DB_PATH;
+  return process.env["HASNA_ECONOMY_CODEX_DB_PATH"] ?? agentPaths().codexDb;
 }
 function codexConfigPath() {
-  return process.env["HASNA_ECONOMY_CODEX_CONFIG_PATH"] ?? DEFAULT_CODEX_CONFIG_PATH;
+  return process.env["HASNA_ECONOMY_CODEX_CONFIG_PATH"] ?? agentPaths().codexConfig;
 }
 function codewithDbPath() {
-  return process.env["HASNA_ECONOMY_CODEWITH_DB_PATH"] ?? DEFAULT_CODEWITH_DB_PATH;
+  return process.env["HASNA_ECONOMY_CODEWITH_DB_PATH"] ?? join6(getHomeDir2(), ".codewith", "state_5.sqlite");
 }
 function codewithConfigPath() {
-  return process.env["HASNA_ECONOMY_CODEWITH_CONFIG_PATH"] ?? DEFAULT_CODEWITH_CONFIG_PATH;
+  return process.env["HASNA_ECONOMY_CODEWITH_CONFIG_PATH"] ?? join6(getHomeDir2(), ".codewith", "config.toml");
 }
 function codexSources() {
   const explicitCodexPath = process.env["HASNA_ECONOMY_CODEX_DB_PATH"];
@@ -5140,7 +5164,7 @@ function codexSources() {
     sessionPrefix: "codex",
     stateSource: "codex"
   }];
-  if (!explicitCodexPath || explicitCodewithPath) {
+  if (!explicitCodexPath && !process.env["CODEX_HOME"] || explicitCodewithPath) {
     sources.push({
       label: "Codewith",
       dbPath: codewithDbPath(),
@@ -5380,9 +5404,9 @@ init_database();
 init_pricing();
 import { readdirSync as readdirSync3, readFileSync as readFileSync4, existsSync as existsSync7, statSync as statSync4 } from "fs";
 import { homedir as homedir5 } from "os";
-import { join as join6, basename as basename3 } from "path";
-var DEFAULT_GEMINI_TMP_DIR = join6(homedir5(), ".gemini", "tmp");
-var DEFAULT_GEMINI_HISTORY_DIR = join6(homedir5(), ".gemini", "history");
+import { join as join7, basename as basename3 } from "path";
+var DEFAULT_GEMINI_TMP_DIR = join7(homedir5(), ".gemini", "tmp");
+var DEFAULT_GEMINI_HISTORY_DIR = join7(homedir5(), ".gemini", "history");
 function geminiTmpDir() {
   return process.env["HASNA_ECONOMY_GEMINI_TMP_DIR"] ?? DEFAULT_GEMINI_TMP_DIR;
 }
@@ -5404,7 +5428,7 @@ function listProjectDirs(...roots) {
     try {
       for (const entry of readdirSync3(root, { withFileTypes: true })) {
         if (entry.isDirectory())
-          dirs.add(join6(root, entry.name));
+          dirs.add(join7(root, entry.name));
       }
     } catch {
       collectionProblem("failed", "source_unreadable");
@@ -5417,7 +5441,7 @@ function projectRoot(projectDir, chatData) {
     return chatData.projectPath;
   if (chatData.project_path)
     return chatData.project_path;
-  const rootFile = join6(projectDir, ".project_root");
+  const rootFile = join7(projectDir, ".project_root");
   try {
     if (existsSync7(rootFile))
       return readFileSync4(rootFile, "utf-8").trim();
@@ -5442,12 +5466,12 @@ async function ingestGemini(db, verbose) {
   const account = await resolveAccountForAgent("gemini");
   const projectDirs = listProjectDirs(tmpDir, historyDir);
   for (const projectDir of projectDirs) {
-    const chatsDir = join6(projectDir, "chats");
+    const chatsDir = join7(projectDir, "chats");
     if (!existsSync7(chatsDir))
       continue;
     let chatFiles = [];
     try {
-      chatFiles = readdirSync3(chatsDir).filter((f) => f.endsWith(".json")).map((f) => join6(chatsDir, f));
+      chatFiles = readdirSync3(chatsDir).filter((f) => f.endsWith(".json")).map((f) => join7(chatsDir, f));
     } catch {
       collectionProblem("failed", "source_unreadable");
       continue;
@@ -5559,13 +5583,13 @@ init_database();
 init_pricing();
 import { existsSync as existsSync8, readFileSync as readFileSync5, readdirSync as readdirSync4, statSync as statSync5 } from "fs";
 import { homedir as homedir6 } from "os";
-import { join as join7 } from "path";
-var OPENCODE_STORAGE = join7(homedir6(), ".local", "share", "opencode", "storage");
+import { join as join8 } from "path";
+var OPENCODE_STORAGE = join8(homedir6(), ".local", "share", "opencode", "storage");
 function walkJsonFiles(dir, acc = []) {
   if (!existsSync8(dir))
     return acc;
   for (const entry of readdirSync4(dir, { withFileTypes: true })) {
-    const p = join7(dir, entry.name);
+    const p = join8(dir, entry.name);
     if (entry.isDirectory())
       walkJsonFiles(p, acc);
     else if (entry.name.endsWith(".json"))
@@ -5585,7 +5609,7 @@ function parseSessionIdFromPath(filePath) {
   return null;
 }
 async function ingestOpenCode(db, verbose = false, sourceDir = OPENCODE_STORAGE) {
-  const messageDir = join7(sourceDir, "message");
+  const messageDir = join8(sourceDir, "message");
   if (!existsSync8(messageDir))
     collectionProblem("missing", "source_missing");
   const files = walkJsonFiles(messageDir);
@@ -5780,13 +5804,13 @@ async function ingestCursor(db, verbose = false) {
 init_database();
 import { existsSync as existsSync9, readFileSync as readFileSync6, readdirSync as readdirSync5, statSync as statSync6 } from "fs";
 import { homedir as homedir7 } from "os";
-import { join as join8 } from "path";
-var PI_SESSION_DIR = process.env["PI_CODING_AGENT_SESSION_DIR"] ?? join8(homedir7(), ".pi", "agent", "sessions");
+import { join as join9 } from "path";
+var PI_SESSION_DIR = process.env["PI_CODING_AGENT_SESSION_DIR"] ?? join9(homedir7(), ".pi", "agent", "sessions");
 function walkSessions(dir, acc = []) {
   if (!existsSync9(dir))
     return acc;
   for (const entry of readdirSync5(dir, { withFileTypes: true })) {
-    const p = join8(dir, entry.name);
+    const p = join9(dir, entry.name);
     if (entry.isDirectory())
       walkSessions(p, acc);
     else if (entry.name.endsWith(".json"))
@@ -5887,8 +5911,8 @@ async function ingestPi(db, verbose = false, sourceDir = PI_SESSION_DIR) {
 init_database();
 import { existsSync as existsSync10, statSync as statSync7 } from "fs";
 import { homedir as homedir8 } from "os";
-import { join as join9 } from "path";
-var HERMES_DB = join9(homedir8(), ".hermes", "state.db");
+import { join as join10 } from "path";
+var HERMES_DB = join10(homedir8(), ".hermes", "state.db");
 async function ingestHermes(db, verbose = false, sourcePath = HERMES_DB) {
   if (!existsSync10(sourcePath)) {
     collectionProblem("missing", "source_missing");
@@ -5958,7 +5982,7 @@ init_database();
 init_pricing();
 import { existsSync as existsSync11 } from "fs";
 import { homedir as homedir9 } from "os";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 import { homedir as pathsResolverHomedir2 } from "os";
 import { join as pathsResolverJoin2 } from "path";
 var PATHS_RESOLVER_KIND_ENV2 = {
@@ -6025,8 +6049,8 @@ function defaultLoopsDbPath() {
     app: "loops",
     home: process.env["HOME"] || process.env["USERPROFILE"] || undefined
   });
-  const legacy = join10(process.env["HOME"] || process.env["USERPROFILE"] || homedir9(), ".hasna", "loops", "loops.db");
-  return existsSync11(join10(resolved, "loops.db")) ? join10(resolved, "loops.db") : legacy;
+  const legacy = join11(process.env["HOME"] || process.env["USERPROFILE"] || homedir9(), ".hasna", "loops", "loops.db");
+  return existsSync11(join11(resolved, "loops.db")) ? join11(resolved, "loops.db") : legacy;
 }
 function loopsDbPath() {
   return process.env["HASNA_ECONOMY_LOOPS_DB_PATH"] ?? defaultLoopsDbPath();
@@ -6210,33 +6234,6 @@ async function ingestLoops(db, verbose = false) {
 
 // src/ingest/claude-quota.ts
 import { existsSync as existsSync12, readFileSync as readFileSync7 } from "fs";
-
-// src/lib/paths.ts
-import { homedir as homedir10 } from "os";
-import { join as join11 } from "path";
-function getHomeDir2() {
-  return process.env["USERPROFILE"] ?? process.env["HOME"] ?? homedir10();
-}
-function agentPaths() {
-  const home = getHomeDir2();
-  return {
-    claudeProjects: join11(home, ".claude", "projects"),
-    claudeCredentials: join11(home, ".claude", ".credentials.json"),
-    takumiProjects: join11(home, ".takumi", "projects"),
-    codexDir: join11(home, ".codex"),
-    codexDb: join11(home, ".codex", "state_5.sqlite"),
-    codexAuth: join11(home, ".codex", "auth.json"),
-    codexConfig: join11(home, ".codex", "config.toml"),
-    geminiTmp: join11(home, ".gemini", "tmp"),
-    geminiHistory: join11(home, ".gemini", "history"),
-    opencodeMessages: join11(home, ".local", "share", "opencode", "storage", "message"),
-    piSessions: join11(home, ".pi", "agent", "sessions"),
-    hermesDir: join11(home, ".hermes"),
-    hermesDb: join11(home, ".hermes", "state.db")
-  };
-}
-
-// src/ingest/claude-quota.ts
 var USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
 var OAUTH_BETA = "oauth-2025-04-20";
 function readClaudeToken() {
@@ -7429,7 +7426,7 @@ import { randomUUID } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/economy",
-  version: "0.5.4",
+  version: "0.5.6",
   description: "AI coding cost tracker \u2014 CLI + MCP server + REST API for Claude Code, Codex, OpenCode, Cursor, Pi, and Hermes, with legacy Gemini CLI session and Gemini API billing ingestion",
   repository: {
     type: "git",
@@ -7462,6 +7459,8 @@ var package_default = {
   files: [
     "dist",
     "docs",
+    "native/Tools/pair-qr.py",
+    "native/Tools/pair-qr.swift",
     "postinstall.js",
     "LICENSE",
     "README.md",

package/native/README.md

@@ -0,0 +1,131 @@
+# Economy native applications
+
+Shared Swift models, canonical HTTPS clients and SwiftUI reports for the Mac
+menu bar (`../menubar/App`) and iPhone (`../ios`). Minimum macOS 14 / iOS 17;
+system glass controls on OS 26. Opaque data cards/lists, semantic fonts, Dynamic
+Type and native navigation retain the approved Usage / Spend direction.
+
+## Authentication and activation
+
+iPhone sign-in uses Scan pairing code, with a secure Paste fallback. The Mac
+shows a five-minute QR code; the signed-in iPhone inspects the computer and
+workspace and explicitly approves read-only access. Each device gets its own
+Economy-only Identities session. Scanning never approves a Mac automatically.
+
+The native adapter calls the pinned `economy-pairing` routes at
+`https://api.hasna.com/identities/v1`, selects the returned workspace, exchanges
+short-lived Economy tokens, refreshes and revokes the exact session on logout.
+The session stays in device-only Keychain storage after first unlock. The
+Economy access token stays in memory and goes only to
+`https://api.hasna.com/economy/v1`. Redirects, foreign QR authorities and responses
+with another app or tenant are refused. No station key importer, local server
+fallback or connect URL scheme is registered.
+
+An already authorized human session bootstraps the iPhone through
+`python3 native/Tools/pair-qr.py --tenant <workspace-id> --session-ref <human-session-reference>`.
+The launcher opens the owner's Terminal and projects the named Secrets reference
+there as `ECONOMY_HUMAN_SESSION`; it returns no Terminal output. Both issuer and
+renderer verify the direct Terminal ancestry and refuse captured harness PTYs.
+Never run real codes in a captured agent terminal. The helper obtains a
+single-use code, hands only that temporary code to the CoreImage renderer and
+clears the display within five minutes. `--self-test` decodes a synthetic QR;
+`test_pair_qr.py` proves transcript/agent-key refusal and credential confinement.
+The existing Identities human login flow remains the bootstrap when no human
+session exists; pairing does not create or assume an account.
+
+The adapter verifies Economy's `/auth/session` subject, tenant, effective scopes
+and integer expiry. Viewer sign-in never requests write access. Refresh and period
+changes cannot orphan an active send-code/verify/workspace operation. Write-only users
+remain signed in with a specific no-report-read-access state; native Save needs
+both write permission and the readback used to confirm the rule. Refresh and
+account/period changes fence pending responses. Sign-out clears local state first
+and reports unconfirmed remote revocation. A stale logout cannot clear a new login.
+
+**Hosted activation is off by default.** A reviewed delivery build passes
+`auth-enabled`; the build receipt records the exact activation value, version and
+build. An inactive artifact is not completed native delivery. Activation also
+requires the reviewed human audience, independently verified store tenant and
+principal allowlist, live grants, deployed server changes and owner-initiated
+sign-in acceptance. No automated real OTP/email operation was performed here.
+
+## Reports and exact budget recovery
+
+Reports use a captured session with generation/expiry checks before and after
+network work. Responses are capped at 8 MiB with at most four concurrent reads.
+Session and period changes cancel old work and clear the report. A failed refresh
+retains the original acquisition time; a 401/403 clears private data. Report cache
+is memory-only. Persistent offline reports are not implemented.
+
+Subscriptions, account breakdowns and quota observations use current unpaginated
+server arrays. Sessions traverse 100-row offset pages to a short final page, with
+a 2,000-record bound and visible truncation. Duplicate pages fail closed. Offset
+traversal is not a consistent snapshot; open records do not establish live work.
+Totals cover the complete returned population independently of search/visible
+rows. Known valuation subtotals distinguish missing prices/bases from affirmative
+known zero; exact acquired UTC calendar bounds remain separate from local timestamp
+display, including cached reports. Unknown fees and provider coverage remain explicit.
+Quota selection uses source time before station recording time, expires at reset or
+15 minutes, and a native one-second view timeline reevaluates it without network
+activity. Historical readings remain labeled. Budget scope labels include every
+project, agent and cost-center restriction conjunctively. Station timestamps
+are reported observations, not proof of a complete online fleet.
+
+Copy prompt is the first budget control. Its prominent action uses an explicit
+foreground/background pair in both appearances. Secondary Save requires current
+read and write permission again before dispatch/retry, and creates one immutable
+`metered_api_usd` rule through `/ingest`, then verifies its actor-bound receipt
+and authoritative budget status. It excludes subscriptions, estimates, unknown
+cost bases and provider billing. Calendar windows are UTC; weeks start Sunday.
+Saved rules are alert thresholds, never spending enforcement or verified delivery.
+
+Before POST, the complete command, stable UUID key and canonical body hash are
+persisted and read back in account-bound Keychain recovery storage. After response
+loss or restart, only explicit receipt checks and exact same-command retries are
+offered. An absent receipt does not prove an earlier request cannot commit. A new
+key never resolves an uncertain command. Retained recovery history is bounded to
+40 commands per account and fails closed at the bound. This is operational intent,
+not a local authoritative report store. The typed canonical JSON writer has hash
+parity vectors from the actual server, including Unicode and scalar edge cases.
+
+## Build and test
+
+Use an exact committed source copy on an Xcode 26 Mac. The dependency-free runner
+creates synthetic HOME/cache/DerivedData, kernel-enforces read-only station/source
+files, denies network, runs positive/negative write controls and checks source
+hashes. It invokes installed Apple `swiftc`, SDK and XCTest directly. Refused
+Xcode/SwiftPM shared temporary writes remain in task evidence; no boundary was
+relaxed to make those paths work.
+
+```sh
+python3 apps/economy/native/Tools/build-isolated.py test /absolute/.hasna/scratchpad/scratch/session/test-1
+python3 apps/economy/native/Tools/build-isolated.py mac /absolute/.hasna/scratchpad/scratch/session/mac-1 Release auth-disabled
+python3 apps/economy/native/Tools/build-isolated.py ios /absolute/.hasna/scratchpad/scratch/session/ios-1 Debug
+python3 apps/economy/native/Tools/build-isolated.py device /absolute/.hasna/scratchpad/scratch/session/device-1 Release auth-disabled
+# Reviewed delivery preparation supplies both actual release metadata values:
+# ... mac FRESH_PATH Release auth-enabled VERSION BUILD
+```
+
+Omitted version/build use fixture-only `0.1.0` / `1`, clearly recorded in the
+receipt. The existing macOS identifier is `com.hasna.economy-bar`, product
+`HasnaEconomy.app`, display name `HasnaEconomy`, and LSUIElement is true. No new
+identifier or signing registration is created. Signed iPhone identity, signing,
+notarization, installation and distribution remain coordinator operations.
+
+Debug apps accept `-demo -demoRoute usage|spend|unknown|account|budget|offline|empty|loading|error`.
+The 125-subscription fixture uses distinct provider/account IDs and no files,
+network or credential storage, even in an auth-enabled Debug build. Release
+must exclude fixture markers and arguments, using Debug as the positive control.
+The former localhost menu-bar Sources/Tests/Tools/Resources are retained but
+excluded by the replacement Package.swift target.
+
+`Tools/capture-ios.py` requires an explicit owned simulator/device set/name,
+captures light/dark and largest Dynamic Type, then shuts down only that device.
+The Mac helper captures only its own fresh fixture application's windows; its
+station14 SSH window-discovery failure remains open. A fixture window is not
+menu-bar interaction acceptance. Actual Mac interaction, keyboard/VoiceOver,
+minimum-OS fallback and signed-device acceptance are separate from compiler and
+fixture checks. Owner-facing screen captures go through Designs.
+
+Apple references: [MenuBarExtra](https://developer.apple.com/documentation/swiftui/menubarextra),
+[native design adoption](https://developer.apple.com/videos/play/wwdc2025/323/),
+[application delegate adaptor](https://developer.apple.com/documentation/swiftui/nsapplicationdelegateadaptor).

package/native/Tools/pair-qr.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Show a one-use Economy connection code only in the owner's Terminal.
+
+Pass an existing authorized human Identities session's Secrets reference using
+--session-ref. The launcher opens Terminal and projects it there. The server
+verifies the session and selected tenant; no station agent key works.
+"""
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import shlex
+import subprocess
+import sys
+import urllib.request
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+def owner_terminal():
+    """Refuse captured harness PTYs, including a CLI inside a Terminal window.
+
+    This prevents accidental transcript delivery; it is not a privilege boundary
+    against another process running as the owner. Never screen-capture the code.
+    """
+    if not sys.stdout.isatty() or not sys.stdin.isatty():
+        return False
+    if any(os.environ.get(key) for key in ['CODEX_THREAD_ID', 'CODEX_INTERNAL_ORIGINATOR_OVERRIDE',
+                                          'CLAUDECODE', 'SUMI_SESSION_ID', 'OPENCODE_SESSION_ID']):
+        return False
+    pid = os.getppid()
+    for _ in range(12):
+        try:
+            result = subprocess.run(['/bin/ps', '-p', str(pid), '-o', 'ppid=', '-o', 'comm='],
+                                    capture_output=True, text=True, timeout=3)
+        except (OSError, subprocess.TimeoutExpired):
+            return False
+        if result.returncode:
+            return False
+        fields = result.stdout.strip().split(None, 1)
+        if len(fields) != 2 or not fields[0].isdigit():
+            return False
+        parent, executable = int(fields[0]), fields[1]
+        if executable == '/System/Applications/Utilities/Terminal.app/Contents/MacOS/Terminal':
+            return True
+        if Path(executable).name not in ['Python', 'python3', 'bash', 'zsh', 'login', 'bun', 'secrets']:
+            return False
+        if parent <= 1 or parent == pid:
+            return False
+        pid = parent
+    return False
+
+
+def launch_owner_terminal(reference, tenant):
+    if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_./-]{0,254}', reference):
+        print('Invalid Secrets reference.', file=sys.stderr)
+        return 2
+    # AppleScript receives references and paths only. Its returned text never
+    # contains Terminal output. No QR or credential is returned to this process.
+    command = shlex.join(['secrets', 'exec', reference, '--as', 'ECONOMY_HUMAN_SESSION', '--',
+                          '/usr/bin/python3', str(Path(__file__).resolve()), '--owner-terminal', '--tenant', tenant])
+    script = 'tell application "Terminal"\nactivate\ndo script ' + json.dumps(command) + '\nend tell\n'
+    try:
+        result = subprocess.run(['/usr/bin/osascript', '-'], input=script, text=True, capture_output=True, timeout=30)
+    except (OSError, subprocess.TimeoutExpired):
+        print('Could not confirm the owner Terminal window. Check Terminal before retrying.', file=sys.stderr)
+        return 1
+    if result.returncode:
+        print('Could not open the owner Terminal window. No code was displayed by this process.', file=sys.stderr)
+        return 1
+    print('Opened the Economy pairing window on this Mac. Scan it with Economy on your iPhone.')
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--tenant', help='Exact workspace ID, resolved through Identities')
+    parser.add_argument('--self-test', action='store_true')
+    parser.add_argument('--session-ref', help='Authorized human-session reference in Secrets; never a value')
+    parser.add_argument('--owner-terminal', action='store_true', help=argparse.SUPPRESS)
+    args = parser.parse_args()
+    human = os.environ.pop('ECONOMY_HUMAN_SESSION', None)
+    renderer = Path(__file__).with_name('pair-qr.swift')
+    if args.self_test:
+        return subprocess.run(['/usr/bin/swift', str(renderer), '--self-test']).returncode
+    if not args.tenant or not re.fullmatch(r'[A-Za-z0-9_-]{1,255}', args.tenant):
+        print('Provide the exact authorized workspace with --tenant.', file=sys.stderr)
+        return 2
+    if not args.owner_terminal:
+        if not args.session_ref:
+            print('Use --session-ref to open the owner Terminal. Credential values are not accepted here.', file=sys.stderr)
+            return 3
+        return launch_owner_terminal(args.session_ref, args.tenant)
+    if args.session_ref or not owner_terminal():
+        print('Refusing to show a connection code outside the direct owner Terminal path.', file=sys.stderr)
+        return 3
+    if not human or not re.fullmatch(r'hst_[A-Za-z0-9_-]{43}', human):
+        print('An existing human Identities session is required via ECONOMY_HUMAN_SESSION. Station keys are refused.', file=sys.stderr)
+        return 2
+    request = urllib.request.Request('https://api.hasna.com/identities/v1/auth/economy-pairing/issue',
+        data=json.dumps({'tenant_id': args.tenant, 'device_name': 'Your iPhone'}).encode(),
+        headers={'Authorization': 'Bearer ' + human, 'Content-Type': 'application/json',
+                 'Accept': 'application/json', 'User-Agent': 'Hasna-Economy-Pairing/1.0'}, method='POST')
+    try:
+        with urllib.request.build_opener(NoRedirect).open(request, timeout=15) as response:
+            raw = response.read(8193)
+            if response.status != 200 or len(raw) > 8192:
+                raise ValueError('response')
+        value = json.loads(raw)
+        if not re.fullmatch(r'hec_[A-Za-z0-9_-]{43}', value.get('code', '')) or not 1 <= value.get('expires_in', 0) <= 300:
+            raise ValueError('response')
+    except Exception:
+        print('Unable to issue the connection code. Check the human session, workspace and hosted pairing service.', file=sys.stderr)
+        return 1
+    human = None
+    # Only the temporary code goes to the renderer. The human session was
+    # removed from the environment before any child was started.
+    environment = {k: v for k, v in os.environ.items() if k in
+                   ['PATH', 'HOME', 'TMPDIR', 'LANG', 'TERM', 'DEVELOPER_DIR', 'CLANG_MODULE_CACHE_PATH']}
+    environment['ECONOMY_PAIR_CODE'] = value['code']
+    environment['ECONOMY_PAIR_SERVER'] = 'https://api.hasna.com/economy'
+    environment['ECONOMY_PAIR_TTL'] = str(value['expires_in'])
+    return subprocess.run(['/usr/bin/swift', str(renderer)], env=environment).returncode
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())