wip

.claude/plans/folder_size.md

@@ -0,0 +1,27 @@
+# FolderSize follow-ups
+
+`El.Credo.FolderSize` enforces 3 ≤ .ex files per folder ≤ 13.
+
+## Config
+
+`.credo.exs`:
+
+```elixir
+{El.Credo.FolderSize, [exempt: ["lib"], exempt_names: ["behaviours"]]}
+```
+
+- `exempt: ["lib"]` — package root (`lib/el.ex` only).
+- `exempt_names: ["behaviours"]` — any folder with `behaviours` as a path segment. Behaviours dirs mirror their impl folder; refactor the impl, the behaviours follow.
+
+## Outstanding LEAVE-AS-FINDING folders
+
+These are real namespaces flagged by the check. Don't exempt — revisit when scope changes.
+
+| Folder | Files now | Note |
+|---|---|---|
+| `lib/el/cli/daemon` | 2 (connection.ex, env.ex; sibling `behaviours/`) | Real namespace, grows with daemon work. |
+| `lib/el/platform` | 2 (code.ex, parser.ex; sibling `behaviours/`) | Same shape as cli/daemon. |
+| `lib/el/session/claude` | 2 (driver.ex, opts.ex) | Cohesive but thin. Revisit when claude/ grows or shrinks. |
+| `lib/el/session/commands` | 2 (ask.ex, tell.ex) | Command-pattern namespace, grows with commands. |
+
+Re-evaluate when any of these folders gain/lose a file.

.claude/plans/help.md

@@ -0,0 +1,21 @@
+# Help Plan
+
+Gap list between `features/help.feature` and current implementation.
+
+## Not Implemented
+
+- `Output.usage_message` layout doesn't match the grouped sectioned block in `features/help.feature` (info/log with `[-json]`, `start [args]` with sub-args, `cmds:` group). Tracked as H7.
+- README + `~/.claude/skills/el/` docs don't mention `-json`. Tracked as H8.
+
+## Already Working
+
+- `el -v`, `el ls`, `el exit`, `el clear`
+- `el <name> start [-m model] [-a agent]` — explicit `start` keyword wired (H9)
+- `el <name> <msg>`
+- `el <name>` → info (alive ? info : usage)
+- `el <name> [-json]` → JSON info (alive: full shape; dead: `{name, alive: false}`)
+- `el <name> log [n|all]`, `el <name> log all`
+- `el <name> log [n|all] [-json]` → JSON array of `{type, message, response, metadata}` (dead session → `[]`; H6/H11 pin)
+- `el <name|glob> clear`, `el <name|glob> exit`, `el <name|glob> restart`, `el <name|glob> log [n|all]`
+- `el restart` → daemon restart (kills daemon BEAM + all `claude` subprocesses; `Restorer.restore_sessions` rehydrates every session from DETS on boot — strict superset of "restart all sessions")
+- Plain `el <name> log` gated on `alive?` — dead session prints "No sessions running" instead of crashing (H10)

.claude/settings.json

@@ -1,7 +1,28 @@
 {
   "model": "opus",
   "permissions": {
-    "allow": ["Write", "Bash", "Bash(bundle exec cucumber*)"],
-    "deny": []
+    "deny": ["Bash(* cucumber *)", "Bash(git push *)"]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '[.tool_input.file_path // \"\", .tool_input.new_string // \"\", .tool_input.content // \"\"] | @tsv' | awk -F'\t' '$1 ~ /\\.claude\\/settings(\\.local)?\\.json$/ && ($2 ~ /allow/ || $3 ~ /allow/) {print; exit}' | grep -q . && printf '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Blocked: Claude is not allowed to add allow permissions to .claude/settings.json\"}}' || true"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cmd=$(jq -r '.tool_input.command // \"\"'); echo \"$cmd\" | grep -q '\\.claude/settings.*\\.json' && echo \"$cmd\" | grep -q 'allow' && printf '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Blocked: Claude is not allowed to modify allow permissions in .claude/settings.json\"}}' || true"
+          }
+        ]
+      }
+    ]
   }
 }

.credo.exs

@@ -21,18 +21,8 @@
         # You can give explicit globs or simply directories.
         # In the latter case `**/*.{ex,exs}` will be used.
         #
-        included: [
-          "lib/",
-          "specs/",
-          "src/",
-          "test/",
-          "web/",
-          "apps/*/lib/",
-          "apps/*/src/",
-          "apps/*/test/",
-          "apps/*/web/"
-        ],
-        excluded: [~r"/_build/", ~r"/deps/", ~r"/node_modules/", ~r"specs/"]
+        included: ["lib/"],
+        excluded: [~r"/_build/", ~r"/deps/", ~r"/node_modules/"]
       },
       #
       # Load and configure plugins here:
@@ -42,7 +32,7 @@
       # If you create your own checks, you must specify the source files for
       # them here, so they can be loaded by Credo before running the analysis.
       #
-      requires: ["credo_checks/line_check.ex", "credo_checks/max_function_lines.ex", "credo_checks/max_module_lines.ex"],
+      requires: ["credo_checks/line_check.ex", "credo_checks/max_function_lines.ex", "credo_checks/max_module_lines.ex", "credo_checks/folder_size.ex"],
       #
       # If you want to enforce a style guide and need a more traditional linting
       # experience, you can change `strict` to `true` below:
@@ -76,6 +66,7 @@
           {Credo.Check.Design.DuplicatedCode, mass_threshold: 40},
           {El.Credo.MaxFunctionLines, [max_lines: 5]},
           {El.Credo.MaxModuleLines, [max_lines: 100]},
+          {El.Credo.FolderSize, [exempt: ["lib"], exempt_names: ["behaviours"]]},
           {Credo.Check.Warning.Dbg, []},
           {Credo.Check.Warning.IoInspect, []},
           {Credo.Check.Warning.IExPry, []},

README.md

@@ -30,12 +30,22 @@ brew install limadelic/tap/el
 
 ```
 > el
-el -v                        version
-el ls                        list sessions
-el <name> [-m <model>] [-a <agent>] start or status
-el <name> <msg>              send a msg
-el <name|glob> log [n|all]   view log (default: last 1)
-el <name|glob> clear         clear log
-el <name|glob> exit          exit session
-el exit                      exit all sessions
+el -v                                 version
+el ls                                 list names
+el <name> [-json]                     info
+el <name> log [n|all] [-json]         view log (default: last 1)
+
+el <name> start [args]                start session
+  args:
+    -m <model>                        model
+    -a <agent>                        agent
+
+el <name> <msg>                       send a msg
+
+el <name|glob> <cmd>                  apply command to one or many
+el <cmd>                              apply command to all
+  cmds:
+    clear                             start new session
+    exit                              exit session
+    restart                           restart session
 ```

credo_checks/folder_size.ex

@@ -0,0 +1,63 @@
+defmodule El.Credo.FolderSize do
+  use Credo.Check, category: :refactor, base_priority: :normal, run_on_all: true
+
+  alias Credo.SourceFile
+  alias Credo.Check.Params
+  alias Credo.IssueMeta
+
+  def param_defaults do
+    [max: 13, min: 3, exempt: [], exempt_names: []]
+  end
+
+  @check_desc "Folder structure is maintainable."
+
+  def explanations do
+    [
+      check: @check_desc,
+      params: [
+        max: "Maximum .ex files allowed in a folder (default 13)",
+        min: "Minimum .ex files required in a folder (default 3)",
+        exempt: "List of folder paths to skip (default [])",
+        exempt_names: "List of folder names to skip (default [])"
+      ]
+    ]
+  end
+
+  def run(%SourceFile{} = _source_file, _params) do
+    []
+  end
+
+  def run_on_all_source_files(exec, source_files, params) do
+    max = Params.get(params, :max, __MODULE__)
+    min = Params.get(params, :min, __MODULE__)
+    exempt = Params.get(params, :exempt, __MODULE__)
+    exempt_names = Params.get(params, :exempt_names, __MODULE__)
+    source_files
+    |> Enum.group_by(fn sf -> Path.dirname(sf.filename) end)
+    |> Enum.each(fn {folder, files} ->
+      skip? = folder in exempt or Enum.any?(Path.split(folder), &(&1 in exempt_names))
+      unless skip? do
+        sf = hd(files)
+        issue_meta = IssueMeta.for(sf, params)
+        file_count = length(files)
+
+        if file_count > max do
+          issue = format_issue(issue_meta,
+            message: "Folder #{folder} has #{file_count} .ex files (max: #{max})",
+            line_no: 1
+          )
+          Credo.Execution.ExecutionIssues.append(exec, sf, issue)
+        end
+
+        if file_count < min do
+          issue = format_issue(issue_meta,
+            message: "Folder #{folder} has #{file_count} .ex files (min: #{min})",
+            line_no: 1
+          )
+          Credo.Execution.ExecutionIssues.append(exec, sf, issue)
+        end
+      end
+    end)
+    :ok
+  end
+end

features/agent.feature

@@ -7,7 +7,7 @@ Feature: Agent support
     * > el kenny exit
 
   Scenario: Implicit agent detection from name
-    * > el kent:
+    * > el kent start:
       | agent | kent |
       | model | opus |
     * > el kent exit
@@ -19,7 +19,7 @@ Feature: Agent support
     * > el kent exit
 
   Scenario: Lisa agent with sonnet model
-    * > el lisa:
+    * > el lisa start:
       | agent | lisa   |
       | model | sonnet |
     * > el lisa exit

features/card.feature

@@ -17,10 +17,10 @@ Feature: Agent card
     * > el <name> exit
 
     Examples:
-      | args          | name    |
-      | kent          | kent    |
-      | kento -a kent | kento   |
-      | kent@el       | kent@el |
+      | args                | name    |
+      | kent start          | kent    |
+      | kento start -a kent | kento   |
+      | kent@el start       | kent@el |
 
   @el_kent
   Scenario: Used
@@ -41,7 +41,7 @@ Feature: Agent card
     * > el kent exit
 
   Scenario: Anom
-    * > el anom:
+    * > el anom start:
       """
       ╭────────────────────────────────────────────────╮
       │ name:  anom                              id: … │

features/help.feature

@@ -3,19 +3,30 @@ Feature: Help
   Scenario Outline: <scenario>
     * > el <args>:
       """
-      el v0.1.
-      el -v                                version
-      el ls                                list sessions
-      el <name> [-m <model>] [-a <agent>]  start or status
-      el <name> <msg>                      send a msg
-      el <name|glob> log [n|all]           view log (default: last 1)
-      el <name|glob> clear                 clear log
-      el <name|glob> exit                  exit session
-      el exit                              exit all sessions
-      el restart                           restart daemon
+      el v0.1.*
+
+      el -v                                 version
+      el ls                                 list names
+      el <name> [-json]                     info
+      el <name> log [n|all] [-json]         view log (default: last 1)
+
+      el <name> start [args]                start session
+        args:
+          -m <model>                        model
+          -a <agent>                        agent
+
+      el <name> <msg>                       send a msg
+
+      el <name|glob> <cmd>                  apply command to one or many
+      el <cmd>                              apply command to all
+        cmds:
+          clear                             start new session
+          exit                              exit session
+          restart                           restart session
       """
 
     Examples:
-      | scenario | args       |
-      | Help     |            |
-      | Usage    | --nonsense |
+      | scenario           | args     |
+      | Help               |          |
+      | Usage not a flag   | --noflag |
+      | Usage not an agent | nobody   |

features/support/el_helper.rb

@@ -21,7 +21,13 @@ def verify_docstring(args, expected)
       next if words.empty?
 
       words.each do |word|
-        unless output.downcase.include?(word.downcase)
+        matched = output.downcase.include?(word.downcase) ||
+          begin
+            Regexp.new(word, Regexp::IGNORECASE).match?(output)
+          rescue RegexpError
+            false
+          end
+        unless matched
           missing_words << { word: word, source_line: expected_line }
         end
       end

features/support/hooks.rb

@@ -7,7 +7,7 @@
 end
 
 Before do |scenario|
-  scenario.tags.map(&:name).grep(/^@el_(.+)$/) { el($1) }
+  scenario.tags.map(&:name).grep(/^@el_(.+)$/) { el("#{$1} start") }
 end
 
 After do |scenario|

lib/el.ex

@@ -62,37 +62,32 @@ defmodule El do
   end
 
   @impl true
-  def exit_pattern(pattern, opts \\ []) do
-    ls(opts)
-    |> Enum.filter(&match_pattern?(&1, pattern))
-    |> Enum.each(&El.exit(&1, opts))
+  def restart(name, opts \\ []) do
+    El.Lifecycle.exit(name, :restart, opts)
+    resume_session(name, opts)
   end
 
-  @impl true
-  def clear_pattern(pattern, opts \\ []) do
-    ls(opts) |> Enum.filter(&match_pattern?(&1, pattern)) |> Enum.each(&El.clear(&1, opts))
+  defp resume_session(name, opts) do
+    session_meta = Keyword.get(opts, :session_meta, El.Session.Meta)
+    resume_with_session_meta(name, opts, session_meta.lookup(name))
   end
 
-  @impl true
-  def log_pattern(pattern, count, opts \\ []),
-    do:
-      ls(opts) |> Enum.filter(&match_pattern?(&1, pattern)) |> Enum.flat_map(&log_entries(&1, count, opts))
-
-  defp log_entries(name, count, opts) do
-    name |> session_api(opts).log(count) |> filter_found()
+  defp resume_with_session_meta(name, opts, {:ok, session_id, agent, model}) do
+    resume_opts = [resume: session_id, agent: agent, model: model] ++ opts
+    start(name, resume_opts)
   end
 
-  defp filter_found(:not_found), do: []
-  defp filter_found(entries), do: entries
+  @impl true
+  defdelegate restart_pattern(pattern, opts \\ []), to: El.Pattern, as: :restart
 
-  defp match_pattern?(name, pattern) do
-    name_str = Atom.to_string(name)
-    regex_pattern = pattern_to_regex(pattern)
-    Regex.match?(~r/^#{regex_pattern}$/, name_str)
-  end
+  @impl true
+  defdelegate exit_pattern(pattern, opts \\ []), to: El.Pattern, as: :exit
+
+  @impl true
+  defdelegate clear_pattern(pattern, opts \\ []), to: El.Pattern, as: :clear
 
-  defp pattern_to_regex(pattern),
-    do: pattern |> String.replace("*", ".*") |> String.replace("?", ".")
+  @impl true
+  defdelegate log_pattern(pattern, count, opts \\ []), to: El.Pattern, as: :log
 
   @impl true
   def ls(opts \\ []) do

lib/el/agent/detector.ex

@@ -6,8 +6,8 @@ defmodule El.Agent.Detector do
     check_paths(fs, paths(name))
   end
 
-  def cwd(fs \\ El.Infra.FileSystem) do
-    fs.cwd()
+  def cwd!(fs \\ El.Infra.FileSystem) do
+    fs.cwd!()
   end
 
   def mkdir_p!(path, fs \\ El.Infra.FileSystem) do