kairos-chain 3.50.0 → 3.51.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 826aabda2632b42bb5e4c688f443616faf29b9b97daba55aa02fa6834bf1629d
-  data.tar.gz: 2a743cfa76eb0d56db2220ed40c11ea0cc52f88c9b16ed8dfb84855d54b15981
+  metadata.gz: fea78afc847b26db63d7355188444750fdb3cbbf84494cc489e63402bea3b630
+  data.tar.gz: b638968a01320bf5196d7f2b383b5c6dfa118a9432dc6feadf4ef04cbd4ee6b8
 SHA512:
-  metadata.gz: 0e0ab6e95d0f527e738053fe45e9899e761820809c0f26ab37dd55eacadf13b387b22737475a8685b894d095aa9ba4529df142ab3809adf917c2ff275b46f403
-  data.tar.gz: 1272d3d2ffd8cc80615dc1990346758982cb64cb78d947965d754d3ae5d0e148524044c8197efbb836e0ecf067cfcae69f51aa90a934a71da691525c0b190da2
+  metadata.gz: 0be2e69efbd5eda0c8c839c627389def7dd68db5cda29a904072e762677238459ef6a2fad8373d612715f1eeeb928579a7a318bc97ffdd5fb6c38eb54991c522
+  data.tar.gz: 74fd8b7ba83ef25552130dbd7b86047ce96fda674b1d151b247813597adef09c60ec192c524507ad054d3af3c63154b497de71d912891f84cad8637e79bd1bdf

data/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.51.0] - 2026-07-23
+
+### Agent SkillSet — interruption resilience A-1 + A-2
+
+Addresses the failure mode where the orchestrator's API stalling leaves an
+auto-mode agent loop waiting on input: the running MCP server is intact, but
+the driver stops, and auto-permission is orthogonal to driver liveness.
+Design v0.3.1 FROZEN (design-by-invariant, multi-LLM review 3R converged).
+
+- **A-1 — AdvanceGate** (`lib/agent/advance_gate.rb`): every state-advancing
+  `agent_step` call passes through a per-session serialized, atomic, anchored
+  gate. INV-A2 (serialized atomic advance via `advance.lock` + tmp-rename
+  commit), INV-A3 (anchored at-most-once with a `seq:state:cycle` anchor,
+  committed outcomes replay on retry, side-effect intent bracket with
+  no-silent-drop), INV-A4 (`next_move` derivable from persisted state),
+  INV-A5 (adjudication as a gated judgment). `adjudicate` action added.
+  Impl review 4R converged, 49 probes.
+- **A-2 — delegated step executor** (`lib/agent/step_delegation.rb`,
+  `bin/agent_step_worker.rb`): INV-A1 driver independence. `agent_step` with
+  `execution: "delegated"` returns a resumable handle while a detached
+  (setsid) worker re-enters the SAME gated `agent_step` under server-side
+  ownership — delegate → wait → collect, transplanted from the review
+  SkillSet. All correctness inherited from the A-1 gate; the delegation layer
+  is coordination/observability only. New `agent_wait` tool; `agent_status`
+  surfaces the handle. Impl review 6R converged, 81 probes total.
+- Attended real-worker run with a live LLM-bearing step validated
+  (2026-07-23, isolated harness): the detached worker bootstrapped the full
+  ToolRegistry and ran ORIENT+DECIDE via the claude CLI; liveness, collect,
+  and collector-owned teardown all held.
+- Native body path unchanged (selectable-off). All prior agent-suite tests
+  remain at the main baseline.
+
 ## [3.50.0] - 2026-07-23
 
 ### Chain Distillation SkillSet — slice 1 (CD-1..CD-6)

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.50.0"
+  VERSION = "3.51.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/skillsets/agent/bin/agent_step_worker.rb

@@ -0,0 +1,183 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# Interruption resilience Slice A-2 — detached agent step worker (INV-A1).
+#
+# Spawned by StepDelegation#spawn_worker after agent_step was called with
+# execution: "delegated". This worker is deliberately thin: it bootstraps a
+# ToolRegistry (the same construction the MCP server uses) and re-enters the
+# SAME gated agent_step path with the recorded arguments (the delegation-start
+# anchor is already injected into those arguments). Every correctness property
+# — per-session serialization, anchored at-most-once, side-effect intent
+# bracket — is enforced by the AdvanceGate inside that call (Slice A-1), not by
+# this script. If this worker dies, the driver re-issues the recorded call
+# safely; if it double-runs, the gate serializes and replays.
+#
+# argv: <session_id> <session_dir>
+# env:  KAIROS_PROJECT_ROOT (chdir target)
+#       KAIROS_SERVER_LIB   (lib dir to load kairos_mcp from)
+#       KAIROS_DATA_DIR     (the server's effective data dir; makes the
+#                            worker resolve the SAME .kairos)
+#
+# Exit codes: 0 success; 1 exception; 125 setsid failed; 130 signal.
+#
+# NB: bootstrap failures (LoadError/ScriptError from require) are caught too,
+# so the driver always sees a result rather than a silently hung handle.
+
+require 'json'
+require 'time'
+require 'fileutils'
+
+session_id  = ARGV[0] or abort 'usage: agent_step_worker.rb <session_id> <session_dir>'
+session_dir = ARGV[1] or abort 'usage: agent_step_worker.rb <session_id> <session_dir>'
+
+# Read the handle identity from the raw file first, so even a bootstrap
+# failure can tag its error result with the delegation it belongs to.
+def read_handle_identity(session_dir)
+  raw = JSON.parse(File.read(File.join(session_dir, 'delegation.json')))
+  { 'issue_anchor' => raw['issue_anchor'], 'action_key' => raw['action_key'],
+    'step_token' => raw['step_token'] }
+rescue StandardError
+  {}
+end
+
+def write_raw_result(session_dir, identity, outcome)
+  payload = identity.merge('outcome' => outcome)
+  tmp = File.join(session_dir, "delegation_result.json.tmp.#{Process.pid}")
+  File.write(tmp, JSON.generate(payload))
+  File.rename(tmp, File.join(session_dir, 'delegation_result.json'))
+rescue StandardError
+  # nothing more we can do
+end
+
+boot_identity = read_handle_identity(session_dir)
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+begin
+  require 'agent/step_delegation'
+rescue ScriptError, StandardError => e
+  # The delegation lib is co-located with this script; if even it cannot load
+  # we tag a raw result with the handle identity so status can surface it as
+  # 'ready' (an error outcome) rather than the driver waiting out the grace.
+  write_raw_result(session_dir, boot_identity,
+                   { 'status' => 'error',
+                     'error' => "worker bootstrap failed: #{e.class}: #{e.message}" })
+  exit 1
+end
+
+delegation = KairosMcp::SkillSets::Agent::StepDelegation.new(session_dir)
+my_token = boot_identity['step_token']
+
+shutdown = { requested: false }
+%w[TERM INT HUP].each do |sig|
+  Signal.trap(sig) { shutdown[:requested] = true }
+end
+
+begin
+  Process.setsid
+rescue Errno::EPERM
+  # Already a session leader — acceptable; continue.
+rescue StandardError => e
+  delegation.write_result({ 'status' => 'error',
+                            'error' => "worker setsid failed: #{e.message}" },
+                          identity: boot_identity)
+  exit 125
+end
+
+heartbeat_thread = Thread.new do
+  loop do
+    begin
+      delegation.touch_heartbeat(my_token)
+    rescue StandardError
+      # A transient touch failure must not kill the heartbeat thread and
+      # make a live worker look crashed; retry on the next tick.
+    end
+    sleep KairosMcp::SkillSets::Agent::StepDelegation::HEARTBEAT_INTERVAL_SECONDS
+  end
+end
+
+# Self-timeout watchdog: a hung gated call would otherwise hold the advance
+# lock forever. Exiting the process releases its flock; the driver then sees
+# 'crashed' and re-issues safely. We deliberately write NO result here so the
+# collector takes the crash path — if the gated advance had already committed,
+# crashed_response recovers its outcome from the gate log; an error result
+# would instead mask that committed advance.
+timeout_s = KairosMcp::SkillSets::Agent::StepDelegation.worker_self_timeout_seconds
+watchdog = Thread.new do
+  sleep timeout_s
+  exit!(124)
+end
+
+begin
+  Dir.chdir(ENV['KAIROS_PROJECT_ROOT']) if ENV['KAIROS_PROJECT_ROOT'] &&
+                                           Dir.exist?(ENV['KAIROS_PROJECT_ROOT'])
+  $LOAD_PATH.unshift(ENV['KAIROS_SERVER_LIB']) if ENV['KAIROS_SERVER_LIB']
+  # KAIROS_DATA_DIR was set in the worker env by spawn_worker so ToolRegistry
+  # / Session resolve the server's effective .kairos even under --data-dir.
+  require 'kairos_mcp/tool_registry'
+
+  pending = delegation.pending
+  raise "no pending delegation in #{session_dir}" unless pending
+
+  # Supersession guard: run ONLY if the live handle is still ours. If a fresh
+  # open_handle replaced it while we were starting up (e.g. we were declared
+  # 'crashed' on a stale heartbeat and the driver re-delegated), or we could
+  # not read our own identity at boot (my_token nil), do NOT run: the new
+  # worker owns this delegation, and the gate would replay/serialize our stale
+  # call anyway. Exiting leaves the current handle to its rightful worker.
+  if my_token.nil? || pending['step_token'] != my_token
+    exit 0
+  end
+
+  # Past the guard, boot_identity is non-empty and is our own handle identity
+  # (also driving the per-token heartbeat); write_result tags with it.
+  identity = boot_identity
+
+  args = (pending['arguments'] || {}).merge('session_id' => session_id)
+  args.delete('execution') # never recurse into another delegation
+
+  exit 130 if shutdown[:requested]
+
+  registry = KairosMcp::ToolRegistry.new
+  raw = registry.call_tool('agent_step', args)
+
+  # Normalize the MCP content shape to the response hash the inline call
+  # would have returned.
+  text = if raw.is_a?(Array) && raw.first.is_a?(Hash)
+           raw.first[:text] || raw.first['text']
+         end
+  response = begin
+    text ? JSON.parse(text) : { 'status' => 'error', 'error' => 'unrecognized tool result shape' }
+  rescue JSON::ParserError
+    { 'status' => 'error', 'error' => 'unparseable tool result', 'raw' => text.to_s[0, 500] }
+  end
+
+  # Write the result (tagged with our OWN startup identity) and leave the
+  # pending handle in place: teardown is the collector's job (agent_wait#collect
+  # clears result+handle atomically under delegation.lock), so the worker never
+  # races a concurrently-opened fresh delegation by clearing state it may no
+  # longer own or by mislabeling its result as a newer delegation's.
+  delegation.write_result(response, identity: identity)
+  exit 0
+rescue SystemExit, SignalException
+  # A deliberate exit (including our own `exit 0`) or a signal is not a
+  # failure to report — let it propagate.
+  raise
+rescue Exception => e # rubocop:disable Lint/RescueException
+  # Catch Exception, not just StandardError: LoadError/ScriptError from the
+  # bootstrap require are exactly the failure class the driver must see as a
+  # result rather than a silently hung handle. Leave teardown to the collector.
+  # Tag with our OWN startup identity (boot_identity is always our handle;
+  # the in-block `identity` local may be unassigned if we failed early, and
+  # a re-read of pending could belong to a superseding delegation).
+  begin
+    delegation.write_result({ 'status' => 'error', 'error' => "worker: #{e.class}: #{e.message}" },
+                            identity: (boot_identity.empty? ? nil : boot_identity))
+  rescue StandardError
+    # best effort
+  end
+  exit 1
+ensure
+  watchdog&.kill
+  heartbeat_thread&.kill
+end

data/templates/skillsets/agent/lib/agent/advance_gate.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'digest'
+require 'time'
+
+module KairosMcp
+  module SkillSets
+    module Agent
+      # Interruption resilience Slice A (design v0.3.1 FROZEN).
+      #
+      # AdvanceGate is the single entry point through which every
+      # state-advancing operation on an agent session must pass. It carries
+      # three of the frozen invariants:
+      #
+      #   INV-A2 (serialized atomic advance): a non-blocking per-session file
+      #     lock serializes advances; a concurrent caller is refused with
+      #     'busy', never interleaved. Every gate file is committed via
+      #     tmp-write + atomic rename, so a resumed driver observes a
+      #     transition in full or not at all.
+      #
+      #   INV-A3 (anchored at-most-once): each advance is bound to the anchor
+      #     of the state it was issued against. A re-issue whose anchor (and
+      #     action) match an already-committed advance replays the recorded
+      #     outcome without re-executing. A stale anchor is rejected with the
+      #     current state. The side-effect intent bracket (open_intent /
+      #     close_intent) makes a crash between executing an external effect
+      #     and recording it detectable: the orphan intent surfaces as an
+      #     unresolved point instead of being silently dropped or re-run.
+      #
+      #   INV-A4 (monotone derivable recovery): current_anchor and the
+      #     committed advance log are derived from persisted state alone, so
+      #     a fresh driver needs no memory of the interrupted one.
+      #
+      # The anchor is a monotonic sequence number combined with the session
+      # state name and cycle ("<seq>:<state>:<cycle>"): the sequence carries
+      # uniqueness, the state/cycle carry readability. Anchors are optional on
+      # the wire for compatibility (§7): an anchorless call is treated as
+      # issued against the current state, and every response carries the new
+      # anchor so the caller can join the regime on its next call.
+      class AdvanceGate
+        LOCK_FILE   = 'advance.lock'
+        STATE_FILE  = 'advance.json'
+        LOG_FILE    = 'advance_log.jsonl'
+        INTENT_FILE = 'act_intent.json'
+
+        # Raised never; results are communicated as Hashes so the tool layer
+        # can render them without exception plumbing.
+
+        def initialize(session_dir)
+          @dir = session_dir
+          FileUtils.mkdir_p(@dir)
+        end
+
+        # ---- anchor -------------------------------------------------------
+
+        def seq
+          gate_state['seq']
+        end
+
+        def current_anchor(session)
+          "#{gate_state['seq']}:#{session.state}:#{session.cycle_number}"
+        end
+
+        # ---- serialized advance (INV-A2) ---------------------------------
+
+        # Runs the block under the per-session advance lock.
+        # Returns the block's value, or { 'status' => 'busy' } if another
+        # advance holds the lock. The lock spans anchor validation, phase
+        # execution, and outcome commit, so no two advances interleave.
+        def with_lock
+          File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |f|
+            unless f.flock(File::LOCK_EX | File::LOCK_NB)
+              return { 'status' => 'busy',
+                       'error' => 'another advance is in progress on this session' }
+            end
+            begin
+              # Any memoized gate state predates the lock; drop it so every
+              # read inside the critical section reflects the persisted truth
+              # (a gate instance that outlives a lock window must not serve a
+              # stale seq).
+              @gate_state = nil
+              yield
+            ensure
+              f.flock(File::LOCK_UN)
+            end
+          end
+        end
+
+        # True while another advance holds the lock. Read-only probes (the
+        # status surface) use this to distinguish "an advance is in flight"
+        # from "an advance died mid-effect" — an open intent plus a held lock
+        # is normal execution, not an unresolved point.
+        # Probes with a shared lock so concurrent probes never serialize each
+        # other and the window in which a probe could make a real advance's
+        # LOCK_EX attempt fail spuriously is minimal (a spurious 'busy' is
+        # safe: the caller retries).
+        def busy?
+          File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |f|
+            if f.flock(File::LOCK_SH | File::LOCK_NB)
+              f.flock(File::LOCK_UN)
+              false
+            else
+              true
+            end
+          end
+        end
+
+        # ---- anchored at-most-once (INV-A3) ------------------------------
+
+        # Checks a provided anchor against the current state and the committed
+        # log. Returns:
+        #   { 'disposition' => 'proceed' }                     — execute normally
+        #   { 'disposition' => 'replay', 'outcome' => {...} }  — committed already
+        #   { 'disposition' => 'rejected', ... }               — stale/unknown anchor
+        # A nil anchor proceeds (compatibility path, §7: the first advance
+        # establishes the anchor from the state it reads).
+        def check(anchor, action, session)
+          return { 'disposition' => 'proceed' } if anchor.nil? || anchor.to_s.empty?
+          return { 'disposition' => 'proceed' } if anchor == current_anchor(session)
+
+          committed = find_committed(anchor)
+          if committed
+            if committed['action'] == action
+              return { 'disposition' => 'replay', 'outcome' => committed['outcome'] }
+            end
+            return { 'disposition' => 'rejected',
+                     'reason' => 'anchor was consumed by a different action',
+                     'consumed_by' => committed['action'] }
+          end
+
+          { 'disposition' => 'rejected',
+            'reason' => 'anchor does not match current session state' }
+        end
+
+        # Commits an advance: appends the outcome record and bumps the
+        # sequence, both atomically. Called with the lock held, after the
+        # session's own state has been persisted, so a crash before this call
+        # leaves the old anchor valid (the advance never happened) and a crash
+        # after leaves it replayable (the advance fully happened).
+        def commit(anchor_at_issue, action, outcome)
+          entry = {
+            'seq'       => gate_state['seq'],
+            'anchor'    => anchor_at_issue,
+            'action'    => action,
+            'outcome'   => outcome,
+            'timestamp' => Time.now.utc.iso8601
+          }
+          repair_log_tail
+          File.open(log_path, 'a') { |f| f.puts(JSON.generate(entry)) }
+          atomic_write(state_path, JSON.pretty_generate('seq' => gate_state['seq'] + 1))
+          @gate_state = nil
+        end
+
+        # ---- side-effect intent bracket (INV-A3, no silent drop) ---------
+
+        # Persisted before an external side effect begins.
+        def open_intent(anchor, decision_payload)
+          digest = Digest::SHA256.hexdigest(JSON.generate(decision_payload || {}))[0, 16]
+          atomic_write(intent_path, JSON.pretty_generate(
+            'anchor' => anchor, 'decision_digest' => digest,
+            'opened_at' => Time.now.utc.iso8601
+          ))
+        end
+
+        # Removed only after the advance carrying the effect has committed.
+        def close_intent
+          File.delete(intent_path) if File.exist?(intent_path)
+        end
+
+        # An intent whose advance never committed. Its outcome is unknowable
+        # from here: it is surfaced, never resolved silently (INV-A3), and its
+        # adjudication is a gated human judgment (INV-A5).
+        #
+        # cleanup: deleting a stale intent is a write, so it happens only when
+        # the caller holds the advance lock (cleanup: true from the gated step
+        # path). Read-only probes (status/next_move) must not delete: an
+        # unlocked delayed delete could race a fresh open_intent and remove a
+        # LIVE intent.
+        def unresolved_intent(cleanup: false)
+          raw = begin
+            File.read(intent_path)
+          rescue Errno::ENOENT
+            return nil
+          end
+
+          intent = JSON.parse(raw)
+          # If the log contains a committed advance for the intent's anchor,
+          # the effect was recorded — the intent file is a stale leftover.
+          # Exception: a stop committed at the same anchor with the intent
+          # still unresolved did NOT record the effect (it recorded the
+          # ambiguity); such a commit must not make the audit trace look
+          # stale, or cleanup would silently erase it.
+          committed = find_committed(intent['anchor'])
+          if committed && !committed.dig('outcome', 'unresolved_intent_at_stop')
+            File.delete(intent_path) if cleanup && File.exist?(intent_path)
+            return nil
+          end
+          intent
+        rescue JSON::ParserError
+          # A torn intent file is itself an unresolved point; report it.
+          { 'anchor' => nil, 'corrupt' => true }
+        end
+
+        # ---- derivable next move (INV-A4) --------------------------------
+
+        # From persisted state alone: the single next move a fresh driver
+        # should issue. An unresolved side-effect point takes precedence over
+        # every other pending advance (v0.3.1 uniqueness clause).
+        def next_move(session)
+          intent = unresolved_intent
+          # A terminated session has no next move; a kept intent is an audit
+          # record of the ambiguity, not a pending adjudication (the step
+          # tool refuses post-termination adjudication, so recommending it
+          # would loop forever).
+          if session.state == 'terminated'
+            move = { 'tool' => nil,
+                     'reason' => 'session is terminated; no further moves' }
+            move['audit_intent'] = intent if intent
+            return move
+          end
+
+          if intent
+            return {
+              'tool' => 'agent_step',
+              'args' => { 'session_id' => session.session_id, 'action' => 'adjudicate',
+                          'anchor' => current_anchor(session) },
+              'reason' => 'unresolved side-effect: an act was started but its outcome ' \
+                          'was never recorded; adjudicate with resolution ' \
+                          '"reattempt" or "already_done"',
+              'unresolved_intent' => intent
+            }
+          end
+
+          action, reason = case effective_state(session)
+                           when 'observed', 'autonomous_cycling'
+                             ['approve', 'run Orient+Decide']
+                           when 'proposed'
+                             ['approve', 'run Act+Reflect (or "revise"/"skip")']
+                           when 'checkpoint'
+                             ['approve', 'start next cycle']
+                           when 'paused_risk', 'paused_error'
+                             ['approve', 'resume from pause (or "skip"/"stop")']
+                           else
+                             [nil, "unrecognized state #{session.state}"]
+                           end
+          return { 'tool' => nil, 'reason' => reason } unless action
+
+          {
+            'tool' => 'agent_step',
+            'args' => { 'session_id' => session.session_id, 'action' => action,
+                        'anchor' => current_anchor(session) },
+            'reason' => reason
+          }
+        end
+
+        # A transient phase state persisted by an interrupted call maps to the
+        # stable state it is recoverable from. Phases before ACT are
+        # side-effect free (their re-run is safe); the ACT window is governed
+        # by the intent bracket, not by this mapping.
+        def effective_state(session)
+          case session.state
+          when 'orienting', 'deciding' then 'observed'
+          when 'acting', 'reflecting'  then 'proposed'
+          else session.state
+          end
+        end
+
+        # The committed outcome recorded for an anchor, or nil. Used by the
+        # delegation wait surface (Slice A-2) to recover a committed advance's
+        # return value when a worker died after committing but before writing
+        # its result (crash-window b). When action is given, the committed
+        # entry's action must match — so a different judgment that consumed the
+        # same anchor before the crash never returns the wrong outcome.
+        def committed_outcome(anchor, action = nil)
+          entry = find_committed(anchor)
+          return nil unless entry
+          return nil if action && entry['action'] != action
+          entry['outcome']
+        end
+
+        private
+
+        def find_committed(anchor)
+          return nil unless File.exist?(log_path)
+
+          found = nil
+          File.foreach(log_path) do |line|
+            entry = JSON.parse(line.strip) rescue nil
+            found = entry if entry && entry['anchor'] == anchor
+          end
+          found
+        end
+
+        # The effective sequence fails closed: it is reconciled against the
+        # committed log's highest recorded seq, so a lost or corrupt
+        # advance.json can never regress the sequence and let an
+        # already-consumed anchor match the current one again (at-most-once
+        # would silently break on exactly the anchors whose state component
+        # did not change, e.g. revise at proposed).
+        def gate_state
+          @gate_state ||= begin
+            file_seq = begin
+              File.exist?(state_path) ? (JSON.parse(File.read(state_path))['seq'] || 0) : 0
+            rescue JSON::ParserError
+              0
+            end
+            { 'seq' => [file_seq, log_max_seq + 1].max }
+          end
+        end
+
+        # Highest committed seq in the log, or -1 when no advance committed.
+        def log_max_seq
+          return -1 unless File.exist?(log_path)
+
+          max = -1
+          File.foreach(log_path) do |line|
+            entry = JSON.parse(line.strip) rescue nil
+            s = entry && entry['seq']
+            max = s if s.is_a?(Integer) && s > max
+          end
+          max
+        end
+
+        # A crash mid-append can leave a torn tail line; without repair the
+        # next append would concatenate onto it and corrupt BOTH records.
+        # Terminating the torn tail confines the damage to the already-lost
+        # entry.
+        def repair_log_tail
+          return unless File.exist?(log_path) && File.size(log_path).positive?
+
+          last = File.open(log_path, 'rb') do |f|
+            f.seek(-1, IO::SEEK_END)
+            f.read(1)
+          end
+          File.open(log_path, 'a') { |f| f.write("\n") } unless last == "\n"
+        end
+
+        # INV-A2: no partial-write window. Content lands under a temp name and
+        # is renamed into place; rename is atomic on POSIX filesystems. The
+        # temp name carries pid + thread id so two writers in one process
+        # cannot collide on the temp file.
+        def atomic_write(path, content)
+          tmp = "#{path}.tmp.#{Process.pid}.#{Thread.current.object_id}"
+          File.write(tmp, content)
+          File.rename(tmp, path)
+        end
+
+        def lock_path   = File.join(@dir, LOCK_FILE)
+        def state_path  = File.join(@dir, STATE_FILE)
+        def log_path    = File.join(@dir, LOG_FILE)
+        def intent_path = File.join(@dir, INTENT_FILE)
+      end
+    end
+  end
+end

data/templates/skillsets/agent/lib/agent/session.rb

@@ -71,7 +71,7 @@ module KairosMcp
 
         # Persist decision_payload for the proposed→ACT transition.
         def save_decision(decision_payload)
-          File.write(decision_path, JSON.pretty_generate(decision_payload))
+          atomic_write(decision_path, JSON.pretty_generate(decision_payload))
         end
 
         # Load the last saved decision_payload.
@@ -84,7 +84,7 @@ module KairosMcp
 
         # Persist observation for ORIENT continuity.
         def save_observation(observation)
-          File.write(observation_path, JSON.pretty_generate(observation))
+          atomic_write(observation_path, JSON.pretty_generate(observation))
         end
 
         # Append a progress entry after REFLECT (M5: cumulative progress file).
@@ -139,7 +139,7 @@ module KairosMcp
             config: @config, autonomous: @autonomous,
             invocation_context: @invocation_context.to_h
           }
-          File.write(state_path, JSON.pretty_generate(data))
+          atomic_write(state_path, JSON.pretty_generate(data))
         end
 
         # Load a session from disk.
@@ -210,6 +210,15 @@ module KairosMcp
 
         private
 
+        # INV-A2 (interruption resilience Slice A): no partial-write window.
+        # A resumed driver must observe a persisted record in full or not at
+        # all; tmp-write + rename makes each single-file commit atomic.
+        def atomic_write(path, content)
+          tmp = "#{path}.tmp.#{Process.pid}"
+          File.write(tmp, content)
+          File.rename(tmp, path)
+        end
+
         def review_path
           File.join(session_dir, 'last_review.json')
         end