Gupp Propulsion

GUPP Propulsion

The Gas Town Universal Propulsion Principle: If there is work on your hook, YOU MUST RUN IT.

GUPP is the interrupt controller of the Gastown chipset. In a real processor, the interrupt controller converts external events (keyboard press, network packet, timer tick) into CPU interrupts that force immediate handling. Without it, the CPU would have to poll every device continuously, wasting cycles on checks that almost always find nothing. GUPP does the same for AI coding agents: it converts the polled model (agent checks periodically, waits for user input) into an interrupt-driven model (work appears on hook, agent executes immediately).

Why GUPP Exists

LLM coding assistants are trained through RLHF to be helpful, harmless, and honest. A side effect of this training is a strong bias toward waiting for the user -- asking clarifying questions, seeking confirmation before acting, pausing between steps for feedback. This is appropriate in interactive chat but catastrophic for autonomous multi-agent orchestration, where every moment of idle waiting is a moment the pipeline stalls.

Gastown discovered this empirically. Agents spawned with a work item would introduce themselves, summarize their understanding of the task, and then wait. They would ask "Shall I proceed?" when the answer was already on their hook. GUPP was created to override this trained passivity with an explicit, non-negotiable execution mandate.

The principle is simple: if you have hooked work, you do not wait. You do not ask for confirmation. You do not summarize your plan and pause for feedback. You begin execution immediately. This is physics, not politeness. Gastown is a steam engine and you are a piston.

Activation Triggers

This skill activates when:

• An agent has work assigned to its hook and is not yet executing
• Stall detection identifies an agent with hooked work that has gone idle
• A new agent is spawned and needs GUPP enforcement injected into its context
• Runtime-specific GUPP strategy selection is needed
• Heartbeat supervision needs to be configured for active agents
• An agent has been nudged but remains stalled

Per-Runtime Enforcement Strategies

GUPP enforcement adapts to each runtime's capabilities through the Runtime HAL. The HAL detects the active runtime and GUPP selects the highest-fidelity enforcement mechanism available.

Claude Code

Claude Code provides the richest enforcement surface through its session hooks system.

Codex

Codex lacks session hooks. GUPP uses startup command injection as the primary strategy.

Gemini

Gemini has no hook support and limited startup injection. GUPP relies on polling.

Strategy Selection

The Runtime HAL exposes getGUPPStrategy() which returns the primary strategy for the detected runtime. Other chipset skills call this method without knowing which runtime is active:

const hal = detectRuntime();
const strategy = hal.getGUPPStrategy();

switch (strategy) {
  case 'hook_injection':
    // Claude Code path: inject via SessionStart hook
    break;
  case 'startup_fallback':
    // Codex path: inject via gt prime command
    break;
  case 'polling':
    // Gemini/unknown path: agent polls for assignments
    break;
}

Configurable Thresholds

All GUPP timing parameters are configurable through the chipset YAML. Defaults are tuned for typical LLM agent behavior but can be adjusted per-project or per-runtime based on observed performance.

gupp:
  thresholds:
    stall_detection: 300    # seconds (5 min) -- time before declaring an agent stalled
    nudge_interval: 120     # seconds (2 min) -- time between heartbeat checks
    restart_threshold: 600  # seconds (10 min) -- time before requesting session restart

Threshold Reference

The Runtime HAL provides per-runtime defaults that override the chipset YAML defaults when a specific runtime is detected. For example, Claude Code uses a 120s stall threshold (the hook system makes stalls more detectable) while Gemini uses 300s (polling introduces latency).

Deacon Heartbeat Pattern

The Deacon heartbeat is the supervision loop that enforces GUPP across all active agents. It runs independently of any individual agent session -- typically inside the witness-observer or as a standalone patrol process.

1. Timer fires (every nudge_interval seconds)
2. For each agent with an active hook:
   a. Read last_activity timestamp from state file
   b. If now - last_activity > stall_detection:
      i.  Send nudge via nudge-sync
      ii. Record nudge timestamp and count
3. For each previously nudged agent:
   a. If still stalled after nudge_interval:
      i.  Escalate to witness-observer
      ii. Witness sends health_escalation mail to mayor
4. For each agent past restart_threshold:
   a. Request boot restart via Runtime HAL
   b. Increment restart counter for this bead
   c. If restart_count >= 3: escalate to human

The full heartbeat protocol is documented in heartbeat.md.

Observable Metrics

GUPP exposes these metrics for skill-creator's pattern detection and adaptive learning. Over time, skill-creator proposes refinements to thresholds and strategy selections based on observed effectiveness.

GUPP Response Time

Time elapsed from hook assignment to first work activity (first commit, first file edit, or first status update). Measured per-agent, per-session.

gupp_response_time_seconds{agent="polecat-alpha", runtime="claude"} 12.4

Ideal: under 30 seconds for Claude Code (hook injection), under 60 seconds for Codex (startup fallback), under 120 seconds for Gemini (polling).

Nudge Effectiveness

Boolean per-nudge: did the agent resume work within nudge_interval seconds after receiving the nudge? Tracks whether nudges are actually fixing stalls or just adding noise.

gupp_nudge_effective{agent="polecat-alpha", nudge_id="n-001"} true
gupp_nudge_effective{agent="polecat-beta", nudge_id="n-002"} false

A nudge effectiveness rate below 50% suggests the stall detection threshold is too aggressive (false positives) or the agent is genuinely stuck and needs restart rather than nudging.

Strategy Success Rate

Per-runtime success rate: what percentage of GUPP activations result in the agent beginning work within the expected response window? Tracks which primary strategy produces the fastest, most reliable GUPP response.

gupp_strategy_success_rate{runtime="claude", strategy="hook_injection"} 0.94
gupp_strategy_success_rate{runtime="codex", strategy="startup_fallback"} 0.78
gupp_strategy_success_rate{runtime="gemini", strategy="polling"} 0.65

Stall Frequency

How often agents stall per session. A session with zero stalls is ideal. High stall frequency may indicate a systemic issue (context window exhaustion, ambiguous work items, missing dependencies).

gupp_stalls_per_session{runtime="claude"} 0.3
gupp_stalls_per_session{runtime="codex"} 1.1

Learning Feedback Loop

Skill-creator observes these metrics across sessions and proposes adjustments:

1. Threshold tuning: If stall detection fires frequently but nudge effectiveness is low, increase stall_detection to reduce false positives
2. Strategy switching: If a runtime's primary strategy has low success rate, recommend switching to the secondary
3. Interval optimization: If nudge effectiveness is high but response time is long, decrease nudge_interval for faster recovery
4. Restart policy: If restarts consistently fix stalls, the agent may need better initial context (improve hook injection quality)

Safety Boundaries

GUPP Is Advisory in GSD

GUPP enforcement is ADVISORY within GSD's structured workflow. The GSD orchestrator's phase gates, verification steps, and checkpoint protocols take precedence over GUPP urgency. If a GSD checkpoint requires human verification, GUPP does not override it. If a phase gate blocks progress pending approval, GUPP does not force execution past the gate.

The hierarchy is:

GSD orchestrator (highest authority)
  |
  v
Phase gates and checkpoints
  |
  v
GUPP propulsion (execution enforcement)
  |
  v
Agent autonomy (lowest -- must obey all above)

GUPP operates between the orchestrator's structural gates. Within a phase, within an approved plan, within a committed task -- GUPP demands immediate execution. But it never overrides the orchestrator's decision about what to execute or when a phase is complete.

Restart Limits

The watchdog restart mechanism has strict limits to prevent infinite restart loops:

Human Escalation

After 3 restarts for the same bead without resolution, GUPP stops attempting automated recovery and escalates to a human operator:

if (restartCount >= 3) {
  const escalation: AgentMessage = {
    from: witnessId,
    to: 'mayor',
    channel: 'mail',
    payload: `HUMAN_ESCALATION: ${beadId} has stalled ${restartCount} times. ` +
             `Automated recovery exhausted. Requires human intervention.`,
    timestamp: new Date().toISOString(),
    durable: true,
  };
  // Mayor surfaces this to the human operator
}

The mayor receives the escalation and surfaces it through whatever channel the human is monitoring (terminal output, notification file, log). GUPP does not attempt a fourth restart.

No Data Destruction

GUPP enforcement never destroys work in progress. Restarts preserve the agent's branch and commits. Nudges are non-destructive signals. Escalations are informational. At no point does GUPP delete files, reset branches, or discard uncommitted changes.

Integration with Other Gastown Skills

References

• references/gastown-origin.md -- The GUPP principle from Gastown, how it fights model training bias
• references/boundaries.md -- Advisory nature, restart limits, human escalation rules
• heartbeat.md -- Deacon heartbeat supervision pattern and integration points