lampson 0.1.0 → 0.1.2

package/lib/skills.syn

@@ -1,179 +1,179 @@
--- lib/skills.syn — skills: procedimientos en Markdown que el modelo carga bajo demanda 
---
--- Una skill = carpeta con SKILL.md y frontmatter YAML mínimo:
---   ---
---   name: deploy
---   description: Cómo desplegar este proyecto (una línea; es lo que ve el modelo en el índice)
---   ---
---   ...instrucciones...
---
--- Se buscan en (prioridad de abajo hacia arriba, el nombre repetido gana el más específico):
---   .lampson/skills-global/<name>/SKILL.md     -- ~/.agents/skills  (junction que crea lampson.ps1/sh; `npx skills add -g`)
---   .lampson/skills-claude/<name>/SKILL.md     -- ~/.claude/skills  (idem; las de Claude Code también sirven acá)
---   skills/<name>/SKILL.md                     -- del harness (enseñan a usar lampson y Synsema)
---   workspace/.claude/skills/<name>/SKILL.md   -- del proyecto, instaladas para Claude Code
---   workspace/.agents/skills/<name>/SKILL.md   -- del proyecto, canónico de `npx skills add owner/repo` (skills.sh)
---   workspace/skills/<name>/SKILL.md           -- del proyecto (committeables)
---   workspace/.lampson/skills/<name>/SKILL.md  -- locales al proyecto (no committeadas)
---
--- Skills externas (2026-08-27): el estándar "Agent Skills" (agentskills.io) es el mismo formato que usamos
--- (SKILL.md + frontmatter name/description), así que NO hay instalador propio: `npx skills add owner/repo
--- --skill x` deja la skill en ./.agents/skills (o ~/.agents/skills con -g) y Lampson la ve en el próximo
--- arranque. Las carpetas de HOME no se pueden declarar como capability con ruta dinámica → se MONTAN
--- bajo .lampson/ (mismo truco que workspace/).
---
--- El system prompt lleva SOLO el índice (name + description); el contenido entra al contexto
--- cuando el modelo llama a la tool `skill(name)`. Así el prompt no crece con cada skill.
-
-let ROOTS be [
-    {"dir": ".lampson/skills-global", "source": "global"},
-    {"dir": ".lampson/skills-claude", "source": "global"},
-    {"dir": "skills", "source": "harness"},
-    {"dir": "workspace/.claude/skills", "source": "project"},
-    {"dir": "workspace/.agents/skills", "source": "project"},
-    {"dir": "workspace/skills", "source": "project"},
-    {"dir": "workspace/.lampson/skills", "source": "local"}
-]
-
-task frontmatter(md)
-    -- devuelve {name, description, body}; sin frontmatter → name vacío
-    let out be {"name": "", "description": "", "body": md}
-    when not starts_with(md, "---")
-        give out
-    let rest be slice(md, 3, length(md))
-    let parts be split(rest, "\n---")
-    when length(parts) < 2
-        give out
-    let head be parts[0]
-    let body be join(slice(parts, 1, length(parts)), "\n---")
-    each line in split(head, "\n")
-        let l be trim(line)
-        when starts_with(l, "name:")
-            set out["name"] to trim(slice(l, 5, length(l)))
-        otherwise when starts_with(l, "description:")
-            set out["description"] to trim(slice(l, 12, length(l)))
-    set out["body"] to trim(body)
-    give out
-
-task scan_root(root, acc)
-    let out be acc
-    try
-        each e in list_dir(root["dir"])
-            when e["is_dir"]
-                let path be root["dir"] + "/" + e["name"] + "/SKILL.md"
-                try
-                    let fm be frontmatter(read_file(path))
-                    let name be when fm["name"] == "" then e["name"] otherwise fm["name"]
-                    set out[name] to {"name": name, "description": fm["description"], "path": path, "source": root["source"]}
-                recover err
-                    set out to out
-    recover err
-        give out
-    give out
-
--- índice: map name → {name, description, path, source}
-export task index()
-    require file.read("skills")
-    require file.read("skills/*")
-    require file.read("workspace")
-    require file.read("workspace/*")
-    require file.read(".lampson")
-    require file.read(".lampson/*")
-    let acc be {}
-    each r in ROOTS
-        set acc to scan_root(r, acc)
-    give acc
-
--- sección del system prompt
-export task prompt_section(idx)
-    let names be sort_by(keys(idx), (n) => n)
-    when length(names) == 0
-        give ""
-    let lines be ["", "# Skills (load one with the `skill` tool when relevant — read it BEFORE doing that kind of task)"]
-    each n in names
-        let s be idx[n]
-        set lines to append(lines, "- " + n + " (" + s["source"] + "): " + s["description"])
-    give join(lines, "\n")
-
-export task load(name)
-    require file.read("skills")
-    require file.read("skills/*")
-    require file.read("workspace")
-    require file.read("workspace/*")
-    require file.read(".lampson")
-    require file.read(".lampson/*")
-    let idx be index()
-    when not contains(idx, name)
-        raise("unknown skill '" + name + "'. Available: " + join(sort_by(keys(idx), (n) => n), ", "))
-    let s be idx[name]
-    let fm be frontmatter(read_file(s["path"]))
-    -- archivos hermanos de la skill (scripts, templates) para que el modelo sepa que existen
-    let dir be slice(s["path"], 0, length(s["path"]) - length("/SKILL.md"))
-    let extras be []
-    each e in list_dir(dir)
-        when e["name"] != "SKILL.md"
-            set extras to append(extras, dir + "/" + e["name"] + (when e["is_dir"] then "/" otherwise ""))
-    let head be "# skill: " + name + " (" + s["source"] + ", " + s["path"] + ")\n"
-    when length(extras) > 0
-        set head to head + "Files in this skill: " + join(extras, ", ") + "\n"
-    give head + "\n" + fm["body"]
-
--- ---------- instalación de skills externas (skills.sh / cualquier repo con SKILL.md) ----------
--- No reinventamos el instalador: `npx skills add <owner/repo> --skill <name>` (vercel-labs/skills) escribe
--- en ./.agents/skills (scope project) o ~/.agents/skills (-g, scope global — sirve para TODOS los proyectos,
--- que es lo que uno quiere con una skill de Go, de Next, de diseño…). `-a codex -y` = no interactivo
--- (codex ya usa la carpeta canónica, así que no crea symlinks extra; verificado 2026-08-27). Es una acción
--- con efectos fuera del workspace → permission.syn la marca "ask" SIEMPRE (human in the loop), incluso en yolo.
-task shell_exe()
-    require env("LAMPSON_*")
-    require env("OS")
-    let is_win be env("OS", "") == "Windows_NT"
-    give env("LAMPSON_SHELL", when is_win then "C:\\Program Files\\Git\\bin\\bash.exe" otherwise "bash")
-
-task valid_slug(s)
-    when s == nothing or s == ""
-        give false
-    give matches(s, "[a-zA-Z0-9._/@:-]{1,120}")
-
--- la junction/symlink .lampson/skills-global → ~/.agents/skills la crea lampson.ps1/sh al arrancar, pero si
--- la carpeta HOME no existía todavía (primera instalación global) hay que crear ambas ahora
-task ensure_global_mount()
-    require exec
-    require env("LAMPSON_*")
-    require env("OS")
-    let is_win be env("OS", "") == "Windows_NT"
-    let win be "src=\"$USERPROFILE/.agents/skills\"; mkdir -p \"$src\"; [ -e .lampson/skills-global ] || cmd //c mklink //J \".lampson\\\\skills-global\" \"$(cygpath -w \"$src\")\" >/dev/null"
-    let unix be "src=\"$HOME/.agents/skills\"; mkdir -p \"$src\"; [ -e .lampson/skills-global ] || ln -s \"$src\" .lampson/skills-global"
-    run(shell_exe(), ["-c", when is_win then win otherwise unix], 30, {"cwd": "."})
-
-task tail_out(s)
-    let t be strip_ansi(replace_text(s, "\r", ""))
-    when length(t) > 3000
-        give slice(t, length(t) - 3000, length(t))
-    give t
-
-export task install(source, name, scope)
-    require exec
-    require time
-    require env("LAMPSON_*")
-    require env("OS")
-    require file.read("skills")
-    require file.read("skills/*")
-    require file.read("workspace")
-    require file.read("workspace/*")
-    require file.read(".lampson")
-    require file.read(".lampson/*")
-    when not valid_slug(source)
-        raise("invalid source '" + text(source) + "' (expected owner/repo or a github URL)")
-    when not valid_slug(name)
-        raise("invalid skill name '" + text(name) + "'")
-    let global be scope != "project"
-    let argv be ["-y", "skills", "add", source, "--skill", name, "-a", "codex", "-y"]
-    when global
-        set argv to append(argv, "-g")
-        ensure_global_mount()
-    let r be run(shell_exe(), ["-c", "CI=1 npx " + join(argv, " ") + " 2>&1"], 240, {"cwd": when global then "." otherwise "workspace"})
-    let idx be index()
-    when contains(idx, name)
-        give "installed skill '" + name + "' (" + (when global then "global: ~/.agents/skills, available in every project" otherwise "project: ./.agents/skills") + "). It is in the skills index now — call skill(name=\"" + name + "\") to load it.\n" + tail_out(r["stdout"])
-    give "npx skills finished (exit " + text(r["exit_code"]) + ") but '" + name + "' is not in the skills index. Output:\n" + tail_out(r["stdout"])
+-- lib/skills.syn — skills: procedimientos en Markdown que el modelo carga bajo demanda 
+--
+-- Una skill = carpeta con SKILL.md y frontmatter YAML mínimo:
+--   ---
+--   name: deploy
+--   description: Cómo desplegar este proyecto (una línea; es lo que ve el modelo en el índice)
+--   ---
+--   ...instrucciones...
+--
+-- Se buscan en (prioridad de abajo hacia arriba, el nombre repetido gana el más específico):
+--   .lampson/skills-global/<name>/SKILL.md     -- ~/.agents/skills  (junction que crea lampson.ps1/sh; `npx skills add -g`)
+--   .lampson/skills-claude/<name>/SKILL.md     -- ~/.claude/skills  (idem; las de Claude Code también sirven acá)
+--   skills/<name>/SKILL.md                     -- del harness (enseñan a usar lampson y Synsema)
+--   workspace/.claude/skills/<name>/SKILL.md   -- del proyecto, instaladas para Claude Code
+--   workspace/.agents/skills/<name>/SKILL.md   -- del proyecto, canónico de `npx skills add owner/repo` (skills.sh)
+--   workspace/skills/<name>/SKILL.md           -- del proyecto (committeables)
+--   workspace/.lampson/skills/<name>/SKILL.md  -- locales al proyecto (no committeadas)
+--
+-- Skills externas (2026-08-27): el estándar "Agent Skills" (agentskills.io) es el mismo formato que usamos
+-- (SKILL.md + frontmatter name/description), así que NO hay instalador propio: `npx skills add owner/repo
+-- --skill x` deja la skill en ./.agents/skills (o ~/.agents/skills con -g) y Lampson la ve en el próximo
+-- arranque. Las carpetas de HOME no se pueden declarar como capability con ruta dinámica → se MONTAN
+-- bajo .lampson/ (mismo truco que workspace/).
+--
+-- El system prompt lleva SOLO el índice (name + description); el contenido entra al contexto
+-- cuando el modelo llama a la tool `skill(name)`. Así el prompt no crece con cada skill.
+
+let ROOTS be [
+    {"dir": ".lampson/skills-global", "source": "global"},
+    {"dir": ".lampson/skills-claude", "source": "global"},
+    {"dir": "skills", "source": "harness"},
+    {"dir": "workspace/.claude/skills", "source": "project"},
+    {"dir": "workspace/.agents/skills", "source": "project"},
+    {"dir": "workspace/skills", "source": "project"},
+    {"dir": "workspace/.lampson/skills", "source": "local"}
+]
+
+task frontmatter(md)
+    -- devuelve {name, description, body}; sin frontmatter → name vacío
+    let out be {"name": "", "description": "", "body": md}
+    when not starts_with(md, "---")
+        give out
+    let rest be slice(md, 3, length(md))
+    let parts be split(rest, "\n---")
+    when length(parts) < 2
+        give out
+    let head be parts[0]
+    let body be join(slice(parts, 1, length(parts)), "\n---")
+    each line in split(head, "\n")
+        let l be trim(line)
+        when starts_with(l, "name:")
+            set out["name"] to trim(slice(l, 5, length(l)))
+        otherwise when starts_with(l, "description:")
+            set out["description"] to trim(slice(l, 12, length(l)))
+    set out["body"] to trim(body)
+    give out
+
+task scan_root(root, acc)
+    let out be acc
+    try
+        each e in list_dir(root["dir"])
+            when e["is_dir"]
+                let path be root["dir"] + "/" + e["name"] + "/SKILL.md"
+                try
+                    let fm be frontmatter(read_file(path))
+                    let name be when fm["name"] == "" then e["name"] otherwise fm["name"]
+                    set out[name] to {"name": name, "description": fm["description"], "path": path, "source": root["source"]}
+                recover err
+                    set out to out
+    recover err
+        give out
+    give out
+
+-- índice: map name → {name, description, path, source}
+export task index()
+    require file.read("skills")
+    require file.read("skills/*")
+    require file.read("workspace")
+    require file.read("workspace/*")
+    require file.read(".lampson")
+    require file.read(".lampson/*")
+    let acc be {}
+    each r in ROOTS
+        set acc to scan_root(r, acc)
+    give acc
+
+-- sección del system prompt
+export task prompt_section(idx)
+    let names be sort_by(keys(idx), (n) => n)
+    when length(names) == 0
+        give ""
+    let lines be ["", "# Skills (load one with the `skill` tool when relevant — read it BEFORE doing that kind of task)"]
+    each n in names
+        let s be idx[n]
+        set lines to append(lines, "- " + n + " (" + s["source"] + "): " + s["description"])
+    give join(lines, "\n")
+
+export task load(name)
+    require file.read("skills")
+    require file.read("skills/*")
+    require file.read("workspace")
+    require file.read("workspace/*")
+    require file.read(".lampson")
+    require file.read(".lampson/*")
+    let idx be index()
+    when not contains(idx, name)
+        raise("unknown skill '" + name + "'. Available: " + join(sort_by(keys(idx), (n) => n), ", "))
+    let s be idx[name]
+    let fm be frontmatter(read_file(s["path"]))
+    -- archivos hermanos de la skill (scripts, templates) para que el modelo sepa que existen
+    let dir be slice(s["path"], 0, length(s["path"]) - length("/SKILL.md"))
+    let extras be []
+    each e in list_dir(dir)
+        when e["name"] != "SKILL.md"
+            set extras to append(extras, dir + "/" + e["name"] + (when e["is_dir"] then "/" otherwise ""))
+    let head be "# skill: " + name + " (" + s["source"] + ", " + s["path"] + ")\n"
+    when length(extras) > 0
+        set head to head + "Files in this skill: " + join(extras, ", ") + "\n"
+    give head + "\n" + fm["body"]
+
+-- ---------- instalación de skills externas (skills.sh / cualquier repo con SKILL.md) ----------
+-- No reinventamos el instalador: `npx skills add <owner/repo> --skill <name>` (vercel-labs/skills) escribe
+-- en ./.agents/skills (scope project) o ~/.agents/skills (-g, scope global — sirve para TODOS los proyectos,
+-- que es lo que uno quiere con una skill de Go, de Next, de diseño…). `-a codex -y` = no interactivo
+-- (codex ya usa la carpeta canónica, así que no crea symlinks extra; verificado 2026-08-27). Es una acción
+-- con efectos fuera del workspace → permission.syn la marca "ask" SIEMPRE (human in the loop), incluso en yolo.
+task shell_exe()
+    require env("LAMPSON_*")
+    require env("OS")
+    let is_win be env("OS", "") == "Windows_NT"
+    give env("LAMPSON_SHELL", when is_win then "C:\\Program Files\\Git\\bin\\bash.exe" otherwise "bash")
+
+task valid_slug(s)
+    when s == nothing or s == ""
+        give false
+    give matches(s, "[a-zA-Z0-9._/@:-]{1,120}")
+
+-- la junction/symlink .lampson/skills-global → ~/.agents/skills la crea lampson.ps1/sh al arrancar, pero si
+-- la carpeta HOME no existía todavía (primera instalación global) hay que crear ambas ahora
+task ensure_global_mount()
+    require exec
+    require env("LAMPSON_*")
+    require env("OS")
+    let is_win be env("OS", "") == "Windows_NT"
+    let win be "src=\"$USERPROFILE/.agents/skills\"; mkdir -p \"$src\"; [ -e .lampson/skills-global ] || cmd //c mklink //J \".lampson\\\\skills-global\" \"$(cygpath -w \"$src\")\" >/dev/null"
+    let unix be "src=\"$HOME/.agents/skills\"; mkdir -p \"$src\"; [ -e .lampson/skills-global ] || ln -s \"$src\" .lampson/skills-global"
+    run(shell_exe(), ["-c", when is_win then win otherwise unix], 30, {"cwd": "."})
+
+task tail_out(s)
+    let t be strip_ansi(replace_text(s, "\r", ""))
+    when length(t) > 3000
+        give slice(t, length(t) - 3000, length(t))
+    give t
+
+export task install(source, name, scope)
+    require exec
+    require time
+    require env("LAMPSON_*")
+    require env("OS")
+    require file.read("skills")
+    require file.read("skills/*")
+    require file.read("workspace")
+    require file.read("workspace/*")
+    require file.read(".lampson")
+    require file.read(".lampson/*")
+    when not valid_slug(source)
+        raise("invalid source '" + text(source) + "' (expected owner/repo or a github URL)")
+    when not valid_slug(name)
+        raise("invalid skill name '" + text(name) + "'")
+    let global be scope != "project"
+    let argv be ["-y", "skills", "add", source, "--skill", name, "-a", "codex", "-y"]
+    when global
+        set argv to append(argv, "-g")
+        ensure_global_mount()
+    let r be run(shell_exe(), ["-c", "CI=1 npx " + join(argv, " ") + " 2>&1"], 240, {"cwd": when global then "." otherwise "workspace"})
+    let idx be index()
+    when contains(idx, name)
+        give "installed skill '" + name + "' (" + (when global then "global: ~/.agents/skills, available in every project" otherwise "project: ./.agents/skills") + "). It is in the skills index now — call skill(name=\"" + name + "\") to load it.\n" + tail_out(r["stdout"])
+    give "npx skills finished (exit " + text(r["exit_code"]) + ") but '" + name + "' is not in the skills index. Output:\n" + tail_out(r["stdout"])

package/lib/tools/bash.syn

@@ -1,105 +1,105 @@
--- lib/tools/bash.syn — ejecutar un comando de shell con cwd = workspace/
---
--- MIGAS:
---   * en Windows `bash` a secas resuelve al de WSL y cuelga; usar Git Bash explícito (default) o cmd.
---   * NO usar `run()` para el comando del modelo: se cuelga para siempre si el comando deja un
---     descendiente vivo (Windows hereda el pipe de stdout) y su timeout mata solo al hijo directo.
---     Desde 2026-08-27 el comando corre con `proc_spawn` (v0.6.9): eventos por línea hasta el exit o el
---     plazo, stdin cerrado (EOF: nada se queda esperando teclado), y `proc_close` mata el ÁRBOL
---     (Job Object / process group) — un nieto con el pipe abierto no cuelga (1 s de gracia). Adiós
---     bash_wrapper.sh y archivos temporales.
---   * el proceso hijo NO hereda el scope de Synsema (un `cat ../x` en bash funciona). El aislamiento del
---     shell lo dan permission.syn (patrones) + el operador (contenedor si hace falta).
-use "./common.syn" as c
-use "./proc.syn" as proc
-
-export task shell_config()
-    require env("LAMPSON_*")
-    require env("OS")
-    let is_win be env("OS", "") == "Windows_NT"
-    let shell be env("LAMPSON_SHELL", when is_win then "C:\\Program Files\\Git\\bin\\bash.exe" otherwise "bash")
-    let is_cmd be c.ends_with(lower(shell), "cmd.exe") or lower(shell) == "cmd"
-    give {"shell": shell, "flag": env("LAMPSON_SHELL_FLAG", when is_cmd then "/c" otherwise "-c"), "is_cmd": is_cmd}
-
--- comandos que son servidores/watchers: rechazarlos ANTES de correrlos. El timeout mata el árbol, pero
--- un servidor lanzado acá dejó un huérfano con el puerto 3000 tomado y el `process` real se fue al 3001
--- (2026-08-27). La descripción ya lo decía; el modelo lo intentó igual "con | head" — hay que impedirlo.
-let SERVER_RE be ".*((npm|pnpm|yarn|bun)( run)? (dev|start|serve|watch|preview)|npx (next|vite|nodemon|serve|http-server)|next (dev|start)|vite( |$)|nodemon|synsema serve|uvicorn|gunicorn|flask run|manage\\.py runserver|python3? -m http\\.server|rails s(erver)?|php -S|ng serve|cargo (run|watch)|go run|dotnet (run|watch)|tail -f).*"
-
-export task looks_like_server(command)
-    let cmd be trim(lower(replace_text(command, "\n", " ")))
-    when matches(cmd, "timeout [0-9]+.*")
-        give false
-    give matches(cmd, SERVER_RE)
-
--- corre argv con plazo real: junta stdout+stderr por líneas, corta al plazo y mata el árbol
-export task run_capture(exe, argv, t)
-    require exec
-    require time
-    require file("workspace")
-    require file("workspace/*")
-    let p be proc_spawn(exe, argv, {"cwd": c.ROOT, "stderr": "merge", "on_full": "drop_oldest"})
-    proc_close_stdin(p)
-    let deadline be now() + t
-    let lines be []
-    let size be 0
-    let cut be false
-    let code be nothing
-    let timed_out be false
-    while code == nothing and not timed_out
-        let left be deadline - now()
-        when left <= 0
-            set timed_out to true
-        otherwise
-            let ev be proc_recv(p, when left < 0.2 then 0.2 otherwise left)
-            when ev == nothing
-                set timed_out to now() >= deadline
-            otherwise when ev["type"] == "exit"
-                set code to ev["data"]["exit_code"]
-            otherwise when size < 1000000
-                set lines to append(lines, ev["data"])
-                set size to size + length(ev["data"]) + 1
-            otherwise
-                set cut to true
-    proc_close(p)
-    let out be join(lines, "\n")
-    when cut
-        set out to out + "\n[output truncated at 1 MB]"
-    when timed_out
-        give "ERROR: timeout after " + text(t) + "s — the command and its child processes were killed. For servers/watchers use the process tool. Output so far:\n" + out
-    when code != 0
-        set out to out + "\n[exit code " + text(code) + "]"
-    give out
-
-export task tool(command, timeout)
-    require exec
-    require time
-    require env("LAMPSON_*")
-    require env("OS")
-    require file(".lampson")
-    require file(".lampson/*")
-    when looks_like_server(command)
-        give "REFUSED: this looks like a server/watcher (`" + command + "`). bash kills its process tree at the timeout, and a dev server left half-killed keeps its port busy. Use the process tool instead: process(action=\"start\", name=\"dev\", command=\"...\"), then process(action=\"logs\") or just keep working — its new output is appended to every bash result. If it is really a one-shot command, wrap it with `timeout 30 ...` and explain why."
-    let sc be shell_config()
-    let t be when timeout == nothing then 120 otherwise floor(timeout)
-    when t > 600
-        set t to 600
-    when t < 1
-        set t to 1
-    let out be run_capture(sc["shell"], [sc["flag"], command], t)
-    when trim(out) == ""
-        set out to "(no output)"
-    -- lo que pasó mientras tanto en los procesos gestionados (servidores) — el agente "ve la consola"
-    let rep be proc.report()
-    when rep != ""
-        set out to out + "\n\n" + rep
-    give c.truncate(out, c.MAX_OUTPUT)
-
-export let SPEC be {
-    "name": "bash",
-    "description": "Run a shell command with the workspace root as working directory (no persistent shell state between calls: cwd and env reset). Returns stdout+stderr and [exit code N] when non-zero. Use it for git, tests, builds, package managers. Commands are killed (with their child processes) after the timeout (default 120s, max 600) — so NEVER run a server, watcher or REPL here: use the `process` tool (start/logs/stop) for anything long-running; its new log lines are appended to every bash result automatically. Avoid interactive commands. Prefer read/grep/find over cat/grep/find for files.",
-    "parameters": {"type": "object", "properties": {
-        "command": {"type": "string"},
-        "timeout": {"type": "integer", "description": "Seconds (optional, default 120, max 600)"}
-    }, "required": ["command"]}
-}
+-- lib/tools/bash.syn — ejecutar un comando de shell con cwd = workspace/
+--
+-- MIGAS:
+--   * en Windows `bash` a secas resuelve al de WSL y cuelga; usar Git Bash explícito (default) o cmd.
+--   * NO usar `run()` para el comando del modelo: se cuelga para siempre si el comando deja un
+--     descendiente vivo (Windows hereda el pipe de stdout) y su timeout mata solo al hijo directo.
+--     Desde 2026-08-27 el comando corre con `proc_spawn` (v0.6.9): eventos por línea hasta el exit o el
+--     plazo, stdin cerrado (EOF: nada se queda esperando teclado), y `proc_close` mata el ÁRBOL
+--     (Job Object / process group) — un nieto con el pipe abierto no cuelga (1 s de gracia). Adiós
+--     bash_wrapper.sh y archivos temporales.
+--   * el proceso hijo NO hereda el scope de Synsema (un `cat ../x` en bash funciona). El aislamiento del
+--     shell lo dan permission.syn (patrones) + el operador (contenedor si hace falta).
+use "./common.syn" as c
+use "./proc.syn" as proc
+
+export task shell_config()
+    require env("LAMPSON_*")
+    require env("OS")
+    let is_win be env("OS", "") == "Windows_NT"
+    let shell be env("LAMPSON_SHELL", when is_win then "C:\\Program Files\\Git\\bin\\bash.exe" otherwise "bash")
+    let is_cmd be c.ends_with(lower(shell), "cmd.exe") or lower(shell) == "cmd"
+    give {"shell": shell, "flag": env("LAMPSON_SHELL_FLAG", when is_cmd then "/c" otherwise "-c"), "is_cmd": is_cmd}
+
+-- comandos que son servidores/watchers: rechazarlos ANTES de correrlos. El timeout mata el árbol, pero
+-- un servidor lanzado acá dejó un huérfano con el puerto 3000 tomado y el `process` real se fue al 3001
+-- (2026-08-27). La descripción ya lo decía; el modelo lo intentó igual "con | head" — hay que impedirlo.
+let SERVER_RE be ".*((npm|pnpm|yarn|bun)( run)? (dev|start|serve|watch|preview)|npx (next|vite|nodemon|serve|http-server)|next (dev|start)|vite( |$)|nodemon|synsema serve|uvicorn|gunicorn|flask run|manage\\.py runserver|python3? -m http\\.server|rails s(erver)?|php -S|ng serve|cargo (run|watch)|go run|dotnet (run|watch)|tail -f).*"
+
+export task looks_like_server(command)
+    let cmd be trim(lower(replace_text(command, "\n", " ")))
+    when matches(cmd, "timeout [0-9]+.*")
+        give false
+    give matches(cmd, SERVER_RE)
+
+-- corre argv con plazo real: junta stdout+stderr por líneas, corta al plazo y mata el árbol
+export task run_capture(exe, argv, t)
+    require exec
+    require time
+    require file("workspace")
+    require file("workspace/*")
+    let p be proc_spawn(exe, argv, {"cwd": c.ROOT, "stderr": "merge", "on_full": "drop_oldest"})
+    proc_close_stdin(p)
+    let deadline be now() + t
+    let lines be []
+    let size be 0
+    let cut be false
+    let code be nothing
+    let timed_out be false
+    while code == nothing and not timed_out
+        let left be deadline - now()
+        when left <= 0
+            set timed_out to true
+        otherwise
+            let ev be proc_recv(p, when left < 0.2 then 0.2 otherwise left)
+            when ev == nothing
+                set timed_out to now() >= deadline
+            otherwise when ev["type"] == "exit"
+                set code to ev["data"]["exit_code"]
+            otherwise when size < 1000000
+                set lines to append(lines, ev["data"])
+                set size to size + length(ev["data"]) + 1
+            otherwise
+                set cut to true
+    proc_close(p)
+    let out be join(lines, "\n")
+    when cut
+        set out to out + "\n[output truncated at 1 MB]"
+    when timed_out
+        give "ERROR: timeout after " + text(t) + "s — the command and its child processes were killed. For servers/watchers use the process tool. Output so far:\n" + out
+    when code != 0
+        set out to out + "\n[exit code " + text(code) + "]"
+    give out
+
+export task tool(command, timeout)
+    require exec
+    require time
+    require env("LAMPSON_*")
+    require env("OS")
+    require file(".lampson")
+    require file(".lampson/*")
+    when looks_like_server(command)
+        give "REFUSED: this looks like a server/watcher (`" + command + "`). bash kills its process tree at the timeout, and a dev server left half-killed keeps its port busy. Use the process tool instead: process(action=\"start\", name=\"dev\", command=\"...\"), then process(action=\"logs\") or just keep working — its new output is appended to every bash result. If it is really a one-shot command, wrap it with `timeout 30 ...` and explain why."
+    let sc be shell_config()
+    let t be when timeout == nothing then 120 otherwise floor(timeout)
+    when t > 600
+        set t to 600
+    when t < 1
+        set t to 1
+    let out be run_capture(sc["shell"], [sc["flag"], command], t)
+    when trim(out) == ""
+        set out to "(no output)"
+    -- lo que pasó mientras tanto en los procesos gestionados (servidores) — el agente "ve la consola"
+    let rep be proc.report()
+    when rep != ""
+        set out to out + "\n\n" + rep
+    give c.truncate(out, c.MAX_OUTPUT)
+
+export let SPEC be {
+    "name": "bash",
+    "description": "Run a shell command with the workspace root as working directory (no persistent shell state between calls: cwd and env reset). Returns stdout+stderr and [exit code N] when non-zero. Use it for git, tests, builds, package managers. Commands are killed (with their child processes) after the timeout (default 120s, max 600) — so NEVER run a server, watcher or REPL here: use the `process` tool (start/logs/stop) for anything long-running; its new log lines are appended to every bash result automatically. Avoid interactive commands. Prefer read/grep/find over cat/grep/find for files.",
+    "parameters": {"type": "object", "properties": {
+        "command": {"type": "string"},
+        "timeout": {"type": "integer", "description": "Seconds (optional, default 120, max 600)"}
+    }, "required": ["command"]}
+}