code-context-control 2.122.0__py3-none-any.whl → 2.124.0__py3-none-any.whl

cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.122.0"
+__version__ = "2.124.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -271,7 +271,7 @@ _STALE_MCP_TOOLS = {
     "mcp__c3__c3_remember",           # → c3_memory(action='add')
     "mcp__c3__c3_recall",             # → c3_memory(action='recall')
     "mcp__c3__c3_sltm_add",           # → c3_memory(action='add')
-    "mcp__c3__c3_file_map",           # → c3_compress(mode='map')
+    "mcp__c3__c3_file_map",           # → c3_read(file_path) map
     "mcp__c3__c3_extract",            # → c3_read
     "mcp__c3__c3_transcript_search",  # → c3_search(action='transcript')
     "mcp__c3__c3_session_log",        # → c3_session(action='log')
@@ -3971,7 +3971,7 @@ def cmd_benchmark(args):
             "prompt_budget_multiplier": round(_prompt_gain(comp_comp, comp_orig), 2),
         },
         "file_navigation": {
-            "description": "Use c3_compress(mode='map') to choose targeted reads instead of opening whole files blindly.",
+            "description": "Use the c3_read file map to choose targeted reads instead of opening whole files blindly.",
             "performance_metric": "map success rate",
             "with_c3": {"tool": "c3_compress(mode='map')", "total_tokens": file_map_comp, "avg_latency_ms": round(_avg(file_map_c3_latencies), 2), "performance": round((file_map_successes / len(file_map_sample) * 100), 1) if file_map_sample else 0.0},
             "without_c3": {"approach": "read full files into context", "total_tokens": file_map_orig, "avg_latency_ms": round(_avg(file_map_baseline_latencies), 2), "performance": 100.0},
@@ -5005,7 +5005,7 @@ back to native tools as the task progresses.
 
 ## Quick Reference
 - **Search**: `c3_search(query=..., action='code|files|semantic')` — before Grep/Glob
-- **Read**: `c3_compress(mode='map')` then `c3_read(symbols=...)` — before native Read
+- **Read**: `c3_read(file_path)` maps a file (or directory), then `c3_read(symbols=['Class.method'])` — before native Read
 - **Impact**: `c3_impact(target='symbol')` — blast-radius check before editing shared symbols
 - **Edit**: `c3_edit(file_path=..., old_string=..., new_string=...)` — before Edit/Write
 - **Validate**: `c3_validate(file_path=...)` — after every edit (pyright/tsc type check if installed)

cli/guide/index.html

@@ -636,7 +636,7 @@
             <span>Discover files / content — never start with Grep/Glob</span>
           </div>
           <div class="quick-item">
-            <code>3. c3_compress(mode='map') + c3_read(symbols=…)</code>
+            <code>3. c3_read(file_path) + c3_read(symbols=…)</code>
             <span>Map then surgically read — never start with native Read</span>
           </div>
           <div class="quick-item">

cli/guide/workflow.html

@@ -315,7 +315,7 @@
           <tr>
             <td><span class="badge badge-blue">3</span></td>
             <td><strong>Map + Read</strong></td>
-            <td><code>c3_compress(mode='map')</code> → <code>c3_read(symbols=…)</code></td>
+            <td><code>c3_read(file_path)</code> (map) → <code>c3_read(symbols=…)</code></td>
             <td>Before reading any file content</td>
           </tr>
           <tr>

cli/hook_pretool_enforce.py

@@ -130,7 +130,7 @@ _VAULT_FILES = frozenset({"config.json", "secrets.enc", "cred_state.json",
 # Redirect messages per native tool
 _REDIRECTS = {
     "Read": (
-        "Use c3_compress(file_path='...', mode='map') to map the file first, "
+        "Use c3_read(file_path='...') to map the file first (one line per symbol), "
         "then c3_read(file_path='...', symbols=['...']) for surgical extraction."
     ),
     "Grep": (

cli/mcp_server.py

@@ -47,7 +47,6 @@ C3_VERSION = _read_version()
 # Tool handlers
 from cli.tools._helpers import maybe_related_facts, validate_file_path
 from cli.tools.agent import handle_agent
-from cli.tools.compress import handle_compress
 from cli.tools.delegate import handle_delegate
 from cli.tools.edit import handle_edit
 from cli.tools.filter import handle_filter
@@ -85,7 +84,7 @@ def _build_instructions(ide_name: str) -> str:
     return (
         "C3 — local code intelligence. Route by goal:\n"
         "  FIND candidates → c3_search\n"
-        "  MAP a file → c3_read(file_path) with no symbols, then READ → c3_read(symbols=…); batch maps → c3_compress\n"
+        "  MAP a file/dir → c3_read(file_path) with no symbols (comma paths batch), then READ → c3_read(symbols=…)\n"
         "  EDIT code → c3_edit (always; it logs to the ledger automatically)\n"
         "  VALIDATE after every edit → c3_validate\n"
         "  BLAST RADIUS before shared-symbol edits → c3_impact\n"
@@ -598,22 +597,10 @@ async def c3_read(file_path: str, symbols: Any = None, lines: Any = None,
     return await asyncio.to_thread(handle_read, file_path, symbols, lines, include_docstrings, svc, finalize)
 
 
-@mcp.tool()
-async def c3_compress(file_path: str, mode: str = "map", ctx: Context = None) -> str:
-    """MAP a file — one line per symbol with full signature and [La-Lb] range, ~10% of the
-    file's tokens (read-only, plan-mode safe). Same map as c3_read(file_path) with no symbols;
-    use this form for a comma-separated batch (up to 10). mode: map (default); other modes
-    are legacy."""
-    path_err = validate_file_path(file_path)
-    if path_err:
-        return f"[c3_compress:error] {path_err}"
-    svc = _svc(ctx)
-
-    def finalize(name, args, resp, summ, **kw):
-        return _finalize_response(ctx, name, args, resp, summ, **kw)
-
-    return await asyncio.to_thread(handle_compress, file_path, mode, svc, finalize, maybe_related_facts)
-
+# c3_compress left the MCP surface in 2.124.0: c3_read(file_path) serves the
+# same map, c3_read('a.py,b.py') the same batch, c3_read('<dir>') a directory.
+# handle_compress stays importable for c3_project, the Oracle bridge and the
+# CLI (docs/file-map.md § Retired modes).
 
 @mcp.tool()
 async def c3_validate(file_path: str, ctx: Context = None) -> str:

cli/tools/compress.py

@@ -102,7 +102,7 @@ def _build_map(svc, rel: str) -> str:
         svc.file_memory.complete_updates(completed)
     if failed:
         svc.file_memory.complete_updates(failed, failed=True)
-    return svc.file_memory.get_or_build_map(rel)
+    return svc.file_memory.get_or_build_map(rel, max_tokens=svc.file_memory.MAP_TOKEN_BUDGET)
 
 
 def _compress_single(file_path: str, requested: str, note: str, svc, finalize) -> str:
@@ -197,7 +197,8 @@ def _compress_batch(paths: list, requested: str, note: str, svc, finalize) -> st
                 return fp, None, None, None, "not found"
             rel = str(full.resolve().relative_to(
                 Path(svc.project_path).resolve())).replace("\\", "/")
-            res = svc.file_memory.get_or_build_map(rel)
+            res = svc.file_memory.get_or_build_map(
+                rel, max_tokens=svc.file_memory.MAP_TOKEN_BUDGET)
             try:
                 raw_tok = count_tokens(full.read_text(encoding="utf-8", errors="replace"))
                 map_tok = count_tokens(res)

cli/tools/read.py

@@ -177,6 +177,22 @@ def handle_read(file_path: str, symbols: Any = None, lines: Any = None,
 
     rel_path = str(full.resolve().relative_to(Path(svc.project_path).resolve())).replace("\\", "/")
 
+    if full.is_dir():
+        # A directory maps to one line per file, budgeted
+        # (docs/file-map.md § Directories). `lines=<int>` sets the budget.
+        from services.dir_map import DEFAULT_MAX_TOKENS, render_directory_map
+        budget = DEFAULT_MAX_TOKENS
+        if isinstance(lines, int) and not isinstance(lines, bool) and lines > 0:
+            budget = lines
+        text, dir_detail = render_directory_map(svc, rel_path, max_tokens=budget)
+        tok = count_tokens(text)
+        if finalize is None:
+            return text
+        return finalize_with_tokens(
+            finalize, svc, "c3_read", {"file": file_path}, text,
+            f"dir:{dir_detail['files']}files->{tok}tok",
+            optimized_tokens=tok, response_tokens=tok, detail=dir_detail)
+
     # Resolve ranges
     ranges = []
 
@@ -315,7 +331,8 @@ def handle_read(file_path: str, symbols: Any = None, lines: Any = None,
 
     if not ranges:
         map_cached = not svc.file_memory.needs_update(rel_path)
-        file_map = svc.file_memory.get_or_build_map(rel_path)
+        file_map = svc.file_memory.get_or_build_map(
+            rel_path, max_tokens=svc.file_memory.MAP_TOKEN_BUDGET)
         if count_tokens(file_map) >= full_file_tokens():
             # A map that costs more than the file is worth nothing: serve the
             # file (docs/file-map.md § Small files).
@@ -325,6 +342,8 @@ def handle_read(file_path: str, symbols: Any = None, lines: Any = None,
                 + "\n[map only — pass lines=[start,end] or symbols=[...] for exact source]"
                 + maybe_related_facts(svc, rel_path, top_k=3, context="read"))
         map_tok = count_tokens(resp)
+        if finalize is None:
+            return resp
         return finalize_with_tokens(
             finalize, svc, "c3_read", {"file": file_path},
             resp, f"{full_file_tokens()}->{map_tok}tok",

{code_context_control-2.122.0.dist-info → code_context_control-2.124.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.122.0
+Version: 2.124.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.122.0.dist-info → code_context_control-2.124.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
 cli/__init__.py,sha256=ec66drCZGNMRU4V6ov0zVhYZph1us12Vn8OvG_LJyRY,22
 cli/_hook_utils.py,sha256=e48F6FQloFReUIMtmWsih2t54j9SROzAaHtMkEuttDs,20489
 cli/_shell_writes.py,sha256=XzUNlUDljmg-wZxK03xHnRe36WeQxe4tpO9HKVFwP5o,5090
-cli/c3.py,sha256=DWhVK-bMa3_Tzz1cXdmjS0197VmE1b4Xb8HCtLa8-tw,416811
+cli/c3.py,sha256=TRLSfHOBi-9AxQUAaXYq46tFgaBd4WMKw0WIBnFijHI,416843
 cli/docs.html,sha256=X9M7qC7LWi8pPJNF-4yEM57jhuZ3WeTESECbdDOeNaA,143172
 cli/edits.html,sha256=UjAhoCmBmQ89cklGvJqzC6eyNP2tc8H6T-e01DVkLvE,43418
 cli/hook_access_guard.py,sha256=ba8-un6G9Ap8HCzx7nyhVq3c_G4sOtiVXRy0BzzX8-Y,23349
@@ -15,7 +15,7 @@ cli/hook_edit_ledger.py,sha256=3ooM6Lv83Ntq_aeyrZdn-0FlZSsE_CrWeuB_V-SEAJk,12105
 cli/hook_edit_unlock.py,sha256=PwPRuCQPARZZRtH6wb2Xm-6ADpfrC-0rXs2uRmHAAmg,6883
 cli/hook_filter.py,sha256=v8ZSznK5StTfYYqae1l4V2bm-e9sy2RFfpbNr5KwE2U,4988
 cli/hook_ghost_files.py,sha256=plbedFgIJ5tXEE_8USUE39RmyODh1UjIUFNRbUo4R8w,10291
-cli/hook_pretool_enforce.py,sha256=heNHckDbieUD0x6sKydusmkxWzliMbyN1SpD4518PQc,31323
+cli/hook_pretool_enforce.py,sha256=k9jEyi7ip7MnsbBK3jE0JEcLEitHMg2iMWnX56XhaBY,31329
 cli/hook_prompt_recall.py,sha256=LHyubu36pf5h3hbLBe0yH-yGhAlwLJdsc7hfa7WB1h4,3471
 cli/hook_read.py,sha256=ZWZldgqGSNz78COhlgETQ7yxdOW5vWIIHUet9gZKhxk,8176
 cli/hook_session_stats.py,sha256=i1k7DM0RoQsHm5R8C8RUWvpEA7lzP-NPD95-fAARlnI,7273
@@ -23,7 +23,7 @@ cli/hook_terse_advisor.py,sha256=W_zaTfX2akgX-ifuUTsLu2H1atM8XmWt6jpPoeU7Pm0,625
 cli/hub_server.py,sha256=4BxvRHCGNc87jOtWankOVjQLYNk-GhWI2OY1harC8ro,184548
 cli/hub_ui.html,sha256=nnGqWhWGCLfNisGUnoAlQFcBr6wPNsq-AEOR7uFtVkE,2942
 cli/mcp_proxy.py,sha256=r-Qhlie7gCtotex8yQUudCyBLRUK-IW6cNIW5RhBW0o,17648
-cli/mcp_server.py,sha256=MC5adrvIoENLBhV3y4OCrgHHySb-EAfqVngx9MZvZOQ,64241
+cli/mcp_server.py,sha256=3oxd0sQisBVnWRVix9TDBPgv_w-9dc-MIClJEd6igws,63714
 cli/progress.py,sha256=qTkNy0howOD3hXraMo4ok3dYTpBW5yG_tenKfF4UDM0,1470
 cli/server.py,sha256=bsHvKGPXsBJi_MDLiw0IAEq8RWKIG56q72c7OKKTLug,173324
 cli/ui.html,sha256=xcdt74nlFEXx-0Bx6-Okw-WSVZPAXL0iukxU0ytI6CA,5694
@@ -36,12 +36,12 @@ cli/guide/access.html,sha256=BelnEc4p7XgcH_ysTlMXL9ZHCD0O4CPLq3h5rvqPIh8,14790
 cli/guide/bitbucket.html,sha256=6zmHIv2-G314_HDqMCQV-ZAIy0-co0gaFs0_k2Q1kYc,35491
 cli/guide/credentials.html,sha256=801vO_cCqG7oHsa73yAGSoBDGZ4mcGsdx6D2uS1dwCQ,58196
 cli/guide/getting-started.html,sha256=VAKnff0tDFGPobVAihHW1-hjUfAkxQrpVJg6yKcWcbg,21653
-cli/guide/index.html,sha256=bn6c4QcekSaDa08gsD8UjkAM-Z6wBY2PI0loIV8zZ1Q,22874
+cli/guide/index.html,sha256=nNM_gAi3e8SGEUV7jIsd8N3kmAP35BepwmjZ2HuJoSA,22869
 cli/guide/masking.html,sha256=Jz8fEwp5XwudUafn0Ymytofpf4PPWRpyxOHMl09dD5o,19203
 cli/guide/oracle.html,sha256=66utgqoOpHXxZBEopnw-Q-tvhoQOD82YckXW2xDTTJ4,25152
 cli/guide/shared.css,sha256=Mmm7W6aYxrkDq2RPOcyXiQFYGR-yB3auwX1uIWi6C74,15967
 cli/guide/tools.html,sha256=KrTwffccJrkxiEhn1TBdyN2qUzOuL_uIUxR0wH39pk0,92693
-cli/guide/workflow.html,sha256=yshn1oL7mScB_FmT99alxxpmuFWdlaQzRuUIk8JT-iE,64581
+cli/guide/workflow.html,sha256=-VyLgULPDsucuN1N8D6Vc6g-VMzUIfLVpVah_pDekfk,64582
 cli/hub_ui/app.js,sha256=Gbk-2DxqUynrVqJbS8pNUEHmcCpjuUhqeDxWUWa6e_A,6984
 cli/hub_ui/state.js,sha256=yQXsN0G1YCvtlv6aoIs0iqY7DNfhQ0ybj7Ig9wbBuY4,7279
 cli/hub_ui/components/add_project.js,sha256=j5m0mX0gePcEYQW_0vodJkw5v8Vn2lQqPAI0miIGdv4,3182
@@ -78,7 +78,7 @@ cli/tools/agent.py,sha256=RmEEh5HhCZLvYu0gSRcwA_NENpd4iIYJW3exBzT8kVs,47983
 cli/tools/artifacts.py,sha256=SjazShDFIzOpAZW7uMv9itBktXnc6pqQKZeaen8GgzI,9379
 cli/tools/bitbucket.py,sha256=cni8Y1EoiNm9jcHEpzi2dgKFIT1-4ct0WOhpTs7ac3k,35812
 cli/tools/ci.py,sha256=fQ03RENywS5gqHjH26Fa4YiraBTvchlPcPSnVYwwKBs,19444
-cli/tools/compress.py,sha256=f8DNJlr49cVibvuOSyChHjytzbB30m7uXW3zWq8mVAU,10819
+cli/tools/compress.py,sha256=YjYl0ariAAtIAyG2O-iSgweQXY2-THnl7JcNL83HXbI,10926
 cli/tools/credentials.py,sha256=R8Errpa41vsq0Z_sb7K-fmJxVovzXDYUyniITLrFC24,19033
 cli/tools/delegate.py,sha256=yA2-ph53Y8XAJMpz7R5LwqXshRRD8bYljgN244RbHWA,62012
 cli/tools/edit.py,sha256=xnRRM2UUybvGvfSzXzIjWmt6_zNaCbkupiK1z-8K4jE,30127
@@ -92,7 +92,7 @@ cli/tools/locks.py,sha256=FvuNxToU-5ZE2m_C6fTrn1jKERoxR4cbtxNb_b8mXqA,5882
 cli/tools/memory.py,sha256=yDDRsEngeFcjb6nXUrhRZXuboasXfixJeyltKhDbZD4,24935
 cli/tools/override.py,sha256=LiZFgoDN-35NXVwldnYrcCzfBl8MhQQ3tKVVkOG5d_o,9217
 cli/tools/project.py,sha256=MWzi7tBTQ03p_6PavmG9ZLXZHO0IhjKEJNyB0oZWTFc,24248
-cli/tools/read.py,sha256=vQP-tfm3Mpx0y2vObPBOUeHsCdANacb_onzYJc0v-m8,17641
+cli/tools/read.py,sha256=yLpJuxQnGRnEvX5lyVeQn2L56tz90dmilIaj1f4KmSk,18532
 cli/tools/search.py,sha256=BZh3E7YggjCWOC1lJz0YNcRsdDLWsJiEmONtgUW2rEo,32397
 cli/tools/session.py,sha256=ailQiRqXhi9NcBB3XS3Dv72GEkEZaYivB0bqDlhmgTA,5202
 cli/tools/shell.py,sha256=Zcsocl8IXeL9DSQNewq_fXECSufTccUdwc-H3S2Alto,58818
@@ -123,7 +123,7 @@ cli/ui/components/sessions.js,sha256=FIKtil76B8tCkAmcFV7hlj6GQ_DCJK2jCzvEmdK7NBE
 cli/ui/components/settings.js,sha256=ATbAjBlVIwCNpxq7s191b49a_INQV38iwmySqtJLYwY,79066
 cli/ui/components/sidebar.js,sha256=K2ym2kUgpbyG-EBA_wBIIiqQY8qTatsiBZwzseMWuIQ,9939
 cli/ui/components/tasks.js,sha256=vyKQ3uwoppMwvdEaHlhWXW4oWcAisx4NveqzMhsYqHo,38438
-code_context_control-2.122.0.dist-info/licenses/LICENSE,sha256=l8Kh5QCNWNvR6kIt8L0BUZvc2LAFiHv2c-FnsGnUZf4,11301
+code_context_control-2.124.0.dist-info/licenses/LICENSE,sha256=l8Kh5QCNWNvR6kIt8L0BUZvc2LAFiHv2c-FnsGnUZf4,11301
 core/__init__.py,sha256=TSDCEcM4V7gcZVM3w2ykJaqEUch4Dkon-rivV17T73s,2501
 core/codex_patch.py,sha256=CxvT_rQIwPNTRJZj9EHJmx0ZdOeSLxjiixuLI3Z7lPc,2107
 core/config.py,sha256=YmkcZwedz_lfDM0ZuI_f4xpe98ixPLcSQFcTCHgRiRg,19206
@@ -200,8 +200,8 @@ services/ci_intel.py,sha256=frr1jL-FXU_JNUoRW8TwnZo04fqUElAGGEsDEvgIeUs,7161
 services/ci_runner.py,sha256=egkFGaOjAa45KIMFbGX7108R2wUQwUuLgJ4Iq7ygx9I,40768
 services/ci_workflow.py,sha256=xfeUvzcm9GHiDdi7QAbg4SAvnzzuCCV3bmwdAMUTZKA,31133
 services/circuit_breaker.py,sha256=ES6PpjL40gfDhtK88GeS6GFzsz5EOEEkZsB-DzX_tbw,3179
-services/claude_md.py,sha256=jXvr0orZOkPYrVxEkf67beAj8EKPbB_M99mmxxMsPg4,61217
-services/codex_integration.py,sha256=dXlaVbQJrIrlZw5hZcDjhZVli3AvumnOTQTkl-_I-rg,7708
+services/claude_md.py,sha256=U9Ogzktmqz1D75L_vEBuadNqddrhUY1v_e3KbPn46EE,61453
+services/codex_integration.py,sha256=px7Mcyl8d3TlJxMyjzhuysuz0caaqWh023UvW2CdVjE,7716
 services/codex_transcript.py,sha256=TtxKiNkZ3vsWpaQRczaIGsA7wd8r24z_65Nnso2BNj0,3658
 services/compressor.py,sha256=TnszNgnikaWR2CgUe4wO8NQ2ayNzhMExY42IVPMV5w4,33222
 services/context_snapshot.py,sha256=2f_bxY3xX4ZC653ncYno8YSeSTFSavwBjrorytHA0Ns,16879
@@ -209,6 +209,7 @@ services/conversation_store.py,sha256=RKA0nk09VAI8Ip935kSVlQdF-cQEzFLrgHbZiEJ7G1
 services/cred_audit.py,sha256=tdxnRzbB0c8nJ7dqA9HOJrcOeRWivEzq6yhwu6ksmZI,10240
 services/cred_telemetry.py,sha256=LwDd4x0Mu6YXeDUrgICHnX9o1Ym_4hoouRp98qx0zlI,10926
 services/credential_store.py,sha256=x8ejkSJAqjlUHwCdJ-AyOrLJwSpMCUmuq61nkBTrm-Y,68797
+services/dir_map.py,sha256=r40hj8PN6lDnKGFjDsslsMQJhbdMkleIksHtYTw4sQA,6666
 services/doc_index.py,sha256=cIb1jk4GrKK7cLwD6phoc04TvKA7Ee94kKHXxB7tT_k,19223
 services/e2e_benchmark.py,sha256=5Z3rE42o08MKVbIX_769V0RX2yAzSVcApCvdAQ9YLAU,134988
 services/e2e_evaluator.py,sha256=FsB4vMzcFUcmicfIwRtA8JZ_XeMpuk2_-86F2iVNEDc,17783
@@ -217,8 +218,8 @@ services/edit_ledger.py,sha256=Tj8Q14o19VHQHpofRHdbZKKcVs17v-ctZ3LOeVTqvdQ,29362
 services/embedding_index.py,sha256=c85kAkekL7r-liiFEwqi7nJAQr4ZbJA36h0oMdiTurc,25156
 services/enforcement_policy.py,sha256=bB-lI7EZwWT5MhoNtkBjjixN4h7zAYUtVBWPMJ6aONo,17196
 services/error_reporting.py,sha256=HZ3ru8i5RLf8nq2R4iRnTs5sm1blUxknSbv5hdxuxs0,4139
-services/file_map.py,sha256=t5Ua4abJDuo-EZSX793MWiXg4uMqNAk1KxZrOffIm48,14500
-services/file_memory.py,sha256=AckiClEKJeVJqCPoCTrqkCMDfHruVWhz2UZn3Df_7bU,33788
+services/file_map.py,sha256=j37DTR-UE_PMNj7vG2HiHucpwpJNaKgiD94UNUU-UXE,17091
+services/file_memory.py,sha256=4n2y6Sci4ThP1ob8dh68bEq80ui5I50iWpQjoIbGI84,38565
 services/git_context.py,sha256=FFdA8Y46op4DYsUnZsXLTqxIjgxb0q_d-hkFTbosC8Q,9518
 services/hub_service.py,sha256=z2MZ2Rg9NLNXxQ17e05XGF_f6qSTDWLYtoC3WpuQfGU,2634
 services/index_store.py,sha256=SWHHKQB_wYww1ubtKgkLo5FFEqaWhPbw0OAN8x3gk9Q,16453
@@ -250,7 +251,7 @@ services/override_grants.py,sha256=BQVwD6WCxVORsUaqDWNToIalz2mStnJRMIR-SOxQzuQ,3
 services/override_policy.py,sha256=VC5H-FETUz4u6f4JM_q5jqT2HIb1MiFzhpdJyuBG72I,22369
 services/override_requests.py,sha256=H9lSUbfOjkjE1muztaQ58InqqsqhtnKIT-pF2VzvWkg,31148
 services/override_wake.py,sha256=HjSOXQTDi0irgeMyrTqngL7xLcSOOIgYsVW9yxod4ps,10363
-services/parser.py,sha256=4pklWjWICIVohRLghylS727idWCWyrUBWks1Xh4526o,62782
+services/parser.py,sha256=S_YoKLS3r1xCUVHApXb3BTEfoRAzFhuo1_8XsG0qxVE,63505
 services/project_manager.py,sha256=uQh-GUvH5cgV5Ce9XYPINlQeqH6NvNdW8zrNFYRbBkw,37855
 services/project_runtime.py,sha256=yyftX48BFjq4B2KcR4KGszDAAa4xR6gn6j0SgTyro1s,11603
 services/protocol.py,sha256=CWZ0BWWd-jPui-11hZlvGgkNk18gMFhhLWbp-BP35Kk,12861
@@ -305,8 +306,8 @@ tui/screens/search_view.py,sha256=MMHjVdlk3HZSuDBSvq8IGrqv_Mh5Us6YqXQ80bcWSMk,19
 tui/screens/session_view.py,sha256=eZ1eDwHTvPOck1wCCviixtOaCxIkBT_95ytNNNriGNA,5991
 tui/screens/stats.py,sha256=p81PjzdaIv7hllb8f45-rlVe4lJZwSdIMqu7e86_u5s,6223
 tui/screens/ui_view.py,sha256=1QJCgLh2YfgWIpvzRG1KOGXYEaOYX6ojN61Azjf2oX0,2125
-code_context_control-2.122.0.dist-info/METADATA,sha256=-kj7pKeDDSrFJ_FyQa-f4EelTWd5cOrlYl4lJWIu4GQ,27067
-code_context_control-2.122.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-code_context_control-2.122.0.dist-info/entry_points.txt,sha256=7kX_WUsDCF2hbXzvbNyscyaBb9AeA-DJY5v_5hN0DlU,93
-code_context_control-2.122.0.dist-info/top_level.txt,sha256=wRt41zBybVF3qAiNXHz9BURbkKvUvfhmWWtKMhaw6eE,29
-code_context_control-2.122.0.dist-info/RECORD,,
+code_context_control-2.124.0.dist-info/METADATA,sha256=aoNZXvOHSJK4ylPra3DMz2K2FMUEkKIKiAYLOUYOWcg,27067
+code_context_control-2.124.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+code_context_control-2.124.0.dist-info/entry_points.txt,sha256=7kX_WUsDCF2hbXzvbNyscyaBb9AeA-DJY5v_5hN0DlU,93
+code_context_control-2.124.0.dist-info/top_level.txt,sha256=wRt41zBybVF3qAiNXHz9BURbkKvUvfhmWWtKMhaw6eE,29
+code_context_control-2.124.0.dist-info/RECORD,,

services/claude_md.py

@@ -32,7 +32,7 @@ When falling back, state which c3_* tool was attempted and why it was insufficie
 ## Workflow (follow this order — do not skip steps)
 1. **RECALL**: `c3_memory(action='recall')` — before any multi-step or context-dependent task. Large memory stores: use `index` first (compact list), then `fetch` for specific IDs
 2. **SEARCH FIRST**: `c3_search(action='code|files|semantic')` — before ANY file discovery or content search. Never start with Grep/Glob
-3. **MAP before READ**: `c3_compress(mode='map')` then `c3_read(symbols=...|lines=...)` — for ANY file read. Never start with native Read. Use `mode='ast'` for knowledge-graph overview (requires codebase-memory-mcp)
+3. **MAP before READ**: `c3_read(file_path)` with no symbols/lines returns the file map (one line per symbol with signature and `[La-Lb]` range, ~10% of the file's tokens; a directory path maps its files), then `c3_read(symbols=['Class.method']|lines=[a,b])` for the source you need. Never start with native Read. `c3_compress` is the same map for a comma-separated batch (legacy; removed in 2.124.0)
 4. **IMPACT** (shared symbols): `c3_impact(target='symbol')` — blast-radius check before editing any function/class used across files
 5. **EDIT via C3**: `c3_edit(file_path, old_string, new_string, summary)` — for ALL edits. Parallel across files; `edits=[]` batch for same file
 6. **FILTER**: `c3_filter(text=...)` — for terminal output >10 lines or log files
@@ -55,7 +55,7 @@ In plan mode, all c3_* read tools (search, read, compress, filter, validate, sta
 ## Anti-patterns (DO NOT do these)
 - Starting with native file search/read/grep without a prior c3_* call
 - Using native Edit when c3_edit is available
-- Reading entire files when c3_compress + c3_read would be more surgical
+- Reading entire files when a c3_read map + a symbol read would be more surgical
 - Skipping c3_validate after making edits"""
 
 # Pointer that replaces the embedded Project Context tree (v2.60.0).
@@ -73,14 +73,14 @@ C3_NANO_WORKFLOW = """\
 ## C3 Tools — MANDATORY
 Native tools BLOCKED unless c3_* called first. State reason when falling back.
 1. c3_search(action='code|files|semantic') — BEFORE any search/grep/glob
-2. c3_compress(mode='map') then c3_read(symbols=...|lines=...) — BEFORE any file read
+2. c3_read(file_path) maps a file (or directory); then c3_read(symbols=['Class.method']|lines=[a,b]) — BEFORE any file read
 3. c3_edit(file_path, old_string, new_string, summary) — for ALL edits; edits=[{...}] batch
 4. c3_filter(text='...') — output >10 lines
 5. c3_validate(file_path) — after edits
 6. c3_session(action='log'|'snapshot') — decisions / before /clear
 7. `[c3-access:confirm]` = PAUSE, not block: a human approves this exact write (agent-config files — .mcp.json, instruction docs, .claude bodies — hold by default). Read the S8 tail: wait on the request it names (c3_override(action='wait', request_id='...', timeout_s=180)), then retry once. Never retry early, never route around it.
 Plan mode: all c3_* read tools work normally — skip edit/delegate steps.
-DO NOT: start with native Read/Grep/Glob/Edit, skip c3_validate, read full files without c3_compress."""
+DO NOT: start with native Read/Grep/Glob/Edit, skip c3_validate, read full files without mapping them first."""
 
 
 # --- Per-IDE workflow adaptation ----------------------------------------------

services/codex_integration.py

@@ -8,7 +8,7 @@ CODEX_WORKFLOW = """# C3 — Codex workflow
 
 Use C3 for repository intelligence and audited changes:
 1. Recall relevant project facts with c3_memory; inspect .c3/MAP.md.
-2. Find candidates with c3_search; map with c3_compress(mode='map'), then
+2. Find candidates with c3_search; map with c3_read(file_path) (no symbols), then
    read exact symbols or lines with c3_read. Check shared changes with c3_impact.
 3. Edit with c3_edit, validate with c3_validate, and record decisions with
    c3_session(action='log'). Preserve unrelated work.

services/dir_map.py

@@ -0,0 +1,176 @@
+"""Directory maps — one line per file, budgeted, for `c3_read('<dir>')`.
+
+    # services/ (58 files, 41,203L)
+    compressor.py (809L python) — CodeCompressor; compress_file; STRUCTURE_PATTERNS
+    file_map.py (280L python) — render_map; parse_signature; parse_map; KINDS
+    …
+    … 12 more files
+
+Files are ranked the way a reader would want them: recently edited first
+(the edit ledger), then by how much structure they hold (symbol count),
+then by path. The map is filled to a token budget and closes with how
+many files it left out. Traversal is bounded — the scanner's SKIP_DIRS
+and .gitignore pruning, never following symlinks, a hard file cap — and
+structure comes from file_memory records, extracting on the fly only
+for a bounded number of code files (docs/file-map.md § Directories).
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Optional
+
+from core import count_tokens
+from services.file_memory import CODE_EXTENSIONS, LANG_MAP
+from services.scanner import iter_files
+
+DEFAULT_MAX_TOKENS = 1500
+MAX_FILES = 400            # hard traversal cap
+MAX_EXTRACT_FILES = 120    # code files parsed on the fly, per call
+EXTRACT_DEADLINE_S = 3.0   # then the rest show line counts only
+MAX_EXTRACT_BYTES = 200 * 1024
+SYMBOLS_PER_FILE = 6
+LEDGER_LOOKBACK = 300      # recent ledger entries consulted for ranking
+
+
+def _recent_edit_ranks(svc) -> dict:
+    """path -> recency rank (0 = most recent) from the edit ledger."""
+    ledger = getattr(svc, "edit_ledger", None)
+    if ledger is None:
+        return {}
+    try:
+        entries = ledger.get_history(limit=LEDGER_LOOKBACK)
+    except Exception:
+        return {}
+    ranks: dict = {}
+    for entry in entries or []:
+        f = str((entry or {}).get("file") or "").replace("\\", "/")
+        if f and f not in ranks:
+            ranks[f] = len(ranks)
+    return ranks
+
+
+#: What a reader wants to see first on a one-line summary of a file.
+_SYMBOL_PRIORITY = {"class": 0, "interface": 0, "struct": 0, "trait": 0, "enum": 0,
+                    "function": 1, "method": 1, "type": 2, "heading": 2, "section": 2,
+                    "constant": 3, "variable": 3}
+_SKIP_SYMBOL_TYPES = {"import", "decorator", "comment", "content", "property", "impl"}
+
+
+def _structural_sections(record: Optional[dict]) -> list:
+    return [s for s in (record or {}).get("sections") or []
+            if s.get("type") not in _SKIP_SYMBOL_TYPES
+            and str(s.get("name") or "").strip() not in ("", "(full file)")]
+
+
+def _top_symbols(record: Optional[dict]) -> list:
+    """Up to SYMBOLS_PER_FILE names: classes first, then functions, then the
+    rest, constants last — each group in source order."""
+    picked = sorted(enumerate(_structural_sections(record)),
+                    key=lambda iv: (_SYMBOL_PRIORITY.get(iv[1].get("type"), 2),
+                                    str(iv[1].get("name") or "").startswith("_"),
+                                    iv[0]))
+    names = []
+    for _, s in picked[:SYMBOLS_PER_FILE]:
+        name = str(s.get("name") or "").strip()
+        if s.get("type") == "heading":
+            name = name.split(":", 1)[-1].strip()
+        names.append(name)
+    return names
+
+
+def _line_count(path: Path) -> int:
+    try:
+        with open(path, "rb") as fh:
+            return sum(1 for _ in fh)
+    except OSError:
+        return 0
+
+
+def render_directory_map(svc, rel_dir: str, *, max_tokens: int = DEFAULT_MAX_TOKENS) -> tuple:
+    """Return (text, detail) for the directory `rel_dir` (project-relative, posix)."""
+    root = Path(svc.project_path).resolve()
+    rel_dir = str(rel_dir).replace("\\", "/").strip("/")
+    target = (root / rel_dir).resolve() if rel_dir else root
+    label = (rel_dir + "/") if rel_dir else "./"
+
+    files = []
+    capped = False
+    for fp in iter_files(target, max_files=MAX_FILES + 1):
+        if len(files) >= MAX_FILES:
+            capped = True
+            break
+        try:
+            files.append(fp.resolve().relative_to(root).as_posix())
+        except ValueError:
+            continue
+
+    store = getattr(svc, "file_memory", None)
+    recent = _recent_edit_ranks(svc)
+    started = time.monotonic()
+    extracted = 0
+    rows = []
+    total_lines = 0
+    for rel in files:
+        record = None
+        if store is not None:
+            try:
+                record = store.get(rel)
+            except Exception:
+                record = None
+            ext = Path(rel).suffix.lower()
+            if (record is None and ext in CODE_EXTENSIONS
+                    and extracted < MAX_EXTRACT_FILES
+                    and time.monotonic() - started < EXTRACT_DEADLINE_S):
+                try:
+                    if (root / rel).stat().st_size <= MAX_EXTRACT_BYTES:
+                        record = store.update(rel)
+                        extracted += 1
+                except Exception:
+                    record = None
+        lines = int((record or {}).get("lines") or 0) or _line_count(root / rel)
+        total_lines += lines
+        ext = Path(rel).suffix.lower()
+        lang = str((record or {}).get("language") or LANG_MAP.get(ext) or ext.lstrip(".") or "")
+        symbols = _top_symbols(record)
+        rows.append({
+            "rel": rel,
+            "name": rel[len(rel_dir) + 1:] if rel_dir and rel.startswith(rel_dir + "/") else rel,
+            "lines": lines,
+            "lang": lang,
+            "symbols": symbols,
+            "recent": recent.get(rel, 10 ** 6),
+            "nsym": len(_structural_sections(record)),
+        })
+
+    rows.sort(key=lambda r: (r["recent"], -r["nsym"], r["rel"]))
+
+    header = f"# {label} ({len(files)}{'+' if capped else ''} files, {total_lines:,}L)"
+    body = []
+    for r in rows:
+        line = f"{r['name']} ({r['lines']}L {r['lang']})".rstrip()
+        if r["symbols"]:
+            line += " — " + "; ".join(r["symbols"])
+        body.append(line)
+
+    kept = list(body)
+    while kept and count_tokens("\n".join([header] + kept)) > max_tokens:
+        kept.pop()
+    dropped = len(body) - len(kept)
+    parts = [header] + kept
+    if dropped:
+        parts.append(f"… {dropped} more files")
+    if capped:
+        parts.append(f"[dir_map] traversal capped at {MAX_FILES} files; map a subdirectory")
+    # In source order the reader gets recency first; say so once.
+    parts.append("[dir_map] recently edited first, then by structure; "
+                 "c3_read('<file>') maps one file")
+    text = "\n".join(parts)
+    detail = {
+        "backend": "directory",
+        "files": len(files),
+        "listed": len(kept),
+        "extracted": extracted,
+        "capped": capped,
+    }
+    return text, detail

services/file_map.py

@@ -56,7 +56,7 @@ _PY_DEF = re.compile(r"^(?:async\s+)?def\s+[\w.]+\s*\((?P<params>.*)\)\s*(?:->\s
 _PY_CLASS = re.compile(r"^class\s+\w+\s*(?:\((?P<bases>.*)\))?\s*:?$")
 _GO_FUNC = re.compile(r"^func\s+(?:\((?P<recv>[^)]*)\)\s*)?\w+\s*\((?P<params>.*?)\)\s*(?P<ret>[^{]*?)\s*\{?$")
 _RS_FN = re.compile(r"^(?:pub(?:\([^)]*\))?\s+)?(?:async\s+|const\s+|unsafe\s+)*fn\s+\w+(?:<[^>]*>)?\s*\((?P<params>.*)\)\s*(?:->\s*(?P<ret>[^{]+?))?\s*(?:where\b.*)?\{?$")
-_JS_FUNC = re.compile(r"^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*\w*\s*(?:<[^>]*>)?\s*\((?P<params>.*)\)\s*(?::\s*(?P<ret>[^{]+?))?\s*\{?$")
+_JS_FUNC = re.compile(r"^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*[\w$]*\s*(?:<[^>]*>)?\s*\((?P<params>.*)\)\s*(?::\s*(?P<ret>[^{]+?))?\s*\{?\s*$")
 _JS_ARROW = re.compile(r"^(?:export\s+)?(?:const|let|var)\s+\w+\s*(?::[^=]+)?=\s*(?:async\s+)?\((?P<params>.*)\)\s*(?::\s*(?P<ret>[^=]+?))?\s*=>")
 _JS_ARROW1 = re.compile(r"^(?:export\s+)?(?:const|let|var)\s+\w+\s*=\s*(?:async\s+)?(?P<params>\w+)\s*=>")
 _JS_CLASS = re.compile(r"^(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+\w+(?:<[^>]*>)?\s*(?:extends\s+(?P<base>[\w.<>, ]+?))?\s*(?:implements\s+(?P<impl>[\w.<>, ]+?))?\s*\{?$")
@@ -67,6 +67,40 @@ def _norm(text: str) -> str:
     return _WS.sub(" ", str(text or "")).strip()
 
 
+def _declaration_head(sig: str) -> str:
+    """Cut a brace-language signature after its parameter list and return
+    type: the text up to the body's `{`, an arrow, or a `;`. Parentheses
+    are depth-matched, so a 400-char minified chunk holding several
+    declarations yields only the first one's head."""
+    i = sig.find("(")
+    if i < 0:
+        j = sig.find("{")
+        return sig if j < 0 else sig[:j].rstrip()
+    depth = 0
+    close = -1
+    for k in range(i, len(sig)):
+        ch = sig[k]
+        if ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+            if depth == 0:
+                close = k
+                break
+    if close < 0:
+        return sig
+    rest = sig[close + 1:]
+    cut = len(rest)
+    for stop in ("{", ";"):
+        j = rest.find(stop)
+        if 0 <= j < cut:
+            cut = j
+    j = rest.find("=>")
+    if 0 <= j < cut:
+        cut = j + 2   # keep the arrow: the arrow-function grammar needs it
+    return (sig[:close + 1] + rest[:cut]).rstrip()
+
+
 def parse_signature(signature: str, language: str) -> dict:
     """Split a raw signature into params / ret / receiver / bases.
 
@@ -78,6 +112,10 @@ def parse_signature(signature: str, language: str) -> dict:
     if not sig:
         return {}
     lang = (language or "").lower()
+    if lang in ("javascript", "typescript", "go", "rust") and not sig.lstrip().startswith(
+            ("class ", "export class", "export default class", "abstract class",
+             "struct ", "pub struct", "enum ", "pub enum", "trait ", "pub trait", "impl ", "type ")):
+        sig = _declaration_head(sig)
     out: dict = {}
     if lang == "python":
         m = _PY_DEF.match(sig)
@@ -290,6 +328,25 @@ def render_map(record: dict, *, include_docs: bool = False,
     header = f"# {path} ({total_lines}L {language})".rstrip()
     body: list = []
 
+    shape = record.get("shape") or {}
+    parser = str(record.get("parser") or "")
+    minified = bool(shape.get("minified"))
+    if parser == "skipped" or shape.get("oversized"):
+        body.append(f"[map:not mapped] {shape.get('bytes', 0):,} bytes on {total_lines} lines, "
+                    f"longest line {shape.get('longest_line', 0):,} chars — read with lines=[a,b]")
+        return "\n".join([header] + body)
+    if parser == "lexical":
+        body.append("[map:lexical-fallback] the parse overran its deadline; "
+                    "symbols come from a line scan and may be incomplete")
+    if minified:
+        # A minified bundle's `var` soup is not structure; named declarations are.
+        soup = [s for s in sections if s.get("type") in ("variable", "constant")]
+        sections = [s for s in sections if s.get("type") not in ("variable", "constant")]
+        body.append(f"[map:minified] longest line {shape.get('longest_line', 0):,} chars; "
+                    f"{len(soup)} var bindings omitted")
+    elif shape.get("generated"):
+        body.append("[map:generated] the file says it is generated")
+
     imports = [s for s in sections if s.get("type") == "import"]
     others = [s for s in sections if s.get("type") != "import"]
     if imports:
@@ -329,7 +386,9 @@ def render_map(record: dict, *, include_docs: bool = False,
         while kept and count_tokens("\n".join([header] + kept)) > max_tokens:
             kept.pop()
         dropped = len(body) - len(kept)
-        text = "\n".join([header] + kept + [f"… {dropped} more symbols"])
+        text = "\n".join([header] + kept + [
+            f"… {dropped} more symbols (map budget {max_tokens} tokens; "
+            f"pass symbols=[…] or lines=[a,b] for the part you need)"])
     return text
 
 

services/file_memory.py

@@ -195,6 +195,10 @@ class FileMemoryStore:
             "parser": parser,
             "sections": sections,
         }
+        shape = getattr(self, "_last_shape", None) or {}
+        if shape.get("minified") or shape.get("generated") or shape.get("oversized"):
+            record["shape"] = {k: shape[k] for k in ("minified", "generated", "oversized",
+                                                      "longest_line", "bytes") if k in shape}
 
         self._save(rel_path, record)
         self._cache_map(rel_path, record)
@@ -213,17 +217,31 @@ class FileMemoryStore:
             return None
         return self._cache_map(rel_path, record)
 
-    def get_or_build_map(self, rel_path: str) -> str:
-        """Get map if cached, otherwise build it on-demand."""
+    #: Default token budget for a map served to the model (C4, 2.124.0). A
+    #: 250 KB generated module renders 117k tokens unbounded; the MCP
+    #: response cap is 25k. Over budget the map keeps its first lines and
+    #: says how many symbols it left out.
+    MAP_TOKEN_BUDGET = 6000
+
+    def get_or_build_map(self, rel_path: str, max_tokens: Optional[int] = None) -> str:
+        """Get map if cached, otherwise build it on-demand.
+
+        `max_tokens` renders a budgeted map (never cached); None serves the
+        cached full map.
+        """
         record = self.get(rel_path)
 
         # Check staleness
         if record and not self.needs_update(rel_path):
+            if max_tokens:
+                return render_map(record, max_tokens=max_tokens)
             return self._cache_map(rel_path, record)
 
         # Build fresh
         updated = self.update(rel_path)
         if updated:
+            if max_tokens:
+                return render_map(updated, max_tokens=max_tokens)
             return self._cache_map(rel_path, updated)
 
         return f"[file_map] Could not build map for {rel_path} — file not found or unreadable."
@@ -556,6 +574,39 @@ class FileMemoryStore:
     PARSER_TREE_SITTER = "tree_sitter"
     PARSER_REGEX = "regex"
     PARSER_GENERIC = "generic"
+    PARSER_LEXICAL = "lexical"       # deadline or parse failure -> regex scan
+    PARSER_SKIPPED = "skipped"       # minified / oversized: not parsed
+
+    #: Bounds for large files (C4, 2.124.0). A parse that overruns the
+    #: deadline is abandoned for the regex scan; a minified or oversized
+    #: file is not parsed at all.
+    PARSE_DEADLINE_S = 1.5
+    MAX_PARSE_BYTES = 2 * 1024 * 1024
+    MINIFIED_LINE_CHARS = 2000
+    MINIFIED_AVG_LINE_CHARS = 400
+    GENERATED_MARKERS = ("do not edit", "autogenerated", "auto-generated",
+                         "@generated", "generated by", "generated file")
+
+    @classmethod
+    def classify_large(cls, content: str) -> dict:
+        """Cheap shape facts before any parse: {minified, generated, longest_line, oversized}."""
+        size = len(content)
+        longest = 0
+        n_lines = 0
+        for line in content.split("\n"):
+            n_lines += 1
+            if len(line) > longest:
+                longest = len(line)
+        avg = size / max(1, n_lines)
+        head = "\n".join(content.split("\n", 6)[:6]).lower()
+        return {
+            "bytes": size,
+            "lines": n_lines,
+            "longest_line": longest,
+            "minified": longest >= cls.MINIFIED_LINE_CHARS and avg >= cls.MINIFIED_AVG_LINE_CHARS,
+            "generated": any(m in head for m in cls.GENERATED_MARKERS),
+            "oversized": size >= cls.MAX_PARSE_BYTES,
+        }
 
     def _extract_sections(self, filepath: Path, content: str) -> list:
         """Extract structural sections with line ranges from source code."""
@@ -570,18 +621,56 @@ class FileMemoryStore:
         older single-value call keeps working.
         """
         ext = filepath.suffix.lower()
-
-        # Try AST parser first
-        ast_sections = extract_sections_ast(content, ext)
-        if ast_sections is not None:
-            return ast_sections, self.PARSER_TREE_SITTER
+        shape = self.classify_large(content)
+        self._last_shape = shape
+        if shape["oversized"]:
+            # Not worth a parse: the map says so and stops (docs/file-map.md
+            # § Large files). Minified files ARE parsed — bounded signature
+            # capture made that cheap — and the renderer drops their
+            # binding soup.
+            return [{"type": "content", "name": "(not mapped)",
+                     "line_start": 1, "line_end": max(1, shape["lines"]),
+                     "note": "oversized"}], self.PARSER_SKIPPED
 
         lines = content.splitlines()
         patterns = STRUCTURE_PATTERNS.get(ext, {})
 
+        # Try AST parser first, under a deadline. tree-sitter 0.26 has no
+        # parse timeout, so the parse runs on a worker and is abandoned
+        # (not killed) when it overruns; the regex scan answers instead.
+        ast_sections, overran = self._extract_ast_with_deadline(content, ext)
+        if ast_sections is not None:
+            return ast_sections, self.PARSER_TREE_SITTER
+        if overran and patterns:
+            secs, _ = self._extract_regex_sections(lines, ext, patterns)
+            return secs, self.PARSER_LEXICAL
+
         if not patterns:
             return self._extract_generic_sections(lines), self.PARSER_GENERIC
 
+        secs, _ = self._extract_regex_sections(lines, ext, patterns)
+        return secs, self.PARSER_REGEX
+
+    def _extract_ast_with_deadline(self, content: str, ext: str):
+        """(sections | None, overran). Runs extract_sections_ast on a worker
+        thread bounded by PARSE_DEADLINE_S; the thread is daemonic so an
+        abandoned parse cannot hold the process open."""
+        import concurrent.futures as _cf
+        pool = _cf.ThreadPoolExecutor(max_workers=1, thread_name_prefix="c3-parse")
+        try:
+            fut = pool.submit(extract_sections_ast, content, ext)
+            try:
+                return fut.result(timeout=self.PARSE_DEADLINE_S), False
+            except _cf.TimeoutError:
+                self._record_diag("parse_deadline", ext, f"{len(content)} bytes")
+                return None, True
+            except Exception:
+                return None, True
+        finally:
+            pool.shutdown(wait=False)
+
+    def _extract_regex_sections(self, lines: list, ext: str, patterns: dict) -> tuple:
+        """The regex/indentation extractor (the pre-tree-sitter path)."""
         sections = []
         i = 0
         current_class = None  # Track current class for method nesting
@@ -674,6 +763,14 @@ class FileMemoryStore:
 
         base_indent = len(lines[start]) - len(lines[start].lstrip())
 
+        def _last_code_line(upto: int) -> int:
+            # 1-indexed line number of the last non-blank line before `upto`
+            # (0-indexed exclusive): blank lines belong to nobody.
+            j = upto
+            while j > start + 1 and not lines[j - 1].strip():
+                j -= 1
+            return j
+
         for i in range(start + 1, len(lines)):
             line = lines[i]
             stripped = line.strip()
@@ -681,11 +778,11 @@ class FileMemoryStore:
                 continue
             current_indent = len(line) - len(line.lstrip())
             if current_indent <= base_indent:
-                return i  # 1-indexed
+                return _last_code_line(i)  # 1-indexed
             # Check for decorators at same level (next function)
             if current_indent == base_indent and stripped.startswith('@'):
-                return i
-        return len(lines)
+                return _last_code_line(i)
+        return _last_code_line(len(lines))
 
     def _find_brace_block_end(self, lines: list, start: int) -> int:
         """Find end of a brace-delimited block.

services/parser.py

@@ -57,6 +57,28 @@ PARSER_VERSION = "4"  # 4: records carry parser attribution, no summary, posix p
 
 _WS_RUN = re.compile(r"\s+")
 
+#: A signature is never longer than this. A 680 KB minified line used to be
+#: copied into every one of its 20,000 symbols (176 s, an 11 MB record).
+SIGNATURE_MAX_CHARS = 400
+
+
+def _sig_line(lines: List[str], node) -> str:
+    """The node's first line from its start column, capped at SIGNATURE_MAX_CHARS."""
+    row, col = node.start_point
+    line = lines[row] if row < len(lines) else ""
+    chunk = line[col:col + SIGNATURE_MAX_CHARS] if len(line) - col > SIGNATURE_MAX_CHARS else line[col:]
+    if not chunk.strip():
+        chunk = line[:SIGNATURE_MAX_CHARS]
+    return chunk.strip()
+
+
+def _sig_span(lines: List[str], start_row: int, end_row: int) -> str:
+    """Lines start_row..end_row joined, capped at SIGNATURE_MAX_CHARS."""
+    text = "\n".join(lines[start_row:end_row + 1]).strip()
+    if len(text) > SIGNATURE_MAX_CHARS:
+        text = text[:SIGNATURE_MAX_CHARS].rstrip() + "…"
+    return text
+
 
 def _node_text(node, lines: List[str]) -> str:
     """The source text of a node, joined across lines, whitespace-normalized."""
@@ -157,7 +179,7 @@ def _walk_python(node, lines: List[str], sections: List[Dict[str, Any]], parent_
             # Find the colon
             colon_node = next((c for c in child.children if c.type == ':'), None)
             sig_end = colon_node.end_point[0] if colon_node else sig_start
-            signature = '\n'.join(lines[sig_start:sig_end+1]).strip()
+            signature = _sig_span(lines, sig_start, sig_end)
 
             section = {
                 "type": "class",
@@ -186,7 +208,7 @@ def _walk_python(node, lines: List[str], sections: List[Dict[str, Any]], parent_
             sig_start = child.start_point[0]
             colon_node = next((c for c in child.children if c.type == ':'), None)
             sig_end = colon_node.end_point[0] if colon_node else sig_start
-            signature = '\n'.join(lines[sig_start:sig_end+1]).strip()
+            signature = _sig_span(lines, sig_start, sig_end)
 
             is_async = any(c.type == 'async' for c in child.children)
 
@@ -232,7 +254,7 @@ def _walk_python(node, lines: List[str], sections: List[Dict[str, Any]], parent_
                                 "name": name,
                                 "line_start": child.start_point[0] + 1,
                                 "line_end": child.end_point[0] + 1,
-                                "signature": lines[child.start_point[0]].strip()
+                                "signature": _sig_line(lines, child)
                             })
 
         elif child.type == 'comment':
@@ -249,10 +271,10 @@ def _walk_python(node, lines: List[str], sections: List[Dict[str, Any]], parent_
         elif child.type in ('import_statement', 'import_from_statement'):
             section = {
                 "type": "import",
-                "name": lines[child.start_point[0]].strip(),
+                "name": _sig_line(lines, child),
                 "line_start": child.start_point[0] + 1,
                 "line_end": child.end_point[0] + 1,
-                "signature": lines[child.start_point[0]].strip()
+                "signature": _sig_line(lines, child)
             }
             if not parent_section:
                 sections.append(section)
@@ -294,7 +316,7 @@ def _walk_js_ts(node, lines: List[str], sections: List[Dict[str, Any]], parent_s
             name = lines[name_node.start_point[0]][name_node.start_point[1]:name_node.end_point[1]] if name_node else 'Unknown'
 
             # Simple signature heuristic: first line
-            signature = lines[child.start_point[0]].strip()
+            signature = _sig_line(lines, child)
 
             t = child.type.split('_')[0]
             section = {
@@ -321,7 +343,7 @@ def _walk_js_ts(node, lines: List[str], sections: List[Dict[str, Any]], parent_s
             name_node = next((c for c in child.children if c.type in ('property_identifier', 'identifier', 'private_property_identifier')), None)
             name = lines[name_node.start_point[0]][name_node.start_point[1]:name_node.end_point[1]] if name_node else 'Unknown'
 
-            signature = lines[child.start_point[0]].strip()
+            signature = _sig_line(lines, child)
 
             is_async = any(c.type == 'async' for c in child.children)
 
@@ -373,7 +395,7 @@ def _walk_js_ts(node, lines: List[str], sections: List[Dict[str, Any]], parent_s
                         "name": name,
                         "line_start": child.start_point[0] + 1,
                         "line_end": child.end_point[0] + 1,
-                        "signature": lines[child.start_point[0]].strip()
+                        "signature": _sig_line(lines, child)
                     }
                     if is_async: section["async"] = True
                     doc = _extract_docstring_js(child, lines)
@@ -391,7 +413,7 @@ def _walk_js_ts(node, lines: List[str], sections: List[Dict[str, Any]], parent_s
                         "name": name,
                         "line_start": child.start_point[0] + 1,
                         "line_end": child.end_point[0] + 1,
-                        "signature": lines[child.start_point[0]].strip()
+                        "signature": _sig_line(lines, child)
                     })
 
         elif child.type == 'comment':
@@ -408,10 +430,10 @@ def _walk_js_ts(node, lines: List[str], sections: List[Dict[str, Any]], parent_s
         elif child.type == 'import_statement':
             section = {
                 "type": "import",
-                "name": lines[child.start_point[0]].strip(),
+                "name": _sig_line(lines, child),
                 "line_start": child.start_point[0] + 1,
                 "line_end": child.end_point[0] + 1,
-                "signature": lines[child.start_point[0]].strip()
+                "signature": _sig_line(lines, child)
             }
             if not parent_section:
                 sections.append(section)
@@ -446,7 +468,7 @@ def _walk_html(node, lines: List[str], sections: List[Dict[str, Any]]):
                         "name": f"{tag_name}: {text_content.strip()[:60]}",
                         "line_start": child.start_point[0] + 1,
                         "line_end": child.end_point[0] + 1,
-                        "signature": lines[child.start_point[0]].strip()
+                        "signature": _sig_line(lines, child)
                     })
 
                 # Check for ID attribute
@@ -474,7 +496,7 @@ def _walk_html(node, lines: List[str], sections: List[Dict[str, Any]]):
                             "tag": tag_name,
                             "line_start": child.start_point[0] + 1,
                             "line_end": child.end_point[0] + 1,
-                            "signature": lines[child.start_point[0]].strip()
+                            "signature": _sig_line(lines, child)
                         })
 
             # Recurse into element children
@@ -504,7 +526,7 @@ def _walk_markdown(node, lines: List[str], sections: List[Dict[str, Any]]):
                 "name": f"{level}: {content_text.strip()[:60]}",
                 "line_start": child.start_point[0] + 1,
                 "line_end": child.end_point[0] + 1,
-                "signature": lines[child.start_point[0]].strip()
+                "signature": _sig_line(lines, child)
             })
 
         # Recurse if needed (atx headings are top level usually, but just in case)
@@ -582,7 +604,7 @@ def _walk_go(node, lines: List[str], sections: List[Dict[str, Any]]):
             name_node = next((c for c in child.children if c.type == 'identifier' or c.type == 'field_identifier'), None)
             name = lines[name_node.start_point[0]][name_node.start_point[1]:name_node.end_point[1]] if name_node else 'Unknown'
 
-            signature = lines[child.start_point[0]].strip()
+            signature = _sig_line(lines, child)
 
             receiver = ""
             if child.type == 'method_declaration':
@@ -609,7 +631,7 @@ def _walk_go(node, lines: List[str], sections: List[Dict[str, Any]]):
                             "name": _node_text(ident, lines),
                             "line_start": spec.start_point[0] + 1,
                             "line_end": spec.end_point[0] + 1,
-                            "signature": lines[spec.start_point[0]].strip()
+                            "signature": _sig_line(lines, spec)
                         })
         elif child.type == 'type_declaration':
             # Drill into type specs
@@ -625,7 +647,7 @@ def _walk_go(node, lines: List[str], sections: List[Dict[str, Any]]):
                         "name": name,
                         "line_start": child.start_point[0] + 1,
                         "line_end": child.end_point[0] + 1,
-                        "signature": lines[child.start_point[0]].strip()
+                        "signature": _sig_line(lines, child)
                     })
         _walk_go(child, lines, sections)
 
@@ -656,9 +678,9 @@ def _walk_rust(node, lines: List[str], sections: List[Dict[str, Any]]):
                     sig.append(ln)
                     if '{' in ln or ln.rstrip().endswith(';'):
                         break
-                signature = " ".join(x.strip() for x in sig)
+                signature = " ".join(x.strip() for x in sig)[:SIGNATURE_MAX_CHARS]
             else:
-                signature = lines[child.start_point[0]].strip()
+                signature = _sig_line(lines, child)
             sections.append({
                 "type": stype,
                 "name": name,